Publikacja pakietu Python w PyPI za pomocą Poetry | Przewodnik

# Publikacja pakietu Python w PyPI: automatyzacja procesu za pomocą Poetry

Publikacja własnego pakietu Python w repozytorium PyPI to obowiązkowy etap dla programistów dążących do ponownego wykorzystania kodu. Narzędzie Poetry znacznie ułatwia ten proces, przejmując zarządzanie zależnościami i budowanie artefaktów. W tym przewodniku szczegółowo omówimy przygotowanie projektu, konfigurację środowiska i publikację pakietu, w tym pracę z tokenami API i opcjonalnymi zależnościami.

Przygotowanie konta i generowanie tokenu API

Pierwszym krokiem jest utworzenie konta na oficjalnej stronie PyPI. Po rejestracji należy wygenerować token API do uwierzytelniania podczas publikacji. W panelu użytkownika przejdź do sekcji API tokens i kliknij przycisk Generate API token. Podaj nazwę tokenu i wybierz zakres działania. Dla nowych projektów nadaje się token na poziomie konta (Entire account), ponieważ nie masz jeszcze zarejestrowanych pakietów. Ważne: skopiuj wygenerowany token natychmiast po utworzeniu — nie zostanie wyświetlony ponownie.

Procedura generowania obejmuje:

• Uwierzytelnienie w koncie PyPI
• Przejście do sekcji zarządzania tokenami API
• Podanie nazwy tokenu i wybór zakresu
• Potwierdzenie utworzenia i zapisanie wartości tokenu

Ten token zostanie użyty przez Poetry do bezpiecznej publikacji bez przekazywania loginu i hasła. Przechowuj go w bezpiecznym miejscu, podobnie jak hasło.

Inicjalizacja projektu za pomocą Poetry

Utwórz katalog główny projektu i skonfiguruj środowisko wirtualne:

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

Zainstaluj Poetry za pomocą pip i uruchom inicjalizację:

pip install poetry
poetry init

W trybie interaktywnym podaj podstawowe parametry: nazwę pakietu, wersję, opis, autora i obsługiwaną wersję Pythona. Główne pola w generowanym pliku pyproject.toml:

• name — unikalna nazwa pakietu w PyPI (musi odpowiadać snake_case nazwy katalogu z kodem)
• version — semantyczna wersja pakietu
• python — zakres obsługiwanych wersji interpretera
• readme — ścieżka do pliku z opisem
• packages — wskazanie katalogu z kodem źródłowym

Po inicjalizacji utwórz katalog na kod (nazwa jest przekształcana z name poprzez zamianę myślników na podkreślenia) i dodaj podstawową strukturę plików.

Struktura projektu i konfiguracja

Typowa struktura projektu wygląda następująco:

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

Krytycznie ważne jest zachowanie zgodności między nazwą pakietu w pyproject.toml a nazwą katalogu z kodem. Na przykład dla name = "my-package" katalog musi nazywać się my_package. W pliku __init__.py zaleca się importowanie głównych funkcji dla wygody użycia.

Przykład implementacji w core.py:

PREPEND_STR = 'prepend_'

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

Obowiązkowo dodaj plik licencji (najlepiej MIT) i README.md z opisem funkcjonalności. Przed publikacją utwórz lockfile zależności poleceniem poetry lock.

Budowa i publikacja pakietu

Przed wysłaniem do repozytorium zbuduj artefakty:

poetry build

To polecenie wygeneruje source distribution (.tar.gz) i plik wheel (.whl) w katalogu dist/. Następnie skonfiguruj Poetry do użycia tokenu API:

poetry config pypi-token.pypi pypi-XXXXXXXX

Zastąp pypi-XXXXXXXX swoim tokenem. Teraz wykonaj publikację:

poetry publish

Po udanej operacji zobaczysz potwierdzenie wgrania do PyPI. Publikację możesz sprawdzić przez wyszukiwanie na stronie PyPI lub instalując pakiet lokalnie:

pip install my-package

Praca z dodatkowymi zależnościami

Aby zaimplementować opcjonalne komponenty (instalowane przez pip install package[extra]), skonfiguruj pyproject.toml w następujący sposób:

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

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

Tutaj zależność pydantic jest oznaczona jako opcjonalna przez optional = true, a w sekcji extras tworzona jest grupa pydantic obejmująca tę bibliotekę. Użytkownicy będą mogli zainstalować dodatkowe komponenty poleceniem pip install my-package[pydantic].

Co ważne

• Ściśle przestrzegaj zgodności między nazwą pakietu w pyproject.toml a nazwą katalogu z kodem (myślniki → podkreślenia)
• Zawsze podawaj licencję i szczegółowy opis w README.md, aby zwiększyć zaufanie użytkowników
• Używaj tokenów API zamiast loginu/hasła do bezpiecznej publikacji
• Dla opcjonalnych zależności poprawnie konfiguruj sekcje dependencies i extras
• Przed publikacją sprawdzaj poprawność budowy przez poetry build

— Editorial Team