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 43 de 47 · Proyecto final: CRUD de tareas con SQLite ✦ WebMCP implementado

Fase 2: el dominio, la entidad Tarea

10 min de lectura 4 retos

Con el esquema listo, toca el corazón de la app: el dominio. Aquí vive lo que significa «tarea» sin hablar de SQL ni de web: la entidad Tarea, la Prioridad, sus reglas y sus errores. Es la parte que más tiempo vivirá y la que menos debe depender de nada.

¿De dónde vienen los nombres?

__post_init__ = post (después de) + init (inicialización), con guiones bajos dobles
Un método que @dataclass llama justo después de rellenar los campos. Es el sitio para validar, como el cuerpo de un constructor de PHP.
IntEnum = Integer + Enum (enumeración de enteros)
Un enum cuyos miembros son números enteros: Prioridad.ALTA == 2. Casa con la columna INTEGER de la tabla.
strip = inglés to strip (quitar, despojar)
Quita los espacios del principio y del final de un texto. Es el trim() de PHP.
replace = inglés replace (reemplazar)
dataclasses.replace(tarea, id=3) crea una copia de la tarea cambiando solo lo que pidas. Es el with de los objetos readonly de PHP.
En 4 ideas
1/4

La Tarea es un @dataclass y la Prioridad un IntEnum de valores 0, 1 y 2, los mismos que guarda la columna. En PHP sería una final class con constructor promovido y un enum Prioridad: int.

1 · La entidad: Tarea y Prioridad

Una entidad es un objeto con identidad: dos tareas con el mismo título siguen siendo dos tareas, porque cada una tiene su id. Para guardar sus datos usamos lo que ya conoces del módulo 05: un @dataclass para la tarea y un enum para la prioridad.

Un detalle importante: una tarea nueva todavía no tiene id, se lo dará la base de datos al guardarla. Por eso el id es int | None y vale None al principio, como el ?int $id = null de PHP. Pulsa Ejecutar:

Pythonmain.py
from dataclasses import dataclass, field
from enum import IntEnum


class Prioridad(IntEnum):
    BAJA = 0
    MEDIA = 1
    ALTA = 2


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


nueva = Tarea("Comprar pan")
urgente = Tarea("Llamar al banco", Prioridad.ALTA)

# En PHP: echo $nueva->prioridad->name . " " . var_export($nueva->hecha, true);
print(nueva.prioridad.name, nueva.hecha, nueva.id)
print(urgente.prioridad.name, urgente.prioridad.value)
print(nueva == Tarea("Comprar pan"))
PHP 8.5tarea.php
<?php
declare(strict_types=1);

enum Prioridad: int
{
    case Baja = 0;
    case Media = 1;
    case Alta = 2;
}

final class Tarea
{
    /**
     * @param list<string> $etiquetas
     */
    public function __construct(
        public string $titulo,
        public Prioridad $prioridad = Prioridad::Media,
        public bool $hecha = false,
        public array $etiquetas = [],
        public ?int $id = null,
    ) {
    }
}

$nueva = new Tarea("Comprar pan");
echo $nueva->prioridad->name . " " . var_export($nueva->hecha, true) . PHP_EOL;
Pythontarea.py
from dataclasses import dataclass, field
from enum import IntEnum


class Prioridad(IntEnum):
    BAJA = 0
    MEDIA = 1
    ALTA = 2


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


nueva = Tarea("Comprar pan")
print(nueva.prioridad.name, nueva.hecha)

¿Por qué? · En PHP no existe

¿Por qué el id va el último y con = None? En PHP el orden no importa tanto

En un @dataclass, los campos sin valor por defecto tienen que ir antes que los que sí lo tienen (como los parámetros de una función). Lo que siempre se pide al crear una tarea, el titulo, va primero; lo opcional, después.

El id va al final porque casi nunca lo escribes tú: lo rellena el repositorio. Así Tarea("Comprar pan") basta para una tarea nueva. Un id de 0 sería peor: 0 es un número válido y no distingue «aún sin guardar» de «la tarea cero»; None dice claramente «todavía no tiene».

Equivalencia POO · PHP → Python

La entidad usa casi todo lo del módulo 05: dataclass, enum y valores por defecto.

PHPPythonQuién lo ve
public string $titulo (constructor promovido)titulo: str dentro de @dataclassCualquiera: en Python no hay private de verdad
enum Prioridad: int { case Baja = 0; }class Prioridad(IntEnum): BAJA = 0Cualquiera; IntEnum también se compara y se guarda como número
final class TareaNo existe final para clases: se confía en el acuerdo del equipoEl compilador no lo impide; las herramientas de tipos pueden avisar con @final
array $etiquetas = []field(default_factory=list)Cada tarea recibe su propia lista

2 · Que no nazca una tarea sin título

La regla más básica del negocio: una tarea necesita un título. Si cada sitio de la app tuviera que acordarse de comprobarlo, tarde o temprano alguno se olvidaría. Es mejor que la propia entidad no deje existir a una tarea sin título. Para eso está __post_init__: @dataclass lo llama justo después de rellenar los campos.

Pythonmain.py
from dataclasses import dataclass, field


class TituloVacio(Exception):
    pass


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

    def __post_init__(self):
        # En PHP: $this->titulo = trim($titulo);
        self.titulo = self.titulo.strip()
        # En PHP: if ($this->titulo === "") { throw new TituloVacio(...); }
        if not self.titulo:
            raise TituloVacio("el título no puede estar vacío")


print(repr(Tarea("  Comprar pan  ").titulo))

for texto in ["", "   "]:
    try:
        Tarea(texto)
    except TituloVacio as error:
        print(f"{texto!r} -> {error}")
PHP 8.5validar.php
<?php
declare(strict_types=1);

final class TituloVacio extends DomainException
{
}

final class Tarea
{
    public string $titulo;

    public function __construct(string $titulo, public bool $hecha = false)
    {
        $this->titulo = trim($titulo);
        if ($this->titulo === "") {
            throw new TituloVacio("el título no puede estar vacío");
        }
    }
}

try {
    new Tarea("   ");
} catch (TituloVacio $e) {
    echo $e->getMessage() . PHP_EOL;
}
Pythonvalidar.py
from dataclasses import dataclass


class TituloVacio(Exception):
    pass


@dataclass
class Tarea:
    titulo: str
    hecha: bool = False

    def __post_init__(self):
        self.titulo = self.titulo.strip()
        if not self.titulo:
            raise TituloVacio("el título no puede estar vacío")


try:
    Tarea("   ")
except TituloVacio as error:
    print(error)

¿Por qué? · En PHP no existe

¿Por qué validar en la entidad si la columna ya es NOT NULL?

Porque NOT NULL solo rechaza el valor ausente, no el vacío: un título "" o " " entra sin problema en la base de datos. Y aunque lo rechazara, el error llegaría tarde y con un mensaje de SQL, no de tu negocio.

Si la validación vive en la entidad, da igual por dónde llegue la tarea (la API, un script, un test): no puede existir sin título. Es la misma idea del constructor privado con static function nueva() de PHP, pero con una sola línea de convenio: cualquier tarea pasa por __post_init__.

3 · El comportamiento va dentro de la entidad

Una tarea no solo guarda datos: sabe hacer cosas. Completarse, recibir etiquetas. Si esas reglas viven en la propia clase, hay un único sitio donde mirar y nadie las repite mal. La regla de las etiquetas: se guardan en minúsculas, sin espacios sobrantes, sin vacías y sin repetir.

Pythonmain.py
from dataclasses import dataclass, field


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

    def completar(self) -> None:
        self.hecha = True

    def etiquetar(self, nombre: str) -> bool:
        """Añade la etiqueta y devuelve True si era nueva."""
        nombre = nombre.strip().lower()
        if not nombre or nombre in self.etiquetas:
            return False
        self.etiquetas.append(nombre)
        return True


tarea = Tarea("Comprar pan")
print(tarea.etiquetar("  Casa "))
print(tarea.etiquetar("casa"))
print(tarea.etiquetar(""))
print(tarea.etiquetar("URGENTE"))
tarea.completar()
print(tarea)

Equivalencia POO · PHP → Python

Los métodos de la entidad: lo mismo que en PHP, con self explícito.

PHPPythonQuién lo ve
public function completar(): voiddef completar(self) -> None:Cualquiera (en Python todo es público salvo acuerdo)
$this->hecha = true;self.hecha = TrueEl propio método
private function normalizar()def _normalizar(self): (un guion bajo)Solo por convenio: se pide no usarlo desde fuera
readonly en la entidad@dataclass(frozen=True) + replace()Inmutable: cambias haciendo una copia nueva

¿Por qué? · En PHP no existe

¿Por qué completar() y no tarea.hecha = True desde donde haga falta?

Hoy completar es solo poner hecha = True. Mañana quizá haya que apuntar cuándo se completó, o impedir completar una tarea ya hecha. Si todo el código escribe tarea.hecha = True por su cuenta, tendrías que cambiarlo en veinte sitios; con el método, se cambia en uno.

Es el viejo consejo de PHP de «no tocar las propiedades desde fuera»: aquí Python no lo impone con private, así que depende de que el equipo lo respete. Los métodos que dicen qué ha pasado (completar, etiquetar) hacen el código más fácil de leer que un montón de asignaciones.

4 · Los errores del dominio

Cuando algo sale mal en el negocio, lo mejor es lanzar un error que diga lo que pasó: no un ValueError genérico, sino TituloVacio o TareaNoEncontrada. En el módulo 07 viste cómo crearlos; aquí los juntamos bajo un padre común, DominioError, para poder atrapar «cualquier error del negocio» de golpe.

Pythonmain.py
class DominioError(Exception):
    """Padre de todos los errores del negocio."""


class TituloVacio(DominioError):
    pass


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


def buscar(id: int, tareas: dict[int, str]) -> str:
    if id not in tareas:
        raise TareaNoEncontrada(id)
    return tareas[id]


tareas = {1: "Comprar pan"}

for id in [1, 7]:
    try:
        print(buscar(id, tareas))
    except TareaNoEncontrada as error:
        print("no está:", error, "| id:", error.id)

print(issubclass(TareaNoEncontrada, DominioError), issubclass(TituloVacio, DominioError))

¿Por qué? · En PHP no existe

¿Por qué un error propio con el id dentro, y no raise ValueError("no existe")?

Con un ValueError, quien lo atrapa no sabe qué salió mal: podría ser cualquier cosa de cualquier librería. Con TareaNoEncontrada, un except concreto dice exactamente «no había tarea con ese id».

Y guardar el id como atributo (error.id) permite a la capa de arriba construir un mensaje útil sin tener que leer el texto del error. Es el mismo patrón que en PHP: una excepción con propiedades, no solo con un mensaje.

5 · Un dominio que no depende de nadie

Mira lo que hemos escrito en toda la lección: ni un import sqlite3, ni un import fastapi. Solo dataclasses y enum, de la biblioteca estándar. Es a propósito: el dominio no sabe cómo se guarda ni cómo se sirve. Por eso puedes probarlo en el navegador, sin base de datos ni servidor.

CapaPuede importarNo puede importar
app/domainLa biblioteca estándar y nada mássqlite3, fastapi, app.application, app.infrastructure
app/applicationapp.domainsqlite3, fastapi, app.infrastructure
app/infrastructureapp.domain, app.application, sqlite3, fastapiNada prohibido: es la capa de fuera

Las flechas de dependencia siempre apuntan hacia dentro: la infraestructura conoce al dominio, nunca al revés. Si algún día un import de app/domain mira hacia fuera, algo se ha torcido. Una forma fácil de comprobarlo:

Pythonmain.py
import ast

codigo_del_dominio = """
from dataclasses import dataclass, field
from enum import IntEnum
"""

PROHIBIDOS = {"sqlite3", "fastapi", "pydantic", "app.infrastructure", "app.application"}

for nodo in ast.walk(ast.parse(codigo_del_dominio)):
    if isinstance(nodo, ast.ImportFrom):
        modulo = nodo.module or ""
        estado = "PROHIBIDO" if modulo.split(".")[0] in {p.split(".")[0] for p in PROHIBIDOS} else "ok"
        print(f"from {modulo} -> {estado}")

Hora de practicar

Retos · 0/4 resueltos

Reto 1 de 4

La prioridad por defecto

El programa crea una tarea sin decir su prioridad. Haz que imprima el nombre de su prioridad por defecto, MEDIA. Es el $tarea->prioridad->name de 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. Tarea es un @dataclass y Prioridad un IntEnum de 0/1/2 (en PHP, una final class con constructor promovido y un enum Prioridad: int).
  2. El id es int | None = None: una tarea nueva todavía no lo tiene (en PHP, ?int $id = null).
  3. Se valida en __post_init__: trim, y TituloVacio si queda vacío (en PHP, el throw del constructor). NOT NULL no rechaza "".
  4. Las reglas son métodos de la entidad (completar(), etiquetar()), no asignaciones sueltas desde fuera.
  5. Los errores del negocio heredan de DominioError, llevan sus datos (error.id) y no saben de HTTP.

Para recordarlo: «Nace Validada, Habla Sola»

NNace validada
__post_init__
HHechos en métodos
tarea.completar()
SSin dependencias
solo dataclasses y enum

El dominio Nace validado (no puede existir mal), los Hechos son métodos (completar, etiquetar) y va Sin dependencias: nada de sqlite3 ni de fastapi.