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.

Try to keep lines under 80 characters long, but aim for readability and obviousness over strict adherence for the sake of strict adherence. Shorter lines are just a general side effect of good idiomatic Python - short but properly scoped descriptive names, avoiding staircase code, etc. When splitting up lines, pick the most obviously unambiguous method possible for the situation.

Module structure
The standard way to distribute Python modules is to create a  file and leverage a library called "distribute". There are modules that will generate the structure of a base project for you, a deprecated one is  which is no longer maintained. A replacement is pythong.

In general module structure should look like this:

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

Imports
Within a file it's generally a good idea to organize your imports in some fashion. Typically alphabetical order is favored, but this can become unwieldy when importing a large number of libraries. To help avoid this, it's good to separate out imports in this fashion, with each block separated from the others by an empty line:


 * Standard library imports
 * Third party imports
 * Your library imports

Here are some patterns to avoid:

Imports expanded example
Here is a more detailed abstracted version (the comments are just for explanation purposes):

Docstrings and function annotation
Generally all but the simplest functions should have docstrings. These are standardized in 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.