PYTHON PACKAGİNG: VENV, POETRY VE BAĞIMLILIK YÖNETİMİNDE SAĞLAM YAKLAŞIM

Python’da “çalışıyor” demek, çoğu zaman “her yerde aynı şekilde çalışıyor” demek değildir. Farklı makinede farklı sürüm, farklı bağımlılık çözümü veya eksik sistem paketleri yüzünden en iyi kod bile sürpriz çıkarabilir. Bu yüzden packaging konusu, sadece dağıtım değil; aynı zamanda ekip içi verim, hata ayıklama süresi ve üretim güvenilirliğiyle doğrudan ilgilidir.

Bu yazıda, izole çalışma ortamı kurulumundan başlayıp bağımlılıkların kilitlenmesine, proje yapısının standardize edilmesine ve CI/CD’de tekrarlanabilir build sürecine kadar “sağlam yaklaşım”ı adım adım ele alacağız. Odak noktamız: venv ile izolasyon, Poetry ile modern bağımlılık yönetimi ve tutarlı dağıtım pratikleri.

Hedef, tek bir araç ezberi değil; projeyi büyütürken sürtünmeyi azaltan, “aynı commit = aynı çıktı” yaklaşımına yaklaşan bir çalışma düzeni kurmak. Yazının sonunda, kendi projenize uyarlayabileceğiniz küçük bir kontrol listesi de bulacaksınız.

Python paketleme nedir ve neden önemlidir?

“Python packaging” genellikle iki konuyu birlikte ifade eder: (1) projenin bağımlılıklarını ve çalışma ortamını yönetmek, (2) projenin dağıtılabilir bir biçime (wheel/sdist) dönüştürülmesi. İlk başlık günlük geliştirmeyi, ikinci başlık ise paylaşım ve yayınlamayı güçlendirir.

Geliştirme tarafında sorunlar çoğu zaman “bağımlılık çözümü”nden çıkar: aynı kütüphanenin farklı sürümleri, dolaylı bağımlılıklardaki değişimler veya sistemde yüklü paketlerin ortama sızması. Bu yüzden ortam izolasyonu ve bağımlılık kilitleme, kaliteyi görünmez şekilde artırır.

Birincil hedef: tekrarlanabilirlik

Bir proje “tekrarlanabilir” olduğunda, aynı kaynak kodla farklı bilgisayarlarda benzer çıktı alırsınız. Bu, sadece testlerin geçmesi değil; aynı zamanda üretimde beklenmedik kırılımların azalması anlamına gelir. Burada kilit kavramlar: sürüm pin’leme, lock dosyası ve deterministik çözüm.

Bağımlılık zincirini görünür kılmak

Doğrudan bağımlılıklar kadar, onların getirdiği dolaylı bağımlılıklar da önemlidir. Sürüm çatışmaları ve güvenlik yamaları çoğunlukla bu katmanda görünür. Bu nedenle düzenli güncelleme, bağımlılık denetimi ve sürüm stratejisi bir “paketleme” disiplininin parçasıdır.

venv ile izole ortamlar: temel strateji

venv, Python’un yerleşik sanal ortam aracıdır ve projenin paketlerini sistem Python’undan ayırır. Bu yaklaşım, işletim sistemi güncellemelerinin veya farklı projelerin birbirini etkilemesini engeller. Ekip içinde yeni birinin projeyi ayağa kaldırmasını da hızlandırır.

venv kurulumu ve pip ile temel akış

Aşağıdaki örnek, bir proje klasöründe sanal ortam oluşturmayı ve temel kurulum adımlarını gösterir. Windows ve Unix ailesinde aktivasyon komutu farklıdır; ancak mantık aynıdır.

python -m venv .venv
# macOS / Linux
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements.txt

python -m pip freeze > requirements.lock.txt

requirements.txt mi, lock dosyası mı?

requirements.txt çoğu ekipte “doğrudan bağımlılık listesi” olarak kullanılır; ancak tek başına deterministik çözüm sağlamaz. Bir “lock” yaklaşımında, çözümlenmiş sürümler sabitlenir ve ortam yeniden kurulduğunda aynı sürümler elde edilir. Pip ekosisteminde bunu farklı yöntemlerle yapabilirsiniz; fakat Poetry bu işi daha bütünlüklü ele alır.

Poetry ile modern bağımlılık yönetimi

Poetry, bağımlılık yönetimini pyproject.toml etrafında birleştirir ve lock dosyası üreterek aynı çözümün yeniden kurulmasını kolaylaştırır. Ayrıca paket metadata’sını tek yerde topladığı için proje standardizasyonunu güçlendirir.

pyproject.toml: tek kaynak yaklaşımı

Poetry ile proje tanımı, sürüm ve bağımlılıklar tek bir dosyada düzenlenir. Bu, ekip içi görüş ayrılıklarını azaltır: “nerede ne yazıyor?” sorusunun cevabı netleşir.

Poetry komutlarıyla pratik kurulum

Aşağıdaki akış, yeni bir proje başlatmak veya mevcut projeye Poetry eklemek için tipik bir senaryodur. Lock dosyası, bağımlılıkların çözümlenmiş halini kaydeder.

poetry init
poetry add requests
poetry add --group dev pytest ruff

poetry lock
poetry install

poetry run pytest -q

Poetry mi, pip-tools mu?

Poetry; proje metadata’sı, bağımlılık çözümü, lock dosyası ve çalıştırma deneyimini tek çatı altında sunar. pip-tools ise pip tabanlı kalmak isteyen ekipler için güçlü bir alternatiftir. Tercih, ekibin alışkanlıkları, CI/CD yapısı ve yayınlama ihtiyacına göre değişir; önemli olan araçtan bağımsız olarak aynı prensipleri uygulamaktır: izolasyon, kilitleme, sürüm stratejisi ve denetim.

Proje yapısı, sürümleme ve dağıtım pratikleri

Sağlam bir paketleme yaklaşımı, kod düzenini ve yayınlama sürecini de iyileştirir. Özellikle kütüphane geliştiriyorsanız, “src layout” gibi yerleşimler import karmaşasını azaltır ve testlerin gerçek paket yapısını hedeflemesini sağlar.

SemVer ve sürüm disiplinine yaklaşım

Sürümleme, ekip içi iletişimin bir parçasıdır. Değişikliklerin etkisini sürüm numarasına yansıtmak, bağımlı projelerin güncellemelerini daha öngörülebilir kılar. “Kırıcı değişiklik” ile “geri uyumlu iyileştirme” ayrımını net tutmak, uzun vadede bakım maliyetini düşürür.

wheel ve sdist farkını bilmek

Dağıtımda iki temel çıktı öne çıkar: sdist (kaynak dağıtımı) ve wheel (derlenmiş/önceden paketlenmiş dağıtım). Wheel çoğu zaman kurulum hızını artırır ve derleme bağımlılıklarını azaltır. Ancak bazı projelerde sdist zorunludur; bu nedenle build sürecinin hangi çıktıları ürettiğini bilmek önemlidir.

CI/CD ve güvenlik: tekrarlanabilir build zinciri

Yerelde düzgün çalışan bir proje, CI’da farklı davranıyorsa genellikle ortamın deterministik olmamasından şüphelenin. Lock dosyasının kullanılması, Python sürümünün sabitlenmesi ve build adımlarının açıkça tanımlanması bu problemi büyük ölçüde azaltır.

Python sürümünü sabitlemek ve matrix test

Projeyi birden çok Python sürümünde destekliyorsanız, CI’da bir sürüm matrisi kurmak erken uyarı sağlar. Buna ek olarak, minimum desteklenen sürümle test etmek (örneğin “lowest supported”) uyumluluk sorunlarını hızlı yakalar.

Tedarik zinciri risklerini azaltmak

Bağımlılıklar, projenizin saldırı yüzeyinin önemli bir parçasıdır. Düzenli güncelleme, güvenlik taraması ve şüpheli paketlere karşı temkin, “paketleme”nin doğal uzantısıdır. İmza doğrulama, hash pin’leme veya özel indeks kullanımı gibi yöntemler, gereksinimlerinize göre değerlendirilebilir.

Sık yapılan hatalar ve pratik kontrol listesi

Birçok ekip, büyüme döneminde aynı hatalara düşer: ortamı sistem Python’uyla karıştırmak, lock dosyasını commit etmemek, “herkesin makinesinde farklı” bağımlılık sürümlerine izin vermek veya sürümleme disiplinini ertelemek. Aşağıdaki maddeler, hızlı bir kalite çıpası olabilir.

Takım içi standartlar: küçük kurallar, büyük kazanım

• Her proje için ayrı sanal ortam kullanın; sistem Python’una paket kurmayın.
• Lock dosyasını repoda tutun ve CI’da lock’a göre kurulum yapın.
• Python sürümünü dokümante edin; mümkünse araçlarla sabitleyin.
• Geliştirme bağımlılıklarını (test, lint) ayrı bir grupta yönetin.
• Yayınlamadan önce wheel/sdist üretimini CI’da doğrulayın.
• Düzenli aralıklarla bağımlılık güncellemesi ve güvenlik taraması uygulayın.

Bu yaklaşımı eğitim perspektifiyle derinleştirmek isterseniz, ekip pratiklerine odaklanan içerik için Python eğitimi sayfasına göz atabilirsiniz. Orada, proje standardizasyonu ve sürdürülebilir geliştirme akışını daha sistematik şekilde ele alan modüller bulabilirsiniz.

Özetle: venv izolasyonu temel çizgi, Poetry ise bağımlılık çözümü ve lock dosyasıyla bu çizgiyi pratikte sürdürülebilir hale getirir. Araç seçimi değişebilir; fakat prensipler aynı kalır: deterministik kurulum, görünür bağımlılık zinciri, tutarlı sürümleme ve CI/CD’de tekrarlanabilir build.