Distribúcia Python balíčkov: Publikovanie na PyPI a správa verzií

Rozsiahly ekosystém Pythonu je poháňaný obrovskou zbierkou balíčkov, ktoré sú ľahko dostupné prostredníctvom Python Package Index (PyPI). Tento sprievodca poskytuje komplexný prehľad o tom, ako distribuovať vlastné Python balíčky cez PyPI, aby boli prístupné vývojárom po celom svete. Preskúmame základné nástroje, osvedčené postupy pre správu verzií a pracovné postupy pre vytváranie a publikovanie vysokokvalitných Python balíčkov.

Prečo distribuovať váš Python balíček?

Distribúcia vášho Python balíčka ponúka množstvo výhod:

• Zdieľanie vašej práce: Umožňuje ostatným vývojárom jednoducho opätovne použiť váš kód, čím podporuje spoluprácu a inovácie. Predstavte si globálny tím, ktorý používa vaše špecializované nástroje na analýzu dát vytvorené v Pythone.
• Správa závislostí: Zjednodušuje proces správy závislostí v iných projektoch. Váš balíček môže byť nainštalovaný jediným príkazom, spolu so všetkými jeho závislosťami.
• Príspevok do open-source: Umožňuje vám prispievať do open-source komunity a získať uznanie za vašu prácu. Mnoho kritických softvérových komponentov sú open-source balíčky udržiavané vývojármi z celého sveta.
• Kontrola verzií a aktualizácie: Poskytuje štruktúrovaný spôsob správy verzií, vydávania aktualizácií a opravy chýb. Tým sa zabezpečí, že používatelia majú vždy prístup k najnovšej a najspoľahlivejšej verzii vášho balíčka.
• Jednoduchá inštalácia: Zjednodušuje inštaláciu pre používateľov prostredníctvom pip install nazov-vasho-balicka.

Základné nástroje pre distribúciu Python balíčkov

Na vytváranie a distribúciu Python balíčkov je nevyhnutných niekoľko nástrojov:

• setuptools: Široko používaná knižnica na definovanie metadát balíčka, vrátane názvu, verzie, závislostí a vstupných bodov. Je to de facto štandard pre balíčkovanie Python projektov.
• wheel: Distribučný formát, ktorý poskytuje efektívnejší a spoľahlivejší proces inštalácie v porovnaní so zdrojovými distribúciami. Wheels sú predkompilované distribúcie, ktoré je možné nainštalovať bez nutnosti kompilácie.
• twine: Nástroj na bezpečné nahrávanie vášho balíčka na PyPI. Twine šifruje vaše prihlasovacie údaje a dáta balíčka počas prenosu, čím chráni pred odpočúvaním a útokmi typu man-in-the-middle.
• venv/virtualenv: Sú to nástroje na vytváranie izolovaných Python prostredí. Používanie virtuálnych prostredí je kľúčové pre správu závislostí a predchádzanie konfliktom medzi rôznymi projektmi.

Nastavenie vášho projektu

Predtým, ako budete môcť distribuovať svoj balíček, musíte správne štruktúrovať váš projekt.

Príklad štruktúry projektu

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

Vysvetlenie:

• my_package/: Hlavný adresár obsahujúci zdrojový kód vášho balíčka.
• my_package/__init__.py: Robí z adresára `my_package` Python balíček. Môže byť prázdny alebo obsahovať inicializačný kód.
• my_package/module1.py, my_package/module2.py: Vaše Python moduly obsahujúce skutočný kód.
• tests/: Adresár obsahujúci vaše jednotkové testy. Je kľúčové písať testy na zabezpečenie kvality a spoľahlivosti vášho balíčka.
• README.md: Markdown súbor poskytujúci popis vášho balíčka, návod na použitie a ďalšie relevantné informácie. Toto je často prvá vec, ktorú používatelia vidia na PyPI.
• LICENSE: Súbor obsahujúci licenciu, pod ktorou je váš balíček distribuovaný (napr. MIT, Apache 2.0, GPL). Výber vhodnej licencie je nevyhnutný na špecifikovanie, ako môžu ostatní používať váš kód.
• setup.py: Hlavný konfiguračný súbor, ktorý definuje metadáta a inštrukcie na zostavenie vášho balíčka.
• .gitignore: Špecifikuje súbory a adresáre, ktoré by mal Git ignorovať (napr. dočasné súbory, artefakty zostavenia).

Vytvorenie súboru `setup.py`

Súbor `setup.py` je srdcom distribúcie vášho balíčka. Obsahuje metadáta o vašom balíčku a pokyny na jeho zostavenie a inštaláciu. Tu je príklad:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # Nahraďte názvom vášho balíčka
    version="0.1.0",
    author="Vaše Meno",  # Nahraďte vaším menom
    author_email="vas.email@example.com", # Nahraďte vaším e-mailom
    description="Malý príkladový balíček",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # Nahraďte URL vášho repozitára
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # Príklad závislosti
    ],
)

Vysvetlenie:

• name: Názov vášho balíčka, ktorý bude použitý na PyPI. Vyberte jedinečný a popisný názov.
• version: Číslo verzie vášho balíčka. Riaďte sa sémantickým verziovaním (viď nižšie).
• author, author_email: Vaše meno a e-mailová adresa.
• description: Krátky popis vášho balíčka.
• long_description: Dlhší, podrobnejší popis, zvyčajne načítaný z vášho súboru `README.md`.
• long_description_content_type: Špecifikuje formát vášho dlhého popisu (napr. "text/markdown").
• url: URL domovskej stránky vášho balíčka (napr. GitHub repozitár).
• packages: Zoznam balíčkov, ktoré sa majú zahrnúť do vašej distribúcie. `setuptools.find_packages()` automaticky nájde všetky balíčky vo vašom projekte.
• classifiers: Metadáta, ktoré pomáhajú používateľom nájsť váš balíček na PyPI. Vyberte vhodné klasifikátory zo zoznamu Trove Classifiers. Zvážte zahrnutie klasifikátorov pre podporované verzie Pythonu, operačné systémy a licencie.
• python_requires: Špecifikuje minimálnu verziu Pythonu potrebnú na použitie vášho balíčka.
• install_requires: Zoznam závislostí, ktoré váš balíček vyžaduje. Tieto závislosti budú automaticky nainštalované pri inštalácii vášho balíčka.

Správa verzií: Sémantické verziovanie

Sémantické verziovanie (SemVer) je široko prijímaná schéma verziovania, ktorá poskytuje jasný a konzistentný spôsob komunikácie povahy zmien vo vašom balíčku.

Číslo verzie SemVer sa skladá z troch častí: MAJOR.MINOR.PATCH.

• MAJOR: Zvyšuje sa, keď urobíte nekompatibilné zmeny v API. Označuje to významnú zmenu, ktorá môže vyžadovať, aby používatelia aktualizovali svoj kód.
• MINOR: Zvyšuje sa, keď pridáte funkcionalitu spätne kompatibilným spôsobom. Znamená to nové funkcie alebo vylepšenia, ktoré neporušia existujúci kód.
• PATCH: Zvyšuje sa, keď urobíte spätne kompatibilné opravy chýb. Je to pre malé opravy, ktoré nepridávajú nové funkcie ani neporušujú existujúcu funkcionalitu.

Príklady:

• 1.0.0: Prvé vydanie.
• 1.1.0: Pridaná nová funkcia bez porušenia existujúceho kódu.
• 1.0.1: Opravená chyba vo vydaní 1.0.0.
• 2.0.0: Urobené nekompatibilné zmeny v API.

Používanie SemVer pomáha používateľom pochopiť dopad prechodu na novú verziu vášho balíčka.

Zostavenie vášho balíčka

Keď máte nakonfigurovaný súbor `setup.py`, môžete zostaviť svoj balíček.

1. Vytvorte virtuálne prostredie: Dôrazne sa odporúča vytvoriť virtuálne prostredie na izoláciu závislostí vášho balíčka. Použite `python3 -m venv .venv` (alebo `virtualenv .venv`) a potom ho aktivujte (`source .venv/bin/activate` na Linux/macOS, `.venv\Scripts\activate` na Windows).
2. Nainštalujte závislosti pre zostavenie: Spustite `pip install --upgrade setuptools wheel`.
3. Zostavte balíček: Spustite `python setup.py sdist bdist_wheel`. Tento príkaz vytvorí dva distribučné súbory v adresári `dist`: zdrojovú distribúciu (sdist) a wheel distribúciu (bdist_wheel).

`sdist` obsahuje váš zdrojový kód a súbor `setup.py`. `bdist_wheel` je predkompilovaná distribúcia, ktorú je možné nainštalovať rýchlejšie.

Publikovanie vášho balíčka na PyPI

Predtým, ako budete môcť publikovať svoj balíček, musíte si vytvoriť účet na PyPI (https://pypi.org/) a vytvoriť API token. Tento token sa použije na overenie vašich nahrávaní.

1. Zaregistrujte sa na PyPI: Prejdite na https://pypi.org/account/register/ a vytvorte si účet.
2. Vytvorte API token: Prejdite na https://pypi.org/manage/account/, posuňte sa nadol do sekcie "API tokens" a vytvorte nový token. Tento token si bezpečne uložte, pretože ho budete potrebovať na nahranie balíčka.
3. Nainštalujte Twine: Spustite `pip install twine`.
4. Nahrajte váš balíček: Spustite `twine upload dist/*`. Budete vyzvaní na zadanie používateľského mena (__token__) a hesla (API token, ktorý ste vytvorili).

Dôležitá bezpečnostná poznámka: Nikdy necommitujte váš API token do vášho repozitára. Uložte ho bezpečne a na prístup k nemu počas procesu nahrávania použite premenné prostredia alebo iné bezpečné metódy.

Testovanie inštalácie vášho balíčka

Po publikovaní vášho balíčka je nevyhnutné otestovať, či sa dá správne nainštalovať.

1. Vytvorte nové virtuálne prostredie: Tým sa zabezpečí, že testujete inštaláciu v čistom prostredí.
2. Nainštalujte váš balíček: Spustite `pip install nazov-vasho-balicka`.
3. Importujte a použite váš balíček: V interpreteri Pythonu importujte váš balíček a overte, či funguje podľa očakávania.

Kontinuálna integrácia a kontinuálne nasadenie (CI/CD)

Na automatizáciu procesu zostavovania, testovania a publikovania vášho balíčka môžete použiť nástroje CI/CD, ako sú GitHub Actions, GitLab CI alebo Travis CI.

Tu je príklad pracovného postupu GitHub Actions, ktorý zostavuje a publikuje váš balíček na PyPI:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build package
      run: python setup.py sdist bdist_wheel
    - name: Publish package to PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Vysvetlenie:

• Tento pracovný postup sa spustí, keď je na GitHube publikované nové vydanie.
• Načíta kód, nastaví Python, nainštaluje závislosti, zostaví balíček a nahrá ho na PyPI.
• secrets.PYPI_API_TOKEN je tajomstvo GitHubu, ktoré uchováva váš PyPI API token. Toto tajomstvo musíte nakonfigurovať v nastaveniach vášho GitHub repozitára.

Osvedčené postupy pre distribúciu Python balíčkov

• Píšte komplexnú dokumentáciu: Zahrňte podrobný súbor `README.md`, ako aj API dokumentáciu pomocou nástrojov ako Sphinx. Jasná a kompletná dokumentácia je kľúčová pre jednoduché používanie vášho balíčka.
• Píšte jednotkové testy: Dôkladne testujte svoj kód, aby ste zaistili jeho kvalitu a spoľahlivosť. Používajte testovací framework ako pytest alebo unittest.
• Dodržiavajte štýlové odporúčania PEP 8: Držte sa štýlového sprievodcu Python Enhancement Proposal 8 (PEP 8), aby ste zabezpečili konzistentný a čitateľný kód.
• Používajte licenciu: Vyberte si vhodnú open-source licenciu na špecifikovanie, ako môžu ostatní používať váš kód.
• Udržujte svoje závislosti aktuálne: Pravidelne aktualizujte závislosti vášho balíčka, aby ste mohli využívať opravy chýb, bezpečnostné záplaty a nové funkcie.
• Používajte virtuálne prostredie: Vždy vyvíjajte a testujte svoj balíček v rámci virtuálneho prostredia na izoláciu závislostí.
• Zvážte internacionalizáciu (i18n) a lokalizáciu (l10n): Ak váš balíček spracováva text alebo dáta určené pre používateľov, zvážte jeho prispôsobenie pre rôzne jazyky a regióny. Tým sa rozšíri vaša potenciálna používateľská základňa na celom svete. Nástroje ako Babel s tým môžu pomôcť.
• Spracovávajte rôzne časové pásma a meny: Ak váš balíček pracuje s dátumami, časmi alebo finančnými transakciami, dbajte na rôzne časové pásma a meny po celom svete. Používajte vhodné knižnice a API na správne zvládnutie týchto zložitostí.
• Poskytujte jasné chybové hlásenia: Píšte informatívne chybové hlásenia, ktoré používateľom pomôžu pochopiť, čo sa pokazilo a ako to opraviť. Ak je to možné, preložte tieto chybové hlásenia do rôznych jazykov.
• Myslite na prístupnosť: Pri navrhovaní rozhrania a dokumentácie vášho balíčka zvážte používateľov so zdravotným postihnutím. Dodržiavajte usmernenia pre prístupnosť, aby ste zabezpečili, že váš balíček bude použiteľný pre všetkých.

Pokročilé témy

• Namespace packages: Umožňujú rozdeliť jeden Python balíček do viacerých adresárov alebo dokonca viacerých distribúcií.
• Entry points: Umožňujú definovať funkcie alebo triedy, ktoré môžu byť volané z iných balíčkov alebo z príkazového riadku.
• Data files: Umožňujú zahrnúť do vašej distribúcie aj iné ako Python súbory (napr. dátové súbory, konfiguračné súbory).
• Conditional dependencies: Umožňujú špecifikovať závislosti, ktoré sú potrebné len za určitých podmienok (napr. na konkrétnom operačnom systéme).

Záver

Distribúcia vášho Python balíčka na PyPI je skvelý spôsob, ako zdieľať svoju prácu so svetom a prispieť do ekosystému Pythonu. Dodržiavaním krokov a osvedčených postupov uvedených v tomto sprievodcovi môžete vytvárať a publikovať vysokokvalitné Python balíčky, ktoré sa ľahko inštalujú, používajú a udržiavajú. Nezabudnite uprednostniť jasnú dokumentáciu, dôkladné testovanie a konzistentnú správu verzií, aby ste zabezpečili úspech vášho balíčka.