Všichni milujeme Ansible, ale Ansible je YAML. Pro konfigurační soubory existuje řada formátů: seznamy hodnot, páry "parametr-hodnota", INI soubory, YAML, JSON, XML a mnoho dalších. Avšak z několika důvodů je z nich YAML často považován za obzvlášť složitý. Konkrétně, navzdory svému osvěžujícímu minimalismu a působivým schopnostem práce s hierarchickými hodnotami, může syntaktický styl YAML rozčilovat svým Pythonovským přístupem k odsazení.
Pokud vás YAML štve, můžete – a měli byste! – podniknout následujících 10 kroků, abyste snížili své podráždění na přijatelnou úroveň a objevili krásu YAML. Jak je obvyklé v pravém seznamu, naše desítka tipů bude očíslována od nuly, meditaci a duchovní praktiky přidáváme na přání 😉
0. Donuťte svůj editor pracovat
Bez ohledu na to, jaký máte textový editor – určitě pro něj existuje alespoň jeden plugin pro práci s YAML. Pokud ho nemáte, okamžitě jej najděte a nainstalujte. Čas strávený hledáním a nastavením se vám stokrát vrátí pokaždé, když budete muset editovat YAML.
Například editor podporuje YAML ve výchozím nastavení, zatímco pro GNU Emacs je potřeba nainstalovat další balíčky, například, .
Emacs v režimu YAML a zobrazení mezer.
Pokud váš oblíbený editor nemá režim YAML, část problémů lze vyřešit prací s nastavením. Například vestavěný textový editor GNOME Gedit nemá režim YAML, ale ve výchozím nastavení zvýrazňuje syntaxi YAML a umožňuje nakonfigurovat práci s odsazením:
Nastavení odsazení v Gedit.
A plugin pro Gedit zobrazuje mezery jako tečky, odstraňuje nejasnosti s úrovněmi odsazení.
Jinými slovy, věnujte čas studiu svého oblíbeného editoru. Zjistěte, co on sám nebo jeho vývojářská komunita nabízí pro práci s YAML, a využijte tyto možnosti. Určitě nebudete litovat.
1. Použijte linter
Ideálně programovací jazyky a jazyky pro značkování používají předvídatelnou syntaxi. Počítače si s předvídatelností dobře poradí, a proto již v roce 1978 vznikla koncepce Pokud vám za těch 40 let jeho existence unikla a stále nepoužíváte YAML linter, je nejvyšší čas vyzkoušet yamllint.
Nainstalovat můžete použít pomocí výchozího správce balíčků Linuxu. Například v 8 nebo to se to provádí takto:
$ sudo dnf install yamllint
Poté jednoduše spustíte yamllint a předáte mu YAML soubor k ověření. Takto to vypadá, pokud předáte linteru soubor s chybou:
$ yamllint errorprone.yaml
errorprone.yaml
23:10 error syntax error: mapping values are not allowed here
23:11 error trailing spaces (trailing-spaces)
Čísla vlevo nejsou čas, ale souřadnice chyby: číslo řádku a sloupce. Popis chyby vám možná nic neřekne, ale přesně víte, kde se nachází. Stačí se podívat na toto místo v kódu a pravděpodobně vše bude jasné.
Když yamllint nenajde v souboru žádné chyby, na obrazovku se nic nevypisuje. Pokud vás to ticho děsí a chcete trochu více zpětné vazby, můžete spustit linter s podmínkovým příkazem echo pomocí dvojité ampersandu (&&), takto:
$ yamllint perfect.yaml && echo "OK"
OK
V POSIX dvojitý ampersand funguje pouze tehdy, když předchozí příkaz vrátí 0. A yamllint vrací počet nalezených chyb, takže celá tato podmínková konstrukce funguje.
2. Pište v Pythonu, ne v YAML
Pokud vás YAML opravdu štve, prostě ho nepoužívejte, v doslovném smyslu. Někdy je YAML jediným formátem, který aplikace akceptuje. Ale i v tomto případě nemusíte vytvářet YAML soubor. Pište v tom, co se vám líbí, a pak to konvertujte. Například pro Python existuje skvělá knihovna a dva způsoby konverze: konverze přímo a konverze pomocí skriptů.
Konverze přímo
V tomto případě je soubor s daty zároveň Python skriptem, který generuje YAML. Tento způsob je nejvhodnější pro malé sady dat. Prostě zapíšete JSON data do proměnné Pythonu, přidáte direktivu import a na konci souboru přidáte tři řádky pro realizaci výstupu.
#!/usr/bin/python3
import yaml
d={
"glossary": {
"title": "example glossary",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Standard Generalized Markup Language",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "A meta-markup language, used to create markup languages such as DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "markup"
}
}
}
}
}
f=open('output.yaml','w')
f.write(yaml.dump(d))
f.close
Nyní spustíme tento soubor na Pythonu a na výstupu získáme soubor output.yaml:
$ python3 ./example.json
$ cat output.yaml
glossary:
GlossDiv:
GlossList:
GlossEntry:
Abbrev: ISO 8879:1986
Acronym: SGML
GlossDef:
GlossSeeAlso: [GML, XML]
para: A meta-markup language, used to create markup languages such as DocBook.
GlossSee: markup
GlossTerm: Standard Generalized Markup Language
ID: SGML
SortAs: SGML
title: S
title: example glossary
Jedná se o naprosto správný YAML, ale yamllint vydá varování, že nezačíná s –. No, to lze snadno opravit ručně nebo mírně vylepšit Python skript.
Konverze pomocí skriptů
V tomto případě nejprve píšeme v JSON-u a poté spustíme konvertor jako samostatný Python skript, který na výstupu poskytne YAML. Ve srovnání s předchozím je tento způsob lépe škálovatelný, protože je konverze oddělená od dat.
Nejdříve vytvoříme JSON soubor example.json, například si ho můžeme vzít z :
{
"glossary": {
"title": "příklady slovníku",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Standard Generalized Markup Language",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "Meta-markup jazyk, používaný k vytvoření markup jazyků jako je DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "markup"
}
}
}
}
}
Poté vytvoříme jednoduchý konverzní skript a uložíme ho pod názvem json2yaml.py. Tento skript importuje oba moduly — YAML a JSON Python, a také načítá soubor JSON zadaný uživatelem, provádí konverzi a zapisuje data do souboru output.yaml.
#!/usr/bin/python3
import yaml
import sys
import json
OUT=open('output.yaml','w')
IN=open(sys.argv[1], 'r')
JSON = json.load(IN)
IN.close()
yaml.dump(JSON, OUT)
OUT.close()
Uložte tento skript do systémové cesty a spouštějte podle potřeby:
$ ~/bin/json2yaml.py example.json
3. Parsujte hodně a často
Někdy je užitečné podívat se na problém z jiného úhlu. Pokud je pro vás těžké představit si vztahy mezi daty v YAML, můžete je dočasně převést na něco více známého.
Například, pokud vám vyhovuje pracovat se seznamy slovníků nebo s JSON, můžete YAML převést na JSON pouhými dvěma příkazy v interaktivní Python shellu. Předpokládejme, že máte YAML soubor mydata.yaml, pak to bude vypadat takto:
$ python3
>>> f=open('mydata.yaml','r')
>>> yaml.load(f)
{'document': 34843, 'date': datetime.date(2019, 5, 23), 'bill-to': {'given': 'Seth', 'family': 'Kenlon', 'address': {'street': '51b Mornington Roadn', 'city': 'Brooklyn', 'state': 'Wellington', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Dobrý článek. Mohl být lepší.'}
Na toto téma lze najít spoustu dalších příkladů. Kromě toho existuje mnoho online konvertorů a místních parserů. Takže se nebojte přeformátovat data, když v nich vidíte jen nesrozumitelnou směs.
4. Čtěte specifikace
Pokud se vracíte k YAML po dlouhé době, je užitečné navštívit a přečíst si specifikace. Pokud máte obtíže s YAML, ale k specifikaci jste se ještě nedostali, je čas tuto situaci napravit. Specifikace jsou překvapivě dobře napsané a požadavky na syntax jsou ilustrovány velkým množstvím příkladů v .
5. Pseudokonfigurace
Při psaní knihy nebo článku je vždy užitečné nejprve si vytvořit předběžný plán, alespoň ve formě osnovy. Totéž platí pro YAML. Pravděpodobně máte představu, jaká data byste měli zapsat do YAML souboru, ale nejste si jisti, jak je vzájemně propojit. Proto než začnete vytvářet YAML, nakreslete si pseudo-konfigurační soubor.
Pseudo-konfigurace podobná pseudo-kódu, kde není nutné se obávat struktury nebo odsazení, vztahů "rodič-potomek", dědění a zasazení. Také zde: vykreslujete iterace dat, jak se vám objevují v hlavě.
Pseudo-konfigurace s uvedením programátorů (Martin a Tabitha) a jejich dovedností (programovací jazyky: Python, Perl, Pascal a Lisp, Fortran, Erlang, resp.).
Když nakreslíte pseudo-konfigurační soubor na papír, důkladně jej analyzujte a pokud je vše v pořádku, uspořádejte ho do platného YAML souboru.
6. Dilema "tabulace vs. mezery"
Budete muset vyřešit dilema . Ne v globálním smyslu, ale pouze na úrovni vaší organizace, nebo alespoň projektu. Není důležité, zda se bude používat post-processing skriptem sed, nastavení textových editorů na strojích programátorů nebo celkové zavedení pokynů k přísnému dodržování směrnic linteru pod hrozbou propuštění, ale všichni členové vašeho týmu, kteří se jakýmkoli způsobem dotýkají YAML, by měli používat pouze mezery (jak přede psání standard YAML).
V jakémkoli normálním textovém editoru lze nastavit automatickou výměnu tabulace za stanovený počet mezer, takže se není třeba obávat vzpoury přívrženců klávesy Tab ,
Jak je dobře známé každému nepříteli YAML, na obrazovce není vidět rozdíl mezi tabulací a mezerami. A když něco není vidět, většinou si na to vzpomeneme až na poslední chvíli, poté, co jsme prozkoumali a vyřešili všechny ostatní možné problémy. Hodina strávená hledáním špatné tabulace nebo bloku mezer prostě volá po tom, abyste rychle vytvořili politiku používání toho či onoho, a poté zavedli železobetonovou kontrolu jejího dodržování (například prostřednictvím Git hook pro povinný běh skrze linter).
7. Raději méně, ale lépe (nebo více – to je méně)
Někteří lidé rádi píší v YAML, protože zdůrazňuje strukturu. Při tom aktivně využívají odsazení k vykreslení bloků dat. Je to taková forma podvodu na napodobení značkovacích jazyků, ve kterých se používají jasné oddělovače.
Zde je příklad takové strukturovanosti z :
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
Některým lidem tento způsob pomáhá rozložit v hlavě strukturu YAML, jiné to naproti tomu irituje množstvím zbytečných, podle jejich názoru, odsazení.
Ale pokud jste vlastníkem YAML dokumentu a odpovídáte za jeho údržbu, pak jen vy musíte určovat, jak používat odsazení. Pokud vás velká odsazení rozčilují, snižte je na minimum, které je možné podle specifikace YAML. Například výše uvedený soubor z dokumentace Ansible lze bez jakýchkoliv ztrát přepsat takto:
---
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
8. Používejte šablony
Pokud při vyplňování souboru YAML neustále opakujete stejné chyby, má smysl vložit do něj šablonu ve formě komentáře. Příště tak můžete tuto šablonu jednoduše zkopírovat a vložit do ní skutečná data, například:
---
# - <common name>:
# name: Given Surname
# job: JOB
# skills:
# - LANG
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
9. Použijte něco jiného
Pokud vás aplikace nedrží pevně v klíčích, možná by stálo za to přejít z YAML na jiný formát. Postupem času mohou konfigurační soubory přerůst samy sebe a v takovém případě je lepší je převést na jednoduché skripty v Lua nebo Pythonu.
YAML je skvělá věc, kterou mnozí ocení pro minimalismus a jednoduchost, ale není to jediný nástroj ve vaší výbavě. Takže se ho někdy dá vzdát. Pro YAML se snadno najdou parsingové knihovny, takže pokud nabídnete pohodlné možnosti migrace, vaši uživatelé tento odchod snesou relativně bez problémů.
Pokud se ale bez YAML opravdu neobejdete, vezměte si k srdci těchto 10 rad a přemoci svůj odpor k YAML jednou provždy!
Zdroj: habr.com
