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

Fase 3: el repositorio, protocolo y SQLite

10 min de lectura 4 retos

El dominio no sabe guardar nada. De eso se encarga el repositorio: el objeto que apunta las tareas y las recupera. En esta fase escribes el Protocol que dice qué sabe hacer un repositorio y sus dos versiones, una en memoria y otra en SQLite, y ves los tres fallos clásicos de hablar con una base de datos desde Python.

¿De dónde vienen los nombres?

repositorio = del latín repositorium (almacén, despensa)
El objeto que esconde dónde y cómo se guardan las cosas. Quien lo usa pide «guarda esta tarea» sin saber si hay SQL detrás.
fetchone = inglés fetch (ir a buscar, traer) + one (uno)
Trae una fila del resultado, o None si ya no quedan. Es el $consulta->fetch() de PDO.
rowcount = inglés row count (cuenta de filas)
Cuántas filas cambió el último UPDATE o DELETE. Si vale 0, no encontró ninguna.
rollback = inglés roll back (hacer rodar hacia atrás)
Deshace lo que no se ha confirmado con commit(). Es el $pdo->rollBack().
row_factory = inglés row (fila) + factory (fábrica)
La función que decide en qué se convierte cada fila. Con sqlite3.Row se leen por nombre de columna.
En 4 ideas
1/4

RepositorioTareas es un Protocol con guardar, buscar_por_id, listar y borrar: la interfaz de PHP, pero las clases la cumplen sin escribir implements. Por eso RepositorioMemoria y RepositorioSqlite valen para el mismo código.

1 · Un Protocol, dos almacenes

Piensa en una librería con un buzón de pedidos. Al cliente le da igual si el pedido se guarda en un cuaderno o en un ordenador: solo sabe que puede dejar, buscar, listar y tirar pedidos. Eso es un repositorio. Lo que sabe hacer se escribe con un Protocol (módulo 06):

Pythonmain.py
from typing import Protocol

from app.domain.tarea import Tarea


class RepositorioTareas(Protocol):
    def guardar(self, tarea: Tarea) -> Tarea: ...

    def buscar_por_id(self, id: int) -> Tarea: ...

    def listar(self) -> list[Tarea]: ...

    def borrar(self, id: int) -> None: ...

Los ... son el cuerpo vacío: un Protocol solo describe, no hace. Y ahora la versión más sencilla, la memoria: un diccionario de id a tarea. Sirve para los tests y para entender qué tiene que cumplir cualquier repositorio. Pulsa Ejecutar:

Pythonmain.py
from dataclasses import dataclass, field, 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
    etiquetas: list[str] = field(default_factory=list)
    id: int | None = None


class RepositorioMemoria:
    def __init__(self):
        self._tareas: dict[int, Tarea] = {}
        self._siguiente = 1

    def guardar(self, tarea: Tarea) -> Tarea:
        if tarea.id is None:
            tarea = replace(tarea, id=self._siguiente)
            self._siguiente += 1
        elif tarea.id not in self._tareas:
            raise TareaNoEncontrada(tarea.id)
        self._tareas[tarea.id] = replace(tarea)
        return tarea

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

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

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


repo = RepositorioMemoria()
repo.guardar(Tarea("Comprar pan"))
repo.guardar(Tarea("Llamar al banco"))
repo.borrar(1)

print(repo.listar())
try:
    repo.buscar_por_id(1)
except TareaNoEncontrada as error:
    print(error)
PHP 8.5RepositorioMemoria.php
<?php
declare(strict_types=1);

interface RepositorioTareas
{
    public function guardar(Tarea $tarea): Tarea;

    public function buscarPorId(int $id): Tarea;

    /** @return list<Tarea> */
    public function listar(): array;

    public function borrar(int $id): void;
}

final class RepositorioMemoria implements RepositorioTareas
{
    /** @var array<int, Tarea> */
    private array $tareas = [];
    private int $siguiente = 1;

    public function guardar(Tarea $tarea): Tarea
    {
        $tarea->id ??= $this->siguiente++;
        $this->tareas[$tarea->id] = clone $tarea;
        return $tarea;
    }

    public function buscarPorId(int $id): Tarea
    {
        return clone ($this->tareas[$id] ?? throw new TareaNoEncontrada($id));
    }

    public function listar(): array
    {
        return array_values(array_map(fn (Tarea $t): Tarea => clone $t, $this->tareas));
    }

    public function borrar(int $id): void
    {
        $this->buscarPorId($id);
        unset($this->tareas[$id]);
    }
}
Pythonmemoria.py
from dataclasses import dataclass, replace


class TareaNoEncontrada(Exception):
    pass


@dataclass
class Tarea:
    titulo: str
    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 buscar_por_id(self, id):
        if id not in self._tareas:
            raise TareaNoEncontrada(id)
        return replace(self._tareas[id])

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

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


repo = RepositorioMemoria()
repo.guardar(Tarea("Comprar pan"))
print(repo.listar())

¿Por qué? · En PHP no existe

¿Por qué replace(tarea) al guardar y al leer? En PHP los objetos se pasan por «identificador», y también engaña

En Python una tarea es un objeto, y asignarlo a otra variable no lo copia: apunta al mismo (módulo 04). Si el repositorio guardara el objeto tal cual, quien lo recibiera de vuelta tendría el mismo objeto de dentro y podría cambiarlo sin llamar a guardar(): el repositorio parecería funcionar en los tests y fallaría con SQLite, que siempre devuelve una tarea nueva.

replace(tarea) (sin cambios) hace una copia, como el clone de PHP. Así la memoria se comporta como una base de datos de verdad: lo que lees es una foto, y para cambiar algo hay que llamar a guardar(). Lo verás en acción en la fase 4.

2 · El repositorio SQLite

Ahora el repositorio de verdad. Recibe la conexión en el constructor (así quien lo crea decide a qué base de datos habla) y traduce entre filas y tareas. Fíjate en tres cosas: usa ? para todos los valores, rellena creada_en él mismo, y traduce 0/1 a bool y el texto de etiquetas a lista en un solo sitio, a_tarea().

Pythonmain.py
import sqlite3
from dataclasses import dataclass, field, replace
from datetime import UTC, datetime
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


def a_tarea(fila: sqlite3.Row) -> Tarea:
    return Tarea(
        id=fila["id"],
        titulo=fila["titulo"],
        prioridad=Prioridad(fila["prioridad"]),
        hecha=bool(fila["hecha"]),
        etiquetas=[e for e in fila["etiquetas"].split(",") if e],
    )


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

    def guardar(self, tarea: Tarea) -> Tarea:
        cursor = self._conexion.execute(
            "INSERT INTO tareas (titulo, prioridad, hecha, etiquetas, creada_en) VALUES (?, ?, ?, ?, ?)",
            (
                tarea.titulo,
                int(tarea.prioridad),
                int(tarea.hecha),
                ",".join(tarea.etiquetas),
                datetime.now(UTC).isoformat(timespec="seconds"),
            ),
        )
        self._conexion.commit()
        return replace(tarea, id=cursor.lastrowid)

    def listar(self) -> list[Tarea]:
        filas = self._conexion.execute(
            "SELECT id, titulo, prioridad, hecha, etiquetas FROM tareas ORDER BY id"
        ).fetchall()
        return [a_tarea(fila) for fila in filas]


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

repo = RepositorioSqlite(conexion)
guardada = repo.guardar(Tarea("Comprar pan", Prioridad.ALTA, etiquetas=["casa", "urgente"]))
repo.guardar(Tarea("Llamar al banco"))

print("id asignado:", guardada.id)
for tarea in repo.listar():
    print(tarea)
PHP 8.5RepositorioSqlite.php
<?php
declare(strict_types=1);

final class RepositorioSqlite implements RepositorioTareas
{
    public function __construct(private PDO $pdo)
    {
    }

    public function guardar(Tarea $tarea): Tarea
    {
        $consulta = $this->pdo->prepare(
            "INSERT INTO tareas (titulo, prioridad, hecha, etiquetas, creada_en) VALUES (?, ?, ?, ?, ?)"
        );
        $consulta->execute([
            $tarea->titulo,
            $tarea->prioridad->value,
            (int) $tarea->hecha,
            implode(",", $tarea->etiquetas),
            gmdate("c"),
        ]);
        $tarea->id = (int) $this->pdo->lastInsertId();
        return $tarea;
    }

    public function buscarPorId(int $id): Tarea
    {
        $consulta = $this->pdo->prepare("SELECT * FROM tareas WHERE id = ?");
        $consulta->execute([$id]);
        $fila = $consulta->fetch(PDO::FETCH_ASSOC);
        if ($fila === false) {
            throw new TareaNoEncontrada($id);
        }
        return $this->aTarea($fila);
    }
}
Pythonsqlite.py
import sqlite3
from dataclasses import dataclass, replace


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


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

    def guardar(self, tarea):
        cursor = self._conexion.execute(
            "INSERT INTO tareas (titulo) VALUES (?)", (tarea.titulo,)
        )
        self._conexion.commit()
        return replace(tarea, id=cursor.lastrowid)


conexion = sqlite3.connect(":memory:")
conexion.execute("CREATE TABLE tareas (id INTEGER PRIMARY KEY AUTOINCREMENT, titulo TEXT NOT NULL)")
print(RepositorioSqlite(conexion).guardar(Tarea("Comprar pan")))

Equivalencia POO · PHP → Python

El repositorio SQLite junta casi todo lo de los módulos 05, 06 y 07.

PHPPythonQuién lo ve
implements RepositorioTareasNada: basta con tener los mismos métodos (el Protocol los comprueba por estructura)Las herramientas de tipos, no el intérprete
private PDO $pdo (constructor promovido)self._conexion = conexion (con un guion bajo)Por convenio, solo la propia clase
$this->pdo->prepare(...)self._conexion.execute(...)El propio método (self va explícito)
throw new TareaNoEncontrada($id)raise TareaNoEncontrada(id)Quien llame a buscar_por_id()
(int) $tarea->hechaint(tarea.hecha)True se guarda como 1 y False como 0

Esa versión solo guarda y lista. El fichero completo del proyecto, app/infrastructure/sqlite/repositorio_sqlite.py, añade la rama UPDATE de guardar (cuando la tarea ya tiene id), buscar_por_id y borrar. Son pocas líneas más y siguen el mismo patrón:

Pythonmain.py
import sqlite3
from dataclasses import replace
from datetime import UTC, datetime

from app.domain.errores import TareaNoEncontrada
from app.domain.tarea import Prioridad, Tarea

def a_tarea(fila: sqlite3.Row) -> Tarea:
    return Tarea(
        id=fila["id"],
        titulo=fila["titulo"],
        prioridad=Prioridad(fila["prioridad"]),
        hecha=bool(fila["hecha"]),
        etiquetas=[e for e in fila["etiquetas"].split(",") if e],
    )


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

    def guardar(self, tarea: Tarea) -> Tarea:
        etiquetas = ",".join(tarea.etiquetas)
        if tarea.id is None:
            cursor = self._conexion.execute(
                "INSERT INTO tareas (titulo, prioridad, hecha, etiquetas, creada_en) VALUES (?, ?, ?, ?, ?)",
                (
                    tarea.titulo,
                    int(tarea.prioridad),
                    int(tarea.hecha),
                    etiquetas,
                    datetime.now(UTC).isoformat(timespec="seconds"),
                ),
            )
            self._conexion.commit()
            return replace(tarea, id=cursor.lastrowid)
        cursor = self._conexion.execute(
            "UPDATE tareas SET titulo = ?, prioridad = ?, hecha = ?, etiquetas = ? WHERE id = ?",
            (tarea.titulo, int(tarea.prioridad), int(tarea.hecha), etiquetas, tarea.id),
        )
        if cursor.rowcount == 0:
            raise TareaNoEncontrada(tarea.id)
        self._conexion.commit()
        return tarea

    def buscar_por_id(self, id: int) -> Tarea:
        fila = self._conexion.execute(
            "SELECT id, titulo, prioridad, hecha, etiquetas FROM tareas WHERE id = ?", (id,)
        ).fetchone()
        if fila is None:
            raise TareaNoEncontrada(id)
        return a_tarea(fila)

    def listar(self) -> list[Tarea]:
        filas = self._conexion.execute(
            "SELECT id, titulo, prioridad, hecha, etiquetas FROM tareas ORDER BY id"
        ).fetchall()
        return [a_tarea(fila) for fila in filas]

    def borrar(self, id: int) -> None:
        cursor = self._conexion.execute("DELETE FROM tareas WHERE id = ?", (id,))
        if cursor.rowcount == 0:
            raise TareaNoEncontrada(id)
        self._conexion.commit()

3 · Consultas con parámetros: la f-string que rompe todo

Esta es la sección más importante de la lección. La tentación es escribir el SQL con una f-string: es corto, se lee bien y en la demo funciona. Mira lo que pasa con dos versiones de la misma búsqueda por título: una pega el texto dentro del SQL y la otra usa ?.

Pythonmain.py
import sqlite3

conexion = sqlite3.connect(":memory:")
conexion.execute("CREATE TABLE tareas (id INTEGER PRIMARY KEY AUTOINCREMENT, titulo TEXT NOT NULL)")
conexion.execute("INSERT INTO tareas (titulo) VALUES (?)", ("Comprar pan",))
conexion.execute("INSERT INTO tareas (titulo) VALUES (?)", ("Llamar a O'Brien",))
conexion.commit()


def buscar_mal(titulo):
    # En PHP: $pdo->query("SELECT ... WHERE titulo = '$titulo'")  <- el mismo error
    sql = f"SELECT id, titulo FROM tareas WHERE titulo = '{titulo}'"
    return conexion.execute(sql).fetchall()


def buscar_bien(titulo):
    # En PHP: $pdo->prepare("SELECT ... WHERE titulo = ?")->execute([$titulo])
    return conexion.execute(
        "SELECT id, titulo FROM tareas WHERE titulo = ?", (titulo,)
    ).fetchall()


print("1. mal, normal:    ", buscar_mal("Comprar pan"))
print("2. mal, inyección: ", buscar_mal("x' OR '1'='1"))
print("3. bien, inyección:", buscar_bien("x' OR '1'='1"))
print("4. bien, comilla:  ", buscar_bien("Llamar a O'Brien"))

try:
    buscar_mal("Llamar a O'Brien")
except sqlite3.OperationalError as error:
    print("5. mal, comilla:   ", error)
  1. Con un título normal, las dos versiones dan el mismo resultado. Por eso el fallo no se ve en la demo.
  2. Con x' OR '1'='1, la versión mala devuelve todas las tareas: el texto del usuario ha dejado de ser un valor y se ha convertido en parte del SQL (WHERE titulo = 'x' OR '1'='1'). Esto es una inyección SQL. Con un DELETE en vez de un SELECT, borraría la tabla entera.
  3. La versión con ? no devuelve nada: busca un título que literalmente se llama x' OR '1'='1 y no existe.
  4. Hasta con buena intención rompe: un título con una comilla, como Llamar a O'Brien, hace que la versión mala dé un OperationalError (la comilla cierra el texto antes de tiempo).

¿Por qué? · En PHP no existe

¿Por qué ? evita la inyección? ¿No es lo mismo que pegar el texto?

No es lo mismo. Con ?, el SQL y los valores viajan por separado: primero SQLite analiza la sentencia (WHERE titulo = ?) y decide qué es código; después recibe los valores y los trata siempre como datos, nunca como código. Da igual lo que contengan: comillas, OR, ; o DROP TABLE.

Con una f-string, el texto ya está mezclado antes de llegar a la base de datos, y SQLite no puede saber qué parte puso el programador y cuál el usuario. Es el mismo motivo por el que en PHP se usa prepare() y no query("... '$titulo'").

4 · commit, rollback y with: los cambios no se guardan solos

En PHP con PDO, cada exec() o execute() queda guardado al instante (el modo «autocommit»). En Python no: tras un INSERT, UPDATE o DELETE, el módulo sqlite3 abre una transacción y los cambios no son definitivos hasta que llamas a conexion.commit(). Si cierras o haces rollback(), se pierden.

Pythonmain.py
import sqlite3

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


def contar():
    return conexion.execute("SELECT COUNT(*) FROM tareas").fetchone()[0]


conexion.execute("INSERT INTO tareas (titulo) VALUES (?)", ("Comprar pan",))
print("transacción abierta:", conexion.in_transaction)
conexion.commit()
print("tras commit:", contar(), conexion.in_transaction)

conexion.execute("INSERT INTO tareas (titulo) VALUES (?)", ("Sin confirmar",))
print("antes de rollback:", contar())
conexion.rollback()
print("tras rollback:", contar())

try:
    with conexion:
        conexion.execute("INSERT INTO tareas (titulo) VALUES (?)", ("Dentro del with",))
        raise RuntimeError("algo falló")
except RuntimeError:
    pass
print("with con error:", contar())

with conexion:
    conexion.execute("INSERT INTO tareas (titulo) VALUES (?)", ("Dentro del with",))
print("with sin error:", contar())

¿Por qué? · En PHP no existe

¿Por qué no hay autocommit? En PHP no hacía falta commit()

Porque Python sigue la norma de los drivers de base de datos (DB-API, la especificación común): toda modificación va dentro de una transacción para poder deshacerla si algo sale mal a medias. Si guardas una tarea y su registro de auditoría, quieres que se guarden las dos o ninguna.

El precio es el fallo clásico: olvidar el commit(). El programa parece funcionar, porque tu propia conexión ve sus cambios sin confirmar, pero otra conexión (otro proceso, otra petición) no ve nada, y al cerrar se pierden. Por eso el repositorio llama a commit() al final de cada operación que escribe.

5 · Filas que no existen: fetchone, rowcount y las excepciones

Qué pasa si pides una tarea que no existe. En PDO, fetch() devuelve false y es fácil olvidarse de comprobarlo. En sqlite3, fetchone() devuelve None, y el siguiente fila["titulo"] revienta con un TypeError lejos de la causa. El repositorio lo traduce a un error del dominio en el momento:

Pythonmain.py
import sqlite3


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


conexion = sqlite3.connect(":memory:")
conexion.row_factory = sqlite3.Row
conexion.execute("CREATE TABLE tareas (id INTEGER PRIMARY KEY AUTOINCREMENT, titulo TEXT NOT NULL)")
conexion.execute("INSERT INTO tareas (titulo) VALUES (?)", ("Comprar pan",))
conexion.commit()


def buscar_titulo(id):
    fila = conexion.execute("SELECT titulo FROM tareas WHERE id = ?", (id,)).fetchone()
    # En PHP: if ($fila === false) { throw new TareaNoEncontrada($id); }
    if fila is None:
        raise TareaNoEncontrada(id)
    return fila["titulo"]


def borrar(id):
    cursor = conexion.execute("DELETE FROM tareas WHERE id = ?", (id,))
    # En PHP: if ($consulta->rowCount() === 0) { throw ... }
    if cursor.rowcount == 0:
        raise TareaNoEncontrada(id)
    conexion.commit()


print(buscar_titulo(1))
for id in [7]:
    try:
        buscar_titulo(id)
    except TareaNoEncontrada as error:
        print("buscar:", error)

borrar(1)
try:
    borrar(1)
except TareaNoEncontrada as error:
    print("borrar:", error)

¿Por qué? · En PHP no existe

¿Por qué lanzar un error en vez de devolver None desde buscar_por_id?

Si devuelves None, cada sitio que llame al repositorio tiene que acordarse de comprobar if tarea is None. Y el olvido no da un error claro, sino un AttributeError: 'NoneType' object has no attribute 'hecha' varias líneas después, que despista.

Con una excepción de dominio, el olvido se nota: el programa se detiene en el sitio exacto y dice qué pasó. Es la decisión opuesta a ?Tarea de PHP, y más segura. En la fase 4 verás cómo la API la convierte en un 404.

La pregunta que te vas a hacer

Vale, pero… ¿no es mucho trabajo escribir todo este SQL a mano? ¿Dónde está mi Eloquent o mi Doctrine?

Para una tabla es poco código, y tener el SQL a la vista enseña mucho. Cuando el proyecto crece, estos son los recursos más usados:

Hora de practicar

Retos · 0/4 resueltos

Reto 1 de 4

Buscar por título, sin inyección

La tabla ya tiene una tarea. Escribe la búsqueda con un parámetro ? para que buscar("Comprar pan") imprima Comprar pan. Es el prepare("... WHERE titulo = ?") 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. RepositorioTareas es un Protocol: memoria y SQLite lo cumplen sin implements (en PHP, una interface y dos clases que la implementan).
  2. Los valores van con ? y en una tupla; nunca en una f-string (en PHP, prepare() y execute([...]), no query("... '$x'")).
  3. Escribir exige conexion.commit(): sin él, los cambios no son definitivos (en PHP con PDO se guardan solos).
  4. with conexion: confirma o deshace, pero no cierra la conexión.
  5. fetchone() da None y rowcount da 0 cuando no hay nada: se traduce a TareaNoEncontrada en el repositorio (en PHP, fetch() da false).

Para recordarlo: «Parámetros, Commit, Error»

PParámetros
execute(sql, (valor,))
CCommit
conexion.commit()
EError de dominio
raise TareaNoEncontrada(id)

Las tres cosas de todo método que habla con la base de datos: Parámetros con ?, Commit si escribe y Error de dominio si no encuentra nada.