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.
pip install pyyamlimport 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"])
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.
# 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"]))
'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)
{'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 {})
ScannerError
mapping values are not allowed here
řádek 4 sloupec 9
None
{}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)
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}")
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))
{'zeme': 'NO', 'verze': '1.10', 'kod': '010', 'delka': '1:30'}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)
Co vrátí yaml.safe_load("verze: 1.20")?
Hodnota vypadá jako desetinné číslo, takže se tak načte a koncová nula zmizí. Čísla verzí proto patří do uvozovek.
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)
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š.
Dostaneš YAML soubor od cizího člověka. Čím ho načteš?
safe_load vytváří jen základní typy. Načtení přes UnsafeLoader může spustit kód uložený v souboru.
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))
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)
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)
{'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.
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}
YAML není jediná možnost a pro jednoduchou konfiguraci často ani ta nejlepší.
| Formát | Komentáře | V Pythonu | Kde se hodí |
|---|---|---|---|
| JSON | ne | json, čtení i zápis | výměna dat mezi programy |
| TOML | ano | tomllib, jen čtení | konfigurace aplikací, pyproject.toml |
| INI | ano | configparser | jednoduchá plochá nastavení |
| YAML | ano | pyyaml, nutno doinstalovat | hluboce vnořené konfigurace, DevOps |
.env | ano | os.environ, python-dotenv | tajné 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")))
{'port': 8080, 'jazyky': ['cs', 'en']}
'8080'
8080TOML 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}))
{'port': 443, 'host': 'a'}
duplicate key 'port' na řádku 3
True
119 znaků YAML -> 8410 znaků JSON
druhy: &id001
- 1
- 2
prvni: *id001