PythonCodingGuidelines
1.0.0
Las Pautas de codificación de Python son un conjunto de pautas, reglas y mejores prácticas probadas y verdaderas sobre la codificación en Python.
El objetivo de las directrices es ayudar a los desarrolladores a utilizar Python de forma eficaz y proporcionar un estilo Python moderno más legible. Un código que es fácilmente mantenible y escalable. Además, establecer un estándar de desarrollo a seguir al desarrollar aplicaciones o bibliotecas en Python.
Espero que este documento también pueda ayudarle a comenzar con Python. Si viene de otro lenguaje de scripting como JavaScript, encontrará que Python es muy similar y este documento es una forma de realizar la transición a Python.
Las pautas se centran en todos los recursos proporcionados por el lenguaje Python habitualmente definido en el estándar PEP8. PEP8 PEP8 aquí solo se utiliza como base para esta propuesta de guía de codificación. Quiero promover un estilo Python más legible y moderno.
Es posible que algunas de las reglas de esta guía sean contrarias a sus expectativas o incluso a su experiencia.
Si no te he sugerido que cambies tu estilo de codificación de alguna manera, ¡he fallado!
Intente verificar o refutar las reglas de esta guía. En particular, realmente me gustaría que algunas de las reglas propuestas estuvieran respaldadas con mediciones y mejores ejemplos.
Es una regla general del desarrollo de software crear aplicaciones que sean legibles, mantenibles y escalables. Esta no es siempre la verdad, pero apuntamos a este objetivo.
Los estándares de código son herramientas que ayudan a lograr la creación de aplicaciones con los principios de la tríada mencionados anteriormente. Estos son algunos de los beneficios que se obtienen al establecer un estándar de desarrollo consistente:
️ Advertencia: Este es un documento vivo en mejora continua. Comentarios y sugerencias de mejora son bienvenidos. Planeo modificar y ampliar este documento a medida que mejore nuestra comprensión y evolucione el lenguaje del conjunto de bibliotecas disponibles.
| Nombre | Convención | Ejemplo de código |
|---|---|---|
| nombre de variable única | caso_serpiente | age: int = 100 |
| nombre de variable compuesta | caso_serpiente | first_name: str = "Akira" |
| nombre constante | CONSTANTE | CPU: number = 8 |
| nombre constante compuesto | CONSTANTE | MAX_NUMBER: number = 100 |
| nombre de enumeración | PascalCaso | class Color(Enum): RED = 1 GREEN = 2 |
| nombre de la función | caso_serpiente | def main() |
| función con parámetros | caso_serpiente | def calculate(n1: int, n2: int) |
| función con tipo de retorno | caso_serpiente | def calculate(n1: int, n2: int) -> int: |
| nombre de la función compuesta | caso_serpiente | def add_two_numbers(n1: int, n2: int) -> int: |
| nombre de clase | PascalCaso | class Base |
| nombre de clase compuesta | PascalCaso | class MyClass |
| interfaces | PascalCaso | class IUser(ABC) |
| fundición | por defecto | age: int = int(100) |
| lista | camelloCaso | myList: list[int] = [1,2,3] |
| tupla | camelloCaso | myTuple: tuple[int] = (1,2,3) |
| colocar | caso_serpiente | my_set: set[int] = {1,2,3} |
| diccionario | caso_serpiente | my_dictionary: dict = {"name": "John", "age": 100} |
| sugerencias de tipos múltiples | caso_serpiente | var_a: Union[int, str] |
Propusimos utilizar Google Doc Style para la documentación de Python, ya que es el más fácil de leer y comprender. La guía de estilo de Google también es muy popular y ampliamente utilizada en la comunidad Python.
def add_binary ( a : int , b : int ) -> int :
"""
Returns the sum of two decimal numbers in binary format.
Parameters:
a (int): First number to add
b (int): Second number to add
Returns:
binary (int): Binary int of the sum of a and b
"""
binary_sum = bin ( a + b )[ 2 :]
return int ( binary_sum )La sugerencia de tipo es una solución formal para indicar estáticamente el tipo de valor.
Ejemplo:
def addBinary(a: int, b: int)-> int:
...
En esta función anterior, es explícito que la función espera el valor int en las variables a y b y devuelve el valor int .
Consulte este enlace: Documentación oficial de escritura en Python
¿Pero no es Python un lenguaje sin escribir? Sí, no lo es. Si pasa cualquier valor diferente de int , funciona.
¿Cómo verificar el tipo de golpe en Python?
Deberías usar la biblioteca mypy .
Mypy es un verificador de tipos estáticos opcional para Python que tiene como objetivo combinar los beneficios de la escritura dinámica (o "pato") y la escritura estática. (Fuente: Documentación Oficial)
pip install mypy
mypy mycode.py
La idea de utilizar linter para Python es hacer cumplir las pautas de codificación propuestas en este documento. Usaré Precommit.
pip install pre-commit
Configuración básica:
.pre-commit-config.yml para guardar las configuraciones previas a la confirmaciónEn el siguiente ejemplo, el script ejecutará estos pasos:
Ejemplo:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- id: check-json
- id: detect-private-key
- repo: https://github.com/PyCQA/isort
rev: 5.12.0
hooks:
- id: isort
- repo: https://github.com/psf/black
rev: 22.12.0
hooks:
- id: black
language_version: python3.10
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: 'v0.0.260'
hooks:
- id: ruff
pyproject.toml para guardar las configuraciones de los corredores previos a la confirmaciónEjemplo:
[tool.black]
line-length = 80
target-version = ['py310']
include = '.pyi?$'
[tool.isort]
line_length = 79
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true
Después de estas configuraciones, cada vez que realice una confirmación, se ejecutará la confirmación previa.
Documentación oficial previa al compromiso
El marco propuesto para las pruebas es pytest. También es un marco de prueba muy popular para Python.
tests : pytest
pytest --cov . 
Para obtener más comandos de pytest, siga la documentación oficial aquí pytest
A continuación se muestra un ejemplo de definición de función para una prueba:
Después de crear su función como se muestra en el siguiente ejemplo: 
Puedes crear tu prueba unitaria siguiendo estos pasos:
test_ en el nombre de la función.
Para comenzar un proyecto nuevo, puede clonar el proyecto usando el siguiente comando:
git clone https://github.com/rsaz/python-project-templateA continuación se muestra una estructura predeterminada del proyecto propuesta.
La estructura del proyecto se basa en lo siguiente:
| Carpeta/Archivo | Descripción |
|---|---|
| utiles | Scripts de PowerShell que permiten crear, activar, desactivar y eliminar entornos, así como actualizar y crear las dependencias. |
| .vscode | Configuración específica del editor |
| src | Carpeta fuente principal del proyecto |
| prueba | Carpeta que contiene todas las pruebas unitarias de la aplicación. |
| venv | Entorno virtual de Python |
| .pylintrc | Archivo de configuración para el analizador de código estático pylint para Python |
| pytest.ini | Archivo de configuración para pytest |
| LICENCIA.txt | Términos de la licencia del proyecto |
| LÉAME.md | Detalles del proyecto |
| requisitos.txt | Dependencias del proyecto |
| setup.cfg y setup.py | Configuración inicial del proyecto |
