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 27 de 47 · Herencia, protocolos y genéricos ✦ WebMCP implementado

Genéricos: lo que en PHP era @template

10 min de lectura 4 retos

Una pila de tareas y una pila de números son la misma estructura con otro contenido. Un genérico es una clase o función que dice «trabajo con un tipo, el que me pongas». En PHP lo cuentas en un comentario @template que solo lee PHPStan; en Python tiene sintaxis propia: class Pila[T] y def primero[T](...).

¿De dónde vienen los nombres?

genérico = del latín genus (clase, tipo): «válido para todo un tipo de cosas»
Una pieza de código escrita una vez que sirve para varios tipos distintos sin copiarla.
T = inicial de inglés Type (tipo)
El nombre de costumbre para «un tipo cualquiera», como la x de una ecuación. Puede llevar otro nombre, pero casi todos usan T.
TypeVar = inglés type variable (variable de tipo)
La forma antigua de declarar T (T = TypeVar("T")), antes de Python 3.12. Todavía la verás en código viejo.
type = inglés type (tipo)
Desde Python 3.12, la palabra type al principio de una línea (type Titulo = str) crea un alias: un nombre nuevo para un tipo largo.
Sized = inglés sized (que tiene tamaño)
Un protocolo de collections.abc: cualquier objeto al que se le puede hacer len().
En 4 ideas
1/4

Un genérico es código escrito una vez para varios tipos. En PHP lo describes con @template T en un docblock; en Python lo escribes en el propio código: class Pila[T]: (3.12+).

1 · Para qué sirve un genérico

Imagina una caja con etiqueta. Una caja de «cosas» vale para todo, pero al sacar algo no sabes qué es. Una caja etiquetada «de tareas» sabe que todo lo de dentro son tareas, y al sacar una tu editor te ayuda con .titulo. El genérico es la etiqueta.

Prueba con la función más sencilla: devolver el primer elemento de una lista. Con list[T] y -> T le dices al comprobador de tipos «lo que sale es del mismo tipo que lo que entró»:

Pythonmain.py
def primero[T](xs: list[T]) -> T:
    return xs[0]


titulos = ["Comprar pan", "Llamar al banco"]
prioridades = [3, 1, 2]

print(primero(titulos))
print(primero(prioridades))
print(primero([True, False]))
PHP 8.5primero.php
<?php
declare(strict_types=1);

/**
 * @template T
 * @param list<T> $xs
 * @return T
 */
function primero(array $xs): mixed
{
    return $xs[0];
}

echo primero(["Comprar pan", "Llamar al banco"]) . PHP_EOL;
echo primero([3, 1, 2]) . PHP_EOL;
Pythonmain.py
def primero[T](xs: list[T]) -> T:
    return xs[0]


print(primero(["Comprar pan", "Llamar al banco"]))
print(primero([3, 1, 2]))

¿Por qué? · En PHP no existe

¿Por qué PHP lo cuenta en un comentario y Python en el código?

PHP no tiene genéricos en el lenguaje: el tipo de retorno es mixed y todo lo demás vive en un docblock @template que solo leen PHPStan, Psalm y tu editor. Para PHP, ese comentario no existe.

Python sí puso el hueco [T] en la sintaxis, así que T forma parte del código y no se desincroniza como un comentario viejo. Pero ojo: Python tampoco lo comprueba al ejecutar. Lo lee la herramienta de tipos, igual que en PHP.

2 · Una clase genérica: class Pila[T]

Una pila es como una pila de platos: el último que pones es el primero que cogerás. Se llama LIFO (last in, first out: el último en entrar es el primero en salir). Sirve igual para tareas, números o textos, así que es el candidato perfecto para un genérico.

Pythonmain.py
class Pila[T]:
    def __init__(self) -> None:
        self._items: list[T] = []

    def apilar(self, item: T) -> None:
        self._items.append(item)

    def desapilar(self) -> T:
        return self._items.pop()

    def ver(self) -> T:
        return self._items[-1]

    def __len__(self) -> int:
        return len(self._items)


deshacer = Pila[str]()
deshacer.apilar("crear tarea")
deshacer.apilar("marcar hecha")
print(deshacer.ver())
print(deshacer.desapilar())
print(len(deshacer))

numeros = Pila[int]()
numeros.apilar(7)
print(numeros.desapilar())

Pila[str]() es «una pila de textos». Fíjate en que Pila[T] se escribe con corchetes, no con <T> como en otros lenguajes.

PHP 8.5Pila.php
<?php
declare(strict_types=1);

/**
 * @template T
 */
final class Pila
{
    /** @var list<T> */
    private array $items = [];

    /** @param T $item */
    public function apilar(mixed $item): void
    {
        $this->items[] = $item;
    }

    /** @return T */
    public function desapilar(): mixed
    {
        return array_pop($this->items);
    }

    public function count(): int
    {
        return count($this->items);
    }
}

$deshacer = new Pila();
$deshacer->apilar("crear tarea");
echo $deshacer->desapilar() . PHP_EOL;
Pythonmain.py
class Pila[T]:
    def __init__(self) -> None:
        self._items: list[T] = []

    def apilar(self, item: T) -> None:
        self._items.append(item)

    def desapilar(self) -> T:
        return self._items.pop()

    def __len__(self) -> int:
        return len(self._items)


deshacer = Pila[str]()
deshacer.apilar("crear tarea")
print(deshacer.desapilar())
  1. class Pila[T] declara T una vez, y vale en toda la clase.
  2. Dentro, list[T], item: T y -> T usan ese mismo T: «el tipo que me pusieron».
  3. Pila[str]() lo concreta al crear el objeto: ahí T pasa a ser str.

Cuando hay dos piezas distintas, usas dos letras: class Par[K, V] (como array<K, V> en un docblock de PHP).

3 · Un repositorio genérico

En la lección anterior el repositorio guardaba solo tareas. ¿Y si mañana quieres guardar etiquetas con el mismo código? Un repositorio genérico guarda «lo que sea» y cada uso concreta el tipo:

Pythonmain.py
from dataclasses import dataclass
from typing import Protocol


@dataclass
class Tarea:
    id: int
    titulo: str


@dataclass
class Etiqueta:
    id: int
    nombre: str


class Repositorio[T](Protocol):
    def guardar(self, id: int, item: T) -> T: ...
    def buscar(self, id: int) -> T: ...


class RepoMemoria[T]:
    def __init__(self) -> None:
        self._items: dict[int, T] = {}

    def guardar(self, id: int, item: T) -> T:
        self._items[id] = item
        return item

    def buscar(self, id: int) -> T:
        return self._items[id]


def titulo_de(repo: Repositorio[Tarea], id: int) -> str:
    return repo.buscar(id).titulo


tareas = RepoMemoria[Tarea]()
tareas.guardar(1, Tarea(1, "Comprar pan"))

etiquetas = RepoMemoria[Etiqueta]()
etiquetas.guardar(1, Etiqueta(1, "urgente"))

print(titulo_de(tareas, 1))
print(etiquetas.buscar(1).nombre)

Fíjate en Repositorio[T](Protocol): un protocolo (lección anterior) que además es genérico. titulo_de pide un Repositorio[Tarea], y RepoMemoria[Tarea] lo cumple sin heredar de nada.

4 · Alias con type y límites para T

Hay tipos que se hacen largos: Callable[[Tarea], bool] (una función que recibe una tarea y devuelve un booleano). Con la palabra type (3.12+) les pones un nombre corto, como un apodo:

Pythonmain.py
from collections.abc import Callable
from dataclasses import dataclass


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


type Titulo = str
type Filtro = Callable[[Tarea], bool]
type ListaTareas = list[Tarea]


def filtrar(tareas: ListaTareas, condicion: Filtro) -> ListaTareas:
    return [t for t in tareas if condicion(t)]


def sin_hacer(t: Tarea) -> bool:
    return not t.hecha


tareas = [Tarea(1, "Comprar pan"), Tarea(2, "Llamar", True)]
print(filtrar(tareas, sin_hacer))
print(type(Filtro).__name__, Filtro.__name__)
PHP 8.5Tareas.php
<?php
declare(strict_types=1);

/**
 * @phpstan-type Filtro callable(Tarea): bool
 */
final class Tareas
{
    /**
     * @param list<Tarea> $tareas
     * @param Filtro $condicion
     * @return list<Tarea>
     */
    public static function filtrar(array $tareas, callable $condicion): array
    {
        return array_values(array_filter($tareas, $condicion));
    }
}
Pythonmain.py
from collections.abc import Callable
from dataclasses import dataclass


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


type Filtro = Callable[[Tarea], bool]


def filtrar(tareas: list[Tarea], condicion: Filtro) -> list[Tarea]:
    return [t for t in tareas if condicion(t)]


print(filtrar([Tarea(1, "Comprar pan")], lambda t: not t.hecha))

A veces quieres que T no valga para cualquier cosa, solo para tipos que sepan algo. Con T: Sized dices «T tiene que ser algo al que se le pueda hacer len()». Con una tupla, «solo uno de estos»:

Pythonmain.py
from collections.abc import Sized


def mas_larga[T: Sized](opciones: list[T]) -> T:
    return max(opciones, key=len)


def suma_doble[N: (int, float)](a: N, b: N) -> N:
    return (a + b) * 2


print(mas_larga(["pan", "leche", "huevos"]))
print(mas_larga([[1, 2], [1], [1, 2, 3]]))
print(suma_doble(2, 3))
print(suma_doble(0.5, 0.25))
Quiero…En PHP (docblock)En Python
Una función genérica@template T + @param list<T>def f[T](xs: list[T]) -> T
Una clase genérica@template T sobre la claseclass Pila[T]:
Varios tipos@template K, @template Vclass Par[K, V]:
Un alias de tipo@phpstan-type Filtro ...type Filtro = Callable[...]
Un límite para T@template T of Countabledef f[T: Sized](...)
Concretar al usarlo@var Pila<string>Pila[str]()

5 · Lo que los genéricos NO hacen

Igual que con los type hints de la lección anterior, Python no comprueba nada de esto al ejecutar. Puedes crear una pila «de enteros» y meterle un texto. Mira:

Pythonmain.py
class Pila[T]:
    def __init__(self) -> None:
        self._items: list[T] = []

    def apilar(self, item: T) -> None:
        self._items.append(item)

    def ver(self) -> T:
        return self._items[-1]


numeros = Pila[int]()
numeros.apilar(7)
numeros.apilar("esto no es un entero")
print(numeros.ver())
print(Pila.__type_params__)

¿Por qué? · En PHP no existe

¿Por qué existen los genéricos si Python no los comprueba?

Son para tus herramientas y para quien lea tu código. Un comprobador como mypy o pyright sí lee Pila[int] y te avisa en rojo en el editor de que esa línea con "esto no es un entero" está mal, antes de ejecutar. Y tu editor sabe, al hacer numeros.ver()., que es un int y te ofrece sus métodos.

En PHP tienes el mismo trato con PHPStan: el @template solo sirve si pasas el análisis. La diferencia es que en Python el hueco [T] es parte del lenguaje (Pila.__type_params__ lo guarda), no un comentario.

La pregunta que te vas a hacer

Vale, pero… ¿cómo hago que Python SÍ rechace el tipo equivocado?

No lo hace por sí solo: tienes tres caminos, de menos a más fuerte. Primero, correr mypy/pyright antes de subir (como un paso del CI). Segundo, validar a mano con isinstance(item, int) si de verdad te importa. Tercero, con FastAPI (módulos finales) los datos que entran por la API se validan en ejecución con la biblioteca Pydantic.

Equivalencia POO · PHP → Python

Los genéricos de PHP (docblocks) traducidos a Python:

PHPPythonQuién lo ve
/** @template T */ class Pilaclass Pila[T]:El comprobador de tipos (PHPStan en PHP, mypy/pyright aquí)
@param T $item / @return Titem: T / -> TSolo anotaciones: no se comprueban al ejecutar
@var Pila<string>Pila[str]()Lo lee el comprobador; en ejecución es una Pila normal
@template T of Countableclass Pila[T: Sized]El comprobador
@phpstan-type Filtro ...type Filtro = Callable[...]Cualquiera que importe el módulo
interface Repositorio + @template Tclass Repositorio[T](Protocol)Quien lo use como tipo
mixedAny (de typing)Desactiva la comprobación para ese valor

Hora de practicar

Retos · 0/4 resueltos

Reto 1 de 4

El primero de la lista

Escribe la función genérica primero[T](xs: list[T]) -> T que devuelva el primer elemento. El programa debe imprimir pan y después 3. En PHP serían un @template T y un return $xs[0];.

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 genérico se escribe una vez y vale para varios tipos: class Pila[T], def primero[T](xs: list[T]) -> T (en PHP, @template T en un docblock).
  2. Pila[str]() concreta el tipo al usarla (en PHP, @var Pila<string>).
  3. type Filtro = Callable[[Tarea], bool] pone nombre a un tipo largo (en PHP, @phpstan-type).
  4. T: Sized limita lo que puede ser T (en PHP, @template T of Countable).
  5. Todo esto es para mypy/pyright y para quien lee: Python no lo comprueba al ejecutar (PHP tampoco comprueba sus @template).

Para recordarlo: «Una T, un Alias, un Límite»

TTipo
class Pila[T] declara el hueco
AAlias
type Filtro = ... pone nombre
LLímite
T: Sized restringe el hueco

Los genéricos tienen Tipo (el hueco), Alias (el apodo) y Límite (lo que se le exige). Y un recordatorio: «el genérico es una etiqueta para el comprobador, no un guardia para Python».