Podrobný návod na vytvorenie vášho prvého Python balíka

Vytvorenie Python modulu si vyžaduje viac než len písanie kódu. Moderný vývoj si žiada vhodné nástroje, štandardizované pracovné postupy a automatizáciu. V tejto príručke si prejdeme nastavenie robustného Python projektu, vrátane testovania, lintovania, CI/CD potrubí a publikovania na PyPI. Či už vyvíjate pomocnú knižnicu alebo rozsiahlu aplikáciu, tieto postupy zefektívnia váš pracovný postup a zabezpečia udržiavateľnosť.

Stručne

Tento článok prevedie Python vývojárov procesom vytvárania profesionálnych modulov tým, že pokryje základné kroky, ako je nastavenie štruktúry projektu s kľúčovými súbormi, automatizácia vývojových úloh, písanie unit testov pomocou pytest a bezpečné publikovanie balíka na PyPI prostredníctvom GitHub Actions. Dodržiavaním týchto osvedčených postupov môžu vývojári vytvárať robustné a zdieľateľné Python knižnice/moduly.

Nastavenie vášho vývojového prostredia

Predtým, ako sa ponoríte do vytvárania modulov, uistite sa, že máte na svojom vývojovom počítači nainštalovaný Python. Tu je stručný návod pre hlavné operačné systémy:

Prejdite na oficiálnu webovú stránku Pythonu: https://www.python.org/downloads/ (otvorí sa v novom okne)
Stiahnite si najnovšiu stabilnú verziu Python 3.13.3.

Windows

Spustite inštalátor a nezabudnite počas inštalácie začiarknuť možnosť Add Python to PATH. To vám umožní spúšťať príkazy Pythonu z príkazového riadka. Po inštalácii overte svoju inštaláciu pomocou príkazu python --version v PowerShell/CMD.

Inštalácia Chocolatey

Chocolatey zjednodušuje nastavenie vývoja v Pythone na Windowse tým, že poskytuje pohodlný spôsob inštalácie základných vývojových nástrojov.

Ak chcete nainštalovať Chocolatey, otvorte PowerShell ako správca a vykonajte uvedený inštalačný príkaz.

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('http://internal/odata/repo/ChocolateyInstall.ps1'))

Inštalácia Make na Windowse

Make inštalujeme pomocou Chocolatey pre jednoduchú, automatizovanú inštaláciu a správu nástroja make na Windowse.

choco install make

Linux

Debian/Ubuntu

sudo apt update
sudo apt install python3 python3-pip

Fedora/CentOS/RHEL

sudo dnf install python3 python3-pip

Arch Linux

sudo pacman -S python python-pip

macOS

macOS prichádza s predinštalovaným Pythonom, ale často ide o staršiu verziu. Odporúča sa nainštalovať novšiu verziu pomocou oficiálneho inštalátora alebo správcu balíkov, ako je Homebrew:

Použitie oficiálneho inštalátora: Prejdite na https://www.python.org/downloads/macos/ (otvorí sa v novom okne) a stiahnite si najnovšiu stabilnú verziu. Spustite inštalátor.

Použitie Homebrew (ak ho máte nainštalovaný)

brew update
brew install python@3

Možno budete musieť upraviť svoju premennú prostredia PATH, aby ste uprednostnili Python nainštalovaný cez Homebrew.

Základné vývojové nástroje

Nainštalujte ich globálne alebo vo virtuálnom prostredí:

pip install setuptools wheel flake8 pytest black pylint

Kľúčové balíky pre vývoj modulov

Na vytvorenie profesionálneho Python modulu budete potrebovať niekoľko základných balíkov:

setuptools: Je to široko používaná knižnica na balenie Python projektov. Poskytuje potrebné nástroje na definovanie vášho balíka a jeho metadát. Už ste ho špecifikovali ako váš build backend v pyproject.toml.
pytest: Výkonný a flexibilný testovací framework pre Python. Zjednodušuje písanie a spúšťanie testov. Váš Makefile už využíva pytest.
typing-extensions: Tento balík poskytuje backporty nových typových anotácií pre staršie verzie Pythonu. Váš pyproject.toml ho správne obsahuje ako podmienenú závislosť.
flake8: Wrapper okolo PyFlakes, pycodestyle a McCabe, používaný na lintovanie vášho kódu a zabezpečenie dodržiavania konvencií štýlu Pythonu (PEP 8). Váš Makefile používa flake8 na lintovanie.
black: Názorovo orientovaný formátovač kódu, ktorý automaticky formátuje váš kód do konzistentného štýlu. Hoci nie je striktne vyžadovaný, výrazne zlepšuje čitateľnosť kódu a znižuje diskusie o štýle. Váš Makefile obsahuje príkaz na formátovanie pomocou black.
pytest-cov: Plugin pre pytest na meranie pokrytia kódu testami. Váš Makefile ho používa na generovanie správ o pokrytí.

Štruktúra priečinkov projektu

Dobre definovaná štruktúra projektu je kľúčová pre udržiavateľnosť a spoluprácu. Tu je bežná a odporúčaná štruktúra pre Python modul:

    your_module_name/
      .github/
      └── workflows/
          ├── python-publish.yml
          └── tests.yml
      src/
      └── your_module_name/
          ├── __init__.py
          ├── core.py
      tests/
          ├── __init__.py
          ├── requirements.txt
          └── test_your_module_name.py
      .gitattributes
      .gitignore
      CHANGELOG.md
      LICENSE
      Makefile
      pyproject.toml
      README.md
      requirements.txt
      setup.py

Poďme si rozobrať každú zložku

.github/

Účel: Tento priečinok je špecifický pre GitHub a používa sa na konfiguráciu rôznych funkcií GitHubu pre váš repozitár.
Význam pre vývoj Python modulu: Je bežné používať GitHub na hostovanie zdrojového kódu vášho modulu, sledovanie problémov a správu príspevkov.

.github/workflows/

Účel: Tento podadresár v priečinku .github/ obsahuje súbory YAML, ktoré definujú automatizované pracovné postupy. Tieto pracovné postupy sa spúšťajú udalosťami vo vašom repozitári GitHub (napr. odoslanie kódu, otvorenie požiadaviek na zlúčenie).
Význam pre vývoj Python modulu: Tu definujete svoje potrubia Continuous Integration/Continuous Deployment (CI/CD).
- python-publish.yml: Tento pracovný postup pravdepodobne automatizuje proces publikovania vášho Python modulu do indexu balíkov, ako je PyPI (Python Package Index), keď vytvoríte novú verziu (napr. označíte commit). Môže zahŕňať zostavenie balíka, spustenie testov a následné nahranie na PyPI.
- tests.yml: Tento pracovný postup je zvyčajne nakonfigurovaný tak, aby automaticky spúšťal vaše testy vždy, keď sa do repozitára odošle kód alebo sa otvorí požiadavka na zlúčenie. To zaisťuje, že vaše zmeny kódu nezaviedli žiadne regresie. Môže tiež zahŕňať kontroly lintovania a formátovania.

src/

Účel: Tento priečinok je štandardným umiestnením pre skutočný zdrojový kód vášho modulu.
Význam pre vývoj Python modulu: Jasne oddeľuje logiku vášho modulu od ostatných súborov projektu, ako sú testy a dokumentácia.

src/your_module_name/

Účel: Tento podadresár, pomenovaný po vašom module, je skutočným Python balíkom.
Význam pre vývoj Python modulu: Táto štruktúra umožňuje čistejšie importy v rámci vášho projektu a keď používatelia inštalujú váš modul.
- __init__.py: Tento súbor robí z priečinka your_module_name Python balík. Môže byť prázdny alebo môže obsahovať kód na inicializáciu balíka alebo na sprístupnenie špecifických modulov alebo funkcií na najvyššej úrovni.
- core.py: Toto je príklad Python súboru obsahujúceho základnú logiku vášho modulu. Môžete tu mať viacero súborov .py, z ktorých každý je zodpovedný za rôzne aspekty funkčnosti vášho modulu.

tests/

Účel: Tento priečinok obsahuje vaše unit testy.
Význam pre vývoj Python modulu: Písanie komplexných testov je kľúčové pre zabezpečenie spoľahlivosti a správnosti vášho modulu.
- __init__.py: Podobne ako v priečinku src, aj tento súbor robí z priečinka tests Python balík, hoci sa menej často používa na inicializáciu v testovacích sadách.
- test_your_module_name.py: Toto je príklad testovacieho súboru. Obsahuje skutočné testovacie funkcie, ktoré overujú správanie kódu vo vašom priečinku src/your_module_name/. Zvyčajne by ste mali viacero testovacích súborov pokrývajúcich rôzne časti vášho modulu.
- requirements.txt (v priečinku tests/): Tento súbor obsahuje zoznam špecifických Python balíkov potrebných na spustenie vašich testov. Môžu sem patriť testovacie frameworky ako pytest, nástroje na pokrytie kódu ako pytest-cov a akékoľvek iné závislosti potrebné iba na testovacie účely. Toto je oddelené od hlavného súboru requirements.txt projektu.

.gitattributes

Účel: Tento súbor hovorí Gitu, ako má zaobchádzať s koncami riadkov a inými atribútmi súborov pre váš repozitár.
Význam pre vývoj Python modulu: Pomáha zabezpečiť konzistentnosť medzi rôznymi operačnými systémami (Windows, Linux, macOS), kde sa s koncami riadkov zaobchádza odlišne. Bežným zápisom je text=auto eol=lf na vynútenie koncoviek riadkov LF (Line Feed).

.gitignore

Účel: Tento súbor špecifikuje zámerne nesledované súbory, ktoré má Git ignorovať.
Význam pre vývoj Python modulu: Zabraňuje odoslaniu do vášho repozitára dočasných súborov, artefaktov zostavenia, konfigurácií špecifických pre prostredie (ako sú priečinky virtuálneho prostredia) a iných nepotrebných súborov.

CHANGELOG.md

Účel: Tento súbor zaznamenáva zmeny vykonané v každej verzii vášho modulu.
Význam pre vývoj Python modulu: Je nevyhnutné, aby používatelia pochopili, čo je nové, vylepšené alebo opravené v každej verzii. Odporúča sa dodržiavať štandard, ako je Keep a Changelog.

LICENSE

Účel: Tento súbor obsahuje licenciu, pod ktorou je váš modul distribuovaný.
Význam pre vývoj Python modulu: Výberom open-source licencie jasne definujete podmienky používania, úprav a distribúcie vášho modulu pre ostatných.

Makefile

Účel: Tento súbor automatizuje bežné vývojové úlohy pomocou nástroja make.
Význam pre vývoj Python modulu: Ako bolo uvedené v predchádzajúcom článku, poskytuje pohodlný spôsob spúšťania testov, lintovania kódu, formátovania kódu, zostavovania balíka a vykonávania iných opakujúcich sa úloh pomocou jednoduchých príkazov.

pyproject.toml

Účel: Tento súbor špecifikuje požiadavky na systém zostavenia pre Python projekty, ako je definované v PEP 518.
Význam pre vývoj Python modulu: Je to moderný štandard pre správu metadát projektu, závislostí zostavenia a voliteľných závislostí. Pri použití s backendom zostavenia, ako je setuptools, nahrádza potrebu samostatného súboru setup.py v mnohých prípadoch.

README.md

Účel: Tento súbor poskytuje prehľad vášho modulu, vrátane jeho účelu, pokynov na inštaláciu, príkladov použitia a akýchkoľvek iných relevantných informácií.
Význam pre vývoj Python modulu: Je to prvý kontaktný bod pre používateľov a prispievateľov, ktorý poskytuje základné informácie o vašom module.

requirements.txt (na koreňovej úrovni)

Účel: Tento súbor obsahuje zoznam závislostí vášho Python modulu pri spustení.
Význam pre vývoj Python modulu: Keď používatelia inštalujú váš modul pomocou príkazu pip install your_module_name, pip použije tento súbor na inštaláciu potrebných závislostí. Hoci pyproject.toml je moderný prístup na deklarovanie závislostí, requirements.txt sa stále bežne používa, najmä na špecifikovanie presných verzií pre reprodukovateľnosť. Môžete ho vygenerovať z vášho vývojového prostredia alebo ho udržiavať spolu s vaším pyproject.toml.

setup.py

Účel: Historicky sa tento súbor používal na definovanie spôsobu inštalácie a distribúcie vášho modulu pomocou setuptools.
Význam pre vývoj Python modulu: Hoci pyproject.toml je odporúčaný moderný prístup, setup.py je stále prítomný v mnohých projektoch, najmä v tých, ktoré ešte neboli úplne migrované. Často funguje v spojení s pyproject.toml, keď je setuptools špecifikovaný ako backend zostavenia.

Toto podrobné rozdelenie by vám malo poskytnúť jasné pochopenie účelu a významu každej zložky v tomto dobre štruktúrovanom projekte Python modulu. Táto štruktúra podporuje organizáciu, udržiavateľnosť a spoluprácu.

Automatizácia úloh pomocou `Makefile`

Makefile je súbor používaný nástrojom make, čo je nástroj príkazového riadka, ktorý automatizuje procesy zostavenia. Vo vývoji softvéru je bežné mať sériu úloh, ktoré je potrebné opakovane vykonávať, ako napríklad spúšťanie testov, lintovanie kódu, formátovanie, vytváranie dokumentácie alebo inštalácia softvéru. Makefile definuje tieto úlohy ako "ciele" a špecifikuje príkazy potrebné na vykonanie každého cieľa. To poskytuje niekoľko výhod:

Automatizácia: Automatizuje opakujúce sa úlohy, čím šetrí vývojárom čas a znižuje pravdepodobnosť chýb.
Konzistentnosť: Zabezpečuje, že tieto úlohy sa vykonávajú konzistentne pri každom spustení.
Efektívnosť: make je dostatočne inteligentný na to, aby znovu vykonal úlohy iba vtedy, keď sa zmenili ich závislosti, čím sa proces stáva efektívnejším.
Dokumentácia: Samotný Makefile slúži ako forma dokumentácie, ktorá načrtáva bežné vývojové príkazy pre projekt.

Príklad `Makefile`

.PHONY: test lint format install uninstall coverage help

# Predvolený cieľ pri spustení iba 'make'
help:
  @echo "Dostupné príkazy:"
  @echo "  make test         - Spustenie všetkých testov"
  @echo "  make lint         - Spustenie kontrol lintovania"
  @echo "  make format       - Formátovanie kódu pomocou Black (ak je nainštalovaný)"
  @echo "  make coverage     - Generovanie správy o pokrytí testami"
  @echo "  make install      - Inštalácia balíka"
  @echo "  make uninstall    - Odinštalovanie balíka"
  @echo "  make check        - Spustenie lintovania a testov"

test:
  pytest tests/

lint:
  flake8 src/ tests/

format:
  black src/ tests/ || echo "Black nie je nainštalovaný. Spustite 'pip install black' pre povolenie formátovania."

coverage:
  pytest --cov=<your_module_name> tests/ --cov-report=term --cov-report=html
  @echo "HTML správa o pokrytí bola vygenerovaná v priečinku htmlcov/"

install:
  pip install .

uninstall:
  pip uninstall -y <your_module_name>

check: lint test

Vysvetlenie príkazov

.PHONY: test lint format install uninstall coverage help: Tento riadok deklaruje, že uvedené ciele nie sú skutočné súbory, ale príkazy, ktoré sa majú vykonať.
help: Toto je predvolený cieľ. Spustenie príkazu make bez akýchkoľvek argumentov vykoná tento príkaz a zobrazí užitočný zoznam dostupných príkazov.
test: Spustí vaše unit testy pomocou pytest.
lint: Vykoná statickú analýzu kódu pomocou flake8 na identifikáciu potenciálnych problémov so štýlom a chýb.
format: Automaticky naformátuje váš kód tak, aby dodržiaval konzistentný štýl pomocou black. Časť || echo ... zabezpečuje, že ak black nie je nainštalovaný, príkaz nezlyhá, ale namiesto toho vypíše užitočnú správu.
coverage: Spustí testy s analýzou pokrytia pomocou pytest-cov. Generuje terminálovú správu aj HTML správu v priečinku htmlcov/, ktorá zobrazuje, ktoré časti vášho kódu sú pokryté testami.
install: Nainštaluje váš modul pomocou pip. Znak . odkazuje na aktuálny priečinok, kde sa nachádza súbor setup.py (alebo pyproject.toml s inštrukciami na zostavenie).
uninstall: Odinštaluje váš modul pomocou pip. Prepínač -y automaticky potvrdí odinštaláciu.
check: Postupne spustí príkazy lint a test, čím zabezpečí, že váš kód je štylisticky správny a prejde všetkými testami.

Ak chcete použiť tento Makefile, musíte mať na svojom systéme nainštalovaný nástroj make. Zvyčajne je predvolene dostupný na systémoch Linux a macOS. Pre Windows možno budete musieť nainštalovať balík nástrojov na zostavenie.

Správa metadát projektu pomocou `pyproject.toml`

Súbor pyproject.toml je moderný štandard pre špecifikáciu požiadaviek na systém zostavenia a metadát projektu pre Python projekty, ako je definované v PEP 518. Slúži ako centrálny konfiguračný súbor, ktorý nástrojom na zostavenie, ako sú pip a build, hovorí, ako zostaviť váš projekt a aké má závislosti. To ponúka niekoľko výhod:

Štandardizácia: Poskytuje štandardizovaný spôsob konfigurácie Python projektov, čo uľahčuje rôznym nástrojom ich pochopenie a prácu s nimi.
Správa závislostí: Umožňuje deklarovať závislosti počas zostavenia aj behu v jednom súbore.
Špecifikácia backendu zostavenia: Špecifikuje, ktorý backend zostavenia (napr. setuptools, poetry-core) sa má použiť na zostavenie vášho projektu.
Ukladanie metadát: Centralizuje metadáta projektu, ako je názov, verzia, autori, licencia a ďalšie.
Rozšíriteľnosť: Podporuje ďalšie konfiguračné sekcie pre rôzne nástroje, ako sú lintery a formátovače.

Príklad obsahu `pyproject.toml`

[project]
authors = [
    {name = "your_name", email = "your_email"},
]
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Developers",
    "Intended Audience :: Information Technology",
    "Natural Language :: English",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Topic :: Software Development :: Libraries",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: Text Processing :: General",
    "Typing :: Typed",
    "Framework :: Pytest",
]
dependencies = [
    "typing-extensions>=4.0.0; python_version<'3.11'",
]
description = "<your_project_description>"
keywords = []
license = {text = "<your_license>"}
maintainers = [
    {name = "your_name", email = "your_email"},
]
name = "<your_module_name>"
readme = "README.md"
requires-python = ">=3.10"
version = "1.0.0"

[project.urls]
"Bug Tracker" = "https://github.com/.../<your_module_name>/issues"
"Change Log" = "https://github.com/.../<your_module_name>/blob/main/CHANGELOG.md"
"Github" = "https://github.com/.../<your_module_name>"
"Homepage" = "https://github.com/.../<your_module_name>"

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools>=65.0.0", "wheel"]

[project.optional-dependencies]
test = [
    "pytest>=8.3.0",
    "pytest-cov>=4.1.0",
    "flake8>=7.0.0",
]

Vysvetlenie kľúčových sekcií

[project]: Obsahuje základné metadáta projektu, ako je názov, verzia, autori, popis, licencia, závislosti a ďalšie.
[project.urls]: Poskytuje odkazy na relevantné zdroje projektu.
[build-system]: Špecifikuje backend zostavenia a jeho požiadavky.
[project.optional-dependencies]: Definuje voliteľné závislosti, často používané pre vývoj alebo testovanie.

Používaním súboru pyproject.toml prijímate modernejší a štandardizovanejší prístup k správe konfigurácie vášho Python projektu.

Písanie robustného kódu pomocou unit testov s využitím `pytest`

Vytvorenie spoľahlivého Python modulu si vyžaduje dôkladné testovanie. Unit testy sa zameriavajú na overenie funkčnosti jednotlivých komponentov vášho kódu, čím zabezpečujú, že sa správajú podľa očakávania za rôznych podmienok. pytest je populárny a výkonný testovací framework, ktorý zjednodušuje proces písania a spúšťania unit testov v Pythone.

Pozrime sa na praktický príklad použitia pytest na základe vášho poskytnutého testovacieho kódu:

import pytest

class TestMyModuleFunction:
    def test_should_return_five(self):
        assert my_add_function(2, 3) == 5

Spúšťanie vašich testov

Ak chcete spustiť tieto testy pomocou pytest, zvyčajne prejdete do koreňového priečinka vášho projektu v termináli a vykonáte príkaz:

make test

Ako je definované vo vašom Makefile, tento príkaz inštruuje pytest, aby vyhľadal a spustil všetky testovacie súbory (zvyčajne pomenované tak, že začínajú na test_ a nachádzajú sa v priečinku tests). pytest potom poskytne súhrn výsledkov testov, ktorý indikuje, ktoré testy prešli a ktoré zlyhali.

Výhody unit testovania

Skoré odhalenie chýb: Písanie testov vám pomáha identifikovať a opraviť chyby v skorých fázach vývoja, predtým ako sa stanú zložitejšími a ťažšie sledovateľnými.
Istota v kóde: Komplexná sada unit testov vám dáva istotu, že váš kód funguje správne a že zmeny, ktoré v budúcnosti vykonáte, nezavedú žiadne regresie.
Živá dokumentácia: Vaše testy slúžia ako forma dokumentácie, ktorá ilustruje, ako sa majú rôzne časti vášho modulu používať.
Vylepšený návrh: Proces písania testov vás často núti dôkladnejšie premýšľať o návrhu vášho kódu, čo vedie k modulárnejším a testovateľnejším komponentom.

Začlenením unit testovania pomocou pytest do vášho pracovného postupu vývoja Python modulu môžete výrazne zlepšiť kvalitu a spoľahlivosť vášho kódu. Nezabudnite písať testy pre rôzne scenáre, vrátane bežných prípadov, okrajových prípadov a potenciálnych chybových stavov.

Publikovanie vášho Python balíka na PyPI

Keď vytvoríte dobre štruktúrovaný a dôkladne otestovaný Python modul, ďalším logickým krokom je zdieľať ho so širšou Python komunitou publikovaním na Python Package Index (PyPI). To umožňuje ostatným vývojárom jednoducho nainštalovať a používať váš modul vo svojich projektoch. Tu je návod, ako sprístupniť váš balík na PyPI:

Predtým, ako sa pustíte do procesu publikovania, uistite sa, že vaše lokálne prostredie je v poriadku:

Formátujte svoj kód: Spustite make format, aby ste zabezpečili, že váš kód dodržiava konzistentné štýlové pravidlá.
Lintujte svoj kód: Vykonajte make lint, aby ste zachytili akékoľvek potenciálne štylistické problémy alebo chyby.
Spustite unit testy: Overte funkčnosť vášho modulu spustením make test. Všetky testy by mali pred pokračovaním prejsť.
Odošlite zmeny na GitHub: Potvrďte všetky svoje zmeny a odošlite ich do svojho vzdialeného repozitára GitHub.

Príprava na publikovanie na PyPI

Registrácia na PyPI: Ak ste to ešte neurobili, vytvorte si účet na oficiálnej webovej stránke PyPI: https://pypi.org (otvorí sa v novom okne)

Nastavenie autentifikácie pomocou API tokenu

Ak chcete používať API tokeny na publikovanie z vášho pracovného postupu GitHub Actions, budete musieť vytvoriť API token na PyPI a bezpečne ho uložiť ako tajomstvo vo vašom repozitári GitHub:

Generovanie API tokenu na PyPI

Setting Up API Token Authentication

Prihláste sa do svojho účtu PyPI na https://pypi.org (otvorí sa v novom okne).
Prejdite do nastavení svojho účtu https://pypi.org/manage/account (otvorí sa v novom okne).
Vyhľadajte sekciu API tokens.
Kliknite na Add API token.
Vyplňte pole Token name.
Vyberte rozsah platnosti tokenu. Pre publikovanie zvyčajne vyberiete rozsah pre váš konkrétny projekt alebo "Entire account", ak plánujete publikovať viacero balíkov.
Kliknite na "Create token".

Dôležité: Skopírujte vygenerovaný token a okamžite ho uložte na bezpečné miesto. Už ho nebudete môcť znova zobraziť.

Pridanie API tokenu ako tajomstva repozitára GitHub

Add the API Token as a GitHub Repository Secret

Prejdite do svojho repozitára GitHub pre váš Python modul.
V hornej časti stránky prejdite na Settings.
V ľavom bočnom paneli kliknite na Secrets and variables a potom na Actions.
Kliknite na sekciu Repository secrets.
Kliknite na zelené tlačidlo New repository secret.
Do poľa Name zadajte PYPI_API_TOKEN.
Do poľa Secret vložte API token, ktorý ste skopírovali z PyPI.
Kliknite na zelené tlačidlo Add secret.

Teraz, keď ste uložili svoj API token PyPI ako tajomstvo vo vašom repozitári GitHub, váš pracovný postup GitHub Actions ho môže použiť na autentifikáciu s PyPI počas procesu nahrávania balíka. Budete musieť zabezpečiť, aby bol váš pracovný postup python-publish.yml nakonfigurovaný na používanie tohto tajomstva na autentifikáciu namiesto spoliehania sa výlučne na nastavenie dôveryhodného vydavateľa (alebo ako alternatívna metóda).

Nastavenie publikovania balíka na PyPI

Toto musíte nakonfigurovať vo svojom účte PyPI:

Prihláste sa do svojho účtu PyPI na https://pypi.org (otvorí sa v novom okne).
Prejdite do nastavení Trusted Publisher Management https://pypi.org/manage/account/publishing (otvorí sa v novom okne).
Nájdite sekciu Add a new pending publisher.
Vyplňte formulár s podrobnosťami o vašom projekte a odošlite ho. Týmto prepojíte váš projekt PyPI s vaším repozitárom GitHub a špecifikovaným pracovným postupom.
- PyPI Project Name (required): your_module_name (Toto by sa malo zhodovať s poľom name vo vašom súbore pyproject.toml).
- Owner (required): Názov vašej organizácie GitHub alebo vaše používateľské meno GitHub, ktoré vlastní repozitár.
- Repository name (required): Názov vášho repozitára GitHub (napr. your_module_name).
- Workflow name (required): python-publish.yml (Toto je názov súboru vášho pracovného postupu publikovania v priečinku .github/workflows/ vášho repozitára GitHub).
- Environment name (optional): Tu môžete zadať názov prostredia GitHub Actions, ak ste si ho nakonfigurovali pre publikovanie v nastaveniach vášho repozitára. Používanie vyhradeného prostredia na publikovanie sa dôrazne odporúča pre zvýšenú bezpečnosť.

Záverečné kroky na vydanie vášho Python modulu

Po dokončení nastavenia PyPI a GitHubu je následný proces publikovania automatizovaný prostredníctvom GitHub Actions. Ak chcete iniciovať vydanie:

Odošlite svoj projekt na GitHub: Uistite sa, že všetky lokálne zmeny sú potvrdené a odoslané do vášho vzdialeného repozitára GitHub.
Vytvorte novú verziu: Vo svojom repozitári GitHub vytvorte novú verziu. Táto akcia slúži ako spúšťač pre váš nakonfigurovaný pracovný postup GitHub Actions (napr. python-publish.yml).

Po vytvorení novej verzie GitHub Actions automaticky vykoná pracovný postup publikovania. Tento pracovný postup zvyčajne vykoná úlohy, ako je zostavenie vášho balíka, a ak prejdú všetky definované kontroly (vrátane testov) a súbor pyproject.toml je úspešne overený pomocou PyPI, prejde k nahraniu novo vytvorenej verzie vášho balíka na PyPI.

Po úspešnom dokončení pracovného postupu GitHub Actions bude váš Python balík verejne prístupný na PyPI. Vývojári si ho potom môžu nainštalovať pomocou štandardného príkazu pip:

pip install your_module_name

Váš publikovaný balík nájdete na PyPI na nasledujúcej URL adrese: https://pypi.org/project/your_module_name/ (nahraďte your_module_name skutočným názvom vášho modulu).

Osvedčené postupy

Verzovanie: Používajte sémantické verzovanie v súbore pyproject.toml.
Dokumentácia: Udržiavajte súbory README.md a CHANGELOG.md aktualizované.
Testovanie: Pred odoslaním zmien spustite make check (lint + test).

Záver

Vytvorenie profesionálneho Python modulu zahŕňa viac než len písanie kódu. Dodržiavaním dobre definovanej štruktúry projektu, automatizáciou úloh pomocou nástrojov ako make, správou metadát pomocou pyproject.toml a využívaním základných vývojových balíkov môžete vytvárať robustné, udržiavateľné a ľahko zdieľateľné Python moduly, ktoré budú prínosom pre vaše vlastné projekty aj pre širšiu Python komunitu. Osvojte si tieto postupy a posuniete svoje vývojárske zručnosti v jazyku Python na vyššiu úroveň a vytvoríte trvalý vplyv svojim kódom.

Otázky

Dobre definovaná štruktúra projektu zlepšuje organizáciu, udržiavateľnosť a prehľadnosť. Oddelenie zdrojového kódu do priečinka src/ zabraňuje problémom s importom a uľahčuje balenie, zatiaľ čo vyhradený priečinok tests/ udržuje testovací kód oddelený od hlavnej logiky.

Súbor Makefile automatizuje bežné vývojové úlohy, ako je spúšťanie tests, linting, formatting, installing a uninstalling balíka, čím šetrí čas a zabezpečuje konzistentnosť v rámci projektu.

pyproject.toml je moderný štandard pre metadáta projektu a konfiguráciu systému zostavenia. Často nahrádza súbor setup.py. Súbor requirements.txt primárne obsahuje zoznam závislostí pri behu, zatiaľ čo pyproject.toml môže špecifikovať aj závislosti pri zostavení.

Unit testy overujú funkčnosť jednotlivých častí vášho kódu, pomáhajú odhaliť chyby v skorých fázach, zvyšujú istotu v kóde, slúžia ako dokumentácia a zlepšujú celkový návrh vášho modulu.

Pomocou testovacieho frameworku, ako je pytest, môžete zvyčajne spustiť testy tak, že prejdete do koreňového priečinka projektu v termináli a vykonáte príkaz ako make test (ak je nakonfigurovaný súbor Makefile) alebo priamo pomocou pytest tests/.

Článok načrtáva dve hlavné metódy: použitie mechanizmu dôveryhodného vydavateľa PyPI s GitHub Actions a použitie API tokenov PyPI na autentifikáciu v rámci pracovného postupu GitHub Actions.

API token PyPI (otvorí sa v novom okne) je bezpečná alternatíva k používaniu vášho hesla na nahrávanie balíkov. Ponúka podrobnejšiu kontrolu a v prípade kompromitácie ho možno odvolať, čím sa zvyšuje bezpečnosť vášho účtu PyPI.

Použitím GitHub Actions (otvorí sa v novom okne) môžete vytvoriť pracovný postup, ktorý automaticky zostaví, otestuje a publikuje váš balík na PyPI vždy, keď vo vašom repozitári GitHub vytvoríte novú verziu. To výrazne zefektívňuje proces vydania.

Autor článku Zsolt Oroszlány

Vedúci kreatívnej agentúry Playful Sparkle prináša viac ako 20 rokov skúseností v oblasti grafického dizajnu a programovania. Vedie inovatívne projekty a svoj voľný čas trávi cvičením, pozeraním filmov a experimentovaním s novými funkciami CSS. Zsoltovo oddanie práci a záľubám je hnacou silou jeho úspechu v kreatívnom priemysle.