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 40 de 47 · Un proyecto real ✦ WebMCP implementado

FastAPI y por qué necesita uvicorn

10 min de lectura 3 retos

FastAPI no es un servidor. Es el framework: define tus rutas, valida lo que llega y genera la documentación. Quien abre el puerto y habla HTTP es uvicorn. En esta lección ves por qué son dos piezas, qué hace cada una, cómo se compara con nginx + php-fpm y por qué tus funciones se escriben con async def.

¿De dónde vienen los nombres?

FastAPI = inglés fast (rápido) + API (Application Programming Interface, interfaz de programación de aplicaciones)
Rápido por dos motivos que ellos mismos citan: el rendimiento (corre sobre ASGI) y lo rápido que se escribe (los tipos hacen el trabajo de validar).
uvicorn = nombre propio del servidor; su documentación lo define como «una implementación de servidor web ASGI para Python»
El programa que abre el puerto, entiende HTTP y llama a tu aplicación. Es el nginx + php-fpm de Python, todo en uno.
BaseModel = inglés base model (modelo base)
La clase de pydantic de la que heredas para describir los datos de una petición. Tus campos con tipos se validan solos.
OpenAPI = Open (abierto) + API
El formato estándar para describir una API (rutas, parámetros, respuestas). FastAPI lo genera solo y de él salen las páginas de documentación interactiva /docs.
gunicorn = Green Unicorn (unicornio verde), con juego de palabras con el servidor Unicorn de Ruby
Un servidor clásico de Python (WSGI) que gestiona varios procesos. Se puede combinar con uvicorn en producción.
En 4 ideas
1/4

FastAPI es una aplicación ASGI: un objeto que se puede llamar (app(scope, receive, send)). Define rutas, valida con pydantic y documenta en OpenAPI. No abre ningún puerto: es como tu index.php sin nginx.

1 · FastAPI es una aplicación, no un servidor

En la lección anterior viste que una aplicación ASGI es solo una función que el servidor llama. Esto es literalmente lo que es un objeto FastAPI: algo que se puede llamar con scope, receive y send. Para demostrarlo, aquí no hay servidor: llamamos nosotros a la aplicación con una petición inventada y vemos qué mensajes devuelve.

Pythonmain.pySolo lectura: necesita FastAPI
import asyncio

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def inicio():
    return {"app": "tareas"}


async def llama(app, ruta):
    mensajes = []
    scope = {
        "type": "http", "method": "GET", "path": ruta, "query_string": b"", "headers": [],
        "http_version": "1.1", "scheme": "http", "server": ("localhost", 8000),
        "client": ("127.0.0.1", 1), "root_path": "",
    }

    async def receive():
        return {"type": "http.request", "body": b"", "more_body": False}

    async def send(mensaje):
        mensajes.append(mensaje)

    await app(scope, receive, send)
    return mensajes


if __name__ == "__main__":
    print(callable(app))
    for mensaje in asyncio.run(llama(app, "/")):
        print(mensaje)
True
{'type': 'http.response.start', 'status': 200, 'headers': [(b'content-length', b'16'), (b'content-type', b'application/json')]}
{'type': 'http.response.body', 'body': b'{"app":"tareas"}'}
  • callable(app) es True: la aplicación es un objeto que se llama como una función.
  • FastAPI devolvió dos mensajes: la cabecera (http.response.start, con el 200) y el cuerpo (http.response.body). Es el protocolo ASGI que viste a mano.
  • Fíjate en que no ha hecho falta abrir ningún puerto. Por eso el TestClient de la lección de tests prueba una API sin servidor.

2 · Rutas, tipos y validación: lo que PHP hace a mano

Esta es la misma ruta, POST /tareas, en un index.php y en FastAPI. A la izquierda lo haces todo tú: leer el cuerpo, decodificar el JSON, comprobar el título y poner el código de estado. A la derecha declaras qué forma tiene el dato y FastAPI hace lo demás:

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

header('Content-Type: application/json');

$ruta = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$metodo = $_SERVER['REQUEST_METHOD'];

if ($metodo === 'POST' && $ruta === '/tareas') {
    $cuerpo = json_decode(file_get_contents('php://input'), true);
    $titulo = trim((string) ($cuerpo['titulo'] ?? ''));
    if ($titulo === '') {
        http_response_code(422);
        echo json_encode(['detail' => 'titulo obligatorio']);
        exit;
    }
    http_response_code(201);
    echo json_encode(['id' => 1, 'titulo' => $titulo, 'prioridad' => 1]);
    exit;
}

http_response_code(404);
echo json_encode(['detail' => 'Not Found']);
Pythonmain.pySolo lectura: necesita FastAPI
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()


class TareaNueva(BaseModel):
    titulo: str = Field(min_length=1)
    prioridad: int = 1


@app.post("/tareas", status_code=201)
def crea(nueva: TareaNueva):
    return {"id": 1, "titulo": nueva.titulo, "prioridad": nueva.prioridad}


if __name__ == "__main__":
    cliente = TestClient(app)
    respuesta = cliente.post("/tareas", json={"titulo": "Comprar pan"})
    print(respuesta.status_code, respuesta.json())
    respuesta = cliente.post("/tareas", json={"titulo": "x", "prioridad": "alta"})
    print(respuesta.status_code, respuesta.json())
    print(cliente.post("/tareas", json={"titulo": ""}).status_code)
    print(cliente.get("/nada").status_code)

Salida real de las cuatro líneas de prueba. Una prioridad "alta" no es un entero, y FastAPI responde 422 con el campo exacto que falla, sin que escribas un solo if:

201 {'id': 1, 'titulo': 'Comprar pan', 'prioridad': 1}
422 {'detail': [{'type': 'int_parsing', 'loc': ['body', 'prioridad'], 'msg': 'Input should be a valid integer, unable to parse string as an integer', 'input': 'alta'}]}
422
404

Equivalencia POO · PHP → Python

La clase TareaNueva es el equivalente del DTO (el objeto que transporta datos) que en PHP escribirías a mano. Esto es lo que cambia:

PHPPython (pydantic)Quién lo ve
final readonly class TareaNueva { public function __construct(public string $titulo, public int $prioridad = 1) {} }class TareaNueva(BaseModel): titulo: str; prioridad: int = 1FastAPI, que lo construye con lo que llega
Validar a mano en el constructor y lanzar InvalidArgumentExceptionField(min_length=1) y los tipos: pydantic valida al crear el objetoResponde 422 sola
extends(BaseModel): heredar de la clase basepydantic, que lee las anotaciones de tipo
#[Route('/tareas', methods: ['POST'])] en un controlador@app.post("/tareas") sobre la funciónEl enrutador de FastAPI
json_decode(file_get_contents('php://input'), true)un parámetro tipado: nueva: TareaNuevaFastAPI inyecta el cuerpo ya validado

Lo mismo vale para los datos que van en la URL: un parámetro de la función con un tipo se convierte en parámetro de ruta (/tareas/{id} con id: int) o de consulta (?pendientes=true con pendientes: bool = False). Si id no es un entero, 422 también.

¿Por qué? · En PHP no existe

¿Por qué FastAPI usa los tipos para validar? En PHP no existe

En PHP, un tipo (int $id) se comprueba dentro de tu código y lanza un TypeError que tú has de capturar y convertir en una respuesta. Los tipos y el HTTP son dos mundos separados.

En FastAPI el tipo es la declaración de qué se espera: el framework lo lee antes de llamar a tu función, valida, convierte ("7" se vuelve 7) y, si falla, responde con el error sin que tu código llegue a ejecutarse. Los mismos tipos generan la documentación OpenAPI: el módulo 01 dijo que los tipos eran opcionales; aquí es donde se aprovechan.

Un detalle que muerde: FastAPI prueba las rutas en el orden en que las definiste y se queda con la primera que encaja. Si pones /tareas/{id} antes de /tareas/pendientes, la palabra pendientes entra como un id. Con FastAPI de verdad:

Pythonmain.pySolo lectura: necesita FastAPI
from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()


@app.get("/tareas/{id}")
def detalle(id: int):
    return {"detalle": id}


@app.get("/tareas/pendientes")
def pendientes():
    return {"lista": "pendientes"}


if __name__ == "__main__":
    cliente = TestClient(app)
    respuesta = cliente.get("/tareas/pendientes")
    print(respuesta.status_code, respuesta.json())
    print(cliente.get("/tareas/7").json())
422 {'detail': [{'type': 'int_parsing', 'loc': ['path', 'id'], 'msg': 'Input should be a valid integer, unable to parse string as an integer', 'input': 'pendientes'}]}
{'detalle': 7}

La ruta /tareas/pendientes nunca se alcanza: /tareas/{id} ya la había cogido. La regla es las rutas fijas, antes que las que tienen variables. Este enrutador de juguete, con la misma regla de «gana la primera», lo muestra con Python puro:

Pythonmain.py
class Enrutador:
    def __init__(self):
        self.rutas = []

    def registra(self, patron, funcion):
        self.rutas.append((patron.split("/"), funcion))

    def atiende(self, ruta):
        partes = ruta.split("/")
        for patron, funcion in self.rutas:
            if len(patron) != len(partes):
                continue
            variables = {}
            for esperado, real in zip(patron, partes):
                if esperado.startswith("{"):
                    variables[esperado[1:-1]] = real
                elif esperado != real:
                    break
            else:
                return funcion(**variables)
        return "404"


def detalle(id):
    return f"detalle de {id}"


def pendientes():
    return "lista de pendientes"


bien = Enrutador()
bien.registra("/tareas/pendientes", pendientes)
bien.registra("/tareas/{id}", detalle)

mal = Enrutador()
mal.registra("/tareas/{id}", detalle)
mal.registra("/tareas/pendientes", pendientes)

print("fijas primero:", bien.atiende("/tareas/pendientes"))
print("variables primero:", mal.atiende("/tareas/pendientes"))

3 · uvicorn: el servidor que llama a tu app

Si FastAPI no abre puertos, ¿quién lo hace? uvicorn. Se lanza desde la terminal diciéndole dónde está tu app, con la forma fichero:objeto:

$ uvicorn main:app --port 8000
INFO:     Started server process [7]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     127.0.0.1:60024 - "GET /tareas HTTP/1.1" 200 OK

Esa salida es real (la última línea es una petición GET /tareas que le hicimos). main:app quiere decir: «importa el módulo main (el fichero main.py) y coge la variable app». Es lo mismo que escribir from main import app.

Lo que uvicorn hace por cada petición es lo que tú hiciste a mano en la lección anterior, pero con red de verdad:

  1. Abre un puerto (por defecto 127.0.0.1:8000) y se queda escuchando.
  2. Lee los bytes que llegan y entiende el HTTP: método, ruta, cabeceras, cuerpo.
  3. Construye el scope con esos datos (el $_SERVER).
  4. Llama a tu app: await app(scope, receive, send).
  5. Convierte los mensajes que la app manda por send en una respuesta HTTP y la devuelve al navegador.
AspectoPHP: nginx + php-fpmPython: uvicorn + FastAPI
Quién escucha en el puertonginxuvicorn (o nginx delante, redirigiendo a uvicorn)
Cómo llega la petición a tu códigonginx habla FastCGI con php-fpm, que arranca el scriptuvicorn llama a la función app dentro de su propio proceso
ProcesosUn grupo de procesos php-fpm (pm.max_children)Un proceso con un bucle de eventos, o varios con --workers
Estado entre peticionesNinguno: cada una empieza limpiaTu app vive en memoria: lo que guardes en una variable global sigue ahí
Tras editar el códigoSe relee solo (con OPcache, tras su revalidación)Hay que reiniciar, o arrancar con --reload en desarrollo

¿Por qué? · En PHP no existe

¿Por qué FastAPI y uvicorn son dos programas separados? En PHP no existe

En PHP, nginx y php-fpm también son dos programas, pero PHP trae su lado ya integrado: tú nunca ves el contrato entre los dos. En Python lo ves, porque FastAPI (el framework) y uvicorn (el servidor) los escriben autores distintos.

Esa separación es útil: la misma app FastAPI corre en uvicorn, en hypercorn o en granian sin cambiar una línea, y puedes cambiar de servidor sin tocar tu código. Y para pruebas, el TestClient hace de servidor falso y no abre ningún puerto.

4 · async def: por qué las rutas son asíncronas

Con uvicorn, un solo proceso atiende muchas peticiones a la vez usando un bucle de eventos (lo viste en el módulo 08: async/await). El truco es que, cuando una ruta tiene que esperar (a la BD, a otra API), le dice al bucle «avísame cuando llegue» con await, y mientras tanto el bucle atiende otras peticiones.

Mira la diferencia con dos tareas que esperan una décima. La primera usa time.sleep, que bloquea todo el proceso; la segunda usa await asyncio.sleep, que deja pasar a la otra. Fíjate en el orden de los mensajes:

Pythonmain.py
import asyncio
import time

registro = []


async def bloquea(nombre):
    registro.append(f"{nombre} empieza")
    time.sleep(0.01)
    registro.append(f"{nombre} termina")


async def espera(nombre):
    registro.append(f"{nombre} empieza")
    await asyncio.sleep(0.01)
    registro.append(f"{nombre} termina")


async def main():
    await asyncio.gather(bloquea("a"), bloquea("b"))
    print("con time.sleep:   ", registro)
    registro.clear()
    await asyncio.gather(espera("a"), espera("b"))
    print("con asyncio.sleep:", registro)


asyncio.run(main())

Con time.sleep, la tarea b no empieza hasta que la a termina: una petición lenta congela a todas las demás. Con await asyncio.sleep empiezan las dos a la vez. En una API, esa espera sería una consulta a la BD.

FastAPI te deja elegir entre def y async def en cada ruta, y hace cosas distintas con cada una:

Escribes…FastAPI la ejecuta…Úsala cuando…
async def con awaiten el bucle de eventos, sin hilosesperas con cosas asíncronas (await consulta(...), httpx.AsyncClient)
def normalen un hilo aparte, para no bloquear el buclellamas a código bloqueante de siempre (sqlite3, requests, ficheros)
async def con una llamada bloqueante dentrobloquea todo el servidor mientras durenunca: es el error más típico
Pythonmain.pySolo lectura: necesita FastAPI
import asyncio
import time

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()


@app.get("/bien")
async def bien():
    await asyncio.sleep(0.01)
    return {"ok": True}


@app.get("/con-def")
def con_def():
    time.sleep(0.01)
    return {"ok": True}


@app.get("/mal")
async def mal():
    # Bloquea el bucle de eventos: ninguna otra petición avanza hasta que acabe
    time.sleep(0.01)
    return {"ok": True}


if __name__ == "__main__":
    cliente = TestClient(app)
    for ruta in ["/bien", "/con-def", "/mal"]:
        print(ruta, cliente.get(ruta).json())

Las tres funcionan, y con una sola petición ni lo notarías. La diferencia aparece con carga: /mal frena a todos los demás mientras duerme; /con-def duerme en un hilo y el bucle sigue libre; /bien ni siquiera ocupa un hilo.

¿Por qué? · En PHP no existe

¿Por qué async def y no un proceso por petición como en PHP? En PHP no existe

PHP resuelve la concurrencia repitiendo procesos: cada petición, uno. Es sencillo y aísla los fallos, pero cada proceso ocupa memoria mientras espera la BD, y para atender 1000 a la vez necesitas 1000 procesos.

El bucle de eventos resuelve lo mismo esperando mejor: un solo proceso con miles de peticiones en espera, porque esperar no cuesta nada. Por eso FastAPI nació sobre ASGI y async. El inconveniente es el que acabas de ver: una llamada bloqueante frena a todos.

5 · Desarrollo y producción

Lo mismo que ya haces con PHP (php -S para probar, nginx + php-fpm para producir) tiene su pareja:

$ uvicorn main:app --reload
$ uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
  • --reload vigila los ficheros y reinicia el servidor al guardar. Solo en desarrollo: gasta CPU y reinicia en medio de peticiones. Es la comodidad que PHP te da gratis al releer el script.
  • --workers 4 arranca 4 procesos de la app, cada uno con su bucle de eventos, para aprovechar varios núcleos. No se puede usar con --reload.
  • --host 0.0.0.0 hace que escuche en todas las interfaces. Por defecto escucha solo en 127.0.0.1, y dentro de un contenedor de Docker no verías nada desde fuera.
  • Con gunicorn como gestor de procesos (reinicio ordenado, señales) se usa el paquete uvicorn-worker: gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker. El módulo antiguo uvicorn.workers está marcado como obsoleto.
  • Detrás de nginx: en producción casi siempre nginx sigue delante (HTTPS, límites, ficheros estáticos) y reenvía a uvicorn con proxy_pass en vez del fastcgi_pass de php-fpm.

La pregunta que te vas a hacer

Vale, pero… ¿cómo dejo mi API siempre encendida en el VPS?

Igual que cualquier programa que no debe morir: un contenedor (Docker) con la orden de uvicorn como CMD, o un servicio de systemd, con nginx delante. El módulo 10 termina con esa fase de despliegue. A diferencia de PHP, aquí tú eres quien mantiene vivo el proceso.

Hora de practicar

Retos · 0/3 resueltos

Reto 1 de 3

El await que falta

cuenta_pendientes es una corrutina (async def), así que print(cuenta_pendientes()) no imprime el número: imprime un objeto corrutina. En una app real, uvicorn hace el await por ti; aquí lo tienes que hacer tú. Haz que el programa imprima 2 con asyncio.run.

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. FastAPI es la app, uvicorn es el servidor: FastAPI define rutas y validación; uvicorn abre el puerto y la llama (tu index.php frente a nginx + php-fpm).
  2. uvicorn main:app = «del fichero main.py, el objeto app». Sin lanzar uvicorn, python main.py no sirve nada.
  3. Un parámetro con tipo (id: int, nueva: TareaNueva) lo valida FastAPI antes de ejecutar tu función; si falla, responde 422 (en PHP, if a mano sobre $_POST).
  4. async def para esperar con await, def normal para código bloqueante; un time.sleep dentro de async def congela todo el servidor.
  5. --reload solo en desarrollo, --workers N en producción (no se combinan) y nginx por delante, con proxy_pass en vez de fastcgi_pass.

Para recordarlo: «La app se llama, el servidor llama»

FFastAPI
rutas y validación: la app
Uuvicorn
puerto y HTTP: el servidor
Aasync def
await si esperas; def si bloqueas

FastAPI es la app, Uvicorn el servidor y Async decide cómo esperas. Un truco para no liarte: la app es una función, y las funciones se llaman; el servidor es quien las llama.