Modern Paket Yönetimi: Poetry ve pyproject.toml

Şimdiye kadar pip install paket_adi yazdın, paket geldi, kullandın. Küçük projelerde bu yeter. Ama proje büyüdükçe sorular çoğalır: "Hangi versiyonu kurmuştum?", "Arkadaşım neden farklı versiyon görüyor?", "Test için gereken paketler production'a neden gidiyor?" Bu soruların hepsi paket yönetimi sorunudur ve pip tek başına bunları çözmek için tasarlanmadı.

Bu derste Python'un modern paket yönetim aracı Poetry'yi ve Python ekosisteminin yeni standart dosyası pyproject.toml'u öğreneceksin. Dersin sonunda projelerini profesyonel seviyede yönetebilecek, dependency cehenneminden kurtulacak ve "bende çalışıyor ama sende çalışmıyor" problemini tarihe gömeceksin.

1. pip + venv'in Sınırları

🏗️ Analoji: Yapı Malzemesi Listesi

Bir ev inşa ettiğini düşün. Malzeme listeni bir kâğıda yazıyorsun: "Çimento, demir, tuğla." Ama kaç torba çimento? Hangi çapta demir? Ne marka tuğla? Kâğıtta bunlar yok. Bir de yardımcına bu listeyi verdiğinde, o da marketin o günkü rafında ne varsa onu alıyor. Sonuç: senin evinde 5 torba çimento var, onun evinde 50 torba.

pip + requirements.txt tam olarak bu. Çalışır ama deterministik değildir.

requirements.txt'in Problemleri

En yaygın yöntem projedeki bağımlılıkları requirements.txt dosyasına yazmaktır:

# requirements.txt
flask>=2.0
sqlalchemy
requests==2.31.0

Bu basit dosyanın birkaç ciddi sorunu var:

# Sorun 1: "freeze" her şeyi döker
pip freeze > requirements.txt

# Sonuç: direkt bağımlılıklar + onların bağımlılıkları karışır
# 5 paket kurmuştun, dosyada 47 satır var
# Hangisi senin istediğin, hangisi otomatik gelen? Belli değil.

# Sorun 2: Alt bağımlılık versiyonları değişir
# Senin makinende: flask==2.3.2 → werkzeug==2.3.6
# Arkadaşının makinesinde: flask==2.3.2 → werkzeug==2.3.7
# Aynı Flask, farklı Werkzeug — ve bir gün bu fark patlıyor

# Sorun 3: Dev ve production bağımlılıkları ayrılmaz
# pytest, black, mypy sadece geliştirme için lazım
# Ama requirements.txt'te hepsi bir arada
# İki dosya mı tutacaksın? requirements.txt + requirements-dev.txt?
# Peki test? requirements-test.txt de mi?

İşin özü şu: pip bir paket kurucudur, bir proje yöneticisi değildir. Paketleri kurar ama projeni yönetmez — bağımlılık çözümleme (dependency resolution) yüzeyseldir, lock mekanizması yoktur, proje metadata'sı (isim, versiyon, yazar) ile ilgilenmez.

2. pyproject.toml: Python'un Yeni Standart Dosyası

PEP 517 ve PEP 518

Python topluluğu bu problemleri gördü ve bir dizi PEP (Python Enhancement Proposal) ile çözüm üretti:

• PEP 518 (2016): Build sistemi bağımlılıklarını tanımlamak için pyproject.toml dosyasını standart yaptı.

• PEP 517 (2017): Build backend'lerin nasıl çalışacağını standartlaştırdı.

• PEP 621 (2021): Proje metadata'sının pyproject.toml'da nasıl yazılacağını belirledi.

Eskiden her build aracının (setuptools, flit, poetry) kendi config dosyası vardı: setup.py, setup.cfg, pyproject.toml... Şimdi tek bir dosya her şeyi yönetiyor.

pyproject.toml Anatomisi

# pyproject.toml — projenin kimlik kartı

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "my-awesome-project"
version = "0.1.0"
description = "Harika bir Python projesi"
authors = ["Tolgahan <tolgahan@example.com>"]
readme = "README.md"
license = "MIT"
python = "^3.10"

[tool.poetry.dependencies]
python = "^3.10"
flask = "^3.0"
sqlalchemy = "^2.0"
requests = "^2.31"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.0"
mypy = "^1.5"

[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"

TOML (Tom's Obvious Minimal Language) formatı ini dosyalarına benzer ama daha güçlüdür. [section] blokları, key = "value" çiftleri ve iç içe yapılar destekler. JSON'dan daha okunabilir, YAML'dan daha güvenilirdir.

Neden TOML?

# TOML — net ve okunabilir
[tool.poetry.dependencies]
flask = "^3.0"
requests = {version = "^2.31", optional = true}

[tool.poetry.scripts]
my-cli = "my_project.cli:main"

Her şey tek dosyada, her şeyin yeri belli. setup.py gibi Python kodu çalıştırma riski yok — TOML bir veri formatıdır, çalıştırılabilir kod değildir. Bu da güvenlik açısından büyük bir artıdır.

3. Poetry: Kurulum ve Temel Kullanım

Poetry Nedir?

Poetry, Python için hepsi bir arada bir proje yönetim aracıdır. Tek bir komut satırı aracıyla şunları yapar:

• Proje oluşturma ve yapılandırma

• Bağımlılık ekleme, kaldırma ve güncelleme

• Sanal ortam (virtual environment) yönetimi

• Lock dosyası ile deterministik kurulum

• Paket build ve PyPI'a publish

Kurulum

Poetry'yi pip ile kurmamalısın. Kendi kurulum scripti var — böylece sistem Python'undan bağımsız çalışır:

# Önerilen kurulum — resmi installer
curl -sSL https://install.python-poetry.org | python3 -

# Versiyon kontrolü
poetry --version
# Poetry (version 1.8.2)

# Alternatif: pipx ile (izole ortamda CLI araçları kurar)
pipx install poetry

⚠️ Dikkat: pip install poetry yapma. Bu, Poetry'yi projenin sanal ortamına kurar ve bağımlılık çakışmalarına yol açabilir. Poetry global bir araç olmalı — tıpkı git gibi.

Yeni Proje Oluşturma

# Sıfırdan yeni proje
poetry new my-project

# Oluşan yapı:
# my-project/
# ├── pyproject.toml
# ├── README.md
# ├── my_project/
# │   └── __init__.py
# └── tests/
#     └── __init__.py

Mevcut bir projede Poetry'ye geçiş yapmak istersen:

# Mevcut dizinde pyproject.toml oluştur
cd existing-project
poetry init

# İnteraktif sihirbaz sorar:
# - Proje adı
# - Versiyon
# - Açıklama
# - Bağımlılıklar (isterseniz atla, sonra ekle)

Bağımlılık Ekleme: poetry add

# Production bağımlılığı ekle
poetry add flask
poetry add sqlalchemy requests

# Belirli versiyon
poetry add "flask>=3.0,<4.0"
poetry add flask@^3.0

# Dev bağımlılığı ekle
poetry add --group dev pytest black mypy

# Test grubu
poetry add --group test pytest-cov hypothesis

# Docs grubu
poetry add --group docs sphinx sphinx-rtd-theme

# Bağımlılık kaldır
poetry remove flask

Her poetry add komutu iki şey yapar: pyproject.toml'a bağımlılığı ekler ve poetry.lock dosyasını günceller. Bu ikili yapı, Poetry'nin gücünün kaynağıdır.

Kurulum: poetry install

# Tüm bağımlılıkları kur (lock dosyasından)
poetry install

# Sadece production (dev grupları hariç)
poetry install --only main

# Belirli grupları dahil et
poetry install --with test,docs

# Belirli grupları hariç tut
poetry install --without docs

poetry install komutu poetry.lock dosyasını okur ve birebir aynı versiyonları kurar. Ekipteki herkes, CI/CD pipeline'ı, production sunucusu — hepsi aynı versiyonları alır. "Bende çalışıyor" problemi biter.

Lock Dosyası: Deterministik Kurulumun Anahtarı

# Lock dosyasını güncelle (dependency değişikliğinden sonra)
poetry lock

# Lock dosyasını güncelle ama paketleri kurma
poetry lock --no-update

poetry.lock dosyası her paketin tam versiyonunu, hash'ini ve alt bağımlılıklarını içerir:

# poetry.lock'tan bir kesit (otomatik oluşturulur, elle düzenleme!)
[[package]]
name = "flask"
version = "3.0.2"
description = "A simple framework for building complex web applications."
python-versions = ">=3.8"

[package.dependencies]
Werkzeug = ">=3.0.0"
Jinja2 = ">=3.1.2"
itsdangerous = ">=2.1.2"
click = ">=8.1.3"
blinker = ">=1.6.2"

[[package]]
name = "werkzeug"
version = "3.0.1"
# ... tam versiyon sabitlenmiş

💡 İpucu: poetry.lock dosyasını mutlaka Git'e commit'le. Bu dosya olmadan, farklı makinelerde farklı versiyonlar kurulabilir. pyproject.toml "ne istediğini" söyler, poetry.lock "ne kurulduğunu" söyler.

4. Version Constraint'ler

Bağımlılık tanımlarken versiyon aralığı belirtirsin. Poetry (ve genel olarak Python ekosistemi) Semantic Versioning (SemVer) kullanır: MAJOR.MINOR.PATCH

• MAJOR (3.x.x): Geriye uyumsuz (breaking) değişiklikler

• MINOR (x.1.x): Geriye uyumlu yeni özellikler

• PATCH (x.x.2): Bug fix'ler

Constraint Türleri

[tool.poetry.dependencies]
# Tam sabitlenmiş — sadece bu versiyon
flask = "3.0.2"

# Caret (^) — en yaygın, SemVer uyumlu güncelleme
# ^3.0.2  →  >=3.0.2, <4.0.0  (major değişmez)
# ^0.2.3  →  >=0.2.3, <0.3.0  (0.x'te minor = major gibi)
flask = "^3.0"

# Tilde (~) — daha kısıtlı
# ~3.0.2  →  >=3.0.2, <3.1.0  (sadece patch güncellenir)
flask = "~3.0.2"

# Compatible release (~=) — PEP 440 stili
# ~=3.0.2  →  >=3.0.2, <3.1.0  (tilde ile aynı)
flask = "~=3.0.2"

# Aralık belirtme
flask = ">=3.0,<4.0"

# Wildcard
flask = "3.0.*"

# En az bu versiyon
flask = ">=3.0"

Hangi Constraint'i Kullanmalı?

# ✅ Çoğu durumda caret (^) kullan
# Yeni özellikler gelir, breaking change gelmez
requests = "^2.31"

# ✅ Çok hassas projelerde tilde (~) kullan
# Sadece bug fix'ler gelir
cryptography = "~41.0.5"

# ❌ Tam sabitleme genelde gereksiz
# Güvenlik yamaları bile gelmez
requests = "2.31.0"

# ❌ Üst sınır koymamak tehlikeli
# Bir gün breaking change gelir ve her şey patlar
requests = ">=2.0"

Genel kural: kütüphaneler için ^ (caret), kritik/güvenlik hassas paketler için ~ (tilde), uygulamalar için zaten poetry.lock tam versiyonu sabitler.

5. Sanal Ortam Yönetimi

Poetry kendi sanal ortamını otomatik yönetir. python -m venv .venv yapmanıza gerek yok:

# Sanal ortam bilgisi
poetry env info

# Sanal ortam dizinini göster
poetry env info --path
# /home/user/.cache/pypoetry/virtualenvs/my-project-Xy7z-py3.11

# Sanal ortam içinde komut çalıştır
poetry run python main.py
poetry run pytest
poetry run black .

# Sanal ortam shell'ine gir
poetry shell

# Belirli Python versiyonuyla ortam oluştur
poetry env use python3.12
poetry env use /usr/bin/python3.11

# Sanal ortamı sil
poetry env remove python3.11

Sanal ortamı proje dizini içinde istiyorsan:

# Global ayar: .venv dizini proje içinde olsun
poetry config virtualenvs.in-project true

# Artık .venv dizini proje kökünde oluşur
# IDE'ler (VS Code, PyCharm) bunu otomatik algılar

Bu ayar özellikle IDE entegrasyonu için önerilir. VS Code projeyi açtığında .venv dizinini otomatik bulur ve doğru Python interpreter'ını seçer.

6. Poetry vs pip+venv Karşılaştırma

İki yaklaşımı yan yana koyalım:

# === pip + venv yaklaşımı ===

# 1. Sanal ortam oluştur
python -m venv .venv
source .venv/bin/activate   # Linux/Mac
.venv\Scripts\activate      # Windows

# 2. Paketleri kur
pip install flask sqlalchemy requests
pip install pytest black mypy  # dev paketleri de aynı yere

# 3. Bağımlılıkları kaydet
pip freeze > requirements.txt

# 4. Başka makinede kur
pip install -r requirements.txt

# 5. Güncelleme?
pip install --upgrade flask
pip freeze > requirements.txt  # tekrar freeze

# === Poetry yaklaşımı ===

# 1. Proje başlat (sanal ortam otomatik)
poetry init

# 2. Paketleri kur — gruplarıyla
poetry add flask sqlalchemy requests
poetry add --group dev pytest black mypy

# 3. Kayıt otomatik (pyproject.toml + poetry.lock)

# 4. Başka makinede kur — birebir aynı versiyonlar
poetry install

# 5. Güncelleme
poetry update flask  # lock da güncellenir

Poetry'nin bağımlılık çözümleyicisi bir SAT solver kullanır. Bu matematiksel bir tatmin edilebilirlik problemi çözücüsüdür — tüm paketlerin uyumlu versiyonlarını bulmayı garanti eder veya "bu kombinasyon imkânsız" der. pip'in çözücüsü 2020'de geliştirildi ama hâlâ Poetry kadar güçlü değildir.

7. pipenv: Kısa Bir Bakış

Poetry'den önce bu boşluğu doldurmaya çalışan bir araç daha var: pipenv.

# pipenv kullanımı
pipenv install flask
pipenv install --dev pytest
pipenv shell
pipenv lock

pipenv, Pipfile ve Pipfile.lock dosyalarını kullanır. Bir dönem Python.org tarafından "önerilen" araç olarak gösterildi ama sonra bu ifade kaldırıldı. Bugün pipenv hâlâ kullanılıyor ama birkaç dezavantajı var:

• Yavaş: Dependency resolution ve lock işlemi Poetry'den belirgin şekilde yavaş.

• pyproject.toml desteği yok: Kendi Pipfile formatını kullanır — standartlaşma dışında kalır.

• Build ve publish yok: Sadece dependency yönetimi yapar, paket oluşturup yayınlayamaz.

Yeni projelerde Poetry tercih edilmeli. Mevcut pipenv projelerini de zamanla Poetry'ye taşımak iyi bir yatırımdır. Poetry, pipenv'in yaptığı her şeyi yapar ve üstüne build/publish ekler.

8. Dependency Grupları

Gerçek projelerde farklı ortamlar farklı paketlere ihtiyaç duyar. Bir test framework'ü production'da gereksizdir, bir dokümantasyon aracı CI pipeline'ında yer kaplar:

[tool.poetry.dependencies]
# Ana bağımlılıklar — production'da gerekli
python = "^3.10"
flask = "^3.0"
sqlalchemy = "^2.0"
redis = "^5.0"

[tool.poetry.group.dev.dependencies]
# Geliştirme araçları — sadece developer'ın makinesinde
pytest = "^7.4"
black = "^23.0"
mypy = "^1.5"
ruff = "^0.1"
ipython = "^8.0"

[tool.poetry.group.test.dependencies]
# Test araçları — CI/CD'de de kurulur
pytest-cov = "^4.1"
pytest-asyncio = "^0.21"
hypothesis = "^6.0"
factory-boy = "^3.3"

[tool.poetry.group.docs.dependencies]
# Dokümantasyon — sadece docs build'de
sphinx = "^7.0"
sphinx-rtd-theme = "^1.3"
myst-parser = "^2.0"

# Gruplarla kurulum kontrolü
poetry install                     # main + tüm gruplar
poetry install --only main         # sadece production
poetry install --with test         # main + test
poetry install --without docs,dev  # docs ve dev hariç

Bu yapı CI/CD pipeline'larında çok değerlidir. Production deploy'da sadece --only main, test aşamasında --with test, dokümantasyon build'de --with docs kurarsın. Gereksiz paket kurulmaz, Docker image boyutu küçülür, güvenlik yüzeyi daralır.

Optional Dependencies

Bazı bağımlılıklar isteğe bağlı olabilir — kullanıcı isterse kurar:

[tool.poetry.extras]
mysql = ["mysqlclient"]
postgres = ["psycopg2-binary"]
all-databases = ["mysqlclient", "psycopg2-binary"]

# Kullanıcı istediği extra'yı kurar
pip install my-package[postgres]
pip install my-package[all-databases]

9. Publishing: Build ve Yayınlama

Kendi paketini PyPI'a yayınlamak Poetry ile çok kolaydır:

Build

# Paket oluştur
poetry build

# Oluşan dosyalar:
# dist/
# ├── my_project-0.1.0-py3-none-any.whl   (wheel — kurulum için)
# └── my_project-0.1.0.tar.gz              (source distribution)

Wheel (.whl) önceden derlenmiş formattır — kurulum hızlıdır. Source distribution (.tar.gz) kaynak kodunu içerir — her platformda build edilir. İkisi de oluşturulur, PyPI'a ikisi de yüklenir.

PyPI'a Yayınlama

# Test PyPI'a yayınla (önce test et!)
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish --repository testpypi

# Gerçek PyPI'a yayınla
poetry publish

# Build + publish tek adımda
poetry publish --build

# Token ile authentication (önerilen)
poetry config pypi-token.pypi pypi-AgEIcH...

# Tam bir yayınlama workflow'u
# 1. Versiyon güncelle
poetry version patch   # 0.1.0 → 0.1.1
poetry version minor   # 0.1.1 → 0.2.0
poetry version major   # 0.2.0 → 1.0.0

# 2. Build et
poetry build

# 3. Test PyPI'a dene
poetry publish --repository testpypi

# 4. Test PyPI'dan kurulumu test et
pip install --index-url https://test.pypi.org/simple/ my-project

# 5. Her şey OK ise gerçek PyPI'a
poetry publish

⚠️ Dikkat: PyPI'a yüklenen bir versiyon geri alınamaz. my-project==1.0.0 yükledikten sonra bu versiyon numarasını bir daha kullanamazsın. Bu yüzden Test PyPI'da test etmek kritik önem taşır.

10. Gerçek Dünya: CI/CD Entegrasyonu

Poetry'nin asıl gücü takım çalışmasında ve CI/CD pipeline'larında ortaya çıkar. İşte bir GitHub Actions örneği:

# .github/workflows/test.yml
name: Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          version: latest
          virtualenvs-create: true
          virtualenvs-in-project: true

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}

      - name: Install dependencies
        run: poetry install --with test

      - name: Run tests
        run: poetry run pytest --cov=my_project tests/

      - name: Lint
        run: |
          poetry run ruff check .
          poetry run mypy my_project/

Bu pipeline her push'ta ve PR'da çalışır. poetry.lock'un hash'ini cache key olarak kullanır — bağımlılıklar değişmedikçe yeniden kurulum yapmaz. Üç farklı Python versiyonunda test eder. Lock dosyası sayesinde CI'da kurulan paketler senin makinendekiyle birebir aynıdır.

Dockerfile Örneği

# Dockerfile — multi-stage build
FROM python:3.12-slim as builder

# Poetry kurulumu
RUN pip install poetry==1.8.2
ENV POETRY_VIRTUALENVS_IN_PROJECT=true \
    POETRY_NO_INTERACTION=1

WORKDIR /app

# Önce sadece dependency dosyalarını kopyala (cache için)
COPY pyproject.toml poetry.lock ./
RUN poetry install --only main --no-root

# Sonra kaynak kodu kopyala
COPY . .
RUN poetry install --only main

# Production stage — sadece gerekli dosyalar
FROM python:3.12-slim as runtime
WORKDIR /app

COPY --from=builder /app/.venv ./.venv
COPY --from=builder /app/my_project ./my_project

ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "my_project"]

Multi-stage build ile Docker image boyutu dramatik şekilde küçülür. Poetry ve build araçları sadece builder stage'de bulunur, production image'a geçmez.

11. Poetry Komut Referansı

Günlük kullanımda en sık ihtiyaç duyacağın komutlar:

# Proje başlatma
poetry new project-name         # Yeni proje oluştur
poetry init                     # Mevcut dizinde başlat

# Bağımlılık yönetimi
poetry add package              # Bağımlılık ekle
poetry add --group dev package  # Grup bağımlılığı ekle
poetry remove package           # Kaldır
poetry update                   # Tüm paketleri güncelle
poetry update flask requests    # Belirli paketleri güncelle
poetry show                     # Kurulu paketleri listele
poetry show --tree              # Bağımlılık ağacını göster
poetry show --outdated          # Güncellemesi olan paketler

# Sanal ortam
poetry env info                 # Ortam bilgisi
poetry env use python3.12       # Python versiyonu seç
poetry shell                    # Ortam shell'ine gir
poetry run command              # Ortam içinde komut çalıştır

# Build ve yayınlama
poetry build                    # Paket oluştur
poetry publish                  # PyPI'a yayınla
poetry version patch            # Versiyon artır

# Lock
poetry lock                     # Lock dosyasını güncelle
poetry install                  # Lock'tan kur
poetry export -f requirements.txt --output requirements.txt
# pip kullanan ortamlar için requirements.txt üret

poetry export komutu özellikle geçiş döneminde kullanışlıdır. Takımın bir kısmı hâlâ pip kullanıyorsa veya deployment ortamı Poetry desteklemiyorsa, lock dosyasından deterministik bir requirements.txt üretebilirsin.

12. Best Practices

Do ✅

# poetry.lock'u commit'le
git add pyproject.toml poetry.lock
git commit -m "chore: update dependencies"

# Versiyon constraint'lerde caret kullan
# pyproject.toml
flask = "^3.0"

# CI'da --no-interaction kullan
poetry install --no-interaction

# Sanal ortamı proje içinde tut (IDE uyumu)
poetry config virtualenvs.in-project true

Don't ❌

# poetry.lock'u .gitignore'a ekleme
# (Kütüphane yazıyorsan tartışılır ama uygulama için kesinlikle commit'le)

# pip install poetry yapma
# Global installer veya pipx kullan

# Elle poetry.lock düzenleme
# Her zaman poetry lock komutuyla güncelle

# Sanal ortamı (.venv) commit'leme
echo ".venv/" >> .gitignore

Mevcut Projeyi Poetry'ye Taşıma

# 1. Poetry'yi başlat
cd my-existing-project
poetry init

# 2. requirements.txt'ten bağımlılıkları aktar
cat requirements.txt | xargs poetry add

# 3. Dev bağımlılıklarını ayrı ekle
cat requirements-dev.txt | xargs poetry add --group dev

# 4. Lock dosyasını oluştur ve test et
poetry lock
poetry install
poetry run pytest

# 5. Eski dosyaları temizle (her şey çalıştıktan sonra)
git rm requirements.txt requirements-dev.txt

13. Alternatifler: Hızlı Bir Bakış

Poetry tek seçenek değil. Python ekosisteminde birkaç alternatif daha var:

uv özellikle son dönemde hızla yükselen bir araç. Astral (ruff'un yaratıcıları) tarafından geliştiriliyor, pip install komutunun 10-100x hızında çalışıyor. Henüz Poetry kadar tam bir proje yöneticisi olmasa da hızla gelişiyor.

Hangi aracı seçersen seç, önemli olan bir araç seçmek ve tutarlı kullanmaktır. pip freeze > requirements.txt dönemi bitti.

Özet

• `pip` + `requirements.txt` basit projeler için yeterlidir ama deterministik değildir — lock mekanizması ve dependency grupları yoktur.

• `pyproject.toml` Python projelerinin standart yapılandırma dosyasıdır (PEP 517/518/621). Proje metadata'sı, bağımlılıklar ve build ayarları tek dosyada toplanır.

• Poetry bağımlılık yönetimi, sanal ortam, build ve publish işlemlerini tek araçta birleştirir. poetry.lock ile deterministik kurulum sağlar.

• Version constraint'lerde caret (^) operatörü çoğu durum için idealdir — SemVer uyumlu güncellemelere izin verir, breaking change'leri engeller.

• Dependency grupları (dev, test, docs) ile farklı ortamlara farklı paketler kurulur — production image'ı temiz kalır.

• `poetry.lock` dosyasını Git'e commit'le. Bu dosya, ekipteki herkesin ve CI/CD'nin birebir aynı versiyonları kurmasını garanti eder.