0 dní v řadě · 0 bodů

Užitečné knihovny · 22 min

PyYAML a konfigurační soubory

Přečteš a zapíšeš YAML, vyhneš se pastem jako no = False a postavíš konfiguraci s výchozími hodnotami a kontrolou chyb.

Hloubka
Úkoly
Lidsky řečeno

Představ si kávovar, u kterého bys musel pro změnu velikosti kávy přepájet elektroniku. Nesmysl, od toho jsou tlačítka. Konfigurační soubor jsou tlačítka tvého programu: port, jazyk nebo adresu změníš v obyčejném textu a kód zůstane nedotčený.

Nastavení patří mimo kód

Konfigurace jsou hodnoty, které se liší podle toho, kde a jak program běží. Na tvém notebooku se připojuje k testovací databázi, na serveru k ostré. Kdyby byly adresy natvrdo v kódu, musel bys ho pro každé prostředí upravovat.

YAML je textový formát, který se k tomu často používá. Píšou se v něm třeba soubory pro Docker Compose, Kubernetes nebo GitHub Actions. Struktura se vyjadřuje odsazením a čte se skoro jako poznámky na papíře. Knihovna se instaluje jako pyyaml, importuje se jako yaml.

bash
pip install pyyaml
import yaml

text = """
nazev: Moje aplikace
port: 8080
debug: true
jazyky:
  - cs
  - en
databaze:
  host: localhost
  heslo: null
"""

nastaveni = yaml.safe_load(text)

print(type(nastaveni).__name__)
print(nastaveni["port"] + 1)
print(nastaveni["jazyky"][0])
print(nastaveni["databaze"]["host"])
print(nastaveni["databaze"]["heslo"])
Výstup
dict
8081
cs
localhost
None

yaml.safe_load udělá z textu běžné pythonovské objekty: slovníky, seznamy, čísla, texty. Žádnou novou datovou strukturu se učit nemusíš. port je rovnou číslo a true je True.

Syntaxe v pěti minutách

Dvojtečka a mezera tvoří dvojici klíč a hodnota. Pomlčka a mezera tvoří položku seznamu. Vnoření určuje odsazení mezerami. Znak # uvozuje komentář, a právě komentáře jsou velká výhoda proti JSONu.

yaml
# Web server settings
server:
  host: 0.0.0.0
  port: 8080

# A list of dictionaries
uzivatele:
  - jmeno: Eva
    role: admin
  - jmeno: Petr
    role: host

# The short form, same as in JSON
barvy: [cerna, bila]
limity: {cpu: 2, pamet: 512}

Delší text se zapisuje dvěma způsoby. | zachová zalomení řádků, > je nahradí mezerami. Hodí se to na skripty nebo šablony e-mailů.

import yaml

text = """
skript: |
  echo start
  echo konec
popis: >
  Tenhle text je v souboru
  na dvou řádcích.
bez_konce: |-
  Poslední zalomení zmizí.
"""

data = yaml.safe_load(text)
print(repr(data["skript"]))
print(repr(data["popis"]))
print(repr(data["bez_konce"]))
Výstup
'echo start\necho konec\n'
'Tenhle text je v souboru na dvou řádcích.\n'
'Poslední zalomení zmizí.'

Z reálného souboru se čte stejně, jen místo textu předáš otevřený soubor. Kódování uveď vždy, jinak ti na Windows rozbije diakritiku.

from pathlib import Path
import yaml

Path("nastaveni.yaml").write_text("mesto: Plzeň\npocet: 3\n", encoding="utf-8")

with open("nastaveni.yaml", encoding="utf-8") as soubor:
    data = yaml.safe_load(soubor)

print(data)
Výstup
{'mesto': 'Plzeň', 'pocet': 3}

Chyby v souboru jsou výjimky typu yaml.YAMLError. Většina nese i polohu, takže uživateli můžeš říct přesně, kde se spletl. Řádky se v ní počítají od nuly.

import yaml

spatne = """
server:
  port: 8080
    host: localhost
"""

try:
    yaml.safe_load(spatne)
except yaml.YAMLError as chyba:
    misto = chyba.problem_mark
    print(type(chyba).__name__)
    print(chyba.problem)
    print("řádek", misto.line + 1, "sloupec", misto.column + 1)

print(yaml.safe_load(""))
print(yaml.safe_load("# jen komentář") or {})
Výstup
ScannerError
mapping values are not allowed here
řádek 4 sloupec 9
None
{}
Úkol

Výchozí hodnoty

Doplň funkci nacti_nastaveni(text). Načte YAML z textu a vrátí slovník, ve kterém jsou výchozí hodnoty z VYCHOZI přepsané tím, co je v textu. Prázdný text vrátí výchozí hodnoty. Slovník VYCHOZI se nesmí změnit.

import yaml

VYCHOZI = {"host": "localhost", "port": 8000, "debug": False}

def nacti_nastaveni(text):
    return yaml.safe_load(text)
Výstup

Pasti: když YAML ví lépe než ty

YAML si typ hodnoty domýšlí podle toho, jak vypadá. Většinou pomáhá, někdy tropí hlouposti. PyYAML se drží starší verze standardu, YAML 1.1, a ta je v domýšlení obzvlášť horlivá.

import yaml

text = """
zeme: NO
odpoved: yes
svetlo: off
verze: 1.10
kod: 010
delka: 1:30
datum: 2026-03-01
velke: 1e3
"""

for klic, hodnota in yaml.safe_load(text).items():
    print(f"{klic:8} {hodnota!r}")
Výstup
zeme     False
odpoved  True
svetlo   False
verze    1.1
kod      8
delka    90
datum    datetime.date(2026, 3, 1)
velke    '1e3'

Norsko se proměnilo v False, verze 1.10 v číslo 1.1, 010 je osmičkově 8 a 1:30 se přečetlo jako šedesátková soustava, tedy 90. Datum je objekt date. A zápis 1e3, který bys čekal jako číslo, zůstal textem, protože PyYAML u exponentu vyžaduje tečku.

Lék je jednoduchý: co má být text, dej do uvozovek.

import yaml

text = """
zeme: "NO"
verze: "1.10"
kod: "010"
delka: "1:30"
"""

print(yaml.safe_load(text))
Výstup
{'zeme': 'NO', 'verze': '1.10', 'kod': '010', 'delka': '1:30'}
Úkol

Zachraň Norsko

Uprav text v proměnné text tak, aby se všechny tři hodnoty načetly jako řetězce přesně v tomto tvaru: NO, 3.10, 08:30.

import yaml

text = """
zeme: NO
python: 3.10
otevreno: 08:30
"""

data = yaml.safe_load(text)
print(data)
Výstup
Kvíz

Co vrátí yaml.safe_load("verze: 1.20")?

safe_load, nebo load?

Plný YAML umí víc než data. Značkami jako !!python/object/apply může říct, ať se při načítání zavolá funkce. Cizí soubor by tak mohl spustit libovolný příkaz. safe_load tyhle značky odmítá.

import yaml

utok = "!!python/object/apply:os.system ['echo napadeno']"

try:
    yaml.safe_load(utok)
except yaml.YAMLError as chyba:
    print(type(chyba).__name__)
    print(chyba.problem)
Výstup
ConstructorError
could not determine a constructor for the tag 'tag:yaml.org,2002:python/object/apply:os.system'

Zvyk je tedy jednoduchý: vždy yaml.safe_load. Samotné yaml.load(text) bez uvedeného loaderu dnes skončí chybou TypeError, a loadery UnsafeLoader nebo FullLoader na běžnou konfiguraci nepotřebuješ.

Kvíz

Dostaneš YAML soubor od cizího člověka. Čím ho načteš?

Zápis do YAML

Opačný směr obstará yaml.safe_dump. Výchozí nastavení není pro češtinu příjemné: klíče seřadí podle abecedy a diakritiku převede na kódy. Tyhle dva parametry si proto zapamatuj.

import yaml

data = {"zeme": "Česko", "aktivni": True, "kod": "NO", "mesta": ["Brno", "Třeboň"], "limit": None}

print(yaml.safe_dump(data))
print(yaml.safe_dump(data, allow_unicode=True, sort_keys=False))
Výstup
aktivni: true
kod: 'NO'
limit: null
mesta:
- Brno
- "T\u0159ebo\u0148"
zeme: "\u010Cesko"

zeme: Česko
aktivni: true
kod: 'NO'
mesta:
- Brno
- Třeboň
limit: null

Všimni si, že "NO" knihovna sama uzavřela do uvozovek, aby se po načtení nezměnilo v False. Při zápisu do souboru předej otevřený soubor jako druhý argument a znovu nezapomeň na encoding="utf-8".

import yaml

data = {"nazev": "Žluťoučký kůň", "porty": [80, 443]}

with open("vystup.yaml", "w", encoding="utf-8") as soubor:
    yaml.safe_dump(data, soubor, allow_unicode=True, sort_keys=False)

with open("vystup.yaml", encoding="utf-8") as soubor:
    print(soubor.read())
    soubor.seek(0)
    print(yaml.safe_load(soubor) == data)
Výstup
nazev: Žluťoučký kůň
porty:
- 80
- 443

True

Konfigurace, která přežije provoz

Osvědčené pořadí je: výchozí hodnoty v kódu, přes ně soubor, přes něj proměnné prostředí. Proměnné prostředí jsou pojmenované hodnoty, které programu předává systém nebo hostingová služba. Hesla patří tam nebo do správce tajemství, ne do souboru v Gitu.

Vnořené slovníky se ale obyčejným {**a, **b} nesloučí, celý podslovník by se nahradil. Proto rekurzivní funkce. Prostředí tady předáváme jako obyčejný slovník, doma tam dáš os.environ.

import yaml

VYCHOZI = {
    "server": {"host": "127.0.0.1", "port": 8000},
    "log": {"uroven": "INFO"},
}

def sluc(zaklad, zmeny):
    vysledek = dict(zaklad)
    for klic, hodnota in zmeny.items():
        if isinstance(hodnota, dict) and isinstance(vysledek.get(klic), dict):
            vysledek[klic] = sluc(vysledek[klic], hodnota)
        else:
            vysledek[klic] = hodnota
    return vysledek

def over(cfg):
    port = cfg["server"]["port"]
    if not isinstance(port, int) or isinstance(port, bool) or not 1 <= port <= 65535:
        raise ValueError(f"server.port musí být číslo 1 až 65535, je tam {port!r}")
    return cfg

def nacti(text, prostredi):
    cfg = sluc(VYCHOZI, yaml.safe_load(text) or {})
    if "APP_PORT" in prostredi:
        cfg["server"]["port"] = int(prostredi["APP_PORT"])
    return over(cfg)

soubor = """
server:
  host: 0.0.0.0
"""

print(nacti(soubor, {}))
print(nacti(soubor, {"APP_PORT": "9000"})["server"])

try:
    nacti("server: {port: 'osmdesat'}", {})
except ValueError as chyba:
    print("Chyba konfigurace:", chyba)
Výstup
{'server': {'host': '0.0.0.0', 'port': 8000}, 'log': {'uroven': 'INFO'}}
{'host': '0.0.0.0', 'port': 9000}
Chyba konfigurace: server.port musí být číslo 1 až 65535, je tam 'osmdesat'

Kontrola při startu je levná pojistka. Program spadne hned se srozumitelnou hláškou, a ne až ve tři ráno při prvním použití špatné hodnoty. U větších projektů tuhle práci převezme třeba knihovna pydantic.

Úkol

Hluboké sloučení

Doplň funkci sluc(zaklad, zmeny). Vrátí nový slovník. Hodnoty ze zmeny mají přednost. Když je pod stejným klíčem na obou stranách slovník, sloučí se rekurzivně. Vstupní slovníky se nesmí změnit.

def sluc(zaklad, zmeny):
    return {**zaklad, **zmeny}
Výstup

YAML není jediná možnost a pro jednoduchou konfiguraci často ani ta nejlepší.

FormátKomentářeV PythonuKde se hodí
JSONnejson, čtení i zápisvýměna dat mezi programy
TOMLanotomllib, jen čteníkonfigurace aplikací, pyproject.toml
INIanoconfigparserjednoduchá plochá nastavení
YAMLanopyyaml, nutno doinstalovathluboce vnořené konfigurace, DevOps
.envanoos.environ, python-dotenvtajné a na prostředí závislé hodnoty
import configparser
import tomllib

toml_text = """
[server]
port = 8080
jazyky = ["cs", "en"]
"""
print(tomllib.loads(toml_text)["server"])

ini = configparser.ConfigParser()
ini.read_string("[server]\nport = 8080\n")
print(repr(ini["server"]["port"]))
print(repr(ini["server"].getint("port")))
Výstup
{'port': 8080, 'jazyky': ['cs', 'en']}
'8080'
8080

TOML má jasné typy a řetězce musí být v uvozovkách, takže se v něm Norsko neztratí. INI vrací všechno jako text a převod je na tobě.

Pod kapotou · kotvy, duplicity a výkon

Kotvy. &jmeno označí uzel, *jmeno na něj odkáže a << (rozšíření YAML 1.1) ho vmíchá do slovníku. Po načtení jde o stejný objekt, takže změna přes jeden klíč se projeví i u druhého. Stejně to funguje obráceně: safe_dump u objektu použitého dvakrát sám vypíše &id001 a *id001, což bývá nečekané. Předejdeš tomu kopií, nebo podtřídou SafeDumper s ignore_aliases = lambda self, data: True.

Billion laughs. Vnořené aliasy dovolí z pár řádků popsat obří strukturu. Při načtení se díky sdílení nic nerozbalí, takže safe_load projde rychle. Exploze přijde až při průchodu nebo serializaci (ukázka níže). U nedůvěryhodného vstupu proto nestačí „mám safe_load“: omez velikost vstupu a hloubku, nebo aliasy zakaž.

Duplicitní klíče. Specifikace je zakazuje, PyYAML je ale tiše přijme a vyhraje poslední. Při slučování ručně psaných souborů z toho vznikají chyby, které se špatně hledají, a pomůže vlastní loader.

YAML 1.1 a 1.2. Verze 1.2 omezila booleany na true a false a zrušila šedesátková čísla. PyYAML zůstává u 1.1, ruamel.yaml používá ve výchozím stavu 1.2. Totéž no tak může v různých nástrojích znamenat různé věci. Proto uvozovky i tam, kde zrovna nevadí.

Výkon. Čistě pythonovský SafeLoader je pomalý. Když je k dispozici libyaml (yaml.__with_libyaml__), použij yaml.load(f, Loader=yaml.CSafeLoader). Chybové hlášky se mohou mírně lišit.

import json
import yaml

class StrictLoader(yaml.SafeLoader):
    def construct_mapping(self, node, deep=False):
        seen = set()
        for key_node, _ in node.value:
            if key_node.tag == "tag:yaml.org,2002:merge":
                continue
            key = self.construct_object(key_node, deep=True)
            if key in seen:
                raise yaml.constructor.ConstructorError(
                    None, None, f"duplicate key {key!r}", key_node.start_mark)
            seen.add(key)
        return super().construct_mapping(node, deep)

dvakrat = "port: 80\nhost: a\nport: 443\n"
print(yaml.safe_load(dvakrat))
try:
    yaml.load(dvakrat, Loader=StrictLoader)
except yaml.YAMLError as chyba:
    print(chyba.problem, "na řádku", chyba.problem_mark.line + 1)

bomba = """
a: &a [x, x, x, x, x, x]
b: &b [*a, *a, *a, *a, *a, *a]
c: &c [*b, *b, *b, *b, *b, *b]
d: &d [*c, *c, *c, *c, *c, *c]
"""
data = yaml.safe_load(bomba)
print(data["b"][0] is data["a"])
print(len(bomba), "znaků YAML ->", len(json.dumps(data)), "znaků JSON")

spolecne = [1, 2]
print(yaml.safe_dump({"prvni": spolecne, "druhy": spolecne}))
Výstup
{'port': 443, 'host': 'a'}
duplicate key 'port' na řádku 3
True
119 znaků YAML -> 8410 znaků JSON
druhy: &id001
- 1
- 2
prvni: *id001