Organice los archivos en una carpeta src con tests paralelos:

<proyecto>
├── src
│   ├── <paquete_principal>/*
│   │    ├── __init__.py
│   │    └── archivos.py
│   └── pruebas/*
│        └── tests.py
├── .gitignore
├── pyproject.toml
└── README.md

paquete_principal debe coincidir con el nombre usado en instalaciones (pip install mi_paquete) o imports (import mi_paquete).

Ventajas de Usar src

Evite estructuras planas que dispersan módulos:

proyecto_desorganizado
├── modulo_a/*  # ¡Problemático!
├── modulo_b/*
└── pruebas/*

La carpeta src centraliza el código, simplificando configuración de CI/CD y evitando conflictos de nombres en IDEs.

Convneciones de Nombres

Módulos

Use pluarles cuando corresponda:

proyecto_ejemplo/
└── src
    └── mi_proyecto
         ├── config.py 
         ├── controladores.py
         ├── entidades.py
         └── almacenamientos.py

Ejemplo de importación:

from mi_proyecto.almacenamientos import obtener_almacen
from mi_proyecto.entidades import Ubicacion

Funciones y Métodos

Usar verbos para acciones:

def obtener_pedidos(): ...
def procesar_evento(): ...
# Evitar: envio_email() → usar enviar_email()

Variables y Constantes

Usar sustantivos, plural para colecciones:

avion = Avion()
usuarios = [Usuario(1), Usuario(2)]
ID_CLIENTE = 1001
# Evitar: obtener_id = 1001

Clases

Nombres descripitvos en singular, con sufijos opcionales:

class GestorCorreos:  # Claro propósito
class ServicioValidacion: ...
# Evitar: Correo (ambiguo)

Agrupación Lógica

Comience con funciones, agrupe en clases al surgir responsabilidades:

# Antes: Funciones sueltas
def formatear_log(datos): ...
def guardar_log(datos): ...

# Después: Agrupación en clase
class Registrador:
    def formatear_log(self, datos): ...
    def guardar_log(self, datos): ...

Punto de Entrada

Defina un módulo principal con protección de ejecución:

def iniciar_aplicacion():
    # Lógica principal

if __name__ == "__main__":
    iniciar_aplicacion()

Módulo Ejecutable

Para paquetes invocables (python -m mi_paquete):

src/
└── mi_paquete
     ├── __init__.py
     ├── __main__.py  # Contiene if __name__ == "__main__"
     └── ...