Python Paket Yapısı: Setup.py vs. Pyproject.toml - Kapsamlı Bir Rehber

Uzun yıllar boyunca setup.py dosyası Python paket yönetiminin temel taşı olmuştur. Ancak manzara evrimleşti ve pyproject.toml modern bir alternatif olarak ortaya çıktı. Bu kapsamlı rehber, bu iki yaklaşım arasındaki farkları inceleyerek projeniz için hangisinin doğru olduğunu anlamanıza ve Python paketlerinizi etkili bir şekilde yönetmenize yardımcı olacaktır.

Temelleri Anlamak

Python Paketi Nedir?

Python paketi, Python kodunuzu organize etmenin ve dağıtmanın bir yoludur. İlgili modülleri bir dizin hiyerarşisinde gruplandırmanıza olanak tanır, bu da kodunuzu daha modüler, yeniden kullanılabilir ve bakımı yapılabilir hale getirir. Paketler, kodunuzu başkalarıyla paylaşmak ve projelerinizdeki bağımlılıkları yönetmek için esastır.

Paket Meta Verisinin Rolü

Paket meta verisi, ad, sürüm, yazar, bağımlılıklar ve giriş noktaları gibi paketiniz hakkında temel bilgiler sağlar. Bu meta veriler, paketlerinizi yüklemek, yükseltmek ve yönetmek için pip gibi paket yöneticileri tarafından kullanılır. Tarihsel olarak, setup.py bu meta veriyi tanımlamanın birincil yoluydu.

Setup.py: Geleneksel Yaklaşım

Setup.py Nedir?

setup.py, paketinizin yapısını ve meta verilerini tanımlamak için setuptools kütüphanesini kullanan bir Python betiğidir. Dinamik olarak yürütülen bir dosyadır, yani paketi yapılandırmak için Python kodu çalıştırır.

Setup.py'nin Temel Bileşenleri

Tipik bir setup.py dosyası aşağıdaki bileşenleri içerir:

• Paket Adı: Paketinizin adı (örneğin, my_package).
• Sürüm: Paketinizin sürüm numarası (örneğin, 1.0.0).
• Yazar ve Sorumlu Bilgileri: Paket yazarı ve sorumlusu hakkında detaylar.
• Bağımlılıklar: Paketinizin bağımlı olduğu diğer paketlerin listesi (örneğin, requests >= 2.20.0).
• Giriş Noktaları: Paketiniz için komut satırı betikleri veya diğer giriş noktalarının tanımları.
• Paket Verileri: Pakete dahil edilmesi gereken kod dışı dosyalar (örneğin, yapılandırma dosyaları, veri dosyaları).

Örnek Setup.py

            from setuptools import setup, find_packages

setup(
    name='my_package',
    version='1.0.0',
    author='John Doe',
    author_email='john.doe@example.com',
    description='A simple Python package',
    packages=find_packages(),
    install_requires=[
        'requests >= 2.20.0',
    ],
    entry_points={
        'console_scripts': [
            'my_script = my_package.module:main',
        ],
    },
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
)

            

              
                Copy
              
            
          

Setup.py'nin Avantajları

• Tanıdıklık: Geleneksel ve iyi bilinen bir yaklaşımdır, bu nedenle birçok geliştirici zaten aşinadır.
• Esneklik: Bir Python betiği olduğu için yüksek derecede esneklik sunar. Gerekirse karmaşık mantık yürütebilir ve derleme sürecini özelleştirebilirsiniz.
• Genişletilebilirlik: Setuptools zengin bir özellik seti sunar ve özel komutlar ve uzantılarla genişletilebilir.

Setup.py'nin Dezavantajları

• Dinamik Yürütme: setup.py'nin dinamik doğası, derleme işlemi sırasında rastgele kod yürüttüğü için bir güvenlik riski olabilir.
• Zımni Bağımlılıklar: setup.py genellikle setuptools'un kendisi gibi zımni bağımlılıklara güvenir, bu da tutarsızlıklara ve hatalara yol açabilir.
• Karmaşıklık: Karmaşık projeler için setup.py büyük ve bakımı zor hale gelebilir.
• Sınırlı Bildirimsel Yapılandırma: Paket meta verilerinin çoğu bildirimsel yerine zorunlu olarak tanımlanır, bu da anlaşılmasını zorlaştırır.

Pyproject.toml: Modern Alternatif

Pyproject.toml Nedir?

pyproject.toml, paketinizin derleme sistemini ve meta verilerini tanımlamak için TOML (Tom'un Açık, Minimal Dili) biçimini kullanan bir yapılandırma dosyasıdır. Bildirimsel bir yaklaşımdır, yani neyi başarmak istediğinizi belirtirsiniz, nasıl başaracağınızı değil.

Pyproject.toml'un Ana Bölümleri

• [build-system]: Kullanılacak derleme sistemini tanımlar (örneğin, setuptools, poetry, flit).
• [project]: Ad, sürüm, açıklama, yazarlar ve bağımlılıklar gibi proje hakkındaki meta verileri içerir.
• [tool.poetry] veya [tool.flit]: Araç özelindeki yapılandırmalar için bölümler (örneğin, Poetry, Flit).

Örnek Pyproject.toml (Setuptools ile)

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

[project]
name = "my_package"
version = "1.0.0"
description = "A simple Python package"
authors = [
    { name = "John Doe", email = "john.doe@example.com" }
]
dependencies = [
    "requests >= 2.20.0",
]

[project.scripts]
my_script = "my_package.module:main"

[project.optional-dependencies]
dev = [
    "pytest",
    "flake8",
]

[project.classifiers]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
homepage = "https://example.com"
repository = "https://github.com/example/my_package"

            

              
                Copy
              
            
          

Örnek Pyproject.toml (Poetry ile)

            [tool.poetry]
name = "my_package"
version = "1.0.0"
description = "A simple Python package"
authors = ["John Doe "]
license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = ">=3.7,<3.12"
requests = ">=2.20.0"

[tool.poetry.dev-dependencies]
pytest = "^6.0"
flake8 = "^3.9"

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

            

              
                Copy
              
            
          

Pyproject.toml'un Avantajları

• Bildirimsel Yapılandırma: pyproject.toml, paket meta verilerinizi tanımlamak için bildirimsel bir yol sunarak anlaşılmasını ve bakımını kolaylaştırır.
• Standardize Derleme Sistemi: Farklı ortamlarda tutarlı derlemeler sağlayarak kullanılacak derleme sistemini belirtir.
• Gelişmiş Bağımlılık Yönetimi: Poetry ve Pipenv gibi araçlar, sağlam bağımlılık yönetimi özellikleri sunmak için pyproject.toml ile sorunsuz bir şekilde entegre olur.
• Azaltılmış Güvenlik Riskleri: Statik bir yapılandırma dosyası olduğu için, derleme işlemi sırasında dinamik kod yürütme ile ilgili güvenlik risklerini ortadan kaldırır.
• Modern Araçlarla Entegrasyon: pyproject.toml, Poetry, Pipenv ve Flit gibi modern Python paketleme araçları için standarttır.

Pyproject.toml'un Dezavantajları

• Öğrenme Eğrisi: Geliştiricilerin yeni bir sözdizimi (TOML) ve paket yönetimi hakkında yeni bir düşünce tarzı öğrenmeleri gerekebilir.
• Sınırlı Esneklik: Karmaşık mantık gerektiren yüksek derecede özelleştirilmiş derleme süreçleri için uygun olmayabilir.
• Araç Bağımlılığı: Belirli bir derleme sistemi (örneğin, Setuptools, Poetry, Flit) seçmeniz ve kullanmayı öğrenmeniz gerekecektir.

Setup.py ve Pyproject.toml Karşılaştırması

İşte setup.py ve pyproject.toml arasındaki temel farkları özetleyen bir tablo:

Geçiş Stratejileri: Setup.py'den Pyproject.toml'a

setup.py'den pyproject.toml'a geçiş göz korkutucu görünebilir, ancak uzun vadeli bakım ve tutarlılık için değerli bir yatırımdır. Kullanabileceğiniz birkaç strateji şunlardır:

1. Minimal Bir Pyproject.toml ile Başlayın

Derleme sistemini belirten temel bir pyproject.toml dosyası oluşturun ve ardından meta verileri setup.py'den pyproject.toml'a yavaş yavaş taşıyın.

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

            

              
                Copy
              
            
          

2. Pyproject.toml ile Setuptools Kullanın

Derleme sisteminiz olarak Setuptools'u kullanmaya devam edin, ancak proje meta verilerini pyproject.toml'da tanımlayın. Bu, tanıdık bir araç kullanırken pyproject.toml'un avantajlarından yararlanmanıza olanak tanır.

3. Poetry Gibi Modern Bir Araca Geçiş Yapın

Poetry veya Pipenv gibi modern bir araca geçiş yapmayı düşünün. Bu araçlar kapsamlı bağımlılık yönetimi özellikleri sunar ve pyproject.toml ile sorunsuz bir şekilde entegre olur.

Örnek: Poetry'ye Geçiş

1. Poetry'yi Yükleyin: pip install poetry
2. Projenizde Poetry'yi Başlatın: poetry init (Bu, bir pyproject.toml dosyası oluşturmanızda size rehberlik edecektir)
3. Bağımlılıklarınızı Ekleyin: poetry add requests (veya diğer bağımlılıklar)
4. Paketinizi Derleyin: poetry build

4. Otomatik Geçiş Araçları Kullanın

Bazı araçlar geçiş sürecini otomatikleştirmeye yardımcı olabilir. Örneğin, setup.py dosyanızı bir pyproject.toml dosyasına dönüştürmek için araçlar kullanabilirsiniz.

Python Paket Yönetimi İçin En İyi Uygulamalar

1. Sanal Bir Ortam Kullanın

Projenizin bağımlılıklarını sistem genelindeki Python kurulumundan izole etmek için her zaman bir sanal ortam kullanın. Bu, çakışmaları önler ve projenizin doğru bağımlılıklara sahip olmasını sağlar.

venv kullanarak örnek:

            python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS'ta
.venv\Scripts\activate  # Windows'ta

            

              
                Copy
              
            
          

conda kullanarak örnek:

            conda create -n myenv python=3.9
conda activate myenv

            

              
                Copy
              
            
          

2. Bağımlılıkları Doğru Belirtin

Bağımlılıklarınızın uyumlu sürümlerini belirtmek için sürüm kısıtlamaları kullanın. Bu, uyumsuz kütüphane güncellemelerinden kaynaklanan beklenmeyen davranışları önler. Bağımlılıklarınızı yönetmek için pip-tools gibi araçları kullanın.

Örnek bağımlılık belirtimi:

            
requests >= 2.20.0, < 3.0.0

            

              
                Copy
              
            
          

3. Tutarlı Bir Derleme Sistemi Kullanın

Bir derleme sistemi seçin (örneğin, Setuptools, Poetry, Flit) ve ona bağlı kalın. Bu, farklı ortamlarda tutarlı derlemeler sağlar ve paketleme sürecini basitleştirir.

4. Paketinizle İlgili Dokümantasyon Yazın

Paketiniz için net ve özlü belgeler yazın. Bu, kullanıcıların paketinizinkullanmayı anlamalarına yardımcı olur ve başkalarının projenize katkıda bulunmasını kolaylaştırır. Kodunuzdan belgeler oluşturmak için Sphinx gibi araçları kullanın.

5. Sürekli Entegrasyon (CI) Kullanın

Kodunuzdaki değişiklikler yapıldığında paketinizin otomatik olarak derlenmesi, test edilmesi ve dağıtılması için bir CI sistemi (örneğin, GitHub Actions, Travis CI, GitLab CI) kurun. Bu, paketinizin her zaman çalışır durumda olmasını sağlamaya yardımcı olur.

Örnek GitHub Actions yapılandırması:

            name: Python Package

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

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python 3.9
      uses: actions/setup-python@v4
      with:
        python-version: 3.9
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install poetry
        poetry install
    - name: Lint with flake8
      run: |
        poetry run flake8 .
    - name: Test with pytest
      run: |
        poetry run pytest

            

              
                Copy
              
            
          

6. Paketinizi PyPI'ye Yayınlayın

Paketinizi Python Paket İndeksi'ne (PyPI) yayınlayarak dünyayla paylaşın. Bu, başkalarının paketini yüklemesini ve kullanmasını kolaylaştırır.

PyPI'ye yayınlama adımları:

1. PyPI ve TestPyPI'da bir hesap oluşturun.
2. twine'i yükleyin: pip install twine.
3. Paketinizi derleyin: poetry build veya python setup.py sdist bdist_wheel.
4. Paketinizi TestPyPI'ye yükleyin: twine upload --repository testpypi dist/*.
5. Paketinizi PyPI'ye yükleyin: twine upload dist/*.

Gerçek Dünya Örnekleri

Popüler Python projelerinin pyproject.toml'u nasıl kullandığına bakalım:

• Poetry: Kendi paket yönetimi için pyproject.toml kullanır.
• Black: Taviz vermeyen kod biçimlendirici de pyproject.toml'u kullanır.
• FastAPI: Python ile API'ler oluşturmak için modern, hızlı (yüksek performanslı) bir web çerçevesi de bunu kullanır.

Sonuç

pyproject.toml, paket meta verilerinizi tanımlamak ve bağımlılıkları yönetmek için bildirimsel ve güvenli bir yol sunarak Python paket yönetiminin modern standardını temsil eder. setup.py bize iyi hizmet etmiş olsa da, pyproject.toml'a geçiş yapmak uzun vadeli bakım, tutarlılık ve modern araçlarla entegrasyon için değerli bir yatırımdır. En iyi uygulamaları benimseyerek ve doğru araçları kullanarak, Python paketleme iş akışınızı geliştirebilir ve yüksek kaliteli, yeniden kullanılabilir paketler oluşturabilirsiniz.

Daha Fazla Kaynak

• Python Paketleme Kullanıcı Rehberi: Araç Önerileri
• Pip: pyproject.toml desteği
• Poetry: pyproject.toml dosyası
• Setuptools: pyproject.toml kullanımı