Struktura balíčků Python: Setup.py vs. Pyproject.toml – Kompletní průvodce

Po mnoho let byl soubor setup.py základním kamenem správy balíčků Pythonu. Krajina se však vyvinula a pyproject.toml se stal moderní alternativou. Tento obsáhlý průvodce zkoumá rozdíly mezi těmito dvěma přístupy a pomáhá vám pochopit, který z nich je pro váš projekt ten pravý a jak efektivně spravovat vaše Python balíčky.

Porozumění základům

Co je to Python balíček?

Python balíček je způsob, jak organizovat a distribuovat váš Python kód. Umožňuje vám seskupovat související moduly do hierarchie adresářů, čímž se váš kód stává modulárnějším, znovupoužitelným a snadněji spravovatelným. Balíčky jsou nezbytné pro sdílení vašeho kódu s ostatními a pro správu závislostí ve vašich projektech.

Role metadat balíčku

Metadata balíčku poskytují zásadní informace o vašem balíčku, jako je jeho název, verze, autor, závislosti a vstupní body. Tato metadata používají správci balíčků, jako je pip, k instalaci, aktualizaci a správě vašich balíčků. Historicky byl setup.py primárním způsobem definice těchto metadat.

Setup.py: Tradiční přístup

Co je to Setup.py?

setup.py je Python skript, který používá knihovnu setuptools k definování struktury a metadat vašeho balíčku. Jedná se o dynamicky prováděný soubor, což znamená, že spouští Python kód pro konfiguraci balíčku.

Klíčové komponenty Setup.py

Typický soubor setup.py obsahuje následující komponenty:

• Název balíčku: Název vašeho balíčku (např. my_package).
• Verze: Číslo verze vašeho balíčku (např. 1.0.0).
• Informace o autorovi a správci: Podrobnosti o autorovi a správci balíčku.
• Závislosti: Seznam dalších balíčků, na kterých váš balíček závisí (např. requests >= 2.20.0).
• Vstupní body: Definice pro skripty příkazového řádku nebo jiné vstupní body do vašeho balíčku.
• Datové soubory balíčku: Ne-kódové soubory (např. konfigurační soubory, datové soubory), které by měly být součástí balíčku.

Příklad 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
              
            
          

Výhody Setup.py

• Známý přístup: Jedná se o tradiční a dobře známý přístup, takže mnoho vývojářů jej již zná.
• Flexibilita: Protože se jedná o Python skript, nabízí vysokou míru flexibility. Můžete provádět složitou logiku a přizpůsobit proces sestavení podle potřeby.
• Rozšiřitelnost: Setuptools poskytuje bohatou sadu funkcí a lze jej rozšířit o vlastní příkazy a rozšíření.

Nevýhody Setup.py

• Dynamické spouštění: Dynamická povaha setup.py může představovat bezpečnostní riziko, protože během procesu sestavení spouští libovolný kód.
• Implicitní závislosti: setup.py se často spoléhá na implicitní závislosti, jako je samotný setuptools, což může vést k nekonzistencím a chybám.
• Složitost: U složitých projektů se setup.py může stát velkým a obtížně udržovatelným.
• Omezená deklarativní konfigurace: Velká část metadat balíčku je definována imperativně, nikoli deklarativně, což ztěžuje pochopení.

Pyproject.toml: Moderní alternativa

Co je to Pyproject.toml?

pyproject.toml je konfigurační soubor, který používá formát TOML (Tom's Obvious, Minimal Language) k definování build systému a metadat vašeho balíčku. Jedná se o deklarativní přístup, což znamená, že specifikujete, čeho chcete dosáhnout, nikoli jak toho dosáhnout.

Klíčové sekce Pyproject.toml

• [build-system]: Definuje build systém k použití (např. setuptools, poetry, flit).
• [project]: Obsahuje metadata o projektu, jako je jeho název, verze, popis, autoři a závislosti.
• [tool.poetry] nebo [tool.flit]: Sekce pro konfigurace specifické pro nástroje (např. Poetry, Flit).

Příklad Pyproject.toml (se Setuptools)

            [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
              
            
          

Příklad Pyproject.toml (s Poetry)

            [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
              
            
          

Výhody Pyproject.toml

• Deklarativní konfigurace: pyproject.toml poskytuje deklarativní způsob definice metadat vašeho balíčku, což usnadňuje pochopení a údržbu.
• Standardizovaný build systém: Specifikuje build systém k použití, což zajišťuje konzistentní sestavení napříč různými prostředími.
• Vylepšená správa závislostí: Nástroje jako Poetry a Pipenv se bezproblémově integrují s pyproject.toml a poskytují robustní funkce pro správu závislostí.
• Snížená bezpečnostní rizika: Protože se jedná o statický konfigurační soubor, eliminuje bezpečnostní rizika spojená s dynamickým spouštěním kódu během procesu sestavení.
• Integrace s moderními nástroji: pyproject.toml je standardem pro moderní nástroje pro balíčkování Pythonu, jako jsou Poetry, Pipenv a Flit.

Nevýhody Pyproject.toml

• Křivka učení: Vývojáři se možná budou muset naučit nový syntax (TOML) a nový způsob myšlení o správě balíčků.
• Omezená flexibilita: Nemusí být vhodný pro vysoce přizpůsobené build procesy, které vyžadují složitou logiku.
• Závislost na nástrojích: Budete muset vybrat a naučit se používat konkrétní build systém (např. Setuptools, Poetry, Flit).

Porovnání Setup.py a Pyproject.toml

Zde je tabulka shrnující klíčové rozdíly mezi setup.py a pyproject.toml:

Strategie migrace: Z Setup.py na Pyproject.toml

Migrace ze setup.py na pyproject.toml se může zdát náročná, ale je to cenná investice do dlouhodobé udržitelnosti a konzistence. Zde je několik strategií, které můžete použít:

1. Začněte s minimálním Pyproject.toml

Vytvořte základní soubor pyproject.toml, který specifikuje build systém, a poté postupně migrujte metadata ze setup.py do pyproject.toml.

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

            

              
                Copy
              
            
          

2. Použijte Setuptools s Pyproject.toml

Nadále používejte Setuptools jako svůj build systém, ale definujte metadata projektu v pyproject.toml. To vám umožní využívat výhod pyproject.toml a zároveň používat známý nástroj.

3. Migrujte na moderní nástroj jako Poetry

Zvažte migraci na moderní nástroj, jako je Poetry nebo Pipenv. Tyto nástroje poskytují komplexní funkce pro správu závislostí a bezproblémově se integrují s pyproject.toml.

Příklad: Migrace na Poetry

1. Nainstalujte Poetry: pip install poetry
2. Inicializujte Poetry ve svém projektu: poetry init (Toto vás provede vytvořením souboru pyproject.toml)
3. Přidejte své závislosti: poetry add requests (nebo jakékoli jiné závislosti)
4. Sestavte svůj balíček: poetry build

4. Použijte nástroje pro automatizovanou migraci

Některé nástroje mohou pomoci automatizovat proces migrace. Můžete například použít nástroje k převodu vašeho souboru setup.py na soubor pyproject.toml.

Osvědčené postupy pro správu balíčků Python

1. Používejte virtuální prostředí

Vždy používejte virtuální prostředí k izolaci závislostí vašeho projektu od systémové instalace Pythonu. Tím se zabrání konfliktům a zajistí se, že váš projekt má správné závislosti.

Příklad použití venv:

            python3 -m venv .venv
source .venv/bin/activate  # Na Linuxu/macOS
.venv\Scripts\activate  # Na Windows

            

              
                Copy
              
            
          

Příklad použití conda:

            conda create -n myenv python=3.9
conda activate myenv

            

              
                Copy
              
            
          

2. Přesně specifikujte závislosti

Používejte omezení verzí ke specifikaci kompatibilních verzí vašich závislostí. Tím se zabrání neočekávanému chování způsobenému nekompatibilními aktualizacemi knihoven. Používejte nástroje jako pip-tools pro správu vašich závislostí.

Příklad specifikace závislostí:

            
requests >= 2.20.0, < 3.0.0

            

              
                Copy
              
            
          

3. Používejte konzistentní build systém

Vyberte si build systém (např. Setuptools, Poetry, Flit) a držte se ho. Tím se zajistí konzistentní sestavení napříč různými prostředími a zjednoduší se proces balíčkování.

4. Dokumentujte svůj balíček

Napište jasnou a stručnou dokumentaci pro svůj balíček. To pomůže uživatelům pochopit, jak balíček používat, a usnadní ostatním přispívat do vašeho projektu. Používejte nástroje jako Sphinx k generování dokumentace z vašeho kódu.

5. Používejte Continuous Integration (CI)

Nastavte systém CI (např. GitHub Actions, Travis CI, GitLab CI) pro automatické sestavování, testování a nasazování vašeho balíčku při každé změně vašeho kódu. Tím zajistíte, že váš balíček bude vždy v pracovním stavu.

Příklad konfigurace GitHub Actions:

            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. Publikujte svůj balíček na PyPI

Sdílejte svůj balíček se světem publikováním na Python Package Index (PyPI). To usnadňuje ostatním instalovat a používat váš balíček.

Kroky k publikování na PyPI:

1. Zaregistrujte si účet na PyPI a TestPyPI.
2. Nainstalujte twine: pip install twine.
3. Sestavte svůj balíček: poetry build nebo python setup.py sdist bdist_wheel.
4. Nahrajte svůj balíček na TestPyPI: twine upload --repository testpypi dist/*.
5. Nahrajte svůj balíček na PyPI: twine upload dist/*.

Příklady z praxe

Podívejme se, jak některé populární Python projekty používají pyproject.toml:

• Poetry: Používá pyproject.toml pro vlastní správu balíčků.
• Black: Neúprosný formátovač kódu také využívá pyproject.toml.
• FastAPI: Moderní, rychlý (vysoce výkonný) webový framework pro budování API s Pythonem jej také používá.

Závěr

pyproject.toml představuje moderní standard pro správu balíčků Pythonu, který nabízí deklarativní a bezpečný způsob definování metadat vašeho balíčku a správu závislostí. Zatímco setup.py nám dobře sloužil, migrace na pyproject.toml je cennou investicí do dlouhodobé udržitelnosti, konzistence a integrace s moderními nástroji. Přijetím osvědčených postupů a využitím správných nástrojů můžete zefektivnit svůj pracovní postup balíčkování Pythonu a vytvářet vysoce kvalitní, znovupoužitelné balíčky.

Další zdroje

• Průvodce uživatele pro balíčkování v Pythonu: Doporučení nástrojů
• Pip: Podpora pyproject.toml
• Poetry: Soubor pyproject.toml
• Setuptools: Použití pyproject.toml