Manual:Coding conventions/Python/cs

Tato stránka popisuje kódovací konvence pro Python projekty, které jsou součástí projektu MediaWiki nebo podpůrných projektů.

Úvod
Nejprve si pamatujte, že standardy kódu jsou pouze pokyny a mohou být porušovány, pokud existuje dobrý důvod.


 * Zaměřte se na čitelnost a srozumitelnost před přísným dodržováním.
 * Kód se čte mnohem častěji, než je zapsán.
 * Buďte konzistentní s existujícím kódem, ale použijte svůj nejlepší úsudek. Pokud není příliš těžké opravit stávající kód, učiňte tak tučně.

Cokoli, co není zahrnuto v tomto dokumentu, naleznete v Python Enhancement Návrh 0008, kde najdete obecný postup. Následující části jsou z větší části shrnutím nejčastěji uváděných částí PEP8.



Verze Pythonu
Minimální podporovaná verze je 2.7, ale ve zvláštních případech je v pořádku podporovat starší verze.

Pokud jste to ještě neudělali, měli byste přejít na Python 3 pro místní vývoj.

Mezery
Řádky by měly být odsazeny 4 mezerami.

Řádky na konci souborů by měly končit novým řádkem, stejně jako každý jiný řádek v souboru.

Snažte se udržet řádky kratší než 80 znaků, ale snažte se o čitelnost a srozumitelnost před přísným dodržováním kvůli přísnému dodržování. Kratší řádky jsou jen obecným vedlejším efektem dobrého idiomatického Pythonu – krátké, ale správně vymezené popisné názvy, vyhýbající se stupňovitému kódu atd. Při rozdělování řádků vyberte nejzjevnější možnou metodu pro danou situaci.



Struktura modulu
Standardní způsob distribuce modulů Pythonu je vytvořit soubor  a využít knihovnu nazvanou "distribute". Existují moduly, které za vás vygenerují strukturu základního projektu, zastaralý je, který již není udržován. Náhrada je python.

Obecně by struktura modulu měla vypadat takto:

newproject ├── bin ├── distribute_setup.py ├── docs ├── newproject │    └── __init__.py ├── setup.py └── tests ├── __init__.py      └── newproject_tests.py

Importy
V rámci souboru je obecně dobré nějakým způsobem importy uspořádat. Obvykle je upřednostňováno abecední pořadí, ale to může být při importu velkého počtu knihoven nepraktické. Abyste tomu zabránili, je dobré oddělit importy tímto způsobem, přičemž každý blok je od ostatních oddělen prázdným řádkem:


 * Standardní importy knihoven
 * Importy třetích stran
 * Importy vaší knihovny

Zde je několik vzorů, kterým se vyhnout:



Příklad rozšířeného importu
Zde je podrobnější abstrahovaná verze (komentáře jsou pouze pro účely vysvětlení):



Dokumentační řetězce a anotace funkcí
Obecně by všechny funkce kromě těch nejjednodušších měly mít docstring. Ty jsou standardizovány v PEP 257

To umožňuje automaticky generovat dokumenty a také používat vestavěnou funkci  v Pythonu.

V Pythonu 3.3 a vyšších specifikuje PEP 3107 syntaxi pro anotace funkcí.

Anotace funkcí nemají úplně nastavený případ použití, ale častým případem, který se objevuje, jsou vylepšené dokumenty nápovědy a anotace typu.



Konflikty pojmenování
Konflikt s vestavěnými prvky je poněkud běžný problém. Existují některé vestavěné názvy (například  a  ), které můžete chtít použít ve svém kódu. The PEP8 way to deal with these conflicts is by appending an underscore to the name, such as  or   (although if you're naming a variable   that may be a code smell).

If you find yourself in conflict with the name of some part of another module,  is your friend.