0 dní v řadě · 0 bodů

Soubory, chyby a knihovny · 22 min

Virtuální prostředí a závislosti

Každému projektu dáš vlastní sadu balíků, naučíš se pip, verze a requirements.txt a přestaneš se bát věty „u mě to fungovalo“.

Hloubka
Úkoly
Lidsky řečeno

Představ si dílnu s jedinou policí na nářadí. Na stavbu kůlny potřebuješ malé kladivo, na bourání zdi velké. Police má ale místo jen na jedno kladivo, takže kdo přinese nové, staré vyhodí. Virtuální prostředí je vlastní bedna s nářadím pro každou zakázku. Co je v jedné bedně, druhou vůbec nezajímá.

Problém: jedna police pro všechny projekty

Balík je kód, který napsal někdo jiný a ty si ho stáhneš do počítače. Python si balíky ukládá do složky site-packages. Bez dalších opatření je ta složka jedna pro celý počítač a od každého balíku v ní může ležet jen jedna verze.

Zahrajeme si to na slovníku. Klíč je jméno balíku, hodnota jeho verze.

police = {}

def nainstaluj(balik, verze):
    if balik in police and police[balik] != verze:
        print(f"{balik}: verzi {police[balik]} přepsala verze {verze}")
    police[balik] = verze

nainstaluj("pandas", "1.5.3")   # starý projekt A
nainstaluj("pandas", "2.2.3")   # nový projekt B

print("Projekt A čeká 1.5.3, na polici je", police["pandas"])

# Totéž s vlastní bednou pro každý projekt
bedny = {"projekt-a": {"pandas": "1.5.3"}, "projekt-b": {"pandas": "2.2.3"}}
for projekt, balicky in bedny.items():
    print(projekt, "má pandas", balicky["pandas"])
Výstup
pandas: verzi 1.5.3 přepsala verze 2.2.3
Projekt A čeká 1.5.3, na polici je 2.2.3
projekt-a má pandas 1.5.3
projekt-b má pandas 2.2.3

Přesně takhle se rozbíjejí staré projekty: nikdo na ně nesáhl, ale kvůli jinému projektu se jim pod rukama vyměnila knihovna. Virtuální prostředí (anglicky virtual environment, zkráceně venv) je složka s vlastním site-packages pro jeden projekt.

Kde Python balíky hledá

Když napíšeš import neco, Python prochází seznam složek v sys.path a bere první shodu. Spusť si to. Výpis se liší podle toho, kde kód běží.

import sys

for slozka in sys.path:
    print(repr(slozka))
Výstup

Dvě hodnoty prozradí, jestli běžíš ve virtuálním prostředí. sys.prefix je složka aktuálního prostředí a sys.base_prefix složka Pythonu, ze kterého vzniklo. Když se liší, jsi ve venvu.

import sys

def jsem_ve_venvu():
    return sys.prefix != sys.base_prefix

print("Virtuální prostředí:", jsem_ve_venvu())
Výstup
Virtuální prostředí: False

Tady vyjde False, protože ukázky běží přímo v prohlížeči a balíky si načítají samy. Příkazy z dalších částí proto patří do terminálu na tvém počítači. Terminál je okno, kam se píšou příkazy pro systém: ve Windows je to PowerShell (najdeš ho v nabídce Start), na macOS aplikace Terminál, na Linuxu také Terminál.

Zjistit verzi nainstalovaného balíku umí i sám Python:

from importlib.metadata import PackageNotFoundError, version

def zjisti_verzi(balik):
    try:
        return version(balik)
    except PackageNotFoundError:
        return None

print(zjisti_verzi("balik-ktery-tu-urcite-neni"))
Výstup
None

Virtuální prostředí krok za krokem

Potřebuješ Python nainstalovaný z python.org nebo ze svého systému. Otevři terminál, vytvoř složku projektu a přejdi do ní. cd znamená „změň složku“.

bash
mkdir muj-projekt
cd muj-projekt
python --version

Na macOS a Linuxu se příkaz často jmenuje python3. Ve Windows funguje i spouštěč py. Prostředí vytvoříš jedním řádkem:

bash
python -m venv .venv

-m venv říká „spusť modul venv“ a .venv je jméno nové složky. To jméno není povinné, ale je zvykem a editory ho samy poznají. Uvnitř najdeš zhruba tohle:

text
.venv/
  pyvenv.cfg              nastavení: odkud prostředí pochází
  Scripts/                Windows: python.exe, pip.exe, Activate.ps1
  bin/                    macOS a Linux: python, pip, activate
  Lib/site-packages/      Windows: sem půjdou balíky
  lib/python3.12/site-packages/    macOS a Linux: sem půjdou balíky

Teď prostředí aktivuj. Tím terminálu řekneš, aby python a pip bral z této složky.

bash
# Windows, PowerShell
.venv\Scripts\Activate.ps1

# Windows, příkazový řádek cmd
.venv\Scripts\activate.bat

# macOS a Linux
source .venv/bin/activate

Na začátku řádku se objeví (.venv). Ověř si, že je všechno na svém místě, a až skončíš, prostředí opusť:

bash
python -c "import sys; print(sys.prefix)"
python -m pip --version
deactivate

Oba výpisy musí ukazovat do tvé složky .venv. Složku nikdy nedávej do Gitu ani ji nekopíruj na jiný počítač. Stačí do souboru .gitignore přidat řádek .venv/. Co to znamená, probírá lekce Git a práce v týmu. Prostředí je na jedno použití: když se pokazí, smažeš ho a vytvoříš znovu.

Kvíz

Co přesně udělá aktivace prostředí?

Pod kapotou · jak Python pozná, že je ve venvu

Mechanismus popisuje PEP 405. Při startu hledá interpret soubor pyvenv.cfg vedle své binárky nebo o složku výš. Z klíče home odvodí základní instalaci, sys.prefix nastaví na prostředí a sys.base_prefix nechá na základním Pythonu. Standardní knihovna se nekopíruje a bere se ze základní instalace, přibude jen vlastní site-packages. Proto je python -m venv --without-pip skoro okamžité a většinu běžného času zabere ensurepip.

Aktivace tedy není nutná. .venv/bin/python app.py nebo .venv\Scripts\python.exe app.py běží ve správném prostředí i bez ní, a tak se to hodí psát do cronu, systemd a Dockerfile. Prostředí ale nejde přesouvat: skripty v bin mají v shebangu absolutní cestu a activate ji má zapsanou také. Ve Windows je Scripts\python.exe malý přesměrovač na základní interpret, na Unixu obvykle symlink, takže odinstalace základního Pythonu prostředí rozbije. Od Pythonu 3.12 už venv nepředinstalovává setuptools, což občas shodí staré projekty spoléhající na pkg_resources.

pip: instalace balíků

pip je program, který stahuje balíky z veřejného katalogu PyPI (Python Package Index) a ukládá je do site-packages. Spouštěj ho jako python -m pip. Máš pak jistotu, že patří k tomu Pythonu, který právě používáš.

bash
python -m pip install requests            # nejnovější vhodná verze
python -m pip install requests==2.32.3    # přesně tato verze
python -m pip install --upgrade requests  # aktualizace
python -m pip list                        # co je nainstalované
python -m pip list --outdated             # co má novější verzi
python -m pip show requests               # podrobnosti, včetně závislostí
python -m pip uninstall requests          # odebrání

Jméno pro instalaci a jméno pro import se někdy liší. Hledej ho v dokumentaci balíku a nehádej. Na PyPI může kdokoli nahrát balík s podobným názvem.

InstaluješImportuješ
pillowPIL
beautifulsoup4bs4
pyyamlyaml
scikit-learnsklearn

Po pip install requests přibude víc než jeden balík. requests sám potřebuje další a ty mohou potřebovat další. Těm se říká závislosti. Přímé jsou ty, o které sis řekl, tranzitivní přišly s nimi.

ZAVISLOSTI = {
    "requests": ["certifi", "charset-normalizer", "idna", "urllib3"],
    "rich": ["markdown-it-py", "pygments"],
    "markdown-it-py": ["mdurl"],
}

for balik in ["requests", "rich", "idna"]:
    prime = ZAVISLOSTI.get(balik, [])
    print(balik, "->", ", ".join(prime) or "nic dalšího")
Výstup
requests -> certifi, charset-normalizer, idna, urllib3
rich -> markdown-it-py, pygments
idna -> nic dalšího

pip uninstall odebere jen jmenovaný balík. Jeho závislosti zůstanou ležet v prostředí. Nejčistší úklid je proto smazat .venv a nainstalovat znovu, co opravdu potřebuješ.

Úkol

Všechno, co přijde s balíkem

Napiš funkci vsechny_zavislosti(balik, graf). graf je slovník jako v ukázce výše. Funkce vrátí seřazený seznam všech přímých i tranzitivních závislostí. Samotný balik v něm nebude, ani když na sebe balíky odkazují dokola. Balík, který ve slovníku chybí, žádné závislosti nemá.

GRAF = {
    "rich": ["markdown-it-py", "pygments"],
    "markdown-it-py": ["mdurl"],
}

def vsechny_zavislosti(balik, graf):
    # doplň
    return []

print(vsechny_zavislosti("rich", GRAF))
Výstup

Verze a jak je zapisovat

Verze jako 2.31.0 se obvykle čte hlavní.vedlejší.oprava. Změna posledního čísla bývá oprava chyb, prostředního nové funkce, prvního změny, které mohou rozbít starý kód. Je to zvyk, ne zákon. Třeba certifi čísluje verze podle data.

Verze nejsou desetinná čísla ani obyčejné texty. Texty se porovnávají znak po znaku, takže vyjde nesmysl:

print("3.10" > "3.9")                  # porovnání textů
print((3, 10) > (3, 9))                # porovnání n-tic čísel
print(tuple(int(c) for c in "3.10".split(".")))
print((2,) == (2, 0))                  # pozor: různá délka
Výstup
False
True
(3, 10)
False

Text "3.10" prohrál, protože znak 1 je v abecedě před 9. N-tice čísel porovnávají správně, ale (2,) a (2, 0) se neshodují, ačkoli jde o stejnou verzi.

V závislostech se verze omezují takto:

ZápisVýznam
requests==2.32.3přesně tato verze
requests>=2.31tato nebo novější
requests>=2.31,<3od 2.31 výš, ale ne 3.0 a dál
requests~=2.32.0kompatibilní: >=2.32.0 a zároveň ==2.32.*
requests!=2.32.0cokoli kromě této verze

Někdy se požadavky nedají splnit. Pak pip raději skončí chybou ResolutionImpossible, než aby nainstaloval něco nefunkčního.

text
tvuj-projekt
  ├── balik-a  chce  knihovna<2
  └── balik-b  chce  knihovna>=2      v jednom prostředí nejde splnit obojí
Úkol

Stačí tahle verze?

Napiš funkci splnuje(verze, minimum), která vrátí True, když je verze stejná nebo novější než minimum. Verze jsou texty z čísel a teček. Chybějící části se počítají jako nula, takže "2" a "2.0.0" jsou stejná verze.

def splnuje(verze, minimum):
    # doplň
    return verze >= minimum

print(splnuje("3.10", "3.9"))
Výstup
Kvíz

Co dovolí zápis requests~=2.32.0?

Pod kapotou · PEP 440 a co dokáže rozbít vlastní parser

Úkol výše je záměrně zjednodušený. Reálné verze podle PEP 440 mají předběžná vydání a další přípony s pořadím 1.0.dev1 < 1.0a1 < 1.0b2 < 1.0rc1 < 1.0 < 1.0.post1. V produkčním kódu verze ručně nerozebírej a použij balík packaging, na kterém stojí i pip:

python
from packaging.specifiers import SpecifierSet
from packaging.version import Version

Version("1.0") == Version("1.0.0")            # True
Version("1.0rc1") < Version("1.0")            # True
"2.99" in SpecifierSet("~=2.31")              # True
"3.0rc1" in SpecifierSet(">=2.0,<3")          # False

Stejně tak jména: Flask_SQLAlchemy, flask.sqlalchemy a flask-sqlalchemy jsou podle PEP 503 tentýž projekt. Normalizace je re.sub(r"[-_.]+", "-", jmeno).lower().

Od verze 20.3 má pip výchozí resolver s backtrackingem: když kandidát nevyhoví, vrací se a zkouší starší verze. Volné rozsahy tak mohou vést k dlouhému stahování metadat a překvapivě starým verzím. Co by se stalo, ukáže pip install --dry-run --report vystup.json balik.

requirements.txt: recept na stejné prostředí

Prostředí do Gitu nepatří, ale kolega nebo server ho musí umět postavit znovu. Stačí k tomu soubor se seznamem balíků. Říká se mu requirements.txt a vznikne jediným příkazem:

bash
python -m pip freeze > requirements.txt

freeze vypíše nainstalované balíky s přesnými verzemi, včetně tranzitivních závislostí. Znak > výstup zapíše do souboru. Výsledek vypadá třeba takto (čísla budou u tebe jiná):

text
certifi==2024.8.30
charset-normalizer==3.4.0
idna==3.10
requests==2.32.3
urllib3==2.2.3

Na jiném počítači pak obnovíš totéž:

bash
python -m venv .venv
source .venv/bin/activate       # ve Windows .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Aktualizace má pevný rytmus: povýšíš balík, otestuješ program a teprve potom znovu spustíš freeze. Soubor pak zaznamenává stav, o kterém víš, že funguje. Až budeš balíčkovat vlastní projekt, přijde na řadu pyproject.toml. Hotové knihovny si vyzkoušíš hned v dalším modulu, začíná lekcí Co je knihovna a jak se v ní vyznat.

Úkol

Sedí prostředí na recept?

Napiš dvě funkce.

nacti_pozadavky(text) dostane obsah requirements.txt a vrátí slovník {jméno: verze}. Vynech prázdné řádky a komentáře, které začínají #, i ty na konci řádku. Jméno převeď na malá písmena a podtržítka nahraď pomlčkami.

rozdily(pozadavky, nainstalovano) vrátí seřazený seznam jmen z pozadavky, která v druhém slovníku chybějí nebo mají jinou verzi.

RECEPT = """
# webová část
requests==2.32.3
Charset_Normalizer==3.4.0   # kvůli kódování

idna==3.10
"""

def nacti_pozadavky(text):
    # doplň
    return {}

def rozdily(pozadavky, nainstalovano):
    # doplň
    return []

print(nacti_pozadavky(RECEPT))
Výstup
Kvíz

Kolega si stáhl tvůj projekt a program hlásí ModuleNotFoundError. Co je správný postup?

Pod kapotou · lock soubory, hashe a dodavatelský řetězec

pip freeze je chudý lock soubor: nerozliší přímé závislosti od tranzitivních a zachytí jen jednu platformu. Když ho vyrobíš ve Windows, může obsahovat třeba pywin32, který se na Linuxu nenainstaluje. Běžné řešení je oddělit záměr (requirements.in nebo pyproject.toml) od výsledku a výsledek generovat nástrojem: pip-compile z pip-tools, Poetry, PDM nebo uv. PEP 751 zavádí společný formát pylock.toml. Novější pip ho umí vytvořit experimentálním příkazem pip lock a přijmout přes -r.

Pevná verze nestačí, pokud chceš vědět, že stahuješ pořád stejné bajty. pip-compile --generate-hashes přidá ke každému balíku --hash=sha256:... a pip pak běží v režimu --require-hashes, kde odmítne vše bez shody, včetně tranzitivních závislostí.

Pár věcí z praxe:

  • Instalace ze zdrojového archivu (sdist) spouští build, tedy cizí kód. --only-binary :all: připustí jen wheely, které se pouze rozbalí. Kód ale pořád běží při importu a soubory .pth v site-packages mohou řádkem začínajícím import spustit kód při každém startu Pythonu.
  • --extra-index-url nedává přednost tvému firemnímu indexu. pip bere všechny indexy jako rovnocenné a vybírá nejvyšší verzi, na čemž stojí útok dependency confusion. Používej jeden proxy index přes --index-url.
  • Novější pip má --uploaded-prior-to, kterým lze ignorovat čerstvě nahrané verze. Řada škodlivých vydání se odhalí během krátké doby.
  • requirements.txt neurčuje verzi Pythonu ani systémové knihovny. To řeší až requires-python, kontejner nebo jiný popis prostředí.