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:
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 nedostanouSlovo 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)
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)
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.
Co je hlavní výhoda složky src?
Rychlost ani pyproject.toml s ní nesouvisí. Jde o to, aby se testoval nainstalovaný balíček, ne náhodou nalezená složka.
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í.
[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| Sekce | K č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"])
kavarna 0.1.0
['requests>=2.32', 'rich']
{'kavarna': 'kavarna.cli:main'}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"]
"""
Instalace a vlastní příkaz
V čerstvém virtuálním prostředí nainstaluješ projekt takhle:
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:
kavarna 100 --dph 0.12 # příkaz z [project.scripts]
python -m kavarna 100 # spuštění balíčku přes __main__.pyZá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
112.00 Kč návratový kód: 0 121.00 Kč návratový kód: 0
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
Proč má main parametr argv=None, když by si argumenty mohla vzít sama ze sys.argv?
Při None si argparse vezme sys.argv[1:], takže běžné spuštění funguje dál. Test ale předá seznam přímo.
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))
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řesopen(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-appkase normalizuje podle PEP 503, ale importuje se typickymoje_appka. UPillowaPILje 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:
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ýstupuZá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")
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.
Modul ceny.py s výpočty potřebuje vypsat varování. Co je nejčistší řešení?
Spodní vrstva nemá znát horní. Vrátí informaci a o její podobě pro člověka rozhodne vrstva, která s člověkem mluví.
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í.
.venv/
__pycache__/
*.pyc
dist/
build/
*.egg-info/
.pytest_cache/
.ruff_cache/
.mypy_cache/
.coverage
.envU verzí závislostí záleží na tom, co vyvíjíš:
| Knihovna | Aplikace | |
|---|---|---|
dependencies | široké rozsahy, ať se snese s ostatními | co přímo používá |
| Lock soubor | jen pro vlastní vývoj | povinně v gitu, ať všude běží totéž |
| Kdo vybírá konkrétní verze | ten, 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.