Příručka:Konvence pro psaní kódu/Python

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.

Python 2.7 již není udržován od roku 2020.

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 setup.py a využít knihovnu nazvanou "distribute". Existují moduly, které za vás vygenerují strukturu základního projektu, zastaralý je paster create, 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

importosimportreimportsysimportpymongofromsqlalchemyimportcreate_engine,exceptionsfrommymoduleimportMyCustomException,models,views

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

importsys,os# importování různých modulů na stejném řádkufromsqlalchemyimport*# neimportujte *from.modelsimportutil# místo relativních importů používejte plně kvalifikované názvy

Příklad rozšířeného importu

Zde je podrobnější abstrahovaná verze (komentáře jsou pouze pro účely vysvětlení):

# Úplný import modulů na stdlib, v abecedním pořadíimporta_stdlib_moduleimportb_stdlib_module# Import submodulů modulů stdlib, v abecedním pořadí jak svisle, tak vodorovněfromanother_stdlib_moduleimporta_stdlib_submodule,b_stdlib_submodulefromc_stdlib_moduleimportanother_stdlib_submodule,last_stdlib_submodule# Úplný import modulů třetích stran v abecedním pořadíimporta_third_party_moduleimportb_third_party_module# Importy submodulů modulů třetích stran v abecedním pořadí vertikálně i horizontálněfromanother_third_party_moduleimporta_third_submodule,b_third_submodulefromc_third_party_moduleimportanother_third_submodule,last_third_submodule# Úplný import aktuálních aplikačních modulů v abecedním pořadí a s absolutními importyimportmyapp.a_moduleimportmyapp.b_module# Importy submodulů aktuálních aplikačních modulů v abecedním pořadí vertikálně i horizontálněfrommy_app.another_moduleimporta_submodule,b_submodulefrommy_app.c_moduleimportanother_submodule,last_submodule

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

deffractionize(first,second=1):""" Vytvořte řetězcovou reprezentaci zlomku dvou čísel. Argumenty klíčových slov: first -- čitatel second -- jmenovatel (cokoli kromě 0) """return"{0} / {1}"%(first,second)

To umožňuje automaticky generovat dokumenty a také používat vestavěnou funkci help 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.

defparse(source:"the original document",lang:"jaká syntaxe značek se používá? [md|rst|textile]",force:"Ignorovat syntaktické chyby?"):

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 hash a id), které můžete chtít použít ve svém kódu. PEP8 způsob, jak se vypořádat s těmito konflikty, je připojením podtržítka k názvu, například hash_ nebo class_ (i když pokud pojmenováváte proměnnou class_, může to být smell kód).

Pokud se ocitnete v konfliktu s názvem některé části jiného modulu, import as je váš přítel.

fromsqlalchemyimportexceptionsassa_exceptionsfrommymoduleimportexceptionsasmy_exceptions

Související odkazy

• Pokyny pro vývoj Pywikibota
• Oficiální webová stránka