Python 3.8 ile konumsal parametreler: Bir API imzasını tasarlamak
Python 3.8’in bölme işaretiyle tanımlanan parametrelerinin kütüphane tasarımına, uyumluluğa ve testlere etkisini inceliyoruz.
İşlev imzası neden sürüm sözleşmesidir?
Python 3.8, fonksiyon tanımında bölme işaretiyle yalnız konumdan verilebilen parametreleri ifade etmeye başladı. İşaretin solundaki parametreler anahtar sözcükle gönderilemez. Bu seçim bir kütüphane API’sinde çağıranın neye güvenebileceğini belirler. Bir değerin konumu ve anlamı sözleşmenin parçası olabilir. İsmi de anahtar sözcük kullanımına açıldıysa kullanıcılar o ismi kodlarına yazabilir. İsim değişikliğinin kullanıcı tarafındaki etkisi bu durumda bir dokümantasyon düzenlemesinden daha büyüktür. Yeni bir API’de hangi parametrenin isimle çağrılacağını açıkça seçmek uyumluluk sınırını baştan görünür kılar.
Konumsal veri ve isimli seçenekleri ayırmak
Örneğin bir CSV satırını işleyen işlevde satır verisinin konumu anlaşılır olabilir. Ayraç ve boş değeri yorumlama davranışı ise isimle verildiğinde çağrı daha okunaklı olur. Böyle bir imzaya slash ile konumsal veri, yıldız ile isimli seçenekler konabilir. Kullanıcı bir kaydı çağrıda ilk sırada görürken değiştirilen ayracı da açık bir isimle görür. Bilinçli istisnalar önemlidir. Bir işlevin ilk iki parametresi benzer türde iki tarih taşıyorsa isimle çağrı, kaynak tarihiyle hedef tarihi sessizce yer değiştirme riskini azaltabilir.
def read_row(row, /, *, delimiter=","):
return row.split(delimiter)
read_row("id|name", delimiter="|")Var olan çağrıları dönüştürmeden önce incelemek
Eski bir işlev müşteriler tarafından isimli argümanla çağrılıyorsa yeni imzada bir parametreyi yalnız konumsal yapmak kırıcı değişikliktir. Değişikliği yalnız projenin kendi testleriyle değerlendirmeyin. Belgelerdeki örnekler, eklentiler, komut satırı katmanı ve işlevi başka bir kayıt mekanizmasına veren kullanıcılar farklı çağrı biçimlerine dayanabilir. Yeni işlev için daha dar bir imza oluşturup eskisini uyumluluk katmanı olarak sürdürmek bir geçiş yolu olabilir. Kullanımdan kaldırma uyarısı, davranış ve zaman çizelgesini birlikte anlatmalı.
İmza değişikliği için üç tür test
En az bir normal çağrı, bir isimli seçenek ve bir hatalı anahtar sözcük örneği kurun. Hata testi belirli bir metne gereksiz yere bağımlı olmadan TypeError türünü ve reddedilen kullanımın koşulunu doğrulayabilir. İşlevi bir dekoratör sarıyorsa kullanıcıya gösterilen imza ile çağrı davranışı arasındaki farkı test edin. API belgeleri imzayı otomatik okuyorsa slash ve yıldız konumları orada da görünmeli. Bu kontroller çağrı sözleşmesinin yanlışlıkla genişlemesini veya daralmasını erken fark ettirir.
Bugün geriye dönüp hangi kararı alırdık?
Yeni API tasarımında önce çağrının nasıl okunduğuna bakardım. Bir değer bağlamdan belliyse kısa konumsal çağrı iyi çalışabilir. Politika, zaman aşımı veya davranış seçenekleri için açık isimler hata olasılığını düşürür. Parametre adını ileride serbestçe değiştirebilmeyi tek hedef yapmayın. İsimli çağrılar ekiplerde önemli bir dokümantasyon işlevi görür. Seçimi, davranışın örnek çağrılarda anlaşılabilirliği ve mevcut müşterilerle uyumluluk üzerinden değerlendirin. Bir imza değişikliğinde örnek dokümanı, tip bilgisi ve test olguları aynı gözden geçirmeye girmeli. Örneğin bir değişken sayıda seçenek alan kütüphanede işlev imzasını programatik olarak oluşturan bir eklenti olabilir. Bu eklentinin imza üzerindeki parametre türünü doğru okuduğunu kontrol edin. Kullanıcıların yazdığı betikleri tarama olanağınız varsa konumsal ve isimli kullanım örneklerini sınıflandırın. Bunları geçiş belgesinde çalışan örnekler ve reddedilen örnekler olarak yan yana gösterin.
Yorumlar
Henüz yorum yok. İlk katkıyı sen yapabilirsin.
“Python 3.8 ile konumsal parametreler: Bir API imzasını tasarlamak” başlıklı makalede özellikle şu noktayı düşündüm: sürüm geçişi ve geri dönüş planının ayrıca açıklanması faydalı olur.
Editörün notu: Kaynak bir duyuru olduğu için geleceğe dönük ifadeleri kesinleşmiş performans sonucu olarak aktarmıyoruz. Yeni veriler geldikçe değerlendirme güncellenebilir.
Bence öne çıkan sorulardan biri, kaynağın neyi kesin olarak doğruladığı. İleriye dönük beklentileri sonuç gibi okumamak lazım.
İzlemeye değer bir başlık. Bir sonraki sürümün ölçümleri geldiğinde bugünkü değerlendirmeyi güncellemeliyiz.
✎ Yorum yaz