0 dní v řadě · 0 bodů

Profesionální vývoj · 28 min

Struktura projektu a pyproject.toml

Z hromady skriptů uděláš instalovatelný projekt: src layout, pyproject.toml, vlastní příkaz v terminálu a wheel, do kterého nahlédneš.

Hloubka
Úkoly
Lidsky řečeno

Doma víš, že sůl je ve třetí skříňce vlevo. V restauraci to nestačí: nový kuchař musí kuchyni pochopit za pět minut. Proto má každá věc své místo a na dveřích visí karta s tím, co se tu vaří a co je k tomu potřeba. Struktura složek je rozložení kuchyně. Soubor pyproject.toml je ta karta na dveřích.

Od skriptu k projektu

Jeden soubor program.py je v pořádku, dokud ho píšeš sám a pouštíš na svém počítači. Potíže přijdou, když program poroste: kolega ho nerozběhne, protože neví, co doinstalovat. Testy nemají odkud importovat. Na serveru se spouští jinak než u tebe.

Projekt je složka, která tyhle otázky řeší předem. Běžné rozložení vypadá takhle:

text
kavarna/                    kořen projektu, obvykle i kořen gitu
├── pyproject.toml          název, verze, závislosti, nastavení nástrojů
├── README.md               co to je a jak to spustit
├── .gitignore              co do gitu nepatří
├── src/
│   └── kavarna/            vlastní kód, tedy importovatelný balíček
│       ├── __init__.py
│       ├── __main__.py     spustí se při: python -m kavarna
│       ├── cli.py          příkazová řádka
│       └── ceny.py         výpočty
└── tests/
    └── test_ceny.py        testy, k zákazníkovi se nedostanou

Slovo kavarna tu je dvakrát a není to chyba. Vnější složka je projekt, vnitřní je balíček, který se importuje příkazem import kavarna. Co je balíček a __init__.py, ukázala lekce Moduly a balíčky.

Postavíme si kousek té struktury přímo v kódu a zkusíme balíček naimportovat.

import importlib
import sys
from pathlib import Path

soubory = {
    "src/kavarna/__init__.py": "from .ceny import s_dph\n",
    "src/kavarna/ceny.py": (
        "def s_dph(cena, sazba=0.21):\n"
        "    return round(cena * (1 + sazba), 2)\n"
    ),
}
for cesta, obsah in soubory.items():
    soubor = Path(cesta)
    soubor.parent.mkdir(parents=True, exist_ok=True)
    soubor.write_text(obsah, encoding="utf-8")

for soubor in sorted(Path("src").rglob("*.py")):
    print(soubor.as_posix())

importlib.invalidate_caches()
try:
    importlib.import_module("kavarna")
except ModuleNotFoundError as chyba:
    print("Bez instalace:", chyba)

# Instalace udělá v principu tohle: zařídí, aby Python složku našel.
slozka = str(Path("src").resolve())
sys.path.insert(0, slozka)
importlib.invalidate_caches()
kavarna = importlib.import_module("kavarna")
print("Po zpřístupnění:", kavarna.s_dph(100))
sys.path.remove(slozka)
Výstup
src/kavarna/__init__.py
src/kavarna/ceny.py
Bez instalace: No module named 'kavarna'
Po zpřístupnění: 121.0

Python hledá moduly jen v seznamu sys.path. Složka src v něm není, takže import napoprvé selže. V reálném projektu ji do sys.path nepřidáváš ručně. Projekt nainstaluješ a o zbytek se postará pip.

Proč je kód ve složce src

Možná tě napadlo: k čemu src? Stačilo by dát kavarna/ rovnou do kořene. Takové rozložení se jmenuje flat layout a funguje. Má ale záludnost. Když spustíš testy z kořene projektu, Python často najde balíček přímo ve vedlejší složce a nainstalovanou verzi vůbec nepoužije.

Testy tak ověřují něco jiného, než co dostane zákazník. Pokud při balení vypadne soubor, u tebe všechno projde a rozbije se to až u něj.

import importlib
import sys
from pathlib import Path

def zapis(cesta, obsah):
    soubor = Path(cesta)
    soubor.parent.mkdir(parents=True, exist_ok=True)
    soubor.write_text(obsah, encoding="utf-8")

zapis("site-packages/kavarna/__init__.py", 'ODKUD = "nainstalovaný balíček"\n')
zapis("kavarna/__init__.py", 'ODKUD = "složka vedle testů"\n')

instalace = str(Path("site-packages").resolve())
sys.path.append(instalace)
importlib.invalidate_caches()

kavarna = importlib.import_module("kavarna")
print("Flat layout:", kavarna.ODKUD)

# Přesun do src: z kořene projektu už balíček není vidět.
del sys.modules["kavarna"]
Path("src").mkdir()
Path("kavarna").rename("src/kavarna")
importlib.invalidate_caches()

kavarna = importlib.import_module("kavarna")
print("Src layout:", kavarna.ODKUD)
sys.path.remove(instalace)
Výstup
Flat layout: složka vedle testů
Src layout: nainstalovaný balíček

Složka src je malá pojistka. Kód se nedá naimportovat omylem, musíš ho opravdu nainstalovat. Díky tomu testuješ totéž, co pošleš ven.

Kvíz

Co je hlavní výhoda složky src?

pyproject.toml: karta projektu

pyproject.toml je textový soubor ve formátu TOML. Má sekce v hranatých závorkách a pod nimi dvojice klíč = hodnota. Dnes je to standardní místo pro popis pythonního projektu a většina nástrojů v něm hledá i své nastavení.

toml
[build-system]
requires = ["hatchling>=1.27"]
build-backend = "hatchling.build"

[project]
name = "kavarna"
version = "0.1.0"
description = "Výpočty cen pro malou kavárnu"
readme = "README.md"
requires-python = ">=3.12"
license = "MIT"
dependencies = [
    "requests>=2.32",
]

[project.optional-dependencies]
export = ["openpyxl>=3.1"]

[project.scripts]
kavarna = "kavarna.cli:main"

[dependency-groups]
dev = ["pytest>=8", "ruff", "mypy"]

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.ruff]
line-length = 100
SekceK čemu slouží
[build-system]čím se projekt zabalí; tady nástrojem hatchling
[project]údaje o projektu a závislosti, bez kterých neběží
[project.optional-dependencies]volitelné doplňky, instalace pip install "kavarna[export]"
[project.scripts]příkazy, které po instalaci přibudou v terminálu
[dependency-groups]nástroje jen pro vývoj, zákazníkovi se neinstalují
[tool.*]nastavení jednotlivých nástrojů

Zápis "requests>=2.32" znáš z lekce Virtuální prostředí a závislosti. Rozdíl je v tom, že requirements.txt popisuje konkrétní prostředí, kdežto dependencies říká, co projekt potřebuje.

TOML umí číst i samotný Python, od verze 3.11 v modulu tomllib. Modul umí jen čtení, zápis ne.

import tomllib

TEXT = """
[project]
name = "kavarna"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["requests>=2.32", "rich"]

[project.scripts]
kavarna = "kavarna.cli:main"
"""

data = tomllib.loads(TEXT)
projekt = data["project"]
print(projekt["name"], projekt["version"])
print(projekt["dependencies"])
print(projekt["scripts"])
Výstup
kavarna 0.1.0
['requests>=2.32', 'rich']
{'kavarna': 'kavarna.cli:main'}
Úkol

Oprav kartu projektu

Řetězec PYPROJECT je syntakticky správně, ale dva klíče jsou v chybné sekci. Přesuň requires-python a dependencies do [project]. V [project.scripts] má zůstat jen příkaz kavarna.

PYPROJECT = """
[build-system]
requires = ["hatchling>=1.27"]
build-backend = "hatchling.build"

[project]
name = "kavarna"
version = "0.1.0"

[project.scripts]
kavarna = "kavarna.cli:main"
requires-python = ">=3.12"
dependencies = ["requests>=2.32"]
"""
Výstup

Instalace a vlastní příkaz

V čerstvém virtuálním prostředí nainstaluješ projekt takhle:

bash
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python -m pip install -U pip
pip install -e . --group dev     # --group vyžaduje pip 25.1 nebo novější

Tečka znamená „tenhle projekt“. Přepínač -e je editovatelná instalace: Python nepracuje s kopií, ale přímo s tvými soubory, takže změny v kódu platí hned. Znovu instalovat musíš až po změně závislostí nebo příkazů v pyproject.toml.

Po instalaci jde program spustit dvěma způsoby:

bash
kavarna 100 --dph 0.12     # příkaz z [project.scripts]
python -m kavarna 100      # spuštění balíčku přes __main__.py

Zápis kavarna.cli:main říká: z modulu kavarna.cli vezmi funkci main a zavolej ji. To, co funkce vrátí, se stane návratovým kódem programu. Nula znamená úspěch, cokoli jiného chybu. Podle něj poznají výsledek skripty a automatické buildy.

Argumenty příkazové řádky zpracuje modul argparse. Funkce main přijímá seznam argumentů argv. Když žádný nedostane, vezme je z příkazové řádky. V testu jí je tak můžeš předat přímo.

import importlib
import runpy
import sys
from pathlib import Path

soubory = {
    "kavarna/__init__.py": "",
    "kavarna/cli.py": '''
import argparse

def main(argv=None):
    parser = argparse.ArgumentParser(prog="kavarna")
    parser.add_argument("cena", type=float)
    parser.add_argument("--dph", type=float, default=0.21)
    args = parser.parse_args(argv)
    print(f"{args.cena * (1 + args.dph):.2f} Kč")
    return 0
''',
    "kavarna/__main__.py": '''
import sys
from .cli import main

sys.exit(main())
''',
}
for cesta, obsah in soubory.items():
    soubor = Path(cesta)
    soubor.parent.mkdir(exist_ok=True)
    soubor.write_text(obsah, encoding="utf-8")
importlib.invalidate_caches()

# Přímé volání, tak to dělá test:
main = importlib.import_module("kavarna.cli").main
print("návratový kód:", main(["100", "--dph", "0.12"]))

# Totéž co: python -m kavarna 100
puvodni = sys.argv
sys.argv = ["kavarna", "100"]
try:
    runpy.run_module("kavarna", run_name="__main__", alter_sys=True)
except SystemExit as konec:
    print("návratový kód:", konec.code)
finally:
    sys.argv = puvodni
Výstup
112.00 Kč
návratový kód: 0
121.00 Kč
návratový kód: 0
Úkol

Funkce main pro příkazovou řádku

Napiš funkci main(argv=None). Přijme povinný argument litry (desetinné číslo) a volitelný --cena (cena za litr, výchozí 40). Vypíše součin zaokrouhlený na dvě místa ve tvaru 120.00 Kč a vrátí 0.

import argparse

def main(argv=None):
    parser = argparse.ArgumentParser(prog="mleko")
    # doplň argumenty, výpis a návratový kód
Výstup
Kvíz

Proč má main parametr argv=None, když by si argumenty mohla vzít sama ze sys.argv?

Pod kapotou · wheel je zip s metadaty

python -m build (nebo uv build) vytvoří dva artefakty: sdist se zdrojáky a wheel, hotový archiv pro instalaci. Sestavení spouští backend podle PEP 517 v izolovaném prostředí, do kterého se doinstaluje build-system.requires (PEP 518). Metadata v [project] definuje PEP 621, editovatelné instalace PEP 660.

Wheel je obyčejný ZIP. pip ho rozbalí do site-packages a podle entry_points.txt vygeneruje spouštěč, který zavolá sys.exit(main()). Ručně poskládaný wheel níž ukazuje celý mechanismus. Čisté wheely jde dokonce importovat přímo ze ZIPu, v praxi na to ale nespoléhej.

import importlib
import importlib.metadata as metadata
import importlib.resources as resources
import sys
import zipfile
from pathlib import Path

wheel = Path("kavarna-1.2.0-py3-none-any.whl").resolve()
info = "kavarna-1.2.0.dist-info"
with zipfile.ZipFile(wheel, "w") as z:
    z.writestr("kavarna/__init__.py", "")
    z.writestr("kavarna/cli.py", "def main():\n    print('běžím z wheelu')\n    return 0\n")
    z.writestr("kavarna/sazby.json", '{"dph": 0.21}')
    z.writestr(f"{info}/METADATA", "Metadata-Version: 2.4\nName: kavarna\nVersion: 1.2.0\nRequires-Dist: requests>=2.32\n")
    z.writestr(f"{info}/entry_points.txt", "[console_scripts]\nkavarna = kavarna.cli:main\n")
    print(*z.namelist(), sep="\n")

sys.path.insert(0, str(wheel))
importlib.invalidate_caches()

print("verze:", metadata.version("kavarna"))
print("závislosti:", metadata.requires("kavarna"))
vstup = metadata.entry_points(group="console_scripts", name="kavarna")["kavarna"]
print("příkaz:", vstup.value, "->", vstup.load()())
print("data:", resources.files("kavarna").joinpath("sazby.json").read_text(encoding="utf-8"))
sys.path.remove(str(wheel))
Výstup
kavarna/__init__.py
kavarna/cli.py
kavarna/sazby.json
kavarna-1.2.0.dist-info/METADATA
kavarna-1.2.0.dist-info/entry_points.txt
verze: 1.2.0
závislosti: ['requests>=2.32']
běžím z wheelu
příkaz: kavarna.cli:main -> 0
data: {"dph": 0.21}

Z ukázky plynou tři pravidla pro praxi:

  • Verzi za běhu čti přes importlib.metadata.version("kavarna"). Nedržíš ji pak na dvou místech.
  • Datové soubory otevírej přes importlib.resources.files(...), ne přes open(Path(__file__).parent / ...). První způsob funguje i tam, kde balíček není rozbalený na disku.
  • Název distribuce a importu jsou dvě věci. pip install moje-appka se normalizuje podle PEP 503, ale importuje se typicky moje_appka. U Pillow a PIL je rozdíl ještě větší.

Rozdíl mezi extras a skupinami: optional-dependencies se publikují v metadatech balíčku, dependency-groups (PEP 735) ne. Testovací nástroje proto patří do skupin. Knihovna by neměla bez důvodu stropovat závislosti (requests<3), protože tím zákazníkům vyrábí neřešitelné konflikty. Přesné verze patří do lock souboru aplikace. Licenci zapisuj jako SPDX výraz license = "MIT" podle PEP 639. Typovaná knihovna přidá prázdný soubor py.typed (PEP 561), jinak mypy její anotace ignoruje.

Rozděl kód podle smyslu

Soubor utils.py je šuplík, kam se časem nastěhuje všechno. Lepší je dělit kód podle toho, o čem je, a držet tři vrstvy:

text
cli.py, api.py             vstup a výstup: argumenty, HTTP, print
      │
      ▼
sluzby.py                  postup: co se stane v jakém pořadí
      │
      ▼
ceny.py, objednavka.py     pravidla: čisté výpočty bez vstupu a výstupu

Závislosti vedou jen shora dolů. Výpočet ceny neví nic o terminálu ani o webu. Když přidáš webové rozhraní, spodní vrstvy se nemění, a jde je snadno testovat. O tom je lekce Mocky a testovatelný návrh.

Když vedou šipky oběma směry, vznikne kruhový import. Modul A potřebuje B, B potřebuje A a jeden z nich ještě není dočtený.

import importlib
from pathlib import Path

Path("ceny.py").write_text(
    "from objednavka import POLOZKY\n"
    "def celkem():\n"
    "    return sum(POLOZKY)\n",
    encoding="utf-8",
)
Path("objednavka.py").write_text(
    "from ceny import celkem\n"
    "POLOZKY = [10, 20]\n",
    encoding="utf-8",
)
importlib.invalidate_caches()
importlib.import_module("ceny")
Výstup

Python začne číst ceny, skočí do objednavka a ta chce celkem. Jenže ceny jsou zatím rozečtené a funkce v nich ještě neexistuje. Správná oprava není schovat import do funkce. Společnou část přesuň do třetího modulu, na kterém budou záviset oba.

Kvíz

Modul ceny.py s výpočty potřebuje vypsat varování. Co je nejčistší řešení?

Co patří do repozitáře

Do gitu dej zdrojáky, testy, pyproject.toml, README a u aplikace i lock soubor s přesnými verzemi. Nepatří tam nic, co se dá znovu vygenerovat, a žádná tajemství.

text
.venv/
__pycache__/
*.pyc
dist/
build/
*.egg-info/
.pytest_cache/
.ruff_cache/
.mypy_cache/
.coverage
.env

U verzí závislostí záleží na tom, co vyvíjíš:

KnihovnaAplikace
dependenciesširoké rozsahy, ať se snese s ostatnímico přímo používá
Lock souborjen pro vlastní vývojpovinně v gitu, ať všude běží totéž
Kdo vybírá konkrétní verzeten, kdo knihovnu používáty

Lock soubor umí například uv lock (vytvoří uv.lock) nebo pip-compile z balíku pip-tools. Pro výměnu mezi nástroji vznikl standardní formát pylock.toml podle PEP 751.