Python Academy · Lekcja

Struktura projektu i pyproject.toml

Q: Czy lekcja „Struktura projektu i pyproject.toml” jest bezpłatna?

Tak — pełny tekst „Struktura projektu i pyproject.toml” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Python Academy, przejdź na CoddyKit PRO. Kurs Python Academy zawiera 4 lekcji w sumie.

Q: Co nauczysz się w „Struktura projektu i pyproject.toml”?

Zaprojektuj strukturę pakietu Ćwiczysz Python Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Q: Czy potrzebuję doświadczenia, aby zacząć Python Academy?

Nie wymagamy żadnego doświadczenia. Python Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Q: Ile czasu zajmuje lekcja „Struktura projektu i pyproject.toml”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Q: Czy mogę pisać i uruchamiać kod w tej lekcji Python Academy?

Tak. Każda lekcja Python Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Zaprojektuj strukturę pakietu

Struktura projektu i pyproject.toml to bezpłatna lekcja Python Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Python Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Python Academy zawiera 4 lekcji w sumie.

Dlaczego warto pakietować kod

Skrypt znajduje się na Państwa komputerze, natomiast pakiet może zainstalować każdy za pomocą pip install. Pakietowanie zamienia folder z kodem w możliwą do dystrybucji, wersjonowaną i wielokrotnego użytku jednostkę.

Pierwszym krokiem jest przejrzysty układ projektu i plik konfiguracyjny.

Układ src

Zalecana struktura umieszcza kod, który można importować, w katalogu src/:

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.md i tests/

Układ src zapobiega przypadkowemu importowaniu kodu z katalogu głównego projektu zamiast zainstalowanej kopii.

Plik init.py

Plik __init__.py oznacza katalog jako pakiet, który można importować, i jest wykonywany przy pierwszym zaimportowaniu pakietu. To również miejsce, w którym udostępnia się publiczne API, importując najważniejsze nazwy.

Do utworzenia pakietu wystarczy nawet pusty plik __init__.py.

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

Czym jest pyproject.toml

Plik pyproject.toml to pojedynczy, ustandaryzowany plik konfiguracyjny (PEP 518/621) używany we współczesnym pakietowaniu w Pythonie. W większości projektów zastępuje dawny plik setup.py i jest odczytywany przez narzędzia budowania.

Wykorzystuje format TOML: sekcje umieszczone w nawiasach kwadratowych oraz wiersze w postaci klucz = wartość.

Tabela build-system

Tabela [build-system] informuje narzędzia, jak zbudować pakiet. Często stosuje się:

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

Inne backendy to Hatchling i Flit; idea pozostaje taka sama.

Tabela project

Tabela [project] zawiera metadane: name, version, description, authors, readme, requires-python i dependencies. To właśnie te informacje użytkownicy widzą w PyPI.

Można ją traktować jako dowód tożsamości pakietu.

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

Zasady nazewnictwa

Nazwa pakietu musi być unikalna w PyPI i podlega normalizacji: wielkość liter nie ma znaczenia, a łączniki i podkreślenia są traktowane tak samo. Przed wybraniem nazwy należy sprawdzić jej dostępność, aby uniknąć konfliktu podczas przesyłania pakietu.

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

Deklarowanie zależności

Zależności wymagane w czasie działania należy wymienić w polu dependencies, podając ograniczenia wersji, takie jak 'requests>=2.28,<3'. Opcjonalne dodatki umieszcza się w sekcji [project.optional-dependencies]; można je instalować za pomocą pip install mytool[dev].

Ograniczenia powinny być tak luźne, jak to bezpieczne, aby pakiet mógł współistnieć z innymi pakietami.

Punkty wejścia

Aby dostarczać narzędzie wiersza poleceń, należy dodać wpis [project.scripts], na przykład mytool = 'mypackage.cli:main'. Po instalacji wpisanie mytool uruchamia tę funkcję. W ten sposób swoje polecenia udostępniają narzędzia CLI, takie jak black czy pytest.

Dołączanie plików innych niż kod

Pliki danych (szablony, JSON) nie są dołączane automatycznie. Należy skonfigurować dane pakietu w backendzie budowania, aby pliki znalazły się wewnątrz wheel. Pominięcie tego kroku jest częstą przyczyną błędów typu „działa lokalnie, ale po instalacji już nie”.

Instalacje w trybie edytowalnym

Podczas tworzenia pakietu należy zainstalować go w trybie edytowalnym za pomocą pip install -e .. Zmiany w kodzie źródłowym są wtedy od razu widoczne i nie wymagają ponownej instalacji. Działa to dzięki poprawnemu plikowi pyproject.toml, co jest kolejnym powodem, aby skonfigurować go na początku prac.

Instalacje w trybie edytowalnym zapewniają najszybszą informację zwrotną podczas iteracyjnego rozwijania pakietu.

Szybkie sprawdzenie

Proszę sprawdzić swoją wiedzę na temat struktury projektu.

Podsumowanie

Przygotowali już Państwo strukturę pakietu:

Należy używać układu src, w którym plik __init__.py oznacza pakiety
pyproject.toml to standardowy plik konfiguracyjny zawierający [build-system] i [project]
Należy zadeklarować name, version, requires-python i dependencies
Należy dodać punkty wejścia [project.scripts] dla narzędzi CLI i skonfigurować dane pakietu

Często zadawane pytania

Czy lekcja „Struktura projektu i pyproject.toml” jest bezpłatna?