Python Betiklerini Parametreli Komut Satırı Aracına Dönüştürmek

Komut satırı aracı (CLI) nedir ve neden yazılır?

Komut satırı aracı, terminalden bir komut ve parametrelerle çalıştırılan programdır. Python betiğinizi her seferinde kodu açıp dosya yolunu değiştirerek çalıştırmak yerine, "rapor üret, şu klasörden oku, şu tarihe kadar filtrele" gibi parametreleri dışarıdan verirsiniz. Böylece aynı betik farklı girdilerle, kodu değiştirmeden çalışır.

CLI yazmanın somut faydaları şunlardır: • Betik başkasına devredilebilir; kodu okumadan yardım çıktısına bakarak kullanır • Zamanlanmış görevlerde parametreler zamanlayıcıdan verilir, kod değişmez • Farklı ortamlar (deneme, canlı) için tek betik, farklı parametre kullanılır • Hatalı kullanımda araç anlaşılır bir mesajla uyarır • Başka araçlarla zincirlenebilir; bir aracın çıktısı diğerinin girdisi olur

Python'da komut satırı aracı yazmak için standart kütüphanedeki argparse modülü yeterlidir ve ek kurulum gerektirmez. Daha az kodla daha zengin bir kullanım isterseniz Click ve Typer gibi üçüncü taraf kütüphaneler vardır; bunlar parametreleri fonksiyon imzalarından ya da dekoratörlerden çıkarır. Yeni başlayanlar için önce argparse'ı öğrenmek, parametrelerin nasıl işlediğini kavramayı kolaylaştırır.

Bir CLI aracının parçaları: argüman, seçenek, bayrak, alt komut

Komut satırı parametreleri şu temel türlerde ele alınır. Konumsal argüman, sırasına göre verilen zorunlu değerdir; örneğin işlenecek dosyanın yolu. Seçenek, adı ile verilen ve genellikle varsayılan değeri olan parametredir; örneğin çıktı klasörü ya da başlangıç tarihi. Bayrak, değer taşımayan açma-kapama anahtarıdır; örneğin ayrıntılı çıktı ya da deneme modu. Alt komut ise tek bir aracın içinde farklı işlevleri ayırır; git komutundaki ekleme, gönderme, durum gibi.

argparse ile bir ayrıştırıcı oluşturur, parametreleri tek tek tanımlarsınız. Her parametre için ad, tür, varsayılan değer, zorunluluk ve yardım metni belirtilir. Ayrıştırıcı komut satırını okur, türleri dönüştürür ve hatalı kullanımda otomatik olarak anlaşılır bir hata mesajı ile yardım metnini gösterir. Yardım çıktısı otomatik üretildiği için, parametreleri açıklayan metinleri özenle yazmak aracın belgelendirmesini de yapmış olur.

Parametre tasarımında şu ilkeler işe yarar: • Adlar kısa ama açıklayıcı olsun; uzun ve kısa biçim sunulsun • Makul varsayılanlar verin, kullanıcı en az parametreyle çalıştırabilsin • Tehlikeli işlemler (silme, üzerine yazma) için açık onay bayrağı ya da deneme modu ekleyin • Girdi doğrulamasını mümkün olduğunca ayrıştırıcıya bırakın; dosya var mı, değer izin verilen kümede mi gibi

İlk komut satırı aracı: örnek betik

Önce aracın tek cümlelik görevini yazın; net bir görev parametre listesini de belirler. Sonra iş mantığını komut satırından habersiz bir fonksiyon olarak yazın, böylece test edilebilir. Şu örnek, rapor üreten bir betiğin sabitlerini parametreye çevirir:

import argparse

def main(): ayristirici = argparse.ArgumentParser(description="Satış dosyasından bölge raporu üretir") ayristirici.add_argument("dosya", help="Veri dosyasının yolu") ayristirici.add_argument("--bolge", help="Yalnız bu bölgeyi işle") ayristirici.add_argument("--cikti", default="rapor.xlsx", help="Çıktı dosyası") ayristirici.add_argument("--deneme", action="store_true", help="Dosya yazmadan yapılacakları göster") args = ayristirici.parse_args() if not args.dosya.endswith(".csv"): raise SystemExit("Yalnız csv dosyası destekleniyor") print("İşlenecek:", args.dosya, args.bolge, args.cikti, args.deneme)

if __name__ == "__main__": main()

Betik, yardım bayrağıyla çalıştırıldığında parametre açıklamalarını otomatik gösterir; eksik zorunlu parametrede ya da hatalı kullanımda anlaşılır bir hata mesajı verir. Desteklenmeyen dosya biçiminde SystemExit ile mesaj yazıp sıfırdan farklı çıkış koduyla kapanmak, aracı zamanlayıcılar ve başka betikler için güvenilir kılar. Sonuçları standart çıktıya, uyarı ve hataları hata akışına yazın; çıktı bir dosyaya yönlendirildiğinde hata mesajları dosyaya karışmaz. Dosya doğrudan çalıştırıldığında ana fonksiyonu çağıran koruma kalıbı (name main kontrolü) betiğin başka bir modülden içe aktarılırken kendiliğinden çalışmasını engeller.

Örnek senaryo: raporlama aracını parametrelendirmek

Örneğin bir analitik ekibi, satış verisinden rapor üreten bir betik kullanıyor. İlk sürümde tarih aralığı, bölge ve çıktı yolu kodun içinde sabit yazılı; her kullanımda biri dosyayı açıp değiştiriyor. Betiğin CLI'ye dönüştürülmüş hali şöyle çalışır: kullanıcı veri dosyasının yolunu konumsal argüman olarak verir, başlangıç ve bitiş tarihini seçenek olarak, bölgeyi isteğe bağlı filtre olarak, çıktı biçimini (tablo ya da Excel) bir seçenekle belirler. Deneme bayrağı verilirse rapor üretilmeden önce hangi satırların işleneceği ekrana yazılır.

Aynı araç alt komutlarla genişletilebilir: bir alt komut rapor üretir, diğeri veri dosyasının biçimini doğrular, bir diğeri eski raporları temizler. Tek bir araç ekibin ortak giriş noktası haline gelir. Yeni bir ekip arkadaşı kodu okumadan yardım çıktısından aracı öğrenir.

Zamanlayıcı da aynı aracı çağırır; yalnızca parametreleri otomatik verir, örneğin dünün tarihini. Böylece elle kullanım ve otomatik kullanım aynı kodu paylaşır ve ikisi arasında davranış farkı oluşmaz.

Komut satırı araçlarında kullanılabilirlik hataları

CLI yazarken sık görülen sorunlar kullanılabilirlik ve sağlamlık alanında toplanır:

• Mantığı ayrıştırıcıyla iç içe yazmak. İş mantığı parametre okuma koduyla karışırsa test edilemez. Önce fonksiyonları yazın, sonra komut satırına bağlayın.
• Aşırı çok zorunlu parametre. Kullanıcı her seferinde uzun komut yazmak zorunda kalırsa aracı bırakır. Makul varsayılanlar verin.
• Yardım metinlerini boş bırakmak. Otomatik yardım çıktısı yalnızca siz açıklama yazarsanız işe yarar.
• Hatayı yutmak. Bir şey ters gittiğinde araç başarılıymış gibi sıfır koduyla çıkarsa zamanlayıcı ve zincirleme kullanımlar bozulur.
• Gizli bilgiyi komut satırından almak. Şifre parametre olarak verilirse komut geçmişinde ve işlem listesinde görünür. Ortam değişkeni ya da güvenli giriş kullanın.
• Yıkıcı işlemde onay istememek. Silme ve üzerine yazma için deneme modu ve açık onay ekleyin.
• Türkçe karakterli girdi ve çıktıda kodlamayı unutmak.
• Yeni sürümde parametre adlarını sessizce değiştirmek. Aracı kullanan betikler bozulur; eski adı bir süre destekleyip uyarı verin.

Bir de paketleme meselesi vardır: aracın başka bilgisayarlara kolay kurulması için proje yapısına bir giriş noktası tanımlayabilir ve pip ile kurulabilir hale getirebilirsiniz. Böylece kullanıcı betik yolunu hatırlamak yerine doğrudan komut adını yazar.

CLI yazımında öğrenme sırası

Başlangıç düzeyinde tek bir konumsal argüman ve bir seçenek alan küçük bir betik yazın. Amacınız ayrıştırıcının nasıl çalıştığını, yardım çıktısının nasıl üretildiğini ve hatalı kullanımda ne olduğunu görmektir. Kendi işinizde elle değiştirdiğiniz sabitleri parametreye dönüştürmek, gerçek bir ihtiyaçtan öğrenmenin etkili bir yoludur.

Orta düzeyde alt komutlar, tür dönüşümü, izin verilen değer kümeleri, bayraklar, çıkış kodları ve loglama eklenir. İş mantığını ayrı modüle taşıyıp test yazmak da bu aşamanın konusudur.

İleri düzeyde Click ya da Typer gibi kütüphanelerle daha zengin arayüzler kurulur; ilerleme çubukları, renkli çıktı, otomatik tamamlama ve yapılandırma dosyasıyla birlikte çalışma gibi özellikler eklenir. Aracı paket haline getirip ekip içinde dağıtmak, sürümlemek ve belgelemek de ileri düzeyin parçasıdır.

Betiklerini ekiple paylaşmak isteyenler için Mindset bağlamı

Mindset kataloğundaki Python Otomasyon ile Verimlilik programı, betikleri tek seferlik denemelerden tekrar kullanılabilir araçlara dönüştürmeye zemin hazırlar; komut satırı arayüzü ayrı bir modül başlığı değildir, program içindeki betikleri parametreli hale getirerek pratik yapılır. Dosya ve Klasör Yönetimi Otomasyonu ile Zamanlanmış Görevler ve Süreç Yönetimi modülleri, aracın tipik kullanım alanlarını oluşturur. Rutin işlerini betikleştiren ve ekip arkadaşlarıyla paylaşmak isteyen operasyon, veri, finans ve BT destek çalışanları için uygundur.