requirements.txt’ye Veda: Poetry ile Python Paket Yönetimi

Projenizi bir arkadaşınızın bilgisayarında çalıştırdığınızda “bende çalışıyordu ama sende çalışmıyor” diye bir cümle kurduysanız, suçlu büyük ihtimalle bağımlılık yönetimidir. Python’da paketleri kurmanın klasik yolu olan pip ve requirements.txt ikilisi basittir ama alt bağımlılıkların (bir paketin kendi ihtiyaç duyduğu paketlerin) sürümünü kilitlemekte zorlanır. İşte tam bu noktada Poetry devreye giriyor.

Poetry Projesi Ne Yapıyor?

Bu proje, aslında çalıştırdığında gösterişli bir şey yapmıyor: terminale Python’un çalıştığı yolu, sürüm numarasını ve rich kütüphanesinin başarıyla yüklendiğini gösteren şık bir tablo basıyor. Ama asıl mesele kodun kendisi değil, o kodun nasıl çalıştığı: kodu çalıştırmadan önceki adımlar, yani bağımlılıkların nasıl kurulduğu ve hangi sürümlerin garanti edildiği, projenin gerçek öğretici tarafı.

Poetry, projenizin bağımlılıklarını (dependencies) tek bir pyproject.toml dosyasında tanımlamanızı sağlayan modern bir paket yönetim (package management) aracıdır. Siz poetry add rich dediğinizde, Poetry sadece rich paketini indirmekle kalmaz; onun ihtiyaç duyduğu tüm alt paketleri de çözümleyip (dependency resolution) tam sürüm numaralarıyla birlikte poetry.lock adlı bir “kilit dosyasına” yazar. Bu dosya sayesinde projeyi başka bir makinede açan herkes, milimetrik aynı paket ağacını kurar — ne bir sürüm eksik, ne bir tane fazla.

Kısacası bu proje bir algoritma değil, bir iş akışı örneği: modern Python projelerinin bağımlılıklarını nasıl kurumsal düzeyde, tekrarlanabilir (reproducible) şekilde yönettiğini gösteriyor.

Peki requirements.txt neden yetersiz kalıyor? Çünkü genelde sadece doğrudan kullandığın paketlerin sürümünü yazarsın; o paketlerin arkasındaki alt bağımlılıklar (sub-dependencies) genelde sabitlenmez. Zamanla bir alt paket sessizce güncellenir, kodun bir gün çalışır bir gün çalışmaz hâle gelir — buna geliştiriciler arasında biraz şaka yollu “bağımlılık cehennemi” (dependency hell) denir. Poetry’nin poetry.lock dosyası, tam da bu belirsizliği ortadan kaldırmak için var: projeyi bir yıl sonra tekrar kursan bile, o gün kilitlenen sürümler aynen geri gelir.

Kodun Anatomisi

Projenin kalbi aslında pyproject.toml dosyası. pip döneminde bunun karşılığı requirements.txt idi, ama Poetry’de bu dosya hem bağımlılıkları hem proje meta verisini (isim, sürüm, yazar) tek çatı altında toplar:

[project]
name = "34-poetry-package-management"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "rich (>=15.0.0,<16.0.0)",
    "requests (>=2.34.2,<3.0.0)"
]

[dependency-groups]

dev = [ “pytest (>=9.0.3,<10.0.0)” ]

Dikkat edersen pytest normal dependencies listesinde değil, ayrı bir dev grubunda. Bu, Poetry’nin güçlü özelliklerinden biri: test araçları gibi yalnızca geliştirme sırasında gereken paketleri, üretim (production) ortamına hiç taşımadan ayrı tutabiliyorsun.

Uygulamanın kendisi ise sadece kurulan paketin gerçekten kullanılabilir olduğunu kanıtlamak için var:

# Author: Ahmet Aksoy
# Date: 26.05.2026
# Python3.12 Ubuntu 24.04

import sys
from rich.console import Console
from rich.table import Table


def display_environment_info() -> None:
    """Uses the third-party 'rich' package to display system and environment parameters."""
    console = Console()

    table = Table(title="Poetry Managed Environment Metadata")
    table.add_column("Parameter", justify="left", style="cyan", no_wrap=True)
    table.add_column("Value", justify="left", style="magenta")

    table.add_row("Python Executable Path", sys.executable)
    table.add_row("Python Version", sys.version.split()[0])
    table.add_row("Rich Library Status", "Successfully Resolved via Poetry")

    console.print(table)


if __name__ == "__main__":
    display_environment_info()

# Çıktı (terminalde renkli tablo olarak görünür):
# Parameter                | Value
# Python Executable Path   | /home/.../34_poetry_package_management/.venv/bin/python
# Python Version            | 3.12.x
# Rich Library Status       | Successfully Resolved via Poetry

sys.executable satırı aslında en öğretici kısım: çıktı, projenin sistem genelindeki Python’u değil, Poetry’nin sizin için izole ettiği sanal ortamın (virtual environment) kendi Python yorumlayıcısını gösteriyor. Yani rich kütüphanesi sistemine değil, sadece bu projeye özel bir kutuya kuruldu.

Nasıl Çalıştırılır?

Önce Poetry’nin sisteminde kurulu olması gerekiyor. Ubuntu 24.04’te resmi kurulum betiğiyle:

curl -sSL https://install.python-poetry.org | python3 -
poetry --version

Sonra proje klasöründe bağımlılıkları kurup uygulamayı çalıştırmak yeterli:

cd 34_poetry_package_management
poetry install
poetry run python3 src/main.py

poetry install komutu, poetry.lock dosyasındaki tam sürümleri okuyup senin için izole bir sanal ortam kurar. poetry run ise o ortamı manuel olarak aktive etmene gerek bırakmadan, komutu doğrudan o ortamın içinde çalıştırır.

Sıfırdan bir proje kurmak istersen sıralama şöyle: poetry init --no-interaction ile pyproject.toml iskeletini oluştur, poetry add <paket-adı> ile bağımlılık ekle, poetry add <paket-adı> --group dev ile de yalnızca geliştirme ortamında gereken paketleri ayrı tut. Her poetry add komutu, arka planda poetry.lock dosyasını otomatik günceller; yani kilit dosyasını elle düzenlemene hiç gerek kalmaz.

Bu iş akışının asıl gücü, sürekli entegrasyon (CI) ortamlarında ortaya çıkıyor. Bir CD hattı poetry install çalıştırdığında, geliştirme makinende test ettiğin paket ağacının birebir aynısını kurar. pip‘te sık karşılaşılan “staging’de neden farklı davranıyor” sorusu, bu sayede büyük ölçüde ortadan kalkıyor.

Ne Öğrendik?

• pip + requirements.txt ikilisinin aksine Poetry, alt bağımlılıkların sürümünü de poetry.lock dosyasıyla kilitleyerek tekrarlanabilir (reproducible) kurulumlar sağlıyor.
• pyproject.toml, bağımlılıkları ve proje meta verisini tek dosyada topluyor — dağınık yapılandırma dosyalarına gerek kalmıyor.
• dependency-groups özelliğiyle pytest gibi geliştirme araçlarını üretim bağımlılıklarından ayırabiliyoruz.
• poetry run sayesinde sanal ortamı elle aktive etmeden, izole ortamda kod çalıştırabiliyoruz.

Kaynaklar ve Sonraki Adımlar

Bu projede kurduğun dev bağımlılık grubundaki pytest‘i gerçekten kullanmaya başlamak istersen, pytest ile birim testi yazma rehberimiz doğal bir sonraki durak olacaktır. Poetry’nin resmi dokümantasyonunu incelemek ve poetry show --tree komutuyla kendi bağımlılık ağacını görselleştirmek de öğrenmeyi pekiştirecektir.

Ahmet Aksoy

Not: Bu yazıda incelediğimiz kodu ve benzer projelerin kaynak kodlarını https://github.com/ahmetax/practical-python-examples adresinde bulabilirsiniz.