Arquitectura profesional de proyectos en Python

Una arquitectura sólida permite escalar proyectos, mantenerlos y trabajar en equipo sin caos. En esta guía aprenderás estructuras profesionales, separación de capas, patrones de organización, modularización, uso de entornos, configuración, CLI, testing integrado y buenas prácticas reales.

1. Estructura profesional de carpetas

mi_proyecto/
    app/
        __init__.py
        servicios/
        modelos/
        repositorios/
        cli/
    tests/
    config/
    requirements.txt
    README.md

2. Separación de capas

• Capa de dominio: lógica pura, modelos.
• Capa de infraestructura: base de datos, APIs.
• Capa de aplicación: servicios, casos de uso.
• Capa de interfaz: CLI, web, UI.

# dominio/modelos.py
class Usuario:
    def __init__(self, nombre):
        self.nombre = nombre

3. Módulos y paquetes

# app/servicios/usuarios.py
from app.modelos import Usuario

def crear_usuario(nombre):
    return Usuario(nombre)

4. Configuración y variables de entorno

import os

DB_URL = os.getenv("DB_URL", "sqlite:///local.db")

5. Arquitectura hexagonal

La arquitectura hexagonal separa el núcleo del sistema de los adaptadores externos.

# puerto (interfaz)
class RepoUsuarios:
    def guardar(self, usuario): ...

# adaptador
class RepoMemoria(RepoUsuarios):
    def __init__(self):
        self.data = []
    def guardar(self, usuario):
        self.data.append(usuario)

6. CLI + servicios + adaptadores

# cli/main.py
import click
from app.servicios.usuarios import crear_usuario

@click.command()
@click.argument("nombre")
def cli(nombre):
    u = crear_usuario(nombre)
    print("Creado:", u.nombre)

if __name__ == "__main__":
    cli()

7. Integración con testing

# tests/test_usuarios.py
from app.servicios.usuarios import crear_usuario

def test_crear_usuario():
    u = crear_usuario("Ana")
    assert u.nombre == "Ana"

8. Ejercicios

# adaptador falso
class RepoFake(RepoUsuarios):
    def guardar(self, u): print("Guardado")

# cli básico
@click.command()
def cli(): ...

9. Mini‑proyecto: Arquitectura hexagonal completa

# dominio
class Usuario:
    def __init__(self, nombre):
        self.nombre = nombre

# puerto
class RepoUsuarios:
    def guardar(self, usuario): ...

# adaptador
class RepoMemoria(RepoUsuarios):
    def __init__(self):
        self.data = []
    def guardar(self, usuario):
        self.data.append(usuario)

# servicio
def registrar(nombre, repo: RepoUsuarios):
    u = Usuario(nombre)
    repo.guardar(u)
    return u

# cli
import click

@click.command()
@click.argument("nombre")
def cli(nombre):
    repo = RepoMemoria()
    u = registrar(nombre, repo)
    print("Registrado:", u.nombre)

if __name__ == "__main__":
    cli()

Siguiente guía