GÜNDEMDE

DÜNYADAN TEKNOLOJİ HABERLERİ

→
Python 3.8 ile konumsal parametreler: Bir API imzasını tasarlamak
Yazılım · 2019
Yazılım2019

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.

Yazılımcının GünlüğüYayımlanma: 18 Kas 20263 dk okuma
Okuma ilerlemesi0%

İş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.

Servis mimarisiKavramsal şema · makalenin teknik akışını özetler
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.

İlk okuyan sen ol ✎ Yorum yaz

Yorumlar

Henüz yorum yok. İlk katkıyı sen yapabilirsin.

Zeynep Şahin

“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 örnek yanıtı

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.

Deniz Yalçın

Bence öne çıkan sorulardan biri, kaynağın neyi kesin olarak doğruladığı. İleriye dönük beklentileri sonuç gibi okumamak lazım.

İrem Kaplan

İ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

Adın ve soyadın yorumunla birlikte herkese açık görünecek.