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

This makes it possible to automatically generate docs, as well as use Python's built-in  function.

In Python 3.3 and above PEP 3107 specifies syntax for function annotations.

Function annotations do not have a completely set use case, but a common emerging case is for improved help docs and for type annotation.

Naming conflicts
Conflicting with builtins is a somewhat common problem. There are some builtin names (like  and  ) that you may want to use in your code. 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.