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

import os
import re
import sys

import pymongo
from sqlalchemy import create_engine, exceptions

from mymodule import MyCustomException, models, views

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

import sys, os # importování různých modulů na stejném řádku
from sqlalchemy import * # neimportujte *
from .models import util # 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í
import a_stdlib_module
import b_stdlib_module

# Import submodulů modulů stdlib, v abecedním pořadí jak svisle, tak vodorovně
from another_stdlib_module import a_stdlib_submodule, b_stdlib_submodule
from c_stdlib_module import another_stdlib_submodule, last_stdlib_submodule

# Úplný import modulů třetích stran v abecedním pořadí
import a_third_party_module
import b_third_party_module

# Importy submodulů modulů třetích stran v abecedním pořadí vertikálně i horizontálně
from another_third_party_module import a_third_submodule, b_third_submodule
from c_third_party_module import another_third_submodule, last_third_submodule

# Úplný import aktuálních aplikačních modulů v abecedním pořadí a s absolutními importy
import myapp.a_module
import myapp.b_module

# Importy submodulů aktuálních aplikačních modulů v abecedním pořadí vertikálně i horizontálně
from my_app.another_module import a_submodule, b_submodule
from my_app.c_module import another_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

def fractionize(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.

def parse(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.

from sqlalchemy import exceptions as sa_exceptions
from mymodule import exceptions as my_exceptions

Související odkazy

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