Python to język programowania, który pozwala pracować szybciej i skuteczniej integrować systemy. Przyciąga nowych użytkowników, jak również osoby doświadczone z programowaniem, swoją prostotą i przejrzystością, ale też możliwościami oraz ogromną społecznością. Niezależnie od stopnia zaawansowania, każdy projekt potrzebuje początkowej konfiguracji, dzięki której będziemy mogli spokojnie przejść do tego, co wszyscy lubimy najbardziej – kodowania.
W artykule przyjrzyjmy się, gdzie w całym tym zamieszaniu wpasowuje się Poetry i dlaczego uważane jest za przyszłość (bądź może teraźniejszość?) w Pythonie.
Dlaczego Poetry?
Zewnętrzne zależności (paczki), wirtualne środowisko czy też mechanizm tworzenia i udostępniania własnych paczek. Każdy z tych procesów ma własne narzędzie, stworzone tylko do tego celu.
Każdy programista Pythona na pewnym etapie używał narzędzia o nazwie „pip” (Python Package Installer). Pozwala ono na instalację zewnętrznych paczek za pomocą prostych komend. Najczęściej spotykanym rozwiązaniem jest agregowanie wszystkich zależności w jednym pliku – requirements.txt. Dzięki temu możemy jedną komendą instalować wiele paczek na raz.
Kolejnym znanym i rekomendowanym narzędziem jest Virtualenv, które służy do izolowania środowisk. W ten sposób możemy dysponować wieloma niezależnymi środowiskami, bez ryzyka zaśmiecana głównej instalacji Pythona.
Dwa wymienione wyżej narzędzia w wielu przypadkach są wystarczające na początkowym etapie projektu. A co, jeżeli chcielibyśmy utworzyć paczkę ze swoim kodem i udostępnić ją innym osobom?
Z tym może pomóc następne mechanizm – setuptools, które ułatwia proces pakowania projektów i wysyłania ich do repozytorium PyPi (Python Package Index).
Wróćmy zatem do pytania zadanego we wstępie artykułu: gdzie w tym wszystkim pasuje Poetry? Odpowiedź jest prosta – wszędzie! Jest tym jednym narzędziem, które łączy je wszystkie. Ma ogrom (i nawet więcej) funkcjonalności oprogramowań opisanych wyżej. Stare porzekadło mówi: „jeśli coś jest do wszystkiego, to jest do niczego”. Na szczęście nie w tym przypadku.
Poetry jest narzędziem do zarządzania zależnościami (nie tylko paczkami!). Kieruje nimi (instaluje, aktualizuje i usuwa) i potrafi budować zasoby do dystrybucji. A to wszystko zapakowane w jedno, proste i przejrzyste oprogramowanie.
Pierwsze kroki z Poetry
Przygodę z Poetry należy zacząć od jego instalacji prostą, pojedynczą komendą:
curl -sSL https://install.python-poetry.org | python3 -
Powyższa komenda jest przeznaczona dla systemów Linux, macOS i Windows (WSL). Wersja dla Windows Powershell:
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
Jest to oficjalny skrypt, który instaluje Poetry w prywatnym, wirtualnym środowisku Pythona.
Po instalacji powinniśmy sprawdzić, czy cały proces przebiegł pomyślnie:
poetry --version
Jeżeli widzisz komunikat podobny do „Poetry (version 1.2.0)”, to instalacja powiodła się i jesteśmy przygotowani do dalszej eksploracji.
Kolejnym etapem jest stworzenie szkieletu projektu:
poetry new poetry-demo
Wynikiem będzie utworzenie katalogu o poniższej strukturze:
poetry-demo
├── pyproject.toml
├── README.md
├── poetry_demo
│ └── __init__.py
└── tests
└── __init__.pyJeżeli masz już swój projekt i jedynie chcesz zainicjować w nim Poetry:
cd pre-existing-project poetry init
Pyproject.toml
Kluczowym plikiem jest pyproject.toml. To w nim zarządzamy swoim projektem i zależnościami. Obecnie wygląda tak:
[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = []
readme = "README.md"
packages = [{include = "poetry_demo"}]
[tool.poetry.dependencies]
python = "^3.11"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"Poetry zakłada, że główny katalog wewnątrz projektu będzie nazwany tak samo jak w tool.poetry.name. Jeżeli tak nie jest, należy wypełnić pole tool.poetry.packages (tak jak w przykładzie powyżej).
W projektach czasami można spotkać się z tradycyjnym plikiem Manifest.in. Poetry zastępuje go poprzez pola tool.poetry.readme, tool.poetry.include i tool.poetry.exclude. Dodatkowo wymagane jest dokładne określenie wersji Pythona używanej w tym projekcie. Domyślnie ta wartość jest uzupełniana od wersji języka, na której zainstalowane jest Poetry.
Wszystkie zależności uzupełniamy w sekcji tool.poetry.dependencies. Można to zrobić na dwa sposoby:
- Ręczne wpisanie kolejnych dependencji do pliku:
[tool.poetry.dependencies] pendulum = "^2.1" pytest = "==7.4.0"
Po dopisaniu do pliku konieczne będzie ręczne zaktualizowanie środowiska (omówione w dalszej części artykułu).
- Użycie komendy add:
poetry add pytest
Automatycznie zostanie znaleziona pasująca wersja do pozostałych zależności i nastąpi instalacja biblioteki wraz z jej dependencjami.
Istnieje wiele sposobów określenia wersji danej biblioteki, na przykład określenie minimalnej bądź konkretnej. Zalecane jest, aby podawać zawsze stałą wersję. W ten sposób możemy uniknąć problemów z potencjalnie groźnymi aktualizacjami paczek. Z drugiej strony dokłada to dodatkowych zadań deweloperom – warto utrzymywać najnowsze wersje dependencji.
Więcej szczegółów na temat możliwych opcji określenia zależności w projekcie znajdziecie w oficjalnej dokumentacji.
Wirtualne środowisko
W trakcie konfigurowania projektu, Poetry tworzy wirtualne środowisko w katalogu {cache-dir}/virtualenvs. Można zmienić ten katalog poprzez pliki konfiguracyjne Poetry tak, aby środowisko zostało zainstalowane klasycznie (tak jak virtualenv) wewnątrz folderu projektu.
Istnieje wiele metod odpalania komend przy użyciu wirtualnego środowiska utworzonego przez Poetry. Najprostszym z nich jest komenda run:
poetry run python your_script.py poetry run pytest
Kolejnym sposobem jest aktywowanie wirtualnego środowiska i następnie wykonywanie komend. Najprościej można to osiągnąć poprzez poetry shell (deactivate dezaktywuje środowisko). Poetry tworzy w ten sposób subproces, który posiada aktywowane środowisko. Poniższa tabela przedstawia sposoby aktywowania na różnych systemach różnymi sposobami:
| Posix-shell | Windows Powershell | dezaktywowanie | |
| Sub-shell | Poetry shell | Poetry shell | Exit |
| Manualna aktywacja | source {path_to_venv}/bin/activate | {path_to_venv}\Scripts\activate.ps1 | deactivate |
| Jednoliniowa aktywacja | source $(poetry env info –path)/bin/activate | & ((poetry env info –path) + „\Scripts\activate.ps1”) | deactivate |
Instalacja i aktualizacja dependencji
Instalacja odbywa się poprzez komendę poetry install. Automatycznie wczytywania jest zawartość pliku poetry.lock i następnie są dwa dalsze scenariusze:
- Instalacja bez pliku poetry.lock
Jeżeli nigdy wcześniej nie była przeprowadzona instalacja projektu i nie ma pliku poetry.lock, Poetry rozwiązuje wszystkie zależności opisane w pliku pyproject.toml i pobiera najnowsze wersje dependencji. Po zakończeniu instalacji, tworzony jest plik poetry.lock z dokładną informacją, jakie wersje zostały zainstalowane.
- Instalacja z plikiem poetry.lock
Gdy w projekcie mamy plik poetry.lock i pyproject.toml, oznacza to, iż albo wcześniej instalowaliśmy projekt, albo plik poetry.lock został zapisany na repozytorium (to dobrze).
W tej sytuacji instalowanie przebiega podobnie, Poetry rozwiązuje wszystkie zależności z pliku pyproject.toml, ale poszczególne wersje wybiera z pliku poetry.lock.
Dobrą praktyką jest zapisywanie w repozytorium pliku poetry.lock. Dzięki temu wszystkie osoby pracujące nad projektem będą miały identyczne wersje dependencji. Ten sam efekt można uzyskać poprzez ustalenie konkretnych wersji zależności w pliku pyproject.toml. Zaleca się, aby pomimo stałej wersji w pyproject.toml, zapisywać plik poetry.lock do repozytorium.
Aby zaktualizować biblioteki do najnowszej wersji, należy użyć komendy poetry update. Spowoduje to zainstalowanie najnowszych wersji, jak również aktualizację pliku lock. Taki sam efekt można uzyskać poprzez usunięcie pliku lock i ponowne uruchomienie komendy install.
Budowanie paczek i ich dystrybucja
Poetry ma prosty mechanizm budowania i publikowania na PyPi paczek stworzonych z projektu.
Jednym z głównych wymagań, zanim przystąpimy do budowania paczki, jest wersjonowanie. Poetry nie narzuca żadnej konwencji wersjonowania, ale jest zalecanym, aby stosować się do zasad semantycznego wersjonowania (PEP 440). Na przykład wersja 1.0.0-hotfix.1 nie jest poprawna. W zamian za to można użyć 1.0.0-post1, bądź 1.0.0.post1.
Kolejnym elementem, który warto rozważyć, jest plik poetry.lock. W poprzedniej części opisane zostały powody, dla których powinno się przechowywać ten plik w repozytorium. Jeżeli jednak nie chcemy tego robić, można dodać ten plik do listy .gitignore.
Przed publikowaniem paczki należy ją zbudować:
poetry build
Ta komenda zbuduje paczkę w dwóch formatach:
- Sdisk: plik, który zawiera kod źródłowy aplikacji razem z instrukcjami jak je zainstalować. Na tej podstawie system docelowy klienta buduje paczkę wheel bezpośrednio.
- Bdist (wheel): archiwum plików binarnych, które mogą być zainstalowane na konkretnej platformie (np.: linux-x86_64) z konkretną wersją Pythona (np.: Python3.9).
Używanie paczek wheel jest powszechnie stosowane. Oferują one dużo większą prędkość instalacji, a pliki są mniejsze. Domyślnie Poetry czy też pip używają plików wheel. Natomiast najlepszą opcją jest publikacja obu wersji, ponieważ bardzo trudno jest stworzyć archiwa plików binarnych dla każdej wersji systemu i Pythona, zaś sdisk pozwala na instalację każdemu.
Publikacja paczki odbywa się poprzez komendę:
poetry publish
Domyślnie Poetry publikuje wszystko do publicznego PyPi pod warunkiem, iż jest się zarejestrowanym użytkownikiem i dane do logowania zostały poprawnie skonfigurowane.
Warto odnotować, że komenda powyżej nie buduje paczki, należy to zrobić wcześniej bądź dodać flagę –build.
Jeżeli planujemy wysłać naszą paczkę do prywatnego repozytorium, musimy ją dodać do globalnej listy:
poetry source add --priority=supplemental foo https://pypi.example.org/simple/ poetry config repositories.foo https://pypi.example.org/legacy/
I następnie zmodyfikować komendę publish poprzez dodanie parametru:
poetry publish --build --repository foo
Podsumowanie
Poetry jest bardzo wszechstronnym narzędziem wykorzystywanym coraz częściej przez programistów, czemu dowodzi ponad 13 milionów pobrań miesięcznie (stan na 07.2023).
W artykule zostały opisane tylko podstawowe funkcjonalności pozwalające w pełni skonfigurować i utrzymywać w porządku nawet bardzo duże projekty. Poetry ma jeszcze wiele ciekawych mechanizmów takich jak inne repozytorium jako dependencja, system pluginów itp. Jest to jednak materiał na osobny artykuł.
Super artykuł!