Technical Tutorials

Yıllar boyunca Python geliştiricileri, parçalı bir paketleme araçları ekosistemine güvenerek setup.py, setup.cfg ve çeşitli derleme arka uçları arasında sıkışıp kaldı. Bu standartlaşma eksikliği kafa karışıklığına ve teknik borca yol açtı. Ancak, PEP 517 ve PEP 518'in benimsenmesiyle manzara stabilize oldu. Günümüzde Python paketleme, hem oluşturma hem de paketleri dağıtmayı kolaylaştıran standartlaştırılmış bir yapılandırma formatı olan pyproject.toml dosyası tarafından tanımlanmaktadır.

Bu kılavuz, kütüphanelerinin sağlam, tekrarlanabilir ve topluluk tarafından kolayca kurulabilir olmasını sağlamak isteyen geliştiricileri hedef alarak, Python paketleri oluşturma, test etme ve dağıtma konusundaki modern en iyi uygulamaları keşfetmektedir.

Temel Yapılandırma: pyproject.toml

Modern Python paketleme iş akışı tamamen pyproject.toml dosyası etrafında dönmektedir. Bu tek bilgi kaynağı, birden fazla yapılandırma dosyasına olan ihtiyacı ortadan kaldırır. Derleme sistemini ve proje meta verilerini tanımlayarak, PEP 517'ye uyan herhangi bir aracın projenizi tutarlı bir şekilde oluşturmasını sağlar.

Modern bir proje için tipik bir pyproject.toml dosyası şu şekildedir:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-awesome-library"
version = "0.1.0"
description = "A sample library demonstrating modern Python packaging"
readme = "README.md"
license = {text = "MIT"}
authors = [
    {name = "Jane Doe", email = "jane@example.com"}
]
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
    "click>=8.0"
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black"
]

[project.urls]
Homepage = "https://github.com/janedoe/my-awesome-library"
Documentation = "https://my-awesome-library.readthedocs.io"

[project] bölümünde statik meta verilerin kullanımına dikkat edin. setup.py'deki dinamik meta verilerin aksine, statik meta veriler PyPI gibi araçlar tarafından daha hızlı ayrıştırılmasını sağlar ve farklı ortamlar arasında tekrarlanabilirliği garanti eder. Bağımlılıklar, üst düzey kütüphanelerdeki kırıcı değişikliklerden kaçınmak için sıkı bir şekilde sürümlendirilmiştir.

Artifact'ların Oluşturulması ve Dağıtılması

Yapılandırmanız ayarlandıktan sonra bir sonraki adım, dağıtım artifact'larını oluşturmaktır. Sektör standardı, kaynak dağıtımlarından (.tar.gz) ve eski wheel'lerden (.egg) modern wheel'lere (.whl) kaymıştır. Modern wheel'ler, önceden derlenmiş ikili dosyalar ve meta veriler içerir; bu da son kullanıcılar için kurulum sürelerini önemli ölçüde hızlandırır.

Projenizi oluşturmak için, kaynak ve wheel dağıtımları oluşturma konusunda önerilen araç olan build paketini kullanın. İlk olarak, build aracını yükleyin:

python -m pip install build

Ardından, build komutunu çalıştırın:

python -m build

Bu komut, hem kaynak dağıtımını (sdist) hem de wheel'i içeren bir dist/ dizini oluşturur. sdist, tüm kaynak dosyalarını içerir ve kullanıcıların paketleri kendi sistemlerinde kaynaktan oluşturmalarına olanak tanır; wheel ise çoğu kullanıcı için hızlı, kurulabilir bir format sağlar.

PyPI'ye Yükleme

Artifact'larınız hazır olduğunda, son adım dağıtımdır. twine sürüm 4.0+'da tanıtılan Güvenilir Yayın (Trusted publishing) özelliği, uzun ömürlü API belirteçlerine olan ihtiyacı ortadan kaldırarak yükleme işlemini basitleştirir. Bunun yerine, CI/CD hatları için daha güvenli ve kullanışlı olan kimlik doğrulama amacıyla OIDC (OpenID Connect) kullanır.

twine'i yükleyin:

python -m pip install twine

Dağıtımlarınızı yükleyin:

python -m twine upload dist/*

Hataları ana depoya ulaşmadan önce yakalamak için yüklemelerinizi her zaman TestPyPI üzerinde test edin. Bunu, --repository testpypi bayrağını belirtmek ve kimlik bilgileriniz için .pypirc yapılandırmanızı ayarlamak veya ortam değişkenlerini kullanmak suretiyle yapabilirsiniz.

Uzun Vadeli Bakım İçin En İyi Uygulamalar

Paketleme tek seferlik bir görev değildir. Sağlıklı bir projeyi korumak için aşağıdaki uygulamaları göz önünde bulundurun:

Sürüm Yönetimi: Kırıcı değişiklikleri iletmek için anlamsal sürümleme (SemVer) kullanın.
Bağımlılık Sabitleme: Tutarlı oluşturmalar sağlamak için bağımlılıklarınızı pyproject.toml içinde sabitleyin, ancak güvenlik yamalarına izin vermek için esnek aralıklar kullanın (örneğin, >=2.0).
CI/CD Entegrasyonu: Her sürümün birden fazla Python sürümünde test edildiğinden emin olmak için GitHub Actions veya GitLab CI kullanarak testleri ve yayınlamayı otomatikleştirin.
Dokümantasyon: README.md ve dokümantasyonunuzu güncel tutun, çünkü bunlar kullanıcıların PyPI'de gördüğü ilk şeylerdir.

Sonuç

Python paketleme, sağlam ve standartlaştırılmış bir sürece olgunlaştı. pyproject.toml, modern derleme araçları ve güvenli dağıtım yöntemlerinden yararlanarak geliştiriciler, kurulum sorunlarını gidermek yerine kod yazmaya odaklanabilir. Bu modern uygulamaları benimsemek, Python ekosistemine yaptığınız katkilerin yıllar boyunca erişilebilir, güvenilir ve sürdürülebilir olmasını sağlar.