Esencial⏱ 25 minVS Code / Cursor

Valida cuerpos con Pydantic

Recibir JSON tipado y validado.

fastapi pydantic

Antes de comenzar

🎯 Qué vas a lograr en esta lección

¿Qué problema vas a resolver?

Aprenderás a recibir json tipado y validado. La idea es partir de una necesidad concreta, no de memorizar código.

¿Qué vas a construir?

Task Validation Api: un proyecto pequeño para crear un servicio web sencillo. El nombre técnico identifica la carpeta del proyecto; no necesitás memorizarlo.

¿Por qué es útil?

Te ayuda a permitir que otras aplicaciones envíen datos y reciban respuestas.

¿Qué vas a aprender?

Practicarás rutas, solicitudes, validación y respuestas HTTP. Cada término nuevo se explica antes de usarlo.

Tu primera acción

No instalés ni ejecutes nada todavía. Primero lee las palabras esenciales y observa el ejemplo pequeño. Después identificarás qué dato entra, qué instrucción trabaja y qué resultado aparece.

Cómo usar esta lección

Avanza una parte a la vez

Aprende

Leé las palabras nuevas y el ejemplo pequeño.

Practica

Cambiá una sola cosa y ejecuta nuevamente.

Comprueba

Respondé las preguntas y usa las pistas cuando las necesites.

Cierra

Marcá el checklist y decide si continuar o tomar una pausa.

No necesitás entender toda la página de una vez. Termina una parte, haz una pausa breve y continúa cuando estés listo.

Parte 1

Aprende las palabras esenciales

Leé definiciones cortas y explica cada palabra con un ejemplo propio.

Base conceptual — léela antes de practicar

🧱 Conceptos esenciales explicados desde cero

Esta sección no es opcional. Presenta las palabras y procesos que necesitás para comprender el ejemplo. Leé una definición, observa el ejemplo y explícalo con una frase propia antes de avanzar.

`pydantic`

Qué significa: Librería para definir modelos y validar datos en Python.

Para qué sirve: Ayuda a rechazar entradas con tipos o reglas incorrectas.

Ejemplo: class Task(BaseModel): title: str.

Confusión frecuente: El modelo valida datos; no guarda automáticamente en base de datos.

`modelo`

Qué significa: Estructura que representa datos o patrón aprendido.

Para qué sirve: En APIs valida; en ML predice.

Ejemplo: Task model o classifier.

Confusión frecuente: El significado depende del contexto.

`body`

Qué significa: Contenido principal enviado en una solicitud HTTP.

Para qué sirve: Transporta datos complejos.

Ejemplo: JSON de una tarea.

Confusión frecuente: No todos los métodos usan body.

`validacion`

Qué significa: Comprobación de que un dato cumple reglas antes de usarlo.

Para qué sirve: Evita resultados incorrectos y errores inesperados.

Ejemplo: Revisar que una edad sea un entero positivo.

Confusión frecuente: Validar no es lo mismo que corregir automáticamente.

`tipo de dato`

Qué significa: Categoría que indica qué representa un valor y qué operaciones admite.

Para qué sirve: Ayuda a Python a saber si debe sumar, concatenar, comparar o recorrer un dato.

Ejemplo: str para texto, int para enteros, float para decimales, bool para verdadero/falso.

Confusión frecuente: "10" es texto; 10 es número. Se ven parecidos, pero se comportan distinto.

Ejemplo mínimo de endpoint

Este ejemplo es deliberadamente pequeño. Su objetivo es mostrar las piezas básicas sin mezclar todavía toda la lógica del proyecto.

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

Identificá los nombres nuevos: subraya variables, funciones, tipos, herramientas o pasos.
Señala la entrada: qué dato recibe o qué valor ya está escrito.
Señala el proceso: qué instrucción transforma, valida, consulta o calcula.
Señala la salida: qué resultado puede verse o verificarse.
Explícalo: completa “el programa recibe ___, hace ___ y entrega ___”.

No continués todavía si no podés explicar al menos tres términos y el flujo entrada → proceso → salida sin copiar el texto.

Aprende las palabras antes de usarlas

🧠 Conceptos explicados desde cero

No memoricés los nombres. Leé qué significa cada término, observa el ejemplo y trata de explicarlo con tus propias palabras.

`BaseModel`

Qué significa: BaseModel es un concepto de análisis de datos o machine learning.

Para qué sirve: Describir cómo se preparan datos, se aprende un patrón o se evalúa un resultado.

Ejemplo pequeño: En esta lección, BaseModel se usa en un ejemplo pequeño antes del proyecto.

Confusión frecuente: No interpretes la métrica aislada; relaciónala con el problema que intentas resolver.

`Field`

Qué significa: Field es un término técnico utilizado en esta lección.

Para qué sirve: Nombrar una parte específica del proceso de Field.

Ejemplo pequeño: Busca Field en el ejemplo y observa qué recibe y qué produce.

Confusión frecuente: No intentés memorizar el nombre: explicá primero su función con tus propias palabras.

`request body`

Qué significa: request body es una parte de la comunicación entre un cliente y un servidor.

Para qué sirve: Definir qué se envía, dónde se envía y qué se recibe.

Ejemplo pequeño: El diagrama de la lección muestra el lugar de request body en la solicitud.

Confusión frecuente: No confundas la dirección de la solicitud con los datos que viajan dentro de ella.

`schema`

Qué significa: schema es un término técnico utilizado en esta lección.

Para qué sirve: Nombrar una parte específica del proceso de schema.

Ejemplo pequeño: Busca schema en el ejemplo y observa qué recibe y qué produce.

Confusión frecuente: No intentés memorizar el nombre: explicá primero su función con tus propias palabras.

Parte 2

Mirá un ejemplo pequeño

Primero comprende un ejemplo mínimo. Después observa el código completo.

Ejemplo pequeño antes del proyecto

Entender una respuesta de una API

Observá únicamente tres cosas: qué dato existe, qué instrucción se ejecuta y qué resultado aparece.

def health() -> dict[str, str]:
    return {"status": "ok"}

print(health())

Resultado explicado: Antes de iniciar FastAPI, observa que una ruta finalmente devuelve datos.

Antes de continuar, responde con tus palabras:

¿Qué dato recibe o ya tiene el ejemplo?
¿Qué instrucción realiza el trabajo?
¿Qué resultado podés observar?

⌨️ Código completo

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class TaskCreate(BaseModel):
    title: str = Field(min_length=3,max_length=100)
    minutes: int = Field(default=25,ge=5,le=240)
    priority: int = Field(default=2,ge=1,le=3)

@app.post("/tasks",status_code=201)
def create(task: TaskCreate) -> dict:
    return {"id":1,**task.model_dump(),"completed":False}

Código README Desafío

Primero entiende el ejemplo

🖼️ Explicación ilustrada: entrada → proceso → resultado

Piensa en una máquina sencilla: colocas algo en la entrada, la máquina aplica un proceso y entrega un resultado.

Situación

Una persona necesita resolver el problema de «valida cuerpos con pydantic».

Entrada

El programa recibe datos, instrucciones o archivos relacionados con microproyecto.

Proceso

El código valida la entrada, aplica reglas mediante funciones y prepara una respuesta.

Resultado

El usuario recibe un resultado visible que puede comprobar y comparar.

Ejemplo antes y después

Antes

Antes de ejecutar: solo tenemos datos y una necesidad.

Después

Después de ejecutar: tenemos un resultado producido por pasos identificables.

¿Cómo usarás este ejemplo en el mini proyecto?

Ahora practicarás con un mini proyecto. Primero observarás el ejemplo, después cambiarás una sola parte y finalmente explicarás el resultado.

1. ObservarVer el ejemplo

2. EntenderRelacionar datos y resultado

3. CambiarModificar una sola cosa

4. EjecutarComprobar el resultado

5. ExplicarDecir qué aprendiste

Regla: cambia una sola parte, ejecuta de nuevo y explica qué diferencia observaste. No necesitás reconstruir el proyecto completo.

Parte 3

Practica con un mini proyecto

Hacé un cambio pequeño, ejecuta el código y observa qué cambió.

Practica paso a paso

🧩 Mini proyecto guiado: Valida cuerpos con Pydantic

Completá estos ejercicios pequeños antes del desafío. Podés equivocarte: el sistema te explicará qué repasar y te dará una pista.

En esta lección aparece BaseModel. ¿Cuál es la mejor forma de aprenderlo?

Memorizar el nombre sin ver el ejemplo. Explicar qué recibe, para qué sirve y qué resultado produce. Saltarlo y modificar todo el proyecto.

Querés practicar con el código de Valida cuerpos con Pydantic. ¿Qué cambio es mejor para comenzar?

Borrar varias líneas sin ejecutar primero. Cambiar un texto o dato de ejemplo, ejecutar y comparar el resultado. Copiar una solución diferente sin leerla.

Después de modificar un dato, ¿qué tenés que hacer para saber si aprendiste correctamente?

Suponer que funciona porque no ves errores en el editor. Guardar, ejecutar y comparar la salida anterior con la nueva. Cambiar otras cinco cosas antes de ejecutar.

Tarea: abre el editor del navegador o el archivo completo. Cambiá un solo dato visible, ejecútalo y observa qué parte del resultado cambió.

Cambié un único valor. Ejecuté el programa después del cambio. Puedo explicar qué cambió en el resultado.

Completé los tres pasos y puedo explicarlos. Todavía no ejecuté o no entiendo el resultado.

Progreso del mini proyecto

Completá los cuatro pasos.

🧪 Error controlado

Envía un título de una letra y revisa el error JSON.

🤖 Cursor

Explica este proyecto como tutor.
Describe entrada, procesamiento y salida.
Revisa una función por vez.
No cambies el código sin mi autorización.
Después hazme cinco preguntas.

Antes de ejecutar el proyecto

🖥️ Cómo abrir y ejecutar este proyecto, paso a paso

¿Qué significa “ejecutar”?

Ejecutar un proyecto significa pedirle a Python que lea las instrucciones guardadas en sus archivos y realice el trabajo. No modifica tu computadora completa: trabaja dentro de la carpeta del proyecto.

En estas instrucciones utilizarás la terminal, una ventana donde escribís comandos. Un comando es una instrucción corta para la computadora.

Antes de comenzar, confirma estas cuatro cosas

Descargaste y descomprimiste el proyecto. Un ZIP es una carpeta comprimida. Tenés que abrirlo para obtener una carpeta normal.
Abriste la carpeta del proyecto. Dentro deberían aparecer archivos como main.py, requirements.txt y README.md.
Python está instalado. Esto se prepara en el Nivel 00.
La terminal está ubicada en esa carpeta. Si la terminal está en otra carpeta, Python no encontrará main.py.

Terminal

Ventana donde escribís comandos. En macOS se llama Terminal; en Windows podés usar PowerShell.

Lo aprendés en: Nivel 00 · Qué necesitás para empezar a programar.

Carpeta del proyecto

Carpeta que contiene todos los archivos relacionados. Los comandos deben ejecutarse desde esta ubicación.

Lo aprendés en: Nivel 00 · Qué necesitás para empezar a programar.

Entorno virtual (`.venv`)

Una carpeta privada para las librerías de este proyecto. Evitá mezclar herramientas de proyectos diferentes.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`pip`

Herramienta de Python para instalar librerías. Una librería es código preparado por otras personas para resolver tareas comunes.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`requirements.txt`

Archivo de texto que enumera las librerías necesarias. pip lo lee para instalar las versiones requeridas.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`main.py`

Archivo de inicio habitual. El nombre puede cambiar en proyectos avanzados, pero aquí suele contener el flujo principal.

Lo practicas desde: Nivel 01 · Tu primer proyecto con variables.

Escoge únicamente tu sistema operativo

No ejecutés las dos rutas. Usá macOS si trabajás en una Mac o Windows si utilizás PowerShell.

macOS · Terminal zsh

Abrí Terminal dentro de la carpeta del proyecto.
Una forma sencilla es abrir la carpeta en Finder, escribir cd en Terminal, arrastrar la carpeta a la ventana y presionar Enter.
```
pwd
ls
```
Resultado esperado: pwd muestra la ruta de la carpeta y ls muestra main.py.
Creá el entorno virtual.
```
python3 -m venv .venv
```
python3 abre Python. -m venv pide crear un entorno virtual. .venv es el nombre de la nueva carpeta.
Resultado esperado: aparece una carpeta llamada .venv. El comando puede terminar sin mostrar texto.
Activá el entorno.
```
source .venv/bin/activate
```
Activar significa indicar que los siguientes comandos deben utilizar el Python privado del proyecto.
Resultado esperado: la terminal suele mostrar (.venv) al inicio de la línea.
Instalá las librerías del proyecto.
```
python -m pip install -r requirements.txt
```
python -m pip abre el instalador de librerías. -r requirements.txt le indica qué lista debe leer.
Resultado esperado: aparecen mensajes de instalación o se indica que las librerías ya están instaladas.
Ejecutá el archivo principal.
```
python main.py
```
Python abre main.py, lee sus instrucciones de arriba hacia abajo y muestra el resultado.
Resultado esperado: verás el resultado descrito en la sección “Resultado” de esta lección.

Windows · PowerShell

Abrí PowerShell dentro de la carpeta del proyecto.
En el Explorador de archivos, abrí la carpeta, hacé clic en la barra de dirección, escribí powershell y presioná Enter.
```
Get-Location
dir
```
Resultado esperado: Get-Location muestra la carpeta actual y dir muestra main.py.
Creá el entorno virtual.
```
python -m venv .venv
```
python abre Python. -m venv crea el entorno y .venv es el nombre de la carpeta.
Resultado esperado: aparece una carpeta llamada .venv.
Activá el entorno.
```
.venv\Scripts\Activate.ps1
```
PowerShell empieza a utilizar el Python privado de este proyecto.
Resultado esperado: aparece (.venv) al inicio de la línea. Si PowerShell bloquea el archivo, repasa la lección de entornos virtuales antes de cambiar políticas de seguridad.
Instalá las librerías.
```
python -m pip install -r requirements.txt
```
pip lee la lista y prepara las herramientas que utiliza el proyecto.
Resultado esperado: aparecen mensajes de instalación o confirmación.
Ejecutá el archivo principal.
```
python main.py
```
Python abre y ejecuta las instrucciones de main.py.
Resultado esperado: verás el resultado descrito en esta lección.

¿Cómo sé que estoy en la carpeta correcta?

Tenés que poder ver main.py al ejecutar ls en macOS o dir en Windows.

¿Cómo detengo un programa?

Los scripts pequeños terminan solos. Si un servidor continúa funcionando, presiona Control + C.

¿Qué hago si dice que falta un archivo?

Revisá la carpeta actual. El error suele indicar que la terminal no está ubicada donde guardaste el proyecto.

¿Debo repetir todo cada vez?

El entorno se crea e instala una vez. En una sesión nueva normalmente solo activas .venv y ejecutás python main.py.

Términos que aparecerán más adelante

API

Forma organizada para que dos programas intercambien solicitudes y respuestas.

Lo vas a aprender en: Nivel 04 · Consume tu primera API.

FastAPI

Librería de Python para crear APIs y servidores web. Sus proyectos se ejecutan con un comando diferente a python main.py.

Lo vas a aprender en: Nivel 06 · Crea tu primera API.

Docker

Herramienta que empaqueta una aplicación junto con su configuración para ejecutarla de forma consistente en otras computadoras.

Lo vas a aprender en: Nivel 10 · Empaqueta una API con Docker.

Notebook

Documento interactivo que combina pequeños bloques de código, resultados y explicaciones. Es común en análisis de datos.

En este curso: es un recurso opcional. No necesitás usar notebooks para completar las lecciones actuales. Consulta la introducción a notebooks cuando aparezca el término.

Herramienta externa

Programa o servicio que no forma parte de Python, por ejemplo una base de datos, navegador, servicio de nube o modelo de IA.

Regla: no la instales ni ejecutes hasta llegar a la lección que la explica y revisar su README.

🧩 Tres niveles de desafío

Esencial: cambia un dato y verifica el resultado.
Práctica: agrega validación y un mensaje de error claro.
Avanzado: separa responsabilidades, añade pruebas y documenta la arquitectura.

Aprende comprobando

🧪 Comprobaciones programando

Ejecutá un caso controlado y deja que el código compruebe condiciones importantes.

1. Caso normalUsá datos comunes.

2. Valor límiteProbá cero, vacío, máximo o mínimo.

3. Error esperadoComprobá que el mensaje ayude a corregirlo.

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

response = TestClient(app).get("/health")
assert response.status_code == 200
assert response.json() == {"status": "ok"}

Qué estás aprendiendo: TestClient prueba la API sin iniciar un servidor real.

Después de ejecutarlo

¿Qué condición comprueba cada assert?
¿Qué cambio hace fallar la comprobación?
¿El mensaje explica qué tenés que corregir?
¿Podés agregar otro caso?

Parte 4

Comprobá lo que entendiste

Respondé una pregunta a la vez. Podés usar pistas y volver a intentarlo.

Evaluación online

❓ Comprueba lo que entendiste

Respondé sobre Valida cuerpos con Pydantic. Verás una explicación completa y podrás intentarlo nuevamente.

Pregunta 1 de 5 · Selección

¿Cuál describe mejor la entrada principal?

una respuesta HTTP, normalmente JSON la solicitud HTTP con ruta, parámetros, body o archivo FastAPI valida y ejecuta la función de la ruta

Pregunta 2 de 5 · Selección

¿Qué describe mejor el procesamiento?

la solicitud HTTP con ruta, parámetros, body o archivo FastAPI valida y ejecuta la función de la ruta una respuesta HTTP, normalmente JSON

Pregunta 3 de 5 · Selección

¿Qué error esperado debería manejarse?

Ninguno; si funciona una vez siempre funcionará. dato inválido, recurso inexistente o error del servidor Ocultar cualquier error sin informar.

Pregunta 4 de 5 · Respuesta breve

¿Cómo comprobarías que el resultado es correcto?

Pregunta 5 de 5 · Respuesta breve

¿Qué mejora convertiría este microproyecto en una pieza de portafolio más sólida?

Resultado de la evaluación

Completá las cinco preguntas.

Parte 5

Cerrá la lección

Resume lo aprendido, completa el checklist y decide tu siguiente paso.

📝 Resumen

Ejecutaste una referencia funcional.
Identificaste entrada, procesamiento y salida.
Modificaste un comportamiento.
Provocaste y reparaste un error.
Preparaste una mejora para GitHub.

✅ Checklist

Ejecuté la referencia. Expliqué el flujo. Reparé el error. Reconstruí el proyecto. Preparé GitHub.Puedo definir las palabras nuevas principales y explicar el ejemplo mínimo sin copiarlo.

Cómo podrás mejorar este proyecto

🚀 Mejoras futuras y dónde las aprenderás

No son obligatorias ahora. Son mejoras que aplicarás cuando aprendas las herramientas correspondientes.

Separar la configuración del código

Qué mejora: Evita editar el programa cuando cambia una ruta, clave o preferencia.

Dónde lo aprenderás: en la lección «Protege tokens con .env», del nivel APIs y servicios externos.

Añadir pruebas automatizadas

Qué mejora: Comprueba que una modificación no rompa lo existente.

Dónde lo aprenderás: en la lección «Escribe pruebas unitarias», del nivel Testing y despliegue.

Registrar la ejecución

Qué mejora: Ayuda a entender fallos sin imprimir datos sensibles.

Dónde lo aprenderás: en la lección «Configura observabilidad», del nivel Testing y despliegue.

Mejorar mensajes y validación

Qué mejora: Explica qué dato falta y cómo corregirlo.

Dónde lo aprenderás: en la lección «Entrada de datos segura», del nivel Fundamentos de Python.

Documentar decisiones y limitaciones

Qué mejora: Permite que otra persona comprenda y evalúe el proyecto.

Dónde lo aprenderás: en la lección «Construye casos de estudio», del nivel Portafolio profesional.

Crear una demostración

Qué mejora: Muestra el problema, funcionamiento y evidencia.

Dónde lo aprenderás: en la lección «Crea un índice HTML», del nivel Portafolio profesional.

Valida cuerpos con Pydantic

🎯 Qué vas a lograr en esta lección

¿Qué problema vas a resolver?

¿Qué vas a construir?

¿Por qué es útil?

¿Qué vas a aprender?

Tu primera acción

Avanza una parte a la vez

Aprende las palabras esenciales

🧱 Conceptos esenciales explicados desde cero

pydantic

modelo

body

validacion

tipo de dato

Ejemplo mínimo de endpoint

🧠 Conceptos explicados desde cero

BaseModel

Field

request body

schema

Mirá un ejemplo pequeño

Entender una respuesta de una API

⌨️ Código completo

🖼️ Explicación ilustrada: entrada → proceso → resultado

Situación

Entrada

Proceso

Resultado

Ejemplo antes y después

¿Cómo usarás este ejemplo en el mini proyecto?

Practica con un mini proyecto

🧩 Mini proyecto guiado: Valida cuerpos con Pydantic

Reconoce una palabra nueva

Hacé un cambio seguro

Comprobá lo que ocurrió

Tu mini proyecto

Progreso del mini proyecto

🎉 ¡Mini proyecto completado!

🧪 Error controlado

🤖 Cursor

🖥️ Cómo abrir y ejecutar este proyecto, paso a paso

¿Qué significa “ejecutar”?

Antes de comenzar, confirma estas cuatro cosas

Terminal

Carpeta del proyecto

Entorno virtual (.venv)

pip

requirements.txt

main.py

Escoge únicamente tu sistema operativo

macOS · Terminal zsh

Windows · PowerShell

¿Cómo sé que estoy en la carpeta correcta?

¿Cómo detengo un programa?

¿Qué hago si dice que falta un archivo?

¿Debo repetir todo cada vez?

API

FastAPI

Docker

Notebook

Herramienta externa

🧩 Tres niveles de desafío

🧪 Comprobaciones programando

Después de ejecutarlo

Comprobá lo que entendiste

❓ Comprueba lo que entendiste

¿Cuál describe mejor la entrada principal?

¿Qué describe mejor el procesamiento?

¿Qué error esperado debería manejarse?

Resultado de la evaluación

Cerrá la lección

📝 Resumen

✅ Checklist

🚀 Mejoras futuras y dónde las aprenderás

Separar la configuración del código

Añadir pruebas automatizadas

Registrar la ejecución

Mejorar mensajes y validación

Documentar decisiones y limitaciones

`pydantic`

`modelo`

`body`

`validacion`

`tipo de dato`

`BaseModel`

`Field`

`request body`

`schema`

Entorno virtual (`.venv`)

`pip`

`requirements.txt`

`main.py`