Python’da argparse ile Gerçek Bir Komut Satırı Aracı Yazmak

Bir Python scriptini her çalıştırdığında kodun içine girip değişken değerlerini elle değiştirmek zorunda kaldın mı hiç? Ya da input() ile kullanıcıya soru sorup cevap beklemek scriptini otomasyona sokmanı imkânsız hâle mi getirdi? İşte tam burada argparse devreye giriyor: komut satırından (terminal) parametre almanı sağlayan, Python’ın standart kütüphanesinde hazır gelen güçlü bir modül.

Bu Proje Ne Yapıyor?

Bu projede, indirdiğin dosyaların masaüstünde veya İndirilenler klasöründe karman çorman durmasına çözüm olacak gerçek bir dosya düzenleyici (file organizer) yazıyoruz. Ama asıl kahraman dosya taşıma mantığı değil, bu mantığı bir terminal aracına dönüştüren argparse katmanı.

Program iki zorunlu parametre (kaynak ve hedef klasör) ile bir opsiyonel bayrak (--dry-run) alıyor. Kaynak klasördeki dosyaları uzantılarına göre tarıyor (.pdf, .jpg, .py gibi) ve her birini kategori adını taşıyan bir alt klasöre (Documents, Images, Code…) taşıyor. --dry-run bayrağı verildiğinde ise hiçbir dosya gerçekten taşınmıyor, sadece “şunu şuraya taşırdım” bilgisi ekrana basılıyor — yani gerçek işlem öncesi güvenli bir önizleme.

Bu yaklaşım, script’i statik değişkenlerden veya etkileşimli sorulardan kurtarıp bash pipeline’larına, cron görevlerine ve otomasyon zincirlerine sorunsuzca eklenebilen bağımsız bir bileşene dönüştürüyor.

Proje Bilgisi: Bu örnek Ahmet Aksoy tarafından 27.05.2026 tarihinde, Python 3.12 ve Ubuntu 24.04 ortamında yazılmıştır.

Kodun Anatomisi

argparse ile bir CLI aracı kurmanın üç temel adımı var: parser’ı oluşturmak, argümanları tanımlamak ve son olarak parse_args() ile bu değerleri koda aktarmak.

import argparse

parser = argparse.ArgumentParser(
    description="Klasördeki dosyaları uzantılarına göre düzenleyen araç.",
    epilog="Örnek: python3 main.py ./indirilenler ./arsiv --dry-run"
)

# Konumsal argümanlar (positional) — tire almaz, sırayla zorunludur
parser.add_argument("source", type=str,
                     help="Düzenlenecek kaynak klasörün yolu.")
parser.add_argument("target", type=str,
                     help="Dosyaların taşınacağı hedef klasörün yolu.")

# Bayrak/flag argümanı — action="store_true" ile boolean anahtar
parser.add_argument("-d", "--dry-run", action="store_true",
                     help="Dosyaları taşımadan sadece planı gösterir.")

args = parser.parse_args()
print(args.source, args.target, args.dry_run)

Burada dikkat edilmesi gereken üç nokta var:

Konumsal argümanlar (source, target) tire içermez ve komut satırında hangi sırayla yazıldıysa öyle eşleşir. Kullanıcı bunları atlayamaz — atlarsa argparse otomatik olarak hata mesajı basıp programı durdurur.
Bayraklar (-d, --dry-run) tire ile başlar ve action="store_true" sayesinde ekstra bir değer beklemeden kendiliğinden True/False üretir. Bu, klasik if cevap == "e": mantığından çok daha temiz bir çözüm.
description ve epilog parametreleri boşuna değil — bunlar --help komutuyla otomatik üretilen kullanım kılavuzunu besliyor. Kullanıcı hiçbir dokümantasyon okumadan python3 main.py --help yazarak aracın tüm yeteneklerini görebiliyor.

Asıl dosya taşıma işini yapan organize_files() fonksiyonu ise bu argümanları alıp pathlib.Path ile klasörleri geziyor, her dosyanın uzantısını bir sözlükte (extension_map) arıyor ve shutil.move() ile (dry-run değilse) fiziksel taşımayı gerçekleştiriyor. Hata yönetimi tarafında da kaynak klasörün var olup olmadığı en başta kontrol ediliyor; yoksa kullanıcıya net bir [Error] mesajı basılıp fonksiyon güvenle sonlandırılıyor.

Uzantı-kategori eşleşmesi için sözlük (dictionary) kullanılması tesadüf değil — extension_map.get(ext, 'Others') satırı, haritada karşılığı olmayan her uzantıyı otomatik olarak Others klasörüne yönlendiriyor. Yani karşılaşılmayan bir dosya türü programı çökertmiyor, sadece genel bir kategoriye düşüyor. Bu tür “varsayılan değerle düşme (fallback)” mantığı, gerçek dünya verisiyle çalışan her script için önemli bir savunma hattı.

type=str parametresini de atlamamak lazım: argparse, komut satırından gelen her şeyi varsayılan olarak zaten string olarak okur, ama type=int veya type=float yazarak sayısal bir argümanı otomatik olarak doğru tipe dönüştürebilir ve kullanıcı yanlış bir değer girdiğinde ("abc" gibi) argparse bunu kendi başına yakalayıp anlamlı bir hata mesajıyla programı durdurur. Bu, elle yazılan int() çağrılarını try/except bloklarıyla sarmalamaktan çok daha az kod ve çok daha tutarlı bir sonuç demek.

Dosya işleme (file handling) konusuna daha derinlemesine bakmak istersen, Python ile Özyinelemeli Dosya ve Kelime Sayacı Geliştirmek yazımızda pathlib ve klasör gezinme mantığını daha ayrıntılı ele almıştık.

Nasıl Çalıştırılır?

Projeyi çalıştırmak için ek bir bağımlılık kurmana gerek yok — argparse, os, shutil ve pathlib Python’ın standart kütüphanesinde hazır geliyor.

Önce aracın kendini nasıl tanıttığına bak:

python3 main.py --help

Sonra güvenli bir test için sahte bir kaynak klasör oluşturup dry-run modunda dene:

mkdir test_kaynak
touch test_kaynak/belge1.pdf test_kaynak/foto2.png test_kaynak/betik3.py

python3 main.py ./test_kaynak ./test_hedef --dry-run

# Çıktı örneği:
#  -> Mapping: belge1.pdf -> [Documents] folder
#  -> Mapping: foto2.png -> [Images] folder
#  -> Mapping: betik3.py -> [Code] folder
# Execution complete. Total items logged/processed: 3

--dry-run bayrağını kaldırıp tekrar çalıştırdığında dosyaların gerçekten test_hedef/Documents, test_hedef/Images ve test_hedef/Code klasörlerine taşındığını göreceksin.

Argümanlardan birini eksik bırakıp da çalıştırmayı denersen (python3 main.py ./test_kaynak), argparse’ın kendi başına devreye girdiğini ve programı senin hiçbir hata yönetimi (error handling) kodu yazmana gerek kalmadan anlamlı bir error: the following arguments are required: target mesajıyla durdurduğunu göreceksin. Bu, kütüphanenin sana kazandırdığı en büyük zaman tasarruflarından biri.

Ne Öğrendik?

Konumsal argümanlar zorunlu, sıralı girdileri; bayraklar ise opsiyonel anahtarları temsil eder — ikisini doğru yerde kullanmak API tasarımının temelidir.
action="store_true" ile elle boolean parse etme derdinden kurtulursun.
description ve epilog parametreleri sayesinde --help çıktısı kendiliğinden, bakımı kolay bir dokümana dönüşür.
argparse tabanlı bir araç, input() kullanan bir scriptin aksine cron görevlerine, bash pipeline’larına ve CI/CD adımlarına doğrudan entegre edilebilir.
--dry-run gibi bir “önizleme modu” eklemek, özellikle dosya sistemi üzerinde değişiklik yapan araçlarda kullanıcı güvenini kazanmanın ucuz ama etkili bir yoludur.

Kaynaklar ve Sonraki Adımlar

Bu CLI aracını bir sonraki adımda --categories gibi kullanıcı tanımlı bir uzantı haritası parametresiyle genişletebilir ya da subparsers kullanarak organize ve undo gibi alt komutlara bölebilirsin. Dosya yönetimi temalı başka bir proje için Python ve Flask ile Web Tabanlı Gelişmiş Dosya Yöneticisi Yapımı yazımıza da göz atabilirsin.

Ahmet Aksoy

Not: Bu yazıda incelediğimiz kodu ve benzer projelerin kaynak kodlarını https://github.com/ahmetax/practical-python-examples adresinde bulabilirsiniz.