Norma para desarrollos Python

Ámbito de aplicación de la norma

Esta norma es de aplicación tanto para nuevos desarrollos como mantenimientos de productos software que se realicen en lenguaje Python.

Las directrices que contiene la norma son independientes de la pila tecnológica utilizada para el desarrollo de la solución software.

Al implementar un sistema utilizando este lenguaje deben tenerse en cuenta:

• Las directrices y estándares referidos en esta norma.
• Otras normas específicas a la arquitectura o arquitecturas que apliquen a los componentes software del sistema.
• Normas transversales que aplican a cualquier desarrollo como seguridad u observabilidad.

Puedes conocer en esta sección  cómo se marca la obligatoriedad de cumplimiento de las directrices que componen la norma.

Versión y utilización de python

NOR_PYTHON_01 Versión de Python

OBLIGATORIO Se debe utilizar la versión de Python definida en la pila tecnológica corporativa:

https://desarrollo.juntadeandalucia.es/recursos/reglas-pautas/norma-alineamiento-pila-tecnologica

Estructura del proyecto

NOR_PYTHON_02 Repositorios autorizados

OBLIGATORIO Se deben obtener las dependencias del proyecto exclusivamente desde los siguientes repositorios autorizados:

• Repositorio de artefactos corporativo: repositorio establecido en la Norma de gestión de artefactos, que debe utilizarse como origen de las dependencias en los proyectos que se construyan y desplieguen a través de cadena única.
• Python Package Index (PyPI): repositorio oficial del ecosistema Python, disponible en https://pypi.org/, para el resto de casos.

No se deben instalar dependencias desde índices o repositorios no oficiales, URL de repositorios de código o ficheros locales, salvo justificación técnica expresa y aprobada. Cabe señalar que PyPI es el repositorio donde se publican las dependencias y no el gestor que las instala, que se regula en NOR_PYTHON_07.

NOR_PYTHON_03 Estructura estándar del repositorio

OBLIGATORIO Se debe organizar el proyecto con una estructura clara, coherente y predecible, separando explícitamente el código de producción, las pruebas, la documentación y los recursos auxiliares.

Como referencia general, se recomienda una estructura equivalente a la siguiente:

proyecto-python/
+-- pyproject.toml
+-- poetry.lock / uv.lock
+-- README.md
+-- CHANGELOG.md
+-- NOTICE.txt
+-- LICENSE.txt
+-- .gitignore
+-- src/
|   +-- nombre_paquete/
+-- tests/
+-- docs/
+-- scripts/
+-- resources/

• pyproject.toml: actuará como descriptor principal del proyecto, al constituir el mecanismo estándar del ecosistema Python para la definición de metadatos, configuración de construcción, dependencias y herramientas asociadas.
• poetry.lock / uv.lock: fichero de bloqueo generado por el gestor de dependencias utilizado. Deberá incluirse en el control de versiones, conforme a NOR_PYTHON_06.
• README.md: deberá incluir la información funcional, técnica y de despliegue necesaria para facilitar la comprensión, instalación, uso y mantenimiento del proyecto por parte de los desarrolladores.
• CHANGELOG.md: deberá recoger los cambios introducidos en cada versión del software, manteniendo un historial de las modificaciones realizadas. Se recomienda su elaboración siguiendo las buenas prácticas definidas por Keep a Changelog.
• NOTICE.txt: deberá incorporarse cuando sea necesario incluir avisos, atribuciones, información legal complementaria o condiciones de distribución aplicables al software o a cualquiera de sus dependencias.
• LICENSE.txt: salvo que la dirección competente establezca expresamente otra licencia, el software publicado por la Junta de Andalucía deberá distribuirse, con carácter general, bajo la licencia EUPL v1.2.

NOR_PYTHON_04 Configuración de .gitignore

OBLIGATORIO Se debe configurar el fichero .gitignore para excluir del control de versiones los entornos virtuales, dependencias instaladas localmente, cachés, artefactos generados y cualquier otro fichero reconstruible a partir de los elementos versionados del proyecto.

NOR_PYTHON_05 Entorno aislado de ejecución

OBLIGATORIO Se debe construir, probar y ejecutar la aplicación en un entorno Python aislado del sistema operativo.

El entorno debe ser reproducible, utilizar una versión explícita de Python y permitir la instalación de todas las dependencias definidas por el proyecto sin depender de configuraciones locales del equipo de desarrollo.

NOR_PYTHON_06 Dependencias reproducibles

OBLIGATORIO Se deben declarar las dependencias de construcción, prueba y ejecución en pyproject.toml garantizando una instalación reproducible. Se deben fijar las versiones exactas de todas las dependencias, evitando rangos de versiones abiertos, mediante el fichero de bloqueo generado por el gestor de dependencias (uv.lock, poetry.lock) o, cuando se utilice pip u otro gestor sin fichero de bloqueo, mediante la declaración de versiones exactas (==). El fichero de bloqueo debe incluirse en el control de versiones. Asimismo, se deben respetar las restricciones definidas por la pila tecnológica corporativa.

Excepción: los proyectos Python existentes con anterioridad a la publicación de esta norma que declaren sus dependencias en un fichero requirements.txt podrán mantenerlo en lugar de pyproject.toml, siempre que todas las dependencias se declaren con versiones exactas (==). Para su integración en cadena única deberán adaptarse previamente a pyproject.toml, ya que este fichero es el que permite identificar el componente (nombre y versión) en la cadena de integración y despliegue.

NOR_PYTHON_07 Gestor de paquetes y dependencias

OBLIGATORIO Se debe utilizar uno de los gestores de paquetes y dependencias permitidos en esta directriz para la creación del entorno aislado y la resolución e instalación de las dependencias del proyecto.

RECOMENDADO Se recomienda utilizar Poetry como gestor de paquetes y dependencias de referencia. Poetry se basa en pyproject.toml, genera el fichero de bloqueo poetry.lock y es el gestor con el que está implementada actualmente la integración de proyectos Python en cadena única.

Adicionalmente, se permite el uso de los siguientes gestores:

• uv: gestor de dependencias, entornos virtuales y versiones de Python basado en pyproject.toml, con fichero de bloqueo uv.lock.
• Hatch: gestor de proyectos, entornos y empaquetado basado en pyproject.toml. Cuando no se disponga de fichero de bloqueo, las versiones exactas de las dependencias deben declararse explícitamente conforme a NOR_PYTHON_06.
• pip y venv: herramientas estándar incluidas en la distribución oficial de Python.

Se debe utilizar un único gestor por proyecto y documentar en el README.md los comandos necesarios para crear el entorno e instalar las dependencias. Los gestores indicados son alternativos entre sí: el gestor elegido debe utilizarse para todas las operaciones sobre el entorno y las dependencias, sin combinarlo con instalaciones directas mediante pip que no queden reflejadas en pyproject.toml y en el fichero de bloqueo. El uso de cualquier otro gestor requerirá justificación técnica expresa y aprobada.

NOR_PYTHON_08 Uso mínimo de __init__.py

OBLIGATORIO Se debe utilizar __init__.py para declarar paquetes, exportar símbolos de forma controlada o incorporar metadatos mínimos del paquete.

Se debe mantener este fichero libre de lógica de negocio, conexiones externas, cálculos costosos o inicializaciones con efectos laterales relevantes.

Diseño de aplicaciones

NOR_PYTHON_09 Framework para la exposición de APIs

OBLIGATORIO Se debe utilizar FastAPI como framework de referencia para el desarrollo de microservicios con exposición de API, como APIs REST, servicios de inferencia o automatizaciones expuestas como servicio.

Se deben utilizar los mecanismos nativos del framework para el enrutamiento, validación, serialización, gestión de errores, inyección de dependencias y generación de documentación OpenAPI.

Esta directriz se limita a los componentes que exponen APIs y no restringe el uso de otros frameworks o librerías en desarrollos Python de distinta naturaleza, como procesamiento de datos, procesos batch o soluciones de inteligencia artificial, que se regirán por las normas y arquitecturas de referencia que les resulten de aplicación.

Desarrollo de aplicaciones

NOR_PYTHON_10 Convenciones de nombrado y estilo

OBLIGATORIO Se debe seguir una convención de estilo homogénea y reconocible en todo el código fuente.

Se recomienda alinear el código con las convenciones definidas por PEP 8, salvo justificación técnica o estándares corporativos en sentido contrario.

NOR_PYTHON_11 Formateo y análisis estático de código

RECOMENDADO Se recomienda utilizar Ruff como herramienta de formateo y análisis estático (linter) del código fuente, definiendo su configuración en pyproject.toml para que las reglas se apliquen de forma homogénea en todo el proyecto y facilitar el cumplimiento de las convenciones de estilo indicadas en NOR_PYTHON_10.

Se recomienda integrar su ejecución en el proceso de integración continua del proyecto.

NOR_PYTHON_12 Imports claros y estables

OBLIGATORIO Los imports deben ser explícitos y estar agrupados en este orden: librería estándar, dependencias de terceros y módulos propios del proyecto. No está permitido el uso de imports con comodines (from modulo import *), salvo casos excepcionales debidamente justificados.

NOR_PYTHON_13 Modelado explícito de datos

RECOMENDADO Se recomienda modelar los datos estructurados mediante clases, dataclasses o esquemas equivalentes cuando ello mejore la claridad, mantenibilidad y definición de los contratos de la aplicación.

RECOMENDADO Se recomienda utilizar Pydantic para la definición y validación de los modelos de datos de entrada y salida, especialmente en los servicios desarrollados con FastAPI, que lo integra de forma nativa para la validación y serialización de datos.

NOR_PYTHON_14 Tipado estático

OBLIGATORIO Se deben utilizar anotaciones de tipo en interfaces públicas, modelos de entrada y salida, funciones complejas y componentes críticos del sistema.

NOR_PYTHON_15 Docstrings y comentarios

OBLIGATORIO Se debe documentar mediante docstrings los módulos, clases y funciones públicas cuyo propósito, comportamiento o uso no resulte evidente.

OBLIGATORIO Se debe utilizar comentarios para describir decisiones de diseño, restricciones o aspectos relevantes que no puedan deducirse fácilmente del código.

NOR_PYTHON_16 Licencia del proyecto

OBLIGATORIO La licencia del proyecto se debe declarar a nivel de proyecto, mediante el fichero LICENSE.txt indicado en NOR_PYTHON_03 y el campo license de pyproject.toml.

No es necesario incluir cabeceras de licencia ni de metadatos en cada fichero de código. La descripción de cada módulo se recoge en su docstring, conforme a NOR_PYTHON_15, y la autoría, fechas y versiones de los cambios quedan registradas en el repositorio de código.

NOR_PYTHON_17 Cohesión de funciones y clases

OBLIGATORIO Se debe asignar una única responsabilidad principal a cada función, clase y módulo, manteniendo una separación clara entre lógica de negocio, acceso a datos e infraestructura.

Se recomienda evitar dependencias de variables globales mutables y recursos compartidos sin una gestión explícita de su ciclo de vida.

NOR_PYTHON_18 Uso seguro de argumentos por defecto

OBLIGATORIO Se debe utilizar None como valor por defecto cuando un parámetro requiera un objeto mutable, creando la instancia correspondiente dentro de la función o método.

NOR_PYTHON_19 Ausencia de efectos laterales durante la importación

OBLIGATORIO El código que se ejecuta al importar un módulo debe limitarse a declaraciones (funciones, clases y constantes) y configuraciones ligeras. Las operaciones con efectos laterales o con un coste relevante se deben ejecutar de forma explícita desde funciones o desde los mecanismos de arranque de la aplicación, como el evento lifespan de FastAPI. Entre estas operaciones se incluyen abrir conexiones a bases de datos o a servicios externos, cargar ficheros o modelos de gran tamaño, procesar datos o modificar el entorno.

De este modo, importar un módulo no provoca efectos inesperados, se facilita la ejecución de pruebas y se reduce el tiempo de arranque de la aplicación.

NOR_PYTHON_20 Uso de logging para el registro de eventos

OBLIGATORIO Se debe realizar el registro de eventos, trazas y errores mediante los mecanismos de logging y observabilidad definidos para el proyecto.

Se debe evitar el uso de print() como mecanismo de registro del comportamiento de la aplicación.

NOR_PYTHON_21 Gestión segura de recursos

OBLIGATORIO Se debe gestionar eficientemente la utilización de ficheros, conexiones, transacciones, bloqueos y otros recursos compartidos, garantizando su correcta liberación.

NOR_PYTHON_22 Ejecución y deserialización segura

OBLIGATORIO Se deben utilizar mecanismos seguros para procesar datos externos, restringiendo la ejecución dinámica de código y la deserialización de objetos a escenarios controlados y datos confiables y validados.

NOR_PYTHON_23 Coherencia síncrona y asíncrona

OBLIGATORIO Se debe mantener una estrategia coherente de programación síncrona o asíncrona en las capas críticas de la aplicación, evitando llamadas bloqueantes en flujos asíncronos salvo justificación técnica.

Gestión de errores

NOR_PYTHON_24 Clasificación de errores

OBLIGATORIO Se debe distinguir explícitamente entre errores de negocio y errores técnicos para aplicar un tratamiento adecuado a cada tipo de incidencia.

NOR_PYTHON_25 Gestión adecuada de excepciones

OBLIGATORIO Se deben gestionar las excepciones de forma explícita, capturando preferentemente excepciones específicas, registrándolas cuando corresponda y propagándolas cuando no puedan resolverse en la capa actual.

NOR_PYTHON_26 Conservación del contexto del error

RECOMENDADO Se recomienda conservar el contexto de la excepción original cuando se transforme o propague una excepción hacia capas superiores.

NOR_PYTHON_27 Gestión centralizada y mensajes a consumidores

OBLIGATORIO Se deben utilizar mecanismos centralizados para el tratamiento de errores proporcionados por el framework o la arquitectura de la solución.

Se deben proporcionar mensajes adecuados a usuarios y consumidores de APIs, evitando exponer detalles internos de implementación, configuración, infraestructura o seguridad.

Calidad

NOR_PYTHON_28 Separación entre código productivo y pruebas

OBLIGATORIO Se debe mantener el código de producción separado del código de prueba, evitando que este último forme parte del artefacto desplegable salvo justificación técnica expresa y aprobada.

NOR_PYTHON_29 Framework de pruebas unitarias

OBLIGATORIO Se debe utilizar pytest como framework de referencia para la implementación y ejecución de pruebas unitarias y ubicar las pruebas en el directorio tests/, replicando cuando sea útil la estructura del paquete definido en src/.

La versión de pytest debe declararse como dependencia de prueba en pyproject.toml y ajustarse a la versión establecida en la pila tecnológica corporativa.

El proyecto debe documentar en el README.md los comandos necesarios para instalar las dependencias de prueba y ejecutar la batería completa de pruebas.

NOR_PYTHON_30 Análisis de vulnerabilidades en dependencias

OBLIGATORIO Se deben analizar las vulnerabilidades conocidas de las dependencias del proyecto, directas y transitivas, mediante las herramientas de análisis integradas en cadena única antes de cualquier paso a producción.

RECOMENDADO Se recomienda analizar previamente el fichero de bloqueo en el entorno de desarrollo con OSV-Scanner, compatible con todos los gestores de dependencias permitidos en NOR_PYTHON_07.