Mis apuntes · Aprende Python desde PHP

Se guardan solos en este navegador mientras escribes. Puedes usar Markdown. Al descargarlos, la primera línea es tu enlace personal al curso.

Lección 45 de 47 · Proyecto final: CRUD de tareas con SQLite ✦ WebMCP implementado

Fase 4: los casos de uso

10 min de lectura 4 retos

El dominio sabe qué es una tarea y el repositorio sabe guardarla. Falta quien dirija la orquesta: los casos de uso, una pieza por cada cosa que la app sabe hacer. En esta fase escribes CrearTarea, ListarTareas, CompletarTarea y BorrarTarea, los pruebas con repositorios falsos y los enchufas a SQLite.

¿De dónde vienen los nombres?

caso de uso = inglés use case: un uso concreto que le das a la app
Una clase pequeña con una cosa que la app sabe hacer: «crear una tarea», «completar una tarea». Son los verbos de tu app.
ejecutar = inglés execute (ejecutar, llevar a cabo)
El nombre del método único de cada caso de uso. Quien lo llama no necesita saber nada más.
inyección de dependencias = inyectar = meter desde fuera; dependencia = algo que otra pieza necesita
El caso de uso recibe el repositorio en el constructor en vez de crearlo él. Es el __construct(private RepositorioTareas $repo) de PHP.
doble de test = del cine: el doble que sustituye al actor en las escenas peligrosas
Un objeto falso (fake, spy…) que ocupa el lugar del repositorio real en los tests.
En 4 ideas
1/4

Un caso de uso es una clase con un constructor que recibe el repositorio y un único método, ejecutar(). Es tu service o handler de PHP, y hay uno por acción: crear, listar, completar, borrar.

1 · Qué es un caso de uso

Piensa en la barra de una cafetería. El camarero no sabe cocinar ni cómo está montada la nevera: recibe un pedido («un café con leche»), lo pasa a quien corresponda y devuelve el resultado. Un caso de uso hace lo mismo: recibe una petición, usa el dominio y el repositorio, y devuelve el resultado. No sabe si le habla una API, una consola o un test.

Cada caso de uso es una clase con un solo método. Así, mirando la carpeta app/application, ves de un vistazo todo lo que la app sabe hacer. Pulsa Ejecutar:

Pythonmain.py
from dataclasses import dataclass, field, replace


@dataclass
class Tarea:
    titulo: str
    hecha: bool = False
    etiquetas: list[str] = field(default_factory=list)
    id: int | None = None


class RepositorioMemoria:
    def __init__(self):
        self._tareas = {}
        self._siguiente = 1

    def guardar(self, tarea):
        if tarea.id is None:
            tarea = replace(tarea, id=self._siguiente)
            self._siguiente += 1
        self._tareas[tarea.id] = replace(tarea)
        return tarea

    def listar(self):
        return [replace(t) for t in self._tareas.values()]


class CrearTarea:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, titulo, etiquetas=None):
        tarea = Tarea(titulo.strip(), etiquetas=list(etiquetas or []))
        return self._repositorio.guardar(tarea)


class ListarTareas:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, solo_pendientes=False):
        tareas = self._repositorio.listar()
        if solo_pendientes:
            tareas = [t for t in tareas if not t.hecha]
        return tareas


repositorio = RepositorioMemoria()
crear = CrearTarea(repositorio)
listar = ListarTareas(repositorio)

crear.ejecutar("  Comprar pan ")
crear.ejecutar("Llamar al banco", etiquetas=["casa"])

for tarea in listar.ejecutar():
    print(tarea.id, tarea.titulo, tarea.etiquetas)
PHP 8.5CrearTarea.php
<?php
declare(strict_types=1);

final readonly class CrearTarea
{
    public function __construct(private RepositorioTareas $repositorio)
    {
    }

    /**
     * @param list<string> $etiquetas
     */
    public function ejecutar(string $titulo, array $etiquetas = []): Tarea
    {
        return $this->repositorio->guardar(new Tarea(trim($titulo), etiquetas: $etiquetas));
    }
}

$crear = new CrearTarea(new RepositorioMemoria());
$tarea = $crear->ejecutar("  Comprar pan ");
echo $tarea->id . " " . $tarea->titulo . PHP_EOL;
Pythoncrear_tarea.py
from dataclasses import dataclass


@dataclass
class Tarea:
    titulo: str
    id: int | None = None


class RepositorioMemoria:
    def guardar(self, tarea):
        tarea.id = 1
        return tarea


class CrearTarea:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, titulo):
        return self._repositorio.guardar(Tarea(titulo.strip()))


crear = CrearTarea(RepositorioMemoria())
tarea = crear.ejecutar("  Comprar pan ")
print(tarea.id, tarea.titulo)

Equivalencia POO · PHP → Python

Un caso de uso es una clase pequeña. Casi todo ya lo conoces:

PHPPythonQuién lo ve
__construct(private RepositorioTareas $repo)def __init__(self, repositorio): self._repositorio = repositorioSe guarda en el objeto; con _ por convenio es privado
$this->repositorio->guardar(...)self._repositorio.guardar(...)Solo el propio caso de uso
final readonly classUna clase normal: no tiene final ni readonly de claseSe confía en no reasignar self._repositorio
new CrearTarea(new RepositorioMemoria())CrearTarea(RepositorioMemoria())Sin new: llamar a la clase crea el objeto

¿Por qué? · En PHP no existe

¿Por qué una clase con ejecutar() y no una función suelta crear_tarea(repositorio, titulo)?

Una función también valdría, y en Python es muy normal. Elegimos la clase porque el repositorio es una dependencia que no cambia entre llamadas: se pasa una vez al construir y el método solo recibe los datos de la petición. Quien use el caso de uso no necesita ni saber que existe un repositorio.

Además, así encaja con el sistema de dependencias de FastAPI que verás en la fase 5, donde cada ruta pide su caso de uso ya construido. Y es el mismo patrón que verás en cualquier proyecto PHP con DDD: Application Services con un método público.

2 · Buscar, cambiar, guardar

Completar una tarea parece trivial: tarea.hecha = True. Pero la tarea que te da el repositorio es una copia (módulo 04), no la fila de la base de datos. Cambiar la copia no cambia nada guardado. El camino correcto tiene tres pasos:

  1. Buscar la tarea con buscar_por_id(id) (lanza TareaNoEncontrada si no existe).
  2. Cambiarla con su método del dominio, tarea.completar().
  3. Guardarla con guardar(tarea): sin este paso, el cambio se pierde.

Mira qué pasa si te olvidas del tercero. El programa no da ningún error:

Pythonmain.py
from dataclasses import dataclass, replace


class TareaNoEncontrada(Exception):
    pass


@dataclass
class Tarea:
    titulo: str
    hecha: bool = False
    id: int | None = None

    def completar(self):
        self.hecha = True


class RepositorioMemoria:
    def __init__(self):
        self._tareas = {}
        self._siguiente = 1

    def guardar(self, tarea):
        if tarea.id is None:
            tarea = replace(tarea, id=self._siguiente)
            self._siguiente += 1
        self._tareas[tarea.id] = replace(tarea)
        return tarea

    def buscar_por_id(self, id):
        if id not in self._tareas:
            raise TareaNoEncontrada(id)
        return replace(self._tareas[id])


class CompletarSinGuardar:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, id):
        tarea = self._repositorio.buscar_por_id(id)
        tarea.completar()
        return tarea


class CompletarTarea:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, id):
        tarea = self._repositorio.buscar_por_id(id)
        tarea.completar()
        return self._repositorio.guardar(tarea)


repositorio = RepositorioMemoria()
repositorio.guardar(Tarea("Comprar pan"))

devuelta = CompletarSinGuardar(repositorio).ejecutar(1)
print("devuelta dice:", devuelta.hecha)
print("guardada dice:", repositorio.buscar_por_id(1).hecha)

devuelta = CompletarTarea(repositorio).ejecutar(1)
print("con guardar, guardada dice:", repositorio.buscar_por_id(1).hecha)

¿Por qué? · En PHP no existe

¿Por qué el repositorio devuelve copias y no el objeto de dentro? Sería más cómodo

Sería más cómodo y mentiría. Si la memoria devolviera el propio objeto, el caso de uso sin guardar() funcionaría en los tests, y fallaría en producción con SQLite, que siempre construye una tarea nueva a partir de la fila. El bug solo aparecería en el despliegue.

Con copias, el repositorio falso se comporta como el real y los tests cazan el olvido. Es el mismo problema que en PHP con Doctrine: ahí un flush() olvidado se salta los tests si el entity manager ya tiene el objeto en memoria.

3 · Repositorios falsos: probar sin base de datos

Como RepositorioTareas es un Protocol, no hace falta heredar de nada para ser un repositorio falso: basta con tener los métodos. En PHP necesitarías un mock de PHPUnit o una clase que implements la interfaz; aquí es una clase normal. Un buen doble para probar casos de uso es un espía: guarda lo que ha recibido para que el test lo compruebe.

Pythonmain.py
from dataclasses import dataclass


@dataclass
class Tarea:
    titulo: str
    hecha: bool = False
    id: int | None = None

    def completar(self):
        self.hecha = True


class RepositorioEspia:
    """Un repositorio falso: guarda las llamadas para que el test las mire."""

    def __init__(self, tareas):
        self._tareas = {t.id: t for t in tareas}
        self.guardadas = []

    def buscar_por_id(self, id):
        return self._tareas[id]

    def guardar(self, tarea):
        self.guardadas.append(tarea.id)
        return tarea


class CompletarTarea:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, id):
        tarea = self._repositorio.buscar_por_id(id)
        tarea.completar()
        return self._repositorio.guardar(tarea)


espia = RepositorioEspia([Tarea("Comprar pan", id=1), Tarea("Llamar al banco", id=2)])
resultado = CompletarTarea(espia).ejecutar(2)

print(resultado.titulo, resultado.hecha)
print("guardó las tareas:", espia.guardadas)
DobleQué haceCuándo lo usas
Fake (falso)Funciona de verdad pero sin base de datos: RepositorioMemoriaProbar el flujo completo de varios casos de uso
Spy (espía)Funciona y además anota cada llamadaComprobar que se llamó a guardar() y con qué
MockTiene la respuesta preparada y falla si no recibe la llamada esperadaCasos raros: forzar un error del repositorio

4 · Cuando falla: lanzar, no devolver None

Qué debe hacer CompletarTarea si la tarea no existe. Hay dos opciones: devolver None o lanzar TareaNoEncontrada. Elegimos lanzar, y el buscar_por_id del repositorio ya lo hace: el caso de uso no tiene que escribir nada, el error sube solo.

Pythonmain.py
from dataclasses import dataclass, replace


class TareaNoEncontrada(Exception):
    def __init__(self, id):
        super().__init__(f"No existe la tarea {id}")
        self.id = id


@dataclass
class Tarea:
    titulo: str
    hecha: bool = False
    id: int | None = None

    def completar(self):
        self.hecha = True


class RepositorioMemoria:
    def __init__(self, tareas):
        self._tareas = {t.id: t for t in tareas}

    def buscar_por_id(self, id):
        if id not in self._tareas:
            raise TareaNoEncontrada(id)
        return replace(self._tareas[id])

    def guardar(self, tarea):
        self._tareas[tarea.id] = replace(tarea)
        return tarea

    def borrar(self, id):
        if id not in self._tareas:
            raise TareaNoEncontrada(id)
        del self._tareas[id]


class CompletarTarea:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, id):
        tarea = self._repositorio.buscar_por_id(id)
        tarea.completar()
        return self._repositorio.guardar(tarea)


class BorrarTarea:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, id):
        self._repositorio.borrar(id)


repositorio = RepositorioMemoria([Tarea("Comprar pan", id=1)])

for caso, id in [(CompletarTarea(repositorio), 1), (CompletarTarea(repositorio), 7), (BorrarTarea(repositorio), 1), (BorrarTarea(repositorio), 1)]:
    try:
        caso.ejecutar(id)
        print(f"{type(caso).__name__}({id}): bien")
    except TareaNoEncontrada as error:
        print(f"{type(caso).__name__}({id}): {error}")

¿Por qué? · En PHP no existe

¿Por qué el caso de uso no atrapa el error y devuelve un mensaje?

Porque no sabe quién le llama. Una API quiere un 404 con JSON, una consola quiere imprimir un aviso en rojo y un test quiere comprobar que se lanzó. Si el caso de uso decidiera el mensaje, tendría que conocer a todos.

Lanzar el error de dominio y dejar que cada capa de fuera lo traduzca mantiene el caso de uso limpio. Es la misma idea del throw en PHP: el que sabe qué hacer con el error es el que está arriba, no el que lo detecta.

5 · Enchufar todo: del caso de uso al SQLite real

Falta la pieza que monta el puzzle: construir el repositorio, construir los casos de uso con él y entregárselos a la capa de fuera. A ese sitio se le llama raíz de composición (composition root): es el único lugar que conoce las clases concretas. En PHP sería el contenedor de dependencias; aquí, una función. Lo ves funcionando con SQLite de verdad (en memoria):

Pythonmain.py
import sqlite3
from dataclasses import dataclass, field, replace


class TareaNoEncontrada(Exception):
    pass


@dataclass
class Tarea:
    titulo: str
    hecha: bool = False
    etiquetas: list[str] = field(default_factory=list)
    id: int | None = None

    def completar(self):
        self.hecha = True


class RepositorioSqlite:
    def __init__(self, conexion):
        conexion.row_factory = sqlite3.Row
        self._conexion = conexion

    def guardar(self, tarea):
        if tarea.id is None:
            cursor = self._conexion.execute(
                "INSERT INTO tareas (titulo, hecha) VALUES (?, ?)", (tarea.titulo, int(tarea.hecha))
            )
            self._conexion.commit()
            return replace(tarea, id=cursor.lastrowid)
        self._conexion.execute(
            "UPDATE tareas SET titulo = ?, hecha = ? WHERE id = ?", (tarea.titulo, int(tarea.hecha), tarea.id)
        )
        self._conexion.commit()
        return tarea

    def buscar_por_id(self, id):
        fila = self._conexion.execute("SELECT id, titulo, hecha FROM tareas WHERE id = ?", (id,)).fetchone()
        if fila is None:
            raise TareaNoEncontrada(id)
        return Tarea(fila["titulo"], bool(fila["hecha"]), id=fila["id"])

    def listar(self):
        filas = self._conexion.execute("SELECT id, titulo, hecha FROM tareas ORDER BY id")
        return [Tarea(f["titulo"], bool(f["hecha"]), id=f["id"]) for f in filas]


class CrearTarea:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, titulo):
        return self._repositorio.guardar(Tarea(titulo))


class ListarTareas:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self):
        return self._repositorio.listar()


class CompletarTarea:
    def __init__(self, repositorio):
        self._repositorio = repositorio

    def ejecutar(self, id):
        tarea = self._repositorio.buscar_por_id(id)
        tarea.completar()
        return self._repositorio.guardar(tarea)


def construir_casos_de_uso(conexion):
    """La raíz de composición: el único sitio que conoce las clases concretas."""
    repositorio = RepositorioSqlite(conexion)
    return CrearTarea(repositorio), ListarTareas(repositorio), CompletarTarea(repositorio)


conexion = sqlite3.connect(":memory:")
conexion.execute("CREATE TABLE tareas (id INTEGER PRIMARY KEY AUTOINCREMENT, titulo TEXT NOT NULL, hecha INTEGER NOT NULL DEFAULT 0)")

crear, listar, completar = construir_casos_de_uso(conexion)
crear.ejecutar("Comprar pan")
crear.ejecutar("Llamar al banco")
completar.ejecutar(1)

for tarea in listar.ejecutar():
    print(tarea.id, tarea.titulo, "hecha" if tarea.hecha else "pendiente")

La pregunta que te vas a hacer

Vale, pero… ¿no hay un contenedor de dependencias como el de Symfony o Laravel?

Existen librerías para ello, pero en Python casi nunca hacen falta: una función que construye las piezas (como construir_casos_de_uso) es más sencilla y se lee de arriba abajo. FastAPI trae además su propio sistema de dependencias, Depends, que verás en la fase 5. Para curiosear:

Hora de practicar

Retos · 0/4 resueltos

Reto 1 de 4

Crear y listar

Los casos de uso CrearTarea y ListarTareas ya están escritos. Usa el mismo repositorio en los dos para que el programa imprima, una por línea, Comprar pan y Llamar al banco. Es crear dos veces con un mismo new RepositorioMemoria() en PHP.

Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.

Pythonmain.py · editable

Resumen

Lo que te llevas de esta lección

  1. Un caso de uso es una clase con el repositorio en el constructor y un único ejecutar() (en PHP, un service o handler).
  2. Cambiar algo es buscar → cambiar → guardar: lo que lees es una copia, y sin guardar() el cambio se pierde en silencio.
  3. Un repositorio falso no hereda de nada: basta con que tenga los métodos del Protocol (en PHP harías un mock o una clase que implemente la interface).
  4. Los errores se lanzan (TareaNoEncontrada), no se devuelven como None; la capa de fuera decide cómo contarlos.
  5. Un único sitio, la raíz de composición, conoce las clases concretas; el resto trabaja con el Protocol (en PHP, el contenedor de dependencias).

Para recordarlo: «Busca, Cambia, Guarda»

BBusca
buscar_por_id(id)
CCambia
tarea.completar()
GGuarda
guardar(tarea)

El ritmo de todo caso de uso que modifica algo: Busca la tarea, Cámbiala con su método del dominio y Guárdala. Si te saltas el último paso, nadie te avisa.