Publikace Python-balíčku v PyPI s Poetry | Průvodce

Publikování Python balíčku na PyPI: automatizace procesu pomocí Poetry

Publikování vlastního Python balíčku v repozitáři PyPI je nezbytným krokem pro vývojáře, kteří usilují o opakované využití kódu. Nástroj Poetry tento proces výrazně zjednodušuje tím, že přebírá správu závislostí a sestavení artefaktů. V tomto návodu podrobně rozebereme přípravu projektu, nastavení prostředí a publikování balíčku, včetně práce s API tokeny a volitelnými závislostmi.

Příprava účtu a generování API tokenu

Prvním krokem je vytvoření účtu na oficiálních stránkách PyPI. Po registraci je nutné vygenerovat API token pro autentizaci při publikování. V osobním účtu přejděte do sekce API tokens a klikněte na tlačítko Generate API token. Zadejte název tokenu a vyberte rozsah působení. Pro nové projekty je vhodný token na úrovni účtu (Entire account), protože ještě nemáte žádné registrované balíčky. Důležité: zkopírujte vygenerovaný token hned po vytvoření – znovu se nezobrazí.

Postup generování zahrnuje:

• Autorizaci v účtu PyPI
• Přechod do sekce správy API tokens
• Zadání názvu tokenu a výběr scope
• Potvrzení vytvoření a uložení hodnoty tokenu

Tento token bude Poetry používat pro bezpečné publikování bez předávání přihlašovacího jména a hesla. Ukládejte ho na bezpečném místě, stejně jako heslo.

Inicializace projektu s Poetry

Vytvořte kořenovou složku projektu a nastavte virtuální prostředí:

python3 -m venv .venv
source .venv/bin/activate

Nainstalujte Poetry přes pip a spusťte inicializaci:

pip install poetry
poetry init

V interaktivním režimu zadejte základní parametry: název balíčku, verzi, popis, autora a podporovanou verzi Pythonu. Hlavní pole v generovaném souboru pyproject.toml:

• name — unikátní název balíčku v PyPI (může odpovídat snake_case názvu složky s kódem)
• version — sémantická verze balíčku
• python — rozsah podporovaných verzí interpretu
• readme — cesta k souboru s popisem
• packages — uvedení složky se zdrojovým kódem

Po inicializaci vytvořte složku pro kód (název se převede z name nahrazením pomlček podtržítky) a přidejte základní strukturu souborů.

Struktura projektu a konfigurace

Typická struktura projektu vypadá takto:

my-package/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
└── my_package/
    ├── __init__.py
    └── core.py

Je klíčové dodržet shodu mezi názvem balíčku v pyproject.toml a názvem složky s kódem. Například pro name = "my-package" musí být složka pojmenována my_package. V souboru __init__.py se doporučuje importovat hlavní funkce pro pohodlné použití.

Příklad implementace v core.py:

PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}'

Povinně přidejte soubor licence (ideálně MIT) a README.md s popisem funkcionality. Před publikováním zafixujte závislosti příkazem poetry lock.

Sestavení a publikování balíčku

Před odesláním do repozitáře sestavte artefakty:

poetry build

Tento příkaz vygeneruje source distribution (.tar.gz) a wheel soubor (.whl) ve složce dist/. Dále nastavte Poetry pro použití API tokenu:

poetry config pypi-token.pypi pypi-XXXXXXXX

Nahraďte pypi-XXXXXXXX svým tokenem. Nyní proveďte publikování:

poetry publish

Při úspěšné operaci uvidíte potvrzení nahrání na PyPI. Publikování můžete ověřit vyhledáním na stránkách PyPI nebo instalací balíčku lokálně:

pip install my-package

Práce s dodatečnými závislostmi

Pro realizaci volitelných komponent (instalovaných přes pip install package[extra]) nastavte pyproject.toml takto:

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

Zde je závislost pydantic označena jako volitelná přes optional = true, v sekci extras se vytváří skupina pydantic obsahující tuto knihovnu. Uživatelé budou moci nainstalovat dodatečné komponenty příkazem pip install my-package[pydantic].

Co je důležité

• Přísně dodržujte shodu mezi názvem balíčku v pyproject.toml a názvem složky s kódem (pomlčky → podtržítka)
• Vždy uveďte licenci a podrobný popis v README.md pro zvýšení důvěry uživatelů
• Používejte API tokeny místo přihlašovacího jména/hesla pro bezpečné publikování
• Pro volitelné závislosti správně nastavte sekce dependencies a extras
• Před publikováním ověřte správnost sestavení přes poetry build

— Editorial Team