mirror/fastapi
1
0
Fork 0
mirror of https://github.com/fastapi/fastapi.git synced 2026-07-23 21:33:33 -04:00
Code Issues Packages Projects Releases Wiki Activity

🌐 Add new Spanish translations for all docs with new LLM-assisted system using PydanticAI (#13122)

Browse Source 
Co-authored-by: Alejandra <90076947+alejsdev@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: User <alejsdev@gmail.com>
This commit is contained in:
Sebastián Ramírez
2024-12-30 18:26:57 +00:00
committed by GitHub
parent a6afa805cd
commit fe5b2e491e
88 changed files with 14562 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
docs/es/docs/tutorial/background-tasks.md Normal file
View File

@@ -0,0 +1,84 @@
# Tareas en Segundo Plano
Puedes definir tareas en segundo plano para que se ejecuten *después* de devolver un response.
Esto es útil para operaciones que necesitan ocurrir después de un request, pero para las que el cliente realmente no necesita esperar a que la operación termine antes de recibir el response.
Esto incluye, por ejemplo:
* Notificaciones por email enviadas después de realizar una acción:
* Como conectarse a un servidor de email y enviar un email tiende a ser "lento" (varios segundos), puedes devolver el response de inmediato y enviar la notificación por email en segundo plano.
* Procesamiento de datos:
* Por ejemplo, supongamos que recibes un archivo que debe pasar por un proceso lento, puedes devolver un response de "Accepted" (HTTP 202) y procesar el archivo en segundo plano.
## Usando `BackgroundTasks`
Primero, importa `BackgroundTasks` y define un parámetro en tu *path operation function* con una declaración de tipo de `BackgroundTasks`:
{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
**FastAPI** creará el objeto de tipo `BackgroundTasks` por ti y lo pasará como ese parámetro.
## Crear una función de tarea
Crea una función para que se ejecute como la tarea en segundo plano.
Es solo una función estándar que puede recibir parámetros.
Puede ser una función `async def` o una función normal `def`, **FastAPI** sabrá cómo manejarla correctamente.
En este caso, la función de tarea escribirá en un archivo (simulando el envío de un email).
Y como la operación de escritura no usa `async` y `await`, definimos la función con un `def` normal:
{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
## Agregar la tarea en segundo plano
Dentro de tu *path operation function*, pasa tu función de tarea al objeto de *background tasks* con el método `.add_task()`:
{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
`.add_task()` recibe como argumentos:
* Una función de tarea para ejecutar en segundo plano (`write_notification`).
* Cualquier secuencia de argumentos que deba pasarse a la función de tarea en orden (`email`).
* Cualquier argumento de palabras clave que deba pasarse a la función de tarea (`message="some notification"`).
## Inyección de Dependencias
Usar `BackgroundTasks` también funciona con el sistema de inyección de dependencias, puedes declarar un parámetro de tipo `BackgroundTasks` en varios niveles: en una *path operation function*, en una dependencia (dependable), en una sub-dependencia, etc.
**FastAPI** sabe qué hacer en cada caso y cómo reutilizar el mismo objeto, de modo que todas las tareas en segundo plano se combinan y ejecutan en segundo plano después:
{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}
En este ejemplo, los mensajes se escribirán en el archivo `log.txt` *después* de que se envíe el response.
Si hay un query en el request, se escribirá en el log en una tarea en segundo plano.
Y luego otra tarea en segundo plano generada en la *path operation function* escribirá un mensaje usando el parámetro de path `email`.
## Detalles Técnicos
La clase `BackgroundTasks` proviene directamente de <a href="https://www.starlette.io/background/" class="external-link" target="_blank">`starlette.background`</a>.
Se importa/incluye directamente en FastAPI para que puedas importarla desde `fastapi` y evitar importar accidentalmente la alternativa `BackgroundTask` (sin la `s` al final) de `starlette.background`.
Al usar solo `BackgroundTasks` (y no `BackgroundTask`), es posible usarla como un parámetro de *path operation function* y dejar que **FastAPI** maneje el resto por ti, tal como cuando usas el objeto `Request` directamente.
Todavía es posible usar `BackgroundTask` solo en FastAPI, pero debes crear el objeto en tu código y devolver una `Response` de Starlette incluyéndolo.
Puedes ver más detalles en <a href="https://www.starlette.io/background/" class="external-link" target="_blank">la documentación oficial de Starlette sobre Background Tasks</a>.
## Advertencia
Si necesitas realizar una computación intensa en segundo plano y no necesariamente necesitas que se ejecute por el mismo proceso (por ejemplo, no necesitas compartir memoria, variables, etc.), podrías beneficiarte del uso de otras herramientas más grandes como <a href="https://docs.celeryq.dev" class="external-link" target="_blank">Celery</a>.
Tienden a requerir configuraciones más complejas, un gestor de cola de mensajes/trabajos, como RabbitMQ o Redis, pero te permiten ejecutar tareas en segundo plano en múltiples procesos, y especialmente, en múltiples servidores.
Pero si necesitas acceder a variables y objetos de la misma app de **FastAPI**, o necesitas realizar pequeñas tareas en segundo plano (como enviar una notificación por email), simplemente puedes usar `BackgroundTasks`.
## Resumen
Importa y usa `BackgroundTasks` con parámetros en *path operation functions* y dependencias para agregar tareas en segundo plano.

554
docs/es/docs/tutorial/bigger-applications.md Normal file
View File

@@ -0,0 +1,554 @@
# Aplicaciones más grandes - Múltiples archivos
Si estás construyendo una aplicación o una API web, rara vez podrás poner todo en un solo archivo.
**FastAPI** proporciona una herramienta conveniente para estructurar tu aplicación manteniendo toda la flexibilidad.
/// info | Información
Si vienes de Flask, esto sería el equivalente a los Blueprints de Flask.
///
## Un ejemplo de estructura de archivos
Digamos que tienes una estructura de archivos como esta:
```
.
├── app
│   ├── __init__.py
│   ├── main.py
│   ├── dependencies.py
│   └── routers
│   │ ├── __init__.py
│   │ ├── items.py
│   │ └── users.py
│   └── internal
│   ├── __init__.py
│   └── admin.py
```
/// tip | Consejo
Hay varios archivos `__init__.py`: uno en cada directorio o subdirectorio.
Esto es lo que permite importar código de un archivo a otro.
Por ejemplo, en `app/main.py` podrías tener una línea como:
```
from app.routers import items
```
///
* El directorio `app` contiene todo. Y tiene un archivo vacío `app/__init__.py`, por lo que es un "paquete de Python" (una colección de "módulos de Python"): `app`.
* Contiene un archivo `app/main.py`. Como está dentro de un paquete de Python (un directorio con un archivo `__init__.py`), es un "módulo" de ese paquete: `app.main`.
* También hay un archivo `app/dependencies.py`, al igual que `app/main.py`, es un "módulo": `app.dependencies`.
* Hay un subdirectorio `app/routers/` con otro archivo `__init__.py`, por lo que es un "subpaquete de Python": `app.routers`.
* El archivo `app/routers/items.py` está dentro de un paquete, `app/routers/`, por lo que es un submódulo: `app.routers.items`.
* Lo mismo con `app/routers/users.py`, es otro submódulo: `app.routers.users`.
* También hay un subdirectorio `app/internal/` con otro archivo `__init__.py`, por lo que es otro "subpaquete de Python": `app.internal`.
* Y el archivo `app/internal/admin.py` es otro submódulo: `app.internal.admin`.
<img src="/img/tutorial/bigger-applications/package.svg">
La misma estructura de archivos con comentarios:
```
.
├── app # "app" es un paquete de Python
│   ├── __init__.py # este archivo hace que "app" sea un "paquete de Python"
│   ├── main.py # módulo "main", por ejemplo import app.main
│   ├── dependencies.py # módulo "dependencies", por ejemplo import app.dependencies
│   └── routers # "routers" es un "subpaquete de Python"
│   │ ├── __init__.py # hace que "routers" sea un "subpaquete de Python"
│   │ ├── items.py # submódulo "items", por ejemplo import app.routers.items
│   │ └── users.py # submódulo "users", por ejemplo import app.routers.users
│   └── internal # "internal" es un "subpaquete de Python"
│   ├── __init__.py # hace que "internal" sea un "subpaquete de Python"
│   └── admin.py # submódulo "admin", por ejemplo import app.internal.admin
```
## `APIRouter`
Digamos que el archivo dedicado solo a manejar usuarios es el submódulo en `/app/routers/users.py`.
Quieres tener las *path operations* relacionadas con tus usuarios separadas del resto del código, para mantenerlo organizado.
Pero todavía es parte de la misma aplicación/web API de **FastAPI** (es parte del mismo "paquete de Python").
Puedes crear las *path operations* para ese módulo usando `APIRouter`.
### Importar `APIRouter`
Lo importas y creas una "instance" de la misma manera que lo harías con la clase `FastAPI`:
```Python hl_lines="1 3" title="app/routers/users.py"
{!../../docs_src/bigger_applications/app/routers/users.py!}
```
### *Path operations* con `APIRouter`
Y luego lo usas para declarar tus *path operations*.
Úsalo de la misma manera que usarías la clase `FastAPI`:
```Python hl_lines="6 11 16" title="app/routers/users.py"
{!../../docs_src/bigger_applications/app/routers/users.py!}
```
Puedes pensar en `APIRouter` como una clase "mini `FastAPI`".
Se soportan todas las mismas opciones.
Todos los mismos `parameters`, `responses`, `dependencies`, `tags`, etc.
/// tip | Consejo
En este ejemplo, la variable se llama `router`, pero puedes nombrarla como quieras.
///
Vamos a incluir este `APIRouter` en la aplicación principal de `FastAPI`, pero primero, revisemos las dependencias y otro `APIRouter`.
## Dependencias
Vemos que vamos a necesitar algunas dependencias usadas en varios lugares de la aplicación.
Así que las ponemos en su propio módulo `dependencies` (`app/dependencies.py`).
Ahora utilizaremos una dependencia simple para leer un encabezado `X-Token` personalizado:
//// tab | Python 3.9+
```Python hl_lines="3 6-8" title="app/dependencies.py"
{!> ../../docs_src/bigger_applications/app_an_py39/dependencies.py!}
```
////
//// tab | Python 3.8+
```Python hl_lines="1 5-7" title="app/dependencies.py"
{!> ../../docs_src/bigger_applications/app_an/dependencies.py!}
```
////
//// tab | Python 3.8+ non-Annotated
/// tip | Consejo
Preferiblemente usa la versión `Annotated` si es posible.
///
```Python hl_lines="1 4-6" title="app/dependencies.py"
{!> ../../docs_src/bigger_applications/app/dependencies.py!}
```
////
/// tip | Consejo
Estamos usando un encabezado inventado para simplificar este ejemplo.
Pero en casos reales obtendrás mejores resultados usando las [utilidades de Seguridad](security/index.md){.internal-link target=_blank} integradas.
///
## Otro módulo con `APIRouter`
Digamos que también tienes los endpoints dedicados a manejar "items" de tu aplicación en el módulo `app/routers/items.py`.
Tienes *path operations* para:
* `/items/`
* `/items/{item_id}`
Es toda la misma estructura que con `app/routers/users.py`.
Pero queremos ser más inteligentes y simplificar un poco el código.
Sabemos que todas las *path operations* en este módulo tienen el mismo:
* Prefijo de path: `/items`.
* `tags`: (solo una etiqueta: `items`).
* `responses` extra.
* `dependencies`: todas necesitan esa dependencia `X-Token` que creamos.
Entonces, en lugar de agregar todo eso a cada *path operation*, podemos agregarlo al `APIRouter`.
```Python hl_lines="5-10 16 21" title="app/routers/items.py"
{!../../docs_src/bigger_applications/app/routers/items.py!}
```
Como el path de cada *path operation* tiene que empezar con `/`, como en:
```Python hl_lines="1"
@router.get("/{item_id}")
async def read_item(item_id: str):
...
```
...el prefijo no debe incluir un `/` final.
Así que, el prefijo en este caso es `/items`.
También podemos agregar una lista de `tags` y `responses` extra que se aplicarán a todas las *path operations* incluidas en este router.
Y podemos agregar una lista de `dependencies` que se añadirá a todas las *path operations* en el router y se ejecutarán/solucionarán por cada request que les haga.
/// tip | Consejo
Nota que, al igual que [dependencias en decoradores de *path operations*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, ningún valor será pasado a tu *path operation function*.
///
El resultado final es que los paths de item son ahora:
* `/items/`
* `/items/{item_id}`
...como pretendíamos.
* Serán marcados con una lista de tags que contiene un solo string `"items"`.
* Estos "tags" son especialmente útiles para los sistemas de documentación interactiva automática (usando OpenAPI).
* Todos incluirán las `responses` predefinidas.
* Todas estas *path operations* tendrán la lista de `dependencies` evaluadas/ejecutadas antes de ellas.
* Si también declaras dependencias en una *path operation* específica, **también se ejecutarán**.
* Las dependencias del router se ejecutan primero, luego las [dependencias en el decorador](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, y luego las dependencias de parámetros normales.
* También puedes agregar [dependencias de `Security` con `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
/// tip | Consejo
Tener `dependencies` en el `APIRouter` puede ser usado, por ejemplo, para requerir autenticación para un grupo completo de *path operations*. Incluso si las dependencias no son añadidas individualmente a cada una de ellas.
///
/// check | Revisa
Los parámetros `prefix`, `tags`, `responses`, y `dependencies` son (como en muchos otros casos) solo una funcionalidad de **FastAPI** para ayudarte a evitar la duplicación de código.
///
### Importar las dependencias
Este código vive en el módulo `app.routers.items`, el archivo `app/routers/items.py`.
Y necesitamos obtener la función de dependencia del módulo `app.dependencies`, el archivo `app/dependencies.py`.
Así que usamos un import relativo con `..` para las dependencias:
```Python hl_lines="3" title="app/routers/items.py"
{!../../docs_src/bigger_applications/app/routers/items.py!}
```
#### Cómo funcionan los imports relativos
/// tip | Consejo
Si sabes perfectamente cómo funcionan los imports, continúa a la siguiente sección.
///
Un solo punto `.`, como en:
```Python
from .dependencies import get_token_header
```
significaría:
* Partiendo en el mismo paquete en el que este módulo (el archivo `app/routers/items.py`) habita (el directorio `app/routers/`)...
* busca el módulo `dependencies` (un archivo imaginario en `app/routers/dependencies.py`)...
* y de él, importa la función `get_token_header`.
Pero ese archivo no existe, nuestras dependencias están en un archivo en `app/dependencies.py`.
Recuerda cómo se ve nuestra estructura de aplicación/archivo:
<img src="/img/tutorial/bigger-applications/package.svg">
---
Los dos puntos `..`, como en:
```Python
from ..dependencies import get_token_header
```
significan:
* Partiendo en el mismo paquete en el que este módulo (el archivo `app/routers/items.py`) habita (el directorio `app/routers/`)...
* ve al paquete padre (el directorio `app/`)...
* y allí, busca el módulo `dependencies` (el archivo en `app/dependencies.py`)...
* y de él, importa la función `get_token_header`.
¡Eso funciona correctamente! 🎉
---
De la misma manera, si hubiéramos usado tres puntos `...`, como en:
```Python
from ...dependencies import get_token_header
```
eso significaría:
* Partiendo en el mismo paquete en el que este módulo (el archivo `app/routers/items.py`) habita (el directorio `app/routers/`)...
* ve al paquete padre (el directorio `app/`)...
* luego ve al paquete padre de ese paquete (no hay paquete padre, `app` es el nivel superior 😱)...
* y allí, busca el módulo `dependencies` (el archivo en `app/dependencies.py`)...
* y de él, importa la función `get_token_header`.
Eso se referiría a algún paquete arriba de `app/`, con su propio archivo `__init__.py`, etc. Pero no tenemos eso. Así que, eso lanzaría un error en nuestro ejemplo. 🚨
Pero ahora sabes cómo funciona, para que puedas usar imports relativos en tus propias aplicaciones sin importar cuán complejas sean. 🤓
### Agregar algunos `tags`, `responses`, y `dependencies` personalizados
No estamos agregando el prefijo `/items` ni los `tags=["items"]` a cada *path operation* porque los hemos añadido al `APIRouter`.
Pero aún podemos agregar _más_ `tags` que se aplicarán a una *path operation* específica, y también algunas `responses` extra específicas para esa *path operation*:
```Python hl_lines="30-31" title="app/routers/items.py"
{!../../docs_src/bigger_applications/app/routers/items.py!}
```
/// tip | Consejo
Esta última *path operation* tendrá la combinación de tags: `["items", "custom"]`.
Y también tendrá ambas responses en la documentación, una para `404` y otra para `403`.
///
## El `FastAPI` principal
Ahora, veamos el módulo en `app/main.py`.
Aquí es donde importas y usas la clase `FastAPI`.
Este será el archivo principal en tu aplicación que conecta todo.
### Importar `FastAPI`
Importas y creas una clase `FastAPI` como de costumbre.
Y podemos incluso declarar [dependencias globales](dependencies/global-dependencies.md){.internal-link target=_blank} que se combinarán con las dependencias para cada `APIRouter`:
```Python hl_lines="1 3 7" title="app/main.py"
{!../../docs_src/bigger_applications/app/main.py!}
```
### Importar el `APIRouter`
Ahora importamos los otros submódulos que tienen `APIRouter`s:
```Python hl_lines="4-5" title="app/main.py"
{!../../docs_src/bigger_applications/app/main.py!}
```
Como los archivos `app/routers/users.py` y `app/routers/items.py` son submódulos que son parte del mismo paquete de Python `app`, podemos usar un solo punto `.` para importarlos usando "imports relativos".
### Cómo funciona la importación
La sección:
```Python
from .routers import items, users
```
significa:
* Partiendo en el mismo paquete en el que este módulo (el archivo `app/main.py`) habita (el directorio `app/`)...
* busca el subpaquete `routers` (el directorio en `app/routers/`)...
* y de él, importa el submódulo `items` (el archivo en `app/routers/items.py`) y `users` (el archivo en `app/routers/users.py`)...
El módulo `items` tendrá una variable `router` (`items.router`). Este es el mismo que creamos en el archivo `app/routers/items.py`, es un objeto `APIRouter`.
Y luego hacemos lo mismo para el módulo `users`.
También podríamos importarlos así:
```Python
from app.routers import items, users
```
/// info | Información
La primera versión es un "import relativo":
```Python
from .routers import items, users
```
La segunda versión es un "import absoluto":
```Python
from app.routers import items, users
```
Para aprender más sobre Paquetes y Módulos de Python, lee <a href="https://docs.python.org/3/tutorial/modules.html" class="external-link" target="_blank">la documentación oficial de Python sobre Módulos</a>.
///
### Evitar colisiones de nombres
Estamos importando el submódulo `items` directamente, en lugar de importar solo su variable `router`.
Esto se debe a que también tenemos otra variable llamada `router` en el submódulo `users`.
Si hubiéramos importado uno después del otro, como:
```Python
from .routers.items import router
from .routers.users import router
```
el `router` de `users` sobrescribiría el de `items` y no podríamos usarlos al mismo tiempo.
Así que, para poder usar ambos en el mismo archivo, importamos los submódulos directamente:
```Python hl_lines="5" title="app/main.py"
{!../../docs_src/bigger_applications/app/main.py!}
```
### Incluir los `APIRouter`s para `users` y `items`
Ahora, incluyamos los `router`s de los submódulos `users` y `items`:
```Python hl_lines="10-11" title="app/main.py"
{!../../docs_src/bigger_applications/app/main.py!}
```
/// info | Información
`users.router` contiene el `APIRouter` dentro del archivo `app/routers/users.py`.
Y `items.router` contiene el `APIRouter` dentro del archivo `app/routers/items.py`.
///
Con `app.include_router()` podemos agregar cada `APIRouter` a la aplicación principal de `FastAPI`.
Incluirá todas las rutas de ese router como parte de ella.
/// note | Detalles Técnicos
En realidad creará internamente una *path operation* para cada *path operation* que fue declarada en el `APIRouter`.
Así, detrás de escena, funcionará como si todo fuera la misma única aplicación.
///
/// check | Revisa
No tienes que preocuparte por el rendimiento al incluir routers.
Esto tomará microsegundos y solo sucederá al inicio.
Así que no afectará el rendimiento. ⚡
///
### Incluir un `APIRouter` con un `prefix`, `tags`, `responses`, y `dependencies` personalizados
Ahora, imaginemos que tu organización te dio el archivo `app/internal/admin.py`.
Contiene un `APIRouter` con algunas *path operations* de administración que tu organización comparte entre varios proyectos.
Para este ejemplo será súper simple. Pero digamos que porque está compartido con otros proyectos en la organización, no podemos modificarlo y agregar un `prefix`, `dependencies`, `tags`, etc. directamente al `APIRouter`:
```Python hl_lines="3" title="app/internal/admin.py"
{!../../docs_src/bigger_applications/app/internal/admin.py!}
```
Pero aún queremos configurar un `prefix` personalizado al incluir el `APIRouter` para que todas sus *path operations* comiencen con `/admin`, queremos asegurarlo con las `dependencies` que ya tenemos para este proyecto, y queremos incluir `tags` y `responses`.
Podemos declarar todo eso sin tener que modificar el `APIRouter` original pasando esos parámetros a `app.include_router()`:
```Python hl_lines="14-17" title="app/main.py"
{!../../docs_src/bigger_applications/app/main.py!}
```
De esa manera, el `APIRouter` original permanecerá sin modificar, por lo que aún podemos compartir ese mismo archivo `app/internal/admin.py` con otros proyectos en la organización.
El resultado es que, en nuestra aplicación, cada una de las *path operations* del módulo `admin` tendrá:
* El prefix `/admin`.
* El tag `admin`.
* La dependencia `get_token_header`.
* La response `418`. 🍵
Pero eso solo afectará a ese `APIRouter` en nuestra aplicación, no en ningún otro código que lo utilice.
Así, por ejemplo, otros proyectos podrían usar el mismo `APIRouter` con un método de autenticación diferente.
### Incluir una *path operation*
También podemos agregar *path operations* directamente a la aplicación de `FastAPI`.
Aquí lo hacemos... solo para mostrar que podemos 🤷:
```Python hl_lines="21-23" title="app/main.py"
{!../../docs_src/bigger_applications/app/main.py!}
```
y funcionará correctamente, junto con todas las otras *path operations* añadidas con `app.include_router()`.
/// info | Detalles Muy Técnicos
**Nota**: este es un detalle muy técnico que probablemente puedes **simplemente omitir**.
---
Los `APIRouter`s no están "montados", no están aislados del resto de la aplicación.
Esto se debe a que queremos incluir sus *path operations* en el esquema de OpenAPI y las interfaces de usuario.
Como no podemos simplemente aislarlos y "montarlos" independientemente del resto, se "clonan" las *path operations* (se vuelven a crear), no se incluyen directamente.
///
## Revisa la documentación automática de la API
Ahora, ejecuta tu aplicación:
<div class="termy">
```console
$ fastapi dev app/main.py
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
Y abre la documentación en <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
Verás la documentación automática de la API, incluyendo los paths de todos los submódulos, usando los paths correctos (y prefijos) y las tags correctas:
<img src="/img/tutorial/bigger-applications/image01.png">
## Incluir el mismo router múltiples veces con diferentes `prefix`
También puedes usar `.include_router()` múltiples veces con el *mismo* router usando diferentes prefijos.
Esto podría ser útil, por ejemplo, para exponer la misma API bajo diferentes prefijos, por ejemplo, `/api/v1` y `/api/latest`.
Este es un uso avanzado que quizás no necesites realmente, pero está allí en caso de que lo necesites.
## Incluir un `APIRouter` en otro
De la misma manera que puedes incluir un `APIRouter` en una aplicación `FastAPI`, puedes incluir un `APIRouter` en otro `APIRouter` usando:
```Python
router.include_router(other_router)
```
Asegúrate de hacerlo antes de incluir `router` en la aplicación de `FastAPI`, para que las *path operations* de `other_router` también se incluyan.

60
docs/es/docs/tutorial/body-fields.md Normal file
View File

@@ -0,0 +1,60 @@
# Body - Campos
De la misma manera que puedes declarar validaciones adicionales y metadatos en los parámetros de las *path operation function* con `Query`, `Path` y `Body`, puedes declarar validaciones y metadatos dentro de los modelos de Pydantic usando `Field` de Pydantic.
## Importar `Field`
Primero, tienes que importarlo:
{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
/// warning | Advertencia
Fíjate que `Field` se importa directamente desde `pydantic`, no desde `fastapi` como el resto (`Query`, `Path`, `Body`, etc).
///
## Declarar atributos del modelo
Después puedes utilizar `Field` con los atributos del modelo:
{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}
`Field` funciona de la misma manera que `Query`, `Path` y `Body`, tiene todos los mismos parámetros, etc.
/// note | Detalles técnicos
En realidad, `Query`, `Path` y otros que verás a continuación crean objetos de subclases de una clase común `Param`, que es a su vez una subclase de la clase `FieldInfo` de Pydantic.
Y `Field` de Pydantic también regresa una instance de `FieldInfo`.
`Body` también devuelve objetos de una subclase de `FieldInfo` directamente. Y hay otros que verás más adelante que son subclases de la clase `Body`.
Recuerda que cuando importas `Query`, `Path`, y otros desde `fastapi`, en realidad son funciones que devuelven clases especiales.
///
/// tip | Consejo
Observa cómo cada atributo del modelo con un tipo, un valor por defecto y `Field` tiene la misma estructura que un parámetro de una *path operation function*, con `Field` en lugar de `Path`, `Query` y `Body`.
///
## Agregar información extra
Puedes declarar información extra en `Field`, `Query`, `Body`, etc. Y será incluida en el JSON Schema generado.
Aprenderás más sobre cómo agregar información extra más adelante en la documentación, cuando aprendamos a declarar ejemplos.
/// warning | Advertencia
Las claves extra pasadas a `Field` también estarán presentes en el esquema de OpenAPI resultante para tu aplicación.
Como estas claves no necesariamente tienen que ser parte de la especificación de OpenAPI, algunas herramientas de OpenAPI, por ejemplo [el validador de OpenAPI](https://validator.swagger.io/), podrían no funcionar con tu esquema generado.
///
## Resumen
Puedes utilizar `Field` de Pydantic para declarar validaciones adicionales y metadatos para los atributos del modelo.
También puedes usar los argumentos de palabra clave extra para pasar metadatos adicionales del JSON Schema.

173
docs/es/docs/tutorial/body-multiple-params.md Normal file
View File

@@ -0,0 +1,173 @@
# Cuerpo - Múltiples Parámetros
Ahora que hemos visto cómo usar `Path` y `Query`, veamos usos más avanzados de las declaraciones del request body.
## Mezclar `Path`, `Query` y parámetros del cuerpo
Primero, por supuesto, puedes mezclar las declaraciones de parámetros de `Path`, `Query` y del request body libremente y **FastAPI** sabrá qué hacer.
Y también puedes declarar parámetros del cuerpo como opcionales, estableciendo el valor predeterminado a `None`:
{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
## Múltiples parámetros del cuerpo
/// note | Nota
Ten en cuenta que, en este caso, el `item` que se tomaría del cuerpo es opcional. Ya que tiene un valor por defecto de `None`.
///
## Múltiples parámetros del cuerpo
En el ejemplo anterior, las *path operations* esperarían un cuerpo JSON con los atributos de un `Item`, como:
```JSON
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
}
```
Pero también puedes declarar múltiples parámetros del cuerpo, por ejemplo `item` y `user`:
{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
En este caso, **FastAPI** notará que hay más de un parámetro del cuerpo en la función (hay dos parámetros que son modelos de Pydantic).
Entonces, usará los nombres de los parámetros como claves (nombres de campo) en el cuerpo, y esperará un cuerpo como:
```JSON
{
"item": {
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
},
"user": {
"username": "dave",
"full_name": "Dave Grohl"
}
}
```
/// note | Nota
Ten en cuenta que aunque el `item` se declaró de la misma manera que antes, ahora se espera que esté dentro del cuerpo con una clave `item`.
///
**FastAPI** hará la conversión automática del request, de modo que el parámetro `item` reciba su contenido específico y lo mismo para `user`.
Realizará la validación de los datos compuestos, y los documentará así para el esquema de OpenAPI y la documentación automática.
## Valores singulares en el cuerpo
De la misma manera que hay un `Query` y `Path` para definir datos extra para parámetros de query y path, **FastAPI** proporciona un equivalente `Body`.
Por ejemplo, ampliando el modelo anterior, podrías decidir que deseas tener otra clave `importance` en el mismo cuerpo, además de `item` y `user`.
Si lo declaras tal cual, debido a que es un valor singular, **FastAPI** asumirá que es un parámetro de query.
Pero puedes instruir a **FastAPI** para que lo trate como otra clave del cuerpo usando `Body`:
{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
En este caso, **FastAPI** esperará un cuerpo como:
```JSON
{
"item": {
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
},
"user": {
"username": "dave",
"full_name": "Dave Grohl"
},
"importance": 5
}
```
Nuevamente, convertirá los tipos de datos, validará, documentará, etc.
## Múltiples parámetros de cuerpo y query
Por supuesto, también puedes declarar parámetros adicionales de query siempre que lo necesites, además de cualquier parámetro del cuerpo.
Como, por defecto, los valores singulares se interpretan como parámetros de query, no tienes que añadir explícitamente un `Query`, solo puedes hacer:
```Python
q: Union[str, None] = None
```
O en Python 3.10 y superior:
```Python
q: str | None = None
```
Por ejemplo:
{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
/// info | Información
`Body` también tiene todos los mismos parámetros de validación y metadatos extras que `Query`, `Path` y otros que verás luego.
///
## Embeber un solo parámetro de cuerpo
Supongamos que solo tienes un único parámetro de cuerpo `item` de un modelo Pydantic `Item`.
Por defecto, **FastAPI** esperará su cuerpo directamente.
Pero si deseas que espere un JSON con una clave `item` y dentro de ella los contenidos del modelo, como lo hace cuando declaras parámetros de cuerpo extra, puedes usar el parámetro especial `Body` `embed`:
```Python
item: Item = Body(embed=True)
```
como en:
{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
En este caso, **FastAPI** esperará un cuerpo como:
```JSON hl_lines="2"
{
"item": {
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
}
}
```
en lugar de:
```JSON
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2
}
```
## Resumen
Puedes añadir múltiples parámetros de cuerpo a tu *path operation function*, aunque un request solo puede tener un único cuerpo.
Pero **FastAPI** lo manejará, te dará los datos correctos en tu función, y validará y documentará el esquema correcto en la *path operation*.
También puedes declarar valores singulares para ser recibidos como parte del cuerpo.
Y puedes instruir a **FastAPI** para embeber el cuerpo en una clave incluso cuando solo hay un único parámetro declarado.

247
docs/es/docs/tutorial/body-nested-models.md Normal file
View File

@@ -0,0 +1,247 @@
# Cuerpo - Modelos Anidados
Con **FastAPI**, puedes definir, validar, documentar y usar modelos anidados de manera arbitraria (gracias a Pydantic).
## Campos de lista
Puedes definir un atributo como un subtipo. Por ejemplo, una `list` en Python:
{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
Esto hará que `tags` sea una lista, aunque no declare el tipo de los elementos de la lista.
## Campos de lista con parámetro de tipo
Pero Python tiene una forma específica de declarar listas con tipos internos, o "parámetros de tipo":
### Importar `List` de typing
En Python 3.9 y superior, puedes usar el `list` estándar para declarar estas anotaciones de tipo como veremos a continuación. 💡
Pero en versiones de Python anteriores a 3.9 (desde 3.6 en adelante), primero necesitas importar `List` del módulo `typing` estándar de Python:
{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
### Declarar una `list` con un parámetro de tipo
Para declarar tipos que tienen parámetros de tipo (tipos internos), como `list`, `dict`, `tuple`:
* Si estás en una versión de Python inferior a 3.9, importa su versión equivalente del módulo `typing`
* Pasa el/los tipo(s) interno(s) como "parámetros de tipo" usando corchetes: `[` y `]`
En Python 3.9 sería:
```Python
my_list: list[str]
```
En versiones de Python anteriores a 3.9, sería:
```Python
from typing import List
my_list: List[str]
```
Eso es toda la sintaxis estándar de Python para declaraciones de tipo.
Usa esa misma sintaxis estándar para atributos de modelos con tipos internos.
Así, en nuestro ejemplo, podemos hacer que `tags` sea específicamente una "lista de strings":
{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
## Tipos de conjunto
Pero luego pensamos en ello, y nos damos cuenta de que los tags no deberían repetirse, probablemente serían strings únicos.
Y Python tiene un tipo de datos especial para conjuntos de elementos únicos, el `set`.
Entonces podemos declarar `tags` como un conjunto de strings:
{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
Con esto, incluso si recibes un request con datos duplicados, se convertirá en un conjunto de elementos únicos.
Y siempre que emitas esos datos, incluso si la fuente tenía duplicados, se emitirá como un conjunto de elementos únicos.
Y también se anotará/documentará en consecuencia.
## Modelos Anidados
Cada atributo de un modelo Pydantic tiene un tipo.
Pero ese tipo puede ser en sí mismo otro modelo Pydantic.
Así que, puedes declarar "objetos" JSON anidados profundamente con nombres de atributos específicos, tipos y validaciones.
Todo eso, de manera arbitraria.
### Definir un submodelo
Por ejemplo, podemos definir un modelo `Image`:
{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
### Usar el submodelo como tipo
Y luego podemos usarlo como el tipo de un atributo:
{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
Esto significaría que **FastAPI** esperaría un cuerpo similar a:
```JSON
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2,
"tags": ["rock", "metal", "bar"],
"image": {
"url": "http://example.com/baz.jpg",
"name": "The Foo live"
}
}
```
Nuevamente, haciendo solo esa declaración, con **FastAPI** obtienes:
* Soporte de editor (autocompletado, etc.), incluso para modelos anidados
* Conversión de datos
* Validación de datos
* Documentación automática
## Tipos especiales y validación
Además de tipos singulares normales como `str`, `int`, `float`, etc., puedes usar tipos singulares más complejos que heredan de `str`.
Para ver todas las opciones que tienes, revisa el <a href="https://docs.pydantic.dev/latest/concepts/types/" class="external-link" target="_blank">Overview de Tipos de Pydantic</a>. Verás algunos ejemplos en el siguiente capítulo.
Por ejemplo, como en el modelo `Image` tenemos un campo `url`, podemos declararlo como una instance de `HttpUrl` de Pydantic en lugar de un `str`:
{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
El string será verificado para ser una URL válida, y documentado en JSON Schema / OpenAPI como tal.
## Atributos con listas de submodelos
También puedes usar modelos Pydantic como subtipos de `list`, `set`, etc.:
{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
Esto esperará (convertirá, validará, documentará, etc.) un cuerpo JSON como:
```JSON hl_lines="11"
{
"name": "Foo",
"description": "The pretender",
"price": 42.0,
"tax": 3.2,
"tags": [
"rock",
"metal",
"bar"
],
"images": [
{
"url": "http://example.com/baz.jpg",
"name": "The Foo live"
},
{
"url": "http://example.com/dave.jpg",
"name": "The Baz"
}
]
}
```
/// info | Información
Nota cómo la clave `images` ahora tiene una lista de objetos de imagen.
///
## Modelos anidados profundamente
Puedes definir modelos anidados tan profundamente como desees:
{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
/// info | Información
Observa cómo `Offer` tiene una lista de `Item`s, que a su vez tienen una lista opcional de `Image`s
///
## Cuerpos de listas puras
Si el valor superior del cuerpo JSON que esperas es un `array` JSON (una `list` en Python), puedes declarar el tipo en el parámetro de la función, al igual que en los modelos Pydantic:
```Python
images: List[Image]
```
o en Python 3.9 y superior:
```Python
images: list[Image]
```
como en:
{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
## Soporte de editor en todas partes
Y obtienes soporte de editor en todas partes.
Incluso para elementos dentro de listas:
<img src="/img/tutorial/body-nested-models/image01.png">
No podrías obtener este tipo de soporte de editor si estuvieras trabajando directamente con `dict` en lugar de modelos Pydantic.
Pero tampoco tienes que preocuparte por ellos, los `dicts` entrantes se convierten automáticamente y tu salida se convierte automáticamente a JSON también.
## Cuerpos de `dict`s arbitrarios
También puedes declarar un cuerpo como un `dict` con claves de algún tipo y valores de algún otro tipo.
De esta manera, no tienes que saber de antemano cuáles son los nombres válidos de campo/atributo (como sería el caso con modelos Pydantic).
Esto sería útil si deseas recibir claves que aún no conoces.
---
Otro caso útil es cuando deseas tener claves de otro tipo (por ejemplo, `int`).
Eso es lo que vamos a ver aquí.
En este caso, aceptarías cualquier `dict` siempre que tenga claves `int` con valores `float`:
{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
/// tip | Consejo
Ten en cuenta que JSON solo admite `str` como claves.
Pero Pydantic tiene conversión automática de datos.
Esto significa que, aunque tus clientes de API solo pueden enviar strings como claves, mientras esos strings contengan enteros puros, Pydantic los convertirá y validará.
Y el `dict` que recibas como `weights` tendrá realmente claves `int` y valores `float`.
///
## Resumen
Con **FastAPI** tienes la máxima flexibilidad proporcionada por los modelos Pydantic, manteniendo tu código simple, corto y elegante.
Pero con todos los beneficios:
* Soporte de editor (¡autocompletado en todas partes!)
* Conversión de datos (también conocido como parsing/serialización)
* Validación de datos
* Documentación del esquema
* Documentación automática

116
docs/es/docs/tutorial/body-updates.md Normal file
View File

@@ -0,0 +1,116 @@
# Cuerpo - Actualizaciones
## Actualización reemplazando con `PUT`
Para actualizar un ítem puedes utilizar la operación de <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT" class="external-link" target="_blank">HTTP `PUT`</a>.
Puedes usar el `jsonable_encoder` para convertir los datos de entrada en datos que se puedan almacenar como JSON (por ejemplo, con una base de datos NoSQL). Por ejemplo, convirtiendo `datetime` a `str`.
{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *}
`PUT` se usa para recibir datos que deben reemplazar los datos existentes.
### Advertencia sobre el reemplazo
Esto significa que si quieres actualizar el ítem `bar` usando `PUT` con un body que contenga:
```Python
{
"name": "Barz",
"price": 3,
"description": None,
}
```
debido a que no incluye el atributo ya almacenado `"tax": 20.2`, el modelo de entrada tomaría el valor por defecto de `"tax": 10.5`.
Y los datos se guardarían con ese "nuevo" `tax` de `10.5`.
## Actualizaciones parciales con `PATCH`
También puedes usar la operación de <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH" class="external-link" target="_blank">HTTP `PATCH`</a> para actualizar *parcialmente* datos.
Esto significa que puedes enviar solo los datos que deseas actualizar, dejando el resto intacto.
/// note | Nota
`PATCH` es menos usado y conocido que `PUT`.
Y muchos equipos utilizan solo `PUT`, incluso para actualizaciones parciales.
Eres **libre** de usarlos como desees, **FastAPI** no impone ninguna restricción.
Pero esta guía te muestra, más o menos, cómo se pretende que se usen.
///
### Uso del parámetro `exclude_unset` de Pydantic
Si quieres recibir actualizaciones parciales, es muy útil usar el parámetro `exclude_unset` en el `.model_dump()` del modelo de Pydantic.
Como `item.model_dump(exclude_unset=True)`.
/// info | Información
En Pydantic v1 el método se llamaba `.dict()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_dump()`.
Los ejemplos aquí usan `.dict()` para compatibilidad con Pydantic v1, pero deberías usar `.model_dump()` si puedes usar Pydantic v2.
///
Eso generaría un `dict` solo con los datos que se establecieron al crear el modelo `item`, excluyendo los valores por defecto.
Luego puedes usar esto para generar un `dict` solo con los datos que se establecieron (enviados en el request), omitiendo los valores por defecto:
{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
### Uso del parámetro `update` de Pydantic
Ahora, puedes crear una copia del modelo existente usando `.model_copy()`, y pasar el parámetro `update` con un `dict` que contenga los datos a actualizar.
/// info | Información
En Pydantic v1 el método se llamaba `.copy()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_copy()`.
Los ejemplos aquí usan `.copy()` para compatibilidad con Pydantic v1, pero deberías usar `.model_copy()` si puedes usar Pydantic v2.
///
Como `stored_item_model.model_copy(update=update_data)`:
{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
### Resumen de actualizaciones parciales
En resumen, para aplicar actualizaciones parciales deberías:
* (Opcionalmente) usar `PATCH` en lugar de `PUT`.
* Recuperar los datos almacenados.
* Poner esos datos en un modelo de Pydantic.
* Generar un `dict` sin valores por defecto del modelo de entrada (usando `exclude_unset`).
* De esta manera puedes actualizar solo los valores realmente establecidos por el usuario, en lugar de sobrescribir valores ya almacenados con valores por defecto en tu modelo.
* Crear una copia del modelo almacenado, actualizando sus atributos con las actualizaciones parciales recibidas (usando el parámetro `update`).
* Convertir el modelo copiado en algo que pueda almacenarse en tu base de datos (por ejemplo, usando el `jsonable_encoder`).
* Esto es comparable a usar el método `.model_dump()` del modelo de nuevo, pero asegura (y convierte) los valores a tipos de datos que pueden convertirse a JSON, por ejemplo, `datetime` a `str`.
* Guardar los datos en tu base de datos.
* Devolver el modelo actualizado.
{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}
/// tip | Consejo
Puedes realmente usar esta misma técnica con una operación HTTP `PUT`.
Pero el ejemplo aquí usa `PATCH` porque fue creado para estos casos de uso.
///
/// note | Nota
Observa que el modelo de entrada sigue siendo validado.
Entonces, si deseas recibir actualizaciones parciales que puedan omitir todos los atributos, necesitas tener un modelo con todos los atributos marcados como opcionales (con valores por defecto o `None`).
Para distinguir entre los modelos con todos los valores opcionales para **actualizaciones** y modelos con valores requeridos para **creación**, puedes utilizar las ideas descritas en [Modelos Extra](extra-models.md){.internal-link target=_blank}.
///

164
docs/es/docs/tutorial/body.md Normal file
View File

@@ -0,0 +1,164 @@
# Request Body
Cuando necesitas enviar datos desde un cliente (digamos, un navegador) a tu API, los envías como un **request body**.
Un **request** body es un dato enviado por el cliente a tu API. Un **response** body es el dato que tu API envía al cliente.
Tu API casi siempre tiene que enviar un **response** body. Pero los clientes no necesariamente necesitan enviar **request bodies** todo el tiempo, a veces solo solicitan un path, quizás con algunos parámetros de query, pero no envían un body.
Para declarar un **request** body, usas modelos de <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> con todo su poder y beneficios.
/// info | Información
Para enviar datos, deberías usar uno de estos métodos: `POST` (el más común), `PUT`, `DELETE` o `PATCH`.
Enviar un body con un request `GET` tiene un comportamiento indefinido en las especificaciones, no obstante, es soportado por FastAPI, solo para casos de uso muy complejos/extremos.
Como no se recomienda, la documentación interactiva con Swagger UI no mostrará la documentación para el body cuando se usa `GET`, y los proxies intermedios podrían no soportarlo.
///
## Importar `BaseModel` de Pydantic
Primero, necesitas importar `BaseModel` de `pydantic`:
{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
## Crea tu modelo de datos
Luego, declaras tu modelo de datos como una clase que hereda de `BaseModel`.
Usa tipos estándar de Python para todos los atributos:
{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
Al igual que al declarar parámetros de query, cuando un atributo del modelo tiene un valor por defecto, no es obligatorio. De lo contrario, es obligatorio. Usa `None` para hacerlo opcional.
Por ejemplo, el modelo anterior declara un “`object`” JSON (o `dict` en Python) como:
```JSON
{
"name": "Foo",
"description": "An optional description",
"price": 45.2,
"tax": 3.5
}
```
...dado que `description` y `tax` son opcionales (con un valor por defecto de `None`), este “`object`” JSON también sería válido:
```JSON
{
"name": "Foo",
"price": 45.2
}
```
## Decláralo como un parámetro
Para añadirlo a tu *path operation*, decláralo de la misma manera que declaraste parámetros de path y query:
{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
...y declara su tipo como el modelo que creaste, `Item`.
## Resultados
Con solo esa declaración de tipo en Python, **FastAPI** hará lo siguiente:
* Leer el body del request como JSON.
* Convertir los tipos correspondientes (si es necesario).
* Validar los datos.
* Si los datos son inválidos, devolverá un error claro e indicado, señalando exactamente dónde y qué fue lo incorrecto.
* Proporcionar los datos recibidos en el parámetro `item`.
* Como lo declaraste en la función como de tipo `Item`, también tendrás todo el soporte del editor (autocompletado, etc.) para todos los atributos y sus tipos.
* Generar definiciones de <a href="https://json-schema.org" class="external-link" target="_blank">JSON Schema</a> para tu modelo, que también puedes usar en cualquier otro lugar si tiene sentido para tu proyecto.
* Esquemas que serán parte del esquema de OpenAPI generado y usados por la <abbr title="User Interfaces">UIs</abbr> de documentación automática.
## Documentación automática
Los JSON Schemas de tus modelos serán parte del esquema OpenAPI generado y se mostrarán en la documentación API interactiva:
<img src="/img/tutorial/body/image01.png">
Y también se utilizarán en la documentación API dentro de cada *path operation* que los necesite:
<img src="/img/tutorial/body/image02.png">
## Soporte del editor
En tu editor, dentro de tu función, obtendrás anotaciones de tipos y autocompletado en todas partes (esto no sucedería si recibieras un `dict` en lugar de un modelo de Pydantic):
<img src="/img/tutorial/body/image03.png">
También recibirás chequeos de errores para operaciones de tipo incorrecto:
<img src="/img/tutorial/body/image04.png">
No es por casualidad, todo el framework fue construido alrededor de ese diseño.
Y fue rigurosamente probado en la fase de diseño, antes de cualquier implementación, para garantizar que funcionaría con todos los editores.
Incluso se hicieron algunos cambios en Pydantic para admitir esto.
Las capturas de pantalla anteriores se tomaron con <a href="https://code.visualstudio.com" class="external-link" target="_blank">Visual Studio Code</a>.
Pero obtendrías el mismo soporte en el editor con <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> y la mayoría de los otros editores de Python:
<img src="/img/tutorial/body/image05.png">
/// tip | Consejo
Si usas <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a> como tu editor, puedes usar el <a href="https://github.com/koxudaxi/pydantic-pycharm-plugin/" class="external-link" target="_blank">Pydantic PyCharm Plugin</a>.
Mejora el soporte del editor para modelos de Pydantic, con:
* autocompletado
* chequeo de tipos
* refactorización
* búsqueda
* inspecciones
///
## Usa el modelo
Dentro de la función, puedes acceder a todos los atributos del objeto modelo directamente:
{* ../../docs_src/body/tutorial002_py310.py *}
## Request body + parámetros de path
Puedes declarar parámetros de path y request body al mismo tiempo.
**FastAPI** reconocerá que los parámetros de función que coinciden con los parámetros de path deben ser **tomados del path**, y que los parámetros de función que se declaran como modelos de Pydantic deben ser **tomados del request body**.
{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
## Request body + path + parámetros de query
También puedes declarar parámetros de **body**, **path** y **query**, todos al mismo tiempo.
**FastAPI** reconocerá cada uno de ellos y tomará los datos del lugar correcto.
{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
Los parámetros de la función se reconocerán de la siguiente manera:
* Si el parámetro también se declara en el **path**, se utilizará como un parámetro de path.
* Si el parámetro es de un **tipo singular** (como `int`, `float`, `str`, `bool`, etc.), se interpretará como un parámetro de **query**.
* Si el parámetro se declara como del tipo de un **modelo de Pydantic**, se interpretará como un **request body**.
/// note | Nota
FastAPI sabrá que el valor de `q` no es requerido debido al valor por defecto `= None`.
El `str | None` (Python 3.10+) o `Union` en `Union[str, None]` (Python 3.8+) no es utilizado por FastAPI para determinar que el valor no es requerido, sabrá que no es requerido porque tiene un valor por defecto de `= None`.
Pero agregar las anotaciones de tipos permitirá que tu editor te brinde un mejor soporte y detecte errores.
///
## Sin Pydantic
Si no quieres usar modelos de Pydantic, también puedes usar parámetros **Body**. Consulta la documentación para [Body - Multiples Parametros: Valores singulares en body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.

76
docs/es/docs/tutorial/cookie-param-models.md Normal file
View File

@@ -0,0 +1,76 @@
# Modelos de Cookies
Si tienes un grupo de **cookies** que están relacionadas, puedes crear un **modelo de Pydantic** para declararlas. 🍪
Esto te permitirá **reutilizar el modelo** en **múltiples lugares** y también declarar validaciones y metadatos para todos los parámetros a la vez. 😎
/// note | Nota
Esto es compatible desde la versión `0.115.0` de FastAPI. 🤓
///
/// tip | Consejo
Esta misma técnica se aplica a `Query`, `Cookie`, y `Header`. 😎
///
## Cookies con un Modelo de Pydantic
Declara los parámetros de **cookie** que necesites en un **modelo de Pydantic**, y luego declara el parámetro como `Cookie`:
{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
**FastAPI** **extraerá** los datos para **cada campo** de las **cookies** recibidas en el request y te entregará el modelo de Pydantic que definiste.
## Revisa la Documentación
Puedes ver las cookies definidas en la UI de la documentación en `/docs`:
<div class="screenshot">
<img src="/img/tutorial/cookie-param-models/image01.png">
</div>
/// info | Información
Ten en cuenta que, como los **navegadores manejan las cookies** de maneras especiales y detrás de escenas, **no** permiten fácilmente que **JavaScript** las toque.
Si vas a la **UI de la documentación de la API** en `/docs` podrás ver la **documentación** de las cookies para tus *path operations*.
Pero incluso si **rellenas los datos** y haces clic en "Execute", como la UI de la documentación funciona con **JavaScript**, las cookies no serán enviadas y verás un **mensaje de error** como si no hubieras escrito ningún valor.
///
## Prohibir Cookies Extra
En algunos casos de uso especiales (probablemente no muy comunes), podrías querer **restringir** las cookies que deseas recibir.
Tu API ahora tiene el poder de controlar su propio <abbr title="Esto es una broma, por si acaso. No tiene nada que ver con los consentimientos de cookies, pero es gracioso que incluso la API ahora pueda rechazar las pobres cookies. Toma una cookie. 🍪">consentimiento de cookies</abbr>. 🤪🍪
Puedes usar la configuración del modelo de Pydantic para `prohibir` cualquier campo `extra`:
{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *}
Si un cliente intenta enviar algunas **cookies extra**, recibirán un response de **error**.
Pobres banners de cookies con todo su esfuerzo para obtener tu consentimiento para que la <abbr title="Esta es otra broma. No me prestes atención. Toma un café para tu cookie. ☕">API lo rechace</abbr>. 🍪
Por ejemplo, si el cliente intenta enviar una cookie `santa_tracker` con un valor de `good-list-please`, el cliente recibirá un response de **error** que le informa que la cookie `santa_tracker` <abbr title="Santa desaprueba la falta de cookies. 🎅 Está bien, no más bromas de cookies.">no está permitida</abbr>:
```json
{
"detail": [
{
"type": "extra_forbidden",
"loc": ["cookie", "santa_tracker"],
"msg": "Extra inputs are not permitted",
"input": "good-list-please",
}
]
}
```
## Resumen
Puedes usar **modelos de Pydantic** para declarar <abbr title="Toma una última cookie antes de irte. 🍪">**cookies**</abbr> en **FastAPI**. 😎

85
docs/es/docs/tutorial/cors.md Normal file
View File

@@ -0,0 +1,85 @@
# CORS (Cross-Origin Resource Sharing)
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">CORS o "Cross-Origin Resource Sharing"</a> se refiere a situaciones en las que un frontend que se ejecuta en un navegador tiene código JavaScript que se comunica con un backend, y el backend está en un "origen" diferente al frontend.
## Origen
Un origen es la combinación de protocolo (`http`, `https`), dominio (`myapp.com`, `localhost`, `localhost.tiangolo.com`) y puerto (`80`, `443`, `8080`).
Así que, todos estos son orígenes diferentes:
* `http://localhost`
* `https://localhost`
* `http://localhost:8080`
Aunque todos están en `localhost`, usan protocolos o puertos diferentes, por lo tanto, son "orígenes" diferentes.
## Pasos
Entonces, digamos que tienes un frontend corriendo en tu navegador en `http://localhost:8080`, y su JavaScript está tratando de comunicarse con un backend corriendo en `http://localhost` (porque no especificamos un puerto, el navegador asumirá el puerto por defecto `80`).
Entonces, el navegador enviará un request HTTP `OPTIONS` al backend `:80`, y si el backend envía los headers apropiados autorizando la comunicación desde este origen diferente (`http://localhost:8080`), entonces el navegador `:8080` permitirá que el JavaScript en el frontend envíe su request al backend `:80`.
Para lograr esto, el backend `:80` debe tener una lista de "orígenes permitidos".
En este caso, la lista tendría que incluir `http://localhost:8080` para que el frontend `:8080` funcione correctamente.
## Comodines
También es posible declarar la lista como `"*"` (un "comodín") para decir que todos están permitidos.
Pero eso solo permitirá ciertos tipos de comunicación, excluyendo todo lo que implique credenciales: Cookies, headers de autorización como los utilizados con Bearer Tokens, etc.
Así que, para que todo funcione correctamente, es mejor especificar explícitamente los orígenes permitidos.
## Usa `CORSMiddleware`
Puedes configurarlo en tu aplicación **FastAPI** usando el `CORSMiddleware`.
* Importa `CORSMiddleware`.
* Crea una lista de orígenes permitidos (como strings).
* Agrégalo como un "middleware" a tu aplicación **FastAPI**.
También puedes especificar si tu backend permite:
* Credenciales (headers de autorización, cookies, etc).
* Métodos HTTP específicos (`POST`, `PUT`) o todos ellos con el comodín `"*"`.
* Headers HTTP específicos o todos ellos con el comodín `"*"`.
{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
Los parámetros predeterminados utilizados por la implementación de `CORSMiddleware` son restrictivos por defecto, por lo que necesitarás habilitar explícitamente orígenes, métodos o headers particulares para que los navegadores estén permitidos de usarlos en un contexto de Cross-Domain.
Se admiten los siguientes argumentos:
* `allow_origins` - Una lista de orígenes que deberían estar permitidos para hacer requests cross-origin. Por ejemplo, `['https://example.org', 'https://www.example.org']`. Puedes usar `['*']` para permitir cualquier origen.
* `allow_origin_regex` - Una cadena regex para coincidir con orígenes que deberían estar permitidos para hacer requests cross-origin. por ejemplo, `'https://.*\.example\.org'`.
* `allow_methods` - Una lista de métodos HTTP que deberían estar permitidos para requests cross-origin. Por defecto es `['GET']`. Puedes usar `['*']` para permitir todos los métodos estándar.
* `allow_headers` - Una lista de headers de request HTTP que deberían estar soportados para requests cross-origin. Por defecto es `[]`. Puedes usar `['*']` para permitir todos los headers. Los headers `Accept`, `Accept-Language`, `Content-Language` y `Content-Type` siempre están permitidos para <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests" class="external-link" rel="noopener" target="_blank">requests CORS simples</a>.
* `allow_credentials` - Indica que las cookies deberían estar soportadas para requests cross-origin. Por defecto es `False`. Además, `allow_origins` no puede ser configurado a `['*']` para que las credenciales estén permitidas, los orígenes deben ser especificados.
* `expose_headers` - Indica cualquier header de response que debería ser accesible para el navegador. Por defecto es `[]`.
* `max_age` - Establece un tiempo máximo en segundos para que los navegadores almacenen en caché los responses CORS. Por defecto es `600`.
El middleware responde a dos tipos particulares de request HTTP...
### Requests de preflight CORS
Estos son cualquier request `OPTIONS` con headers `Origin` y `Access-Control-Request-Method`.
En este caso, el middleware interceptará el request entrante y responderá con los headers CORS adecuados, y un response `200` o `400` con fines informativos.
### Requests simples
Cualquier request con un header `Origin`. En este caso, el middleware pasará el request a través de lo normal, pero incluirá los headers CORS adecuados en el response.
## Más info
Para más información sobre <abbr title="Cross-Origin Resource Sharing">CORS</abbr>, revisa la <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">documentación de CORS de Mozilla</a>.
/// note | Detalles Técnicos
También podrías usar `from starlette.middleware.cors import CORSMiddleware`.
**FastAPI** proporciona varios middlewares en `fastapi.middleware` como una conveniencia para ti, el desarrollador. Pero la mayoría de los middlewares disponibles provienen directamente de Starlette.
///

113
docs/es/docs/tutorial/debugging.md Normal file
View File

@@ -0,0 +1,113 @@
# Depuración
Puedes conectar el depurador en tu editor, por ejemplo con Visual Studio Code o PyCharm.
## Llama a `uvicorn`
En tu aplicación de FastAPI, importa y ejecuta `uvicorn` directamente:
{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
### Acerca de `__name__ == "__main__"`
El objetivo principal de `__name__ == "__main__"` es tener algo de código que se ejecute cuando tu archivo es llamado con:
<div class="termy">
```console
$ python myapp.py
```
</div>
pero no es llamado cuando otro archivo lo importa, como en:
```Python
from myapp import app
```
#### Más detalles
Supongamos que tu archivo se llama `myapp.py`.
Si lo ejecutas con:
<div class="termy">
```console
$ python myapp.py
```
</div>
entonces la variable interna `__name__` en tu archivo, creada automáticamente por Python, tendrá como valor el string `"__main__"`.
Así que, la sección:
```Python
uvicorn.run(app, host="0.0.0.0", port=8000)
```
se ejecutará.
---
Esto no ocurrirá si importas ese módulo (archivo).
Entonces, si tienes otro archivo `importer.py` con:
```Python
from myapp import app
# Algún código adicional
```
en ese caso, la variable creada automáticamente dentro de `myapp.py` no tendrá la variable `__name__` con un valor de `"__main__"`.
Así que, la línea:
```Python
uvicorn.run(app, host="0.0.0.0", port=8000)
```
no se ejecutará.
/// info | Información
Para más información, revisa <a href="https://docs.python.org/3/library/__main__.html" class="external-link" target="_blank">la documentación oficial de Python</a>.
///
## Ejecuta tu código con tu depurador
Dado que estás ejecutando el servidor Uvicorn directamente desde tu código, puedes llamar a tu programa de Python (tu aplicación FastAPI) directamente desde el depurador.
---
Por ejemplo, en Visual Studio Code, puedes:
* Ir al panel de "Debug".
* "Add configuration...".
* Seleccionar "Python".
* Ejecutar el depurador con la opción "`Python: Current File (Integrated Terminal)`".
Luego, iniciará el servidor con tu código **FastAPI**, deteniéndose en tus puntos de interrupción, etc.
Así es como podría verse:
<img src="/img/tutorial/debugging/image01.png">
---
Si usas PyCharm, puedes:
* Abrir el menú "Run".
* Seleccionar la opción "Debug...".
* Luego aparece un menú contextual.
* Selecciona el archivo para depurar (en este caso, `main.py`).
Luego, iniciará el servidor con tu código **FastAPI**, deteniéndose en tus puntos de interrupción, etc.
Así es como podría verse:
<img src="/img/tutorial/debugging/image02.png">

288
docs/es/docs/tutorial/dependencies/classes-as-dependencies.md Normal file
View File

@@ -0,0 +1,288 @@
# Clases como dependencias
Antes de profundizar en el sistema de **Inyección de Dependencias**, vamos a mejorar el ejemplo anterior.
## Un `dict` del ejemplo anterior
En el ejemplo anterior, estábamos devolviendo un `dict` de nuestra dependencia ("dependable"):
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[9] *}
Pero luego obtenemos un `dict` en el parámetro `commons` de la *path operation function*.
Y sabemos que los editores no pueden proporcionar mucho soporte (como autocompletado) para `dict`s, porque no pueden conocer sus claves y tipos de valor.
Podemos hacerlo mejor...
## Qué hace a una dependencia
Hasta ahora has visto dependencias declaradas como funciones.
Pero esa no es la única forma de declarar dependencias (aunque probablemente sea la más común).
El factor clave es que una dependencia debe ser un "callable".
Un "**callable**" en Python es cualquier cosa que Python pueda "llamar" como una función.
Entonces, si tienes un objeto `something` (que podría _no_ ser una función) y puedes "llamarlo" (ejecutarlo) como:
```Python
something()
```
o
```Python
something(some_argument, some_keyword_argument="foo")
```
entonces es un "callable".
## Clases como dependencias
Puedes notar que para crear una instance de una clase en Python, utilizas esa misma sintaxis.
Por ejemplo:
```Python
class Cat:
def __init__(self, name: str):
self.name = name
fluffy = Cat(name="Mr Fluffy")
```
En este caso, `fluffy` es una instance de la clase `Cat`.
Y para crear `fluffy`, estás "llamando" a `Cat`.
Entonces, una clase en Python también es un **callable**.
Entonces, en **FastAPI**, podrías usar una clase de Python como una dependencia.
Lo que **FastAPI** realmente comprueba es que sea un "callable" (función, clase o cualquier otra cosa) y los parámetros definidos.
Si pasas un "callable" como dependencia en **FastAPI**, analizará los parámetros de ese "callable", y los procesará de la misma manera que los parámetros de una *path operation function*. Incluyendo sub-dependencias.
Eso también se aplica a los callables sin parámetros. Igual que sería para *path operation functions* sin parámetros.
Entonces, podemos cambiar la dependencia "dependable" `common_parameters` de arriba a la clase `CommonQueryParams`:
{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[11:15] *}
Presta atención al método `__init__` usado para crear la instance de la clase:
{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[12] *}
...tiene los mismos parámetros que nuestros `common_parameters` anteriores:
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8] *}
Esos parámetros son los que **FastAPI** usará para "resolver" la dependencia.
En ambos casos, tendrá:
* Un parámetro de query `q` opcional que es un `str`.
* Un parámetro de query `skip` que es un `int`, con un valor por defecto de `0`.
* Un parámetro de query `limit` que es un `int`, con un valor por defecto de `100`.
En ambos casos, los datos serán convertidos, validados, documentados en el esquema de OpenAPI, etc.
## Úsalo
Ahora puedes declarar tu dependencia usando esta clase.
{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[19] *}
**FastAPI** llama a la clase `CommonQueryParams`. Esto crea una "instance" de esa clase y la instance será pasada como el parámetro `commons` a tu función.
## Anotación de tipos vs `Depends`
Nota cómo escribimos `CommonQueryParams` dos veces en el código anterior:
//// tab | Python 3.8+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
```
////
//// tab | Python 3.8+ sin `Annotated`
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python
commons: CommonQueryParams = Depends(CommonQueryParams)
```
////
El último `CommonQueryParams`, en:
```Python
... Depends(CommonQueryParams)
```
...es lo que **FastAPI** utilizará realmente para saber cuál es la dependencia.
Es a partir de este que **FastAPI** extraerá los parámetros declarados y es lo que **FastAPI** realmente llamará.
---
En este caso, el primer `CommonQueryParams`, en:
//// tab | Python 3.8+
```Python
commons: Annotated[CommonQueryParams, ...
```
////
//// tab | Python 3.8+ sin `Annotated`
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python
commons: CommonQueryParams ...
```
////
...no tiene ningún significado especial para **FastAPI**. **FastAPI** no lo usará para la conversión de datos, validación, etc. (ya que está usando `Depends(CommonQueryParams)` para eso).
De hecho, podrías escribir simplemente:
//// tab | Python 3.8+
```Python
commons: Annotated[Any, Depends(CommonQueryParams)]
```
////
//// tab | Python 3.8+ sin `Annotated`
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python
commons = Depends(CommonQueryParams)
```
////
...como en:
{* ../../docs_src/dependencies/tutorial003_an_py310.py hl[19] *}
Pero declarar el tipo es recomendable, ya que de esa manera tu editor sabrá lo que se pasará como el parámetro `commons`, y entonces podrá ayudarte con el autocompletado, chequeo de tipos, etc:
<img src="/img/tutorial/dependencies/image02.png">
## Atajo
Pero ves que estamos teniendo algo de repetición de código aquí, escribiendo `CommonQueryParams` dos veces:
//// tab | Python 3.8+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
```
////
//// tab | Python 3.8+ sin `Annotated`
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python
commons: CommonQueryParams = Depends(CommonQueryParams)
```
////
**FastAPI** proporciona un atajo para estos casos, en donde la dependencia es *específicamente* una clase que **FastAPI** "llamará" para crear una instance de la clase misma.
Para esos casos específicos, puedes hacer lo siguiente:
En lugar de escribir:
//// tab | Python 3.8+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
```
////
//// tab | Python 3.8+ sin `Annotated`
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python
commons: CommonQueryParams = Depends(CommonQueryParams)
```
////
...escribes:
//// tab | Python 3.8+
```Python
commons: Annotated[CommonQueryParams, Depends()]
```
////
//// tab | Python 3.8 sin `Annotated`
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python
commons: CommonQueryParams = Depends()
```
////
Declaras la dependencia como el tipo del parámetro, y usas `Depends()` sin ningún parámetro, en lugar de tener que escribir la clase completa *otra vez* dentro de `Depends(CommonQueryParams)`.
El mismo ejemplo se vería entonces así:
{* ../../docs_src/dependencies/tutorial004_an_py310.py hl[19] *}
...y **FastAPI** sabrá qué hacer.
/// tip | Consejo
Si eso parece más confuso que útil, ignóralo, no lo *necesitas*.
Es solo un atajo. Porque a **FastAPI** le importa ayudarte a minimizar la repetición de código.
///

69
docs/es/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md Normal file
View File

@@ -0,0 +1,69 @@
# Dependencias en decoradores de *path operation*
En algunos casos realmente no necesitas el valor de retorno de una dependencia dentro de tu *path operation function*.
O la dependencia no devuelve un valor.
Pero aún necesitas que sea ejecutada/resuelta.
Para esos casos, en lugar de declarar un parámetro de *path operation function* con `Depends`, puedes añadir una `list` de `dependencies` al decorador de *path operation*.
## Agregar `dependencies` al decorador de *path operation*
El decorador de *path operation* recibe un argumento opcional `dependencies`.
Debe ser una `list` de `Depends()`:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[19] *}
Estas dependencias serán ejecutadas/resueltas de la misma manera que las dependencias normales. Pero su valor (si devuelven alguno) no será pasado a tu *path operation function*.
/// tip | Consejo
Algunos editores revisan los parámetros de función no usados y los muestran como errores.
Usando estas `dependencies` en el decorador de *path operation* puedes asegurarte de que se ejecutan mientras evitas errores en editores/herramientas.
También puede ayudar a evitar confusiones para nuevos desarrolladores que vean un parámetro no usado en tu código y puedan pensar que es innecesario.
///
/// info | Información
En este ejemplo usamos headers personalizados inventados `X-Key` y `X-Token`.
Pero en casos reales, al implementar seguridad, obtendrías más beneficios usando las [Utilidades de Seguridad integradas (el próximo capítulo)](../security/index.md){.internal-link target=_blank}.
///
## Errores de dependencias y valores de retorno
Puedes usar las mismas *funciones* de dependencia que usas normalmente.
### Requisitos de dependencia
Pueden declarar requisitos de request (como headers) u otras sub-dependencias:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
### Lanzar excepciones
Estas dependencias pueden `raise` excepciones, igual que las dependencias normales:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
### Valores de retorno
Y pueden devolver valores o no, los valores no serán usados.
Así que, puedes reutilizar una dependencia normal (que devuelve un valor) que ya uses en otro lugar, y aunque el valor no se use, la dependencia será ejecutada:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
## Dependencias para un grupo de *path operations*
Más adelante, cuando leas sobre cómo estructurar aplicaciones más grandes ([Aplicaciones Más Grandes - Múltiples Archivos](../../tutorial/bigger-applications.md){.internal-link target=_blank}), posiblemente con múltiples archivos, aprenderás cómo declarar un único parámetro `dependencies` para un grupo de *path operations*.
## Dependencias Globales
A continuación veremos cómo añadir dependencias a toda la aplicación `FastAPI`, de modo que se apliquen a cada *path operation*.

275
docs/es/docs/tutorial/dependencies/dependencies-with-yield.md Normal file
View File

@@ -0,0 +1,275 @@
# Dependencias con yield
FastAPI admite dependencias que realizan algunos <abbr title='sometimes also called "exit code", "cleanup code", "teardown code", "closing code", "context manager exit code", etc.'>pasos adicionales después de finalizar</abbr>.
Para hacer esto, usa `yield` en lugar de `return` y escribe los pasos adicionales (código) después.
/// tip | Consejo
Asegúrate de usar `yield` una sola vez por dependencia.
///
/// note | Nota técnica
Cualquier función que sea válida para usar con:
* <a href="https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager" class="external-link" target="_blank">`@contextlib.contextmanager`</a> o
* <a href="https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager" class="external-link" target="_blank">`@contextlib.asynccontextmanager`</a>
sería válida para usar como una dependencia en **FastAPI**.
De hecho, FastAPI usa esos dos decoradores internamente.
///
## Una dependencia de base de datos con `yield`
Por ejemplo, podrías usar esto para crear una sesión de base de datos y cerrarla después de finalizar.
Solo el código anterior e incluyendo la declaración `yield` se ejecuta antes de crear un response:
{* ../../docs_src/dependencies/tutorial007.py hl[2:4] *}
El valor generado es lo que se inyecta en *path operations* y otras dependencias:
{* ../../docs_src/dependencies/tutorial007.py hl[4] *}
El código posterior a la declaración `yield` se ejecuta después de crear el response pero antes de enviarla:
{* ../../docs_src/dependencies/tutorial007.py hl[5:6] *}
/// tip | Consejo
Puedes usar funciones `async` o regulares.
**FastAPI** hará lo correcto con cada una, igual que con dependencias normales.
///
## Una dependencia con `yield` y `try`
Si usas un bloque `try` en una dependencia con `yield`, recibirás cualquier excepción que se haya lanzado al usar la dependencia.
Por ejemplo, si algún código en algún punto intermedio, en otra dependencia o en una *path operation*, realiza un "rollback" en una transacción de base de datos o crea cualquier otro error, recibirás la excepción en tu dependencia.
Por lo tanto, puedes buscar esa excepción específica dentro de la dependencia con `except SomeException`.
Del mismo modo, puedes usar `finally` para asegurarte de que los pasos de salida se ejecuten, sin importar si hubo una excepción o no.
{* ../../docs_src/dependencies/tutorial007.py hl[3,5] *}
## Sub-dependencias con `yield`
Puedes tener sub-dependencias y "árboles" de sub-dependencias de cualquier tamaño y forma, y cualquiera o todas ellas pueden usar `yield`.
**FastAPI** se asegurará de que el "código de salida" en cada dependencia con `yield` se ejecute en el orden correcto.
Por ejemplo, `dependency_c` puede tener una dependencia de `dependency_b`, y `dependency_b` de `dependency_a`:
{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[6,14,22] *}
Y todas ellas pueden usar `yield`.
En este caso, `dependency_c`, para ejecutar su código de salida, necesita que el valor de `dependency_b` (aquí llamado `dep_b`) todavía esté disponible.
Y, a su vez, `dependency_b` necesita que el valor de `dependency_a` (aquí llamado `dep_a`) esté disponible para su código de salida.
{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[18:19,26:27] *}
De la misma manera, podrías tener algunas dependencias con `yield` y otras dependencias con `return`, y hacer que algunas de esas dependan de algunas de las otras.
Y podrías tener una sola dependencia que requiera varias otras dependencias con `yield`, etc.
Puedes tener cualquier combinación de dependencias que quieras.
**FastAPI** se asegurará de que todo se ejecute en el orden correcto.
/// note | Nota técnica
Esto funciona gracias a los <a href="https://docs.python.org/3/library/contextlib.html" class="external-link" target="_blank">Context Managers</a> de Python.
**FastAPI** los utiliza internamente para lograr esto.
///
## Dependencias con `yield` y `HTTPException`
Viste que puedes usar dependencias con `yield` y tener bloques `try` que capturen excepciones.
De la misma manera, podrías lanzar una `HTTPException` o similar en el código de salida, después del `yield`.
/// tip | Consejo
Esta es una técnica algo avanzada, y en la mayoría de los casos realmente no lo necesitarás, ya que puedes lanzar excepciones (incluyendo `HTTPException`) desde dentro del resto del código de tu aplicación, por ejemplo, en la *path operation function*.
Pero está ahí para ti si la necesitas. 🤓
///
{* ../../docs_src/dependencies/tutorial008b_an_py39.py hl[18:22,31] *}
Una alternativa que podrías usar para capturar excepciones (y posiblemente también lanzar otra `HTTPException`) es crear un [Manejador de Excepciones Personalizado](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
## Dependencias con `yield` y `except`
Si capturas una excepción usando `except` en una dependencia con `yield` y no la lanzas nuevamente (o lanzas una nueva excepción), FastAPI no podrá notar que hubo una excepción, al igual que sucedería con Python normal:
{* ../../docs_src/dependencies/tutorial008c_an_py39.py hl[15:16] *}
En este caso, el cliente verá un response *HTTP 500 Internal Server Error* como debería, dado que no estamos lanzando una `HTTPException` o similar, pero el servidor **no tendrá ningún registro** ni ninguna otra indicación de cuál fue el error. 😱
### Siempre `raise` en Dependencias con `yield` y `except`
Si capturas una excepción en una dependencia con `yield`, a menos que estés lanzando otra `HTTPException` o similar, deberías volver a lanzar la excepción original.
Puedes volver a lanzar la misma excepción usando `raise`:
{* ../../docs_src/dependencies/tutorial008d_an_py39.py hl[17] *}
Ahora el cliente obtendrá el mismo response *HTTP 500 Internal Server Error*, pero el servidor tendrá nuestro `InternalError` personalizado en los registros. 😎
## Ejecución de dependencias con `yield`
La secuencia de ejecución es más o menos como este diagrama. El tiempo fluye de arriba a abajo. Y cada columna es una de las partes que interactúa o ejecuta código.
```mermaid
sequenceDiagram
participant client as Client
participant handler as Exception handler
participant dep as Dep with yield
participant operation as Path Operation
participant tasks as Background tasks
Note over client,operation: Puede lanzar excepciones, incluyendo HTTPException
client ->> dep: Iniciar request
Note over dep: Ejecutar código hasta yield
opt raise Exception
dep -->> handler: Lanzar Exception
handler -->> client: Response HTTP de error
end
dep ->> operation: Ejecutar dependencia, por ejemplo, sesión de BD
opt raise
operation -->> dep: Lanzar Exception (por ejemplo, HTTPException)
opt handle
dep -->> dep: Puede capturar excepción, lanzar una nueva HTTPException, lanzar otra excepción
end
handler -->> client: Response HTTP de error
end
operation ->> client: Devolver response al cliente
Note over client,operation: El response ya fue enviado, no se puede cambiar
opt Tasks
operation -->> tasks: Enviar tareas en background
end
opt Lanzar otra excepción
tasks -->> tasks: Manejar excepciones en el código de la tarea en background
end
```
/// info | Información
Solo **un response** será enviado al cliente. Podría ser uno de los responses de error o será el response de la *path operation*.
Después de que se envíe uno de esos responses, no se podrá enviar ningún otro response.
///
/// tip | Consejo
Este diagrama muestra `HTTPException`, pero también podrías lanzar cualquier otra excepción que captures en una dependencia con `yield` o con un [Manejador de Excepciones Personalizado](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
Si lanzas alguna excepción, será pasada a las dependencias con yield, incluyendo `HTTPException`. En la mayoría de los casos querrás volver a lanzar esa misma excepción o una nueva desde la dependencia con `yield` para asegurarte de que se maneje correctamente.
///
## Dependencias con `yield`, `HTTPException`, `except` y Tareas en Background
/// warning | Advertencia
Probablemente no necesites estos detalles técnicos, puedes omitir esta sección y continuar abajo.
Estos detalles son útiles principalmente si estabas usando una versión de FastAPI anterior a 0.106.0 y usabas recursos de dependencias con `yield` en tareas en background.
///
### Dependencias con `yield` y `except`, Detalles Técnicos
Antes de FastAPI 0.110.0, si usabas una dependencia con `yield`, y luego capturabas una excepción con `except` en esa dependencia, y no volvías a lanzar la excepción, la excepción se lanzaría automáticamente/transmitiría a cualquier manejador de excepciones o al manejador de errores interno del servidor.
Esto se cambió en la versión 0.110.0 para corregir el consumo no gestionado de memoria de excepciones transmitidas sin un manejador (errores internos del servidor), y para que sea consistente con el comportamiento del código regular de Python.
### Tareas en Background y Dependencias con `yield`, Detalles Técnicos
Antes de FastAPI 0.106.0, lanzar excepciones después de `yield` no era posible, el código de salida en dependencias con `yield` se ejecutaba *después* de que el response se enviara, por lo que los [Manejadores de Excepciones](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} ya se habrían ejecutado.
Esto se diseñó de esta manera principalmente para permitir usar los mismos objetos "extraídos" por dependencias dentro de tareas en background, porque el código de salida se ejecutaría después de que las tareas en background terminaran.
Sin embargo, ya que esto significaría esperar a que el response viaje a través de la red mientras se retiene innecesariamente un recurso en una dependencia con yield (por ejemplo, una conexión a base de datos), esto se cambió en FastAPI 0.106.0.
/// tip | Consejo
Además, una tarea en background es normalmente un conjunto independiente de lógica que debería manejarse por separado, con sus propios recursos (por ejemplo, su propia conexión a base de datos).
De esta manera probablemente tendrás un código más limpio.
///
Si solías depender de este comportamiento, ahora deberías crear los recursos para tareas en background dentro de la propia tarea en background, y usar internamente solo datos que no dependan de los recursos de las dependencias con `yield`.
Por ejemplo, en lugar de usar la misma sesión de base de datos, crearías una nueva sesión de base de datos dentro de la tarea en background, y obtendrías los objetos de la base de datos usando esta nueva sesión. Y luego, en lugar de pasar el objeto de la base de datos como parámetro a la función de tarea en background, pasarías el ID de ese objeto y luego obtendrías el objeto nuevamente dentro de la función de tarea en background.
## Context Managers
### Qué son los "Context Managers"
Los "Context Managers" son aquellos objetos de Python que puedes usar en una declaración `with`.
Por ejemplo, <a href="https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files" class="external-link" target="_blank">puedes usar `with` para leer un archivo</a>:
```Python
with open("./somefile.txt") as f:
contents = f.read()
print(contents)
```
Internamente, `open("./somefile.txt")` crea un objeto llamado "Context Manager".
Cuando el bloque `with` termina, se asegura de cerrar el archivo, incluso si hubo excepciones.
Cuando creas una dependencia con `yield`, **FastAPI** creará internamente un context manager para ella y lo combinará con algunas otras herramientas relacionadas.
### Usando context managers en dependencias con `yield`
/// warning | Advertencia
Esto es, más o menos, una idea "avanzada".
Si apenas estás comenzando con **FastAPI**, podrías querer omitirlo por ahora.
///
En Python, puedes crear Context Managers <a href="https://docs.python.org/3/reference/datamodel.html#context-managers" class="external-link" target="_blank">creando una clase con dos métodos: `__enter__()` y `__exit__()`</a>.
También puedes usarlos dentro de las dependencias de **FastAPI** con `yield` usando
`with` o `async with` en la función de dependencia:
{* ../../docs_src/dependencies/tutorial010.py hl[1:9,13] *}
/// tip | Consejo
Otra manera de crear un context manager es con:
* <a href="https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager" class="external-link" target="_blank">`@contextlib.contextmanager`</a> o
* <a href="https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager" class="external-link" target="_blank">`@contextlib.asynccontextmanager`</a>
usándolos para decorar una función con un solo `yield`.
Eso es lo que **FastAPI** usa internamente para dependencias con `yield`.
Pero no tienes que usar los decoradores para las dependencias de FastAPI (y no deberías).
FastAPI lo hará por ti internamente.
///

15
docs/es/docs/tutorial/dependencies/global-dependencies.md Normal file
View File

@@ -0,0 +1,15 @@
# Dependencias Globales
Para algunos tipos de aplicaciones, podrías querer agregar dependencias a toda la aplicación.
Similar a como puedes [agregar `dependencies` a los *path operation decorators*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, puedes agregarlos a la aplicación de `FastAPI`.
En ese caso, se aplicarán a todas las *path operations* en la aplicación:
{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[16] *}
Y todas las ideas en la sección sobre [agregar `dependencies` a los *path operation decorators*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} siguen aplicándose, pero en este caso, a todas las *path operations* en la app.
## Dependencias para grupos de *path operations*
Más adelante, al leer sobre cómo estructurar aplicaciones más grandes ([Aplicaciones Más Grandes - Múltiples Archivos](../../tutorial/bigger-applications.md){.internal-link target=_blank}), posiblemente con múltiples archivos, aprenderás cómo declarar un solo parámetro de `dependencies` para un grupo de *path operations*.

250
docs/es/docs/tutorial/dependencies/index.md Normal file
View File

@@ -0,0 +1,250 @@
# Dependencias
**FastAPI** tiene un sistema de **<abbr title="también conocido como componentes, recursos, proveedores, servicios, inyectables">Inyección de Dependencias</abbr>** muy poderoso pero intuitivo.
Está diseñado para ser muy simple de usar, y para hacer que cualquier desarrollador integre otros componentes con **FastAPI** de forma muy sencilla.
## Qué es la "Inyección de Dependencias"
**"Inyección de Dependencias"** significa, en programación, que hay una manera para que tu código (en este caso, tus *path operation functions*) declare las cosas que necesita para funcionar y utilizar: "dependencias".
Y luego, ese sistema (en este caso **FastAPI**) se encargará de hacer lo que sea necesario para proporcionar a tu código esas dependencias necesarias ("inyectar" las dependencias).
Esto es muy útil cuando necesitas:
* Tener lógica compartida (la misma lógica de código una y otra vez).
* Compartir conexiones a bases de datos.
* Imponer seguridad, autenticación, requisitos de roles, etc.
* Y muchas otras cosas...
Todo esto, mientras minimizas la repetición de código.
## Primeros Pasos
Veamos un ejemplo muy simple. Será tan simple que no es muy útil, por ahora.
Pero de esta manera podemos enfocarnos en cómo funciona el sistema de **Inyección de Dependencias**.
### Crear una dependencia, o "dependable"
Primero enfoquémonos en la dependencia.
Es solo una función que puede tomar todos los mismos parámetros que una *path operation function* puede tomar:
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8:9] *}
Eso es todo.
**2 líneas**.
Y tiene la misma forma y estructura que todas tus *path operation functions*.
Puedes pensar en ella como una *path operation function* sin el "decorador" (sin el `@app.get("/some-path")`).
Y puede devolver lo que quieras.
En este caso, esta dependencia espera:
* Un parámetro de query opcional `q` que es un `str`.
* Un parámetro de query opcional `skip` que es un `int`, y por defecto es `0`.
* Un parámetro de query opcional `limit` que es un `int`, y por defecto es `100`.
Y luego solo devuelve un `dict` que contiene esos valores.
/// info | Información
FastAPI agregó soporte para `Annotated` (y comenzó a recomendarlo) en la versión 0.95.0.
Si tienes una versión anterior, obtendrás errores al intentar usar `Annotated`.
Asegúrate de [Actualizar la versión de FastAPI](../../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} al menos a la 0.95.1 antes de usar `Annotated`.
///
### Importar `Depends`
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *}
### Declarar la dependencia, en el "dependant"
De la misma forma en que usas `Body`, `Query`, etc. con los parámetros de tu *path operation function*, usa `Depends` con un nuevo parámetro:
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[13,18] *}
Aunque usas `Depends` en los parámetros de tu función de la misma manera que usas `Body`, `Query`, etc., `Depends` funciona un poco diferente.
Le das a `Depends` un solo parámetro.
Este parámetro debe ser algo como una función.
**No la llames** directamente (no agregues los paréntesis al final), solo pásala como un parámetro a `Depends()`.
Y esa función toma parámetros de la misma manera que las *path operation functions*.
/// tip | Consejo
Verás qué otras "cosas", además de funciones, pueden usarse como dependencias en el próximo capítulo.
///
Cada vez que llega un nuevo request, **FastAPI** se encargará de:
* Llamar a tu función de dependencia ("dependable") con los parámetros correctos.
* Obtener el resultado de tu función.
* Asignar ese resultado al parámetro en tu *path operation function*.
```mermaid
graph TB
common_parameters(["common_parameters"])
read_items["/items/"]
read_users["/users/"]
common_parameters --> read_items
common_parameters --> read_users
```
De esta manera escribes código compartido una vez y **FastAPI** se encarga de llamarlo para tus *path operations*.
/// check | Revisa
Nota que no tienes que crear una clase especial y pasarla en algún lugar a **FastAPI** para "registrarla" o algo similar.
Solo la pasas a `Depends` y **FastAPI** sabe cómo hacer el resto.
///
## Compartir dependencias `Annotated`
En los ejemplos anteriores, ves que hay un poquito de **duplicación de código**.
Cuando necesitas usar la dependencia `common_parameters()`, tienes que escribir todo el parámetro con la anotación de tipo y `Depends()`:
```Python
commons: Annotated[dict, Depends(common_parameters)]
```
Pero como estamos usando `Annotated`, podemos almacenar ese valor `Annotated` en una variable y usarlo en múltiples lugares:
{* ../../docs_src/dependencies/tutorial001_02_an_py310.py hl[12,16,21] *}
/// tip | Consejo
Esto es solo Python estándar, se llama un "alias de tipo", en realidad no es específico de **FastAPI**.
Pero porque **FastAPI** está basado en los estándares de Python, incluido `Annotated`, puedes usar este truco en tu código. 😎
///
Las dependencias seguirán funcionando como se esperaba, y la **mejor parte** es que la **información de tipo se preservará**, lo que significa que tu editor podrá seguir proporcionándote **autocompletado**, **errores en línea**, etc. Lo mismo para otras herramientas como `mypy`.
Esto será especialmente útil cuando lo uses en una **gran base de código** donde uses **las mismas dependencias** una y otra vez en **muchas *path operations***.
## Usar `async` o no usar `async`
Como las dependencias también serán llamadas por **FastAPI** (lo mismo que tus *path operation functions*), las mismas reglas aplican al definir tus funciones.
Puedes usar `async def` o `def` normal.
Y puedes declarar dependencias con `async def` dentro de *path operation functions* normales `def`, o dependencias `def` dentro de *path operation functions* `async def`, etc.
No importa. **FastAPI** sabrá qué hacer.
/// note | Nota
Si no lo sabes, revisa la sección [Async: *"¿Con prisa?"*](../../async.md#in-a-hurry){.internal-link target=_blank} sobre `async` y `await` en la documentación.
///
## Integración con OpenAPI
Todas las declaraciones de request, validaciones y requisitos de tus dependencias (y sub-dependencias) se integrarán en el mismo esquema de OpenAPI.
Así, la documentación interactiva tendrá toda la información de estas dependencias también:
<img src="/img/tutorial/dependencies/image01.png">
## Uso simple
Si lo ves, las *path operation functions* se declaran para ser usadas siempre que un *path* y una *operación* coincidan, y luego **FastAPI** se encarga de llamar la función con los parámetros correctos, extrayendo los datos del request.
En realidad, todos (o la mayoría) de los frameworks web funcionan de esta misma manera.
Nunca llamas directamente a esas funciones. Son llamadas por tu framework (en este caso, **FastAPI**).
Con el sistema de Inyección de Dependencias, también puedes decirle a **FastAPI** que tu *path operation function* también "depende" de algo más que debe ejecutarse antes que tu *path operation function*, y **FastAPI** se encargará de ejecutarlo e "inyectar" los resultados.
Otros términos comunes para esta misma idea de "inyección de dependencias" son:
* recursos
* proveedores
* servicios
* inyectables
* componentes
## Plug-ins de **FastAPI**
Las integraciones y "plug-ins" pueden construirse usando el sistema de **Inyección de Dependencias**. Pero, de hecho, en realidad **no hay necesidad de crear "plug-ins"**, ya que al usar dependencias es posible declarar una cantidad infinita de integraciones e interacciones que se vuelven disponibles para tus *path operation functions*.
Y las dependencias se pueden crear de una manera muy simple e intuitiva que te permite simplemente importar los paquetes de Python que necesitas, e integrarlos con tus funciones de API en un par de líneas de código, *literalmente*.
Verás ejemplos de esto en los próximos capítulos, sobre bases de datos relacionales y NoSQL, seguridad, etc.
## Compatibilidad de **FastAPI**
La simplicidad del sistema de inyección de dependencias hace que **FastAPI** sea compatible con:
* todas las bases de datos relacionales
* bases de datos NoSQL
* paquetes externos
* APIs externas
* sistemas de autenticación y autorización
* sistemas de monitoreo de uso de la API
* sistemas de inyección de datos de response
* etc.
## Simple y Poderoso
Aunque el sistema de inyección de dependencias jerárquico es muy simple de definir y usar, sigue siendo muy poderoso.
Puedes definir dependencias que a su vez pueden definir dependencias ellas mismas.
Al final, se construye un árbol jerárquico de dependencias, y el sistema de **Inyección de Dependencias** se encarga de resolver todas estas dependencias por ti (y sus sub-dependencias) y proporcionar (inyectar) los resultados en cada paso.
Por ejemplo, digamos que tienes 4 endpoints de API (*path operations*):
* `/items/public/`
* `/items/private/`
* `/users/{user_id}/activate`
* `/items/pro/`
entonces podrías agregar diferentes requisitos de permiso para cada uno de ellos solo con dependencias y sub-dependencias:
```mermaid
graph TB
current_user(["current_user"])
active_user(["active_user"])
admin_user(["admin_user"])
paying_user(["paying_user"])
public["/items/public/"]
private["/items/private/"]
activate_user["/users/{user_id}/activate"]
pro_items["/items/pro/"]
current_user --> active_user
active_user --> admin_user
active_user --> paying_user
current_user --> public
active_user --> private
admin_user --> activate_user
paying_user --> pro_items
```
## Integrado con **OpenAPI**
Todas estas dependencias, al declarar sus requisitos, también añaden parámetros, validaciones, etc. a tus *path operations*.
**FastAPI** se encargará de agregar todo al esquema de OpenAPI, para que se muestre en los sistemas de documentación interactiva.

105
docs/es/docs/tutorial/dependencies/sub-dependencies.md Normal file
View File

@@ -0,0 +1,105 @@
# Sub-dependencias
Puedes crear dependencias que tengan **sub-dependencias**.
Pueden ser tan **profundas** como necesites.
**FastAPI** se encargará de resolverlas.
## Primera dependencia "dependable"
Podrías crear una primera dependencia ("dependable") así:
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *}
Declara un parámetro de query opcional `q` como un `str`, y luego simplemente lo devuelve.
Esto es bastante simple (no muy útil), pero nos ayudará a centrarnos en cómo funcionan las sub-dependencias.
## Segunda dependencia, "dependable" y "dependant"
Luego puedes crear otra función de dependencia (un "dependable") que al mismo tiempo declare una dependencia propia (por lo que también es un "dependant"):
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *}
Centrémonos en los parámetros declarados:
* Aunque esta función es una dependencia ("dependable") en sí misma, también declara otra dependencia (depende de algo más).
* Depende del `query_extractor`, y asigna el valor que devuelve al parámetro `q`.
* También declara una `last_query` cookie opcional, como un `str`.
* Si el usuario no proporcionó ningún query `q`, usamos el último query utilizado, que guardamos previamente en una cookie.
## Usa la dependencia
Entonces podemos usar la dependencia con:
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
/// info | Información
Fíjate que solo estamos declarando una dependencia en la *path operation function*, `query_or_cookie_extractor`.
Pero **FastAPI** sabrá que tiene que resolver `query_extractor` primero, para pasar los resultados de eso a `query_or_cookie_extractor` al llamarlo.
///
```mermaid
graph TB
query_extractor(["query_extractor"])
query_or_cookie_extractor(["query_or_cookie_extractor"])
read_query["/items/"]
query_extractor --> query_or_cookie_extractor --> read_query
```
## Usando la misma dependencia múltiples veces
Si una de tus dependencias se declara varias veces para la misma *path operation*, por ejemplo, múltiples dependencias tienen una sub-dependencia común, **FastAPI** sabrá llamar a esa sub-dependencia solo una vez por request.
Y guardará el valor devuelto en un <abbr title="Una utilidad/sistema para almacenar valores calculados/generados, para reutilizarlos en lugar de calcularlos nuevamente.">"cache"</abbr> y lo pasará a todos los "dependants" que lo necesiten en ese request específico, en lugar de llamar a la dependencia varias veces para el mismo request.
En un escenario avanzado donde sabes que necesitas que la dependencia se llame en cada paso (posiblemente varias veces) en el mismo request en lugar de usar el valor "cache", puedes establecer el parámetro `use_cache=False` al usar `Depends`:
//// tab | Python 3.8+
```Python hl_lines="1"
async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_cache=False)]):
return {"fresh_value": fresh_value}
```
////
//// tab | Python 3.8+ sin Anotaciones
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python hl_lines="1"
async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):
return {"fresh_value": fresh_value}
```
////
## Resumen
Aparte de todas las palabras rimbombantes usadas aquí, el sistema de **Inyección de Dependencias** es bastante simple.
Solo son funciones que se ven igual que las *path operation functions*.
Pero aun así, es muy potente y te permite declarar "grafos" de dependencia anidados arbitrariamente profundos (árboles).
/// tip | Consejo
Todo esto podría no parecer tan útil con estos ejemplos simples.
Pero verás lo útil que es en los capítulos sobre **seguridad**.
Y también verás la cantidad de código que te ahorrará.
///

35
docs/es/docs/tutorial/encoder.md Normal file
View File

@@ -0,0 +1,35 @@
# JSON Compatible Encoder
Hay algunos casos en los que podrías necesitar convertir un tipo de dato (como un modelo de Pydantic) a algo compatible con JSON (como un `dict`, `list`, etc).
Por ejemplo, si necesitas almacenarlo en una base de datos.
Para eso, **FastAPI** proporciona una función `jsonable_encoder()`.
## Usando el `jsonable_encoder`
Imaginemos que tienes una base de datos `fake_db` que solo recibe datos compatibles con JSON.
Por ejemplo, no recibe objetos `datetime`, ya que no son compatibles con JSON.
Entonces, un objeto `datetime` tendría que ser convertido a un `str` que contenga los datos en formato <a href="https://en.wikipedia.org/wiki/ISO_8601" class="external-link" target="_blank">ISO</a>.
De la misma manera, esta base de datos no recibiría un modelo de Pydantic (un objeto con atributos), solo un `dict`.
Puedes usar `jsonable_encoder` para eso.
Recibe un objeto, como un modelo de Pydantic, y devuelve una versión compatible con JSON:
{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *}
En este ejemplo, convertiría el modelo de Pydantic a un `dict`, y el `datetime` a un `str`.
El resultado de llamarlo es algo que puede ser codificado con la función estándar de Python <a href="https://docs.python.org/3/library/json.html#json.dumps" class="external-link" target="_blank">`json.dumps()`</a>.
No devuelve un gran `str` que contenga los datos en formato JSON (como una cadena de texto). Devuelve una estructura de datos estándar de Python (por ejemplo, un `dict`) con valores y sub-valores que son todos compatibles con JSON.
/// note | Nota
`jsonable_encoder` es utilizado internamente por **FastAPI** para convertir datos. Pero es útil en muchos otros escenarios.
///

62
docs/es/docs/tutorial/extra-data-types.md Normal file
View File

@@ -0,0 +1,62 @@
# Tipos de Datos Extra
Hasta ahora, has estado usando tipos de datos comunes, como:
* `int`
* `float`
* `str`
* `bool`
Pero también puedes usar tipos de datos más complejos.
Y seguirás teniendo las mismas funcionalidades como hasta ahora:
* Gran soporte de editor.
* Conversión de datos de requests entrantes.
* Conversión de datos para datos de response.
* Validación de datos.
* Anotación y documentación automática.
## Otros tipos de datos
Aquí hay algunos de los tipos de datos adicionales que puedes usar:
* `UUID`:
* Un "Identificador Universalmente Único" estándar, común como un ID en muchas bases de datos y sistemas.
* En requests y responses se representará como un `str`.
* `datetime.datetime`:
* Un `datetime.datetime` de Python.
* En requests y responses se representará como un `str` en formato ISO 8601, como: `2008-09-15T15:53:00+05:00`.
* `datetime.date`:
* `datetime.date` de Python.
* En requests y responses se representará como un `str` en formato ISO 8601, como: `2008-09-15`.
* `datetime.time`:
* Un `datetime.time` de Python.
* En requests y responses se representará como un `str` en formato ISO 8601, como: `14:23:55.003`.
* `datetime.timedelta`:
* Un `datetime.timedelta` de Python.
* En requests y responses se representará como un `float` de segundos totales.
* Pydantic también permite representarlo como una "codificación de diferencia horaria ISO 8601", <a href="https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers" class="external-link" target="_blank">consulta la documentación para más información</a>.
* `frozenset`:
* En requests y responses, tratado igual que un `set`:
* En requests, se leerá una list, eliminando duplicados y convirtiéndola en un `set`.
* En responses, el `set` se convertirá en una `list`.
* El esquema generado especificará que los valores del `set` son únicos (usando `uniqueItems` de JSON Schema).
* `bytes`:
* `bytes` estándar de Python.
* En requests y responses se tratará como `str`.
* El esquema generado especificará que es un `str` con "binary" como "format".
* `Decimal`:
* `Decimal` estándar de Python.
* En requests y responses, manejado igual que un `float`.
* Puedes revisar todos los tipos de datos válidos de Pydantic aquí: <a href="https://docs.pydantic.dev/latest/usage/types/types/" class="external-link" target="_blank">Tipos de datos de Pydantic</a>.
## Ejemplo
Aquí tienes un ejemplo de una *path operation* con parámetros usando algunos de los tipos anteriores.
{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}
Nota que los parámetros dentro de la función tienen su tipo de dato natural, y puedes, por ejemplo, realizar manipulaciones de fechas normales, como:
{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *}

222
docs/es/docs/tutorial/extra-models.md Normal file
View File

@@ -0,0 +1,222 @@
# Modelos Extra
Continuando con el ejemplo anterior, será común tener más de un modelo relacionado.
Esto es especialmente el caso para los modelos de usuario, porque:
* El **modelo de entrada** necesita poder tener una contraseña.
* El **modelo de salida** no debería tener una contraseña.
* El **modelo de base de datos** probablemente necesitaría tener una contraseña hasheada.
/// danger | Peligro
Nunca almacenes contraseñas de usuarios en texto plano. Siempre almacena un "hash seguro" que puedas verificar luego.
Si no lo sabes, aprenderás qué es un "hash de contraseña" en los [capítulos de seguridad](security/simple-oauth2.md#password-hashing){.internal-link target=_blank}.
///
## Múltiples modelos
Aquí tienes una idea general de cómo podrían ser los modelos con sus campos de contraseña y los lugares donde se utilizan:
{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *}
/// info | Información
En Pydantic v1 el método se llamaba `.dict()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_dump()`.
Los ejemplos aquí usan `.dict()` para compatibilidad con Pydantic v1, pero deberías usar `.model_dump()` en su lugar si puedes usar Pydantic v2.
///
### Acerca de `**user_in.dict()`
#### `.dict()` de Pydantic
`user_in` es un modelo Pydantic de la clase `UserIn`.
Los modelos Pydantic tienen un método `.dict()` que devuelve un `dict` con los datos del modelo.
Así que, si creamos un objeto Pydantic `user_in` como:
```Python
user_in = UserIn(username="john", password="secret", email="john.doe@example.com")
```
y luego llamamos a:
```Python
user_dict = user_in.dict()
```
ahora tenemos un `dict` con los datos en la variable `user_dict` (es un `dict` en lugar de un objeto modelo Pydantic).
Y si llamamos a:
```Python
print(user_dict)
```
obtendremos un `dict` de Python con:
```Python
{
'username': 'john',
'password': 'secret',
'email': 'john.doe@example.com',
'full_name': None,
}
```
#### Desempaquetando un `dict`
Si tomamos un `dict` como `user_dict` y lo pasamos a una función (o clase) con `**user_dict`, Python lo "desempaquetará". Pasará las claves y valores del `user_dict` directamente como argumentos clave-valor.
Así que, continuando con el `user_dict` anterior, escribir:
```Python
UserInDB(**user_dict)
```
sería equivalente a algo como:
```Python
UserInDB(
username="john",
password="secret",
email="john.doe@example.com",
full_name=None,
)
```
O más exactamente, usando `user_dict` directamente, con cualquier contenido que pueda tener en el futuro:
```Python
UserInDB(
username = user_dict["username"],
password = user_dict["password"],
email = user_dict["email"],
full_name = user_dict["full_name"],
)
```
#### Un modelo Pydantic a partir del contenido de otro
Como en el ejemplo anterior obtuvimos `user_dict` de `user_in.dict()`, este código:
```Python
user_dict = user_in.dict()
UserInDB(**user_dict)
```
sería equivalente a:
```Python
UserInDB(**user_in.dict())
```
...porque `user_in.dict()` es un `dict`, y luego hacemos que Python lo "desempaquete" al pasarlo a `UserInDB` con el prefijo `**`.
Así, obtenemos un modelo Pydantic a partir de los datos en otro modelo Pydantic.
#### Desempaquetando un `dict` y palabras clave adicionales
Y luego agregando el argumento de palabra clave adicional `hashed_password=hashed_password`, como en:
```Python
UserInDB(**user_in.dict(), hashed_password=hashed_password)
```
...termina siendo como:
```Python
UserInDB(
username = user_dict["username"],
password = user_dict["password"],
email = user_dict["email"],
full_name = user_dict["full_name"],
hashed_password = hashed_password,
)
```
/// warning | Advertencia
Las funciones adicionales de soporte `fake_password_hasher` y `fake_save_user` son solo para demostrar un posible flujo de datos, pero por supuesto no proporcionan ninguna seguridad real.
///
## Reducir duplicación
Reducir la duplicación de código es una de las ideas centrales en **FastAPI**.
Ya que la duplicación de código incrementa las posibilidades de bugs, problemas de seguridad, problemas de desincronización de código (cuando actualizas en un lugar pero no en los otros), etc.
Y estos modelos están compartiendo muchos de los datos y duplicando nombres y tipos de atributos.
Podríamos hacerlo mejor.
Podemos declarar un modelo `UserBase` que sirva como base para nuestros otros modelos. Y luego podemos hacer subclases de ese modelo que heredan sus atributos (declaraciones de tipo, validación, etc).
Toda la conversión de datos, validación, documentación, etc. seguirá funcionando normalmente.
De esa manera, podemos declarar solo las diferencias entre los modelos (con `password` en texto plano, con `hashed_password` y sin contraseña):
{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *}
## `Union` o `anyOf`
Puedes declarar un response que sea la `Union` de dos o más tipos, eso significa que el response sería cualquiera de ellos.
Se definirá en OpenAPI con `anyOf`.
Para hacerlo, usa el type hint estándar de Python <a href="https://docs.python.org/3/library/typing.html#typing.Union" class="external-link" target="_blank">`typing.Union`</a>:
/// note | Nota
Al definir una <a href="https://docs.pydantic.dev/latest/concepts/types/#unions" class="external-link" target="_blank">`Union`</a>, incluye el tipo más específico primero, seguido por el tipo menos específico. En el ejemplo a continuación, el más específico `PlaneItem` viene antes de `CarItem` en `Union[PlaneItem, CarItem]`.
///
{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *}
### `Union` en Python 3.10
En este ejemplo pasamos `Union[PlaneItem, CarItem]` como el valor del argumento `response_model`.
Porque lo estamos pasando como un **valor a un argumento** en lugar de ponerlo en una **anotación de tipo**, tenemos que usar `Union` incluso en Python 3.10.
Si estuviera en una anotación de tipo podríamos haber usado la barra vertical, como:
```Python
some_variable: PlaneItem | CarItem
```
Pero si ponemos eso en la asignación `response_model=PlaneItem | CarItem` obtendríamos un error, porque Python intentaría realizar una **operación inválida** entre `PlaneItem` y `CarItem` en lugar de interpretar eso como una anotación de tipo.
## Lista de modelos
De la misma manera, puedes declarar responses de listas de objetos.
Para eso, usa el `typing.List` estándar de Python (o simplemente `list` en Python 3.9 y posteriores):
{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *}
## Response con `dict` arbitrario
También puedes declarar un response usando un `dict` arbitrario plano, declarando solo el tipo de las claves y valores, sin usar un modelo Pydantic.
Esto es útil si no conoces los nombres de los campos/atributos válidos (que serían necesarios para un modelo Pydantic) de antemano.
En este caso, puedes usar `typing.Dict` (o solo `dict` en Python 3.9 y posteriores):
{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *}
## Recapitulación
Usa múltiples modelos Pydantic y hereda libremente para cada caso.
No necesitas tener un solo modelo de datos por entidad si esa entidad debe poder tener diferentes "estados". Como el caso con la "entidad" usuario con un estado que incluye `password`, `password_hash` y sin contraseña.

255
docs/es/docs/tutorial/handling-errors.md Normal file
View File

@@ -0,0 +1,255 @@
# Manejo de Errores
Existen muchas situaciones en las que necesitas notificar un error a un cliente que está usando tu API.
Este cliente podría ser un navegador con un frontend, un código de otra persona, un dispositivo IoT, etc.
Podrías necesitar decirle al cliente que:
* El cliente no tiene suficientes privilegios para esa operación.
* El cliente no tiene acceso a ese recurso.
* El ítem al que el cliente intentaba acceder no existe.
* etc.
En estos casos, normalmente devolverías un **código de estado HTTP** en el rango de **400** (de 400 a 499).
Esto es similar a los códigos de estado HTTP 200 (de 200 a 299). Esos códigos de estado "200" significan que de alguna manera hubo un "éxito" en el request.
Los códigos de estado en el rango de 400 significan que hubo un error por parte del cliente.
¿Recuerdas todos esos errores de **"404 Not Found"** (y chistes)?
## Usa `HTTPException`
Para devolver responses HTTP con errores al cliente, usa `HTTPException`.
### Importa `HTTPException`
{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
### Lanza un `HTTPException` en tu código
`HTTPException` es una excepción de Python normal con datos adicionales relevantes para APIs.
Debido a que es una excepción de Python, no la `return`, sino que la `raise`.
Esto también significa que si estás dentro de una función de utilidad que estás llamando dentro de tu *path operation function*, y lanzas el `HTTPException` desde dentro de esa función de utilidad, no se ejecutará el resto del código en la *path operation function*, terminará ese request de inmediato y enviará el error HTTP del `HTTPException` al cliente.
El beneficio de lanzar una excepción en lugar de `return`ar un valor será más evidente en la sección sobre Dependencias y Seguridad.
En este ejemplo, cuando el cliente solicita un ítem por un ID que no existe, lanza una excepción con un código de estado de `404`:
{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
### El response resultante
Si el cliente solicita `http://example.com/items/foo` (un `item_id` `"foo"`), ese cliente recibirá un código de estado HTTP de 200, y un response JSON de:
```JSON
{
"item": "The Foo Wrestlers"
}
```
Pero si el cliente solicita `http://example.com/items/bar` (un `item_id` inexistente `"bar"`), ese cliente recibirá un código de estado HTTP de 404 (el error "no encontrado"), y un response JSON de:
```JSON
{
"detail": "Item not found"
}
```
/// tip | Consejo
Cuando lanzas un `HTTPException`, puedes pasar cualquier valor que pueda convertirse a JSON como el parámetro `detail`, no solo `str`.
Podrías pasar un `dict`, un `list`, etc.
Son manejados automáticamente por **FastAPI** y convertidos a JSON.
///
## Agrega headers personalizados
Existen algunas situaciones en las que es útil poder agregar headers personalizados al error HTTP. Por ejemplo, para algunos tipos de seguridad.
Probablemente no necesitarás usarlos directamente en tu código.
Pero en caso de que los necesites para un escenario avanzado, puedes agregar headers personalizados:
{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
## Instalar manejadores de excepciones personalizados
Puedes agregar manejadores de excepciones personalizados con <a href="https://www.starlette.io/exceptions/" class="external-link" target="_blank">las mismas utilidades de excepciones de Starlette</a>.
Supongamos que tienes una excepción personalizada `UnicornException` que tú (o un paquete que usas) podría lanzar.
Y quieres manejar esta excepción globalmente con FastAPI.
Podrías agregar un manejador de excepciones personalizado con `@app.exception_handler()`:
{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
Aquí, si solicitas `/unicorns/yolo`, la *path operation* lanzará un `UnicornException`.
Pero será manejado por el `unicorn_exception_handler`.
Así que recibirás un error limpio, con un código de estado HTTP de `418` y un contenido JSON de:
```JSON
{"message": "Oops! yolo did something. There goes a rainbow..."}
```
/// note | Nota Técnica
También podrías usar `from starlette.requests import Request` y `from starlette.responses import JSONResponse`.
**FastAPI** ofrece las mismas `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette. Lo mismo con `Request`.
///
## Sobrescribir los manejadores de excepciones predeterminados
**FastAPI** tiene algunos manejadores de excepciones predeterminados.
Estos manejadores se encargan de devolver los responses JSON predeterminadas cuando lanzas un `HTTPException` y cuando el request tiene datos inválidos.
Puedes sobrescribir estos manejadores de excepciones con los tuyos propios.
### Sobrescribir excepciones de validación de request
Cuando un request contiene datos inválidos, **FastAPI** lanza internamente un `RequestValidationError`.
Y también incluye un manejador de excepciones predeterminado para ello.
Para sobrescribirlo, importa el `RequestValidationError` y úsalo con `@app.exception_handler(RequestValidationError)` para decorar el manejador de excepciones.
El manejador de excepciones recibirá un `Request` y la excepción.
{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
Ahora, si vas a `/items/foo`, en lugar de obtener el error JSON por defecto con:
```JSON
{
"detail": [
{
"loc": [
"path",
"item_id"
],
"msg": "value is not a valid integer",
"type": "type_error.integer"
}
]
}
```
obtendrás una versión en texto, con:
```
1 validation error
path -> item_id
value is not a valid integer (type=type_error.integer)
```
#### `RequestValidationError` vs `ValidationError`
/// warning | Advertencia
Estos son detalles técnicos que podrías omitir si no es importante para ti en este momento.
///
`RequestValidationError` es una subclase de <a href="https://docs.pydantic.dev/latest/concepts/models/#error-handling" class="external-link" target="_blank">`ValidationError`</a> de Pydantic.
**FastAPI** la usa para que, si usas un modelo Pydantic en `response_model`, y tus datos tienen un error, lo verás en tu log.
Pero el cliente/usuario no lo verá. En su lugar, el cliente recibirá un "Error Interno del Servidor" con un código de estado HTTP `500`.
Debería ser así porque si tienes un `ValidationError` de Pydantic en tu *response* o en cualquier lugar de tu código (no en el *request* del cliente), en realidad es un bug en tu código.
Y mientras lo arreglas, tus clientes/usuarios no deberían tener acceso a información interna sobre el error, ya que eso podría exponer una vulnerabilidad de seguridad.
### Sobrescribir el manejador de errores de `HTTPException`
De la misma manera, puedes sobrescribir el manejador de `HTTPException`.
Por ejemplo, podrías querer devolver un response de texto plano en lugar de JSON para estos errores:
{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
/// note | Nota Técnica
También podrías usar `from starlette.responses import PlainTextResponse`.
**FastAPI** ofrece las mismas `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
///
### Usar el body de `RequestValidationError`
El `RequestValidationError` contiene el `body` que recibió con datos inválidos.
Podrías usarlo mientras desarrollas tu aplicación para registrar el body y depurarlo, devolverlo al usuario, etc.
{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
Ahora intenta enviar un ítem inválido como:
```JSON
{
"title": "towel",
"size": "XL"
}
```
Recibirás un response que te dirá que los datos son inválidos conteniendo el body recibido:
```JSON hl_lines="12-15"
{
"detail": [
{
"loc": [
"body",
"size"
],
"msg": "value is not a valid integer",
"type": "type_error.integer"
}
],
"body": {
"title": "towel",
"size": "XL"
}
}
```
#### `HTTPException` de FastAPI vs `HTTPException` de Starlette
**FastAPI** tiene su propio `HTTPException`.
Y la clase de error `HTTPException` de **FastAPI** hereda de la clase de error `HTTPException` de Starlette.
La única diferencia es que el `HTTPException` de **FastAPI** acepta cualquier dato JSON-able para el campo `detail`, mientras que el `HTTPException` de Starlette solo acepta strings para ello.
Así que puedes seguir lanzando un `HTTPException` de **FastAPI** como de costumbre en tu código.
Pero cuando registras un manejador de excepciones, deberías registrarlo para el `HTTPException` de Starlette.
De esta manera, si alguna parte del código interno de Starlette, o una extensión o complemento de Starlette, lanza un `HTTPException` de Starlette, tu manejador podrá capturarlo y manejarlo.
En este ejemplo, para poder tener ambos `HTTPException` en el mismo código, las excepciones de Starlette son renombradas a `StarletteHTTPException`:
```Python
from starlette.exceptions import HTTPException as StarletteHTTPException
```
### Reutilizar los manejadores de excepciones de **FastAPI**
Si quieres usar la excepción junto con los mismos manejadores de excepciones predeterminados de **FastAPI**, puedes importar y reutilizar los manejadores de excepciones predeterminados de `fastapi.exception_handlers`:
{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
En este ejemplo solo estás `print`eando el error con un mensaje muy expresivo, pero te haces una idea. Puedes usar la excepción y luego simplemente reutilizar los manejadores de excepciones predeterminados.

56
docs/es/docs/tutorial/header-param-models.md Normal file
View File

@@ -0,0 +1,56 @@
# Modelos de Parámetros de Header
Si tienes un grupo de **parámetros de header** relacionados, puedes crear un **modelo Pydantic** para declararlos.
Esto te permitirá **reutilizar el modelo** en **múltiples lugares** y también declarar validaciones y metadatos para todos los parámetros al mismo tiempo. 😎
/// note | Nota
Esto es compatible desde la versión `0.115.0` de FastAPI. 🤓
///
## Parámetros de Header con un Modelo Pydantic
Declara los **parámetros de header** que necesitas en un **modelo Pydantic**, y luego declara el parámetro como `Header`:
{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
**FastAPI** **extraerá** los datos para **cada campo** de los **headers** en el request y te dará el modelo Pydantic que definiste.
## Revisa la Documentación
Puedes ver los headers requeridos en la interfaz de documentación en `/docs`:
<div class="screenshot">
<img src="/img/tutorial/header-param-models/image01.png">
</div>
## Prohibir Headers Extra
En algunos casos de uso especiales (probablemente no muy comunes), podrías querer **restringir** los headers que deseas recibir.
Puedes usar la configuración del modelo de Pydantic para `prohibir` cualquier campo `extra`:
{* ../../docs_src/header_param_models/tutorial002_an_py310.py hl[10] *}
Si un cliente intenta enviar algunos **headers extra**, recibirán un response de **error**.
Por ejemplo, si el cliente intenta enviar un header `tool` con un valor de `plumbus`, recibirán un response de **error** indicando que el parámetro de header `tool` no está permitido:
```json
{
"detail": [
{
"type": "extra_forbidden",
"loc": ["header", "tool"],
"msg": "Extra inputs are not permitted",
"input": "plumbus",
}
]
}
```
## Resumen
Puedes usar **modelos Pydantic** para declarar **headers** en **FastAPI**. 😎

91
docs/es/docs/tutorial/header-params.md Normal file
View File

@@ -0,0 +1,91 @@
# Parámetros de Header
Puedes definir los parámetros de Header de la misma manera que defines los parámetros de `Query`, `Path` y `Cookie`.
## Importar `Header`
Primero importa `Header`:
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *}
## Declarar parámetros de `Header`
Luego declara los parámetros de header usando la misma estructura que con `Path`, `Query` y `Cookie`.
Puedes definir el valor por defecto así como toda la validación extra o los parámetros de anotaciones:
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[9] *}
/// note | Detalles Técnicos
`Header` es una clase "hermana" de `Path`, `Query` y `Cookie`. También hereda de la misma clase común `Param`.
Pero recuerda que cuando importas `Query`, `Path`, `Header`, y otros de `fastapi`, en realidad son funciones que retornan clases especiales.
///
/// info | Información
Para declarar headers, necesitas usar `Header`, porque de otra forma los parámetros serían interpretados como parámetros de query.
///
## Conversión automática
`Header` tiene un poquito de funcionalidad extra además de lo que proporcionan `Path`, `Query` y `Cookie`.
La mayoría de los headers estándar están separados por un carácter "guion", también conocido como el "símbolo menos" (`-`).
Pero una variable como `user-agent` es inválida en Python.
Así que, por defecto, `Header` convertirá los caracteres de los nombres de los parámetros de guion bajo (`_`) a guion (`-`) para extraer y documentar los headers.
Además, los headers HTTP no diferencian entre mayúsculas y minúsculas, por lo que los puedes declarar con el estilo estándar de Python (también conocido como "snake_case").
Así que, puedes usar `user_agent` como normalmente lo harías en código Python, en lugar de necesitar capitalizar las primeras letras como `User_Agent` o algo similar.
Si por alguna razón necesitas desactivar la conversión automática de guiones bajos a guiones, establece el parámetro `convert_underscores` de `Header` a `False`:
{* ../../docs_src/header_params/tutorial002_an_py310.py hl[10] *}
/// warning | Advertencia
Antes de establecer `convert_underscores` a `False`, ten en cuenta que algunos proxies y servidores HTTP no permiten el uso de headers con guiones bajos.
///
## Headers duplicados
Es posible recibir headers duplicados. Eso significa, el mismo header con múltiples valores.
Puedes definir esos casos usando una lista en la declaración del tipo.
Recibirás todos los valores del header duplicado como una `list` de Python.
Por ejemplo, para declarar un header de `X-Token` que puede aparecer más de una vez, puedes escribir:
{* ../../docs_src/header_params/tutorial003_an_py310.py hl[9] *}
Si te comunicas con esa *path operation* enviando dos headers HTTP como:
```
X-Token: foo
X-Token: bar
```
El response sería como:
```JSON
{
"X-Token values": [
"bar",
"foo"
]
}
```
## Recapitulación
Declara headers con `Header`, usando el mismo patrón común que `Query`, `Path` y `Cookie`.
Y no te preocupes por los guiones bajos en tus variables, **FastAPI** se encargará de convertirlos.

120
docs/es/docs/tutorial/metadata.md Normal file
View File

@@ -0,0 +1,120 @@
# Metadata y URLs de Docs
Puedes personalizar varias configuraciones de metadata en tu aplicación **FastAPI**.
## Metadata para la API
Puedes establecer los siguientes campos que se usan en la especificación OpenAPI y en las interfaces automáticas de documentación de la API:
| Parámetro | Tipo | Descripción |
|------------|------|-------------|
| `title` | `str` | El título de la API. |
| `summary` | `str` | Un resumen corto de la API. <small>Disponible desde OpenAPI 3.1.0, FastAPI 0.99.0.</small> |
| `description` | `str` | Una breve descripción de la API. Puede usar Markdown. |
| `version` | `string` | La versión de la API. Esta es la versión de tu propia aplicación, no de OpenAPI. Por ejemplo, `2.5.0`. |
| `terms_of_service` | `str` | Una URL a los Términos de Servicio para la API. Si se proporciona, debe ser una URL. |
| `contact` | `dict` | La información de contacto para la API expuesta. Puede contener varios campos. <details><summary><code>contact</code> fields</summary><table><thead><tr><th>Parámetro</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td>El nombre identificativo de la persona/organización de contacto.</td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>La URL que apunta a la información de contacto. DEBE tener el formato de una URL.</td></tr><tr><td><code>email</code></td><td><code>str</code></td><td>La dirección de correo electrónico de la persona/organización de contacto. DEBE tener el formato de una dirección de correo.</td></tr></tbody></table></details> |
| `license_info` | `dict` | La información de la licencia para la API expuesta. Puede contener varios campos. <details><summary><code>license_info</code> fields</summary><table><thead><tr><th>Parámetro</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td><code>name</code></td><td><code>str</code></td><td><strong>REQUERIDO</strong> (si se establece un <code>license_info</code>). El nombre de la licencia utilizada para la API.</td></tr><tr><td><code>identifier</code></td><td><code>str</code></td><td>Una expresión de licencia <a href="https://spdx.org/licenses/" class="external-link" target="_blank">SPDX</a> para la API. El campo <code>identifier</code> es mutuamente excluyente del campo <code>url</code>. <small>Disponible desde OpenAPI 3.1.0, FastAPI 0.99.0.</small></td></tr><tr><td><code>url</code></td><td><code>str</code></td><td>Una URL a la licencia utilizada para la API. DEBE tener el formato de una URL.</td></tr></tbody></table></details> |
Puedes configurarlos de la siguiente manera:
{* ../../docs_src/metadata/tutorial001.py hl[3:16, 19:32] *}
/// tip | Consejo
Puedes escribir Markdown en el campo `description` y se mostrará en el resultado.
///
Con esta configuración, la documentación automática de la API se vería así:
<img src="/img/tutorial/metadata/image01.png">
## Identificador de licencia
Desde OpenAPI 3.1.0 y FastAPI 0.99.0, también puedes establecer la `license_info` con un `identifier` en lugar de una `url`.
Por ejemplo:
{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}
## Metadata para etiquetas
También puedes agregar metadata adicional para las diferentes etiquetas usadas para agrupar tus path operations con el parámetro `openapi_tags`.
Este toma una list que contiene un diccionario para cada etiqueta.
Cada diccionario puede contener:
* `name` (**requerido**): un `str` con el mismo nombre de etiqueta que usas en el parámetro `tags` en tus *path operations* y `APIRouter`s.
* `description`: un `str` con una breve descripción de la etiqueta. Puede tener Markdown y se mostrará en la interfaz de documentación.
* `externalDocs`: un `dict` que describe documentación externa con:
* `description`: un `str` con una breve descripción para la documentación externa.
* `url` (**requerido**): un `str` con la URL para la documentación externa.
### Crear metadata para etiquetas
Probemos eso en un ejemplo con etiquetas para `users` y `items`.
Crea metadata para tus etiquetas y pásala al parámetro `openapi_tags`:
{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
Nota que puedes utilizar Markdown dentro de las descripciones, por ejemplo "login" se mostrará en negrita (**login**) y "fancy" se mostrará en cursiva (_fancy_).
/// tip | Consejo
No tienes que agregar metadata para todas las etiquetas que uses.
///
### Usar tus etiquetas
Usa el parámetro `tags` con tus *path operations* (y `APIRouter`s) para asignarlas a diferentes etiquetas:
{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
/// info | Información
Lee más sobre etiquetas en [Configuración de Path Operation](path-operation-configuration.md#tags){.internal-link target=_blank}.
///
### Revisa la documentación
Ahora, si revisas la documentación, mostrará toda la metadata adicional:
<img src="/img/tutorial/metadata/image02.png">
### Orden de las etiquetas
El orden de cada diccionario de metadata de etiqueta también define el orden mostrado en la interfaz de documentación.
Por ejemplo, aunque `users` iría después de `items` en orden alfabético, se muestra antes porque agregamos su metadata como el primer diccionario en la list.
## URL de OpenAPI
Por defecto, el esquema OpenAPI se sirve en `/openapi.json`.
Pero puedes configurarlo con el parámetro `openapi_url`.
Por ejemplo, para configurarlo para que se sirva en `/api/v1/openapi.json`:
{* ../../docs_src/metadata/tutorial002.py hl[3] *}
Si quieres deshabilitar el esquema OpenAPI completamente, puedes establecer `openapi_url=None`, eso también deshabilitará las interfaces de usuario de documentación que lo usan.
## URLs de Docs
Puedes configurar las dos interfaces de usuario de documentación incluidas:
* **Swagger UI**: servida en `/docs`.
* Puedes establecer su URL con el parámetro `docs_url`.
* Puedes deshabilitarla estableciendo `docs_url=None`.
* **ReDoc**: servida en `/redoc`.
* Puedes establecer su URL con el parámetro `redoc_url`.
* Puedes deshabilitarla estableciendo `redoc_url=None`.
Por ejemplo, para configurar Swagger UI para que se sirva en `/documentation` y deshabilitar ReDoc:
{* ../../docs_src/metadata/tutorial003.py hl[3] *}

72
docs/es/docs/tutorial/middleware.md Normal file
View File

@@ -0,0 +1,72 @@
# Middleware
Puedes añadir middleware a las aplicaciones de **FastAPI**.
Un "middleware" es una función que trabaja con cada **request** antes de que sea procesada por cualquier *path operation* específica. Y también con cada **response** antes de devolverla.
* Toma cada **request** que llega a tu aplicación.
* Puede entonces hacer algo a esa **request** o ejecutar cualquier código necesario.
* Luego pasa la **request** para que sea procesada por el resto de la aplicación (por alguna *path operation*).
* Después toma la **response** generada por la aplicación (por alguna *path operation*).
* Puede hacer algo a esa **response** o ejecutar cualquier código necesario.
* Luego devuelve la **response**.
/// note | Detalles Técnicos
Si tienes dependencias con `yield`, el código de salida se ejecutará *después* del middleware.
Si hubiera alguna tarea en segundo plano (documentada más adelante), se ejecutará *después* de todo el middleware.
///
## Crear un middleware
Para crear un middleware usas el decorador `@app.middleware("http")` encima de una función.
La función middleware recibe:
* La `request`.
* Una función `call_next` que recibirá la `request` como parámetro.
* Esta función pasará la `request` a la correspondiente *path operation*.
* Luego devuelve la `response` generada por la correspondiente *path operation*.
* Puedes entonces modificar aún más la `response` antes de devolverla.
{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
/// tip | Consejo
Ten en cuenta que los custom proprietary headers se pueden añadir <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">usando el prefijo 'X-'</a>.
Pero si tienes custom headers que deseas que un cliente en un navegador pueda ver, necesitas añadirlos a tus configuraciones de CORS ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) usando el parámetro `expose_headers` documentado en <a href="https://www.starlette.io/middleware/#corsmiddleware" class="external-link" target="_blank">la documentación de CORS de Starlette</a>.
///
/// note | Detalles Técnicos
También podrías usar `from starlette.requests import Request`.
**FastAPI** lo proporciona como una conveniencia para ti, el desarrollador. Pero viene directamente de Starlette.
///
### Antes y después de la `response`
Puedes añadir código que se ejecute con la `request`, antes de que cualquier *path operation* la reciba.
Y también después de que se genere la `response`, antes de devolverla.
Por ejemplo, podrías añadir un custom header `X-Process-Time` que contenga el tiempo en segundos que tomó procesar la request y generar una response:
{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
/// tip | Consejo
Aquí usamos <a href="https://docs.python.org/3/library/time.html#time.perf_counter" class="external-link" target="_blank">`time.perf_counter()`</a> en lugar de `time.time()` porque puede ser más preciso para estos casos de uso. 🤓
///
## Otros middlewares
Más adelante puedes leer sobre otros middlewares en la [Guía del Usuario Avanzado: Middleware Avanzado](../advanced/middleware.md){.internal-link target=_blank}.
Leerás sobre cómo manejar <abbr title="Cross-Origin Resource Sharing">CORS</abbr> con un middleware en la siguiente sección.

107
docs/es/docs/tutorial/path-operation-configuration.md Normal file
View File

@@ -0,0 +1,107 @@
# Configuración de Path Operation
Hay varios parámetros que puedes pasar a tu *path operation decorator* para configurarlo.
/// warning | Advertencia
Ten en cuenta que estos parámetros se pasan directamente al *path operation decorator*, no a tu *path operation function*.
///
## Código de Estado del Response
Puedes definir el `status_code` (HTTP) que se utilizará en el response de tu *path operation*.
Puedes pasar directamente el código `int`, como `404`.
Pero si no recuerdas para qué es cada código numérico, puedes usar las constantes atajo en `status`:
{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}
Ese código de estado se usará en el response y se añadirá al esquema de OpenAPI.
/// note | Detalles Técnicos
También podrías usar `from starlette import status`.
**FastAPI** ofrece el mismo `starlette.status` como `fastapi.status` solo por conveniencia para ti, el desarrollador. Pero viene directamente de Starlette.
///
## Tags
Puedes añadir tags a tu *path operation*, pasando el parámetro `tags` con un `list` de `str` (comúnmente solo una `str`):
{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *}
Serán añadidas al esquema de OpenAPI y usadas por las interfaces de documentación automática:
<img src="/img/tutorial/path-operation-configuration/image01.png">
### Tags con Enums
Si tienes una gran aplicación, podrías terminar acumulando **varias tags**, y querrías asegurarte de que siempre uses la **misma tag** para *path operations* relacionadas.
En estos casos, podría tener sentido almacenar las tags en un `Enum`.
**FastAPI** soporta eso de la misma manera que con strings normales:
{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
## Resumen y Descripción
Puedes añadir un `summary` y `description`:
{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *}
## Descripción desde docstring
Como las descripciones tienden a ser largas y cubrir múltiples líneas, puedes declarar la descripción de la *path operation* en la <abbr title="un string de múltiples líneas como la primera expresión dentro de una función (no asignada a ninguna variable) usada para documentación">docstring</abbr> de la función y **FastAPI** la leerá desde allí.
Puedes escribir <a href="https://en.wikipedia.org/wiki/Markdown" class="external-link" target="_blank">Markdown</a> en el docstring, se interpretará y mostrará correctamente (teniendo en cuenta la indentación del docstring).
{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *}
Será usado en la documentación interactiva:
<img src="/img/tutorial/path-operation-configuration/image02.png">
## Descripción del Response
Puedes especificar la descripción del response con el parámetro `response_description`:
{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[19] *}
/// info | Información
Ten en cuenta que `response_description` se refiere específicamente al response, mientras que `description` se refiere a la *path operation* en general.
///
/// check | Revisa
OpenAPI especifica que cada *path operation* requiere una descripción de response.
Entonces, si no proporcionas una, **FastAPI** generará automáticamente una de "Response exitoso".
///
<img src="/img/tutorial/path-operation-configuration/image03.png">
## Deprecar una *path operation*
Si necesitas marcar una *path operation* como <abbr title="obsoleta, se recomienda no usarla">deprecated</abbr>, pero sin eliminarla, pasa el parámetro `deprecated`:
{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
Se marcará claramente como deprecado en la documentación interactiva:
<img src="/img/tutorial/path-operation-configuration/image04.png">
Revisa cómo lucen las *path operations* deprecadas y no deprecadas:
<img src="/img/tutorial/path-operation-configuration/image05.png">
## Resumen
Puedes configurar y añadir metadatos a tus *path operations* fácilmente pasando parámetros a los *path operation decorators*.

164
docs/es/docs/tutorial/path-params-numeric-validations.md Normal file
View File

@@ -0,0 +1,164 @@
# Parámetros de Path y Validaciones Numéricas
De la misma manera que puedes declarar más validaciones y metadatos para los parámetros de query con `Query`, puedes declarar el mismo tipo de validaciones y metadatos para los parámetros de path con `Path`.
## Importar Path
Primero, importa `Path` de `fastapi`, e importa `Annotated`:
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
/// info | Información
FastAPI agregó soporte para `Annotated` (y comenzó a recomendar su uso) en la versión 0.95.0.
Si tienes una versión anterior, obtendrás errores al intentar usar `Annotated`.
Asegúrate de [Actualizar la versión de FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} a al menos la 0.95.1 antes de usar `Annotated`.
///
## Declarar metadatos
Puedes declarar todos los mismos parámetros que para `Query`.
Por ejemplo, para declarar un valor de metadato `title` para el parámetro de path `item_id` puedes escribir:
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
/// note | Nota
Un parámetro de path siempre es requerido ya que tiene que formar parte del path. Incluso si lo declaras con `None` o le asignas un valor por defecto, no afectará en nada, siempre será requerido.
///
## Ordena los parámetros como necesites
/// tip | Consejo
Esto probablemente no es tan importante o necesario si usas `Annotated`.
///
Supongamos que quieres declarar el parámetro de query `q` como un `str` requerido.
Y no necesitas declarar nada más para ese parámetro, así que realmente no necesitas usar `Query`.
Pero aún necesitas usar `Path` para el parámetro de path `item_id`. Y no quieres usar `Annotated` por alguna razón.
Python se quejará si pones un valor con un "default" antes de un valor que no tenga un "default".
Pero puedes reordenarlos y poner el valor sin un default (el parámetro de query `q`) primero.
No importa para **FastAPI**. Detectará los parámetros por sus nombres, tipos y declaraciones por defecto (`Query`, `Path`, etc.), no le importa el orden.
Así que puedes declarar tu función como:
//// tab | Python 3.8 non-Annotated
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
////
Pero ten en cuenta que si usas `Annotated`, no tendrás este problema, no importará ya que no estás usando los valores por defecto de los parámetros de la función para `Query()` o `Path()`.
{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
## Ordena los parámetros como necesites, trucos
/// tip | Consejo
Esto probablemente no es tan importante o necesario si usas `Annotated`.
///
Aquí hay un **pequeño truco** que puede ser útil, pero no lo necesitarás a menudo.
Si quieres:
* declarar el parámetro de query `q` sin un `Query` ni ningún valor por defecto
* declarar el parámetro de path `item_id` usando `Path`
* tenerlos en un orden diferente
* no usar `Annotated`
...Python tiene una sintaxis especial para eso.
Pasa `*`, como el primer parámetro de la función.
Python no hará nada con ese `*`, pero sabrá que todos los parámetros siguientes deben ser llamados como argumentos de palabras clave (parejas key-value), también conocidos como <abbr title="De: K-ey W-ord Arg-uments"><code>kwargs</code></abbr>. Incluso si no tienen un valor por defecto.
{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
### Mejor con `Annotated`
Ten en cuenta que si usas `Annotated`, como no estás usando valores por defecto de los parámetros de la función, no tendrás este problema y probablemente no necesitarás usar `*`.
{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
## Validaciones numéricas: mayor o igual
Con `Query` y `Path` (y otros que verás más adelante) puedes declarar restricciones numéricas.
Aquí, con `ge=1`, `item_id` necesitará ser un número entero "`g`reater than or `e`qual" a `1`.
{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
## Validaciones numéricas: mayor que y menor o igual
Lo mismo aplica para:
* `gt`: `g`reater `t`han
* `le`: `l`ess than or `e`qual
{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
## Validaciones numéricas: flotantes, mayor y menor
Las validaciones numéricas también funcionan para valores `float`.
Aquí es donde se convierte en importante poder declarar <abbr title="greater than"><code>gt</code></abbr> y no solo <abbr title="greater than or equal"><code>ge</code></abbr>. Ya que con esto puedes requerir, por ejemplo, que un valor sea mayor que `0`, incluso si es menor que `1`.
Así, `0.5` sería un valor válido. Pero `0.0` o `0` no lo serían.
Y lo mismo para <abbr title="less than"><code>lt</code></abbr>.
{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
## Resumen
Con `Query`, `Path` (y otros que aún no has visto) puedes declarar metadatos y validaciones de string de las mismas maneras que con [Parámetros de Query y Validaciones de String](query-params-str-validations.md){.internal-link target=_blank}.
Y también puedes declarar validaciones numéricas:
* `gt`: `g`reater `t`han
* `ge`: `g`reater than or `e`qual
* `lt`: `l`ess `t`han
* `le`: `l`ess than or `e`qual
/// info | Información
`Query`, `Path` y otras clases que verás más adelante son subclases de una clase común `Param`.
Todas ellas comparten los mismos parámetros para validación adicional y metadatos que has visto.
///
/// note | Nota técnica
Cuando importas `Query`, `Path` y otros de `fastapi`, en realidad son funciones.
Que cuando se llaman, retornan instances de clases con el mismo nombre.
Así que importas `Query`, que es una función. Y cuando la llamas, retorna una instance de una clase también llamada `Query`.
Estas funciones están allí (en lugar de usar simplemente las clases directamente) para que tu editor no marque errores sobre sus tipos.
De esa forma puedes usar tu editor y herramientas de programación normales sin tener que agregar configuraciones personalizadas para omitir esos errores.
///

68
docs/es/docs/tutorial/query-param-models.md Normal file
View File

@@ -0,0 +1,68 @@
# Modelos de Parámetros Query
Si tienes un grupo de **parámetros query** que están relacionados, puedes crear un **modelo de Pydantic** para declararlos.
Esto te permitiría **reutilizar el modelo** en **múltiples lugares** y también declarar validaciones y metadatos para todos los parámetros de una vez. 😎
/// note | Nota
Esto es compatible desde la versión `0.115.0` de FastAPI. 🤓
///
## Parámetros Query con un Modelo Pydantic
Declara los **parámetros query** que necesitas en un **modelo de Pydantic**, y luego declara el parámetro como `Query`:
{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
**FastAPI** **extraerá** los datos para **cada campo** de los **parámetros query** en el request y te proporcionará el modelo de Pydantic que definiste.
## Revisa la Documentación
Puedes ver los parámetros query en la UI de documentación en `/docs`:
<div class="screenshot">
<img src="/img/tutorial/query-param-models/image01.png">
</div>
## Prohibir Parámetros Query Extras
En algunos casos de uso especiales (probablemente no muy comunes), podrías querer **restringir** los parámetros query que deseas recibir.
Puedes usar la configuración del modelo de Pydantic para `forbid` cualquier campo `extra`:
{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}
Si un cliente intenta enviar algunos datos **extra** en los **parámetros query**, recibirán un response de **error**.
Por ejemplo, si el cliente intenta enviar un parámetro query `tool` con un valor de `plumbus`, como:
```http
https://example.com/items/?limit=10&tool=plumbus
```
Recibirán un response de **error** que les indica que el parámetro query `tool` no está permitido:
```json
{
"detail": [
{
"type": "extra_forbidden",
"loc": ["query", "tool"],
"msg": "Extra inputs are not permitted",
"input": "plumbus"
}
]
}
```
## Resumen
Puedes usar **modelos de Pydantic** para declarar **parámetros query** en **FastAPI**. 😎
/// tip | Consejo
Alerta de spoiler: también puedes usar modelos de Pydantic para declarar cookies y headers, pero leerás sobre eso más adelante en el tutorial. 🤫
///

515
docs/es/docs/tutorial/query-params-str-validations.md Normal file
View File

@@ -0,0 +1,515 @@
# Parámetros de Query y Validaciones de String
**FastAPI** te permite declarar información adicional y validación para tus parámetros.
Tomemos esta aplicación como ejemplo:
{* ../../docs_src/query_params_str_validations/tutorial001_py310.py hl[7] *}
El parámetro de query `q` es del tipo `Union[str, None]` (o `str | None` en Python 3.10), lo que significa que es de tipo `str` pero también podría ser `None`, y de hecho, el valor por defecto es `None`, así que FastAPI sabrá que no es requerido.
/// note | Nota
FastAPI sabrá que el valor de `q` no es requerido por el valor por defecto `= None`.
El `Union` en `Union[str, None]` permitirá a tu editor darte un mejor soporte y detectar errores.
///
## Validaciones adicionales
Vamos a hacer que, aunque `q` sea opcional, siempre que se proporcione, **su longitud no exceda los 50 caracteres**.
### Importar `Query` y `Annotated`
Para lograr eso, primero importa:
* `Query` desde `fastapi`
* `Annotated` desde `typing` (o desde `typing_extensions` en Python por debajo de 3.9)
//// tab | Python 3.10+
En Python 3.9 o superior, `Annotated` es parte de la biblioteca estándar, así que puedes importarlo desde `typing`.
```Python hl_lines="1 3"
{!> ../../docs_src/query_params_str_validations/tutorial002_an_py310.py!}
```
////
//// tab | Python 3.8+
En versiones de Python por debajo de 3.9 importas `Annotated` desde `typing_extensions`.
Ya estará instalado con FastAPI.
```Python hl_lines="3-4"
{!> ../../docs_src/query_params_str_validations/tutorial002_an.py!}
```
////
/// info | Información
FastAPI añadió soporte para `Annotated` (y empezó a recomendarlo) en la versión 0.95.0.
Si tienes una versión más antigua, obtendrás errores al intentar usar `Annotated`.
Asegúrate de [Actualizar la versión de FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} a al menos 0.95.1 antes de usar `Annotated`.
///
## Usar `Annotated` en el tipo del parámetro `q`
¿Recuerdas que te dije antes que `Annotated` puede ser usado para agregar metadatos a tus parámetros en la [Introducción a Tipos de Python](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}?
Ahora es el momento de usarlo con FastAPI. 🚀
Teníamos esta anotación de tipo:
//// tab | Python 3.10+
```Python
q: str | None = None
```
////
//// tab | Python 3.8+
```Python
q: Union[str, None] = None
```
////
Lo que haremos es envolver eso con `Annotated`, para que se convierta en:
//// tab | Python 3.10+
```Python
q: Annotated[str | None] = None
```
////
//// tab | Python 3.8+
```Python
q: Annotated[Union[str, None]] = None
```
////
Ambas versiones significan lo mismo, `q` es un parámetro que puede ser un `str` o `None`, y por defecto, es `None`.
Ahora vamos a lo divertido. 🎉
## Agregar `Query` a `Annotated` en el parámetro `q`
Ahora que tenemos este `Annotated` donde podemos poner más información (en este caso algunas validaciones adicionales), agrega `Query` dentro de `Annotated`, y establece el parámetro `max_length` a `50`:
{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[9] *}
Nota que el valor por defecto sigue siendo `None`, por lo que el parámetro sigue siendo opcional.
Pero ahora, al tener `Query(max_length=50)` dentro de `Annotated`, le estamos diciendo a FastAPI que queremos que tenga **validación adicional** para este valor, queremos que tenga un máximo de 50 caracteres. 😎
/// tip | Consejo
Aquí estamos usando `Query()` porque este es un **parámetro de query**. Más adelante veremos otros como `Path()`, `Body()`, `Header()`, y `Cookie()`, que también aceptan los mismos argumentos que `Query()`.
///
FastAPI ahora:
* **Validará** los datos asegurándose de que la longitud máxima sea de 50 caracteres
* Mostrará un **error claro** para el cliente cuando los datos no sean válidos
* **Documentará** el parámetro en el OpenAPI esquema *path operation* (así aparecerá en la **UI de documentación automática**)
## Alternativa (antigua): `Query` como valor por defecto
Versiones anteriores de FastAPI (antes de <abbr title="antes de 2023-03">0.95.0</abbr>) requerían que usaras `Query` como el valor por defecto de tu parámetro, en lugar de ponerlo en `Annotated`. Hay una alta probabilidad de que veas código usándolo alrededor, así que te lo explicaré.
/// tip | Consejo
Para nuevo código y siempre que sea posible, usa `Annotated` como se explicó arriba. Hay múltiples ventajas (explicadas a continuación) y no hay desventajas. 🍰
///
Así es como usarías `Query()` como el valor por defecto de tu parámetro de función, estableciendo el parámetro `max_length` a 50:
{* ../../docs_src/query_params_str_validations/tutorial002_py310.py hl[7] *}
Ya que en este caso (sin usar `Annotated`) debemos reemplazar el valor por defecto `None` en la función con `Query()`, ahora necesitamos establecer el valor por defecto con el parámetro `Query(default=None)`, esto sirve al mismo propósito de definir ese valor por defecto (al menos para FastAPI).
Entonces:
```Python
q: Union[str, None] = Query(default=None)
```
...hace que el parámetro sea opcional, con un valor por defecto de `None`, lo mismo que:
```Python
q: Union[str, None] = None
```
Y en Python 3.10 y superior:
```Python
q: str | None = Query(default=None)
```
...hace que el parámetro sea opcional, con un valor por defecto de `None`, lo mismo que:
```Python
q: str | None = None
```
Pero las versiones de `Query` lo declaran explícitamente como un parámetro de query.
/// info | Información
Ten en cuenta que la parte más importante para hacer un parámetro opcional es la parte:
```Python
= None
```
o la parte:
```Python
= Query(default=None)
```
ya que usará ese `None` como el valor por defecto, y de esa manera hará el parámetro **no requerido**.
La parte `Union[str, None]` permite que tu editor brinde un mejor soporte, pero no es lo que le dice a FastAPI que este parámetro no es requerido.
///
Luego, podemos pasar más parámetros a `Query`. En este caso, el parámetro `max_length` que se aplica a los strings:
```Python
q: Union[str, None] = Query(default=None, max_length=50)
```
Esto validará los datos, mostrará un error claro cuando los datos no sean válidos, y documentará el parámetro en el esquema del *path operation* de OpenaPI.
### `Query` como valor por defecto o en `Annotated`
Ten en cuenta que cuando uses `Query` dentro de `Annotated` no puedes usar el parámetro `default` para `Query`.
En su lugar utiliza el valor por defecto real del parámetro de la función. De lo contrario, sería inconsistente.
Por ejemplo, esto no está permitido:
```Python
q: Annotated[str, Query(default="rick")] = "morty"
```
...porque no está claro si el valor por defecto debería ser `"rick"` o `"morty"`.
Así que utilizarías (preferentemente):
```Python
q: Annotated[str, Query()] = "rick"
```
...o en code bases más antiguos encontrarás:
```Python
q: str = Query(default="rick")
```
### Ventajas de `Annotated`
**Usar `Annotated` es recomendado** en lugar del valor por defecto en los parámetros de función, es **mejor** por múltiples razones. 🤓
El valor **por defecto** del **parámetro de función** es el valor **real por defecto**, eso es más intuitivo con Python en general. 😌
Podrías **llamar** a esa misma función en **otros lugares** sin FastAPI, y **funcionaría como se espera**. Si hay un parámetro **requerido** (sin un valor por defecto), tu **editor** te avisará con un error, **Python** también se quejará si lo ejecutas sin pasar el parámetro requerido.
Cuando no usas `Annotated` y en su lugar usas el estilo de valor por defecto **(antiguo)**, si llamas a esa función sin FastAPI en **otros lugares**, tienes que **recordar** pasar los argumentos a la función para que funcione correctamente, de lo contrario, los valores serán diferentes de lo que esperas (por ejemplo, `QueryInfo` o algo similar en lugar de `str`). Y tu editor no se quejará, y Python no se quejará al ejecutar esa función, solo cuando los errores dentro de las operaciones hagan que funcione incorrectamente.
Dado que `Annotated` puede tener más de una anotación de metadato, ahora podrías incluso usar la misma función con otras herramientas, como <a href="https://typer.tiangolo.com/" class="external-link" target="_blank">Typer</a>. 🚀
## Agregar más validaciones
También puedes agregar un parámetro `min_length`:
{* ../../docs_src/query_params_str_validations/tutorial003_an_py310.py hl[10] *}
## Agregar expresiones regulares
Puedes definir una <abbr title="Una expresión regular, regex o regexp es una secuencia de caracteres que define un patrón de búsqueda para strings.">expresión regular</abbr> `pattern` que el parámetro debe coincidir:
{* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *}
Este patrón específico de expresión regular comprueba que el valor recibido del parámetro:
* `^`: comience con los siguientes caracteres, no tiene caracteres antes.
* `fixedquery`: tiene el valor exacto `fixedquery`.
* `$`: termina allí, no tiene más caracteres después de `fixedquery`.
Si te sientes perdido con todas estas ideas de **"expresión regular"**, no te preocupes. Son un tema difícil para muchas personas. Aún puedes hacer muchas cosas sin necesitar expresiones regulares todavía.
Pero cuando las necesites y vayas a aprenderlas, ya sabes que puedes usarlas directamente en **FastAPI**.
### Pydantic v1 `regex` en lugar de `pattern`
Antes de la versión 2 de Pydantic y antes de FastAPI 0.100.0, el parámetro se llamaba `regex` en lugar de `pattern`, pero ahora está en desuso.
Todavía podrías ver algo de código que lo usa:
//// tab | Pydantic v1
{* ../../docs_src/query_params_str_validations/tutorial004_regex_an_py310.py hl[11] *}
////
Pero que sepas que esto está deprecado y debería actualizarse para usar el nuevo parámetro `pattern`. 🤓
## Valores por defecto
Puedes, por supuesto, usar valores por defecto diferentes de `None`.
Digamos que quieres declarar el parámetro de query `q` para que tenga un `min_length` de `3`, y para que tenga un valor por defecto de `"fixedquery"`:
{* ../../docs_src/query_params_str_validations/tutorial005_an_py39.py hl[9] *}
/// note | Nota
Tener un valor por defecto de cualquier tipo, incluyendo `None`, hace que el parámetro sea opcional (no requerido).
///
## Parámetros requeridos
Cuando no necesitamos declarar más validaciones o metadatos, podemos hacer que el parámetro de query `q` sea requerido simplemente no declarando un valor por defecto, como:
```Python
q: str
```
en lugar de:
```Python
q: Union[str, None] = None
```
Pero ahora lo estamos declarando con `Query`, por ejemplo, como:
//// tab | Annotated
```Python
q: Annotated[Union[str, None], Query(min_length=3)] = None
```
////
//// tab | non-Annotated
```Python
q: Union[str, None] = Query(default=None, min_length=3)
```
////
Así que, cuando necesites declarar un valor como requerido mientras usas `Query`, simplemente puedes no declarar un valor por defecto:
{* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *}
### Requerido con Puntos suspensivos (`...`)
Hay una manera alternativa de declarar explícitamente que un valor es requerido. Puedes establecer el valor por defecto al valor literal `...`:
{* ../../docs_src/query_params_str_validations/tutorial006b_an_py39.py hl[9] *}
/// info | Información
Si no habías visto eso `...` antes: es un valor especial único, es <a href="https://docs.python.org/3/library/constants.html#Ellipsis" class="external-link" target="_blank">parte de Python y se llama "Ellipsis"</a>.
Se usa por Pydantic y FastAPI para declarar explícitamente que un valor es requerido.
///
Esto le permitirá a **FastAPI** saber que este parámetro es requerido.
### Requerido, puede ser `None`
Puedes declarar que un parámetro puede aceptar `None`, pero que aún así es requerido. Esto obligaría a los clientes a enviar un valor, incluso si el valor es `None`.
Para hacer eso, puedes declarar que `None` es un tipo válido pero aún usar `...` como el valor por defecto:
{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
/// tip | Consejo
Pydantic, que es lo que impulsa toda la validación y serialización de datos en FastAPI, tiene un comportamiento especial cuando usas `Optional` o `Union[Something, None]` sin un valor por defecto, puedes leer más al respecto en la documentación de Pydantic sobre <a href="https://docs.pydantic.dev/2.3/usage/models/#required-optional-fields" class="external-link" target="_blank">Campos requeridos</a>.
///
/// tip | Consejo
Recuerda que en la mayoría de los casos, cuando algo es requerido, puedes simplemente omitir el default, así que normalmente no tienes que usar `...`.
///
## Lista de parámetros de Query / múltiples valores
Cuando defines un parámetro de query explícitamente con `Query` también puedes declararlo para recibir una lista de valores, o dicho de otra manera, para recibir múltiples valores.
Por ejemplo, para declarar un parámetro de query `q` que puede aparecer varias veces en la URL, puedes escribir:
{* ../../docs_src/query_params_str_validations/tutorial011_an_py310.py hl[9] *}
Entonces, con una URL como:
```
http://localhost:8000/items/?q=foo&q=bar
```
recibirías los múltiples valores del *query parameter* `q` (`foo` y `bar`) en una `list` de Python dentro de tu *path operation function*, en el *parámetro de función* `q`.
Entonces, el response a esa URL sería:
```JSON
{
"q": [
"foo",
"bar"
]
}
```
/// tip | Consejo
Para declarar un parámetro de query con un tipo de `list`, como en el ejemplo anterior, necesitas usar explícitamente `Query`, de lo contrario sería interpretado como un request body.
///
La documentación interactiva de API se actualizará en consecuencia, para permitir múltiples valores:
<img src="/img/tutorial/query-params-str-validations/image02.png">
### Lista de parámetros de Query / múltiples valores con valores por defecto
Y también puedes definir un valor por defecto `list` de valores si no se proporcionan ninguno:
{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
Si vas a:
```
http://localhost:8000/items/
```
el valor por defecto de `q` será: `["foo", "bar"]` y tu response será:
```JSON
{
"q": [
"foo",
"bar"
]
}
```
#### Usando solo `list`
También puedes usar `list` directamente en lugar de `List[str]` (o `list[str]` en Python 3.9+):
{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
/// note | Nota
Ten en cuenta que en este caso, FastAPI no comprobará el contenido de la lista.
Por ejemplo, `List[int]` comprobaría (y documentaría) que el contenido de la lista son enteros. Pero `list` sola no lo haría.
///
## Declarar más metadatos
Puedes agregar más información sobre el parámetro.
Esa información se incluirá en el OpenAPI generado y será utilizada por las interfaces de usuario de documentación y herramientas externas.
/// note | Nota
Ten en cuenta que diferentes herramientas podrían tener diferentes niveles de soporte de OpenAPI.
Algunas de ellas podrían no mostrar toda la información extra declarada todavía, aunque en la mayoría de los casos, la funcionalidad faltante ya está planificada para desarrollo.
///
Puedes agregar un `title`:
{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
Y una `description`:
{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
## Alias para parámetros
Imagina que quieres que el parámetro sea `item-query`.
Como en:
```
http://127.0.0.1:8000/items/?item-query=foobaritems
```
Pero `item-query` no es un nombre de variable válido en Python.
Lo más cercano sería `item_query`.
Pero aún necesitas que sea exactamente `item-query`...
Entonces puedes declarar un `alias`, y ese alias será usado para encontrar el valor del parámetro:
{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
## Declarar parámetros obsoletos
Ahora digamos que ya no te gusta este parámetro.
Tienes que dejarlo allí por un tiempo porque hay clientes usándolo, pero quieres que la documentación lo muestre claramente como <abbr title="obsoleto, se recomienda no usarlo">deprecated</abbr>.
Luego pasa el parámetro `deprecated=True` a `Query`:
{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
La documentación lo mostrará así:
<img src="/img/tutorial/query-params-str-validations/image01.png">
## Excluir parámetros de OpenAPI
Para excluir un parámetro de query del esquema de OpenAPI generado (y por lo tanto, de los sistemas de documentación automática), establece el parámetro `include_in_schema` de `Query` a `False`:
{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
## Recapitulación
Puedes declarar validaciones y metadatos adicionales para tus parámetros.
Validaciones genéricas y metadatos:
* `alias`
* `title`
* `description`
* `deprecated`
Validaciones específicas para strings:
* `min_length`
* `max_length`
* `pattern`
En estos ejemplos viste cómo declarar validaciones para valores de tipo `str`.
Mira los siguientes capítulos para aprender cómo declarar validaciones para otros tipos, como números.

176
docs/es/docs/tutorial/request-files.md Normal file
View File

@@ -0,0 +1,176 @@
# Archivos de Request
Puedes definir archivos que serán subidos por el cliente utilizando `File`.
/// info | Información
Para recibir archivos subidos, primero instala <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo y luego instalarlo, por ejemplo:
```console
$ pip install python-multipart
```
Esto es porque los archivos subidos se envían como "form data".
///
## Importar `File`
Importa `File` y `UploadFile` desde `fastapi`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
## Definir Parámetros `File`
Crea parámetros de archivo de la misma manera que lo harías para `Body` o `Form`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *}
/// info | Información
`File` es una clase que hereda directamente de `Form`.
Pero recuerda que cuando importas `Query`, `Path`, `File` y otros desde `fastapi`, esos son en realidad funciones que devuelven clases especiales.
///
/// tip | Consejo
Para declarar cuerpos de File, necesitas usar `File`, porque de otra manera los parámetros serían interpretados como parámetros query o parámetros de cuerpo (JSON).
///
Los archivos se subirán como "form data".
Si declaras el tipo de tu parámetro de *path operation function* como `bytes`, **FastAPI** leerá el archivo por ti y recibirás el contenido como `bytes`.
Ten en cuenta que esto significa que todo el contenido se almacenará en memoria. Esto funcionará bien para archivos pequeños.
Pero hay varios casos en los que podrías beneficiarte de usar `UploadFile`.
## Parámetros de Archivo con `UploadFile`
Define un parámetro de archivo con un tipo de `UploadFile`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}
Usar `UploadFile` tiene varias ventajas sobre `bytes`:
* No tienes que usar `File()` en el valor por defecto del parámetro.
* Usa un archivo "spooled":
* Un archivo almacenado en memoria hasta un límite de tamaño máximo, y después de superar este límite, se almacenará en el disco.
* Esto significa que funcionará bien para archivos grandes como imágenes, videos, binarios grandes, etc. sin consumir toda la memoria.
* Puedes obtener metadatos del archivo subido.
* Tiene una interfaz `async` <a href="https://docs.python.org/3/glossary.html#term-file-like-object" class="external-link" target="_blank">parecida a un archivo</a>.
* Expone un objeto Python real <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" class="external-link" target="_blank">`SpooledTemporaryFile`</a> que puedes pasar directamente a otros paquetes que esperan un objeto parecido a un archivo.
### `UploadFile`
`UploadFile` tiene los siguientes atributos:
* `filename`: Un `str` con el nombre original del archivo que fue subido (por ejemplo, `myimage.jpg`).
* `content_type`: Un `str` con el tipo de contenido (MIME type / media type) (por ejemplo, `image/jpeg`).
* `file`: Un <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" class="external-link" target="_blank">`SpooledTemporaryFile`</a> (un objeto <a href="https://docs.python.org/3/glossary.html#term-file-like-object" class="external-link" target="_blank">parecido a un archivo</a>). Este es el objeto de archivo Python real que puedes pasar directamente a otras funciones o paquetes que esperan un objeto "parecido a un archivo".
`UploadFile` tiene los siguientes métodos `async`. Todos ellos llaman a los métodos correspondientes del archivo por debajo (usando el `SpooledTemporaryFile` interno).
* `write(data)`: Escribe `data` (`str` o `bytes`) en el archivo.
* `read(size)`: Lee `size` (`int`) bytes/caracteres del archivo.
* `seek(offset)`: Va a la posición de bytes `offset` (`int`) en el archivo.
* Por ejemplo, `await myfile.seek(0)` iría al inicio del archivo.
* Esto es especialmente útil si ejecutas `await myfile.read()` una vez y luego necesitas leer el contenido nuevamente.
* `close()`: Cierra el archivo.
Como todos estos métodos son métodos `async`, necesitas "await" para ellos.
Por ejemplo, dentro de una *path operation function* `async` puedes obtener los contenidos con:
```Python
contents = await myfile.read()
```
Si estás dentro de una *path operation function* normal `def`, puedes acceder al `UploadFile.file` directamente, por ejemplo:
```Python
contents = myfile.file.read()
```
/// note | Detalles Técnicos de `async`
Cuando usas los métodos `async`, **FastAPI** ejecuta los métodos del archivo en un threadpool y los espera.
///
/// note | Detalles Técnicos de Starlette
El `UploadFile` de **FastAPI** hereda directamente del `UploadFile` de **Starlette**, pero añade algunas partes necesarias para hacerlo compatible con **Pydantic** y las otras partes de FastAPI.
///
## Qué es "Form Data"
La manera en que los forms de HTML (`<form></form>`) envían los datos al servidor normalmente utiliza una codificación "especial" para esos datos, es diferente de JSON.
**FastAPI** se asegurará de leer esos datos del lugar correcto en lugar de JSON.
/// note | Detalles Técnicos
Los datos de los forms normalmente se codifican usando el "media type" `application/x-www-form-urlencoded` cuando no incluyen archivos.
Pero cuando el formulario incluye archivos, se codifica como `multipart/form-data`. Si usas `File`, **FastAPI** sabrá que tiene que obtener los archivos de la parte correcta del cuerpo.
Si deseas leer más sobre estas codificaciones y campos de formularios, dirígete a la <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs para <code>POST</code></a>.
///
/// warning | Advertencia
Puedes declarar múltiples parámetros `File` y `Form` en una *path operation*, pero no puedes declarar campos `Body` que esperas recibir como JSON, ya que el request tendrá el cuerpo codificado usando `multipart/form-data` en lugar de `application/json`.
Esto no es una limitación de **FastAPI**, es parte del protocolo HTTP.
///
## Subida de Archivos Opcional
Puedes hacer un archivo opcional utilizando anotaciones de tipos estándar y estableciendo un valor por defecto de `None`:
{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
## `UploadFile` con Metadatos Adicionales
También puedes usar `File()` con `UploadFile`, por ejemplo, para establecer metadatos adicionales:
{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
## Subidas de Múltiples Archivos
Es posible subir varios archivos al mismo tiempo.
Estarían asociados al mismo "campo de formulario" enviado usando "form data".
Para usar eso, declara una lista de `bytes` o `UploadFile`:
{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
Recibirás, como se declaró, una `list` de `bytes` o `UploadFile`s.
/// note | Detalles Técnicos
También podrías usar `from starlette.responses import HTMLResponse`.
**FastAPI** proporciona las mismas `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
///
### Subidas de Múltiples Archivos con Metadatos Adicionales
Y de la misma manera que antes, puedes usar `File()` para establecer parámetros adicionales, incluso para `UploadFile`:
{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
## Recapitulación
Usa `File`, `bytes` y `UploadFile` para declarar archivos que se subirán en el request, enviados como form data.

78
docs/es/docs/tutorial/request-form-models.md Normal file
View File

@@ -0,0 +1,78 @@
# Modelos de Formulario
Puedes usar **modelos de Pydantic** para declarar **campos de formulario** en FastAPI.
/// info | Información
Para usar formularios, primero instala <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo, y luego instalarlo, por ejemplo:
```console
$ pip install python-multipart
```
///
/// note | Nota
Esto es compatible desde la versión `0.113.0` de FastAPI. 🤓
///
## Modelos de Pydantic para Formularios
Solo necesitas declarar un **modelo de Pydantic** con los campos que quieres recibir como **campos de formulario**, y luego declarar el parámetro como `Form`:
{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
**FastAPI** **extraerá** los datos de **cada campo** de los **form data** en el request y te dará el modelo de Pydantic que definiste.
## Revisa la Documentación
Puedes verificarlo en la interfaz de documentación en `/docs`:
<div class="screenshot">
<img src="/img/tutorial/request-form-models/image01.png">
</div>
## Prohibir Campos de Formulario Extra
En algunos casos de uso especiales (probablemente no muy comunes), podrías querer **restringir** los campos de formulario a solo aquellos declarados en el modelo de Pydantic. Y **prohibir** cualquier campo **extra**.
/// note | Nota
Esto es compatible desde la versión `0.114.0` de FastAPI. 🤓
///
Puedes usar la configuración del modelo de Pydantic para `forbid` cualquier campo `extra`:
{* ../../docs_src/request_form_models/tutorial002_an_py39.py hl[12] *}
Si un cliente intenta enviar datos extra, recibirá un response de **error**.
Por ejemplo, si el cliente intenta enviar los campos de formulario:
* `username`: `Rick`
* `password`: `Portal Gun`
* `extra`: `Mr. Poopybutthole`
Recibirá un response de error indicando que el campo `extra` no está permitido:
```json
{
"detail": [
{
"type": "extra_forbidden",
"loc": ["body", "extra"],
"msg": "Extra inputs are not permitted",
"input": "Mr. Poopybutthole"
}
]
}
```
## Resumen
Puedes usar modelos de Pydantic para declarar campos de formulario en FastAPI. 😎

41
docs/es/docs/tutorial/request-forms-and-files.md Normal file
View File

@@ -0,0 +1,41 @@
# Request Forms and Files
Puedes definir archivos y campos de formulario al mismo tiempo usando `File` y `Form`.
/// info | Información
Para recibir archivos subidos y/o form data, primero instala <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, actívalo y luego instálalo, por ejemplo:
```console
$ pip install python-multipart
```
///
## Importar `File` y `Form`
{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[3] *}
## Definir parámetros `File` y `Form`
Crea parámetros de archivo y formulario de la misma manera que lo harías para `Body` o `Query`:
{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[10:12] *}
Los archivos y campos de formulario se subirán como form data y recibirás los archivos y campos de formulario.
Y puedes declarar algunos de los archivos como `bytes` y algunos como `UploadFile`.
/// warning | Advertencia
Puedes declarar múltiples parámetros `File` y `Form` en una *path operation*, pero no puedes también declarar campos `Body` que esperas recibir como JSON, ya que el request tendrá el body codificado usando `multipart/form-data` en lugar de `application/json`.
Esto no es una limitación de **FastAPI**, es parte del protocolo HTTP.
///
## Resumen
Usa `File` y `Form` juntos cuando necesites recibir datos y archivos en el mismo request.

73
docs/es/docs/tutorial/request-forms.md Normal file
View File

@@ -0,0 +1,73 @@
# Form Data
Cuando necesitas recibir campos de formulario en lugar de JSON, puedes usar `Form`.
/// info | Información
Para usar forms, primero instala <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a>.
Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo, y luego instalarlo, por ejemplo:
```console
$ pip install python-multipart
```
///
## Importar `Form`
Importar `Form` desde `fastapi`:
{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *}
## Definir parámetros de `Form`
Crea parámetros de formulario de la misma manera que lo harías para `Body` o `Query`:
{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[9] *}
Por ejemplo, en una de las formas en las que se puede usar la especificación OAuth2 (llamada "password flow") se requiere enviar un `username` y `password` como campos de formulario.
La <abbr title="specification">especificación</abbr> requiere que los campos se llamen exactamente `username` y `password`, y que se envíen como campos de formulario, no JSON.
Con `Form` puedes declarar las mismas configuraciones que con `Body` (y `Query`, `Path`, `Cookie`), incluyendo validación, ejemplos, un alias (por ejemplo, `user-name` en lugar de `username`), etc.
/// info | Información
`Form` es una clase que hereda directamente de `Body`.
///
/// tip | Consejo
Para declarar bodies de forms, necesitas usar `Form` explícitamente, porque sin él, los parámetros se interpretarían como parámetros de query o como parámetros de body (JSON).
///
## Sobre "Campos de Formulario"
La manera en que los forms HTML (`<form></form>`) envían los datos al servidor normalmente usa una codificación "especial" para esos datos, es diferente de JSON.
**FastAPI** se encargará de leer esos datos del lugar correcto en lugar de JSON.
/// note | Detalles técnicos
Los datos de forms normalmente se codifican usando el "media type" `application/x-www-form-urlencoded`.
Pero cuando el formulario incluye archivos, se codifica como `multipart/form-data`. Leerás sobre la gestión de archivos en el próximo capítulo.
Si quieres leer más sobre estas codificaciones y campos de formulario, dirígete a la <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs para <code>POST</code></a>.
///
/// warning | Advertencia
Puedes declarar múltiples parámetros `Form` en una *path operation*, pero no puedes también declarar campos `Body` que esperas recibir como JSON, ya que el request tendrá el body codificado usando `application/x-www-form-urlencoded` en lugar de `application/json`.
Esto no es una limitación de **FastAPI**, es parte del protocolo HTTP.
///
## Recapitulación
Usa `Form` para declarar parámetros de entrada de datos de formulario.

357
docs/es/docs/tutorial/response-model.md Normal file
View File

@@ -0,0 +1,357 @@
# Modelo de Response - Tipo de Retorno
Puedes declarar el tipo utilizado para el response anotando el **tipo de retorno** de la *path operation function*.
Puedes utilizar **anotaciones de tipos** de la misma manera que lo harías para datos de entrada en **parámetros** de función, puedes utilizar modelos de Pydantic, listas, diccionarios, valores escalares como enteros, booleanos, etc.
{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
FastAPI usará este tipo de retorno para:
* **Validar** los datos devueltos.
* Si los datos son inválidos (por ejemplo, falta un campo), significa que el código de *tu* aplicación está defectuoso, no devolviendo lo que debería, y retornará un error del servidor en lugar de devolver datos incorrectos. De esta manera, tú y tus clientes pueden estar seguros de que recibirán los datos y la forma de los datos esperada.
* Agregar un **JSON Schema** para el response, en la *path operation* de OpenAPI.
* Esto será utilizado por la **documentación automática**.
* También será utilizado por herramientas de generación automática de código de cliente.
Pero lo más importante:
* **Limitará y filtrará** los datos de salida a lo que se define en el tipo de retorno.
* Esto es particularmente importante para la **seguridad**, veremos más sobre eso a continuación.
## Parámetro `response_model`
Hay algunos casos en los que necesitas o quieres devolver algunos datos que no son exactamente lo que declara el tipo.
Por ejemplo, podrías querer **devolver un diccionario** u objeto de base de datos, pero **declararlo como un modelo de Pydantic**. De esta manera el modelo de Pydantic haría toda la documentación de datos, validación, etc. para el objeto que devolviste (por ejemplo, un diccionario u objeto de base de datos).
Si añadiste la anotación del tipo de retorno, las herramientas y editores se quejarían con un error (correcto) diciéndote que tu función está devolviendo un tipo (por ejemplo, un dict) que es diferente de lo que declaraste (por ejemplo, un modelo de Pydantic).
En esos casos, puedes usar el parámetro del decorador de path operation `response_model` en lugar del tipo de retorno.
Puedes usar el parámetro `response_model` en cualquiera de las *path operations*:
* `@app.get()`
* `@app.post()`
* `@app.put()`
* `@app.delete()`
* etc.
{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *}
/// note | Nota
Observa que `response_model` es un parámetro del método "decorador" (`get`, `post`, etc). No de tu *path operation function*, como todos los parámetros y el cuerpo.
///
`response_model` recibe el mismo tipo que declararías para un campo de modelo Pydantic, por lo que puede ser un modelo de Pydantic, pero también puede ser, por ejemplo, un `list` de modelos de Pydantic, como `List[Item]`.
FastAPI usará este `response_model` para hacer toda la documentación de datos, validación, etc. y también para **convertir y filtrar los datos de salida** a su declaración de tipo.
/// tip | Consejo
Si tienes chequeos estrictos de tipos en tu editor, mypy, etc., puedes declarar el tipo de retorno de la función como `Any`.
De esa manera le dices al editor que intencionalmente estás devolviendo cualquier cosa. Pero FastAPI todavía hará la documentación de datos, validación, filtrado, etc. con `response_model`.
///
### Prioridad del `response_model`
Si declaras tanto un tipo de retorno como un `response_model`, el `response_model` tomará prioridad y será utilizado por FastAPI.
De esta manera puedes añadir anotaciones de tipos correctas a tus funciones incluso cuando estás devolviendo un tipo diferente al modelo de response, para ser utilizado por el editor y herramientas como mypy. Y aún así puedes hacer que FastAPI realice la validación de datos, documentación, etc. usando el `response_model`.
También puedes usar `response_model=None` para desactivar la creación de un modelo de response para esa *path operation*, podrías necesitar hacerlo si estás añadiendo anotaciones de tipos para cosas que no son campos válidos de Pydantic, verás un ejemplo de eso en una de las secciones a continuación.
## Devolver los mismos datos de entrada
Aquí estamos declarando un modelo `UserIn`, contendrá una contraseña en texto plano:
{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
/// info | Información
Para usar `EmailStr`, primero instala <a href="https://github.com/JoshData/python-email-validator" class="external-link" target="_blank">`email-validator`</a>.
Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo, y luego instalarlo, por ejemplo:
```console
$ pip install email-validator
```
o con:
```console
$ pip install "pydantic[email]"
```
///
Y estamos usando este modelo para declarar nuestra entrada y el mismo modelo para declarar nuestra salida:
{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *}
Ahora, cada vez que un navegador esté creando un usuario con una contraseña, la API devolverá la misma contraseña en el response.
En este caso, podría no ser un problema, porque es el mismo usuario que envía la contraseña.
Pero si usamos el mismo modelo para otra *path operation*, podríamos estar enviando las contraseñas de nuestros usuarios a cada cliente.
/// danger | Peligro
Nunca almacenes la contraseña en texto plano de un usuario ni la envíes en un response como esta, a menos que conozcas todas las advertencias y sepas lo que estás haciendo.
///
## Añadir un modelo de salida
Podemos en cambio crear un modelo de entrada con la contraseña en texto plano y un modelo de salida sin ella:
{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
Aquí, aunque nuestra *path operation function* está devolviendo el mismo usuario de entrada que contiene la contraseña:
{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
...hemos declarado el `response_model` para ser nuestro modelo `UserOut`, que no incluye la contraseña:
{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
Entonces, **FastAPI** se encargará de filtrar todos los datos que no estén declarados en el modelo de salida (usando Pydantic).
### `response_model` o Tipo de Retorno
En este caso, como los dos modelos son diferentes, si anotáramos el tipo de retorno de la función como `UserOut`, el editor y las herramientas se quejarían de que estamos devolviendo un tipo inválido, ya que son clases diferentes.
Por eso en este ejemplo tenemos que declararlo en el parámetro `response_model`.
...pero sigue leyendo abajo para ver cómo superar eso.
## Tipo de Retorno y Filtrado de Datos
Continuemos con el ejemplo anterior. Queríamos **anotar la función con un tipo**, pero queríamos poder devolver desde la función algo que en realidad incluya **más datos**.
Queremos que FastAPI continúe **filtrando** los datos usando el modelo de response. Para que, incluso cuando la función devuelva más datos, el response solo incluya los campos declarados en el modelo de response.
En el ejemplo anterior, debido a que las clases eran diferentes, tuvimos que usar el parámetro `response_model`. Pero eso también significa que no obtenemos el soporte del editor y las herramientas verificando el tipo de retorno de la función.
Pero en la mayoría de los casos en los que necesitamos hacer algo como esto, queremos que el modelo solo **filtre/elimine** algunos de los datos como en este ejemplo.
Y en esos casos, podemos usar clases y herencia para aprovechar las **anotaciones de tipos** de funciones para obtener mejor soporte en el editor y herramientas, y aún así obtener el **filtrado de datos** de FastAPI.
{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *}
Con esto, obtenemos soporte de las herramientas, de los editores y mypy ya que este código es correcto en términos de tipos, pero también obtenemos el filtrado de datos de FastAPI.
¿Cómo funciona esto? Vamos a echarle un vistazo. 🤓
### Anotaciones de Tipos y Herramientas
Primero vamos a ver cómo los editores, mypy y otras herramientas verían esto.
`BaseUser` tiene los campos base. Luego `UserIn` hereda de `BaseUser` y añade el campo `password`, por lo que incluirá todos los campos de ambos modelos.
Anotamos el tipo de retorno de la función como `BaseUser`, pero en realidad estamos devolviendo una instancia de `UserIn`.
El editor, mypy y otras herramientas no se quejarán de esto porque, en términos de tipificación, `UserIn` es una subclase de `BaseUser`, lo que significa que es un tipo *válido* cuando se espera algo que es un `BaseUser`.
### Filtrado de Datos en FastAPI
Ahora, para FastAPI, verá el tipo de retorno y se asegurará de que lo que devuelves incluya **solo** los campos que están declarados en el tipo.
FastAPI realiza varias cosas internamente con Pydantic para asegurarse de que esas mismas reglas de herencia de clases no se utilicen para el filtrado de datos devueltos, de lo contrario, podrías terminar devolviendo muchos más datos de los que esperabas.
De esta manera, puedes obtener lo mejor de ambos mundos: anotaciones de tipos con **soporte de herramientas** y **filtrado de datos**.
## Verlo en la documentación
Cuando veas la documentación automática, puedes verificar que el modelo de entrada y el modelo de salida tendrán cada uno su propio JSON Schema:
<img src="/img/tutorial/response-model/image01.png">
Y ambos modelos se utilizarán para la documentación interactiva de la API:
<img src="/img/tutorial/response-model/image02.png">
## Otras Anotaciones de Tipos de Retorno
Podría haber casos en los que devuelvas algo que no es un campo válido de Pydantic y lo anotes en la función, solo para obtener el soporte proporcionado por las herramientas (el editor, mypy, etc).
### Devolver un Response Directamente
El caso más común sería [devolver un Response directamente como se explica más adelante en la documentación avanzada](../advanced/response-directly.md){.internal-link target=_blank}.
{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
Este caso simple es manejado automáticamente por FastAPI porque la anotación del tipo de retorno es la clase (o una subclase de) `Response`.
Y las herramientas también estarán felices porque tanto `RedirectResponse` como `JSONResponse` son subclases de `Response`, por lo que la anotación del tipo es correcta.
### Anotar una Subclase de Response
También puedes usar una subclase de `Response` en la anotación del tipo:
{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
Esto también funcionará porque `RedirectResponse` es una subclase de `Response`, y FastAPI manejará automáticamente este caso simple.
### Anotaciones de Tipos de Retorno Inválidas
Pero cuando devuelves algún otro objeto arbitrario que no es un tipo válido de Pydantic (por ejemplo, un objeto de base de datos) y lo anotas así en la función, FastAPI intentará crear un modelo de response de Pydantic a partir de esa anotación de tipo, y fallará.
Lo mismo sucedería si tuvieras algo como un <abbr title='Una unión entre múltiples tipos significa "cualquiera de estos tipos".'>union</abbr> entre diferentes tipos donde uno o más de ellos no son tipos válidos de Pydantic, por ejemplo esto fallaría 💥:
{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
...esto falla porque la anotación de tipo no es un tipo de Pydantic y no es solo una sola clase `Response` o subclase, es una unión (cualquiera de los dos) entre una `Response` y un `dict`.
### Desactivar el Modelo de Response
Continuando con el ejemplo anterior, puede que no quieras tener la validación de datos por defecto, documentación, filtrado, etc. que realiza FastAPI.
Pero puedes querer mantener la anotación del tipo de retorno en la función para obtener el soporte de herramientas como editores y verificadores de tipos (por ejemplo, mypy).
En este caso, puedes desactivar la generación del modelo de response configurando `response_model=None`:
{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
Esto hará que FastAPI omita la generación del modelo de response y de esa manera puedes tener cualquier anotación de tipo de retorno que necesites sin que afecte a tu aplicación FastAPI. 🤓
## Parámetros de codificación del Modelo de Response
Tu modelo de response podría tener valores por defecto, como:
{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
* `description: Union[str, None] = None` (o `str | None = None` en Python 3.10) tiene un valor por defecto de `None`.
* `tax: float = 10.5` tiene un valor por defecto de `10.5`.
* `tags: List[str] = []` tiene un valor por defecto de una lista vacía: `[]`.
pero podrías querer omitirlos del resultado si no fueron en realidad almacenados.
Por ejemplo, si tienes modelos con muchos atributos opcionales en una base de datos NoSQL, pero no quieres enviar responses JSON muy largos llenos de valores por defecto.
### Usa el parámetro `response_model_exclude_unset`
Puedes configurar el parámetro del decorador de path operation `response_model_exclude_unset=True`:
{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
y esos valores por defecto no serán incluidos en el response, solo los valores realmente establecidos.
Entonces, si envías un request a esa *path operation* para el ítem con ID `foo`, el response (no incluyendo valores por defecto) será:
```JSON
{
"name": "Foo",
"price": 50.2
}
```
/// info | Información
En Pydantic v1 el método se llamaba `.dict()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_dump()`.
Los ejemplos aquí usan `.dict()` para compatibilidad con Pydantic v1, pero deberías usar `.model_dump()` en su lugar si puedes usar Pydantic v2.
///
/// info | Información
FastAPI usa el método `.dict()` del modelo de Pydantic con <a href="https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict" class="external-link" target="_blank">su parámetro `exclude_unset`</a> para lograr esto.
///
/// info | Información
También puedes usar:
* `response_model_exclude_defaults=True`
* `response_model_exclude_none=True`
como se describe en <a href="https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict" class="external-link" target="_blank">la documentación de Pydantic</a> para `exclude_defaults` y `exclude_none`.
///
#### Datos con valores para campos con valores por defecto
Pero si tus datos tienen valores para los campos del modelo con valores por defecto, como el artículo con ID `bar`:
```Python hl_lines="3 5"
{
"name": "Bar",
"description": "The bartenders",
"price": 62,
"tax": 20.2
}
```
serán incluidos en el response.
#### Datos con los mismos valores que los valores por defecto
Si los datos tienen los mismos valores que los valores por defecto, como el artículo con ID `baz`:
```Python hl_lines="3 5-6"
{
"name": "Baz",
"description": None,
"price": 50.2,
"tax": 10.5,
"tags": []
}
```
FastAPI es lo suficientemente inteligente (de hecho, Pydantic es lo suficientemente inteligente) para darse cuenta de que, a pesar de que `description`, `tax` y `tags` tienen los mismos valores que los valores por defecto, fueron establecidos explícitamente (en lugar de tomados de los valores por defecto).
Por lo tanto, se incluirán en el response JSON.
/// tip | Consejo
Ten en cuenta que los valores por defecto pueden ser cualquier cosa, no solo `None`.
Pueden ser una lista (`[]`), un `float` de `10.5`, etc.
///
### `response_model_include` y `response_model_exclude`
También puedes usar los parámetros del decorador de path operation `response_model_include` y `response_model_exclude`.
Aceptan un `set` de `str` con el nombre de los atributos a incluir (omitiendo el resto) o excluir (incluyendo el resto).
Esto se puede usar como un atajo rápido si solo tienes un modelo de Pydantic y quieres eliminar algunos datos de la salida.
/// tip | Consejo
Pero todavía se recomienda usar las ideas anteriores, usando múltiples clases, en lugar de estos parámetros.
Esto se debe a que el JSON Schema generado en el OpenAPI de tu aplicación (y la documentación) aún será el del modelo completo, incluso si usas `response_model_include` o `response_model_exclude` para omitir algunos atributos.
Esto también se aplica a `response_model_by_alias` que funciona de manera similar.
///
{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *}
/// tip | Consejo
La sintaxis `{"name", "description"}` crea un `set` con esos dos valores.
Es equivalente a `set(["name", "description"])`.
///
#### Usar `list`s en lugar de `set`s
Si olvidas usar un `set` y usas un `list` o `tuple` en su lugar, FastAPI todavía lo convertirá a un `set` y funcionará correctamente:
{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}
## Resumen
Usa el parámetro `response_model` del *decorador de path operation* para definir modelos de response y especialmente para asegurarte de que los datos privados sean filtrados.
Usa `response_model_exclude_unset` para devolver solo los valores establecidos explícitamente.

101
docs/es/docs/tutorial/response-status-code.md Normal file
View File

@@ -0,0 +1,101 @@
# Código de Estado del Response
De la misma manera que puedes especificar un modelo de response, también puedes declarar el código de estado HTTP usado para el response con el parámetro `status_code` en cualquiera de las *path operations*:
* `@app.get()`
* `@app.post()`
* `@app.put()`
* `@app.delete()`
* etc.
{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
/// note | Nota
Observa que `status_code` es un parámetro del método "decorador" (`get`, `post`, etc). No de tu *path operation function*, como todos los parámetros y body.
///
El parámetro `status_code` recibe un número con el código de estado HTTP.
/// info | Información
`status_code` también puede recibir un `IntEnum`, como por ejemplo el <a href="https://docs.python.org/3/library/http.html#http.HTTPStatus" class="external-link" target="_blank">`http.HTTPStatus`</a> de Python.
///
Esto hará:
* Devolver ese código de estado en el response.
* Documentarlo como tal en el esquema de OpenAPI (y por lo tanto, en las interfaces de usuario):
<img src="/img/tutorial/response-status-code/image01.png">
/// note | Nota
Algunos códigos de response (ver la siguiente sección) indican que el response no tiene un body.
FastAPI sabe esto, y producirá documentación OpenAPI que establece que no hay un response body.
///
## Acerca de los códigos de estado HTTP
/// note | Nota
Si ya sabes qué son los códigos de estado HTTP, salta a la siguiente sección.
///
En HTTP, envías un código de estado numérico de 3 dígitos como parte del response.
Estos códigos de estado tienen un nombre asociado para reconocerlos, pero la parte importante es el número.
En breve:
* `100` y superiores son para "Información". Rara vez los usas directamente. Los responses con estos códigos de estado no pueden tener un body.
* **`200`** y superiores son para responses "Exitosos". Estos son los que usarías más.
* `200` es el código de estado por defecto, lo que significa que todo estaba "OK".
* Otro ejemplo sería `201`, "Created". Comúnmente se usa después de crear un nuevo registro en la base de datos.
* Un caso especial es `204`, "No Content". Este response se usa cuando no hay contenido para devolver al cliente, por lo tanto, el response no debe tener un body.
* **`300`** y superiores son para "Redirección". Los responses con estos códigos de estado pueden o no tener un body, excepto `304`, "Not Modified", que no debe tener uno.
* **`400`** y superiores son para responses de "Error del Cliente". Este es el segundo tipo que probablemente más usarías.
* Un ejemplo es `404`, para un response "Not Found".
* Para errores genéricos del cliente, puedes usar simplemente `400`.
* `500` y superiores son para errores del servidor. Casi nunca los usas directamente. Cuando algo sale mal en alguna parte de tu código de aplicación, o del servidor, automáticamente devolverá uno de estos códigos de estado.
/// tip | Consejo
Para saber más sobre cada código de estado y qué código es para qué, revisa la <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" class="external-link" target="_blank">documentación de <abbr title="Mozilla Developer Network">MDN</abbr> sobre códigos de estado HTTP</a>.
///
## Atajo para recordar los nombres
Veamos de nuevo el ejemplo anterior:
{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
`201` es el código de estado para "Created".
Pero no tienes que memorizar lo que significa cada uno de estos códigos.
Puedes usar las variables de conveniencia de `fastapi.status`.
{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
Son solo una conveniencia, mantienen el mismo número, pero de esa manera puedes usar el autocompletado del editor para encontrarlos:
<img src="/img/tutorial/response-status-code/image02.png">
/// note | Nota Técnica
También podrías usar `from starlette import status`.
**FastAPI** proporciona el mismo `starlette.status` como `fastapi.status` solo como una conveniencia para ti, el desarrollador. Pero proviene directamente de Starlette.
///
## Cambiando el valor por defecto
Más adelante, en la [Guía de Usuario Avanzada](../advanced/response-change-status-code.md){.internal-link target=_blank}, verás cómo devolver un código de estado diferente al valor por defecto que estás declarando aquí.

224
docs/es/docs/tutorial/schema-extra-example.md Normal file
View File

@@ -0,0 +1,224 @@
# Declarar Ejemplos de Request
Puedes declarar ejemplos de los datos que tu aplicación puede recibir.
Aquí tienes varias formas de hacerlo.
## Datos extra de JSON Schema en modelos de Pydantic
Puedes declarar `examples` para un modelo de Pydantic que se añadirá al JSON Schema generado.
//// tab | Pydantic v2
{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}
////
//// tab | Pydantic v1
{* ../../docs_src/schema_extra_example/tutorial001_pv1_py310.py hl[13:23] *}
////
Esa información extra se añadirá tal cual al **JSON Schema** generado para ese modelo, y se usará en la documentación de la API.
//// tab | Pydantic v2
En Pydantic versión 2, usarías el atributo `model_config`, que toma un `dict` como se describe en <a href="https://docs.pydantic.dev/latest/api/config/" class="external-link" target="_blank">la documentación de Pydantic: Configuración</a>.
Puedes establecer `"json_schema_extra"` con un `dict` que contenga cualquier dato adicional que desees que aparezca en el JSON Schema generado, incluyendo `examples`.
////
//// tab | Pydantic v1
En Pydantic versión 1, usarías una clase interna `Config` y `schema_extra`, como se describe en <a href="https://docs.pydantic.dev/1.10/usage/schema/#schema-customization" class="external-link" target="_blank">la documentación de Pydantic: Personalización de Esquema</a>.
Puedes establecer `schema_extra` con un `dict` que contenga cualquier dato adicional que desees que aparezca en el JSON Schema generado, incluyendo `examples`.
////
/// tip | Consejo
Podrías usar la misma técnica para extender el JSON Schema y añadir tu propia información extra personalizada.
Por ejemplo, podrías usarlo para añadir metadatos para una interfaz de usuario frontend, etc.
///
/// info | Información
OpenAPI 3.1.0 (usado desde FastAPI 0.99.0) añadió soporte para `examples`, que es parte del estándar de **JSON Schema**.
Antes de eso, solo soportaba la palabra clave `example` con un solo ejemplo. Eso aún es soportado por OpenAPI 3.1.0, pero está obsoleto y no es parte del estándar de JSON Schema. Así que se recomienda migrar de `example` a `examples`. 🤓
Puedes leer más al final de esta página.
///
## Argumentos adicionales en `Field`
Cuando usas `Field()` con modelos de Pydantic, también puedes declarar `examples` adicionales:
{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
## `examples` en JSON Schema - OpenAPI
Cuando usas cualquiera de:
* `Path()`
* `Query()`
* `Header()`
* `Cookie()`
* `Body()`
* `Form()`
* `File()`
también puedes declarar un grupo de `examples` con información adicional que se añadirá a sus **JSON Schemas** dentro de **OpenAPI**.
### `Body` con `examples`
Aquí pasamos `examples` que contiene un ejemplo de los datos esperados en `Body()`:
{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
### Ejemplo en la interfaz de documentación
Con cualquiera de los métodos anteriores se vería así en los `/docs`:
<img src="/img/tutorial/body-fields/image01.png">
### `Body` con múltiples `examples`
Por supuesto, también puedes pasar múltiples `examples`:
{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
Cuando haces esto, los ejemplos serán parte del **JSON Schema** interno para esos datos de body.
Sin embargo, al <abbr title="2023-08-26">momento de escribir esto</abbr>, Swagger UI, la herramienta encargada de mostrar la interfaz de documentación, no soporta mostrar múltiples ejemplos para los datos en **JSON Schema**. Pero lee más abajo para una solución alternativa.
### `examples` específicos de OpenAPI
Desde antes de que **JSON Schema** soportara `examples`, OpenAPI tenía soporte para un campo diferente también llamado `examples`.
Estos `examples` específicos de **OpenAPI** van en otra sección en la especificación de OpenAPI. Van en los **detalles para cada *path operation***, no dentro de cada JSON Schema.
Y Swagger UI ha soportado este campo particular de `examples` por un tiempo. Así que, puedes usarlo para **mostrar** diferentes **ejemplos en la interfaz de documentación**.
La forma de este campo específico de OpenAPI `examples` es un `dict` con **múltiples ejemplos** (en lugar de una `list`), cada uno con información adicional que también se añadirá a **OpenAPI**.
Esto no va dentro de cada JSON Schema contenido en OpenAPI, esto va afuera, directamente en la *path operation*.
### Usando el Parámetro `openapi_examples`
Puedes declarar los `examples` específicos de OpenAPI en FastAPI con el parámetro `openapi_examples` para:
* `Path()`
* `Query()`
* `Header()`
* `Cookie()`
* `Body()`
* `Form()`
* `File()`
Las claves del `dict` identifican cada ejemplo, y cada valor es otro `dict`.
Cada `dict` específico del ejemplo en los `examples` puede contener:
* `summary`: Descripción corta del ejemplo.
* `description`: Una descripción larga que puede contener texto Markdown.
* `value`: Este es el ejemplo real mostrado, e.g. un `dict`.
* `externalValue`: alternativa a `value`, una URL que apunta al ejemplo. Aunque esto puede no ser soportado por tantas herramientas como `value`.
Puedes usarlo así:
{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
### Ejemplos de OpenAPI en la Interfaz de Documentación
Con `openapi_examples` añadido a `Body()`, los `/docs` se verían así:
<img src="/img/tutorial/body-fields/image02.png">
## Detalles Técnicos
/// tip | Consejo
Si ya estás usando la versión **0.99.0 o superior** de **FastAPI**, probablemente puedes **omitir** estos detalles.
Son más relevantes para versiones más antiguas, antes de que OpenAPI 3.1.0 estuviera disponible.
Puedes considerar esto una breve lección de **historia** de OpenAPI y JSON Schema. 🤓
///
/// warning | Advertencia
Estos son detalles muy técnicos sobre los estándares **JSON Schema** y **OpenAPI**.
Si las ideas anteriores ya funcionan para ti, eso podría ser suficiente, y probablemente no necesites estos detalles, siéntete libre de omitirlos.
///
Antes de OpenAPI 3.1.0, OpenAPI usaba una versión más antigua y modificada de **JSON Schema**.
JSON Schema no tenía `examples`, así que OpenAPI añadió su propio campo `example` a su versión modificada.
OpenAPI también añadió los campos `example` y `examples` a otras partes de la especificación:
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object" class="external-link" target="_blank">`Parameter Object` (en la especificación)</a> que era usado por FastAPI:
* `Path()`
* `Query()`
* `Header()`
* `Cookie()`
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object" class="external-link" target="_blank">`Request Body Object`, en el campo `content`, sobre el `Media Type Object` (en la especificación)</a> que era usado por FastAPI:
* `Body()`
* `File()`
* `Form()`
/// info | Información
Este viejo parámetro `examples` específico de OpenAPI ahora es `openapi_examples` desde FastAPI `0.103.0`.
///
### Campo `examples` de JSON Schema
Pero luego JSON Schema añadió un <a href="https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5" class="external-link" target="_blank">campo `examples`</a> a una nueva versión de la especificación.
Y entonces el nuevo OpenAPI 3.1.0 se basó en la última versión (JSON Schema 2020-12) que incluía este nuevo campo `examples`.
Y ahora este nuevo campo `examples` tiene precedencia sobre el viejo campo único (y personalizado) `example`, que ahora está obsoleto.
Este nuevo campo `examples` en JSON Schema es **solo una `list`** de ejemplos, no un dict con metadatos adicionales como en los otros lugares en OpenAPI (descritos arriba).
/// info | Información
Incluso después de que OpenAPI 3.1.0 fue lanzado con esta nueva integración más sencilla con JSON Schema, por un tiempo, Swagger UI, la herramienta que proporciona la documentación automática, no soportaba OpenAPI 3.1.0 (lo hace desde la versión 5.0.0 🎉).
Debido a eso, las versiones de FastAPI anteriores a 0.99.0 todavía usaban versiones de OpenAPI menores a 3.1.0.
///
### `examples` de Pydantic y FastAPI
Cuando añades `examples` dentro de un modelo de Pydantic, usando `schema_extra` o `Field(examples=["algo"])`, ese ejemplo se añade al **JSON Schema** para ese modelo de Pydantic.
Y ese **JSON Schema** del modelo de Pydantic se incluye en el **OpenAPI** de tu API, y luego se usa en la interfaz de documentación.
En las versiones de FastAPI antes de 0.99.0 (0.99.0 y superior usan el nuevo OpenAPI 3.1.0) cuando usabas `example` o `examples` con cualquiera de las otras utilidades (`Query()`, `Body()`, etc.) esos ejemplos no se añadían al JSON Schema que describe esos datos (ni siquiera a la propia versión de JSON Schema de OpenAPI), se añadían directamente a la declaración de la *path operation* en OpenAPI (fuera de las partes de OpenAPI que usan JSON Schema).
Pero ahora que FastAPI 0.99.0 y superiores usa OpenAPI 3.1.0, que usa JSON Schema 2020-12, y Swagger UI 5.0.0 y superiores, todo es más consistente y los ejemplos se incluyen en JSON Schema.
### Swagger UI y `examples` específicos de OpenAPI
Ahora, como Swagger UI no soportaba múltiples ejemplos de JSON Schema (a fecha de 2023-08-26), los usuarios no tenían una forma de mostrar múltiples ejemplos en los documentos.
Para resolver eso, FastAPI `0.103.0` **añadió soporte** para declarar el mismo viejo campo **específico de OpenAPI** `examples` con el nuevo parámetro `openapi_examples`. 🤓
### Resumen
Solía decir que no me gustaba mucho la historia... y mírame ahora dando lecciones de "historia tecnológica". 😅
En resumen, **actualiza a FastAPI 0.99.0 o superior**, y las cosas son mucho **más simples, consistentes e intuitivas**, y no necesitas conocer todos estos detalles históricos. 😎

203
docs/es/docs/tutorial/security/first-steps.md Normal file
View File

@@ -0,0 +1,203 @@
# Seguridad - Primeros pasos
Imaginemos que tienes tu API de **backend** en algún dominio.
Y tienes un **frontend** en otro dominio o en un path diferente del mismo dominio (o en una aplicación móvil).
Y quieres tener una forma para que el frontend se autentique con el backend, usando un **username** y **password**.
Podemos usar **OAuth2** para construir eso con **FastAPI**.
Pero vamos a ahorrarte el tiempo de leer la larga especificación completa solo para encontrar esos pequeños fragmentos de información que necesitas.
Usemos las herramientas proporcionadas por **FastAPI** para manejar la seguridad.
## Cómo se ve
Primero solo usemos el código y veamos cómo funciona, y luego volveremos para entender qué está sucediendo.
## Crea `main.py`
Copia el ejemplo en un archivo `main.py`:
{* ../../docs_src/security/tutorial001_an_py39.py *}
## Ejecútalo
/// info | Información
El paquete <a href="https://github.com/Kludex/python-multipart" class="external-link" target="_blank">`python-multipart`</a> se instala automáticamente con **FastAPI** cuando ejecutas el comando `pip install "fastapi[standard]"`.
Sin embargo, si usas el comando `pip install fastapi`, el paquete `python-multipart` no se incluye por defecto.
Para instalarlo manualmente, asegúrate de crear un [entorno virtual](../../virtual-environments.md){.internal-link target=_blank}, activarlo, y luego instalarlo con:
```console
$ pip install python-multipart
```
Esto se debe a que **OAuth2** utiliza "form data" para enviar el `username` y `password`.
///
Ejecuta el ejemplo con:
<div class="termy">
```console
$ fastapi dev main.py
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
## Revisa
Ve a la documentación interactiva en: <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
Verás algo así:
<img src="/img/tutorial/security/image01.png">
/// check | ¡Botón de autorización!
Ya tienes un nuevo y brillante botón de "Authorize".
Y tu *path operation* tiene un pequeño candado en la esquina superior derecha que puedes pulsar.
///
Y si lo haces, tendrás un pequeño formulario de autorización para escribir un `username` y `password` (y otros campos opcionales):
<img src="/img/tutorial/security/image02.png">
/// note | Nota
No importa lo que escribas en el formulario, aún no funcionará. Pero llegaremos allí.
///
Esto por supuesto no es el frontend para los usuarios finales, pero es una gran herramienta automática para documentar interactivamente toda tu API.
Puede ser utilizada por el equipo de frontend (que también puedes ser tú mismo).
Puede ser utilizada por aplicaciones y sistemas de terceros.
Y también puede ser utilizada por ti mismo, para depurar, revisar y probar la misma aplicación.
## El flujo `password`
Ahora retrocedamos un poco y entendamos qué es todo eso.
El "flujo" `password` es una de las formas ("flujos") definidas en OAuth2, para manejar la seguridad y la autenticación.
OAuth2 fue diseñado para que el backend o la API pudieran ser independientes del servidor que autentica al usuario.
Pero en este caso, la misma aplicación de **FastAPI** manejará la API y la autenticación.
Así que, revisémoslo desde ese punto de vista simplificado:
* El usuario escribe el `username` y `password` en el frontend, y presiona `Enter`.
* El frontend (ejecutándose en el navegador del usuario) envía ese `username` y `password` a una URL específica en nuestra API (declarada con `tokenUrl="token"`).
* La API verifica ese `username` y `password`, y responde con un "token" (no hemos implementado nada de esto aún).
* Un "token" es solo un string con algún contenido que podemos usar luego para verificar a este usuario.
* Normalmente, un token se establece para que expire después de algún tiempo.
* Así que, el usuario tendrá que volver a iniciar sesión más adelante.
* Y si el token es robado, el riesgo es menor. No es como una llave permanente que funcionará para siempre (en la mayoría de los casos).
* El frontend almacena temporalmente ese token en algún lugar.
* El usuario hace clic en el frontend para ir a otra sección de la aplicación web frontend.
* El frontend necesita obtener más datos de la API.
* Pero necesita autenticación para ese endpoint específico.
* Así que, para autenticarse con nuestra API, envía un `header` `Authorization` con un valor de `Bearer ` más el token.
* Si el token contiene `foobar`, el contenido del `header` `Authorization` sería: `Bearer foobar`.
## `OAuth2PasswordBearer` de **FastAPI**
**FastAPI** proporciona varias herramientas, en diferentes niveles de abstracción, para implementar estas funcionalidades de seguridad.
En este ejemplo vamos a usar **OAuth2**, con el flujo **Password**, usando un token **Bearer**. Hacemos eso utilizando la clase `OAuth2PasswordBearer`.
/// info | Información
Un token "bearer" no es la única opción.
Pero es la mejor para nuestro caso de uso.
Y podría ser la mejor para la mayoría de los casos de uso, a menos que seas un experto en OAuth2 y sepas exactamente por qué hay otra opción que se adapta mejor a tus necesidades.
En ese caso, **FastAPI** también te proporciona las herramientas para construirlo.
///
Cuando creamos una instance de la clase `OAuth2PasswordBearer` pasamos el parámetro `tokenUrl`. Este parámetro contiene la URL que el cliente (el frontend corriendo en el navegador del usuario) usará para enviar el `username` y `password` a fin de obtener un token.
{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
/// tip | Consejo
Aquí `tokenUrl="token"` se refiere a una URL relativa `token` que aún no hemos creado. Como es una URL relativa, es equivalente a `./token`.
Porque estamos usando una URL relativa, si tu API estuviera ubicada en `https://example.com/`, entonces se referiría a `https://example.com/token`. Pero si tu API estuviera ubicada en `https://example.com/api/v1/`, entonces se referiría a `https://example.com/api/v1/token`.
Usar una URL relativa es importante para asegurarse de que tu aplicación siga funcionando incluso en un caso de uso avanzado como [Detrás de un Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
///
Este parámetro no crea ese endpoint / *path operation*, pero declara que la URL `/token` será la que el cliente deberá usar para obtener el token. Esa información se usa en OpenAPI, y luego en los sistemas de documentación interactiva del API.
Pronto también crearemos la verdadera *path operation*.
/// info | Información
Si eres un "Pythonista" muy estricto, tal vez no te guste el estilo del nombre del parámetro `tokenUrl` en lugar de `token_url`.
Eso es porque está usando el mismo nombre que en la especificación de OpenAPI. Para que si necesitas investigar más sobre cualquiera de estos esquemas de seguridad, puedas simplemente copiarlo y pegarlo para encontrar más información al respecto.
///
La variable `oauth2_scheme` es una instance de `OAuth2PasswordBearer`, pero también es un "callable".
Podría ser llamada como:
```Python
oauth2_scheme(some, parameters)
```
Así que, puede usarse con `Depends`.
### Úsalo
Ahora puedes pasar ese `oauth2_scheme` en una dependencia con `Depends`.
{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
Esta dependencia proporcionará un `str` que se asigna al parámetro `token` de la *path operation function*.
**FastAPI** sabrá que puede usar esta dependencia para definir un "security scheme" en el esquema OpenAPI (y en los docs automáticos del API).
/// info | Detalles técnicos
**FastAPI** sabrá que puede usar la clase `OAuth2PasswordBearer` (declarada en una dependencia) para definir el esquema de seguridad en OpenAPI porque hereda de `fastapi.security.oauth2.OAuth2`, que a su vez hereda de `fastapi.security.base.SecurityBase`.
Todas las utilidades de seguridad que se integran con OpenAPI (y los docs automáticos del API) heredan de `SecurityBase`, así es como **FastAPI** puede saber cómo integrarlas en OpenAPI.
///
## Lo que hace
Irá y buscará en el request ese header `Authorization`, verificará si el valor es `Bearer ` más algún token, y devolverá el token como un `str`.
Si no ve un header `Authorization`, o el valor no tiene un token `Bearer `, responderá directamente con un error de código de estado 401 (`UNAUTHORIZED`).
Ni siquiera tienes que verificar si el token existe para devolver un error. Puedes estar seguro de que si tu función se ejecuta, tendrá un `str` en ese token.
Puedes probarlo ya en los docs interactivos:
<img src="/img/tutorial/security/image03.png">
Todavía no estamos verificando la validez del token, pero ya es un comienzo.
## Resumen
Así que, en solo 3 o 4 líneas adicionales, ya tienes alguna forma primitiva de seguridad.

103
docs/es/docs/tutorial/security/get-current-user.md Normal file
View File

@@ -0,0 +1,103 @@
# Obtener Usuario Actual
En el capítulo anterior, el sistema de seguridad (que se basa en el sistema de inyección de dependencias) le estaba dando a la *path operation function* un `token` como un `str`:
{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
Pero eso aún no es tan útil. Vamos a hacer que nos dé el usuario actual.
## Crear un modelo de usuario
Primero, vamos a crear un modelo de usuario con Pydantic.
De la misma manera que usamos Pydantic para declarar cuerpos, podemos usarlo en cualquier otra parte:
{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
## Crear una dependencia `get_current_user`
Vamos a crear una dependencia `get_current_user`.
¿Recuerdas que las dependencias pueden tener sub-dependencias?
`get_current_user` tendrá una dependencia con el mismo `oauth2_scheme` que creamos antes.
De la misma manera que estábamos haciendo antes en la *path operation* directamente, nuestra nueva dependencia `get_current_user` recibirá un `token` como un `str` de la sub-dependencia `oauth2_scheme`:
{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
## Obtener el usuario
`get_current_user` usará una función de utilidad (falsa) que creamos, que toma un token como un `str` y devuelve nuestro modelo de Pydantic `User`:
{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
## Inyectar al usuario actual
Entonces ahora podemos usar el mismo `Depends` con nuestro `get_current_user` en la *path operation*:
{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
Ten en cuenta que declaramos el tipo de `current_user` como el modelo de Pydantic `User`.
Esto nos ayudará dentro de la función con todo el autocompletado y chequeo de tipos.
/// tip | Consejo
Tal vez recuerdes que los cuerpos de request también se declaran con modelos de Pydantic.
Aquí **FastAPI** no se confundirá porque estás usando `Depends`.
///
/// check | Revisa
El modo en que este sistema de dependencias está diseñado nos permite tener diferentes dependencias (diferentes "dependables") que todas devuelven un modelo `User`.
No estamos restringidos a tener solo una dependencia que pueda devolver ese tipo de datos.
///
## Otros modelos
Ahora puedes obtener el usuario actual directamente en las *path operation functions* y manejar los mecanismos de seguridad a nivel de **Dependency Injection**, usando `Depends`.
Y puedes usar cualquier modelo o datos para los requisitos de seguridad (en este caso, un modelo de Pydantic `User`).
Pero no estás limitado a usar algún modelo de datos, clase o tipo específico.
¿Quieres tener un `id` y `email` y no tener un `username` en tu modelo? Claro. Puedes usar estas mismas herramientas.
¿Quieres solo tener un `str`? ¿O solo un `dict`? ¿O un instance de clase modelo de base de datos directamente? Todo funciona de la misma manera.
¿En realidad no tienes usuarios que inicien sesión en tu aplicación sino robots, bots u otros sistemas, que solo tienen un token de acceso? Una vez más, todo funciona igual.
Usa cualquier tipo de modelo, cualquier tipo de clase, cualquier tipo de base de datos que necesites para tu aplicación. **FastAPI** te cubre con el sistema de inyección de dependencias.
## Tamaño del código
Este ejemplo podría parecer extenso. Ten en cuenta que estamos mezclando seguridad, modelos de datos, funciones de utilidad y *path operations* en el mismo archivo.
Pero aquí está el punto clave.
El tema de seguridad e inyección de dependencias se escribe una vez.
Y puedes hacerlo tan complejo como desees. Y aún así, tenerlo escrito solo una vez, en un solo lugar. Con toda la flexibilidad.
Pero puedes tener miles de endpoints (*path operations*) usando el mismo sistema de seguridad.
Y todos ellos (o cualquier porción de ellos que quieras) pueden aprovechar la reutilización de estas dependencias o cualquier otra dependencia que crees.
Y todas estas miles de *path operations* pueden ser tan pequeñas como 3 líneas:
{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
## Resumen
Ahora puedes obtener el usuario actual directamente en tu *path operation function*.
Ya estamos a mitad de camino.
Solo necesitamos agregar una *path operation* para que el usuario/cliente envíe realmente el `username` y `password`.
Eso es lo que viene a continuación.

105
docs/es/docs/tutorial/security/index.md Normal file
View File

@@ -0,0 +1,105 @@
# Seguridad
Hay muchas formas de manejar la seguridad, autenticación y autorización.
Y normalmente es un tema complejo y "difícil".
En muchos frameworks y sistemas, solo manejar la seguridad y autenticación requiere una gran cantidad de esfuerzo y código (en muchos casos puede ser el 50% o más de todo el código escrito).
**FastAPI** proporciona varias herramientas para ayudarte a manejar la **Seguridad** de manera fácil, rápida y estándar, sin tener que estudiar y aprender todas las especificaciones de seguridad.
Pero primero, vamos a revisar algunos pequeños conceptos.
## ¿Con prisa?
Si no te importan ninguno de estos términos y solo necesitas agregar seguridad con autenticación basada en nombre de usuario y contraseña *ahora mismo*, salta a los siguientes capítulos.
## OAuth2
OAuth2 es una especificación que define varias maneras de manejar la autenticación y autorización.
Es una especificación bastante extensa y cubre varios casos de uso complejos.
Incluye formas de autenticarse usando un "tercero".
Eso es lo que todos los sistemas con "iniciar sesión con Facebook, Google, Twitter, GitHub" utilizan internamente.
### OAuth 1
Hubo un OAuth 1, que es muy diferente de OAuth2, y más complejo, ya que incluía especificaciones directas sobre cómo encriptar la comunicación.
No es muy popular o usado hoy en día.
OAuth2 no especifica cómo encriptar la comunicación, espera que tengas tu aplicación servida con HTTPS.
/// tip | Consejo
En la sección sobre **deployment** verás cómo configurar HTTPS de forma gratuita, usando Traefik y Let's Encrypt.
///
## OpenID Connect
OpenID Connect es otra especificación, basada en **OAuth2**.
Solo extiende OAuth2 especificando algunas cosas que son relativamente ambiguas en OAuth2, para intentar hacerla más interoperable.
Por ejemplo, el login de Google usa OpenID Connect (que internamente usa OAuth2).
Pero el login de Facebook no soporta OpenID Connect. Tiene su propia versión de OAuth2.
### OpenID (no "OpenID Connect")
Hubo también una especificación "OpenID". Que intentaba resolver lo mismo que **OpenID Connect**, pero no estaba basada en OAuth2.
Entonces, era un sistema completo adicional.
No es muy popular o usado hoy en día.
## OpenAPI
OpenAPI (anteriormente conocido como Swagger) es la especificación abierta para construir APIs (ahora parte de la Linux Foundation).
**FastAPI** se basa en **OpenAPI**.
Eso es lo que hace posible tener múltiples interfaces de documentación interactiva automática, generación de código, etc.
OpenAPI tiene una forma de definir múltiples "esquemas" de seguridad.
Al usarlos, puedes aprovechar todas estas herramientas basadas en estándares, incluidos estos sistemas de documentación interactiva.
OpenAPI define los siguientes esquemas de seguridad:
* `apiKey`: una clave específica de la aplicación que puede provenir de:
* Un parámetro de query.
* Un header.
* Una cookie.
* `http`: sistemas de autenticación HTTP estándar, incluyendo:
* `bearer`: un header `Authorization` con un valor de `Bearer ` más un token. Esto se hereda de OAuth2.
* Autenticación básica HTTP.
* Digest HTTP, etc.
* `oauth2`: todas las formas de OAuth2 para manejar la seguridad (llamadas "flujos").
* Varios de estos flujos son apropiados para construir un proveedor de autenticación OAuth 2.0 (como Google, Facebook, Twitter, GitHub, etc.):
* `implicit`
* `clientCredentials`
* `authorizationCode`
* Pero hay un "flujo" específico que puede usarse perfectamente para manejar la autenticación directamente en la misma aplicación:
* `password`: algunos de los próximos capítulos cubrirán ejemplos de esto.
* `openIdConnect`: tiene una forma de definir cómo descubrir automáticamente los datos de autenticación OAuth2.
* Este descubrimiento automático es lo que se define en la especificación de OpenID Connect.
/// tip | Consejo
Integrar otros proveedores de autenticación/autorización como Google, Facebook, Twitter, GitHub, etc. también es posible y relativamente fácil.
El problema más complejo es construir un proveedor de autenticación/autorización como esos, pero **FastAPI** te da las herramientas para hacerlo fácilmente, mientras hace el trabajo pesado por ti.
///
## Utilidades de **FastAPI**
FastAPI proporciona varias herramientas para cada uno de estos esquemas de seguridad en el módulo `fastapi.security` que simplifican el uso de estos mecanismos de seguridad.
En los siguientes capítulos verás cómo agregar seguridad a tu API usando esas herramientas proporcionadas por **FastAPI**.
Y también verás cómo se integra automáticamente en el sistema de documentación interactiva.

273
docs/es/docs/tutorial/security/oauth2-jwt.md Normal file
View File

@@ -0,0 +1,273 @@
# OAuth2 con Password (y hashing), Bearer con tokens JWT
Ahora que tenemos todo el flujo de seguridad, hagamos que la aplicación sea realmente segura, usando tokens <abbr title="JSON Web Tokens">JWT</abbr> y hashing de contraseñas seguras.
Este código es algo que puedes usar realmente en tu aplicación, guardar los hashes de las contraseñas en tu base de datos, etc.
Vamos a empezar desde donde lo dejamos en el capítulo anterior e incrementarlo.
## Acerca de JWT
JWT significa "JSON Web Tokens".
Es un estándar para codificar un objeto JSON en un string largo y denso sin espacios. Se ve así:
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```
No está encriptado, por lo que cualquiera podría recuperar la información de los contenidos.
Pero está firmado. Así que, cuando recibes un token que has emitido, puedes verificar que realmente lo emitiste.
De esta manera, puedes crear un token con una expiración de, digamos, 1 semana. Y luego, cuando el usuario regresa al día siguiente con el token, sabes que el usuario todavía está registrado en tu sistema.
Después de una semana, el token estará expirado y el usuario no estará autorizado y tendrá que iniciar sesión nuevamente para obtener un nuevo token. Y si el usuario (o un tercero) intenta modificar el token para cambiar la expiración, podrás descubrirlo, porque las firmas no coincidirían.
Si quieres jugar con tokens JWT y ver cómo funcionan, revisa <a href="https://jwt.io/" class="external-link" target="_blank">https://jwt.io</a>.
## Instalar `PyJWT`
Necesitamos instalar `PyJWT` para generar y verificar los tokens JWT en Python.
Asegúrate de crear un [entorno virtual](../../virtual-environments.md){.internal-link target=_blank}, activarlo y luego instalar `pyjwt`:
<div class="termy">
```console
$ pip install pyjwt
---> 100%
```
</div>
/// info | Información
Si planeas usar algoritmos de firma digital como RSA o ECDSA, deberías instalar la dependencia del paquete de criptografía `pyjwt[crypto]`.
Puedes leer más al respecto en la <a href="https://pyjwt.readthedocs.io/en/latest/installation.html" class="external-link" target="_blank">documentación de instalación de PyJWT</a>.
///
## Hashing de contraseñas
"Hacer hashing" significa convertir algún contenido (una contraseña en este caso) en una secuencia de bytes (solo un string) que parece un galimatías.
Siempre que pases exactamente el mismo contenido (exactamente la misma contraseña) obtienes exactamente el mismo galimatías.
Pero no puedes convertir del galimatías de nuevo a la contraseña.
### Por qué usar hashing de contraseñas
Si tu base de datos es robada, el ladrón no tendrá las contraseñas en texto claro de tus usuarios, solo los hashes.
Por lo tanto, el ladrón no podrá intentar usar esa contraseña en otro sistema (como muchos usuarios usan la misma contraseña en todas partes, esto sería peligroso).
## Instalar `passlib`
PassLib es un gran paquete de Python para manejar hashes de contraseñas.
Soporta muchos algoritmos de hashing seguros y utilidades para trabajar con ellos.
El algoritmo recomendado es "Bcrypt".
Asegúrate de crear un [entorno virtual](../../virtual-environments.md){.internal-link target=_blank}, activarlo y luego instalar PassLib con Bcrypt:
<div class="termy">
```console
$ pip install "passlib[bcrypt]"
---> 100%
```
</div>
/// tip | Consejo
Con `passlib`, incluso podrías configurarlo para poder leer contraseñas creadas por **Django**, un plug-in de seguridad de **Flask** u otros muchos.
Así, podrías, por ejemplo, compartir los mismos datos de una aplicación de Django en una base de datos con una aplicación de FastAPI. O migrar gradualmente una aplicación de Django usando la misma base de datos.
Y tus usuarios podrían iniciar sesión desde tu aplicación Django o desde tu aplicación **FastAPI**, al mismo tiempo.
///
## Hash y verificación de contraseñas
Importa las herramientas que necesitamos de `passlib`.
Crea un "contexto" de PassLib. Este es el que se usará para hacer el hash y verificar las contraseñas.
/// tip | Consejo
El contexto de PassLib también tiene funcionalidad para usar diferentes algoritmos de hashing, incluidos los antiguos obsoletos solo para permitir verificarlos, etc.
Por ejemplo, podrías usarlo para leer y verificar contraseñas generadas por otro sistema (como Django) pero hacer hash de cualquier contraseña nueva con un algoritmo diferente como Bcrypt.
Y ser compatible con todos ellos al mismo tiempo.
///
Crea una función de utilidad para hacer el hash de una contraseña que venga del usuario.
Y otra utilidad para verificar si una contraseña recibida coincide con el hash almacenado.
Y otra más para autenticar y devolver un usuario.
{* ../../docs_src/security/tutorial004_an_py310.py hl[8,49,56:57,60:61,70:76] *}
/// note | Nota
Si revisas la nueva (falsa) base de datos `fake_users_db`, verás cómo se ve ahora la contraseña con hash: `"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`.
///
## Manejo de tokens JWT
Importa los módulos instalados.
Crea una clave secreta aleatoria que se usará para firmar los tokens JWT.
Para generar una clave secreta segura al azar usa el comando:
<div class="termy">
```console
$ openssl rand -hex 32
09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7
```
</div>
Y copia el resultado a la variable `SECRET_KEY` (no uses la del ejemplo).
Crea una variable `ALGORITHM` con el algoritmo usado para firmar el token JWT y configúralo a `"HS256"`.
Crea una variable para la expiración del token.
Define un Modelo de Pydantic que se usará en el endpoint de token para el response.
Crea una función de utilidad para generar un nuevo token de acceso.
{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *}
## Actualizar las dependencias
Actualiza `get_current_user` para recibir el mismo token que antes, pero esta vez, usando tokens JWT.
Decodifica el token recibido, verifícalo y devuelve el usuario actual.
Si el token es inválido, devuelve un error HTTP de inmediato.
{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *}
## Actualizar la *path operation* `/token`
Crea un `timedelta` con el tiempo de expiración del token.
Crea un verdadero token de acceso JWT y devuélvelo.
{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *}
### Detalles técnicos sobre el "sujeto" `sub` de JWT
La especificación de JWT dice que hay una clave `sub`, con el sujeto del token.
Es opcional usarlo, pero ahí es donde pondrías la identificación del usuario, por lo que lo estamos usando aquí.
JWT podría ser usado para otras cosas aparte de identificar un usuario y permitirle realizar operaciones directamente en tu API.
Por ejemplo, podrías identificar un "coche" o un "artículo de blog".
Luego, podrías agregar permisos sobre esa entidad, como "conducir" (para el coche) o "editar" (para el blog).
Y luego, podrías darle ese token JWT a un usuario (o bot), y ellos podrían usarlo para realizar esas acciones (conducir el coche, o editar el artículo del blog) sin siquiera necesitar tener una cuenta, solo con el token JWT que tu API generó para eso.
Usando estas ideas, JWT puede ser utilizado para escenarios mucho más sofisticados.
En esos casos, varias de esas entidades podrían tener el mismo ID, digamos `foo` (un usuario `foo`, un coche `foo`, y un artículo del blog `foo`).
Entonces, para evitar colisiones de ID, cuando crees el token JWT para el usuario, podrías prefijar el valor de la clave `sub`, por ejemplo, con `username:`. Así, en este ejemplo, el valor de `sub` podría haber sido: `username:johndoe`.
Lo importante a tener en cuenta es que la clave `sub` debería tener un identificador único a lo largo de toda la aplicación, y debería ser un string.
## Revisa
Ejecuta el servidor y ve a la documentación: <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
Verás la interfaz de usuario como:
<img src="/img/tutorial/security/image07.png">
Autoriza la aplicación de la misma manera que antes.
Usando las credenciales:
Usuario: `johndoe`
Contraseña: `secret`
/// check | Revisa
Observa que en ninguna parte del código está la contraseña en texto claro "`secret`", solo tenemos la versión con hash.
///
<img src="/img/tutorial/security/image08.png">
Llama al endpoint `/users/me/`, obtendrás el response como:
```JSON
{
"username": "johndoe",
"email": "johndoe@example.com",
"full_name": "John Doe",
"disabled": false
}
```
<img src="/img/tutorial/security/image09.png">
Si abres las herramientas de desarrollador, podrías ver cómo los datos enviados solo incluyen el token, la contraseña solo se envía en la primera petición para autenticar al usuario y obtener ese token de acceso, pero no después:
<img src="/img/tutorial/security/image10.png">
/// note | Nota
Observa el header `Authorization`, con un valor que comienza con `Bearer `.
///
## Uso avanzado con `scopes`
OAuth2 tiene la noción de "scopes".
Puedes usarlos para agregar un conjunto específico de permisos a un token JWT.
Luego, puedes darle este token directamente a un usuario o a un tercero, para interactuar con tu API con un conjunto de restricciones.
Puedes aprender cómo usarlos y cómo están integrados en **FastAPI** más adelante en la **Guía de Usuario Avanzada**.
## Resumen
Con lo que has visto hasta ahora, puedes configurar una aplicación **FastAPI** segura usando estándares como OAuth2 y JWT.
En casi cualquier framework el manejo de la seguridad se convierte en un tema bastante complejo rápidamente.
Muchos paquetes que lo simplifican tienen que hacer muchos compromisos con el modelo de datos, la base de datos y las funcionalidades disponibles. Y algunos de estos paquetes que simplifican las cosas demasiado en realidad tienen fallos de seguridad en el fondo.
---
**FastAPI** no hace ningún compromiso con ninguna base de datos, modelo de datos o herramienta.
Te da toda la flexibilidad para elegir aquellas que se ajusten mejor a tu proyecto.
Y puedes usar directamente muchos paquetes bien mantenidos y ampliamente usados como `passlib` y `PyJWT`, porque **FastAPI** no requiere mecanismos complejos para integrar paquetes externos.
Pero te proporciona las herramientas para simplificar el proceso tanto como sea posible sin comprometer la flexibilidad, la robustez o la seguridad.
Y puedes usar e implementar protocolos seguros y estándar, como OAuth2 de una manera relativamente simple.
Puedes aprender más en la **Guía de Usuario Avanzada** sobre cómo usar "scopes" de OAuth2, para un sistema de permisos más detallado, siguiendo estos mismos estándares. OAuth2 con scopes es el mecanismo utilizado por muchos grandes proveedores de autenticación, como Facebook, Google, GitHub, Microsoft, Twitter, etc. para autorizar aplicaciones de terceros para interactuar con sus APIs en nombre de sus usuarios.

289
docs/es/docs/tutorial/security/simple-oauth2.md Normal file
View File

@@ -0,0 +1,289 @@
# Simple OAuth2 con Password y Bearer
Ahora vamos a construir a partir del capítulo anterior y agregar las partes faltantes para tener un flujo de seguridad completo.
## Obtener el `username` y `password`
Vamos a usar las utilidades de seguridad de **FastAPI** para obtener el `username` y `password`.
OAuth2 especifica que cuando se utiliza el "password flow" (que estamos usando), el cliente/usuario debe enviar campos `username` y `password` como form data.
Y la especificación dice que los campos deben llamarse así. Por lo que `user-name` o `email` no funcionarían.
Pero no te preocupes, puedes mostrarlo como quieras a tus usuarios finales en el frontend.
Y tus modelos de base de datos pueden usar cualquier otro nombre que desees.
Pero para la *path operation* de inicio de sesión, necesitamos usar estos nombres para ser compatibles con la especificación (y poder, por ejemplo, utilizar el sistema de documentación integrada de la API).
La especificación también establece que el `username` y `password` deben enviarse como form data (por lo que no hay JSON aquí).
### `scope`
La especificación también indica que el cliente puede enviar otro campo del formulario llamado "`scope`".
El nombre del campo del formulario es `scope` (en singular), pero en realidad es un string largo con "scopes" separados por espacios.
Cada "scope" es simplemente un string (sin espacios).
Normalmente se utilizan para declarar permisos de seguridad específicos, por ejemplo:
* `users:read` o `users:write` son ejemplos comunes.
* `instagram_basic` es usado por Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` es usado por Google.
/// info | Información
En OAuth2 un "scope" es solo un string que declara un permiso específico requerido.
No importa si tiene otros caracteres como `:` o si es una URL.
Esos detalles son específicos de la implementación.
Para OAuth2 son solo strings.
///
## Código para obtener el `username` y `password`
Ahora vamos a usar las utilidades proporcionadas por **FastAPI** para manejar esto.
### `OAuth2PasswordRequestForm`
Primero, importa `OAuth2PasswordRequestForm`, y úsalo como una dependencia con `Depends` en la *path operation* para `/token`:
{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
`OAuth2PasswordRequestForm` es una dependencia de clase que declara un body de formulario con:
* El `username`.
* El `password`.
* Un campo opcional `scope` como un string grande, compuesto por strings separados por espacios.
* Un `grant_type` opcional.
/// tip | Consejo
La especificación de OAuth2 en realidad *requiere* un campo `grant_type` con un valor fijo de `password`, pero `OAuth2PasswordRequestForm` no lo obliga.
Si necesitas imponerlo, utiliza `OAuth2PasswordRequestFormStrict` en lugar de `OAuth2PasswordRequestForm`.
///
* Un `client_id` opcional (no lo necesitamos para nuestro ejemplo).
* Un `client_secret` opcional (no lo necesitamos para nuestro ejemplo).
/// info | Información
`OAuth2PasswordRequestForm` no es una clase especial para **FastAPI** como lo es `OAuth2PasswordBearer`.
`OAuth2PasswordBearer` hace que **FastAPI** sepa que es un esquema de seguridad. Así que se añade de esa manera a OpenAPI.
Pero `OAuth2PasswordRequestForm` es solo una dependencia de clase que podrías haber escrito tú mismo, o podrías haber declarado parámetros de `Form` directamente.
Pero como es un caso de uso común, se proporciona directamente por **FastAPI**, solo para facilitarlo.
///
### Usa el form data
/// tip | Consejo
La instance de la clase de dependencia `OAuth2PasswordRequestForm` no tendrá un atributo `scope` con el string largo separado por espacios, en su lugar, tendrá un atributo `scopes` con la lista real de strings para cada scope enviado.
No estamos usando `scopes` en este ejemplo, pero la funcionalidad está ahí si la necesitas.
///
Ahora, obtén los datos del usuario desde la base de datos (falsa), usando el `username` del campo del form.
Si no existe tal usuario, devolvemos un error diciendo "Incorrect username or password".
Para el error, usamos la excepción `HTTPException`:
{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
### Revisa el password
En este punto tenemos los datos del usuario de nuestra base de datos, pero no hemos revisado el password.
Primero pongamos esos datos en el modelo `UserInDB` de Pydantic.
Nunca deberías guardar passwords en texto plano, así que, usaremos el sistema de hash de passwords (falso).
Si los passwords no coinciden, devolvemos el mismo error.
#### Hashing de passwords
"Hacer hash" significa: convertir algún contenido (un password en este caso) en una secuencia de bytes (solo un string) que parece un galimatías.
Siempre que pases exactamente el mismo contenido (exactamente el mismo password) obtienes exactamente el mismo galimatías.
Pero no puedes convertir del galimatías al password.
##### Por qué usar hashing de passwords
Si tu base de datos es robada, el ladrón no tendrá los passwords en texto plano de tus usuarios, solo los hashes.
Entonces, el ladrón no podrá intentar usar esos mismos passwords en otro sistema (como muchos usuarios usan el mismo password en todas partes, esto sería peligroso).
{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
#### Sobre `**user_dict`
`UserInDB(**user_dict)` significa:
*Pasa las claves y valores de `user_dict` directamente como argumentos clave-valor, equivalente a:*
```Python
UserInDB(
username = user_dict["username"],
email = user_dict["email"],
full_name = user_dict["full_name"],
disabled = user_dict["disabled"],
hashed_password = user_dict["hashed_password"],
)
```
/// info | Información
Para una explicación más completa de `**user_dict` revisa en [la documentación para **Extra Models**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
///
## Devolver el token
El response del endpoint `token` debe ser un objeto JSON.
Debe tener un `token_type`. En nuestro caso, como estamos usando tokens "Bearer", el tipo de token debe ser "`bearer`".
Y debe tener un `access_token`, con un string que contenga nuestro token de acceso.
Para este ejemplo simple, vamos a ser completamente inseguros y devolver el mismo `username` como el token.
/// tip | Consejo
En el próximo capítulo, verás una implementación segura real, con hashing de passwords y tokens <abbr title="JSON Web Tokens">JWT</abbr>.
Pero por ahora, enfoquémonos en los detalles específicos que necesitamos.
///
{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
/// tip | Consejo
De acuerdo con la especificación, deberías devolver un JSON con un `access_token` y un `token_type`, igual que en este ejemplo.
Esto es algo que tienes que hacer tú mismo en tu código, y asegurarte de usar esas claves JSON.
Es casi lo único que tienes que recordar hacer correctamente tú mismo, para ser compatible con las especificaciones.
Para el resto, **FastAPI** lo maneja por ti.
///
## Actualizar las dependencias
Ahora vamos a actualizar nuestras dependencias.
Queremos obtener el `current_user` *solo* si este usuario está activo.
Entonces, creamos una dependencia adicional `get_current_active_user` que a su vez utiliza `get_current_user` como dependencia.
Ambas dependencias solo devolverán un error HTTP si el usuario no existe, o si está inactivo.
Así que, en nuestro endpoint, solo obtendremos un usuario si el usuario existe, fue autenticado correctamente, y está activo:
{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
/// info | Información
El header adicional `WWW-Authenticate` con el valor `Bearer` que estamos devolviendo aquí también es parte de la especificación.
Cualquier código de estado HTTP (error) 401 "UNAUTHORIZED" se supone que también debe devolver un header `WWW-Authenticate`.
En el caso de tokens bearer (nuestro caso), el valor de ese header debe ser `Bearer`.
De hecho, puedes omitir ese header extra y aún funcionaría.
Pero se proporciona aquí para cumplir con las especificaciones.
Además, podría haber herramientas que lo esperen y lo usen (ahora o en el futuro) y eso podría ser útil para ti o tus usuarios, ahora o en el futuro.
Ese es el beneficio de los estándares...
///
## Verlo en acción
Abre la documentación interactiva: <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
### Autenticar
Haz clic en el botón "Authorize".
Usa las credenciales:
Usuario: `johndoe`
Contraseña: `secret`
<img src="/img/tutorial/security/image04.png">
Después de autenticarte en el sistema, lo verás así:
<img src="/img/tutorial/security/image05.png">
### Obtener tus propios datos de usuario
Ahora usa la operación `GET` con la path `/users/me`.
Obtendrás los datos de tu usuario, como:
```JSON
{
"username": "johndoe",
"email": "johndoe@example.com",
"full_name": "John Doe",
"disabled": false,
"hashed_password": "fakehashedsecret"
}
```
<img src="/img/tutorial/security/image06.png">
Si haces clic en el icono de candado y cierras sesión, y luego intentas la misma operación nuevamente, obtendrás un error HTTP 401 de:
```JSON
{
"detail": "Not authenticated"
}
```
### Usuario inactivo
Ahora prueba con un usuario inactivo, autentícate con:
Usuario: `alice`
Contraseña: `secret2`
Y trata de usar la operación `GET` con la path `/users/me`.
Obtendrás un error de "Usuario inactivo", como:
```JSON
{
"detail": "Inactive user"
}
```
## Recapitulación
Ahora tienes las herramientas para implementar un sistema de seguridad completo basado en `username` y `password` para tu API.
Usando estas herramientas, puedes hacer que el sistema de seguridad sea compatible con cualquier base de datos y con cualquier modelo de usuario o de datos.
El único detalle que falta es que en realidad no es "seguro" aún.
En el próximo capítulo verás cómo usar un paquete de hashing de passwords seguro y tokens <abbr title="JSON Web Tokens">JWT</abbr>.

360
docs/es/docs/tutorial/sql-databases.md Normal file
View File

@@ -0,0 +1,360 @@
# Bases de Datos SQL (Relacionales)
**FastAPI** no requiere que uses una base de datos SQL (relacional). Pero puedes utilizar **cualquier base de datos** que desees.
Aquí veremos un ejemplo usando <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">SQLModel</a>.
**SQLModel** está construido sobre <a href="https://www.sqlalchemy.org/" class="external-link" target="_blank">SQLAlchemy</a> y Pydantic. Fue creado por el mismo autor de **FastAPI** para ser la combinación perfecta para aplicaciones de FastAPI que necesiten usar **bases de datos SQL**.
/// tip | Consejo
Puedes usar cualquier otro paquete de bases de datos SQL o NoSQL que quieras (en algunos casos llamadas <abbr title="Object Relational Mapper, un término elegante para un paquete donde algunas clases representan tablas SQL y las instances representan filas en esas tablas">"ORMs"</abbr>), FastAPI no te obliga a usar nada. 😎
///
Como SQLModel se basa en SQLAlchemy, puedes usar fácilmente **cualquier base de datos soportada** por SQLAlchemy (lo que las hace también soportadas por SQLModel), como:
* PostgreSQL
* MySQL
* SQLite
* Oracle
* Microsoft SQL Server, etc.
En este ejemplo, usaremos **SQLite**, porque utiliza un solo archivo y Python tiene soporte integrado. Así que puedes copiar este ejemplo y ejecutarlo tal cual.
Más adelante, para tu aplicación en producción, es posible que desees usar un servidor de base de datos como **PostgreSQL**.
/// tip | Consejo
Hay un generador de proyectos oficial con **FastAPI** y **PostgreSQL** que incluye un frontend y más herramientas: <a href="https://github.com/fastapi/full-stack-fastapi-template" class="external-link" target="_blank">https://github.com/fastapi/full-stack-fastapi-template</a>
///
Este es un tutorial muy simple y corto, si deseas aprender sobre bases de datos en general, sobre SQL o más funcionalidades avanzadas, ve a la <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">documentación de SQLModel</a>.
## Instalar `SQLModel`
Primero, asegúrate de crear tu [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, actívalo, y luego instala `sqlmodel`:
<div class="termy">
```console
$ pip install sqlmodel
---> 100%
```
</div>
## Crear la App con un Solo Modelo
Primero crearemos la versión más simple de la aplicación con un solo modelo de **SQLModel**.
Más adelante la mejoraremos aumentando la seguridad y versatilidad con **múltiples modelos** a continuación. 🤓
### Crear Modelos
Importa `SQLModel` y crea un modelo de base de datos:
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[1:11] hl[7:11] *}
La clase `Hero` es muy similar a un modelo de Pydantic (de hecho, en el fondo, realmente *es un modelo de Pydantic*).
Hay algunas diferencias:
* `table=True` le dice a SQLModel que este es un *modelo de tabla*, que debe representar una **tabla** en la base de datos SQL, no es solo un *modelo de datos* (como lo sería cualquier otra clase regular de Pydantic).
* `Field(primary_key=True)` le dice a SQLModel que `id` es la **clave primaria** en la base de datos SQL (puedes aprender más sobre claves primarias de SQL en la documentación de SQLModel).
Al tener el tipo como `int | None`, SQLModel sabrá que esta columna debe ser un `INTEGER` en la base de datos SQL y que debe ser `NULLABLE`.
* `Field(index=True)` le dice a SQLModel que debe crear un **índice SQL** para esta columna, lo que permitirá búsquedas más rápidas en la base de datos cuando se lean datos filtrados por esta columna.
SQLModel sabrá que algo declarado como `str` será una columna SQL de tipo `TEXT` (o `VARCHAR`, dependiendo de la base de datos).
### Crear un Engine
Un `engine` de SQLModel (en el fondo, realmente es un `engine` de SQLAlchemy) es lo que **mantiene las conexiones** a la base de datos.
Tendrías **un solo objeto `engine`** para todo tu código para conectar a la misma base de datos.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[14:18] hl[14:15,17:18] *}
Usar `check_same_thread=False` permite a FastAPI usar la misma base de datos SQLite en diferentes hilos. Esto es necesario ya que **una sola request** podría usar **más de un hilo** (por ejemplo, en dependencias).
No te preocupes, con la forma en que está estructurado el código, nos aseguraremos de usar **una sola *session* de SQLModel por request** más adelante, esto es realmente lo que intenta lograr el `check_same_thread`.
### Crear las Tablas
Luego añadimos una función que usa `SQLModel.metadata.create_all(engine)` para **crear las tablas** para todos los *modelos de tabla*.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[21:22] hl[21:22] *}
### Crear una Dependencia de Session
Una **`Session`** es lo que almacena los **objetos en memoria** y lleva un seguimiento de cualquier cambio necesario en los datos, luego **usa el `engine`** para comunicarse con la base de datos.
Crearemos una **dependencia de FastAPI** con `yield` que proporcionará una nueva `Session` para cada request. Esto es lo que asegura que usemos una sola session por request. 🤓
Luego creamos una dependencia `Annotated` `SessionDep` para simplificar el resto del código que usará esta dependencia.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *}
### Crear Tablas de Base de Datos al Arrancar
Crearemos las tablas de la base de datos cuando arranque la aplicación.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[32:37] hl[35:37] *}
Aquí creamos las tablas en un evento de inicio de la aplicación.
Para producción probablemente usarías un script de migración que se ejecuta antes de iniciar tu aplicación. 🤓
/// tip | Consejo
SQLModel tendrá utilidades de migración envolviendo Alembic, pero por ahora, puedes usar <a href="https://alembic.sqlalchemy.org/en/latest/" class="external-link" target="_blank">Alembic</a> directamente.
///
### Crear un Hero
Debido a que cada modelo de SQLModel también es un modelo de Pydantic, puedes usarlo en las mismas **anotaciones de tipos** que podrías usar en modelos de Pydantic.
Por ejemplo, si declaras un parámetro de tipo `Hero`, será leído desde el **JSON body**.
De la misma manera, puedes declararlo como el **tipo de retorno** de la función, y luego la forma de los datos aparecerá en la interfaz automática de documentación de la API.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[40:45] hl[40:45] *}
</details>
Aquí usamos la dependencia `SessionDep` (una `Session`) para añadir el nuevo `Hero` a la instance `Session`, comiteamos los cambios a la base de datos, refrescamos los datos en el `hero` y luego lo devolvemos.
### Leer Heroes
Podemos **leer** `Hero`s de la base de datos usando un `select()`. Podemos incluir un `limit` y `offset` para paginar los resultados.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[48:55] hl[51:52,54] *}
### Leer Un Hero
Podemos **leer** un único `Hero`.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[58:63] hl[60] *}
### Eliminar un Hero
También podemos **eliminar** un `Hero`.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[66:73] hl[71] *}
### Ejecutar la App
Puedes ejecutar la aplicación:
<div class="termy">
```console
$ fastapi dev main.py
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
Luego dirígete a la interfaz de `/docs`, verás que **FastAPI** está usando estos **modelos** para **documentar** la API, y los usará para **serializar** y **validar** los datos también.
<div class="screenshot">
<img src="/img/tutorial/sql-databases/image01.png">
</div>
## Actualizar la App con Múltiples Modelos
Ahora vamos a **refactorizar** un poco esta aplicación para aumentar la **seguridad** y la **versatilidad**.
Si revisas la aplicación anterior, en la interfaz verás que, hasta ahora, permite al cliente decidir el `id` del `Hero` a crear. 😱
No deberíamos permitir que eso suceda, podrían sobrescribir un `id` que ya tenemos asignado en la base de datos. Decidir el `id` debería ser tarea del **backend** o la **base de datos**, **no del cliente**.
Además, creamos un `secret_name` para el héroe, pero hasta ahora, lo estamos devolviendo en todas partes, eso no es muy **secreto**... 😅
Arreglaremos estas cosas añadiendo unos **modelos extra**. Aquí es donde SQLModel brillará. ✨
### Crear Múltiples Modelos
En **SQLModel**, cualquier clase de modelo que tenga `table=True` es un **modelo de tabla**.
Y cualquier clase de modelo que no tenga `table=True` es un **modelo de datos**, estos son en realidad solo modelos de Pydantic (con un par de características extra pequeñas). 🤓
Con SQLModel, podemos usar **herencia** para **evitar duplicar** todos los campos en todos los casos.
#### `HeroBase` - la clase base
Comencemos con un modelo `HeroBase` que tiene todos los **campos que son compartidos** por todos los modelos:
* `name`
* `age`
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:9] hl[7:9] *}
#### `Hero` - el *modelo de tabla*
Luego, crearemos `Hero`, el *modelo de tabla* real, con los **campos extra** que no siempre están en los otros modelos:
* `id`
* `secret_name`
Debido a que `Hero` hereda de `HeroBase`, **también** tiene los **campos** declarados en `HeroBase`, por lo que todos los campos para `Hero` son:
* `id`
* `name`
* `age`
* `secret_name`
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:14] hl[12:14] *}
#### `HeroPublic` - el *modelo de datos* público
A continuación, creamos un modelo `HeroPublic`, este es el que será **devuelto** a los clientes de la API.
Tiene los mismos campos que `HeroBase`, por lo que no incluirá `secret_name`.
Por fin, la identidad de nuestros héroes está protegida! 🥷
También vuelve a declarar `id: int`. Al hacer esto, estamos haciendo un **contrato** con los clientes de la API, para que siempre puedan esperar que el `id` esté allí y sea un `int` (nunca será `None`).
/// tip | Consejo
Tener el modelo de retorno asegurando que un valor siempre esté disponible y siempre sea `int` (no `None`) es muy útil para los clientes de la API, pueden escribir código mucho más simple teniendo esta certeza.
Además, los **clientes generados automáticamente** tendrán interfaces más simples, para que los desarrolladores que se comuniquen con tu API puedan tener una experiencia mucho mejor trabajando con tu API. 😎
///
Todos los campos en `HeroPublic` son los mismos que en `HeroBase`, con `id` declarado como `int` (no `None`):
* `id`
* `name`
* `age`
* `secret_name`
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:18] hl[17:18] *}
#### `HeroCreate` - el *modelo de datos* para crear un héroe
Ahora creamos un modelo `HeroCreate`, este es el que **validará** los datos de los clientes.
Tiene los mismos campos que `HeroBase`, y también tiene `secret_name`.
Ahora, cuando los clientes **crean un nuevo héroe**, enviarán el `secret_name`, se almacenará en la base de datos, pero esos nombres secretos no se devolverán en la API a los clientes.
/// tip | Consejo
Esta es la forma en la que manejarías **contraseñas**. Recíbelas, pero no las devuelvas en la API.
También **hashea** los valores de las contraseñas antes de almacenarlos, **nunca los almacenes en texto plano**.
///
Los campos de `HeroCreate` son:
* `name`
* `age`
* `secret_name`
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:22] hl[21:22] *}
#### `HeroUpdate` - el *modelo de datos* para actualizar un héroe
No teníamos una forma de **actualizar un héroe** en la versión anterior de la aplicación, pero ahora con **múltiples modelos**, podemos hacerlo. 🎉
El *modelo de datos* `HeroUpdate` es algo especial, tiene **todos los mismos campos** que serían necesarios para crear un nuevo héroe, pero todos los campos son **opcionales** (todos tienen un valor por defecto). De esta forma, cuando actualices un héroe, puedes enviar solo los campos que deseas actualizar.
Debido a que todos los **campos realmente cambian** (el tipo ahora incluye `None` y ahora tienen un valor por defecto de `None`), necesitamos **volver a declararlos**.
Realmente no necesitamos heredar de `HeroBase` porque estamos volviendo a declarar todos los campos. Lo dejaré heredando solo por consistencia, pero esto no es necesario. Es más una cuestión de gusto personal. 🤷
Los campos de `HeroUpdate` son:
* `name`
* `age`
* `secret_name`
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:28] hl[25:28] *}
### Crear con `HeroCreate` y devolver un `HeroPublic`
Ahora que tenemos **múltiples modelos**, podemos actualizar las partes de la aplicación que los usan.
Recibimos en la request un *modelo de datos* `HeroCreate`, y a partir de él, creamos un *modelo de tabla* `Hero`.
Este nuevo *modelo de tabla* `Hero` tendrá los campos enviados por el cliente, y también tendrá un `id` generado por la base de datos.
Luego devolvemos el mismo *modelo de tabla* `Hero` tal cual desde la función. Pero como declaramos el `response_model` con el *modelo de datos* `HeroPublic`, **FastAPI** usará `HeroPublic` para validar y serializar los datos.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[56:62] hl[56:58] *}
/// tip | Consejo
Ahora usamos `response_model=HeroPublic` en lugar de la **anotación de tipo de retorno** `-> HeroPublic` porque el valor que estamos devolviendo en realidad *no* es un `HeroPublic`.
Si hubiéramos declarado `-> HeroPublic`, tu editor y linter se quejarían (con razón) de que estás devolviendo un `Hero` en lugar de un `HeroPublic`.
Al declararlo en `response_model` le estamos diciendo a **FastAPI** que haga lo suyo, sin interferir con las anotaciones de tipo y la ayuda de tu editor y otras herramientas.
///
### Leer Heroes con `HeroPublic`
Podemos hacer lo mismo que antes para **leer** `Hero`s, nuevamente, usamos `response_model=list[HeroPublic]` para asegurar que los datos se validen y serialicen correctamente.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[65:72] hl[65] *}
### Leer Un Hero con `HeroPublic`
Podemos **leer** un único héroe:
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[75:80] hl[77] *}
### Actualizar un Hero con `HeroUpdate`
Podemos **actualizar un héroe**. Para esto usamos una operación HTTP `PATCH`.
Y en el código, obtenemos un `dict` con todos los datos enviados por el cliente, **solo los datos enviados por el cliente**, excluyendo cualquier valor que estaría allí solo por ser valores por defecto. Para hacerlo usamos `exclude_unset=True`. Este es el truco principal. 🪄
Luego usamos `hero_db.sqlmodel_update(hero_data)` para actualizar el `hero_db` con los datos de `hero_data`.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[83:93] hl[83:84,88:89] *}
### Eliminar un Hero de Nuevo
**Eliminar** un héroe se mantiene prácticamente igual.
No satisfaremos el deseo de refactorizar todo en este punto. 😅
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[96:103] hl[101] *}
### Ejecutar la App de Nuevo
Puedes ejecutar la aplicación de nuevo:
<div class="termy">
```console
$ fastapi dev main.py
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
Si vas a la interfaz de `/docs` de la API, verás que ahora está actualizada, y no esperará recibir el `id` del cliente al crear un héroe, etc.
<div class="screenshot">
<img src="/img/tutorial/sql-databases/image02.png">
</div>
## Resumen
Puedes usar <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">**SQLModel**</a> para interactuar con una base de datos SQL y simplificar el código con *modelos de datos* y *modelos de tablas*.
Puedes aprender mucho más en la documentación de **SQLModel**, hay un mini <a href="https://sqlmodel.tiangolo.com/tutorial/fastapi/" class="external-link" target="_blank">tutorial sobre el uso de SQLModel con **FastAPI**</a>. 🚀

40
docs/es/docs/tutorial/static-files.md Normal file
View File

@@ -0,0 +1,40 @@
# Archivos Estáticos
Puedes servir archivos estáticos automáticamente desde un directorio utilizando `StaticFiles`.
## Usa `StaticFiles`
* Importa `StaticFiles`.
* "Monta" una instance de `StaticFiles()` en un path específico.
{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
/// note | Detalles Técnicos
También podrías usar `from starlette.staticfiles import StaticFiles`.
**FastAPI** proporciona el mismo `starlette.staticfiles` como `fastapi.staticfiles` solo como una conveniencia para ti, el desarrollador. Pero en realidad viene directamente de Starlette.
///
### Qué es "Montar"
"Montar" significa agregar una aplicación completa "independiente" en un path específico, que luego se encargará de manejar todos los sub-paths.
Esto es diferente a usar un `APIRouter`, ya que una aplicación montada es completamente independiente. El OpenAPI y la documentación de tu aplicación principal no incluirán nada de la aplicación montada, etc.
Puedes leer más sobre esto en la [Guía de Usuario Avanzada](../advanced/index.md){.internal-link target=_blank}.
## Detalles
El primer `"/static"` se refiere al sub-path en el que esta "sub-aplicación" será "montada". Por lo tanto, cualquier path que comience con `"/static"` será manejado por ella.
El `directory="static"` se refiere al nombre del directorio que contiene tus archivos estáticos.
El `name="static"` le da un nombre que puede ser utilizado internamente por **FastAPI**.
Todos estos parámetros pueden ser diferentes a "`static`", ajústalos según las necesidades y detalles específicos de tu propia aplicación.
## Más info
Para más detalles y opciones revisa <a href="https://www.starlette.io/staticfiles/" class="external-link" target="_blank">la documentación de Starlette sobre Archivos Estáticos</a>.

240
docs/es/docs/tutorial/testing.md Normal file
View File

@@ -0,0 +1,240 @@
# Testing
Gracias a <a href="https://www.starlette.io/testclient/" class="external-link" target="_blank">Starlette</a>, escribir pruebas para aplicaciones de **FastAPI** es fácil y agradable.
Está basado en <a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPX</a>, que a su vez está diseñado basado en Requests, por lo que es muy familiar e intuitivo.
Con él, puedes usar <a href="https://docs.pytest.org/" class="external-link" target="_blank">pytest</a> directamente con **FastAPI**.
## Usando `TestClient`
/// info | Información
Para usar `TestClient`, primero instala <a href="https://www.python-httpx.org" class="external-link" target="_blank">`httpx`</a>.
Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo y luego instalarlo, por ejemplo:
```console
$ pip install httpx
```
///
Importa `TestClient`.
Crea un `TestClient` pasándole tu aplicación de **FastAPI**.
Crea funciones con un nombre que comience con `test_` (esta es la convención estándar de `pytest`).
Usa el objeto `TestClient` de la misma manera que con `httpx`.
Escribe declaraciones `assert` simples con las expresiones estándar de Python que necesites revisar (otra vez, estándar de `pytest`).
{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
/// tip | Consejo
Nota que las funciones de prueba son `def` normales, no `async def`.
Y las llamadas al cliente también son llamadas normales, sin usar `await`.
Esto te permite usar `pytest` directamente sin complicaciones.
///
/// note | Nota Técnica
También podrías usar `from starlette.testclient import TestClient`.
**FastAPI** proporciona el mismo `starlette.testclient` como `fastapi.testclient` solo por conveniencia para ti, el desarrollador. Pero proviene directamente de Starlette.
///
/// tip | Consejo
Si quieres llamar a funciones `async` en tus pruebas además de enviar solicitudes a tu aplicación FastAPI (por ejemplo, funciones asincrónicas de bases de datos), echa un vistazo a las [Pruebas Asincrónicas](../advanced/async-tests.md){.internal-link target=_blank} en el tutorial avanzado.
///
## Separando pruebas
En una aplicación real, probablemente tendrías tus pruebas en un archivo diferente.
Y tu aplicación de **FastAPI** también podría estar compuesta de varios archivos/módulos, etc.
### Archivo de aplicación **FastAPI**
Digamos que tienes una estructura de archivos como se describe en [Aplicaciones Más Grandes](bigger-applications.md){.internal-link target=_blank}:
```
.
├── app
│   ├── __init__.py
│   └── main.py
```
En el archivo `main.py` tienes tu aplicación de **FastAPI**:
{* ../../docs_src/app_testing/main.py *}
### Archivo de prueba
Entonces podrías tener un archivo `test_main.py` con tus pruebas. Podría estar en el mismo paquete de Python (el mismo directorio con un archivo `__init__.py`):
``` hl_lines="5"
.
├── app
│   ├── __init__.py
│   ├── main.py
│   └── test_main.py
```
Debido a que este archivo está en el mismo paquete, puedes usar importaciones relativas para importar el objeto `app` desde el módulo `main` (`main.py`):
{* ../../docs_src/app_testing/test_main.py hl[3] *}
...y tener el código para las pruebas tal como antes.
## Pruebas: ejemplo extendido
Ahora extiende este ejemplo y añade más detalles para ver cómo escribir pruebas para diferentes partes.
### Archivo de aplicación **FastAPI** extendido
Continuemos con la misma estructura de archivos que antes:
```
.
├── app
│   ├── __init__.py
│   ├── main.py
│   └── test_main.py
```
Digamos que ahora el archivo `main.py` con tu aplicación de **FastAPI** tiene algunas otras **path operations**.
Tiene una operación `GET` que podría devolver un error.
Tiene una operación `POST` que podría devolver varios errores.
Ambas *path operations* requieren un `X-Token` header.
//// tab | Python 3.10+
```Python
{!> ../../docs_src/app_testing/app_b_an_py310/main.py!}
```
////
//// tab | Python 3.9+
```Python
{!> ../../docs_src/app_testing/app_b_an_py39/main.py!}
```
////
//// tab | Python 3.8+
```Python
{!> ../../docs_src/app_testing/app_b_an/main.py!}
```
////
//// tab | Python 3.10+ sin Anotar
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python
{!> ../../docs_src/app_testing/app_b_py310/main.py!}
```
////
//// tab | Python 3.8+ sin Anotar
/// tip | Consejo
Prefiere usar la versión `Annotated` si es posible.
///
```Python
{!> ../../docs_src/app_testing/app_b/main.py!}
```
////
### Archivo de prueba extendido
Podrías entonces actualizar `test_main.py` con las pruebas extendidas:
{* ../../docs_src/app_testing/app_b/test_main.py *}
Cada vez que necesites que el cliente pase información en el request y no sepas cómo, puedes buscar (Googlear) cómo hacerlo en `httpx`, o incluso cómo hacerlo con `requests`, dado que el diseño de HTTPX está basado en el diseño de Requests.
Luego simplemente haces lo mismo en tus pruebas.
Por ejemplo:
* Para pasar un parámetro de *path* o *query*, añádelo a la URL misma.
* Para pasar un cuerpo JSON, pasa un objeto de Python (por ejemplo, un `dict`) al parámetro `json`.
* Si necesitas enviar *Form Data* en lugar de JSON, usa el parámetro `data` en su lugar.
* Para pasar *headers*, usa un `dict` en el parámetro `headers`.
* Para *cookies*, un `dict` en el parámetro `cookies`.
Para más información sobre cómo pasar datos al backend (usando `httpx` o el `TestClient`) revisa la <a href="https://www.python-httpx.org" class="external-link" target="_blank">documentación de HTTPX</a>.
/// info | Información
Ten en cuenta que el `TestClient` recibe datos que pueden ser convertidos a JSON, no modelos de Pydantic.
Si tienes un modelo de Pydantic en tu prueba y quieres enviar sus datos a la aplicación durante las pruebas, puedes usar el `jsonable_encoder` descrito en [Codificador Compatible con JSON](encoder.md){.internal-link target=_blank}.
///
## Ejecútalo
Después de eso, solo necesitas instalar `pytest`.
Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo y luego instalarlo, por ejemplo:
<div class="termy">
```console
$ pip install pytest
---> 100%
```
</div>
Detectará los archivos y pruebas automáticamente, ejecutará las mismas y te reportará los resultados.
Ejecuta las pruebas con:
<div class="termy">
```console
$ pytest
================ test session starts ================
platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1
rootdir: /home/user/code/superawesome-cli/app
plugins: forked-1.1.3, xdist-1.31.0, cov-2.8.1
collected 6 items
---> 100%
test_main.py <span style="color: green; white-space: pre;">...... [100%]</span>
<span style="color: green;">================= 1 passed in 0.03s =================</span>
```
</div>