View source for Manual:Coding conventions/Python/es

<languages/>
{{Shortcut|CC/PY|CC/Python}}
{{Development guideline}}
<div lang="en" dir="ltr" class="mw-content-ltr">
This page describes the '''coding conventions''' for '''Python''' projects that are a part of the MediaWiki project or supporting projects.
</div>

{{TOCRight}}
<div lang="en" dir="ltr" class="mw-content-ltr">
== Preamble ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
First, remember that code standards are only guidelines and can be violated if there is a good reason.
</div>

* <span lang="en" dir="ltr" class="mw-content-ltr">Aim for readability and obviousness over strict adherence for the sake of strict adherence.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Code is read much more often than it is written.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Be consistent with existing code, but use your best judgement.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If it isn't too hard to fix up the existing code, [[w:WP:BOLD|be bold]].</span>

<span lang="en" dir="ltr" class="mw-content-ltr">For anything not covered in this document, please refer to [http://www.python.org/dev/peps/pep-0008/ Python Enhancement Proposal 0008] for the general practice.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The following sections are for the most part a summary of the most commonly referred to parts of PEP8.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Python version ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The minimum supported version is 2.7, but in special cases it is okay to support older versions.
</div>

{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">Python 2.7 is no longer maintained [https://pythonclock.org as of 2020].</span>}}

<div lang="en" dir="ltr" class="mw-content-ltr">
If you have not already, you should change to Python 3 for local development.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Whitespace ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Lines should be indented with 4 spaces.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Lines at the end of files should end with a newline, just like every other line in the file.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">Try to keep lines under 80 characters long, but aim for readability and obviousness over strict adherence for the sake of strict adherence.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Shorter lines are just a general side effect of good idiomatic Python - short but properly scoped descriptive names, avoiding [http://stackoverflow.com/questions/4975457/python-preventing-if-staircases staircase code], etc.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">When splitting up lines, pick the most obviously unambiguous method possible for the situation.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Module structure ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The standard way to distribute Python modules is to create a <code>setup.py</code> file and leverage a library called "distribute".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">There are modules that will generate the structure of a base project for you, a deprecated one is <code>paster create</code> which is no longer maintained.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">A replacement is [https://pypi.python.org/pypi/pythong pythong].</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
In general module structure should look like this:
</div>

<pre>
newproject
├── bin
├── distribute_setup.py
├── docs
├── newproject
│     └── __init__.py
├── setup.py
└── tests
       ├── __init__.py
       └── newproject_tests.py
</pre>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Imports ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Within a file it's generally a good idea to organize your imports in some fashion.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Typically alphabetical order is favored, but this can become unwieldy when importing a large number of libraries.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">Standard library imports</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Third party imports</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Your library imports</span>

<syntaxhighlight lang="python">
import os
import re
import sys

import pymongo
from sqlalchemy import create_engine, exceptions

from mymodule import MyCustomException, models, views
</syntaxhighlight>

Aquí hay algunos patrones que hay que evitar:

<syntaxhighlight lang="python">
import sys, os # importing different modules on the same line
from sqlalchemy import * # don't import *
from .models import util # use fully qualified names instead of relative imports
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
====== Imports expanded example ======
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Here is a more detailed abstracted version (the comments are just for explanation purposes):
</div>

<syntaxhighlight lang="python">
# Full import of stdlib modules, in alphabetic order
import a_stdlib_module
import b_stdlib_module

# Submodules imports of stdlib modules, in alphabetic order both vertically and horizontally
from another_stdlib_module import a_stdlib_submodule, b_stdlib_submodule
from c_stdlib_module import another_stdlib_submodule, last_stdlib_submodule

# Full import of 3rd party modules, in alphabetic order
import a_third_party_module
import b_third_party_module

# Submodules imports of 3rd party modules, in alphabetic order both vertically and horizontally
from another_third_party_module import a_third_submodule, b_third_submodule
from c_third_party_module import another_third_submodule, last_third_submodule

# Full import of current application modules, in alphabetic order and with absolute imports
import myapp.a_module
import myapp.b_module

# Submodules imports of current application modules, in alphabetic order both vertically and horizontally
from my_app.another_module import a_submodule, b_submodule
from my_app.c_module import another_submodule, last_submodule
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Docstrings and function annotation ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Generally all but the simplest functions should have docstrings.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">These are standardized in [http://www.python.org/dev/peps/pep-0257/#multi-line-docstrings PEP 257]</span>

<syntaxhighlight lang="python">
def fractionize(first, second=1):
    """
    Make a string representation of a fraction of two numbers.

    Keyword arguments:
    first -- the top of the fraction
    second -- the bottom of the fraction (anything but 0)
    """
    return "{0} / {1}" % (first, second)
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
This makes it possible to automatically generate docs, as well as use Python's built-in <code>help</code> function.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
In Python 3.3 and above [http://www.python.org/dev/peps/pep-3107/ PEP 3107] specifies syntax for function annotations.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Function annotations do not have a completely set use case, but a common emerging case is for improved help docs and for type annotation.
</div>

<syntaxhighlight lang="python">
def parse(source: "the original document",
          lang: "what markup syntax is being used? [md|rst|textile]",
          force: "Ignore syntax errors?"):
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Naming conflicts ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Conflicting with builtins is a somewhat common problem.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">There are some builtin names (like <code>hash</code> and <code>id</code>) that you may want to use in your code.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The PEP8 way to deal with these conflicts is by appending an underscore to the name, such as <code>hash_</code> or <code>class_</code> (although if you're naming a variable <code>class_</code> that may be a code smell).</span>

<span lang="en" dir="ltr" class="mw-content-ltr">If you find yourself in conflict with the name of some part of another module, <code>import as</code> is your friend.</span>

<syntaxhighlight lang="python">
from sqlalchemy import exceptions as sa_exceptions
from mymodule import exceptions as my_exceptions
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== See also ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* [[Manual:Pywikibot/Development/Guidelines|Pywikibot Development Guidelines]]
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
* [https://www.python.org/ Official website]
</div>
{{Conventions navigation}}