Sync fastapi docs from b5ca1324 on 2025-12-07

docs/es/docs/about/index.md

@@ -0,0 +1,3 @@
+# Acerca de
+
+Acerca de FastAPI, su diseño, inspiración y más. 🤓

docs/es/docs/advanced/additional-responses.md

@@ -0,0 +1,247 @@
+# Responses Adicionales en OpenAPI
+
+/// warning | Advertencia
+
+Este es un tema bastante avanzado.
+
+Si estás comenzando con **FastAPI**, puede que no lo necesites.
+
+///
+
+Puedes declarar responses adicionales, con códigos de estado adicionales, media types, descripciones, etc.
+
+Esos responses adicionales se incluirán en el esquema de OpenAPI, por lo que también aparecerán en la documentación de la API.
+
+Pero para esos responses adicionales tienes que asegurarte de devolver un `Response` como `JSONResponse` directamente, con tu código de estado y contenido.
+
+## Response Adicional con `model`
+
+Puedes pasar a tus *decoradores de path operation* un parámetro `responses`.
+
+Recibe un `dict`: las claves son los códigos de estado para cada response (como `200`), y los valores son otros `dict`s con la información para cada uno de ellos.
+
+Cada uno de esos `dict`s de response puede tener una clave `model`, conteniendo un modelo de Pydantic, así como `response_model`.
+
+**FastAPI** tomará ese modelo, generará su JSON Schema y lo incluirá en el lugar correcto en OpenAPI.
+
+Por ejemplo, para declarar otro response con un código de estado `404` y un modelo Pydantic `Message`, puedes escribir:
+
+{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
+
+/// note | Nota
+
+Ten en cuenta que debes devolver el `JSONResponse` directamente.
+
+///
+
+/// info | Información
+
+La clave `model` no es parte de OpenAPI.
+
+**FastAPI** tomará el modelo de Pydantic de allí, generará el JSON Schema y lo colocará en el lugar correcto.
+
+El lugar correcto es:
+
+* En la clave `content`, que tiene como valor otro objeto JSON (`dict`) que contiene:
+  * Una clave con el media type, por ejemplo, `application/json`, que contiene como valor otro objeto JSON, que contiene:
+    * Una clave `schema`, que tiene como valor el JSON Schema del modelo, aquí es el lugar correcto.
+        * **FastAPI** agrega una referencia aquí a los JSON Schemas globales en otro lugar de tu OpenAPI en lugar de incluirlo directamente. De este modo, otras aplicaciones y clientes pueden usar esos JSON Schemas directamente, proporcionar mejores herramientas de generación de código, etc.
+
+///
+
+Los responses generadas en el OpenAPI para esta *path operation* serán:
+
+```JSON hl_lines="3-12"
+{
+    "responses": {
+        "404": {
+            "description": "Additional Response",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/Message"
+                    }
+                }
+            }
+        },
+        "200": {
+            "description": "Successful Response",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/Item"
+                    }
+                }
+            }
+        },
+        "422": {
+            "description": "Validation Error",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "$ref": "#/components/schemas/HTTPValidationError"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+Los esquemas se referencian a otro lugar dentro del esquema de OpenAPI:
+
+```JSON hl_lines="4-16"
+{
+    "components": {
+        "schemas": {
+            "Message": {
+                "title": "Message",
+                "required": [
+                    "message"
+                ],
+                "type": "object",
+                "properties": {
+                    "message": {
+                        "title": "Message",
+                        "type": "string"
+                    }
+                }
+            },
+            "Item": {
+                "title": "Item",
+                "required": [
+                    "id",
+                    "value"
+                ],
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "title": "Id",
+                        "type": "string"
+                    },
+                    "value": {
+                        "title": "Value",
+                        "type": "string"
+                    }
+                }
+            },
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": [
+                    "loc",
+                    "msg",
+                    "type"
+                ],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "msg": {
+                        "title": "Message",
+                        "type": "string"
+                    },
+                    "type": {
+                        "title": "Error Type",
+                        "type": "string"
+                    }
+                }
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/ValidationError"
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Media types adicionales para el response principal
+
+Puedes usar este mismo parámetro `responses` para agregar diferentes media type para el mismo response principal.
+
+Por ejemplo, puedes agregar un media type adicional de `image/png`, declarando que tu *path operation* puede devolver un objeto JSON (con media type `application/json`) o una imagen PNG:
+
+{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
+
+/// note | Nota
+
+Nota que debes devolver la imagen usando un `FileResponse` directamente.
+
+///
+
+/// info | Información
+
+A menos que especifiques un media type diferente explícitamente en tu parámetro `responses`, FastAPI asumirá que el response tiene el mismo media type que la clase de response principal (por defecto `application/json`).
+
+Pero si has especificado una clase de response personalizada con `None` como su media type, FastAPI usará `application/json` para cualquier response adicional que tenga un modelo asociado.
+
+///
+
+## Combinando información
+
+También puedes combinar información de response de múltiples lugares, incluyendo los parámetros `response_model`, `status_code`, y `responses`.
+
+Puedes declarar un `response_model`, usando el código de estado predeterminado `200` (o uno personalizado si lo necesitas), y luego declarar información adicional para ese mismo response en `responses`, directamente en el esquema de OpenAPI.
+
+**FastAPI** manterá la información adicional de `responses` y la combinará con el JSON Schema de tu modelo.
+
+Por ejemplo, puedes declarar un response con un código de estado `404` que usa un modelo Pydantic y tiene una `description` personalizada.
+
+Y un response con un código de estado `200` que usa tu `response_model`, pero incluye un `example` personalizado:
+
+{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
+
+Todo se combinará e incluirá en tu OpenAPI, y se mostrará en la documentación de la API:
+
+<img src="/img/tutorial/additional-responses/image01.png">
+
+## Combina responses predefinidos y personalizados
+
+Es posible que desees tener algunos responses predefinidos que se apliquen a muchas *path operations*, pero que quieras combinarlos con responses personalizados necesarios por cada *path operation*.
+
+Para esos casos, puedes usar la técnica de Python de "desempaquetar" un `dict` con `**dict_to_unpack`:
+
+```Python
+old_dict = {
+    "old key": "old value",
+    "second old key": "second old value",
+}
+new_dict = {**old_dict, "new key": "new value"}
+```
+
+Aquí, `new_dict` contendrá todos los pares clave-valor de `old_dict` más el nuevo par clave-valor:
+
+```Python
+{
+    "old key": "old value",
+    "second old key": "second old value",
+    "new key": "new value",
+}
+```
+
+Puedes usar esa técnica para reutilizar algunos responses predefinidos en tus *path operations* y combinarlos con otros personalizados adicionales.
+
+Por ejemplo:
+
+{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
+
+## Más información sobre responses OpenAPI
+
+Para ver exactamente qué puedes incluir en los responses, puedes revisar estas secciones en la especificación OpenAPI:
+
+* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object" class="external-link" target="_blank">Objeto de Responses de OpenAPI</a>, incluye el `Response Object`.
+* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object" class="external-link" target="_blank">Objeto de Response de OpenAPI</a>, puedes incluir cualquier cosa de esto directamente en cada response dentro de tu parámetro `responses`. Incluyendo `description`, `headers`, `content` (dentro de este es que declaras diferentes media types y JSON Schemas), y `links`.

docs/es/docs/advanced/additional-status-codes.md

@@ -0,0 +1,41 @@
+# Códigos de Estado Adicionales
+
+Por defecto, **FastAPI** devolverá los responses usando un `JSONResponse`, colocando el contenido que devuelves desde tu *path operation* dentro de ese `JSONResponse`.
+
+Usará el código de estado por defecto o el que configures en tu *path operation*.
+
+## Códigos de estado adicionales
+
+Si quieres devolver códigos de estado adicionales aparte del principal, puedes hacerlo devolviendo un `Response` directamente, como un `JSONResponse`, y configurando el código de estado adicional directamente.
+
+Por ejemplo, supongamos que quieres tener una *path operation* que permita actualizar elementos, y devuelva códigos de estado HTTP de 200 "OK" cuando sea exitoso.
+
+Pero también quieres que acepte nuevos elementos. Y cuando los elementos no existían antes, los crea y devuelve un código de estado HTTP de 201 "Created".
+
+Para lograr eso, importa `JSONResponse`, y devuelve tu contenido allí directamente, configurando el `status_code` que deseas:
+
+{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
+
+/// warning | Advertencia
+
+Cuando devuelves un `Response` directamente, como en el ejemplo anterior, se devuelve directamente.
+
+No se serializará con un modelo, etc.
+
+Asegúrate de que tenga los datos que deseas que tenga y que los valores sean JSON válidos (si estás usando `JSONResponse`).
+
+///
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.responses import JSONResponse`.
+
+**FastAPI** proporciona los mismos `starlette.responses` que `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles provienen directamente de Starlette. Lo mismo con `status`.
+
+///
+
+## OpenAPI y documentación de API
+
+Si devuelves códigos de estado adicionales y responses directamente, no se incluirán en el esquema de OpenAPI (la documentación de la API), porque FastAPI no tiene una forma de saber de antemano qué vas a devolver.
+
+Pero puedes documentarlo en tu código, usando: [Responses Adicionales](additional-responses.md){.internal-link target=_blank}.

docs/es/docs/advanced/advanced-dependencies.md

@@ -0,0 +1,65 @@
+# Dependencias Avanzadas
+
+## Dependencias con parámetros
+
+Todas las dependencias que hemos visto son una función o clase fija.
+
+Pero podría haber casos en los que quieras poder establecer parámetros en la dependencia, sin tener que declarar muchas funciones o clases diferentes.
+
+Imaginemos que queremos tener una dependencia que revise si el parámetro de query `q` contiene algún contenido fijo.
+
+Pero queremos poder parametrizar ese contenido fijo.
+
+## Una *instance* "callable"
+
+En Python hay una forma de hacer que una instance de una clase sea un "callable".
+
+No la clase en sí (que ya es un callable), sino una instance de esa clase.
+
+Para hacer eso, declaramos un método `__call__`:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *}
+
+En este caso, este `__call__` es lo que **FastAPI** usará para comprobar parámetros adicionales y sub-dependencias, y es lo que llamará para pasar un valor al parámetro en tu *path operation function* más adelante.
+
+## Parametrizar la instance
+
+Y ahora, podemos usar `__init__` para declarar los parámetros de la instance que podemos usar para "parametrizar" la dependencia:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[9] *}
+
+En este caso, **FastAPI** nunca tocará ni se preocupará por `__init__`, lo usaremos directamente en nuestro código.
+
+## Crear una instance
+
+Podríamos crear una instance de esta clase con:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[18] *}
+
+Y de esa manera podemos "parametrizar" nuestra dependencia, que ahora tiene `"bar"` dentro de ella, como el atributo `checker.fixed_content`.
+
+## Usar la instance como una dependencia
+
+Luego, podríamos usar este `checker` en un `Depends(checker)`, en lugar de `Depends(FixedContentQueryChecker)`, porque la dependencia es la instance, `checker`, no la clase en sí.
+
+Y al resolver la dependencia, **FastAPI** llamará a este `checker` así:
+
+```Python
+checker(q="somequery")
+```
+
+...y pasará lo que eso retorne como el valor de la dependencia en nuestra *path operation function* como el parámetro `fixed_content_included`:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[22] *}
+
+/// tip | Consejo
+
+Todo esto podría parecer complicado. Y puede que no esté muy claro cómo es útil aún.
+
+Estos ejemplos son intencionalmente simples, pero muestran cómo funciona todo.
+
+En los capítulos sobre seguridad, hay funciones utilitarias que se implementan de esta misma manera.
+
+Si entendiste todo esto, ya sabes cómo funcionan por debajo esas herramientas de utilidad para seguridad.
+
+///

docs/es/docs/advanced/async-tests.md

@@ -0,0 +1,99 @@
+# Tests Asíncronos
+
+Ya has visto cómo probar tus aplicaciones de **FastAPI** usando el `TestClient` proporcionado. Hasta ahora, solo has visto cómo escribir tests sincrónicos, sin usar funciones `async`.
+
+Poder usar funciones asíncronas en tus tests puede ser útil, por ejemplo, cuando consultas tu base de datos de forma asíncrona. Imagina que quieres probar el envío de requests a tu aplicación FastAPI y luego verificar que tu backend escribió exitosamente los datos correctos en la base de datos, mientras usas un paquete de base de datos asíncrono.
+
+Veamos cómo podemos hacer que esto funcione.
+
+## pytest.mark.anyio
+
+Si queremos llamar funciones asíncronas en nuestros tests, nuestras funciones de test tienen que ser asíncronas. AnyIO proporciona un plugin útil para esto, que nos permite especificar que algunas funciones de test deben ser llamadas de manera asíncrona.
+
+## HTTPX
+
+Incluso si tu aplicación de **FastAPI** usa funciones `def` normales en lugar de `async def`, sigue siendo una aplicación `async` por debajo.
+
+El `TestClient` hace algo de magia interna para llamar a la aplicación FastAPI asíncrona en tus funciones de test `def` normales, usando pytest estándar. Pero esa magia ya no funciona cuando lo usamos dentro de funciones asíncronas. Al ejecutar nuestros tests de manera asíncrona, ya no podemos usar el `TestClient` dentro de nuestras funciones de test.
+
+El `TestClient` está basado en <a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPX</a>, y afortunadamente, podemos usarlo directamente para probar la API.
+
+## Ejemplo
+
+Para un ejemplo simple, consideremos una estructura de archivos similar a la descrita en [Aplicaciones Más Grandes](../tutorial/bigger-applications.md){.internal-link target=_blank} y [Testing](../tutorial/testing.md){.internal-link target=_blank}:
+
+```
+.
+├── app
+│   ├── __init__.py
+│   ├── main.py
+│   └── test_main.py
+```
+
+El archivo `main.py` tendría:
+
+{* ../../docs_src/async_tests/main.py *}
+
+El archivo `test_main.py` tendría los tests para `main.py`, podría verse así ahora:
+
+{* ../../docs_src/async_tests/test_main.py *}
+
+## Ejecútalo
+
+Puedes ejecutar tus tests como de costumbre vía:
+
+<div class="termy">
+
+```console
+$ pytest
+
+---> 100%
+```
+
+</div>
+
+## En Detalle
+
+El marcador `@pytest.mark.anyio` le dice a pytest que esta función de test debe ser llamada asíncronamente:
+
+{* ../../docs_src/async_tests/test_main.py hl[7] *}
+
+/// tip | Consejo
+
+Note que la función de test ahora es `async def` en lugar de solo `def` como antes al usar el `TestClient`.
+
+///
+
+Luego podemos crear un `AsyncClient` con la app y enviar requests asíncronos a ella, usando `await`.
+
+{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
+
+Esto es equivalente a:
+
+```Python
+response = client.get('/')
+```
+
+...que usábamos para hacer nuestros requests con el `TestClient`.
+
+/// tip | Consejo
+
+Nota que estamos usando async/await con el nuevo `AsyncClient`: el request es asíncrono.
+
+///
+
+/// warning | Advertencia
+
+Si tu aplicación depende de eventos de lifespan, el `AsyncClient` no activará estos eventos. Para asegurarte de que se activen, usa `LifespanManager` de <a href="https://github.com/florimondmanca/asgi-lifespan#usage" class="external-link" target="_blank">florimondmanca/asgi-lifespan</a>.
+
+///
+
+## Otras Llamadas a Funciones Asíncronas
+
+Al ser la función de test asíncrona, ahora también puedes llamar (y `await`) otras funciones `async` además de enviar requests a tu aplicación FastAPI en tus tests, exactamente como las llamarías en cualquier otro lugar de tu código.
+
+/// tip | Consejo
+
+Si encuentras un `RuntimeError: Task attached to a different loop` al integrar llamadas a funciones asíncronas en tus tests (por ejemplo, cuando usas <a href="https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop" class="external-link" target="_blank">MotorClient de MongoDB</a>), recuerda crear instances de objetos que necesiten un loop de eventos solo dentro de funciones async, por ejemplo, en un callback `'@app.on_event("startup")`.
+
+///

docs/es/docs/advanced/behind-a-proxy.md

@@ -0,0 +1,361 @@
+# Detrás de un Proxy
+
+En algunas situaciones, podrías necesitar usar un **proxy** como Traefik o Nginx con una configuración que añade un prefijo de path extra que no es visto por tu aplicación.
+
+En estos casos, puedes usar `root_path` para configurar tu aplicación.
+
+El `root_path` es un mecanismo proporcionado por la especificación ASGI (en la que está construido FastAPI, a través de Starlette).
+
+El `root_path` se usa para manejar estos casos específicos.
+
+Y también se usa internamente al montar subaplicaciones.
+
+## Proxy con un prefijo de path eliminado
+
+Tener un proxy con un prefijo de path eliminado, en este caso, significa que podrías declarar un path en `/app` en tu código, pero luego añades una capa encima (el proxy) que situaría tu aplicación **FastAPI** bajo un path como `/api/v1`.
+
+En este caso, el path original `/app` realmente sería servido en `/api/v1/app`.
+
+Aunque todo tu código esté escrito asumiendo que solo existe `/app`.
+
+{* ../../docs_src/behind_a_proxy/tutorial001.py hl[6] *}
+
+Y el proxy estaría **"eliminando"** el **prefijo del path** sobre la marcha antes de transmitir el request al servidor de aplicaciones (probablemente Uvicorn a través de FastAPI CLI), manteniendo a tu aplicación convencida de que está siendo servida en `/app`, así que no tienes que actualizar todo tu código para incluir el prefijo `/api/v1`.
+
+Hasta aquí, todo funcionaría normalmente.
+
+Pero luego, cuando abres la UI integrada de los docs (el frontend), esperaría obtener el esquema de OpenAPI en `/openapi.json`, en lugar de `/api/v1/openapi.json`.
+
+Entonces, el frontend (que se ejecuta en el navegador) trataría de alcanzar `/openapi.json` y no podría obtener el esquema de OpenAPI.
+
+Porque tenemos un proxy con un prefijo de path de `/api/v1` para nuestra aplicación, el frontend necesita obtener el esquema de OpenAPI en `/api/v1/openapi.json`.
+
+```mermaid
+graph LR
+
+browser("Navegador")
+proxy["Proxy en http://0.0.0.0:9999/api/v1/app"]
+server["Servidor en http://127.0.0.1:8000/app"]
+
+browser --> proxy
+proxy --> server
+```
+
+/// tip | Consejo
+
+La IP `0.0.0.0` se usa comúnmente para indicar que el programa escucha en todas las IPs disponibles en esa máquina/servidor.
+
+///
+
+La UI de los docs también necesitaría el esquema de OpenAPI para declarar que este API `servidor` se encuentra en `/api/v1` (detrás del proxy). Por ejemplo:
+
+```JSON hl_lines="4-8"
+{
+    "openapi": "3.1.0",
+    // Más cosas aquí
+    "servers": [
+        {
+            "url": "/api/v1"
+        }
+    ],
+    "paths": {
+            // Más cosas aquí
+    }
+}
+```
+
+En este ejemplo, el "Proxy" podría ser algo como **Traefik**. Y el servidor sería algo como FastAPI CLI con **Uvicorn**, ejecutando tu aplicación de FastAPI.
+
+### Proporcionando el `root_path`
+
+Para lograr esto, puedes usar la opción de línea de comandos `--root-path` como:
+
+<div class="termy">
+
+```console
+$ fastapi run main.py --root-path /api/v1
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+</div>
+
+Si usas Hypercorn, también tiene la opción `--root-path`.
+
+/// note | Detalles Técnicos
+
+La especificación ASGI define un `root_path` para este caso de uso.
+
+Y la opción de línea de comandos `--root-path` proporciona ese `root_path`.
+
+///
+
+### Revisar el `root_path` actual
+
+Puedes obtener el `root_path` actual utilizado por tu aplicación para cada request, es parte del diccionario `scope` (que es parte de la especificación ASGI).
+
+Aquí lo estamos incluyendo en el mensaje solo con fines de demostración.
+
+{* ../../docs_src/behind_a_proxy/tutorial001.py hl[8] *}
+
+Luego, si inicias Uvicorn con:
+
+<div class="termy">
+
+```console
+$ fastapi run main.py --root-path /api/v1
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+</div>
+
+El response sería algo como:
+
+```JSON
+{
+    "message": "Hello World",
+    "root_path": "/api/v1"
+}
+```
+
+### Configurar el `root_path` en la app de FastAPI
+
+Alternativamente, si no tienes una forma de proporcionar una opción de línea de comandos como `--root-path` o su equivalente, puedes configurar el parámetro `root_path` al crear tu app de FastAPI:
+
+{* ../../docs_src/behind_a_proxy/tutorial002.py hl[3] *}
+
+Pasar el `root_path` a `FastAPI` sería el equivalente a pasar la opción de línea de comandos `--root-path` a Uvicorn o Hypercorn.
+
+### Acerca de `root_path`
+
+Ten en cuenta que el servidor (Uvicorn) no usará ese `root_path` para nada, a excepción de pasárselo a la app.
+
+Pero si vas con tu navegador a <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000/app</a> verás el response normal:
+
+```JSON
+{
+    "message": "Hello World",
+    "root_path": "/api/v1"
+}
+```
+
+Así que no se esperará que sea accedido en `http://127.0.0.1:8000/api/v1/app`.
+
+Uvicorn esperará que el proxy acceda a Uvicorn en `http://127.0.0.1:8000/app`, y luego será responsabilidad del proxy añadir el prefijo extra `/api/v1` encima.
+
+## Sobre proxies con un prefijo de path eliminado
+
+Ten en cuenta que un proxy con prefijo de path eliminado es solo una de las formas de configurarlo.
+
+Probablemente en muchos casos, el valor predeterminado será que el proxy no tenga un prefijo de path eliminado.
+
+En un caso así (sin un prefijo de path eliminado), el proxy escucharía algo como `https://myawesomeapp.com`, y luego si el navegador va a `https://myawesomeapp.com/api/v1/app` y tu servidor (por ejemplo, Uvicorn) escucha en `http://127.0.0.1:8000`, el proxy (sin un prefijo de path eliminado) accedería a Uvicorn en el mismo path: `http://127.0.0.1:8000/api/v1/app`.
+
+## Probando localmente con Traefik
+
+Puedes ejecutar fácilmente el experimento localmente con un prefijo de path eliminado usando <a href="https://docs.traefik.io/" class="external-link" target="_blank">Traefik</a>.
+
+<a href="https://github.com/containous/traefik/releases" class="external-link" target="_blank">Descarga Traefik</a>, es un archivo binario único, puedes extraer el archivo comprimido y ejecutarlo directamente desde la terminal.
+
+Luego crea un archivo `traefik.toml` con:
+
+```TOML hl_lines="3"
+[entryPoints]
+  [entryPoints.http]
+    address = ":9999"
+
+[providers]
+  [providers.file]
+    filename = "routes.toml"
+```
+
+Esto le dice a Traefik que escuche en el puerto 9999 y que use otro archivo `routes.toml`.
+
+/// tip | Consejo
+
+Estamos utilizando el puerto 9999 en lugar del puerto HTTP estándar 80 para que no tengas que ejecutarlo con privilegios de administrador (`sudo`).
+
+///
+
+Ahora crea ese otro archivo `routes.toml`:
+
+```TOML hl_lines="5  12  20"
+[http]
+  [http.middlewares]
+
+    [http.middlewares.api-stripprefix.stripPrefix]
+      prefixes = ["/api/v1"]
+
+  [http.routers]
+
+    [http.routers.app-http]
+      entryPoints = ["http"]
+      service = "app"
+      rule = "PathPrefix(`/api/v1`)"
+      middlewares = ["api-stripprefix"]
+
+  [http.services]
+
+    [http.services.app]
+      [http.services.app.loadBalancer]
+        [[http.services.app.loadBalancer.servers]]
+          url = "http://127.0.0.1:8000"
+```
+
+Este archivo configura Traefik para usar el prefijo de path `/api/v1`.
+
+Y luego Traefik redireccionará sus requests a tu Uvicorn ejecutándose en `http://127.0.0.1:8000`.
+
+Ahora inicia Traefik:
+
+<div class="termy">
+
+```console
+$ ./traefik --configFile=traefik.toml
+
+INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
+```
+
+</div>
+
+Y ahora inicia tu app, utilizando la opción `--root-path`:
+
+<div class="termy">
+
+```console
+$ fastapi run main.py --root-path /api/v1
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+</div>
+
+### Revisa los responses
+
+Ahora, si vas a la URL con el puerto para Uvicorn: <a href="http://127.0.0.1:8000/app" class="external-link" target="_blank">http://127.0.0.1:8000/app</a>, verás el response normal:
+
+```JSON
+{
+    "message": "Hello World",
+    "root_path": "/api/v1"
+}
+```
+
+/// tip | Consejo
+
+Nota que incluso aunque estés accediendo en `http://127.0.0.1:8000/app`, muestra el `root_path` de `/api/v1`, tomado de la opción `--root-path`.
+
+///
+
+Y ahora abre la URL con el puerto para Traefik, incluyendo el prefijo de path: <a href="http://127.0.0.1:9999/api/v1/app" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/app</a>.
+
+Obtenemos el mismo response:
+
+```JSON
+{
+    "message": "Hello World",
+    "root_path": "/api/v1"
+}
+```
+
+pero esta vez en la URL con el prefijo de path proporcionado por el proxy: `/api/v1`.
+
+Por supuesto, la idea aquí es que todos accedan a la app a través del proxy, así que la versión con el prefijo de path `/api/v1` es la "correcta".
+
+Y la versión sin el prefijo de path (`http://127.0.0.1:8000/app`), proporcionada directamente por Uvicorn, sería exclusivamente para que el _proxy_ (Traefik) la acceda.
+
+Eso demuestra cómo el Proxy (Traefik) usa el prefijo de path y cómo el servidor (Uvicorn) usa el `root_path` de la opción `--root-path`.
+
+### Revisa la UI de los docs
+
+Pero aquí está la parte divertida. ✨
+
+La forma "oficial" de acceder a la app sería a través del proxy con el prefijo de path que definimos. Así que, como esperaríamos, si intentas usar la UI de los docs servida por Uvicorn directamente, sin el prefijo de path en la URL, no funcionará, porque espera ser accedida a través del proxy.
+
+Puedes verificarlo en <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>:
+
+<img src="/img/tutorial/behind-a-proxy/image01.png">
+
+Pero si accedemos a la UI de los docs en la URL "oficial" usando el proxy con puerto `9999`, en `/api/v1/docs`, ¡funciona correctamente! 🎉
+
+Puedes verificarlo en <a href="http://127.0.0.1:9999/api/v1/docs" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/docs</a>:
+
+<img src="/img/tutorial/behind-a-proxy/image02.png">
+
+Justo como queríamos. ✔️
+
+Esto es porque FastAPI usa este `root_path` para crear el `server` por defecto en OpenAPI con la URL proporcionada por `root_path`.
+
+## Servidores adicionales
+
+/// warning | Advertencia
+
+Este es un caso de uso más avanzado. Siéntete libre de omitirlo.
+
+///
+
+Por defecto, **FastAPI** creará un `server` en el esquema de OpenAPI con la URL para el `root_path`.
+
+Pero también puedes proporcionar otros `servers` alternativos, por ejemplo, si deseas que *la misma* UI de los docs interactúe con un entorno de pruebas y de producción.
+
+Si pasas una lista personalizada de `servers` y hay un `root_path` (porque tu API existe detrás de un proxy), **FastAPI** insertará un "server" con este `root_path` al comienzo de la lista.
+
+Por ejemplo:
+
+{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
+
+Generará un esquema de OpenAPI como:
+
+```JSON hl_lines="5-7"
+{
+    "openapi": "3.1.0",
+    // Más cosas aquí
+    "servers": [
+        {
+            "url": "/api/v1"
+        },
+        {
+            "url": "https://stag.example.com",
+            "description": "Entorno de pruebas"
+        },
+        {
+            "url": "https://prod.example.com",
+            "description": "Entorno de producción"
+        }
+    ],
+    "paths": {
+            // Más cosas aquí
+    }
+}
+```
+
+/// tip | Consejo
+
+Observa el server auto-generado con un valor `url` de `/api/v1`, tomado del `root_path`.
+
+///
+
+En la UI de los docs en <a href="http://127.0.0.1:9999/api/v1/docs" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/docs</a> se vería como:
+
+<img src="/img/tutorial/behind-a-proxy/image03.png">
+
+/// tip | Consejo
+
+La UI de los docs interactuará con el server que selecciones.
+
+///
+
+### Desactivar el server automático de `root_path`
+
+Si no quieres que **FastAPI** incluya un server automático usando el `root_path`, puedes usar el parámetro `root_path_in_servers=False`:
+
+{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
+
+y entonces no lo incluirá en el esquema de OpenAPI.
+
+## Montando una sub-aplicación
+
+Si necesitas montar una sub-aplicación (como se describe en [Aplicaciones secundarias - Monturas](sub-applications.md){.internal-link target=_blank}) mientras usas un proxy con `root_path`, puedes hacerlo normalmente, como esperarías.
+
+FastAPI usará internamente el `root_path` de manera inteligente, así que simplemente funcionará. ✨

docs/es/docs/advanced/custom-response.md

@@ -0,0 +1,312 @@
+# Response Personalizado - HTML, Stream, Archivo, otros
+
+Por defecto, **FastAPI** devolverá los responses usando `JSONResponse`.
+
+Puedes sobrescribirlo devolviendo un `Response` directamente como se ve en [Devolver una Response directamente](response-directly.md){.internal-link target=_blank}.
+
+Pero si devuelves un `Response` directamente (o cualquier subclase, como `JSONResponse`), los datos no se convertirán automáticamente (incluso si declaras un `response_model`), y la documentación no se generará automáticamente (por ejemplo, incluyendo el "media type" específico, en el HTTP header `Content-Type` como parte del OpenAPI generado).
+
+Pero también puedes declarar el `Response` que quieres usar (por ejemplo, cualquier subclase de `Response`), en el *path operation decorator* usando el parámetro `response_class`.
+
+Los contenidos que devuelvas desde tu *path operation function* se colocarán dentro de esa `Response`.
+
+Y si ese `Response` tiene un media type JSON (`application/json`), como es el caso con `JSONResponse` y `UJSONResponse`, los datos que devuelvas se convertirán automáticamente (y serán filtrados) con cualquier `response_model` de Pydantic que hayas declarado en el *path operation decorator*.
+
+/// note | Nota
+
+Si usas una clase de response sin media type, FastAPI esperará que tu response no tenga contenido, por lo que no documentará el formato del response en su OpenAPI generado.
+
+///
+
+## Usa `ORJSONResponse`
+
+Por ejemplo, si estás exprimendo el rendimiento, puedes instalar y usar <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a> y establecer el response como `ORJSONResponse`.
+
+Importa la clase `Response` (sub-clase) que quieras usar y declárala en el *path operation decorator*.
+
+Para responses grandes, devolver una `Response` directamente es mucho más rápido que devolver un diccionario.
+
+Esto se debe a que, por defecto, FastAPI inspeccionará cada elemento dentro y se asegurará de que sea serializable como JSON, usando el mismo [Codificador Compatible con JSON](../tutorial/encoder.md){.internal-link target=_blank} explicado en el tutorial. Esto es lo que te permite devolver **objetos arbitrarios**, por ejemplo, modelos de bases de datos.
+
+Pero si estás seguro de que el contenido que estás devolviendo es **serializable con JSON**, puedes pasarlo directamente a la clase de response y evitar la sobrecarga extra que FastAPI tendría al pasar tu contenido de retorno a través de `jsonable_encoder` antes de pasarlo a la clase de response.
+
+{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
+
+/// info | Información
+
+El parámetro `response_class` también se utilizará para definir el "media type" del response.
+
+En este caso, el HTTP header `Content-Type` se establecerá en `application/json`.
+
+Y se documentará así en OpenAPI.
+
+///
+
+/// tip | Consejo
+
+El `ORJSONResponse` solo está disponible en FastAPI, no en Starlette.
+
+///
+
+## Response HTML
+
+Para devolver un response con HTML directamente desde **FastAPI**, usa `HTMLResponse`.
+
+* Importa `HTMLResponse`.
+* Pasa `HTMLResponse` como parámetro `response_class` de tu *path operation decorator*.
+
+{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
+
+/// info | Información
+
+El parámetro `response_class` también se utilizará para definir el "media type" del response.
+
+En este caso, el HTTP header `Content-Type` se establecerá en `text/html`.
+
+Y se documentará así en OpenAPI.
+
+///
+
+### Devuelve una `Response`
+
+Como se ve en [Devolver una Response directamente](response-directly.md){.internal-link target=_blank}, también puedes sobrescribir el response directamente en tu *path operation*, devolviéndolo.
+
+El mismo ejemplo de arriba, devolviendo una `HTMLResponse`, podría verse así:
+
+{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
+
+/// warning | Advertencia
+
+Una `Response` devuelta directamente por tu *path operation function* no se documentará en OpenAPI (por ejemplo, el `Content-Type` no se documentará) y no será visible en la documentación interactiva automática.
+
+///
+
+/// info | Información
+
+Por supuesto, el `Content-Type` header real, el código de estado, etc., provendrán del objeto `Response` que devolviste.
+
+///
+
+### Documenta en OpenAPI y sobrescribe `Response`
+
+Si quieres sobrescribir el response desde dentro de la función pero al mismo tiempo documentar el "media type" en OpenAPI, puedes usar el parámetro `response_class` Y devolver un objeto `Response`.
+
+El `response_class` solo se usará para documentar el OpenAPI *path operation*, pero tu `Response` se usará tal cual.
+
+#### Devuelve un `HTMLResponse` directamente
+
+Por ejemplo, podría ser algo así:
+
+{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
+
+En este ejemplo, la función `generate_html_response()` ya genera y devuelve una `Response` en lugar de devolver el HTML en un `str`.
+
+Al devolver el resultado de llamar a `generate_html_response()`, ya estás devolviendo una `Response` que sobrescribirá el comportamiento predeterminado de **FastAPI**.
+
+Pero como pasaste `HTMLResponse` en el `response_class` también, **FastAPI** sabrá cómo documentarlo en OpenAPI y la documentación interactiva como HTML con `text/html`:
+
+<img src="/img/tutorial/custom-response/image01.png">
+
+## Responses disponibles
+
+Aquí hay algunos de los responses disponibles.
+
+Ten en cuenta que puedes usar `Response` para devolver cualquier otra cosa, o incluso crear una sub-clase personalizada.
+
+/// note | Nota Técnica
+
+También podrías usar `from starlette.responses import HTMLResponse`.
+
+**FastAPI** proporciona los mismos `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.
+
+///
+
+### `Response`
+
+La clase principal `Response`, todos los otros responses heredan de ella.
+
+Puedes devolverla directamente.
+
+Acepta los siguientes parámetros:
+
+* `content` - Un `str` o `bytes`.
+* `status_code` - Un código de estado HTTP `int`.
+* `headers` - Un `dict` de strings.
+* `media_type` - Un `str` que da el media type. Por ejemplo, `"text/html"`.
+
+FastAPI (de hecho Starlette) incluirá automáticamente un header Content-Length. También incluirá un header Content-Type, basado en el `media_type` y añadiendo un conjunto de caracteres para tipos de texto.
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+
+### `HTMLResponse`
+
+Toma algún texto o bytes y devuelve un response HTML, como leíste arriba.
+
+### `PlainTextResponse`
+
+Toma algún texto o bytes y devuelve un response de texto plano.
+
+{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
+
+### `JSONResponse`
+
+Toma algunos datos y devuelve un response codificado como `application/json`.
+
+Este es el response predeterminado usado en **FastAPI**, como leíste arriba.
+
+### `ORJSONResponse`
+
+Un response JSON rápido alternativo usando <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a>, como leíste arriba.
+
+/// info | Información
+
+Esto requiere instalar `orjson`, por ejemplo, con `pip install orjson`.
+
+///
+
+### `UJSONResponse`
+
+Un response JSON alternativo usando <a href="https://github.com/ultrajson/ultrajson" class="external-link" target="_blank">`ujson`</a>.
+
+/// info | Información
+
+Esto requiere instalar `ujson`, por ejemplo, con `pip install ujson`.
+
+///
+
+/// warning | Advertencia
+
+`ujson` es menos cuidadoso que la implementación integrada de Python en cómo maneja algunos casos extremos.
+
+///
+
+{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+
+/// tip | Consejo
+
+Es posible que `ORJSONResponse` sea una alternativa más rápida.
+
+///
+
+### `RedirectResponse`
+
+Devuelve una redirección HTTP. Usa un código de estado 307 (Redirección Temporal) por defecto.
+
+Puedes devolver un `RedirectResponse` directamente:
+
+{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
+
+---
+
+O puedes usarlo en el parámetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
+
+Si haces eso, entonces puedes devolver la URL directamente desde tu *path operation function*.
+
+En este caso, el `status_code` utilizado será el predeterminado para `RedirectResponse`, que es `307`.
+
+---
+
+También puedes usar el parámetro `status_code` combinado con el parámetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
+
+### `StreamingResponse`
+
+Toma un generador `async` o un generador/iterador normal y transmite el cuerpo del response.
+
+{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
+
+#### Usando `StreamingResponse` con objetos similares a archivos
+
+Si tienes un objeto similar a un archivo (por ejemplo, el objeto devuelto por `open()`), puedes crear una función generadora para iterar sobre ese objeto similar a un archivo.
+
+De esa manera, no tienes que leerlo todo primero en memoria, y puedes pasar esa función generadora al `StreamingResponse`, y devolverlo.
+
+Esto incluye muchos paquetes para interactuar con almacenamiento en la nube, procesamiento de video y otros.
+
+{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *}
+
+1. Esta es la función generadora. Es una "función generadora" porque contiene declaraciones `yield` dentro.
+2. Al usar un bloque `with`, nos aseguramos de que el objeto similar a un archivo se cierre después de que la función generadora termine. Así, después de que termina de enviar el response.
+3. Este `yield from` le dice a la función que itere sobre esa cosa llamada `file_like`. Y luego, para cada parte iterada, yield esa parte como proveniente de esta función generadora (`iterfile`).
+
+    Entonces, es una función generadora que transfiere el trabajo de "generar" a algo más internamente.
+
+    Al hacerlo de esta manera, podemos ponerlo en un bloque `with`, y de esa manera, asegurarnos de que el objeto similar a un archivo se cierre después de finalizar.
+
+/// tip | Consejo
+
+Nota que aquí como estamos usando `open()` estándar que no admite `async` y `await`, declaramos el path operation con `def` normal.
+
+///
+
+### `FileResponse`
+
+Transmite un archivo asincrónicamente como response.
+
+Toma un conjunto diferente de argumentos para crear un instance que los otros tipos de response:
+
+* `path` - La path del archivo para el archivo a transmitir.
+* `headers` - Cualquier header personalizado para incluir, como un diccionario.
+* `media_type` - Un string que da el media type. Si no se establece, se usará el nombre de archivo o la path para inferir un media type.
+* `filename` - Si se establece, se incluirá en el response `Content-Disposition`.
+
+Los responses de archivos incluirán los headers apropiados `Content-Length`, `Last-Modified` y `ETag`.
+
+{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
+
+También puedes usar el parámetro `response_class`:
+
+{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
+
+En este caso, puedes devolver la path del archivo directamente desde tu *path operation* function.
+
+## Clase de response personalizada
+
+Puedes crear tu propia clase de response personalizada, heredando de `Response` y usándola.
+
+Por ejemplo, digamos que quieres usar <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a>, pero con algunas configuraciones personalizadas no utilizadas en la clase `ORJSONResponse` incluida.
+
+Digamos que quieres que devuelva JSON con sangría y formato, por lo que quieres usar la opción de orjson `orjson.OPT_INDENT_2`.
+
+Podrías crear un `CustomORJSONResponse`. Lo principal que tienes que hacer es crear un método `Response.render(content)` que devuelva el contenido como `bytes`:
+
+{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
+
+Ahora en lugar de devolver:
+
+```json
+{"message": "Hello World"}
+```
+
+...este response devolverá:
+
+```json
+{
+  "message": "Hello World"
+}
+```
+
+Por supuesto, probablemente encontrarás formas mucho mejores de aprovechar esto que formatear JSON. 😉
+
+## Clase de response predeterminada
+
+Al crear una instance de la clase **FastAPI** o un `APIRouter`, puedes especificar qué clase de response usar por defecto.
+
+El parámetro que define esto es `default_response_class`.
+
+En el ejemplo a continuación, **FastAPI** usará `ORJSONResponse` por defecto, en todas las *path operations*, en lugar de `JSONResponse`.
+
+{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
+
+/// tip | Consejo
+
+Todavía puedes sobrescribir `response_class` en *path operations* como antes.
+
+///
+
+## Documentación adicional
+
+También puedes declarar el media type y muchos otros detalles en OpenAPI usando `responses`: [Responses Adicionales en OpenAPI](additional-responses.md){.internal-link target=_blank}.

docs/es/docs/advanced/dataclasses.md

@@ -0,0 +1,95 @@
+# Usando Dataclasses
+
+FastAPI está construido sobre **Pydantic**, y te he estado mostrando cómo usar modelos de Pydantic para declarar requests y responses.
+
+Pero FastAPI también soporta el uso de <a href="https://docs.python.org/3/library/dataclasses.html" class="external-link" target="_blank">`dataclasses`</a> de la misma manera:
+
+{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
+
+Esto sigue siendo soportado gracias a **Pydantic**, ya que tiene <a href="https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel" class="external-link" target="_blank">soporte interno para `dataclasses`</a>.
+
+Así que, incluso con el código anterior que no usa Pydantic explícitamente, FastAPI está usando Pydantic para convertir esos dataclasses estándar en su propia versión de dataclasses de Pydantic.
+
+Y por supuesto, soporta lo mismo:
+
+* validación de datos
+* serialización de datos
+* documentación de datos, etc.
+
+Esto funciona de la misma manera que con los modelos de Pydantic. Y en realidad se logra de la misma manera internamente, utilizando Pydantic.
+
+/// info | Información
+
+Ten en cuenta que los dataclasses no pueden hacer todo lo que los modelos de Pydantic pueden hacer.
+
+Así que, podrías necesitar seguir usando modelos de Pydantic.
+
+Pero si tienes un montón de dataclasses por ahí, este es un buen truco para usarlos para potenciar una API web usando FastAPI. 🤓
+
+///
+
+## Dataclasses en `response_model`
+
+También puedes usar `dataclasses` en el parámetro `response_model`:
+
+{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
+
+El dataclass será automáticamente convertido a un dataclass de Pydantic.
+
+De esta manera, su esquema aparecerá en la interfaz de usuario de la documentación de la API:
+
+<img src="/img/tutorial/dataclasses/image01.png">
+
+## Dataclasses en Estructuras de Datos Anidadas
+
+También puedes combinar `dataclasses` con otras anotaciones de tipos para crear estructuras de datos anidadas.
+
+En algunos casos, todavía podrías tener que usar la versión de `dataclasses` de Pydantic. Por ejemplo, si tienes errores con la documentación de la API generada automáticamente.
+
+En ese caso, simplemente puedes intercambiar los `dataclasses` estándar con `pydantic.dataclasses`, que es un reemplazo directo:
+
+{* ../../docs_src/dataclasses/tutorial003.py hl[1,5,8:11,14:17,23:25,28] *}
+
+1. Todavía importamos `field` de los `dataclasses` estándar.
+
+2. `pydantic.dataclasses` es un reemplazo directo para `dataclasses`.
+
+3. El dataclass `Author` incluye una lista de dataclasses `Item`.
+
+4. El dataclass `Author` se usa como el parámetro `response_model`.
+
+5. Puedes usar otras anotaciones de tipos estándar con dataclasses como el request body.
+
+    En este caso, es una lista de dataclasses `Item`.
+
+6. Aquí estamos regresando un diccionario que contiene `items`, que es una lista de dataclasses.
+
+    FastAPI todavía es capaz de <abbr title="converting the data to a format that can be transmitted">serializar</abbr> los datos a JSON.
+
+7. Aquí el `response_model` está usando una anotación de tipo de una lista de dataclasses `Author`.
+
+    Nuevamente, puedes combinar `dataclasses` con anotaciones de tipos estándar.
+
+8. Nota que esta *path operation function* usa `def` regular en lugar de `async def`.
+
+    Como siempre, en FastAPI puedes combinar `def` y `async def` según sea necesario.
+
+    Si necesitas un repaso sobre cuándo usar cuál, revisa la sección _"¿Con prisa?"_ en la documentación sobre [`async` y `await`](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+9. Esta *path operation function* no está devolviendo dataclasses (aunque podría), sino una lista de diccionarios con datos internos.
+
+    FastAPI usará el parámetro `response_model` (que incluye dataclasses) para convertir el response.
+
+Puedes combinar `dataclasses` con otras anotaciones de tipos en muchas combinaciones diferentes para formar estructuras de datos complejas.
+
+Revisa las anotaciones en el código arriba para ver más detalles específicos.
+
+## Aprende Más
+
+También puedes combinar `dataclasses` con otros modelos de Pydantic, heredar de ellos, incluirlos en tus propios modelos, etc.
+
+Para saber más, revisa la <a href="https://docs.pydantic.dev/latest/concepts/dataclasses/" class="external-link" target="_blank">documentación de Pydantic sobre dataclasses</a>.
+
+## Versión
+
+Esto está disponible desde la versión `0.67.0` de FastAPI. 🔖

docs/es/docs/advanced/events.md

@@ -0,0 +1,165 @@
+# Eventos de Lifespan
+
+Puedes definir lógica (código) que debería ser ejecutada antes de que la aplicación **inicie**. Esto significa que este código será ejecutado **una vez**, **antes** de que la aplicación **comience a recibir requests**.
+
+De la misma manera, puedes definir lógica (código) que debería ser ejecutada cuando la aplicación esté **cerrándose**. En este caso, este código será ejecutado **una vez**, **después** de haber manejado posiblemente **muchos requests**.
+
+Debido a que este código se ejecuta antes de que la aplicación **comience** a tomar requests, y justo después de que **termine** de manejarlos, cubre todo el **lifespan** de la aplicación (la palabra "lifespan" será importante en un momento 😉).
+
+Esto puede ser muy útil para configurar **recursos** que necesitas usar para toda la app, y que son **compartidos** entre requests, y/o que necesitas **limpiar** después. Por ejemplo, un pool de conexiones a una base de datos, o cargando un modelo de machine learning compartido.
+
+## Caso de Uso
+
+Empecemos con un ejemplo de **caso de uso** y luego veamos cómo resolverlo con esto.
+
+Imaginemos que tienes algunos **modelos de machine learning** que quieres usar para manejar requests. 🤖
+
+Los mismos modelos son compartidos entre requests, por lo que no es un modelo por request, o uno por usuario o algo similar.
+
+Imaginemos que cargar el modelo puede **tomar bastante tiempo**, porque tiene que leer muchos **datos del disco**. Entonces no quieres hacerlo para cada request.
+
+Podrías cargarlo en el nivel superior del módulo/archivo, pero eso también significaría que **cargaría el modelo** incluso si solo estás ejecutando una simple prueba automatizada, entonces esa prueba sería **lenta** porque tendría que esperar a que el modelo se cargue antes de poder ejecutar una parte independiente del código.
+
+Eso es lo que resolveremos, vamos a cargar el modelo antes de que los requests sean manejados, pero solo justo antes de que la aplicación comience a recibir requests, no mientras el código se está cargando.
+
+## Lifespan
+
+Puedes definir esta lógica de *startup* y *shutdown* usando el parámetro `lifespan` de la app de `FastAPI`, y un "context manager" (te mostraré lo que es en un momento).
+
+Comencemos con un ejemplo y luego veámoslo en detalle.
+
+Creamos una función asíncrona `lifespan()` con `yield` así:
+
+{* ../../docs_src/events/tutorial003.py hl[16,19] *}
+
+Aquí estamos simulando la operación costosa de *startup* de cargar el modelo poniendo la función del (falso) modelo en el diccionario con modelos de machine learning antes del `yield`. Este código será ejecutado **antes** de que la aplicación **comience a tomar requests**, durante el *startup*.
+
+Y luego, justo después del `yield`, quitaremos el modelo de memoria. Este código será ejecutado **después** de que la aplicación **termine de manejar requests**, justo antes del *shutdown*. Esto podría, por ejemplo, liberar recursos como la memoria o una GPU.
+
+/// tip | Consejo
+
+El `shutdown` ocurriría cuando estás **deteniendo** la aplicación.
+
+Quizás necesites iniciar una nueva versión, o simplemente te cansaste de ejecutarla. 🤷
+
+///
+
+### Función de Lifespan
+
+Lo primero que hay que notar es que estamos definiendo una función asíncrona con `yield`. Esto es muy similar a las Dependencias con `yield`.
+
+{* ../../docs_src/events/tutorial003.py hl[14:19] *}
+
+La primera parte de la función, antes del `yield`, será ejecutada **antes** de que la aplicación comience.
+
+Y la parte después del `yield` será ejecutada **después** de que la aplicación haya terminado.
+
+### Async Context Manager
+
+Si revisas, la función está decorada con un `@asynccontextmanager`.
+
+Eso convierte a la función en algo llamado un "**async context manager**".
+
+{* ../../docs_src/events/tutorial003.py hl[1,13] *}
+
+Un **context manager** en Python es algo que puedes usar en una declaración `with`, por ejemplo, `open()` puede ser usado como un context manager:
+
+```Python
+with open("file.txt") as file:
+    file.read()
+```
+
+En versiones recientes de Python, también hay un **async context manager**. Lo usarías con `async with`:
+
+```Python
+async with lifespan(app):
+    await do_stuff()
+```
+
+Cuando creas un context manager o un async context manager como arriba, lo que hace es que, antes de entrar al bloque `with`, ejecutará el código antes del `yield`, y al salir del bloque `with`, ejecutará el código después del `yield`.
+
+En nuestro ejemplo de código arriba, no lo usamos directamente, pero se lo pasamos a FastAPI para que lo use.
+
+El parámetro `lifespan` de la app de `FastAPI` toma un **async context manager**, por lo que podemos pasar nuestro nuevo `lifespan` async context manager a él.
+
+{* ../../docs_src/events/tutorial003.py hl[22] *}
+
+## Eventos Alternativos (obsoleto)
+
+/// warning | Advertencia
+
+La forma recomendada de manejar el *startup* y el *shutdown* es usando el parámetro `lifespan` de la app de `FastAPI` como se describió arriba. Si proporcionas un parámetro `lifespan`, los manejadores de eventos `startup` y `shutdown` ya no serán llamados. Es solo `lifespan` o solo los eventos, no ambos.
+
+Probablemente puedas saltarte esta parte.
+
+///
+
+Hay una forma alternativa de definir esta lógica para ser ejecutada durante el *startup* y durante el *shutdown*.
+
+Puedes definir manejadores de eventos (funciones) que necesitan ser ejecutadas antes de que la aplicación se inicie, o cuando la aplicación se está cerrando.
+
+Estas funciones pueden ser declaradas con `async def` o `def` normal.
+
+### Evento `startup`
+
+Para añadir una función que debería ejecutarse antes de que la aplicación inicie, declárala con el evento `"startup"`:
+
+{* ../../docs_src/events/tutorial001.py hl[8] *}
+
+En este caso, la función manejadora del evento `startup` inicializará los ítems de la "base de datos" (solo un `dict`) con algunos valores.
+
+Puedes añadir más de un manejador de eventos.
+
+Y tu aplicación no comenzará a recibir requests hasta que todos los manejadores de eventos `startup` hayan completado.
+
+### Evento `shutdown`
+
+Para añadir una función que debería ejecutarse cuando la aplicación se esté cerrando, declárala con el evento `"shutdown"`:
+
+{* ../../docs_src/events/tutorial002.py hl[6] *}
+
+Aquí, la función manejadora del evento `shutdown` escribirá una línea de texto `"Application shutdown"` a un archivo `log.txt`.
+
+/// info | Información
+
+En la función `open()`, el `mode="a"` significa "añadir", por lo tanto, la línea será añadida después de lo que sea que esté en ese archivo, sin sobrescribir el contenido anterior.
+
+///
+
+/// tip | Consejo
+
+Nota que en este caso estamos usando una función estándar de Python `open()` que interactúa con un archivo.
+
+Entonces, involucra I/O (entrada/salida), que requiere "esperar" para que las cosas se escriban en el disco.
+
+Pero `open()` no usa `async` y `await`.
+
+Por eso, declaramos la función manejadora del evento con `def` estándar en vez de `async def`.
+
+///
+
+### `startup` y `shutdown` juntos
+
+Hay una gran posibilidad de que la lógica para tu *startup* y *shutdown* esté conectada, podrías querer iniciar algo y luego finalizarlo, adquirir un recurso y luego liberarlo, etc.
+
+Hacer eso en funciones separadas que no comparten lógica o variables juntas es más difícil ya que necesitarías almacenar valores en variables globales o trucos similares.
+
+Debido a eso, ahora se recomienda en su lugar usar el `lifespan` como se explicó arriba.
+
+## Detalles Técnicos
+
+Solo un detalle técnico para los nerds curiosos. 🤓
+
+Por debajo, en la especificación técnica ASGI, esto es parte del <a href="https://asgi.readthedocs.io/en/latest/specs/lifespan.html" class="external-link" target="_blank">Protocolo de Lifespan</a>, y define eventos llamados `startup` y `shutdown`.
+
+/// info | Información
+
+Puedes leer más sobre los manejadores `lifespan` de Starlette en <a href="https://www.starlette.dev/lifespan/" class="external-link" target="_blank">la documentación de `Lifespan` de Starlette</a>.
+
+Incluyendo cómo manejar el estado de lifespan que puede ser usado en otras áreas de tu código.
+
+///
+
+## Sub Aplicaciones
+
+🚨 Ten en cuenta que estos eventos de lifespan (startup y shutdown) solo serán ejecutados para la aplicación principal, no para [Sub Aplicaciones - Mounts](sub-applications.md){.internal-link target=_blank}.

docs/es/docs/advanced/generate-clients.md

@@ -0,0 +1,261 @@
+# Genera Clientes
+
+Como **FastAPI** está basado en la especificación OpenAPI, obtienes compatibilidad automática con muchas herramientas, incluyendo la documentación automática de la API (proporcionada por Swagger UI).
+
+Una ventaja particular que no es necesariamente obvia es que puedes **generar clientes** (a veces llamados <abbr title="Software Development Kits">**SDKs**</abbr> ) para tu API, para muchos **lenguajes de programación** diferentes.
+
+## Generadores de Clientes OpenAPI
+
+Hay muchas herramientas para generar clientes desde **OpenAPI**.
+
+Una herramienta común es <a href="https://openapi-generator.tech/" class="external-link" target="_blank">OpenAPI Generator</a>.
+
+Si estás construyendo un **frontend**, una alternativa muy interesante es <a href="https://github.com/hey-api/openapi-ts" class="external-link" target="_blank">openapi-ts</a>.
+
+## Generadores de Clientes y SDKs - Sponsor
+
+También hay algunos generadores de Clientes y SDKs **respaldados por empresas** basados en OpenAPI (FastAPI), en algunos casos pueden ofrecerte **funcionalidades adicionales** además de SDKs/clientes generados de alta calidad.
+
+Algunos de ellos también ✨ [**sponsorean FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, esto asegura el **desarrollo** continuo y saludable de FastAPI y su **ecosistema**.
+
+Y muestra su verdadero compromiso con FastAPI y su **comunidad** (tú), ya que no solo quieren proporcionarte un **buen servicio** sino también asegurarse de que tengas un **buen y saludable framework**, FastAPI. 🙇
+
+Por ejemplo, podrías querer probar:
+
+* <a href="https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship" class="external-link" target="_blank">Speakeasy</a>
+* <a href="https://www.stainlessapi.com/?utm_source=fastapi&utm_medium=referral" class="external-link" target="_blank">Stainless</a>
+* <a href="https://developers.liblab.com/tutorials/sdk-for-fastapi/?utm_source=fastapi" class="external-link" target="_blank">liblab</a>
+
+También hay varias otras empresas que ofrecen servicios similares que puedes buscar y encontrar en línea. 🤓
+
+## Genera un Cliente Frontend en TypeScript
+
+Empecemos con una aplicación simple de FastAPI:
+
+{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}
+
+Nota que las *path operations* definen los modelos que usan para el payload de la petición y el payload del response, usando los modelos `Item` y `ResponseMessage`.
+
+### Documentación de la API
+
+Si vas a la documentación de la API, verás que tiene los **esquemas** para los datos que se enviarán en las peticiones y se recibirán en los responses:
+
+<img src="/img/tutorial/generate-clients/image01.png">
+
+Puedes ver esos esquemas porque fueron declarados con los modelos en la aplicación.
+
+Esa información está disponible en el **JSON Schema** de OpenAPI de la aplicación, y luego se muestra en la documentación de la API (por Swagger UI).
+
+Y esa misma información de los modelos que está incluida en OpenAPI es lo que puede usarse para **generar el código del cliente**.
+
+### Genera un Cliente en TypeScript
+
+Ahora que tenemos la aplicación con los modelos, podemos generar el código del cliente para el frontend.
+
+#### Instalar `openapi-ts`
+
+Puedes instalar `openapi-ts` en tu código de frontend con:
+
+<div class="termy">
+
+```console
+$ npm install @hey-api/openapi-ts --save-dev
+
+---> 100%
+```
+
+</div>
+
+#### Generar el Código del Cliente
+
+Para generar el código del cliente puedes usar la aplicación de línea de comandos `openapi-ts` que ahora estaría instalada.
+
+Como está instalada en el proyecto local, probablemente no podrías llamar a ese comando directamente, pero podrías ponerlo en tu archivo `package.json`.
+
+Podría verse como esto:
+
+```JSON  hl_lines="7"
+{
+  "name": "frontend-app",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "generate-client": "openapi-ts --input http://localhost:8000/openapi.json --output ./src/client --client axios"
+  },
+  "author": "",
+  "license": "",
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.27.38",
+    "typescript": "^4.6.2"
+  }
+}
+```
+
+Después de tener ese script de NPM `generate-client` allí, puedes ejecutarlo con:
+
+<div class="termy">
+
+```console
+$ npm run generate-client
+
+frontend-app@1.0.0 generate-client /home/user/code/frontend-app
+> openapi-ts --input http://localhost:8000/openapi.json --output ./src/client --client axios
+```
+
+</div>
+
+Ese comando generará código en `./src/client` y usará `axios` (el paquete HTTP de frontend) internamente.
+
+### Prueba el Código del Cliente
+
+Ahora puedes importar y usar el código del cliente, podría verse así, nota que tienes autocompletado para los métodos:
+
+<img src="/img/tutorial/generate-clients/image02.png">
+
+También obtendrás autocompletado para el payload a enviar:
+
+<img src="/img/tutorial/generate-clients/image03.png">
+
+/// tip | Consejo
+
+Nota el autocompletado para `name` y `price`, que fue definido en la aplicación de FastAPI, en el modelo `Item`.
+
+///
+
+Tendrás errores en línea para los datos que envíes:
+
+<img src="/img/tutorial/generate-clients/image04.png">
+
+El objeto de response también tendrá autocompletado:
+
+<img src="/img/tutorial/generate-clients/image05.png">
+
+## App de FastAPI con Tags
+
+En muchos casos tu aplicación de FastAPI será más grande, y probablemente usarás tags para separar diferentes grupos de *path operations*.
+
+Por ejemplo, podrías tener una sección para **items** y otra sección para **usuarios**, y podrían estar separadas por tags:
+
+{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
+
+### Genera un Cliente TypeScript con Tags
+
+Si generas un cliente para una aplicación de FastAPI usando tags, normalmente también separará el código del cliente basándose en los tags.
+
+De esta manera podrás tener las cosas ordenadas y agrupadas correctamente para el código del cliente:
+
+<img src="/img/tutorial/generate-clients/image06.png">
+
+En este caso tienes:
+
+* `ItemsService`
+* `UsersService`
+
+### Nombres de los Métodos del Cliente
+
+Ahora mismo los nombres de los métodos generados como `createItemItemsPost` no se ven muy limpios:
+
+```TypeScript
+ItemsService.createItemItemsPost({name: "Plumbus", price: 5})
+```
+
+...eso es porque el generador del cliente usa el **operation ID** interno de OpenAPI para cada *path operation*.
+
+OpenAPI requiere que cada operation ID sea único a través de todas las *path operations*, por lo que FastAPI usa el **nombre de la función**, el **path**, y el **método/operación HTTP** para generar ese operation ID, porque de esa manera puede asegurarse de que los operation IDs sean únicos.
+
+Pero te mostraré cómo mejorar eso a continuación. 🤓
+
+## Operation IDs Personalizados y Mejores Nombres de Métodos
+
+Puedes **modificar** la forma en que estos operation IDs son **generados** para hacerlos más simples y tener **nombres de métodos más simples** en los clientes.
+
+En este caso tendrás que asegurarte de que cada operation ID sea **único** de alguna otra manera.
+
+Por ejemplo, podrías asegurarte de que cada *path operation* tenga un tag, y luego generar el operation ID basado en el **tag** y el nombre de la *path operation* **name** (el nombre de la función).
+
+### Función Personalizada para Generar ID Único
+
+FastAPI usa un **ID único** para cada *path operation*, se usa para el **operation ID** y también para los nombres de cualquier modelo personalizado necesario, para requests o responses.
+
+Puedes personalizar esa función. Toma un `APIRoute` y retorna un string.
+
+Por ejemplo, aquí está usando el primer tag (probablemente tendrás solo un tag) y el nombre de la *path operation* (el nombre de la función).
+
+Puedes entonces pasar esa función personalizada a **FastAPI** como el parámetro `generate_unique_id_function`:
+
+{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
+
+### Generar un Cliente TypeScript con Operation IDs Personalizados
+
+Ahora si generas el cliente de nuevo, verás que tiene los nombres de métodos mejorados:
+
+<img src="/img/tutorial/generate-clients/image07.png">
+
+Como ves, los nombres de métodos ahora tienen el tag y luego el nombre de la función, ahora no incluyen información del path de la URL y la operación HTTP.
+
+### Preprocesa la Especificación OpenAPI para el Generador de Clientes
+
+El código generado aún tiene algo de **información duplicada**.
+
+Ya sabemos que este método está relacionado con los **items** porque esa palabra está en el `ItemsService` (tomado del tag), pero aún tenemos el nombre del tag prefijado en el nombre del método también. 😕
+
+Probablemente aún querremos mantenerlo para OpenAPI en general, ya que eso asegurará que los operation IDs sean **únicos**.
+
+Pero para el cliente generado podríamos **modificar** los operation IDs de OpenAPI justo antes de generar los clientes, solo para hacer esos nombres de métodos más bonitos y **limpios**.
+
+Podríamos descargar el JSON de OpenAPI a un archivo `openapi.json` y luego podríamos **remover ese tag prefijado** con un script como este:
+
+{* ../../docs_src/generate_clients/tutorial004.py *}
+
+//// tab | Node.js
+
+```Javascript
+{!> ../../docs_src/generate_clients/tutorial004.js!}
+```
+
+////
+
+Con eso, los operation IDs serían renombrados de cosas como `items-get_items` a solo `get_items`, de esa manera el generador del cliente puede generar nombres de métodos más simples.
+
+### Generar un Cliente TypeScript con el OpenAPI Preprocesado
+
+Ahora como el resultado final está en un archivo `openapi.json`, modificarías el `package.json` para usar ese archivo local, por ejemplo:
+
+```JSON  hl_lines="7"
+{
+  "name": "frontend-app",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "generate-client": "openapi-ts --input ./openapi.json --output ./src/client --client axios"
+  },
+  "author": "",
+  "license": "",
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.27.38",
+    "typescript": "^4.6.2"
+  }
+}
+```
+
+Después de generar el nuevo cliente, ahora tendrías nombres de métodos **limpios**, con todo el **autocompletado**, **errores en línea**, etc:
+
+<img src="/img/tutorial/generate-clients/image08.png">
+
+## Beneficios
+
+Cuando usas los clientes generados automáticamente obtendrás **autocompletado** para:
+
+* Métodos.
+* Payloads de peticiones en el cuerpo, parámetros de query, etc.
+* Payloads de responses.
+
+También tendrás **errores en línea** para todo.
+
+Y cada vez que actualices el código del backend, y **regeneres** el frontend, tendrás las nuevas *path operations* disponibles como métodos, las antiguas eliminadas, y cualquier otro cambio se reflejará en el código generado. 🤓
+
+Esto también significa que si algo cambió será **reflejado** automáticamente en el código del cliente. Y si haces **build** del cliente, te dará error si tienes algún **desajuste** en los datos utilizados.
+
+Así que, **detectarás muchos errores** muy temprano en el ciclo de desarrollo en lugar de tener que esperar a que los errores se muestren a tus usuarios finales en producción para luego intentar depurar dónde está el problema. ✨

docs/es/docs/advanced/index.md

@@ -0,0 +1,36 @@
+# Guía avanzada del usuario
+
+## Funcionalidades adicionales
+
+El [Tutorial - Guía del usuario](../tutorial/index.md){.internal-link target=_blank} principal debería ser suficiente para darte un recorrido por todas las funcionalidades principales de **FastAPI**.
+
+En las siguientes secciones verás otras opciones, configuraciones y funcionalidades adicionales.
+
+/// tip | Consejo
+
+Las siguientes secciones **no son necesariamente "avanzadas"**.
+
+Y es posible que para tu caso de uso, la solución esté en una de ellas.
+
+///
+
+## Lee primero el Tutorial
+
+Aún podrías usar la mayoría de las funcionalidades en **FastAPI** con el conocimiento del [Tutorial - Guía del usuario](../tutorial/index.md){.internal-link target=_blank} principal.
+
+Y las siguientes secciones asumen que ya lo leíste y que conoces esas ideas principales.
+
+## Cursos externos
+
+Aunque el [Tutorial - Guía del usuario](../tutorial/index.md){.internal-link target=_blank} y esta **Guía avanzada del usuario** están escritos como un tutorial guiado (como un libro) y deberían ser suficientes para que **aprendas FastAPI**, podrías querer complementarlo con cursos adicionales.
+
+O podría ser que simplemente prefieras tomar otros cursos porque se adaptan mejor a tu estilo de aprendizaje.
+
+Algunos proveedores de cursos ✨ [**sponsorean FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, esto asegura el desarrollo continuo y saludable de FastAPI y su **ecosistema**.
+
+Y muestra su verdadero compromiso con FastAPI y su **comunidad** (tú), ya que no solo quieren brindarte una **buena experiencia de aprendizaje** sino que también quieren asegurarse de que tengas un **buen y saludable framework**, FastAPI. 🙇
+
+Podrías querer probar sus cursos:
+
+* <a href="https://training.talkpython.fm/fastapi-courses" class="external-link" target="_blank">Talk Python Training</a>
+* <a href="https://testdriven.io/courses/tdd-fastapi/" class="external-link" target="_blank">Desarrollo guiado por pruebas</a>

docs/es/docs/advanced/middleware.md

@@ -0,0 +1,96 @@
+# Middleware Avanzado
+
+En el tutorial principal leíste cómo agregar [Middleware Personalizado](../tutorial/middleware.md){.internal-link target=_blank} a tu aplicación.
+
+Y luego también leíste cómo manejar [CORS con el `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}.
+
+En esta sección veremos cómo usar otros middlewares.
+
+## Agregando middlewares ASGI
+
+Como **FastAPI** está basado en Starlette e implementa la especificación <abbr title="Asynchronous Server Gateway Interface">ASGI</abbr>, puedes usar cualquier middleware ASGI.
+
+Un middleware no tiene que estar hecho para FastAPI o Starlette para funcionar, siempre que siga la especificación ASGI.
+
+En general, los middlewares ASGI son clases que esperan recibir una aplicación ASGI como primer argumento.
+
+Entonces, en la documentación de middlewares ASGI de terceros probablemente te indicarán que hagas algo como:
+
+```Python
+from unicorn import UnicornMiddleware
+
+app = SomeASGIApp()
+
+new_app = UnicornMiddleware(app, some_config="rainbow")
+```
+
+Pero FastAPI (en realidad Starlette) proporciona una forma más simple de hacerlo que asegura que los middlewares internos manejen errores del servidor y los controladores de excepciones personalizadas funcionen correctamente.
+
+Para eso, usas `app.add_middleware()` (como en el ejemplo para CORS).
+
+```Python
+from fastapi import FastAPI
+from unicorn import UnicornMiddleware
+
+app = FastAPI()
+
+app.add_middleware(UnicornMiddleware, some_config="rainbow")
+```
+
+`app.add_middleware()` recibe una clase de middleware como primer argumento y cualquier argumento adicional que se le quiera pasar al middleware.
+
+## Middlewares integrados
+
+**FastAPI** incluye varios middlewares para casos de uso común, veremos a continuación cómo usarlos.
+
+/// note | Detalles Técnicos
+
+Para los próximos ejemplos, también podrías usar `from starlette.middleware.something import SomethingMiddleware`.
+
+**FastAPI** proporciona varios middlewares en `fastapi.middleware` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los middlewares disponibles provienen directamente de Starlette.
+
+///
+
+## `HTTPSRedirectMiddleware`
+
+Impone que todas las requests entrantes deben ser `https` o `wss`.
+
+Cualquier request entrante a `http` o `ws` será redirigida al esquema seguro.
+
+{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
+
+## `TrustedHostMiddleware`
+
+Impone que todas las requests entrantes tengan correctamente configurado el header `Host`, para proteger contra ataques de HTTP Host Header.
+
+{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
+
+Se soportan los siguientes argumentos:
+
+* `allowed_hosts` - Una list de nombres de dominio que deberían ser permitidos como nombres de host. Se soportan dominios comodín como `*.example.com` para hacer coincidir subdominios. Para permitir cualquier nombre de host, usa `allowed_hosts=["*"]` u omite el middleware.
+
+Si una request entrante no se valida correctamente, se enviará un response `400`.
+
+## `GZipMiddleware`
+
+Maneja responses GZip para cualquier request que incluya `"gzip"` en el header `Accept-Encoding`.
+
+El middleware manejará tanto responses estándar como en streaming.
+
+{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
+
+Se soportan los siguientes argumentos:
+
+* `minimum_size` - No comprimir con GZip responses que sean más pequeñas que este tamaño mínimo en bytes. Por defecto es `500`.
+* `compresslevel` - Usado durante la compresión GZip. Es un entero que varía de 1 a 9. Por defecto es `9`. Un valor más bajo resulta en una compresión más rápida pero archivos más grandes, mientras que un valor más alto resulta en una compresión más lenta pero archivos más pequeños.
+
+## Otros middlewares
+
+Hay muchos otros middlewares ASGI.
+
+Por ejemplo:
+
+* <a href="https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py" class="external-link" target="_blank">`ProxyHeadersMiddleware` de Uvicorn</a>
+* <a href="https://github.com/florimondmanca/msgpack-asgi" class="external-link" target="_blank">MessagePack</a>
+
+Para ver otros middlewares disponibles, revisa <a href="https://www.starlette.dev/middleware/" class="external-link" target="_blank">la documentación de Middleware de Starlette</a> y la <a href="https://github.com/florimondmanca/awesome-asgi" class="external-link" target="_blank">Lista ASGI Awesome</a>.

docs/es/docs/advanced/openapi-callbacks.md

@@ -0,0 +1,186 @@
+# OpenAPI Callbacks
+
+Podrías crear una API con una *path operation* que podría desencadenar un request a una *API externa* creada por alguien más (probablemente el mismo desarrollador que estaría *usando* tu API).
+
+El proceso que ocurre cuando tu aplicación API llama a la *API externa* se llama un "callback". Porque el software que escribió el desarrollador externo envía un request a tu API y luego tu API *responde*, enviando un request a una *API externa* (que probablemente fue creada por el mismo desarrollador).
+
+En este caso, podrías querer documentar cómo esa API externa *debería* verse. Qué *path operation* debería tener, qué cuerpo debería esperar, qué response debería devolver, etc.
+
+## Una aplicación con callbacks
+
+Veamos todo esto con un ejemplo.
+
+Imagina que desarrollas una aplicación que permite crear facturas.
+
+Estas facturas tendrán un `id`, `title` (opcional), `customer`, y `total`.
+
+El usuario de tu API (un desarrollador externo) creará una factura en tu API con un request POST.
+
+Luego tu API (imaginemos):
+
+* Enviará la factura a algún cliente del desarrollador externo.
+* Recogerá el dinero.
+* Enviará una notificación de vuelta al usuario de la API (el desarrollador externo).
+    * Esto se hará enviando un request POST (desde *tu API*) a alguna *API externa* proporcionada por ese desarrollador externo (este es el "callback").
+
+## La aplicación normal de **FastAPI**
+
+Primero veamos cómo sería la aplicación API normal antes de agregar el callback.
+
+Tendrá una *path operation* que recibirá un cuerpo `Invoice`, y un parámetro de query `callback_url` que contendrá la URL para el callback.
+
+Esta parte es bastante normal, probablemente ya estés familiarizado con la mayor parte del código:
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *}
+
+/// tip | Consejo
+
+El parámetro de query `callback_url` utiliza un tipo <a href="https://docs.pydantic.dev/latest/api/networks/" class="external-link" target="_blank">Url</a> de Pydantic.
+
+///
+
+Lo único nuevo es el `callbacks=invoices_callback_router.routes` como un argumento para el *decorador de path operation*. Veremos qué es eso a continuación.
+
+## Documentar el callback
+
+El código real del callback dependerá mucho de tu propia aplicación API.
+
+Y probablemente variará mucho de una aplicación a otra.
+
+Podría ser solo una o dos líneas de código, como:
+
+```Python
+callback_url = "https://example.com/api/v1/invoices/events/"
+httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
+```
+
+Pero posiblemente la parte más importante del callback es asegurarse de que el usuario de tu API (el desarrollador externo) implemente la *API externa* correctamente, de acuerdo con los datos que *tu API* va a enviar en el request body del callback, etc.
+
+Entonces, lo que haremos a continuación es agregar el código para documentar cómo debería verse esa *API externa* para recibir el callback de *tu API*.
+
+Esa documentación aparecerá en la Swagger UI en `/docs` en tu API, y permitirá a los desarrolladores externos saber cómo construir la *API externa*.
+
+Este ejemplo no implementa el callback en sí (eso podría ser solo una línea de código), solo la parte de documentación.
+
+/// tip | Consejo
+
+El callback real es solo un request HTTP.
+
+Cuando implementes el callback tú mismo, podrías usar algo como <a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPX</a> o <a href="https://requests.readthedocs.io/" class="external-link" target="_blank">Requests</a>.
+
+///
+
+## Escribir el código de documentación del callback
+
+Este código no se ejecutará en tu aplicación, solo lo necesitamos para *documentar* cómo debería verse esa *API externa*.
+
+Pero, ya sabes cómo crear fácilmente documentación automática para una API con **FastAPI**.
+
+Así que vamos a usar ese mismo conocimiento para documentar cómo debería verse la *API externa*... creando la(s) *path operation(s)* que la API externa debería implementar (las que tu API va a llamar).
+
+/// tip | Consejo
+
+Cuando escribas el código para documentar un callback, podría ser útil imaginar que eres ese *desarrollador externo*. Y que actualmente estás implementando la *API externa*, no *tu API*.
+
+Adoptar temporalmente este punto de vista (del *desarrollador externo*) puede ayudarte a sentir que es más obvio dónde poner los parámetros, el modelo de Pydantic para el body, para el response, etc. para esa *API externa*.
+
+///
+
+### Crear un `APIRouter` de callback
+
+Primero crea un nuevo `APIRouter` que contendrá uno o más callbacks.
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
+
+### Crear la *path operation* del callback
+
+Para crear la *path operation* del callback utiliza el mismo `APIRouter` que creaste anteriormente.
+
+Debería verse como una *path operation* normal de FastAPI:
+
+* Probablemente debería tener una declaración del body que debería recibir, por ejemplo `body: InvoiceEvent`.
+* Y también podría tener una declaración del response que debería devolver, por ejemplo `response_model=InvoiceEventReceived`.
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
+
+Hay 2 diferencias principales respecto a una *path operation* normal:
+
+* No necesita tener ningún código real, porque tu aplicación nunca llamará a este código. Solo se usa para documentar la *API externa*. Así que, la función podría simplemente tener `pass`.
+* El *path* puede contener una <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">expresión OpenAPI 3</a> (ver más abajo) donde puede usar variables con parámetros y partes del request original enviado a *tu API*.
+
+### La expresión del path del callback
+
+El *path* del callback puede tener una <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">expresión OpenAPI 3</a> que puede contener partes del request original enviado a *tu API*.
+
+En este caso, es el `str`:
+
+```Python
+"{$callback_url}/invoices/{$request.body.id}"
+```
+
+Entonces, si el usuario de tu API (el desarrollador externo) envía un request a *tu API* a:
+
+```
+https://yourapi.com/invoices/?callback_url=https://www.external.org/events
+```
+
+con un JSON body de:
+
+```JSON
+{
+    "id": "2expen51ve",
+    "customer": "Mr. Richie Rich",
+    "total": "9999"
+}
+```
+
+luego *tu API* procesará la factura, y en algún momento después, enviará un request de callback al `callback_url` (la *API externa*):
+
+```
+https://www.external.org/events/invoices/2expen51ve
+```
+
+con un JSON body que contiene algo como:
+
+```JSON
+{
+    "description": "Payment celebration",
+    "paid": true
+}
+```
+
+y esperaría un response de esa *API externa* con un JSON body como:
+
+```JSON
+{
+    "ok": true
+}
+```
+
+/// tip | Consejo
+
+Observa cómo la URL del callback utilizada contiene la URL recibida como parámetro de query en `callback_url` (`https://www.external.org/events`) y también el `id` de la factura desde dentro del JSON body (`2expen51ve`).
+
+///
+
+### Agregar el router de callback
+
+En este punto tienes las *path operation(s)* del callback necesarias (las que el *desarrollador externo* debería implementar en la *API externa*) en el router de callback que creaste antes.
+
+Ahora usa el parámetro `callbacks` en el *decorador de path operation de tu API* para pasar el atributo `.routes` (que en realidad es solo un `list` de rutas/*path operations*) de ese router de callback:
+
+{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
+
+/// tip | Consejo
+
+Observa que no estás pasando el router en sí (`invoices_callback_router`) a `callback=`, sino el atributo `.routes`, como en `invoices_callback_router.routes`.
+
+///
+
+### Revisa la documentación
+
+Ahora puedes iniciar tu aplicación e ir a <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
+
+Verás tu documentación incluyendo una sección de "Callbacks" para tu *path operation* que muestra cómo debería verse la *API externa*:
+
+<img src="/img/tutorial/openapi-callbacks/image01.png">

docs/es/docs/advanced/openapi-webhooks.md

@@ -0,0 +1,55 @@
+# Webhooks de OpenAPI
+
+Hay casos donde quieres decirle a los **usuarios** de tu API que tu aplicación podría llamar a *su* aplicación (enviando una request) con algunos datos, normalmente para **notificar** de algún tipo de **evento**.
+
+Esto significa que en lugar del proceso normal de tus usuarios enviando requests a tu API, es **tu API** (o tu aplicación) la que podría **enviar requests a su sistema** (a su API, su aplicación).
+
+Esto normalmente se llama un **webhook**.
+
+## Pasos de los webhooks
+
+El proceso normalmente es que **tú defines** en tu código cuál es el mensaje que enviarás, el **body de la request**.
+
+También defines de alguna manera en qué **momentos** tu aplicación enviará esas requests o eventos.
+
+Y **tus usuarios** definen de alguna manera (por ejemplo en un panel web en algún lugar) el **URL** donde tu aplicación debería enviar esas requests.
+
+Toda la **lógica** sobre cómo registrar los URLs para webhooks y el código para realmente enviar esas requests depende de ti. Lo escribes como quieras en **tu propio código**.
+
+## Documentando webhooks con **FastAPI** y OpenAPI
+
+Con **FastAPI**, usando OpenAPI, puedes definir los nombres de estos webhooks, los tipos de operaciones HTTP que tu aplicación puede enviar (por ejemplo, `POST`, `PUT`, etc.) y los **bodies** de las requests que tu aplicación enviaría.
+
+Esto puede hacer mucho más fácil para tus usuarios **implementar sus APIs** para recibir tus requests de **webhook**, incluso podrían ser capaces de autogenerar algo de su propio código de API.
+
+/// info | Información
+
+Los webhooks están disponibles en OpenAPI 3.1.0 y superiores, soportados por FastAPI `0.99.0` y superiores.
+
+///
+
+## Una aplicación con webhooks
+
+Cuando creas una aplicación de **FastAPI**, hay un atributo `webhooks` que puedes usar para definir *webhooks*, de la misma manera que definirías *path operations*, por ejemplo con `@app.webhooks.post()`.
+
+{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
+
+Los webhooks que defines terminarán en el esquema de **OpenAPI** y en la interfaz automática de **documentación**.
+
+/// info | Información
+
+El objeto `app.webhooks` es en realidad solo un `APIRouter`, el mismo tipo que usarías al estructurar tu aplicación con múltiples archivos.
+
+///
+
+Nota que con los webhooks en realidad no estás declarando un *path* (como `/items/`), el texto que pasas allí es solo un **identificador** del webhook (el nombre del evento), por ejemplo en `@app.webhooks.post("new-subscription")`, el nombre del webhook es `new-subscription`.
+
+Esto es porque se espera que **tus usuarios** definan el actual **URL path** donde quieren recibir la request del webhook de alguna otra manera (por ejemplo, un panel web).
+
+### Revisa la documentación
+
+Ahora puedes iniciar tu app e ir a <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
+
+Verás que tu documentación tiene las *path operations* normales y ahora también algunos **webhooks**:
+
+<img src="/img/tutorial/openapi-webhooks/image01.png">

docs/es/docs/advanced/path-operation-advanced-configuration.md

@@ -0,0 +1,204 @@
+# Configuración Avanzada de Path Operation
+
+## operationId de OpenAPI
+
+/// warning | Advertencia
+
+Si no eres un "experto" en OpenAPI, probablemente no necesites esto.
+
+///
+
+Puedes establecer el `operationId` de OpenAPI para ser usado en tu *path operation* con el parámetro `operation_id`.
+
+Tienes que asegurarte de que sea único para cada operación.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
+
+### Usar el nombre de la *función de path operation* como el operationId
+
+Si quieres usar los nombres de las funciones de tus APIs como `operationId`s, puedes iterar sobre todas ellas y sobrescribir el `operation_id` de cada *path operation* usando su `APIRoute.name`.
+
+Deberías hacerlo después de agregar todas tus *path operations*.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2, 12:21, 24] *}
+
+/// tip | Consejo
+
+Si llamas manualmente a `app.openapi()`, deberías actualizar los `operationId`s antes de eso.
+
+///
+
+/// warning | Advertencia
+
+Si haces esto, tienes que asegurarte de que cada una de tus *funciones de path operation* tenga un nombre único.
+
+Incluso si están en diferentes módulos (archivos de Python).
+
+///
+
+## Excluir de OpenAPI
+
+Para excluir una *path operation* del esquema OpenAPI generado (y por lo tanto, de los sistemas de documentación automática), utiliza el parámetro `include_in_schema` y configúralo en `False`:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
+
+## Descripción avanzada desde el docstring
+
+Puedes limitar las líneas usadas del docstring de una *función de path operation* para OpenAPI.
+
+Añadir un `\f` (un carácter de separación de página escapado) hace que **FastAPI** trunque la salida usada para OpenAPI en este punto.
+
+No aparecerá en la documentación, pero otras herramientas (como Sphinx) podrán usar el resto.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
+
+## Responses Adicionales
+
+Probablemente has visto cómo declarar el `response_model` y el `status_code` para una *path operation*.
+
+Eso define los metadatos sobre el response principal de una *path operation*.
+
+También puedes declarar responses adicionales con sus modelos, códigos de estado, etc.
+
+Hay un capítulo entero en la documentación sobre ello, puedes leerlo en [Responses Adicionales en OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+## OpenAPI Extra
+
+Cuando declaras una *path operation* en tu aplicación, **FastAPI** genera automáticamente los metadatos relevantes sobre esa *path operation* para incluirlos en el esquema de OpenAPI.
+
+/// note | Nota
+
+En la especificación de OpenAPI se llama el <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object" class="external-link" target="_blank">Objeto de Operación</a>.
+
+///
+
+Tiene toda la información sobre la *path operation* y se usa para generar la documentación automática.
+
+Incluye los `tags`, `parameters`, `requestBody`, `responses`, etc.
+
+Este esquema de OpenAPI específico de *path operation* normalmente se genera automáticamente por **FastAPI**, pero también puedes extenderlo.
+
+/// tip | Consejo
+
+Este es un punto de extensión de bajo nivel.
+
+Si solo necesitas declarar responses adicionales, una forma más conveniente de hacerlo es con [Responses Adicionales en OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+///
+
+Puedes extender el esquema de OpenAPI para una *path operation* usando el parámetro `openapi_extra`.
+
+### Extensiones de OpenAPI
+
+Este `openapi_extra` puede ser útil, por ejemplo, para declarar [Extensiones de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
+
+Si abres la documentación automática de la API, tu extensión aparecerá en la parte inferior de la *path operation* específica.
+
+<img src="/img/tutorial/path-operation-advanced-configuration/image01.png">
+
+Y si ves el OpenAPI resultante (en `/openapi.json` en tu API), verás tu extensión como parte de la *path operation* específica también:
+
+```JSON hl_lines="22"
+{
+    "openapi": "3.1.0",
+    "info": {
+        "title": "FastAPI",
+        "version": "0.1.0"
+    },
+    "paths": {
+        "/items/": {
+            "get": {
+                "summary": "Read Items",
+                "operationId": "read_items_items__get",
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {}
+                            }
+                        }
+                    }
+                },
+                "x-aperture-labs-portal": "blue"
+            }
+        }
+    }
+}
+```
+
+### Esquema de *path operation* personalizada de OpenAPI
+
+El diccionario en `openapi_extra` se combinará profundamente con el esquema de OpenAPI generado automáticamente para la *path operation*.
+
+Por lo tanto, podrías añadir datos adicionales al esquema generado automáticamente.
+
+Por ejemplo, podrías decidir leer y validar el request con tu propio código, sin usar las funcionalidades automáticas de FastAPI con Pydantic, pero aún podrías querer definir el request en el esquema de OpenAPI.
+
+Podrías hacer eso con `openapi_extra`:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[19:36, 39:40] *}
+
+En este ejemplo, no declaramos ningún modelo Pydantic. De hecho, el cuerpo del request ni siquiera se <abbr title="converted from some plain format, like bytes, into Python objects">parse</abbr> como JSON, se lee directamente como `bytes`, y la función `magic_data_reader()` sería la encargada de parsearlo de alguna manera.
+
+Sin embargo, podemos declarar el esquema esperado para el cuerpo del request.
+
+### Tipo de contenido personalizado de OpenAPI
+
+Usando este mismo truco, podrías usar un modelo Pydantic para definir el esquema JSON que luego se incluye en la sección personalizada del esquema OpenAPI para la *path operation*.
+
+Y podrías hacer esto incluso si el tipo de datos en el request no es JSON.
+
+Por ejemplo, en esta aplicación no usamos la funcionalidad integrada de FastAPI para extraer el esquema JSON de los modelos Pydantic ni la validación automática para JSON. De hecho, estamos declarando el tipo de contenido del request como YAML, no JSON:
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22, 24] *}
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[17:22, 24] *}
+
+////
+
+/// info | Información
+
+En la versión 1 de Pydantic el método para obtener el esquema JSON para un modelo se llamaba `Item.schema()`, en la versión 2 de Pydantic, el método se llama `Item.model_json_schema()`.
+
+///
+
+Sin embargo, aunque no estamos usando la funcionalidad integrada por defecto, aún estamos usando un modelo Pydantic para generar manualmente el esquema JSON para los datos que queremos recibir en YAML.
+
+Luego usamos el request directamente, y extraemos el cuerpo como `bytes`. Esto significa que FastAPI ni siquiera intentará parsear la carga útil del request como JSON.
+
+Y luego en nuestro código, parseamos ese contenido YAML directamente, y nuevamente estamos usando el mismo modelo Pydantic para validar el contenido YAML:
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[26:33] *}
+
+////
+
+/// info | Información
+
+En la versión 1 de Pydantic el método para parsear y validar un objeto era `Item.parse_obj()`, en la versión 2 de Pydantic, el método se llama `Item.model_validate()`.
+
+///
+
+/// tip | Consejo
+
+Aquí reutilizamos el mismo modelo Pydantic.
+
+Pero de la misma manera, podríamos haberlo validado de alguna otra forma.
+
+///

docs/es/docs/advanced/response-change-status-code.md

@@ -0,0 +1,31 @@
+# Response - Cambiar Código de Estado
+
+Probablemente leíste antes que puedes establecer un [Código de Estado de Response](../tutorial/response-status-code.md){.internal-link target=_blank} por defecto.
+
+Pero en algunos casos necesitas devolver un código de estado diferente al predeterminado.
+
+## Caso de uso
+
+Por ejemplo, imagina que quieres devolver un código de estado HTTP de "OK" `200` por defecto.
+
+Pero si los datos no existieran, quieres crearlos y devolver un código de estado HTTP de "CREATED" `201`.
+
+Pero todavía quieres poder filtrar y convertir los datos que devuelves con un `response_model`.
+
+Para esos casos, puedes usar un parámetro `Response`.
+
+## Usa un parámetro `Response`
+
+Puedes declarar un parámetro de tipo `Response` en tu *función de path operation* (como puedes hacer para cookies y headers).
+
+Y luego puedes establecer el `status_code` en ese objeto de response *temporal*.
+
+{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
+
+Y luego puedes devolver cualquier objeto que necesites, como lo harías normalmente (un `dict`, un modelo de base de datos, etc.).
+
+Y si declaraste un `response_model`, todavía se utilizará para filtrar y convertir el objeto que devolviste.
+
+**FastAPI** usará ese response *temporal* para extraer el código de estado (también cookies y headers), y los pondrá en el response final que contiene el valor que devolviste, filtrado por cualquier `response_model`.
+
+También puedes declarar el parámetro `Response` en dependencias y establecer el código de estado en ellas. Pero ten en cuenta que el último establecido prevalecerá.

docs/es/docs/advanced/response-cookies.md

@@ -0,0 +1,51 @@
+# Cookies de Response
+
+## Usar un parámetro `Response`
+
+Puedes declarar un parámetro de tipo `Response` en tu *path operation function*.
+
+Y luego puedes establecer cookies en ese objeto de response *temporal*.
+
+{* ../../docs_src/response_cookies/tutorial002.py hl[1, 8:9] *}
+
+Y entonces puedes devolver cualquier objeto que necesites, como normalmente lo harías (un `dict`, un modelo de base de datos, etc).
+
+Y si declaraste un `response_model`, todavía se utilizará para filtrar y convertir el objeto que devolviste.
+
+**FastAPI** utilizará ese response *temporal* para extraer las cookies (también los headers y el código de estado), y las pondrá en el response final que contiene el valor que devolviste, filtrado por cualquier `response_model`.
+
+También puedes declarar el parámetro `Response` en las dependencias, y establecer cookies (y headers) en ellas.
+
+## Devolver una `Response` directamente
+
+También puedes crear cookies al devolver una `Response` directamente en tu código.
+
+Para hacer eso, puedes crear un response como se describe en [Devolver un Response Directamente](response-directly.md){.internal-link target=_blank}.
+
+Luego establece Cookies en ella, y luego devuélvela:
+
+{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
+
+/// tip | Consejo
+
+Ten en cuenta que si devuelves un response directamente en lugar de usar el parámetro `Response`, FastAPI lo devolverá directamente.
+
+Así que tendrás que asegurarte de que tus datos son del tipo correcto. Por ejemplo, que sea compatible con JSON, si estás devolviendo un `JSONResponse`.
+
+Y también que no estés enviando ningún dato que debería haber sido filtrado por un `response_model`.
+
+///
+
+### Más información
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.responses import Response` o `from starlette.responses import JSONResponse`.
+
+**FastAPI** proporciona los mismos `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.
+
+Y como el `Response` se puede usar frecuentemente para establecer headers y cookies, **FastAPI** también lo proporciona en `fastapi.Response`.
+
+///
+
+Para ver todos los parámetros y opciones disponibles, revisa la <a href="https://www.starlette.dev/responses/#set-cookie" class="external-link" target="_blank">documentación en Starlette</a>.

docs/es/docs/advanced/response-directly.md

@@ -0,0 +1,65 @@
+# Devolver una Response Directamente
+
+Cuando creas una *path operation* en **FastAPI**, normalmente puedes devolver cualquier dato desde ella: un `dict`, una `list`, un modelo de Pydantic, un modelo de base de datos, etc.
+
+Por defecto, **FastAPI** convertiría automáticamente ese valor de retorno a JSON usando el `jsonable_encoder` explicado en [JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}.
+
+Luego, detrás de escena, pondría esos datos compatibles con JSON (por ejemplo, un `dict`) dentro de un `JSONResponse` que se usaría para enviar el response al cliente.
+
+Pero puedes devolver un `JSONResponse` directamente desde tus *path operations*.
+
+Esto podría ser útil, por ejemplo, para devolver headers o cookies personalizados.
+
+## Devolver una `Response`
+
+De hecho, puedes devolver cualquier `Response` o cualquier subclase de ella.
+
+/// tip | Consejo
+
+`JSONResponse` en sí misma es una subclase de `Response`.
+
+///
+
+Y cuando devuelves una `Response`, **FastAPI** la pasará directamente.
+
+No hará ninguna conversión de datos con los modelos de Pydantic, no convertirá los contenidos a ningún tipo, etc.
+
+Esto te da mucha flexibilidad. Puedes devolver cualquier tipo de datos, sobrescribir cualquier declaración o validación de datos, etc.
+
+## Usar el `jsonable_encoder` en una `Response`
+
+Como **FastAPI** no realiza cambios en una `Response` que devuelves, tienes que asegurarte de que sus contenidos estén listos para ello.
+
+Por ejemplo, no puedes poner un modelo de Pydantic en un `JSONResponse` sin primero convertirlo a un `dict` con todos los tipos de datos (como `datetime`, `UUID`, etc.) convertidos a tipos compatibles con JSON.
+
+Para esos casos, puedes usar el `jsonable_encoder` para convertir tus datos antes de pasarlos a un response:
+
+{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
+
+/// note | Nota
+
+También podrías usar `from starlette.responses import JSONResponse`.
+
+**FastAPI** proporciona los mismos `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.
+
+///
+
+## Devolver una `Response` personalizada
+
+El ejemplo anterior muestra todas las partes que necesitas, pero aún no es muy útil, ya que podrías haber devuelto el `item` directamente, y **FastAPI** lo colocaría en un `JSONResponse` por ti, convirtiéndolo a un `dict`, etc. Todo eso por defecto.
+
+Ahora, veamos cómo podrías usar eso para devolver un response personalizado.
+
+Digamos que quieres devolver un response en <a href="https://en.wikipedia.org/wiki/XML" class="external-link" target="_blank">XML</a>.
+
+Podrías poner tu contenido XML en un string, poner eso en un `Response`, y devolverlo:
+
+{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+
+## Notas
+
+Cuando devuelves una `Response` directamente, sus datos no son validados, convertidos (serializados), ni documentados automáticamente.
+
+Pero aún puedes documentarlo como se describe en [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+Puedes ver en secciones posteriores cómo usar/declarar estas `Response`s personalizadas mientras todavía tienes conversión automática de datos, documentación, etc.

docs/es/docs/advanced/response-headers.md

@@ -0,0 +1,41 @@
+# Response Headers
+
+## Usa un parámetro `Response`
+
+Puedes declarar un parámetro de tipo `Response` en tu *función de path operation* (como puedes hacer para cookies).
+
+Y luego puedes establecer headers en ese objeto de response *temporal*.
+
+{* ../../docs_src/response_headers/tutorial002.py hl[1, 7:8] *}
+
+Y luego puedes devolver cualquier objeto que necesites, como harías normalmente (un `dict`, un modelo de base de datos, etc).
+
+Y si declaraste un `response_model`, aún se usará para filtrar y convertir el objeto que devolviste.
+
+**FastAPI** usará ese response *temporal* para extraer los headers (también cookies y el código de estado), y los pondrá en el response final que contiene el valor que devolviste, filtrado por cualquier `response_model`.
+
+También puedes declarar el parámetro `Response` en dependencias y establecer headers (y cookies) en ellas.
+
+## Retorna una `Response` directamente
+
+También puedes agregar headers cuando devuelves un `Response` directamente.
+
+Crea un response como se describe en [Retorna un Response Directamente](response-directly.md){.internal-link target=_blank} y pasa los headers como un parámetro adicional:
+
+{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.responses import Response` o `from starlette.responses import JSONResponse`.
+
+**FastAPI** proporciona las mismas `starlette.responses` como `fastapi.responses` solo por conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles provienen directamente de Starlette.
+
+Y como el `Response` se puede usar frecuentemente para establecer headers y cookies, **FastAPI** también lo proporciona en `fastapi.Response`.
+
+///
+
+## Headers Personalizados
+
+Ten en cuenta que los headers propietarios personalizados se pueden agregar <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 headers personalizados que quieres que un cliente en un navegador pueda ver, necesitas agregarlos a tus configuraciones de CORS (leer más en [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), usando el parámetro `expose_headers` documentado en <a href="https://www.starlette.dev/middleware/#corsmiddleware" class="external-link" target="_blank">la documentación CORS de Starlette</a>.

docs/es/docs/advanced/security/http-basic-auth.md

@@ -0,0 +1,107 @@
+# HTTP Basic Auth
+
+Para los casos más simples, puedes usar HTTP Basic Auth.
+
+En HTTP Basic Auth, la aplicación espera un header que contiene un nombre de usuario y una contraseña.
+
+Si no lo recibe, devuelve un error HTTP 401 "Unauthorized".
+
+Y devuelve un header `WWW-Authenticate` con un valor de `Basic`, y un parámetro `realm` opcional.
+
+Eso le dice al navegador que muestre el prompt integrado para un nombre de usuario y contraseña.
+
+Luego, cuando escribes ese nombre de usuario y contraseña, el navegador los envía automáticamente en el header.
+
+## Simple HTTP Basic Auth
+
+* Importa `HTTPBasic` y `HTTPBasicCredentials`.
+* Crea un "esquema de `security`" usando `HTTPBasic`.
+* Usa ese `security` con una dependencia en tu *path operation*.
+* Devuelve un objeto de tipo `HTTPBasicCredentials`:
+  * Contiene el `username` y `password` enviados.
+
+{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}
+
+Cuando intentas abrir la URL por primera vez (o haces clic en el botón "Execute" en la documentación) el navegador te pedirá tu nombre de usuario y contraseña:
+
+<img src="/img/tutorial/security/image12.png">
+
+## Revisa el nombre de usuario
+
+Aquí hay un ejemplo más completo.
+
+Usa una dependencia para comprobar si el nombre de usuario y la contraseña son correctos.
+
+Para esto, usa el módulo estándar de Python <a href="https://docs.python.org/3/library/secrets.html" class="external-link" target="_blank">`secrets`</a> para verificar el nombre de usuario y la contraseña.
+
+`secrets.compare_digest()` necesita tomar `bytes` o un `str` que solo contenga caracteres ASCII (los carácteres en inglés), esto significa que no funcionaría con caracteres como `á`, como en `Sebastián`.
+
+Para manejar eso, primero convertimos el `username` y `password` a `bytes` codificándolos con UTF-8.
+
+Luego podemos usar `secrets.compare_digest()` para asegurar que `credentials.username` es `"stanleyjobson"`, y que `credentials.password` es `"swordfish"`.
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *}
+
+Esto sería similar a:
+
+```Python
+if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
+    # Return some error
+    ...
+```
+
+Pero al usar `secrets.compare_digest()` será seguro contra un tipo de ataques llamados "timing attacks".
+
+### Timing Attacks
+
+¿Pero qué es un "timing attack"?
+
+Imaginemos que algunos atacantes están tratando de adivinar el nombre de usuario y la contraseña.
+
+Y envían un request con un nombre de usuario `johndoe` y una contraseña `love123`.
+
+Entonces el código de Python en tu aplicación equivaldría a algo como:
+
+```Python
+if "johndoe" == "stanleyjobson" and "love123" == "swordfish":
+    ...
+```
+
+Pero justo en el momento en que Python compara la primera `j` en `johndoe` con la primera `s` en `stanleyjobson`, devolverá `False`, porque ya sabe que esas dos strings no son iguales, pensando que "no hay necesidad de gastar más computación comparando el resto de las letras". Y tu aplicación dirá "Nombre de usuario o contraseña incorrectos".
+
+Pero luego los atacantes prueban con el nombre de usuario `stanleyjobsox` y contraseña `love123`.
+
+Y el código de tu aplicación hace algo así como:
+
+```Python
+if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
+    ...
+```
+
+Python tendrá que comparar todo `stanleyjobso` en ambos `stanleyjobsox` y `stanleyjobson` antes de darse cuenta de que ambas strings no son las mismas. Así que tomará algunos microsegundos extra para responder "Nombre de usuario o contraseña incorrectos".
+
+#### El tiempo de respuesta ayuda a los atacantes
+
+En ese punto, al notar que el servidor tardó algunos microsegundos más en enviar el response "Nombre de usuario o contraseña incorrectos", los atacantes sabrán que acertaron en _algo_, algunas de las letras iniciales eran correctas.
+
+Y luego pueden intentar de nuevo sabiendo que probablemente es algo más similar a `stanleyjobsox` que a `johndoe`.
+
+#### Un ataque "profesional"
+
+Por supuesto, los atacantes no intentarían todo esto a mano, escribirían un programa para hacerlo, posiblemente con miles o millones de pruebas por segundo. Y obtendrían solo una letra correcta adicional a la vez.
+
+Pero haciendo eso, en algunos minutos u horas, los atacantes habrían adivinado el nombre de usuario y la contraseña correctos, con la "ayuda" de nuestra aplicación, solo usando el tiempo tomado para responder.
+
+#### Arréglalo con `secrets.compare_digest()`
+
+Pero en nuestro código estamos usando realmente `secrets.compare_digest()`.
+
+En resumen, tomará el mismo tiempo comparar `stanleyjobsox` con `stanleyjobson` que comparar `johndoe` con `stanleyjobson`. Y lo mismo para la contraseña.
+
+De esa manera, usando `secrets.compare_digest()` en el código de tu aplicación, será seguro contra todo este rango de ataques de seguridad.
+
+### Devuelve el error
+
+Después de detectar que las credenciales son incorrectas, regresa un `HTTPException` con un código de estado 401 (el mismo que se devuelve cuando no se proporcionan credenciales) y agrega el header `WWW-Authenticate` para que el navegador muestre el prompt de inicio de sesión nuevamente:
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}

docs/es/docs/advanced/security/index.md

@@ -0,0 +1,19 @@
+# Seguridad Avanzada
+
+## Funcionalidades Adicionales
+
+Hay algunas funcionalidades extra para manejar la seguridad aparte de las cubiertas en el [Tutorial - Guía del Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+/// tip | Consejo
+
+Las siguientes secciones **no son necesariamente "avanzadas"**.
+
+Y es posible que para tu caso de uso, la solución esté en una de ellas.
+
+///
+
+## Lee primero el Tutorial
+
+Las siguientes secciones asumen que ya leíste el [Tutorial - Guía del Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+Todas están basadas en los mismos conceptos, pero permiten algunas funcionalidades adicionales.

docs/es/docs/advanced/security/oauth2-scopes.md

@@ -0,0 +1,274 @@
+# Scopes de OAuth2
+
+Puedes usar scopes de OAuth2 directamente con **FastAPI**, están integrados para funcionar de manera fluida.
+
+Esto te permitiría tener un sistema de permisos más detallado, siguiendo el estándar de OAuth2, integrado en tu aplicación OpenAPI (y la documentación de la API).
+
+OAuth2 con scopes es el mecanismo usado por muchos grandes proveedores de autenticación, como Facebook, Google, GitHub, Microsoft, X (Twitter), etc. Lo usan para proporcionar permisos específicos a usuarios y aplicaciones.
+
+Cada vez que te "logueas con" Facebook, Google, GitHub, Microsoft, X (Twitter), esa aplicación está usando OAuth2 con scopes.
+
+En esta sección verás cómo manejar autenticación y autorización con el mismo OAuth2 con scopes en tu aplicación de **FastAPI**.
+
+/// warning | Advertencia
+
+Esta es una sección más o menos avanzada. Si estás comenzando, puedes saltarla.
+
+No necesariamente necesitas scopes de OAuth2, y puedes manejar autenticación y autorización como quieras.
+
+Pero OAuth2 con scopes se puede integrar muy bien en tu API (con OpenAPI) y en la documentación de tu API.
+
+No obstante, tú aún impones esos scopes, o cualquier otro requisito de seguridad/autorización, como necesites, en tu código.
+
+En muchos casos, OAuth2 con scopes puede ser un exceso.
+
+Pero si sabes que lo necesitas, o tienes curiosidad, sigue leyendo.
+
+///
+
+## Scopes de OAuth2 y OpenAPI
+
+La especificación de OAuth2 define "scopes" como una lista de strings separados por espacios.
+
+El contenido de cada uno de estos strings puede tener cualquier formato, pero no debe contener espacios.
+
+Estos scopes representan "permisos".
+
+En OpenAPI (por ejemplo, en la documentación de la API), puedes definir "esquemas de seguridad".
+
+Cuando uno de estos esquemas de seguridad usa OAuth2, también puedes declarar y usar scopes.
+
+Cada "scope" es solo 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.
+
+///
+
+## Vista global
+
+Primero, echemos un vistazo rápido a las partes que cambian desde los ejemplos en el **Tutorial - User Guide** principal para [OAuth2 con Password (y hashing), Bearer con tokens JWT](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Ahora usando scopes de OAuth2:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:125,129:135,140,156] *}
+
+Ahora revisemos esos cambios paso a paso.
+
+## Esquema de seguridad OAuth2
+
+El primer cambio es que ahora estamos declarando el esquema de seguridad OAuth2 con dos scopes disponibles, `me` y `items`.
+
+El parámetro `scopes` recibe un `dict` con cada scope como clave y la descripción como valor:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
+
+Como ahora estamos declarando esos scopes, aparecerán en la documentación de la API cuando inicies sesión/autorices.
+
+Y podrás seleccionar cuáles scopes quieres dar de acceso: `me` y `items`.
+
+Este es el mismo mecanismo utilizado cuando das permisos al iniciar sesión con Facebook, Google, GitHub, etc:
+
+<img src="/img/tutorial/security/image11.png">
+
+## Token JWT con scopes
+
+Ahora, modifica la *path operation* del token para devolver los scopes solicitados.
+
+Todavía estamos usando el mismo `OAuth2PasswordRequestForm`. Incluye una propiedad `scopes` con una `list` de `str`, con cada scope que recibió en el request.
+
+Y devolvemos los scopes como parte del token JWT.
+
+/// danger | Peligro
+
+Para simplificar, aquí solo estamos añadiendo los scopes recibidos directamente al token.
+
+Pero en tu aplicación, por seguridad, deberías asegurarte de añadir solo los scopes que el usuario realmente puede tener, o los que has predefinido.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *}
+
+## Declarar scopes en *path operations* y dependencias
+
+Ahora declaramos que la *path operation* para `/users/me/items/` requiere el scope `items`.
+
+Para esto, importamos y usamos `Security` de `fastapi`.
+
+Puedes usar `Security` para declarar dependencias (igual que `Depends`), pero `Security` también recibe un parámetro `scopes` con una lista de scopes (strings).
+
+En este caso, pasamos una función de dependencia `get_current_active_user` a `Security` (de la misma manera que haríamos con `Depends`).
+
+Pero también pasamos una `list` de scopes, en este caso con solo un scope: `items` (podría tener más).
+
+Y la función de dependencia `get_current_active_user` también puede declarar sub-dependencias, no solo con `Depends` sino también con `Security`. Declarando su propia función de sub-dependencia (`get_current_user`), y más requisitos de scope.
+
+En este caso, requiere el scope `me` (podría requerir más de un scope).
+
+/// note | Nota
+
+No necesariamente necesitas añadir diferentes scopes en diferentes lugares.
+
+Lo estamos haciendo aquí para demostrar cómo **FastAPI** maneja scopes declarados en diferentes niveles.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *}
+
+/// info | Información Técnica
+
+`Security` es en realidad una subclase de `Depends`, y tiene solo un parámetro extra que veremos más adelante.
+
+Pero al usar `Security` en lugar de `Depends`, **FastAPI** sabrá que puede declarar scopes de seguridad, usarlos internamente y documentar la API con OpenAPI.
+
+Pero cuando importas `Query`, `Path`, `Depends`, `Security` y otros de `fastapi`, en realidad son funciones que devuelven clases especiales.
+
+///
+
+## Usar `SecurityScopes`
+
+Ahora actualiza la dependencia `get_current_user`.
+
+Esta es la que usan las dependencias anteriores.
+
+Aquí es donde estamos usando el mismo esquema de OAuth2 que creamos antes, declarándolo como una dependencia: `oauth2_scheme`.
+
+Porque esta función de dependencia no tiene ningún requisito de scope en sí, podemos usar `Depends` con `oauth2_scheme`, no tenemos que usar `Security` cuando no necesitamos especificar scopes de seguridad.
+
+También declaramos un parámetro especial de tipo `SecurityScopes`, importado de `fastapi.security`.
+
+Esta clase `SecurityScopes` es similar a `Request` (`Request` se usó para obtener el objeto request directamente).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
+
+## Usar los `scopes`
+
+El parámetro `security_scopes` será del tipo `SecurityScopes`.
+
+Tendrá una propiedad `scopes` con una lista que contiene todos los scopes requeridos por sí mismo y por todas las dependencias que lo usan como sub-dependencia. Eso significa, todos los "dependientes"... esto podría sonar confuso, se explica de nuevo más abajo.
+
+El objeto `security_scopes` (de la clase `SecurityScopes`) también proporciona un atributo `scope_str` con un único string, que contiene esos scopes separados por espacios (lo vamos a usar).
+
+Creamos una `HTTPException` que podemos reutilizar (`raise`) más tarde en varios puntos.
+
+En esta excepción, incluimos los scopes requeridos (si los hay) como un string separado por espacios (usando `scope_str`). Ponemos ese string que contiene los scopes en el header `WWW-Authenticate` (esto es parte de la especificación).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
+
+## Verificar el `username` y la forma de los datos
+
+Verificamos que obtenemos un `username`, y extraemos los scopes.
+
+Y luego validamos esos datos con el modelo de Pydantic (capturando la excepción `ValidationError`), y si obtenemos un error leyendo el token JWT o validando los datos con Pydantic, lanzamos la `HTTPException` que creamos antes.
+
+Para eso, actualizamos el modelo de Pydantic `TokenData` con una nueva propiedad `scopes`.
+
+Al validar los datos con Pydantic podemos asegurarnos de que tenemos, por ejemplo, exactamente una `list` de `str` con los scopes y un `str` con el `username`.
+
+En lugar de, por ejemplo, un `dict`, o algo más, ya que podría romper la aplicación en algún punto posterior, haciéndolo un riesgo de seguridad.
+
+También verificamos que tenemos un usuario con ese username, y si no, lanzamos esa misma excepción que creamos antes.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:128] *}
+
+## Verificar los `scopes`
+
+Ahora verificamos que todos los scopes requeridos, por esta dependencia y todos los dependientes (incluyendo *path operations*), estén incluidos en los scopes proporcionados en el token recibido, de lo contrario, lanzamos una `HTTPException`.
+
+Para esto, usamos `security_scopes.scopes`, que contiene una `list` con todos estos scopes como `str`.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[129:135] *}
+
+## Árbol de dependencias y scopes
+
+Revisemos de nuevo este árbol de dependencias y los scopes.
+
+Como la dependencia `get_current_active_user` tiene como sub-dependencia a `get_current_user`, el scope `"me"` declarado en `get_current_active_user` se incluirá en la lista de scopes requeridos en el `security_scopes.scopes` pasado a `get_current_user`.
+
+La *path operation* en sí también declara un scope, `"items"`, por lo que esto también estará en la lista de `security_scopes.scopes` pasado a `get_current_user`.
+
+Así es como se ve la jerarquía de dependencias y scopes:
+
+* La *path operation* `read_own_items` tiene:
+    * Scopes requeridos `["items"]` con la dependencia:
+    * `get_current_active_user`:
+        * La función de dependencia `get_current_active_user` tiene:
+            * Scopes requeridos `["me"]` con la dependencia:
+            * `get_current_user`:
+                * La función de dependencia `get_current_user` tiene:
+                    * No requiere scopes por sí misma.
+                    * Una dependencia usando `oauth2_scheme`.
+                    * Un parámetro `security_scopes` de tipo `SecurityScopes`:
+                        * Este parámetro `security_scopes` tiene una propiedad `scopes` con una `list` que contiene todos estos scopes declarados arriba, por lo que:
+                            * `security_scopes.scopes` contendrá `["me", "items"]` para la *path operation* `read_own_items`.
+                            * `security_scopes.scopes` contendrá `["me"]` para la *path operation* `read_users_me`, porque está declarado en la dependencia `get_current_active_user`.
+                            * `security_scopes.scopes` contendrá `[]` (nada) para la *path operation* `read_system_status`, porque no declaró ningún `Security` con `scopes`, y su dependencia, `get_current_user`, tampoco declara ningún `scopes`.
+
+/// tip | Consejo
+
+Lo importante y "mágico" aquí es que `get_current_user` tendrá una lista diferente de `scopes` para verificar para cada *path operation*.
+
+Todo depende de los `scopes` declarados en cada *path operation* y cada dependencia en el árbol de dependencias para esa *path operation* específica.
+
+///
+
+## Más detalles sobre `SecurityScopes`
+
+Puedes usar `SecurityScopes` en cualquier punto, y en múltiples lugares, no tiene que ser en la dependencia "raíz".
+
+Siempre tendrá los scopes de seguridad declarados en las dependencias `Security` actuales y todos los dependientes para **esa específica** *path operation* y **ese específico** árbol de dependencias.
+
+Debido a que `SecurityScopes` tendrá todos los scopes declarados por dependientes, puedes usarlo para verificar que un token tiene los scopes requeridos en una función de dependencia central, y luego declarar diferentes requisitos de scope en diferentes *path operations*.
+
+Serán verificados independientemente para cada *path operation*.
+
+## Revisa
+
+Si abres la documentación de la API, puedes autenticarte y especificar qué scopes deseas autorizar.
+
+<img src="/img/tutorial/security/image11.png">
+
+Si no seleccionas ningún scope, estarás "autenticado", pero cuando intentes acceder a `/users/me/` o `/users/me/items/` obtendrás un error diciendo que no tienes suficientes permisos. Aún podrás acceder a `/status/`.
+
+Y si seleccionas el scope `me` pero no el scope `items`, podrás acceder a `/users/me/` pero no a `/users/me/items/`.
+
+Eso es lo que pasaría a una aplicación de terceros que intentara acceder a una de estas *path operations* con un token proporcionado por un usuario, dependiendo de cuántos permisos el usuario otorgó a la aplicación.
+
+## Acerca de las integraciones de terceros
+
+En este ejemplo estamos usando el flujo de OAuth2 "password".
+
+Esto es apropiado cuando estamos iniciando sesión en nuestra propia aplicación, probablemente con nuestro propio frontend.
+
+Porque podemos confiar en ella para recibir el `username` y `password`, ya que la controlamos.
+
+Pero si estás construyendo una aplicación OAuth2 a la que otros se conectarían (es decir, si estás construyendo un proveedor de autenticación equivalente a Facebook, Google, GitHub, etc.) deberías usar uno de los otros flujos.
+
+El más común es el flujo implícito.
+
+El más seguro es el flujo de código, pero es más complejo de implementar ya que requiere más pasos. Como es más complejo, muchos proveedores terminan sugiriendo el flujo implícito.
+
+/// note | Nota
+
+Es común que cada proveedor de autenticación nombre sus flujos de una manera diferente, para hacerlos parte de su marca.
+
+Pero al final, están implementando el mismo estándar OAuth2.
+
+///
+
+**FastAPI** incluye utilidades para todos estos flujos de autenticación OAuth2 en `fastapi.security.oauth2`.
+
+## `Security` en `dependencies` del decorador
+
+De la misma manera que puedes definir una `list` de `Depends` en el parámetro `dependencies` del decorador (como se explica en [Dependencias en decoradores de path operation](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), también podrías usar `Security` con `scopes` allí.

docs/es/docs/advanced/settings.md

@@ -0,0 +1,346 @@
+# Configuraciones y Variables de Entorno
+
+En muchos casos, tu aplicación podría necesitar algunas configuraciones o ajustes externos, por ejemplo, claves secretas, credenciales de base de datos, credenciales para servicios de correo electrónico, etc.
+
+La mayoría de estas configuraciones son variables (pueden cambiar), como las URLs de bases de datos. Y muchas podrían ser sensibles, como los secretos.
+
+Por esta razón, es común proporcionarlas en variables de entorno que son leídas por la aplicación.
+
+/// tip | Consejo
+
+Para entender las variables de entorno, puedes leer [Variables de Entorno](../environment-variables.md){.internal-link target=_blank}.
+
+///
+
+## Tipos y validación
+
+Estas variables de entorno solo pueden manejar strings de texto, ya que son externas a Python y tienen que ser compatibles con otros programas y el resto del sistema (e incluso con diferentes sistemas operativos, como Linux, Windows, macOS).
+
+Eso significa que cualquier valor leído en Python desde una variable de entorno será un `str`, y cualquier conversión a un tipo diferente o cualquier validación tiene que hacerse en código.
+
+## Pydantic `Settings`
+
+Afortunadamente, Pydantic proporciona una gran utilidad para manejar estas configuraciones provenientes de variables de entorno con <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/" class="external-link" target="_blank">Pydantic: Settings management</a>.
+
+### Instalar `pydantic-settings`
+
+Primero, asegúrate de crear tu [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, actívalo y luego instala el paquete `pydantic-settings`:
+
+<div class="termy">
+
+```console
+$ pip install pydantic-settings
+---> 100%
+```
+
+</div>
+
+También viene incluido cuando instalas los extras `all` con:
+
+<div class="termy">
+
+```console
+$ pip install "fastapi[all]"
+---> 100%
+```
+
+</div>
+
+/// info | Información
+
+En Pydantic v1 venía incluido con el paquete principal. Ahora se distribuye como este paquete independiente para que puedas elegir si instalarlo o no si no necesitas esa funcionalidad.
+
+///
+
+### Crear el objeto `Settings`
+
+Importa `BaseSettings` de Pydantic y crea una sub-clase, muy similar a un modelo de Pydantic.
+
+De la misma forma que con los modelos de Pydantic, declaras atributos de clase con anotaciones de tipos, y posiblemente, valores por defecto.
+
+Puedes usar todas las mismas funcionalidades de validación y herramientas que usas para los modelos de Pydantic, como diferentes tipos de datos y validaciones adicionales con `Field()`.
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/settings/tutorial001.py hl[2,5:8,11] *}
+
+////
+
+//// tab | Pydantic v1
+
+/// info | Información
+
+En Pydantic v1 importarías `BaseSettings` directamente desde `pydantic` en lugar de desde `pydantic_settings`.
+
+///
+
+{* ../../docs_src/settings/tutorial001_pv1.py hl[2,5:8,11] *}
+
+////
+
+/// tip | Consejo
+
+Si quieres algo rápido para copiar y pegar, no uses este ejemplo, usa el último más abajo.
+
+///
+
+Luego, cuando creas una instance de esa clase `Settings` (en este caso, en el objeto `settings`), Pydantic leerá las variables de entorno de una manera indiferente a mayúsculas y minúsculas, por lo que una variable en mayúsculas `APP_NAME` aún será leída para el atributo `app_name`.
+
+Luego convertirá y validará los datos. Así que, cuando uses ese objeto `settings`, tendrás datos de los tipos que declaraste (por ejemplo, `items_per_user` será un `int`).
+
+### Usar el `settings`
+
+Luego puedes usar el nuevo objeto `settings` en tu aplicación:
+
+{* ../../docs_src/settings/tutorial001.py hl[18:20] *}
+
+### Ejecutar el servidor
+
+Luego, ejecutarías el servidor pasando las configuraciones como variables de entorno, por ejemplo, podrías establecer un `ADMIN_EMAIL` y `APP_NAME` con:
+
+<div class="termy">
+
+```console
+$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+</div>
+
+/// tip | Consejo
+
+Para establecer múltiples variables de entorno para un solo comando, simplemente sepáralas con un espacio y ponlas todas antes del comando.
+
+///
+
+Y luego la configuración `admin_email` se establecería en `"deadpool@example.com"`.
+
+El `app_name` sería `"ChimichangApp"`.
+
+Y el `items_per_user` mantendría su valor por defecto de `50`.
+
+## Configuraciones en otro módulo
+
+Podrías poner esas configuraciones en otro archivo de módulo como viste en [Aplicaciones Más Grandes - Múltiples Archivos](../tutorial/bigger-applications.md){.internal-link target=_blank}.
+
+Por ejemplo, podrías tener un archivo `config.py` con:
+
+{* ../../docs_src/settings/app01/config.py *}
+
+Y luego usarlo en un archivo `main.py`:
+
+{* ../../docs_src/settings/app01/main.py hl[3,11:13] *}
+
+/// tip | Consejo
+
+También necesitarías un archivo `__init__.py` como viste en [Aplicaciones Más Grandes - Múltiples Archivos](../tutorial/bigger-applications.md){.internal-link target=_blank}.
+
+///
+
+## Configuraciones en una dependencia
+
+En algunas ocasiones podría ser útil proporcionar las configuraciones desde una dependencia, en lugar de tener un objeto global con `settings` que se use en todas partes.
+
+Esto podría ser especialmente útil durante las pruebas, ya que es muy fácil sobrescribir una dependencia con tus propias configuraciones personalizadas.
+
+### El archivo de configuración
+
+Proveniente del ejemplo anterior, tu archivo `config.py` podría verse como:
+
+{* ../../docs_src/settings/app02/config.py hl[10] *}
+
+Nota que ahora no creamos una instance por defecto `settings = Settings()`.
+
+### El archivo principal de la app
+
+Ahora creamos una dependencia que devuelve un nuevo `config.Settings()`.
+
+{* ../../docs_src/settings/app02_an_py39/main.py hl[6,12:13] *}
+
+/// tip | Consejo
+
+Hablaremos del `@lru_cache` en un momento.
+
+Por ahora puedes asumir que `get_settings()` es una función normal.
+
+///
+
+Y luego podemos requerirlo desde la *path operation function* como una dependencia y usarlo donde lo necesitemos.
+
+{* ../../docs_src/settings/app02_an_py39/main.py hl[17,19:21] *}
+
+### Configuraciones y pruebas
+
+Luego sería muy fácil proporcionar un objeto de configuraciones diferente durante las pruebas al sobrescribir una dependencia para `get_settings`:
+
+{* ../../docs_src/settings/app02/test_main.py hl[9:10,13,21] *}
+
+En la dependencia sobreescrita establecemos un nuevo valor para el `admin_email` al crear el nuevo objeto `Settings`, y luego devolvemos ese nuevo objeto.
+
+Luego podemos probar que se está usando.
+
+## Leer un archivo `.env`
+
+Si tienes muchas configuraciones que posiblemente cambien mucho, tal vez en diferentes entornos, podría ser útil ponerlos en un archivo y luego leerlos desde allí como si fueran variables de entorno.
+
+Esta práctica es lo suficientemente común que tiene un nombre, estas variables de entorno generalmente se colocan en un archivo `.env`, y el archivo se llama un "dotenv".
+
+/// tip | Consejo
+
+Un archivo que comienza con un punto (`.`) es un archivo oculto en sistemas tipo Unix, como Linux y macOS.
+
+Pero un archivo dotenv realmente no tiene que tener ese nombre exacto.
+
+///
+
+Pydantic tiene soporte para leer desde estos tipos de archivos usando un paquete externo. Puedes leer más en <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support" class="external-link" target="_blank">Pydantic Settings: Dotenv (.env) support</a>.
+
+/// tip | Consejo
+
+Para que esto funcione, necesitas `pip install python-dotenv`.
+
+///
+
+### El archivo `.env`
+
+Podrías tener un archivo `.env` con:
+
+```bash
+ADMIN_EMAIL="deadpool@example.com"
+APP_NAME="ChimichangApp"
+```
+
+### Leer configuraciones desde `.env`
+
+Y luego actualizar tu `config.py` con:
+
+//// tab | Pydantic v2
+
+{* ../../docs_src/settings/app03_an/config.py hl[9] *}
+
+/// tip | Consejo
+
+El atributo `model_config` se usa solo para configuración de Pydantic. Puedes leer más en <a href="https://docs.pydantic.dev/latest/concepts/config/" class="external-link" target="_blank">Pydantic: Concepts: Configuration</a>.
+
+///
+
+////
+
+//// tab | Pydantic v1
+
+{* ../../docs_src/settings/app03_an/config_pv1.py hl[9:10] *}
+
+/// tip | Consejo
+
+La clase `Config` se usa solo para configuración de Pydantic. Puedes leer más en <a href="https://docs.pydantic.dev/1.10/usage/model_config/" class="external-link" target="_blank">Pydantic Model Config</a>.
+
+///
+
+////
+
+/// info | Información
+
+En la versión 1 de Pydantic la configuración se hacía en una clase interna `Config`, en la versión 2 de Pydantic se hace en un atributo `model_config`. Este atributo toma un `dict`, y para obtener autocompletado y errores en línea, puedes importar y usar `SettingsConfigDict` para definir ese `dict`.
+
+///
+
+Aquí definimos la configuración `env_file` dentro de tu clase Pydantic `Settings`, y establecemos el valor en el nombre del archivo con el archivo dotenv que queremos usar.
+
+### Creando el `Settings` solo una vez con `lru_cache`
+
+Leer un archivo desde el disco es normalmente una operación costosa (lenta), por lo que probablemente quieras hacerlo solo una vez y luego reutilizar el mismo objeto de configuraciones, en lugar de leerlo para cada request.
+
+Pero cada vez que hacemos:
+
+```Python
+Settings()
+```
+
+se crearía un nuevo objeto `Settings`, y al crearse leería el archivo `.env` nuevamente.
+
+Si la función de dependencia fuera simplemente así:
+
+```Python
+def get_settings():
+    return Settings()
+```
+
+crearíamos ese objeto para cada request, y estaríamos leyendo el archivo `.env` para cada request. ⚠️
+
+Pero como estamos usando el decorador `@lru_cache` encima, el objeto `Settings` se creará solo una vez, la primera vez que se llame. ✔️
+
+{* ../../docs_src/settings/app03_an_py39/main.py hl[1,11] *}
+
+Entonces, para cualquier llamada subsiguiente de `get_settings()` en las dependencias de los próximos requests, en lugar de ejecutar el código interno de `get_settings()` y crear un nuevo objeto `Settings`, devolverá el mismo objeto que fue devuelto en la primera llamada, una y otra vez.
+
+#### Detalles Técnicos de `lru_cache`
+
+`@lru_cache` modifica la función que decora para devolver el mismo valor que se devolvió la primera vez, en lugar de calcularlo nuevamente, ejecutando el código de la función cada vez.
+
+Así que la función debajo se ejecutará una vez por cada combinación de argumentos. Y luego, los valores devueltos por cada una de esas combinaciones de argumentos se utilizarán una y otra vez cada vez que la función sea llamada con exactamente la misma combinación de argumentos.
+
+Por ejemplo, si tienes una función:
+
+```Python
+@lru_cache
+def say_hi(name: str, salutation: str = "Ms."):
+    return f"Hello {salutation} {name}"
+```
+
+tu programa podría ejecutarse así:
+
+```mermaid
+sequenceDiagram
+
+participant code as Código
+participant function as say_hi()
+participant execute as Ejecutar función
+
+    rect rgba(0, 255, 0, .1)
+        code ->> function: say_hi(name="Camila")
+        function ->> execute: ejecutar código de la función
+        execute ->> code: devolver el resultado
+    end
+
+    rect rgba(0, 255, 255, .1)
+        code ->> function: say_hi(name="Camila")
+        function ->> code: devolver resultado almacenado
+    end
+
+    rect rgba(0, 255, 0, .1)
+        code ->> function: say_hi(name="Rick")
+        function ->> execute: ejecutar código de la función
+        execute ->> code: devolver el resultado
+    end
+
+    rect rgba(0, 255, 0, .1)
+        code ->> function: say_hi(name="Rick", salutation="Mr.")
+        function ->> execute: ejecutar código de la función
+        execute ->> code: devolver el resultado
+    end
+
+    rect rgba(0, 255, 255, .1)
+        code ->> function: say_hi(name="Rick")
+        function ->> code: devolver resultado almacenado
+    end
+
+    rect rgba(0, 255, 255, .1)
+        code ->> function: say_hi(name="Camila")
+        function ->> code: devolver resultado almacenado
+    end
+```
+
+En el caso de nuestra dependencia `get_settings()`, la función ni siquiera toma argumentos, por lo que siempre devolverá el mismo valor.
+
+De esa manera, se comporta casi como si fuera solo una variable global. Pero como usa una función de dependencia, entonces podemos sobrescribirla fácilmente para las pruebas.
+
+`@lru_cache` es parte de `functools`, que es parte del library estándar de Python, puedes leer más sobre él en las <a href="https://docs.python.org/3/library/functools.html#functools.lru_cache" class="external-link" target="_blank">docs de Python para `@lru_cache`</a>.
+
+## Resumen
+
+Puedes usar Pydantic Settings para manejar las configuraciones o ajustes de tu aplicación, con todo el poder de los modelos de Pydantic.
+
+* Al usar una dependencia, puedes simplificar las pruebas.
+* Puedes usar archivos `.env` con él.
+* Usar `@lru_cache` te permite evitar leer el archivo dotenv una y otra vez para cada request, mientras te permite sobrescribirlo durante las pruebas.

docs/es/docs/advanced/sub-applications.md

@@ -0,0 +1,67 @@
+# Sub Aplicaciones - Mounts
+
+Si necesitas tener dos aplicaciones de **FastAPI** independientes, cada una con su propio OpenAPI independiente y su propia interfaz de docs, puedes tener una aplicación principal y "montar" una (o más) sub-aplicación(es).
+
+## Montar una aplicación **FastAPI**
+
+"Montar" significa añadir una aplicación completamente "independiente" en un path específico, que luego se encarga de manejar todo bajo ese path, con las _path operations_ declaradas en esa sub-aplicación.
+
+### Aplicación de nivel superior
+
+Primero, crea la aplicación principal de nivel superior de **FastAPI**, y sus *path operations*:
+
+{* ../../docs_src/sub_applications/tutorial001.py hl[3, 6:8] *}
+
+### Sub-aplicación
+
+Luego, crea tu sub-aplicación, y sus *path operations*.
+
+Esta sub-aplicación es solo otra aplicación estándar de FastAPI, pero es la que se "montará":
+
+{* ../../docs_src/sub_applications/tutorial001.py hl[11, 14:16] *}
+
+### Montar la sub-aplicación
+
+En tu aplicación de nivel superior, `app`, monta la sub-aplicación, `subapi`.
+
+En este caso, se montará en el path `/subapi`:
+
+{* ../../docs_src/sub_applications/tutorial001.py hl[11, 19] *}
+
+### Revisa la documentación automática de la API
+
+Ahora, ejecuta el comando `fastapi` con tu archivo:
+
+<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>
+
+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 para la aplicación principal, incluyendo solo sus propias _path operations_:
+
+<img src="/img/tutorial/sub-applications/image01.png">
+
+Y luego, abre la documentación para la sub-aplicación, en <a href="http://127.0.0.1:8000/subapi/docs" class="external-link" target="_blank">http://127.0.0.1:8000/subapi/docs</a>.
+
+Verás la documentación automática de la API para la sub-aplicación, incluyendo solo sus propias _path operations_, todas bajo el prefijo correcto del sub-path `/subapi`:
+
+<img src="/img/tutorial/sub-applications/image02.png">
+
+Si intentas interactuar con cualquiera de las dos interfaces de usuario, funcionarán correctamente, porque el navegador podrá comunicarse con cada aplicación o sub-aplicación específica.
+
+### Detalles Técnicos: `root_path`
+
+Cuando montas una sub-aplicación como se describe arriba, FastAPI se encargará de comunicar el path de montaje para la sub-aplicación usando un mecanismo de la especificación ASGI llamado `root_path`.
+
+De esa manera, la sub-aplicación sabrá usar ese prefijo de path para la interfaz de documentación.
+
+Y la sub-aplicación también podría tener sus propias sub-aplicaciones montadas y todo funcionaría correctamente, porque FastAPI maneja todos estos `root_path`s automáticamente.
+
+Aprenderás más sobre el `root_path` y cómo usarlo explícitamente en la sección sobre [Detrás de un Proxy](behind-a-proxy.md){.internal-link target=_blank}.

docs/es/docs/advanced/templates.md

@@ -0,0 +1,126 @@
+# Plantillas
+
+Puedes usar cualquier motor de plantillas que desees con **FastAPI**.
+
+Una elección común es Jinja2, el mismo que usa Flask y otras herramientas.
+
+Hay utilidades para configurarlo fácilmente que puedes usar directamente en tu aplicación de **FastAPI** (proporcionadas por Starlette).
+
+## Instalar dependencias
+
+Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo e instalar `jinja2`:
+
+<div class="termy">
+
+```console
+$ pip install jinja2
+
+---> 100%
+```
+
+</div>
+
+## Usando `Jinja2Templates`
+
+* Importa `Jinja2Templates`.
+* Crea un objeto `templates` que puedas reutilizar más tarde.
+* Declara un parámetro `Request` en la *path operation* que devolverá una plantilla.
+* Usa los `templates` que creaste para renderizar y devolver un `TemplateResponse`, pasa el nombre de la plantilla, el objeto de request, y un diccionario "context" con pares clave-valor que se usarán dentro de la plantilla Jinja2.
+
+{* ../../docs_src/templates/tutorial001.py hl[4,11,15:18] *}
+
+/// note | Nota
+
+Antes de FastAPI 0.108.0, Starlette 0.29.0, el `name` era el primer parámetro.
+
+Además, antes de eso, en versiones anteriores, el objeto `request` se pasaba como parte de los pares clave-valor en el contexto para Jinja2.
+
+///
+
+/// tip | Consejo
+
+Al declarar `response_class=HTMLResponse`, la interfaz de usuario de la documentación podrá saber que el response será HTML.
+
+///
+
+/// note | Nota Técnica
+
+También podrías usar `from starlette.templating import Jinja2Templates`.
+
+**FastAPI** proporciona el mismo `starlette.templating` como `fastapi.templating`, solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette. Lo mismo con `Request` y `StaticFiles`.
+
+///
+
+## Escribiendo plantillas
+
+Luego puedes escribir una plantilla en `templates/item.html` con, por ejemplo:
+
+```jinja hl_lines="7"
+{!../../docs_src/templates/templates/item.html!}
+```
+
+### Valores de Contexto de la Plantilla
+
+En el HTML que contiene:
+
+{% raw %}
+
+```jinja
+Item ID: {{ id }}
+```
+
+{% endraw %}
+
+...mostrará el `id` tomado del `dict` de "contexto" que pasaste:
+
+```Python
+{"id": id}
+```
+
+Por ejemplo, con un ID de `42`, esto se renderizaría como:
+
+```html
+Item ID: 42
+```
+
+### Argumentos de la Plantilla `url_for`
+
+También puedes usar `url_for()` dentro de la plantilla, toma como argumentos los mismos que usaría tu *path operation function*.
+
+Entonces, la sección con:
+
+{% raw %}
+
+```jinja
+<a href="{{ url_for('read_item', id=id) }}">
+```
+
+{% endraw %}
+
+...generará un enlace hacia la misma URL que manejaría la *path operation function* `read_item(id=id)`.
+
+Por ejemplo, con un ID de `42`, esto se renderizaría como:
+
+```html
+<a href="/items/42">
+```
+
+## Plantillas y archivos estáticos
+
+También puedes usar `url_for()` dentro de la plantilla, y usarlo, por ejemplo, con los `StaticFiles` que montaste con el `name="static"`.
+
+```jinja hl_lines="4"
+{!../../docs_src/templates/templates/item.html!}
+```
+
+En este ejemplo, enlazaría a un archivo CSS en `static/styles.css` con:
+
+```CSS hl_lines="4"
+{!../../docs_src/templates/static/styles.css!}
+```
+
+Y porque estás usando `StaticFiles`, ese archivo CSS sería servido automáticamente por tu aplicación de **FastAPI** en la URL `/static/styles.css`.
+
+## Más detalles
+
+Para más detalles, incluyendo cómo testear plantillas, revisa <a href="https://www.starlette.dev/templates/" class="external-link" target="_blank">la documentación de Starlette sobre plantillas</a>.

docs/es/docs/advanced/testing-dependencies.md

@@ -0,0 +1,53 @@
+# Probando Dependencias con Overrides
+
+## Sobrescribir dependencias durante las pruebas
+
+Hay algunos escenarios donde podrías querer sobrescribir una dependencia durante las pruebas.
+
+No quieres que la dependencia original se ejecute (ni ninguna de las sub-dependencias que pueda tener).
+
+En cambio, quieres proporcionar una dependencia diferente que se usará solo durante las pruebas (posiblemente solo algunas pruebas específicas), y que proporcionará un valor que pueda ser usado donde se usó el valor de la dependencia original.
+
+### Casos de uso: servicio externo
+
+Un ejemplo podría ser que tienes un proveedor de autenticación externo al que necesitas llamar.
+
+Le envías un token y te devuelve un usuario autenticado.
+
+Este proveedor podría estar cobrándote por cada request, y llamarlo podría tomar más tiempo adicional que si tuvieras un usuario de prueba fijo para los tests.
+
+Probablemente quieras probar el proveedor externo una vez, pero no necesariamente llamarlo para cada test que se realice.
+
+En este caso, puedes sobrescribir la dependencia que llama a ese proveedor y usar una dependencia personalizada que devuelva un usuario de prueba, solo para tus tests.
+
+### Usa el atributo `app.dependency_overrides`
+
+Para estos casos, tu aplicación **FastAPI** tiene un atributo `app.dependency_overrides`, es un simple `dict`.
+
+Para sobrescribir una dependencia para las pruebas, colocas como clave la dependencia original (una función), y como valor, tu dependencia para sobreescribir (otra función).
+
+Y entonces **FastAPI** llamará a esa dependencia para sobreescribir en lugar de la dependencia original.
+
+{* ../../docs_src/dependency_testing/tutorial001_an_py310.py hl[26:27,30] *}
+
+/// tip | Consejo
+
+Puedes sobreescribir una dependencia utilizada en cualquier lugar de tu aplicación **FastAPI**.
+
+La dependencia original podría ser utilizada en una *path operation function*, un *path operation decorator* (cuando no usas el valor de retorno), una llamada a `.include_router()`, etc.
+
+FastAPI todavía podrá sobrescribirla.
+
+///
+
+Entonces puedes restablecer las dependencias sobreescritas configurando `app.dependency_overrides` para que sea un `dict` vacío:
+
+```Python
+app.dependency_overrides = {}
+```
+
+/// tip | Consejo
+
+Si quieres sobrescribir una dependencia solo durante algunos tests, puedes establecer la sobrescritura al inicio del test (dentro de la función del test) y restablecerla al final (al final de la función del test).
+
+///

docs/es/docs/advanced/testing-events.md

@@ -0,0 +1,5 @@
+# Testing Events: startup - shutdown
+
+Cuando necesitas que tus manejadores de eventos (`startup` y `shutdown`) se ejecuten en tus tests, puedes usar el `TestClient` con un statement `with`:
+
+{* ../../docs_src/app_testing/tutorial003.py hl[9:12,20:24] *}

docs/es/docs/advanced/testing-websockets.md

@@ -0,0 +1,13 @@
+# Probando WebSockets
+
+Puedes usar el mismo `TestClient` para probar WebSockets.
+
+Para esto, usas el `TestClient` en un statement `with`, conectándote al WebSocket:
+
+{* ../../docs_src/app_testing/tutorial002.py hl[27:31] *}
+
+/// note | Nota
+
+Para más detalles, revisa la documentación de Starlette sobre <a href="https://www.starlette.dev/testclient/#testing-websocket-sessions" class="external-link" target="_blank">probando sesiones WebSocket</a>.
+
+///

docs/es/docs/advanced/using-request-directly.md

@@ -0,0 +1,56 @@
+# Usar el Request Directamente
+
+Hasta ahora, has estado declarando las partes del request que necesitas con sus tipos.
+
+Tomando datos de:
+
+* El path como parámetros.
+* Headers.
+* Cookies.
+* etc.
+
+Y al hacerlo, **FastAPI** está validando esos datos, convirtiéndolos y generando documentación para tu API automáticamente.
+
+Pero hay situaciones donde podrías necesitar acceder al objeto `Request` directamente.
+
+## Detalles sobre el objeto `Request`
+
+Como **FastAPI** es en realidad **Starlette** por debajo, con una capa de varias herramientas encima, puedes usar el objeto <a href="https://www.starlette.dev/requests/" class="external-link" target="_blank">`Request`</a> de Starlette directamente cuando lo necesites.
+
+También significa que si obtienes datos del objeto `Request` directamente (por ejemplo, leyendo el cuerpo) no serán validados, convertidos o documentados (con OpenAPI, para la interfaz automática de usuario de la API) por FastAPI.
+
+Aunque cualquier otro parámetro declarado normalmente (por ejemplo, el cuerpo con un modelo de Pydantic) seguiría siendo validado, convertido, anotado, etc.
+
+Pero hay casos específicos donde es útil obtener el objeto `Request`.
+
+## Usa el objeto `Request` directamente
+
+Imaginemos que quieres obtener la dirección IP/host del cliente dentro de tu *path operation function*.
+
+Para eso necesitas acceder al request directamente.
+
+{* ../../docs_src/using_request_directly/tutorial001.py hl[1,7:8] *}
+
+Al declarar un parámetro de *path operation function* con el tipo siendo `Request`, **FastAPI** sabrá pasar el `Request` en ese parámetro.
+
+/// tip | Consejo
+
+Nota que en este caso, estamos declarando un parámetro de path además del parámetro del request.
+
+Así que, el parámetro de path será extraído, validado, convertido al tipo especificado y anotado con OpenAPI.
+
+De la misma manera, puedes declarar cualquier otro parámetro como normalmente, y adicionalmente, obtener también el `Request`.
+
+///
+
+## Documentación de `Request`
+
+Puedes leer más detalles sobre el <a href="https://www.starlette.dev/requests/" class="external-link" target="_blank">objeto `Request` en el sitio de documentación oficial de Starlette</a>.
+
+/// note | Detalles Técnicos
+
+Podrías también usar `from starlette.requests import Request`.
+
+**FastAPI** lo proporciona directamente solo como conveniencia para ti, el desarrollador. Pero viene directamente de Starlette.
+
+///

docs/es/docs/advanced/websockets.md

@@ -0,0 +1,186 @@
+# WebSockets
+
+Puedes usar <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API" class="external-link" target="_blank">WebSockets</a> con **FastAPI**.
+
+## Instalar `WebSockets`
+
+Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, activarlo e instalar `websockets`:
+
+<div class="termy">
+
+```console
+$ pip install websockets
+
+---> 100%
+```
+
+</div>
+
+## Cliente WebSockets
+
+### En producción
+
+En tu sistema de producción, probablemente tengas un frontend creado con un framework moderno como React, Vue.js o Angular.
+
+Y para comunicarte usando WebSockets con tu backend probablemente usarías las utilidades de tu frontend.
+
+O podrías tener una aplicación móvil nativa que se comunica con tu backend de WebSocket directamente, en código nativo.
+
+O podrías tener alguna otra forma de comunicarte con el endpoint de WebSocket.
+
+---
+
+Pero para este ejemplo, usaremos un documento HTML muy simple con algo de JavaScript, todo dentro de un string largo.
+
+Esto, por supuesto, no es lo ideal y no lo usarías para producción.
+
+En producción tendrías una de las opciones anteriores.
+
+Pero es la forma más sencilla de enfocarse en el lado del servidor de WebSockets y tener un ejemplo funcional:
+
+{* ../../docs_src/websockets/tutorial001.py hl[2,6:38,41:43] *}
+
+## Crear un `websocket`
+
+En tu aplicación de **FastAPI**, crea un `websocket`:
+
+{* ../../docs_src/websockets/tutorial001.py hl[1,46:47] *}
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.websockets import WebSocket`.
+
+**FastAPI** proporciona el mismo `WebSocket` directamente solo como una conveniencia para ti, el desarrollador. Pero viene directamente de Starlette.
+
+///
+
+## Esperar mensajes y enviar mensajes
+
+En tu ruta de WebSocket puedes `await` para recibir mensajes y enviar mensajes.
+
+{* ../../docs_src/websockets/tutorial001.py hl[48:52] *}
+
+Puedes recibir y enviar datos binarios, de texto y JSON.
+
+## Pruébalo
+
+Si tu archivo se llama `main.py`, ejecuta tu aplicación 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>
+
+Abre tu navegador en <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>.
+
+Verás una página simple como:
+
+<img src="/img/tutorial/websockets/image01.png">
+
+Puedes escribir mensajes en el cuadro de entrada y enviarlos:
+
+<img src="/img/tutorial/websockets/image02.png">
+
+Y tu aplicación **FastAPI** con WebSockets responderá de vuelta:
+
+<img src="/img/tutorial/websockets/image03.png">
+
+Puedes enviar (y recibir) muchos mensajes:
+
+<img src="/img/tutorial/websockets/image04.png">
+
+Y todos usarán la misma conexión WebSocket.
+
+## Usando `Depends` y otros
+
+En endpoints de WebSocket puedes importar desde `fastapi` y usar:
+
+* `Depends`
+* `Security`
+* `Cookie`
+* `Header`
+* `Path`
+* `Query`
+
+Funcionan de la misma manera que para otros endpoints de FastAPI/*path operations*:
+
+{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *}
+
+/// info | Información
+
+Como esto es un WebSocket no tiene mucho sentido lanzar un `HTTPException`, en su lugar lanzamos un `WebSocketException`.
+
+Puedes usar un código de cierre de los <a href="https://tools.ietf.org/html/rfc6455#section-7.4.1" class="external-link" target="_blank">códigos válidos definidos en la especificación</a>.
+
+///
+
+### Prueba los WebSockets con dependencias
+
+Si tu archivo se llama `main.py`, ejecuta tu aplicación 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>
+
+Abre tu navegador en <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>.
+
+Ahí puedes establecer:
+
+* El "ID del Ítem", usado en el path.
+* El "Token" usado como un parámetro query.
+
+/// tip | Consejo
+
+Nota que el query `token` será manejado por una dependencia.
+
+///
+
+Con eso puedes conectar el WebSocket y luego enviar y recibir mensajes:
+
+<img src="/img/tutorial/websockets/image05.png">
+
+## Manejar desconexiones y múltiples clientes
+
+Cuando una conexión de WebSocket se cierra, el `await websocket.receive_text()` lanzará una excepción `WebSocketDisconnect`, que puedes capturar y manejar como en este ejemplo.
+
+{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *}
+
+Para probarlo:
+
+* Abre la aplicación con varias pestañas del navegador.
+* Escribe mensajes desde ellas.
+* Luego cierra una de las pestañas.
+
+Eso lanzará la excepción `WebSocketDisconnect`, y todos los otros clientes recibirán un mensaje como:
+
+```
+Client #1596980209979 left the chat
+```
+
+/// tip | Consejo
+
+La aplicación anterior es un ejemplo mínimo y simple para demostrar cómo manejar y transmitir mensajes a varias conexiones WebSocket.
+
+Pero ten en cuenta que, como todo se maneja en memoria, en una sola lista, solo funcionará mientras el proceso esté en ejecución, y solo funcionará con un solo proceso.
+
+Si necesitas algo fácil de integrar con FastAPI pero que sea más robusto, soportado por Redis, PostgreSQL u otros, revisa <a href="https://github.com/encode/broadcaster" class="external-link" target="_blank">encode/broadcaster</a>.
+
+///
+
+## Más información
+
+Para aprender más sobre las opciones, revisa la documentación de Starlette para:
+
+* <a href="https://www.starlette.dev/websockets/" class="external-link" target="_blank">La clase `WebSocket`</a>.
+* <a href="https://www.starlette.dev/endpoints/#websocketendpoint" class="external-link" target="_blank">Manejo de WebSocket basado en clases</a>.

docs/es/docs/advanced/wsgi.md

@@ -0,0 +1,35 @@
+# Incluyendo WSGI - Flask, Django, otros
+
+Puedes montar aplicaciones WSGI como viste con [Sub Aplicaciones - Mounts](sub-applications.md){.internal-link target=_blank}, [Detrás de un Proxy](behind-a-proxy.md){.internal-link target=_blank}.
+
+Para eso, puedes usar `WSGIMiddleware` y usarlo para envolver tu aplicación WSGI, por ejemplo, Flask, Django, etc.
+
+## Usando `WSGIMiddleware`
+
+Necesitas importar `WSGIMiddleware`.
+
+Luego envuelve la aplicación WSGI (p. ej., Flask) con el middleware.
+
+Y luego móntala bajo un path.
+
+{* ../../docs_src/wsgi/tutorial001.py hl[2:3,3] *}
+
+## Revisa
+
+Ahora, cada request bajo el path `/v1/` será manejado por la aplicación Flask.
+
+Y el resto será manejado por **FastAPI**.
+
+Si lo ejecutas y vas a <a href="http://localhost:8000/v1/" class="external-link" target="_blank">http://localhost:8000/v1/</a> verás el response de Flask:
+
+```txt
+Hello, World from Flask!
+```
+
+Y si vas a <a href="http://localhost:8000/v2" class="external-link" target="_blank">http://localhost:8000/v2</a> verás el response de FastAPI:
+
+```JSON
+{
+    "message": "Hello World"
+}
+```

docs/es/docs/alternatives.md

@@ -0,0 +1,485 @@
+# Alternativas, Inspiración y Comparaciones
+
+Lo que inspiró a **FastAPI**, cómo se compara con las alternativas y lo que aprendió de ellas.
+
+## Introducción
+
+**FastAPI** no existiría si no fuera por el trabajo previo de otros.
+
+Se han creado muchas herramientas antes que han ayudado a inspirar su creación.
+
+He estado evitando la creación de un nuevo framework durante varios años. Primero intenté resolver todas las funcionalidades cubiertas por **FastAPI** usando muchos frameworks diferentes, plug-ins y herramientas.
+
+Pero en algún punto, no hubo otra opción que crear algo que proporcionara todas estas funcionalidades, tomando las mejores ideas de herramientas previas y combinándolas de la mejor manera posible, usando funcionalidades del lenguaje que ni siquiera estaban disponibles antes (anotaciones de tipos de Python 3.6+).
+
+## Herramientas previas
+
+### <a href="https://www.djangoproject.com/" class="external-link" target="_blank">Django</a>
+
+Es el framework más popular de Python y es ampliamente confiable. Se utiliza para construir sistemas como Instagram.
+
+Está relativamente acoplado con bases de datos relacionales (como MySQL o PostgreSQL), por lo que tener una base de datos NoSQL (como Couchbase, MongoDB, Cassandra, etc) como motor de almacenamiento principal no es muy fácil.
+
+Fue creado para generar el HTML en el backend, no para crear APIs utilizadas por un frontend moderno (como React, Vue.js y Angular) o por otros sistemas (como dispositivos del <abbr title="Internet of Things">IoT</abbr>) comunicándose con él.
+
+### <a href="https://www.django-rest-framework.org/" class="external-link" target="_blank">Django REST Framework</a>
+
+El framework Django REST fue creado para ser un kit de herramientas flexible para construir APIs Web utilizando Django, mejorando sus capacidades API.
+
+Es utilizado por muchas empresas, incluidas Mozilla, Red Hat y Eventbrite.
+
+Fue uno de los primeros ejemplos de **documentación automática de APIs**, y esto fue específicamente una de las primeras ideas que inspiraron "la búsqueda de" **FastAPI**.
+
+/// note | Nota
+
+Django REST Framework fue creado por Tom Christie. El mismo creador de Starlette y Uvicorn, en los cuales **FastAPI** está basado.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Tener una interfaz de usuario web de documentación automática de APIs.
+
+///
+
+### <a href="https://flask.palletsprojects.com" class="external-link" target="_blank">Flask</a>
+
+Flask es un "microframework", no incluye integraciones de bases de datos ni muchas de las cosas que vienen por defecto en Django.
+
+Esta simplicidad y flexibilidad permiten hacer cosas como usar bases de datos NoSQL como el sistema de almacenamiento de datos principal.
+
+Como es muy simple, es relativamente intuitivo de aprender, aunque la documentación se vuelve algo técnica en algunos puntos.
+
+También se utiliza comúnmente para otras aplicaciones que no necesariamente necesitan una base de datos, gestión de usuarios, o cualquiera de las muchas funcionalidades que vienen preconstruidas en Django. Aunque muchas de estas funcionalidades se pueden añadir con plug-ins.
+
+Esta separación de partes, y ser un "microframework" que podría extenderse para cubrir exactamente lo que se necesita, fue una funcionalidad clave que quise mantener.
+
+Dada la simplicidad de Flask, parecía una buena opción para construir APIs. Lo siguiente a encontrar era un "Django REST Framework" para Flask.
+
+/// check | Inspiró a **FastAPI** a
+
+Ser un micro-framework. Haciendo fácil mezclar y combinar las herramientas y partes necesarias.
+
+Tener un sistema de routing simple y fácil de usar.
+
+///
+
+### <a href="https://requests.readthedocs.io" class="external-link" target="_blank">Requests</a>
+
+**FastAPI** no es en realidad una alternativa a **Requests**. Su ámbito es muy diferente.
+
+De hecho, sería común usar Requests *dentro* de una aplicación FastAPI.
+
+Aun así, FastAPI se inspiró bastante en Requests.
+
+**Requests** es un paquete para *interactuar* con APIs (como cliente), mientras que **FastAPI** es un paquete para *construir* APIs (como servidor).
+
+Están, más o menos, en extremos opuestos, complementándose entre sí.
+
+Requests tiene un diseño muy simple e intuitivo, es muy fácil de usar, con valores predeterminados sensatos. Pero al mismo tiempo, es muy poderoso y personalizable.
+
+Por eso, como se dice en el sitio web oficial:
+
+> Requests es uno de los paquetes Python más descargados de todos los tiempos
+
+La forma en que lo usas es muy sencilla. Por ejemplo, para hacer un `GET` request, escribirías:
+
+```Python
+response = requests.get("http://example.com/some/url")
+```
+
+La operación de path equivalente en FastAPI podría verse como:
+
+```Python hl_lines="1"
+@app.get("/some/url")
+def read_url():
+    return {"message": "Hello World"}
+```
+
+Mira las similitudes entre `requests.get(...)` y `@app.get(...)`.
+
+/// check | Inspiró a **FastAPI** a
+
+* Tener un API simple e intuitivo.
+* Usar nombres de métodos HTTP (operaciones) directamente, de una manera sencilla e intuitiva.
+* Tener valores predeterminados sensatos, pero personalizaciones poderosas.
+
+///
+
+### <a href="https://swagger.io/" class="external-link" target="_blank">Swagger</a> / <a href="https://github.com/OAI/OpenAPI-Specification/" class="external-link" target="_blank">OpenAPI</a>
+
+La principal funcionalidad que quería de Django REST Framework era la documentación automática de la API.
+
+Luego descubrí que había un estándar para documentar APIs, usando JSON (o YAML, una extensión de JSON) llamado Swagger.
+
+Y ya existía una interfaz de usuario web para las APIs Swagger. Por lo tanto, ser capaz de generar documentación Swagger para una API permitiría usar esta interfaz de usuario web automáticamente.
+
+En algún punto, Swagger fue entregado a la Linux Foundation, para ser renombrado OpenAPI.
+
+Es por eso que cuando se habla de la versión 2.0 es común decir "Swagger", y para la versión 3+ "OpenAPI".
+
+/// check | Inspiró a **FastAPI** a
+
+Adoptar y usar un estándar abierto para especificaciones de API, en lugar de usar un esquema personalizado.
+
+Y a integrar herramientas de interfaz de usuario basadas en estándares:
+
+* <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>
+* <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>
+
+Estas dos fueron elegidas por ser bastante populares y estables, pero haciendo una búsqueda rápida, podrías encontrar docenas de interfaces de usuario alternativas para OpenAPI (que puedes usar con **FastAPI**).
+
+///
+
+### Frameworks REST para Flask
+
+Existen varios frameworks REST para Flask, pero después de invertir tiempo y trabajo investigándolos, encontré que muchos son descontinuados o abandonados, con varios problemas existentes que los hacían inadecuados.
+
+### <a href="https://marshmallow.readthedocs.io/en/stable/" class="external-link" target="_blank">Marshmallow</a>
+
+Una de las principales funcionalidades necesitadas por los sistemas API es la "<abbr title="también llamada marshalling, conversión">serialización</abbr>" de datos, que consiste en tomar datos del código (Python) y convertirlos en algo que pueda ser enviado a través de la red. Por ejemplo, convertir un objeto que contiene datos de una base de datos en un objeto JSON. Convertir objetos `datetime` en strings, etc.
+
+Otra gran funcionalidad necesaria por las APIs es la validación de datos, asegurarse de que los datos sean válidos, dados ciertos parámetros. Por ejemplo, que algún campo sea un `int`, y no algún string aleatorio. Esto es especialmente útil para los datos entrantes.
+
+Sin un sistema de validación de datos, tendrías que hacer todas las comprobaciones a mano, en código.
+
+Estas funcionalidades son para lo que fue creado Marshmallow. Es un gran paquete, y lo he usado mucho antes.
+
+Pero fue creado antes de que existieran las anotaciones de tipos en Python. Así que, para definir cada <abbr title="la definición de cómo deberían formarse los datos">esquema</abbr> necesitas usar utilidades y clases específicas proporcionadas por Marshmallow.
+
+/// check | Inspiró a **FastAPI** a
+
+Usar código para definir "esquemas" que proporcionen tipos de datos y validación automáticamente.
+
+///
+
+### <a href="https://webargs.readthedocs.io/en/latest/" class="external-link" target="_blank">Webargs</a>
+
+Otra gran funcionalidad requerida por las APIs es el <abbr title="lectura y conversión a datos de Python">parse</abbr> de datos de las requests entrantes.
+
+Webargs es una herramienta que fue creada para proporcionar esa funcionalidad sobre varios frameworks, incluido Flask.
+
+Usa Marshmallow por debajo para hacer la validación de datos. Y fue creada por los mismos desarrolladores.
+
+Es una gran herramienta y la he usado mucho también, antes de tener **FastAPI**.
+
+/// info | Información
+
+Webargs fue creada por los mismos desarrolladores de Marshmallow.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Tener validación automática de datos entrantes en una request.
+
+///
+
+### <a href="https://apispec.readthedocs.io/en/stable/" class="external-link" target="_blank">APISpec</a>
+
+Marshmallow y Webargs proporcionan validación, parse y serialización como plug-ins.
+
+Pero la documentación todavía falta. Entonces APISpec fue creado.
+
+Es un plug-in para muchos frameworks (y hay un plug-in para Starlette también).
+
+La manera en que funciona es que escribes la definición del esquema usando el formato YAML dentro del docstring de cada función que maneja una ruta.
+
+Y genera esquemas OpenAPI.
+
+Así es como funciona en Flask, Starlette, Responder, etc.
+
+Pero luego, tenemos otra vez el problema de tener una micro-sintaxis, dentro de un string de Python (un gran YAML).
+
+El editor no puede ayudar mucho con eso. Y si modificamos parámetros o esquemas de Marshmallow y olvidamos también modificar ese docstring YAML, el esquema generado estaría obsoleto.
+
+/// info | Información
+
+APISpec fue creado por los mismos desarrolladores de Marshmallow.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Soportar el estándar abierto para APIs, OpenAPI.
+
+///
+
+### <a href="https://flask-apispec.readthedocs.io/en/latest/" class="external-link" target="_blank">Flask-apispec</a>
+
+Es un plug-in de Flask, que conecta juntos Webargs, Marshmallow y APISpec.
+
+Usa la información de Webargs y Marshmallow para generar automáticamente esquemas OpenAPI, usando APISpec.
+
+Es una gran herramienta, muy subestimada. Debería ser mucho más popular que muchos plug-ins de Flask por ahí. Puede que se deba a que su documentación es demasiado concisa y abstracta.
+
+Esto resolvió tener que escribir YAML (otra sintaxis) dentro de docstrings de Python.
+
+Esta combinación de Flask, Flask-apispec con Marshmallow y Webargs fue mi stack de backend favorito hasta construir **FastAPI**.
+
+Usarlo llevó a la creación de varios generadores de full-stack para Flask. Estos son los principales stacks que yo (y varios equipos externos) hemos estado usando hasta ahora:
+
+* <a href="https://github.com/tiangolo/full-stack" class="external-link" target="_blank">https://github.com/tiangolo/full-stack</a>
+* <a href="https://github.com/tiangolo/full-stack-flask-couchbase" class="external-link" target="_blank">https://github.com/tiangolo/full-stack-flask-couchbase</a>
+* <a href="https://github.com/tiangolo/full-stack-flask-couchdb" class="external-link" target="_blank">https://github.com/tiangolo/full-stack-flask-couchdb</a>
+
+Y estos mismos generadores de full-stack fueron la base de los [Generadores de Proyectos **FastAPI**](project-generation.md){.internal-link target=_blank}.
+
+/// info | Información
+
+Flask-apispec fue creado por los mismos desarrolladores de Marshmallow.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Generar el esquema OpenAPI automáticamente, desde el mismo código que define la serialización y validación.
+
+///
+
+### <a href="https://nestjs.com/" class="external-link" target="_blank">NestJS</a> (y <a href="https://angular.io/" class="external-link" target="_blank">Angular</a>)
+
+Esto ni siquiera es Python, NestJS es un framework de JavaScript (TypeScript) NodeJS inspirado por Angular.
+
+Logra algo algo similar a lo que se puede hacer con Flask-apispec.
+
+Tiene un sistema de inyección de dependencias integrado, inspirado por Angular 2. Requiere pre-registrar los "inyectables" (como todos los otros sistemas de inyección de dependencias que conozco), por lo que añade a la verbosidad y repetición de código.
+
+Como los parámetros se describen con tipos de TypeScript (similar a las anotaciones de tipos en Python), el soporte editorial es bastante bueno.
+
+Pero como los datos de TypeScript no se preservan después de la compilación a JavaScript, no puede depender de los tipos para definir validación, serialización y documentación al mismo tiempo. Debido a esto y algunas decisiones de diseño, para obtener validación, serialización y generación automática del esquema, es necesario agregar decoradores en muchos lugares. Por lo tanto, se vuelve bastante verboso.
+
+No puede manejar muy bien modelos anidados. Entonces, si el cuerpo JSON en la request es un objeto JSON que tiene campos internos que a su vez son objetos JSON anidados, no puede ser documentado y validado apropiadamente.
+
+/// check | Inspiró a **FastAPI** a
+
+Usar tipos de Python para tener un gran soporte del editor.
+
+Tener un poderoso sistema de inyección de dependencias. Encontrar una forma de minimizar la repetición de código.
+
+///
+
+### <a href="https://sanic.readthedocs.io/en/latest/" class="external-link" target="_blank">Sanic</a>
+
+Fue uno de los primeros frameworks de Python extremadamente rápidos basados en `asyncio`. Fue hecho para ser muy similar a Flask.
+
+/// note | Detalles Técnicos
+
+Usó <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a> en lugar del loop `asyncio` por defecto de Python. Eso fue lo que lo hizo tan rápido.
+
+Claramente inspiró a Uvicorn y Starlette, que actualmente son más rápidos que Sanic en benchmarks abiertos.
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Encontrar una manera de tener un rendimiento impresionante.
+
+Por eso **FastAPI** se basa en Starlette, ya que es el framework más rápido disponible (probado por benchmarks de terceros).
+
+///
+
+### <a href="https://falconframework.org/" class="external-link" target="_blank">Falcon</a>
+
+Falcon es otro framework de Python de alto rendimiento, está diseñado para ser minimalista y funcionar como la base de otros frameworks como Hug.
+
+Está diseñado para tener funciones que reciben dos parámetros, un "request" y un "response". Luego "lees" partes del request y "escribes" partes en el response. Debido a este diseño, no es posible declarar parámetros de request y cuerpos con las anotaciones de tipos estándar de Python como parámetros de función.
+
+Por lo tanto, la validación de datos, la serialización y la documentación, tienen que hacerse en código, no automáticamente. O tienen que implementarse como un framework sobre Falcon, como Hug. Esta misma distinción ocurre en otros frameworks que se inspiran en el diseño de Falcon, de tener un objeto request y un objeto response como parámetros.
+
+/// check | Inspiró a **FastAPI** a
+
+Buscar maneras de obtener un gran rendimiento.
+
+Junto con Hug (ya que Hug se basa en Falcon), inspiraron a **FastAPI** a declarar un parámetro `response` en las funciones.
+
+Aunque en FastAPI es opcional, y se utiliza principalmente para configurar headers, cookies y códigos de estado alternativos.
+
+///
+
+### <a href="https://moltenframework.com/" class="external-link" target="_blank">Molten</a>
+
+Descubrí Molten en las primeras etapas de construcción de **FastAPI**. Y tiene ideas bastante similares:
+
+* Basado en las anotaciones de tipos de Python.
+* Validación y documentación a partir de estos tipos.
+* Sistema de Inyección de Dependencias.
+
+No utiliza un paquete de validación de datos, serialización y documentación de terceros como Pydantic, tiene el suyo propio. Por lo tanto, estas definiciones de tipos de datos no serían reutilizables tan fácilmente.
+
+Requiere configuraciones un poquito más verbosas. Y dado que se basa en WSGI (en lugar de ASGI), no está diseñado para aprovechar el alto rendimiento proporcionado por herramientas como Uvicorn, Starlette y Sanic.
+
+El sistema de inyección de dependencias requiere pre-registrar las dependencias y las dependencias se resuelven en base a los tipos declarados. Por lo tanto, no es posible declarar más de un "componente" que proporcione cierto tipo.
+
+Las rutas se declaran en un solo lugar, usando funciones declaradas en otros lugares (en lugar de usar decoradores que pueden colocarse justo encima de la función que maneja el endpoint). Esto se acerca más a cómo lo hace Django que a cómo lo hace Flask (y Starlette). Separa en el código cosas que están relativamente acopladas.
+
+/// check | Inspiró a **FastAPI** a
+
+Definir validaciones extra para tipos de datos usando el valor "default" de los atributos del modelo. Esto mejora el soporte del editor y no estaba disponible en Pydantic antes.
+
+Esto en realidad inspiró la actualización de partes de Pydantic, para soportar el mismo estilo de declaración de validación (toda esta funcionalidad ya está disponible en Pydantic).
+
+///
+
+### <a href="https://github.com/hugapi/hug" class="external-link" target="_blank">Hug</a>
+
+Hug fue uno de los primeros frameworks en implementar la declaración de tipos de parámetros API usando las anotaciones de tipos de Python. Esta fue una gran idea que inspiró a otras herramientas a hacer lo mismo.
+
+Usaba tipos personalizados en sus declaraciones en lugar de tipos estándar de Python, pero aún así fue un gran avance.
+
+También fue uno de los primeros frameworks en generar un esquema personalizado declarando toda la API en JSON.
+
+No se basaba en un estándar como OpenAPI y JSON Schema. Por lo que no sería sencillo integrarlo con otras herramientas, como Swagger UI. Pero, nuevamente, fue una idea muy innovadora.
+
+Tiene una funcionalidad interesante e inusual: usando el mismo framework, es posible crear APIs y también CLIs.
+
+Dado que se basa en el estándar previo para frameworks web Python sincrónicos (WSGI), no puede manejar Websockets y otras cosas, aunque aún así tiene un alto rendimiento también.
+
+/// info | Información
+
+Hug fue creado por Timothy Crosley, el mismo creador de <a href="https://github.com/timothycrosley/isort" class="external-link" target="_blank">`isort`</a>, una gran herramienta para ordenar automáticamente imports en archivos Python.
+
+///
+
+/// check | Ideas que inspiraron a **FastAPI**
+
+Hug inspiró partes de APIStar, y fue una de las herramientas que encontré más prometedoras, junto a APIStar.
+
+Hug ayudó a inspirar a **FastAPI** a usar anotaciones de tipos de Python para declarar parámetros, y a generar un esquema definiendo la API automáticamente.
+
+Hug inspiró a **FastAPI** a declarar un parámetro `response` en funciones para configurar headers y cookies.
+
+///
+
+### <a href="https://github.com/encode/apistar" class="external-link" target="_blank">APIStar</a> (<= 0.5)
+
+Justo antes de decidir construir **FastAPI** encontré **APIStar** server. Tenía casi todo lo que estaba buscando y tenía un gran diseño.
+
+Era una de las primeras implementaciones de un framework utilizando las anotaciones de tipos de Python para declarar parámetros y requests que jamás vi (antes de NestJS y Molten). Lo encontré más o menos al mismo tiempo que Hug. Pero APIStar usaba el estándar OpenAPI.
+
+Tenía validación de datos automática, serialización de datos y generación del esquema OpenAPI basada en las mismas anotaciones de tipos en varios lugares.
+
+Las definiciones de esquema de cuerpo no usaban las mismas anotaciones de tipos de Python como Pydantic, era un poco más similar a Marshmallow, por lo que el soporte del editor no sería tan bueno, pero aún así, APIStar era la mejor opción disponible.
+
+Tenía los mejores benchmarks de rendimiento en ese momento (solo superado por Starlette).
+
+Al principio, no tenía una interfaz de usuario web de documentación de API automática, pero sabía que podía agregar Swagger UI a él.
+
+Tenía un sistema de inyección de dependencias. Requería pre-registrar componentes, como otras herramientas discutidas anteriormente. Pero aún así, era una gran funcionalidad.
+
+Nunca pude usarlo en un proyecto completo, ya que no tenía integración de seguridad, por lo que no podía reemplazar todas las funcionalidades que tenía con los generadores de full-stack basados en Flask-apispec. Tenía en mi lista de tareas pendientes de proyectos crear un pull request agregando esa funcionalidad.
+
+Pero luego, el enfoque del proyecto cambió.
+
+Ya no era un framework web API, ya que el creador necesitaba enfocarse en Starlette.
+
+Ahora APIStar es un conjunto de herramientas para validar especificaciones OpenAPI, no un framework web.
+
+/// info | Información
+
+APIStar fue creado por Tom Christie. El mismo que creó:
+
+* Django REST Framework
+* Starlette (en la cual **FastAPI** está basado)
+* Uvicorn (usado por Starlette y **FastAPI**)
+
+///
+
+/// check | Inspiró a **FastAPI** a
+
+Existir.
+
+La idea de declarar múltiples cosas (validación de datos, serialización y documentación) con los mismos tipos de Python, que al mismo tiempo proporcionaban un gran soporte del editor, era algo que consideré una idea brillante.
+
+Y después de buscar durante mucho tiempo un framework similar y probar muchas alternativas diferentes, APIStar fue la mejor opción disponible.
+
+Luego APIStar dejó de existir como servidor y Starlette fue creado, y fue una nueva y mejor base para tal sistema. Esa fue la inspiración final para construir **FastAPI**.
+
+Considero a **FastAPI** un "sucesor espiritual" de APIStar, mientras mejora y aumenta las funcionalidades, el sistema de tipos y otras partes, basándose en los aprendizajes de todas estas herramientas previas.
+
+///
+
+## Usado por **FastAPI**
+
+### <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a>
+
+Pydantic es un paquete para definir validación de datos, serialización y documentación (usando JSON Schema) basándose en las anotaciones de tipos de Python.
+
+Eso lo hace extremadamente intuitivo.
+
+Es comparable a Marshmallow. Aunque es más rápido que Marshmallow en benchmarks. Y como está basado en las mismas anotaciones de tipos de Python, el soporte del editor es estupendo.
+
+/// check | **FastAPI** lo usa para
+
+Manejar toda la validación de datos, serialización de datos y documentación automática de modelos (basada en JSON Schema).
+
+**FastAPI** luego toma esos datos JSON Schema y los coloca en OpenAPI, aparte de todas las otras cosas que hace.
+
+///
+
+### <a href="https://www.starlette.dev/" class="external-link" target="_blank">Starlette</a>
+
+Starlette es un framework/toolkit <abbr title="El nuevo estándar para construir aplicaciones web asíncronas en Python">ASGI</abbr> liviano, ideal para construir servicios asyncio de alto rendimiento.
+
+Es muy simple e intuitivo. Está diseñado para ser fácilmente extensible y tener componentes modulares.
+
+Tiene:
+
+* Un rendimiento seriamente impresionante.
+* Soporte para WebSocket.
+* Tareas en segundo plano dentro del proceso.
+* Eventos de inicio y apagado.
+* Cliente de pruebas basado en HTTPX.
+* CORS, GZip, Archivos estáticos, Responses en streaming.
+* Soporte para sesiones y cookies.
+* Cobertura de tests del 100%.
+* Base de código 100% tipada.
+* Pocas dependencias obligatorias.
+
+Starlette es actualmente el framework de Python más rápido probado. Solo superado por Uvicorn, que no es un framework, sino un servidor.
+
+Starlette proporciona toda la funcionalidad básica de un microframework web.
+
+Pero no proporciona validación de datos automática, serialización o documentación.
+
+Esa es una de las principales cosas que **FastAPI** agrega, todo basado en las anotaciones de tipos de Python (usando Pydantic). Eso, además del sistema de inyección de dependencias, utilidades de seguridad, generación de esquemas OpenAPI, etc.
+
+/// note | Detalles Técnicos
+
+ASGI es un nuevo "estándar" que está siendo desarrollado por miembros del equipo central de Django. Todavía no es un "estándar de Python" (un PEP), aunque están en proceso de hacerlo.
+
+No obstante, ya está siendo usado como un "estándar" por varias herramientas. Esto mejora enormemente la interoperabilidad, ya que podrías cambiar Uvicorn por cualquier otro servidor ASGI (como Daphne o Hypercorn), o podrías añadir herramientas compatibles con ASGI, como `python-socketio`.
+
+///
+
+/// check | **FastAPI** lo usa para
+
+Manejar todas las partes web centrales. Añadiendo funcionalidades encima.
+
+La clase `FastAPI` en sí misma hereda directamente de la clase `Starlette`.
+
+Por lo tanto, cualquier cosa que puedas hacer con Starlette, puedes hacerlo directamente con **FastAPI**, ya que es básicamente Starlette potenciado.
+
+///
+
+### <a href="https://www.uvicorn.dev/" class="external-link" target="_blank">Uvicorn</a>
+
+Uvicorn es un servidor ASGI extremadamente rápido, construido sobre uvloop y httptools.
+
+No es un framework web, sino un servidor. Por ejemplo, no proporciona herramientas para el enrutamiento por paths. Eso es algo que un framework como Starlette (o **FastAPI**) proporcionaría encima.
+
+Es el servidor recomendado para Starlette y **FastAPI**.
+
+/// check | **FastAPI** lo recomienda como
+
+El servidor web principal para ejecutar aplicaciones **FastAPI**.
+
+También puedes usar la opción de línea de comandos `--workers` para tener un servidor multiproceso asíncrono.
+
+Revisa más detalles en la sección [Despliegue](deployment/index.md){.internal-link target=_blank}.
+
+///
+
+## Benchmarks y velocidad
+
+Para entender, comparar, y ver la diferencia entre Uvicorn, Starlette y FastAPI, revisa la sección sobre [Benchmarks](benchmarks.md){.internal-link target=_blank}.

docs/es/docs/async.md

@@ -0,0 +1,444 @@
+# Concurrencia y async / await
+
+Detalles sobre la sintaxis `async def` para *path operation functions* y algunos antecedentes sobre el código asíncrono, la concurrencia y el paralelismo.
+
+## ¿Con prisa?
+
+<abbr title="too long; didn't read"><strong>TL;DR:</strong></abbr>
+
+Si estás usando paquetes de terceros que te dicen que los llames con `await`, como:
+
+```Python
+results = await some_library()
+```
+
+Entonces, declara tus *path operation functions* con `async def` así:
+
+```Python hl_lines="2"
+@app.get('/')
+async def read_results():
+    results = await some_library()
+    return results
+```
+
+/// note | Nota
+
+Solo puedes usar `await` dentro de funciones creadas con `async def`.
+
+///
+
+---
+
+Si estás usando un paquete de terceros que se comunica con algo (una base de datos, una API, el sistema de archivos, etc.) y no tiene soporte para usar `await` (este es actualmente el caso para la mayoría de los paquetes de base de datos), entonces declara tus *path operation functions* como normalmente, usando simplemente `def`, así:
+
+```Python hl_lines="2"
+@app.get('/')
+def results():
+    results = some_library()
+    return results
+```
+
+---
+
+Si tu aplicación (de alguna manera) no tiene que comunicarse con nada más y esperar a que responda, usa `async def`.
+
+---
+
+Si simplemente no lo sabes, usa `def` normal.
+
+---
+
+**Nota**: Puedes mezclar `def` y `async def` en tus *path operation functions* tanto como necesites y definir cada una utilizando la mejor opción para ti. FastAPI hará lo correcto con ellas.
+
+De todos modos, en cualquiera de los casos anteriores, FastAPI seguirá funcionando de forma asíncrona y será extremadamente rápido.
+
+Pero al seguir los pasos anteriores, podrá hacer algunas optimizaciones de rendimiento.
+
+## Detalles Técnicos
+
+Las versiones modernas de Python tienen soporte para **"código asíncrono"** utilizando algo llamado **"coroutines"**, con la sintaxis **`async` y `await`**.
+
+Veamos esa frase por partes en las secciones a continuación:
+
+* **Código Asíncrono**
+* **`async` y `await`**
+* **Coroutines**
+
+## Código Asíncrono
+
+El código asíncrono simplemente significa que el lenguaje 💬 tiene una forma de decirle a la computadora / programa 🤖 que en algún momento del código, tendrá que esperar que *otra cosa* termine en otro lugar. Digamos que esa *otra cosa* se llama "archivo-lento" 📝.
+
+Entonces, durante ese tiempo, la computadora puede ir y hacer algún otro trabajo, mientras "archivo-lento" 📝 termina.
+
+Luego la computadora / programa 🤖 volverá cada vez que tenga una oportunidad porque está esperando nuevamente, o siempre que 🤖 haya terminado todo el trabajo que tenía en ese punto. Y 🤖 comprobará si alguna de las tareas que estaba esperando ya se han completado, haciendo lo que tenía que hacer.
+
+Después, 🤖 toma la primera tarea que termine (digamos, nuestro "archivo-lento" 📝) y continúa con lo que tenía que hacer con ella.
+
+Ese "esperar otra cosa" normalmente se refiere a las operaciones de <abbr title="Input and Output">I/O</abbr> que son relativamente "lentas" (comparadas con la velocidad del procesador y la memoria RAM), como esperar:
+
+* que los datos del cliente se envíen a través de la red
+* que los datos enviados por tu programa sean recibidos por el cliente a través de la red
+* que el contenido de un archivo en el disco sea leído por el sistema y entregado a tu programa
+* que el contenido que tu programa entregó al sistema sea escrito en el disco
+* una operación de API remota
+* que una operación de base de datos termine
+* que una query de base de datos devuelva los resultados
+* etc.
+
+Como el tiempo de ejecución se consume principalmente esperando operaciones de <abbr title="Input and Output">I/O</abbr>, las llaman operaciones "I/O bound".
+
+Se llama "asíncrono" porque la computadora / programa no tiene que estar "sincronizado" con la tarea lenta, esperando el momento exacto en que la tarea termine, sin hacer nada, para poder tomar el resultado de la tarea y continuar el trabajo.
+
+En lugar de eso, al ser un sistema "asíncrono", una vez terminado, la tarea puede esperar un poco en la cola (algunos microsegundos) para que la computadora / programa termine lo que salió a hacer, y luego regrese para tomar los resultados y continuar trabajando con ellos.
+
+Para el "sincrónico" (contrario al "asíncrono") comúnmente también usan el término "secuencial", porque la computadora / programa sigue todos los pasos en secuencia antes de cambiar a una tarea diferente, incluso si esos pasos implican esperar.
+
+### Concurrencia y Hamburguesas
+
+Esta idea de código **asíncrono** descrita anteriormente a veces también se llama **"concurrencia"**. Es diferente del **"paralelismo"**.
+
+**Concurrencia** y **paralelismo** ambos se relacionan con "diferentes cosas sucediendo más o menos al mismo tiempo".
+
+Pero los detalles entre *concurrencia* y *paralelismo* son bastante diferentes.
+
+Para ver la diferencia, imagina la siguiente historia sobre hamburguesas:
+
+### Hamburguesas Concurrentes
+
+Vas con tu crush a conseguir comida rápida, te pones en fila mientras el cajero toma los pedidos de las personas frente a ti. 😍
+
+<img src="/img/async/concurrent-burgers/concurrent-burgers-01.png" class="illustration">
+
+Luego es tu turno, haces tu pedido de 2 hamburguesas muy sofisticadas para tu crush y para ti. 🍔🍔
+
+<img src="/img/async/concurrent-burgers/concurrent-burgers-02.png" class="illustration">
+
+El cajero dice algo al cocinero en la cocina para que sepan que tienen que preparar tus hamburguesas (aunque actualmente están preparando las de los clientes anteriores).
+
+<img src="/img/async/concurrent-burgers/concurrent-burgers-03.png" class="illustration">
+
+Pagas. 💸
+
+El cajero te da el número de tu turno.
+
+<img src="/img/async/concurrent-burgers/concurrent-burgers-04.png" class="illustration">
+
+Mientras esperas, vas con tu crush y eliges una mesa, te sientas y hablas con tu crush por un largo rato (ya que tus hamburguesas son muy sofisticadas y toman un tiempo en prepararse).
+
+Mientras estás sentado en la mesa con tu crush, mientras esperas las hamburguesas, puedes pasar ese tiempo admirando lo increíble, lindo e inteligente que es tu crush ✨😍✨.
+
+<img src="/img/async/concurrent-burgers/concurrent-burgers-05.png" class="illustration">
+
+Mientras esperas y hablas con tu crush, de vez en cuando revisas el número mostrado en el mostrador para ver si ya es tu turno.
+
+Luego, en algún momento, finalmente es tu turno. Vas al mostrador, obtienes tus hamburguesas y vuelves a la mesa.
+
+<img src="/img/async/concurrent-burgers/concurrent-burgers-06.png" class="illustration">
+
+Tú y tu crush comen las hamburguesas y pasan un buen rato. ✨
+
+<img src="/img/async/concurrent-burgers/concurrent-burgers-07.png" class="illustration">
+
+/// info | Información
+
+Hermosas ilustraciones de <a href="https://www.instagram.com/ketrinadrawsalot" class="external-link" target="_blank">Ketrina Thompson</a>. 🎨
+
+///
+
+---
+
+Imagina que eres la computadora / programa 🤖 en esa historia.
+
+Mientras estás en la fila, estás inactivo 😴, esperando tu turno, sin hacer nada muy "productivo". Pero la fila es rápida porque el cajero solo está tomando los pedidos (no preparándolos), así que está bien.
+
+Luego, cuando es tu turno, haces un trabajo realmente "productivo", procesas el menú, decides lo que quieres, obtienes la elección de tu crush, pagas, verificas que das el billete o tarjeta correctos, verificas que te cobren correctamente, verificas que el pedido tenga los artículos correctos, etc.
+
+Pero luego, aunque todavía no tienes tus hamburguesas, tu trabajo con el cajero está "en pausa" ⏸, porque tienes que esperar 🕙 a que tus hamburguesas estén listas.
+
+Pero como te alejas del mostrador y te sientas en la mesa con un número para tu turno, puedes cambiar 🔀 tu atención a tu crush, y "trabajar" ⏯ 🤓 en eso. Luego, nuevamente estás haciendo algo muy "productivo" como es coquetear con tu crush 😍.
+
+Luego el cajero 💁 dice "he terminado de hacer las hamburguesas" al poner tu número en el mostrador, pero no saltas como loco inmediatamente cuando el número mostrado cambia a tu número de turno. Sabes que nadie robará tus hamburguesas porque tienes el número de tu turno, y ellos tienen el suyo.
+
+Así que esperas a que tu crush termine la historia (termine el trabajo ⏯ / tarea actual que se está procesando 🤓), sonríes amablemente y dices que vas por las hamburguesas ⏸.
+
+Luego vas al mostrador 🔀, a la tarea inicial que ahora está terminada ⏯, recoges las hamburguesas, das las gracias y las llevas a la mesa. Eso termina ese paso / tarea de interacción con el mostrador ⏹. Eso a su vez, crea una nueva tarea, de "comer hamburguesas" 🔀 ⏯, pero la anterior de "obtener hamburguesas" ha terminado ⏹.
+
+### Hamburguesas Paralelas
+
+Ahora imaginemos que estas no son "Hamburguesas Concurrentes", sino "Hamburguesas Paralelas".
+
+Vas con tu crush a obtener comida rápida paralela.
+
+Te pones en fila mientras varios (digamos 8) cajeros que al mismo tiempo son cocineros toman los pedidos de las personas frente a ti.
+
+Todos antes que tú están esperando a que sus hamburguesas estén listas antes de dejar el mostrador porque cada uno de los 8 cajeros va y prepara la hamburguesa de inmediato antes de obtener el siguiente pedido.
+
+<img src="/img/async/parallel-burgers/parallel-burgers-01.png" class="illustration">
+
+Luego, finalmente es tu turno, haces tu pedido de 2 hamburguesas muy sofisticadas para tu crush y para ti.
+
+Pagas 💸.
+
+<img src="/img/async/parallel-burgers/parallel-burgers-02.png" class="illustration">
+
+El cajero va a la cocina.
+
+Esperas, de pie frente al mostrador 🕙, para que nadie más tome tus hamburguesas antes que tú, ya que no hay números para los turnos.
+
+<img src="/img/async/parallel-burgers/parallel-burgers-03.png" class="illustration">
+
+Como tú y tu crush están ocupados no dejando que nadie se interponga y tome tus hamburguesas cuando lleguen, no puedes prestar atención a tu crush. 😞
+
+Este es un trabajo "sincrónico", estás "sincronizado" con el cajero/cocinero 👨‍🍳. Tienes que esperar 🕙 y estar allí en el momento exacto en que el cajero/cocinero 👨‍🍳 termine las hamburguesas y te las entregue, o de lo contrario, alguien más podría tomarlas.
+
+<img src="/img/async/parallel-burgers/parallel-burgers-04.png" class="illustration">
+
+Luego tu cajero/cocinero 👨‍🍳 finalmente regresa con tus hamburguesas, después de mucho tiempo esperando 🕙 allí frente al mostrador.
+
+<img src="/img/async/parallel-burgers/parallel-burgers-05.png" class="illustration">
+
+Tomas tus hamburguesas y vas a la mesa con tu crush.
+
+Simplemente las comes, y has terminado. ⏹
+
+<img src="/img/async/parallel-burgers/parallel-burgers-06.png" class="illustration">
+
+No hubo mucho hablar o coquetear ya que la mayor parte del tiempo se dedicó a esperar 🕙 frente al mostrador. 😞
+
+/// info | Información
+
+Hermosas ilustraciones de <a href="https://www.instagram.com/ketrinadrawsalot" class="external-link" target="_blank">Ketrina Thompson</a>. 🎨
+
+///
+
+---
+
+En este escenario de las hamburguesas paralelas, eres una computadora / programa 🤖 con dos procesadores (tú y tu crush), ambos esperando 🕙 y dedicando su atención ⏯ a estar "esperando en el mostrador" 🕙 por mucho tiempo.
+
+La tienda de comida rápida tiene 8 procesadores (cajeros/cocineros). Mientras que la tienda de hamburguesas concurrentes podría haber tenido solo 2 (un cajero y un cocinero).
+
+Pero aún así, la experiencia final no es la mejor. 😞
+
+---
+
+Esta sería la historia equivalente de las hamburguesas paralelas. 🍔
+
+Para un ejemplo más "de la vida real" de esto, imagina un banco.
+
+Hasta hace poco, la mayoría de los bancos tenían múltiples cajeros 👨‍💼👨‍💼👨‍💼👨‍💼 y una gran fila 🕙🕙🕙🕙🕙🕙🕙🕙.
+
+Todos los cajeros haciendo todo el trabajo con un cliente tras otro 👨‍💼⏯.
+
+Y tienes que esperar 🕙 en la fila por mucho tiempo o pierdes tu turno.
+
+Probablemente no querrías llevar a tu crush 😍 contigo a hacer trámites en el banco 🏦.
+
+### Conclusión de las Hamburguesas
+
+En este escenario de "hamburguesas de comida rápida con tu crush", como hay mucha espera 🕙, tiene mucho más sentido tener un sistema concurrente ⏸🔀⏯.
+
+Este es el caso para la mayoría de las aplicaciones web.
+
+Muchos, muchos usuarios, pero tu servidor está esperando 🕙 su conexión no tan buena para enviar sus requests.
+
+Y luego esperar 🕙 nuevamente a que los responses retornen.
+
+Esta "espera" 🕙 se mide en microsegundos, pero aún así, sumándolo todo, es mucha espera al final.
+
+Por eso tiene mucho sentido usar código asíncrono ⏸🔀⏯ para las APIs web.
+
+Este tipo de asincronía es lo que hizo popular a NodeJS (aunque NodeJS no es paralelo) y esa es la fortaleza de Go como lenguaje de programación.
+
+Y ese es el mismo nivel de rendimiento que obtienes con **FastAPI**.
+
+Y como puedes tener paralelismo y asincronía al mismo tiempo, obtienes un mayor rendimiento que la mayoría de los frameworks de NodeJS probados y a la par con Go, que es un lenguaje compilado más cercano a C <a href="https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1" class="external-link" target="_blank">(todo gracias a Starlette)</a>.
+
+### ¿Es la concurrencia mejor que el paralelismo?
+
+¡No! Esa no es la moraleja de la historia.
+
+La concurrencia es diferente del paralelismo. Y es mejor en escenarios **específicos** que implican mucha espera. Debido a eso, generalmente es mucho mejor que el paralelismo para el desarrollo de aplicaciones web. Pero no para todo.
+
+Así que, para equilibrar eso, imagina la siguiente historia corta:
+
+> Tienes que limpiar una casa grande y sucia.
+
+*Sí, esa es toda la historia*.
+
+---
+
+No hay esperas 🕙 en ninguna parte, solo mucho trabajo por hacer, en múltiples lugares de la casa.
+
+Podrías tener turnos como en el ejemplo de las hamburguesas, primero la sala de estar, luego la cocina, pero como no estás esperando 🕙 nada, solo limpiando y limpiando, los turnos no afectarían nada.
+
+Tomaría la misma cantidad de tiempo terminar con o sin turnos (concurrencia) y habrías hecho la misma cantidad de trabajo.
+
+Pero en este caso, si pudieras traer a los 8 ex-cajeros/cocineros/ahora-limpiadores, y cada uno de ellos (más tú) pudiera tomar una zona de la casa para limpiarla, podrías hacer todo el trabajo en **paralelo**, con la ayuda extra, y terminar mucho antes.
+
+En este escenario, cada uno de los limpiadores (incluyéndote) sería un procesador, haciendo su parte del trabajo.
+
+Y como la mayor parte del tiempo de ejecución se dedica al trabajo real (en lugar de esperar), y el trabajo en una computadora lo realiza una <abbr title="Central Processing Unit">CPU</abbr>, llaman a estos problemas "CPU bound".
+
+---
+
+Ejemplos comunes de operaciones limitadas por la CPU son cosas que requieren procesamiento matemático complejo.
+
+Por ejemplo:
+
+* **Procesamiento de audio** o **imágenes**.
+* **Visión por computadora**: una imagen está compuesta de millones de píxeles, cada píxel tiene 3 valores / colores, procesar eso normalmente requiere calcular algo en esos píxeles, todos al mismo tiempo.
+* **Machine Learning**: normalmente requiere muchas multiplicaciones de "matrices" y "vectores". Piensa en una enorme hoja de cálculo con números y multiplicando todos juntos al mismo tiempo.
+* **Deep Learning**: este es un subcampo de Machine Learning, por lo tanto, se aplica lo mismo. Es solo que no hay una sola hoja de cálculo de números para multiplicar, sino un enorme conjunto de ellas, y en muchos casos, usas un procesador especial para construir y / o usar esos modelos.
+
+### Concurrencia + Paralelismo: Web + Machine Learning
+
+Con **FastAPI** puedes aprovechar la concurrencia que es muy común para el desarrollo web (la misma atracción principal de NodeJS).
+
+Pero también puedes explotar los beneficios del paralelismo y la multiprocesamiento (tener múltiples procesos ejecutándose en paralelo) para cargas de trabajo **CPU bound** como las de los sistemas de Machine Learning.
+
+Eso, más el simple hecho de que Python es el lenguaje principal para **Data Science**, Machine Learning y especialmente Deep Learning, hacen de FastAPI una muy buena opción para APIs web de Data Science / Machine Learning y aplicaciones (entre muchas otras).
+
+Para ver cómo lograr este paralelismo en producción, consulta la sección sobre [Deployment](deployment/index.md){.internal-link target=_blank}.
+
+## `async` y `await`
+
+Las versiones modernas de Python tienen una forma muy intuitiva de definir código asíncrono. Esto hace que se vea igual que el código "secuencial" normal y hace el "wait" por ti en los momentos adecuados.
+
+Cuando hay una operación que requerirá esperar antes de dar los resultados y tiene soporte para estas nuevas funcionalidades de Python, puedes programarlo así:
+
+```Python
+burgers = await get_burgers(2)
+```
+
+La clave aquí es el `await`. Dice a Python que tiene que esperar ⏸ a que `get_burgers(2)` termine de hacer su cosa 🕙 antes de almacenar los resultados en `burgers`. Con eso, Python sabrá que puede ir y hacer algo más 🔀 ⏯ mientras tanto (como recibir otro request).
+
+Para que `await` funcione, tiene que estar dentro de una función que soporte esta asincronía. Para hacer eso, solo declara la función con `async def`:
+
+```Python hl_lines="1"
+async def get_burgers(number: int):
+    # Hacer algunas cosas asíncronas para crear las hamburguesas
+    return burgers
+```
+
+...en lugar de `def`:
+
+```Python hl_lines="2"
+# Esto no es asíncrono
+def get_sequential_burgers(number: int):
+    # Hacer algunas cosas secuenciales para crear las hamburguesas
+    return burgers
+```
+
+Con `async def`, Python sabe que, dentro de esa función, tiene que estar atento a las expresiones `await`, y que puede "pausar" ⏸ la ejecución de esa función e ir a hacer algo más 🔀 antes de regresar.
+
+Cuando deseas llamar a una función `async def`, tienes que "await" dicha función. Así que, esto no funcionará:
+
+```Python
+# Esto no funcionará, porque get_burgers fue definido con: async def
+burgers = get_burgers(2)
+```
+
+---
+
+Así que, si estás usando un paquete que te dice que puedes llamarlo con `await`, necesitas crear las *path operation functions* que lo usen con `async def`, como en:
+
+```Python hl_lines="2-3"
+@app.get('/burgers')
+async def read_burgers():
+    burgers = await get_burgers(2)
+    return burgers
+```
+
+### Más detalles técnicos
+
+Podrías haber notado que `await` solo se puede usar dentro de funciones definidas con `async def`.
+
+Pero al mismo tiempo, las funciones definidas con `async def` deben ser "awaited". Por lo tanto, las funciones con `async def` solo se pueden llamar dentro de funciones definidas con `async def` también.
+
+Entonces, sobre el huevo y la gallina, ¿cómo llamas a la primera función `async`?
+
+Si estás trabajando con **FastAPI** no tienes que preocuparte por eso, porque esa "primera" función será tu *path operation function*, y FastAPI sabrá cómo hacer lo correcto.
+
+Pero si deseas usar `async` / `await` sin FastAPI, también puedes hacerlo.
+
+### Escribe tu propio código async
+
+Starlette (y **FastAPI**) están basados en <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a>, lo que lo hace compatible tanto con la librería estándar de Python <a href="https://docs.python.org/3/library/asyncio-task.html" class="external-link" target="_blank">asyncio</a> como con <a href="https://trio.readthedocs.io/en/stable/" class="external-link" target="_blank">Trio</a>.
+
+En particular, puedes usar directamente <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a> para tus casos de uso avanzados de concurrencia que requieran patrones más avanzados en tu propio código.
+
+E incluso si no estuvieras usando FastAPI, también podrías escribir tus propias aplicaciones asíncronas con <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a> para ser altamente compatibles y obtener sus beneficios (p.ej. *concurrencia estructurada*).
+
+Creé otro paquete sobre AnyIO, como una capa delgada, para mejorar un poco las anotaciones de tipos y obtener mejor **autocompletado**, **errores en línea**, etc. También tiene una introducción amigable y tutorial para ayudarte a **entender** y escribir **tu propio código async**: <a href="https://asyncer.tiangolo.com/" class="external-link" target="_blank">Asyncer</a>. Sería particularmente útil si necesitas **combinar código async con regular** (bloqueante/sincrónico).
+
+### Otras formas de código asíncrono
+
+Este estilo de usar `async` y `await` es relativamente nuevo en el lenguaje.
+
+Pero hace que trabajar con código asíncrono sea mucho más fácil.
+
+Esta misma sintaxis (o casi idéntica) también se incluyó recientemente en las versiones modernas de JavaScript (en el Navegador y NodeJS).
+
+Pero antes de eso, manejar el código asíncrono era mucho más complejo y difícil.
+
+En versiones previas de Python, podrías haber usado hilos o <a href="https://www.gevent.org/" class="external-link" target="_blank">Gevent</a>. Pero el código es mucho más complejo de entender, depurar y razonar.
+
+En versiones previas de NodeJS / JavaScript en el Navegador, habrías usado "callbacks". Lo que lleva al "callback hell".
+
+## Coroutines
+
+**Coroutines** es simplemente el término muy elegante para la cosa que devuelve una función `async def`. Python sabe que es algo parecido a una función, que puede comenzar y que terminará en algún momento, pero que podría pausar ⏸ internamente también, siempre que haya un `await` dentro de él.
+
+Pero toda esta funcionalidad de usar código asíncrono con `async` y `await` a menudo se resume como utilizar "coroutines". Es comparable a la funcionalidad clave principal de Go, las "Goroutines".
+
+## Conclusión
+
+Veamos la misma frase de arriba:
+
+> Las versiones modernas de Python tienen soporte para **"código asíncrono"** utilizando algo llamado **"coroutines"**, con la sintaxis **`async` y `await`**.
+
+Eso debería tener más sentido ahora. ✨
+
+Todo eso es lo que impulsa FastAPI (a través de Starlette) y lo que hace que tenga un rendimiento tan impresionante.
+
+## Detalles Muy Técnicos
+
+/// warning | Advertencia
+
+Probablemente puedas saltarte esto.
+
+Estos son detalles muy técnicos de cómo funciona **FastAPI** en su interior.
+
+Si tienes bastante conocimiento técnico (coroutines, hilos, bloqueo, etc.) y tienes curiosidad sobre cómo FastAPI maneja `async def` vs `def` normal, adelante.
+
+///
+
+### Funciones de *path operation*
+
+Cuando declaras una *path operation function* con `def` normal en lugar de `async def`, se ejecuta en un threadpool externo que luego es esperado, en lugar de ser llamado directamente (ya que bloquearía el servidor).
+
+Si vienes de otro framework async que no funciona de la manera descrita anteriormente y estás acostumbrado a definir funciones de *path operation* solo de cómputo trivial con `def` normal para una pequeña ganancia de rendimiento (alrededor de 100 nanosegundos), ten en cuenta que en **FastAPI** el efecto sería bastante opuesto. En estos casos, es mejor usar `async def` a menos que tus *path operation functions* usen código que realice <abbr title="Input/Output: lectura o escritura en disco, comunicaciones de red.">I/O</abbr> de bloqueo.
+
+Aun así, en ambas situaciones, es probable que **FastAPI** [siga siendo más rápida](index.md#performance){.internal-link target=_blank} que (o al menos comparable a) tu framework anterior.
+
+### Dependencias
+
+Lo mismo aplica para las [dependencias](tutorial/dependencies/index.md){.internal-link target=_blank}. Si una dependencia es una función estándar `def` en lugar de `async def`, se ejecuta en el threadpool externo.
+
+### Sub-dependencias
+
+Puedes tener múltiples dependencias y [sub-dependencias](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} requiriéndose mutuamente (como parámetros de las definiciones de funciones), algunas de ellas podrían ser creadas con `async def` y algunas con `def` normal. Aun funcionará, y las que fueron creadas con `def` normal serían llamadas en un hilo externo (del threadpool) en lugar de ser "awaited".
+
+### Otras funciones de utilidad
+
+Cualquier otra función de utilidad que llames directamente puede ser creada con `def` normal o `async def` y FastAPI no afectará la forma en que la llames.
+
+Esto contrasta con las funciones que FastAPI llama por ti: *path operation functions* y dependencias.
+
+Si tu función de utilidad es una función normal con `def`, será llamada directamente (como la escribas en tu código), no en un threadpool; si la función es creada con `async def` entonces deberías "await" por esa función cuando la llames en tu código.
+
+---
+
+Nuevamente, estos son detalles muy técnicos que probablemente serían útiles si los buscaste.
+
+De lo contrario, deberías estar bien con las pautas de la sección anterior: <a href="#in-a-hurry">¿Con prisa?</a>.

docs/es/docs/benchmarks.md

@@ -0,0 +1,34 @@
+# Benchmarks
+
+Los benchmarks independientes de TechEmpower muestran aplicaciones de **FastAPI** ejecutándose bajo Uvicorn como <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">uno de los frameworks de Python más rápidos disponibles</a>, solo por debajo de Starlette y Uvicorn en sí mismos (utilizados internamente por FastAPI).
+
+Pero al revisar benchmarks y comparaciones, debes tener en cuenta lo siguiente.
+
+## Benchmarks y velocidad
+
+Cuando ves los benchmarks, es común ver varias herramientas de diferentes tipos comparadas como equivalentes.
+
+Específicamente, ver Uvicorn, Starlette y FastAPI comparados juntos (entre muchas otras herramientas).
+
+Cuanto más simple sea el problema resuelto por la herramienta, mejor rendimiento tendrá. Y la mayoría de los benchmarks no prueban las funcionalidades adicionales proporcionadas por la herramienta.
+
+La jerarquía es como:
+
+* **Uvicorn**: un servidor ASGI
+    * **Starlette**: (usa Uvicorn) un microframework web
+        * **FastAPI**: (usa Starlette) un microframework para APIs con varias funcionalidades adicionales para construir APIs, con validación de datos, etc.
+
+* **Uvicorn**:
+    * Tendrá el mejor rendimiento, ya que no tiene mucho código extra aparte del propio servidor.
+    * No escribirías una aplicación directamente en Uvicorn. Eso significaría que tu código tendría que incluir, más o menos, al menos, todo el código proporcionado por Starlette (o **FastAPI**). Y si hicieras eso, tu aplicación final tendría la misma carga que si hubieras usado un framework, minimizando el código de tu aplicación y los bugs.
+    * Si estás comparando Uvicorn, compáralo con Daphne, Hypercorn, uWSGI, etc. Servidores de aplicaciones.
+* **Starlette**:
+    * Tendrá el siguiente mejor rendimiento, después de Uvicorn. De hecho, Starlette usa Uvicorn para ejecutarse. Así que probablemente solo pueda ser "más lento" que Uvicorn por tener que ejecutar más código.
+    * Pero te proporciona las herramientas para construir aplicaciones web sencillas, con enrutamiento basado en paths, etc.
+    * Si estás comparando Starlette, compáralo con Sanic, Flask, Django, etc. Frameworks web (o microframeworks).
+* **FastAPI**:
+    * De la misma forma en que Starlette usa Uvicorn y no puede ser más rápido que él, **FastAPI** usa Starlette, por lo que no puede ser más rápido que él.
+    * FastAPI ofrece más funcionalidades además de las de Starlette. Funcionalidades que casi siempre necesitas al construir APIs, como la validación y serialización de datos. Y al utilizarlo, obtienes documentación automática gratis (la documentación automática ni siquiera añade carga a las aplicaciones en ejecución, se genera al inicio).
+    * Si no usabas FastAPI y utilizabas Starlette directamente (u otra herramienta, como Sanic, Flask, Responder, etc.) tendrías que implementar toda la validación y serialización de datos por ti mismo. Entonces, tu aplicación final aún tendría la misma carga que si hubiera sido construida usando FastAPI. Y en muchos casos, esta validación y serialización de datos es la mayor cantidad de código escrito en las aplicaciones.
+    * Entonces, al usar FastAPI estás ahorrando tiempo de desarrollo, bugs, líneas de código, y probablemente obtendrías el mismo rendimiento (o mejor) que si no lo usaras (ya que tendrías que implementarlo todo en tu código).
+    * Si estás comparando FastAPI, compáralo con un framework de aplicación web (o conjunto de herramientas) que proporcione validación de datos, serialización y documentación, como Flask-apispec, NestJS, Molten, etc. Frameworks con validación de datos, serialización y documentación automáticas integradas.

docs/es/docs/deployment/cloud.md

@@ -0,0 +1,15 @@
+# Despliega FastAPI en Proveedores de Nube
+
+Puedes usar prácticamente **cualquier proveedor de nube** para desplegar tu aplicación FastAPI.
+
+En la mayoría de los casos, los principales proveedores de nube tienen guías para desplegar FastAPI con ellos.
+
+## Proveedores de Nube - Sponsors
+
+Algunos proveedores de nube ✨ [**son sponsors de FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, esto asegura el desarrollo **continuado** y **saludable** de FastAPI y su **ecosistema**.
+
+Y muestra su verdadero compromiso con FastAPI y su **comunidad** (tú), ya que no solo quieren proporcionarte un **buen servicio**, sino también asegurarse de que tengas un **framework bueno y saludable**, FastAPI. 🙇
+
+Podrías querer probar sus servicios y seguir sus guías:
+
+* <a href="https://docs.render.com/deploy-fastapi?utm_source=deploydoc&utm_medium=referral&utm_campaign=fastapi" class="external-link" target="_blank">Render</a>

docs/es/docs/deployment/concepts.md

@@ -0,0 +1,321 @@
+# Conceptos de Implementación
+
+Cuando implementas una aplicación **FastAPI**, o en realidad, cualquier tipo de API web, hay varios conceptos que probablemente te importen, y al entenderlos, puedes encontrar la **forma más adecuada** de **implementar tu aplicación**.
+
+Algunos de los conceptos importantes son:
+
+* Seguridad - HTTPS
+* Ejecución al iniciar
+* Reinicios
+* Replicación (la cantidad de procesos en ejecución)
+* Memoria
+* Pasos previos antes de iniciar
+
+Veremos cómo afectan estas **implementaciones**.
+
+Al final, el objetivo principal es poder **servir a tus clientes de API** de una manera que sea **segura**, para **evitar interrupciones**, y usar los **recursos de cómputo** (por ejemplo, servidores remotos/máquinas virtuales) de la manera más eficiente posible. 🚀
+
+Te contaré un poquito más sobre estos **conceptos** aquí, y eso, con suerte, te dará la **intuición** que necesitarías para decidir cómo implementar tu API en diferentes entornos, posiblemente incluso en aquellos **futuros** que aún no existen.
+
+Al considerar estos conceptos, podrás **evaluar y diseñar** la mejor manera de implementar **tus propias APIs**.
+
+En los próximos capítulos, te daré más **recetas concretas** para implementar aplicaciones de FastAPI.
+
+Pero por ahora, revisemos estas importantes **ideas conceptuales**. Estos conceptos también se aplican a cualquier otro tipo de API web. 💡
+
+## Seguridad - HTTPS
+
+En el [capítulo anterior sobre HTTPS](https.md){.internal-link target=_blank} aprendimos sobre cómo HTTPS proporciona cifrado para tu API.
+
+También vimos que HTTPS es normalmente proporcionado por un componente **externo** a tu servidor de aplicaciones, un **Proxy de Terminación TLS**.
+
+Y debe haber algo encargado de **renovar los certificados HTTPS**, podría ser el mismo componente o algo diferente.
+
+### Herramientas de Ejemplo para HTTPS
+
+Algunas de las herramientas que podrías usar como Proxy de Terminación TLS son:
+
+* Traefik
+    * Maneja automáticamente las renovaciones de certificados ✨
+* Caddy
+    * Maneja automáticamente las renovaciones de certificados ✨
+* Nginx
+    * Con un componente externo como Certbot para las renovaciones de certificados
+* HAProxy
+    * Con un componente externo como Certbot para las renovaciones de certificados
+* Kubernetes con un Controlador de Ingress como Nginx
+    * Con un componente externo como cert-manager para las renovaciones de certificados
+* Manejado internamente por un proveedor de nube como parte de sus servicios (lee abajo 👇)
+
+Otra opción es que podrías usar un **servicio de nube** que haga más del trabajo, incluyendo configurar HTTPS. Podría tener algunas restricciones o cobrarte más, etc. Pero en ese caso, no tendrías que configurar un Proxy de Terminación TLS tú mismo.
+
+Te mostraré algunos ejemplos concretos en los próximos capítulos.
+
+---
+
+Luego, los siguientes conceptos a considerar son todos acerca del programa que ejecuta tu API real (por ejemplo, Uvicorn).
+
+## Programa y Proceso
+
+Hablaremos mucho sobre el "**proceso**" en ejecución, así que es útil tener claridad sobre lo que significa y cuál es la diferencia con la palabra "**programa**".
+
+### Qué es un Programa
+
+La palabra **programa** se usa comúnmente para describir muchas cosas:
+
+* El **código** que escribes, los **archivos Python**.
+* El **archivo** que puede ser **ejecutado** por el sistema operativo, por ejemplo: `python`, `python.exe` o `uvicorn`.
+* Un programa específico mientras está siendo **ejecutado** en el sistema operativo, usando la CPU y almacenando cosas en la memoria. Esto también se llama **proceso**.
+
+### Qué es un Proceso
+
+La palabra **proceso** se usa normalmente de una manera más específica, refiriéndose solo a lo que está ejecutándose en el sistema operativo (como en el último punto anterior):
+
+* Un programa específico mientras está siendo **ejecutado** en el sistema operativo.
+    * Esto no se refiere al archivo, ni al código, se refiere **específicamente** a lo que está siendo **ejecutado** y gestionado por el sistema operativo.
+* Cualquier programa, cualquier código, **solo puede hacer cosas** cuando está siendo **ejecutado**. Así que, cuando hay un **proceso en ejecución**.
+* El proceso puede ser **terminado** (o "matado") por ti, o por el sistema operativo. En ese punto, deja de ejecutarse/ser ejecutado, y ya no puede **hacer cosas**.
+* Cada aplicación que tienes en ejecución en tu computadora tiene algún proceso detrás, cada programa en ejecución, cada ventana, etc. Y normalmente hay muchos procesos ejecutándose **al mismo tiempo** mientras una computadora está encendida.
+* Puede haber **múltiples procesos** del **mismo programa** ejecutándose al mismo tiempo.
+
+Si revisas el "administrador de tareas" o "monitor del sistema" (o herramientas similares) en tu sistema operativo, podrás ver muchos de esos procesos en ejecución.
+
+Y, por ejemplo, probablemente verás que hay múltiples procesos ejecutando el mismo programa del navegador (Firefox, Chrome, Edge, etc.). Normalmente ejecutan un proceso por pestaña, además de algunos otros procesos extra.
+
+<img class="shadow" src="/img/deployment/concepts/image01.png">
+
+---
+
+Ahora que conocemos la diferencia entre los términos **proceso** y **programa**, sigamos hablando sobre implementaciones.
+
+## Ejecución al Iniciar
+
+En la mayoría de los casos, cuando creas una API web, quieres que esté **siempre en ejecución**, ininterrumpida, para que tus clientes puedan acceder a ella en cualquier momento. Esto, por supuesto, a menos que tengas una razón específica para que se ejecute solo en ciertas situaciones, pero la mayoría de las veces quieres que esté constantemente en ejecución y **disponible**.
+
+### En un Servidor Remoto
+
+Cuando configuras un servidor remoto (un servidor en la nube, una máquina virtual, etc.) lo más sencillo que puedes hacer es usar `fastapi run` (que utiliza Uvicorn) o algo similar, manualmente, de la misma manera que lo haces al desarrollar localmente.
+
+Y funcionará y será útil **durante el desarrollo**.
+
+Pero si pierdes la conexión con el servidor, el **proceso en ejecución** probablemente morirá.
+
+Y si el servidor se reinicia (por ejemplo, después de actualizaciones o migraciones del proveedor de la nube) probablemente **no lo notarás**. Y debido a eso, ni siquiera sabrás que tienes que reiniciar el proceso manualmente. Así, tu API simplemente quedará muerta. 😱
+
+### Ejecutar Automáticamente al Iniciar
+
+En general, probablemente querrás que el programa del servidor (por ejemplo, Uvicorn) se inicie automáticamente al arrancar el servidor, y sin necesidad de ninguna **intervención humana**, para tener siempre un proceso en ejecución con tu API (por ejemplo, Uvicorn ejecutando tu aplicación FastAPI).
+
+### Programa Separado
+
+Para lograr esto, normalmente tendrás un **programa separado** que se asegurará de que tu aplicación se ejecute al iniciarse. Y en muchos casos, también se asegurará de que otros componentes o aplicaciones se ejecuten, por ejemplo, una base de datos.
+
+### Herramientas de Ejemplo para Ejecutar al Iniciar
+
+Algunos ejemplos de las herramientas que pueden hacer este trabajo son:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Docker en Modo Swarm
+* Systemd
+* Supervisor
+* Manejado internamente por un proveedor de nube como parte de sus servicios
+* Otros...
+
+Te daré más ejemplos concretos en los próximos capítulos.
+
+## Reinicios
+
+De manera similar a asegurarte de que tu aplicación se ejecute al iniciar, probablemente también quieras asegurarte de que se **reinicie** después de fallos.
+
+### Cometemos Errores
+
+Nosotros, como humanos, cometemos **errores**, todo el tiempo. El software casi *siempre* tiene **bugs** ocultos en diferentes lugares. 🐛
+
+Y nosotros, como desarrolladores, seguimos mejorando el código a medida que encontramos esos bugs y a medida que implementamos nuevas funcionalidades (posiblemente agregando nuevos bugs también 😅).
+
+### Errores Pequeños Manejados Automáticamente
+
+Al construir APIs web con FastAPI, si hay un error en nuestro código, FastAPI normalmente lo contiene a la solicitud única que desencadenó el error. 🛡
+
+El cliente obtendrá un **500 Internal Server Error** para esa solicitud, pero la aplicación continuará funcionando para las siguientes solicitudes en lugar de simplemente colapsar por completo.
+
+### Errores Mayores - Colapsos
+
+Sin embargo, puede haber casos en los que escribamos algún código que **colapse toda la aplicación** haciendo que Uvicorn y Python colapsen. 💥
+
+Y aún así, probablemente no querrías que la aplicación quede muerta porque hubo un error en un lugar, probablemente querrás que **siga ejecutándose** al menos para las *path operations* que no estén rotas.
+
+### Reiniciar Después del Colapso
+
+Pero en esos casos con errores realmente malos que colapsan el **proceso en ejecución**, querrías un componente externo encargado de **reiniciar** el proceso, al menos un par de veces...
+
+/// tip | Consejo
+
+...Aunque si la aplicación completa **colapsa inmediatamente**, probablemente no tenga sentido seguir reiniciándola eternamente. Pero en esos casos, probablemente lo notarás durante el desarrollo, o al menos justo después de la implementación.
+
+Así que enfoquémonos en los casos principales, donde podría colapsar por completo en algunos casos particulares **en el futuro**, y aún así tenga sentido reiniciarla.
+
+///
+
+Probablemente querrías que la cosa encargada de reiniciar tu aplicación sea un **componente externo**, porque para ese punto, la misma aplicación con Uvicorn y Python ya colapsó, así que no hay nada en el mismo código de la misma aplicación que pueda hacer algo al respecto.
+
+### Herramientas de Ejemplo para Reiniciar Automáticamente
+
+En la mayoría de los casos, la misma herramienta que se utiliza para **ejecutar el programa al iniciar** también se utiliza para manejar reinicios automáticos.
+
+Por ejemplo, esto podría ser manejado por:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Docker en Modo Swarm
+* Systemd
+* Supervisor
+* Manejado internamente por un proveedor de nube como parte de sus servicios
+* Otros...
+
+## Replicación - Procesos y Memoria
+
+Con una aplicación FastAPI, usando un programa servidor como el comando `fastapi` que ejecuta Uvicorn, ejecutarlo una vez en **un proceso** puede servir a múltiples clientes concurrentemente.
+
+Pero en muchos casos, querrás ejecutar varios worker processes al mismo tiempo.
+
+### Múltiples Procesos - Workers
+
+Si tienes más clientes de los que un solo proceso puede manejar (por ejemplo, si la máquina virtual no es muy grande) y tienes **múltiples núcleos** en la CPU del servidor, entonces podrías tener **múltiples procesos** ejecutando la misma aplicación al mismo tiempo, y distribuir todas las requests entre ellos.
+
+Cuando ejecutas **múltiples procesos** del mismo programa de API, comúnmente se les llama **workers**.
+
+### Worker Processes y Puertos
+
+Recuerda de la documentación [Sobre HTTPS](https.md){.internal-link target=_blank} que solo un proceso puede estar escuchando en una combinación de puerto y dirección IP en un servidor.
+
+Esto sigue siendo cierto.
+
+Así que, para poder tener **múltiples procesos** al mismo tiempo, tiene que haber un **solo proceso escuchando en un puerto** que luego transmita la comunicación a cada worker process de alguna forma.
+
+### Memoria por Proceso
+
+Ahora, cuando el programa carga cosas en memoria, por ejemplo, un modelo de machine learning en una variable, o el contenido de un archivo grande en una variable, todo eso **consume un poco de la memoria (RAM)** del servidor.
+
+Y múltiples procesos normalmente **no comparten ninguna memoria**. Esto significa que cada proceso en ejecución tiene sus propias cosas, variables y memoria. Y si estás consumiendo una gran cantidad de memoria en tu código, **cada proceso** consumirá una cantidad equivalente de memoria.
+
+### Memoria del Servidor
+
+Por ejemplo, si tu código carga un modelo de Machine Learning con **1 GB de tamaño**, cuando ejecutas un proceso con tu API, consumirá al menos 1 GB de RAM. Y si inicias **4 procesos** (4 workers), cada uno consumirá 1 GB de RAM. Así que, en total, tu API consumirá **4 GB de RAM**.
+
+Y si tu servidor remoto o máquina virtual solo tiene 3 GB de RAM, intentar cargar más de 4 GB de RAM causará problemas. 🚨
+
+### Múltiples Procesos - Un Ejemplo
+
+En este ejemplo, hay un **Proceso Administrador** que inicia y controla dos **Worker Processes**.
+
+Este Proceso Administrador probablemente sería el que escuche en el **puerto** en la IP. Y transmitirá toda la comunicación a los worker processes.
+
+Esos worker processes serían los que ejecutan tu aplicación, realizarían los cálculos principales para recibir un **request** y devolver un **response**, y cargarían cualquier cosa que pongas en variables en RAM.
+
+<img src="/img/deployment/concepts/process-ram.drawio.svg">
+
+Y por supuesto, la misma máquina probablemente tendría **otros procesos** ejecutándose también, aparte de tu aplicación.
+
+Un detalle interesante es que el porcentaje de **CPU utilizado** por cada proceso puede **variar** mucho con el tiempo, pero la **memoria (RAM)** normalmente permanece más o menos **estable**.
+
+Si tienes una API que hace una cantidad comparable de cálculos cada vez y tienes muchos clientes, entonces la **utilización de CPU** probablemente *también sea estable* (en lugar de constantemente subir y bajar rápidamente).
+
+### Ejemplos de Herramientas y Estrategias de Replicación
+
+Puede haber varios enfoques para lograr esto, y te contaré más sobre estrategias específicas en los próximos capítulos, por ejemplo, al hablar sobre Docker y contenedores.
+
+La principal restricción a considerar es que tiene que haber un **componente único** manejando el **puerto** en la **IP pública**. Y luego debe tener una forma de **transmitir** la comunicación a los **procesos/workers** replicados.
+
+Aquí hay algunas combinaciones y estrategias posibles:
+
+* **Uvicorn** con `--workers`
+    * Un administrador de procesos de Uvicorn **escucharía** en la **IP** y **puerto**, y iniciaría **múltiples worker processes de Uvicorn**.
+* **Kubernetes** y otros sistemas de **contenedor distribuidos**
+    * Algo en la capa de **Kubernetes** escucharía en la **IP** y **puerto**. La replicación sería al tener **múltiples contenedores**, cada uno con **un proceso de Uvicorn** ejecutándose.
+* **Servicios en la Nube** que manejan esto por ti
+    * El servicio en la nube probablemente **manejará la replicación por ti**. Posiblemente te permitiría definir **un proceso para ejecutar**, o una **imagen de contenedor** para usar, en cualquier caso, lo más probable es que sería **un solo proceso de Uvicorn**, y el servicio en la nube se encargaría de replicarlo.
+
+/// tip | Consejo
+
+No te preocupes si algunos de estos elementos sobre **contenedores**, Docker, o Kubernetes no tienen mucho sentido todavía.
+
+Te contaré más sobre imágenes de contenedores, Docker, Kubernetes, etc. en un capítulo futuro: [FastAPI en Contenedores - Docker](docker.md){.internal-link target=_blank}.
+
+///
+
+## Pasos Previos Antes de Iniciar
+
+Hay muchos casos en los que quieres realizar algunos pasos **antes de iniciar** tu aplicación.
+
+Por ejemplo, podrías querer ejecutar **migraciones de base de datos**.
+
+Pero en la mayoría de los casos, querrás realizar estos pasos solo **una vez**.
+
+Así que, querrás tener un **único proceso** para realizar esos **pasos previos**, antes de iniciar la aplicación.
+
+Y tendrás que asegurarte de que sea un único proceso ejecutando esos pasos previos incluso si después, inicias **múltiples procesos** (múltiples workers) para la propia aplicación. Si esos pasos fueran ejecutados por **múltiples procesos**, **duplicarían** el trabajo al ejecutarlo en **paralelo**, y si los pasos fueran algo delicado como una migración de base de datos, podrían causar conflictos entre sí.
+
+Por supuesto, hay algunos casos en los que no hay problema en ejecutar los pasos previos múltiples veces, en ese caso, es mucho más fácil de manejar.
+
+/// tip | Consejo
+
+También, ten en cuenta que dependiendo de tu configuración, en algunos casos **quizás ni siquiera necesites realizar pasos previos** antes de iniciar tu aplicación.
+
+En ese caso, no tendrías que preocuparte por nada de esto. 🤷
+
+///
+
+### Ejemplos de Estrategias para Pasos Previos
+
+Esto **dependerá mucho** de la forma en que **implementarás tu sistema**, y probablemente estará conectado con la forma en que inicias programas, manejas reinicios, etc.
+
+Aquí hay algunas ideas posibles:
+
+* Un "Contenedor de Inicio" en Kubernetes que se ejecuta antes de tu contenedor de aplicación
+* Un script de bash que ejecuta los pasos previos y luego inicia tu aplicación
+    * Aún necesitarías una forma de iniciar/reiniciar *ese* script de bash, detectar errores, etc.
+
+/// tip | Consejo
+
+Te daré más ejemplos concretos para hacer esto con contenedores en un capítulo futuro: [FastAPI en Contenedores - Docker](docker.md){.internal-link target=_blank}.
+
+///
+
+## Utilización de Recursos
+
+Tu(s) servidor(es) es(son) un **recurso** que puedes consumir o **utilizar**, con tus programas, el tiempo de cómputo en las CPUs y la memoria RAM disponible.
+
+¿Cuánto de los recursos del sistema quieres consumir/utilizar? Podría ser fácil pensar "no mucho", pero en realidad, probablemente querrás consumir **lo más posible sin colapsar**.
+
+Si estás pagando por 3 servidores pero solo estás usando un poquito de su RAM y CPU, probablemente estés **desperdiciando dinero** 💸, y probablemente **desperdiciando la energía eléctrica del servidor** 🌎, etc.
+
+En ese caso, podría ser mejor tener solo 2 servidores y usar un mayor porcentaje de sus recursos (CPU, memoria, disco, ancho de banda de red, etc.).
+
+Por otro lado, si tienes 2 servidores y estás usando **100% de su CPU y RAM**, en algún momento un proceso pedirá más memoria y el servidor tendrá que usar el disco como "memoria" (lo cual puede ser miles de veces más lento), o incluso **colapsar**. O un proceso podría necesitar hacer algún cálculo y tendría que esperar hasta que la CPU esté libre de nuevo.
+
+En este caso, sería mejor obtener **un servidor extra** y ejecutar algunos procesos en él para que todos tengan **suficiente RAM y tiempo de CPU**.
+
+También existe la posibilidad de que, por alguna razón, tengas un **pico** de uso de tu API. Tal vez se volvió viral, o tal vez otros servicios o bots comienzan a usarla. Y podrías querer tener recursos extra para estar a salvo en esos casos.
+
+Podrías establecer un **número arbitrario** para alcanzar, por ejemplo, algo **entre 50% a 90%** de utilización de recursos. El punto es que esas son probablemente las principales cosas que querrás medir y usar para ajustar tus implementaciones.
+
+Puedes usar herramientas simples como `htop` para ver la CPU y RAM utilizadas en tu servidor o la cantidad utilizada por cada proceso. O puedes usar herramientas de monitoreo más complejas, que pueden estar distribuidas a través de servidores, etc.
+
+## Resumen
+
+Has estado leyendo aquí algunos de los conceptos principales que probablemente necesitarás tener en mente al decidir cómo implementar tu aplicación:
+
+* Seguridad - HTTPS
+* Ejecución al iniciar
+* Reinicios
+* Replicación (la cantidad de procesos en ejecución)
+* Memoria
+* Pasos previos antes de iniciar
+
+Comprender estas ideas y cómo aplicarlas debería darte la intuición necesaria para tomar decisiones al configurar y ajustar tus implementaciones. 🤓
+
+En las próximas secciones, te daré ejemplos más concretos de posibles estrategias que puedes seguir. 🚀

docs/es/docs/deployment/docker.md

@@ -0,0 +1,620 @@
+# FastAPI en Contenedores - Docker
+
+Al desplegar aplicaciones de FastAPI, un enfoque común es construir una **imagen de contenedor de Linux**. Normalmente se realiza usando <a href="https://www.docker.com/" class="external-link" target="_blank">**Docker**</a>. Luego puedes desplegar esa imagen de contenedor de varias formas.
+
+Usar contenedores de Linux tiene varias ventajas, incluyendo **seguridad**, **replicabilidad**, **simplicidad**, y otras.
+
+/// tip | Consejo
+
+¿Tienes prisa y ya conoces esto? Salta al [`Dockerfile` más abajo 👇](#construir-una-imagen-de-docker-para-fastapi).
+
+///
+
+<details>
+<summary>Vista previa del Dockerfile 👀</summary>
+
+```Dockerfile
+FROM python:3.9
+
+WORKDIR /code
+
+COPY ./requirements.txt /code/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+COPY ./app /code/app
+
+CMD ["fastapi", "run", "app/main.py", "--port", "80"]
+
+# Si estás detrás de un proxy como Nginx o Traefik añade --proxy-headers
+# CMD ["fastapi", "run", "app/main.py", "--port", "80", "--proxy-headers"]
+```
+
+</details>
+
+## Qué es un Contenedor
+
+Los contenedores (principalmente contenedores de Linux) son una forma muy **ligera** de empaquetar aplicaciones incluyendo todas sus dependencias y archivos necesarios, manteniéndolos aislados de otros contenedores (otras aplicaciones o componentes) en el mismo sistema.
+
+Los contenedores de Linux se ejecutan utilizando el mismo núcleo de Linux del host (máquina, máquina virtual, servidor en la nube, etc.). Esto significa que son muy ligeros (en comparación con las máquinas virtuales completas que emulan un sistema operativo completo).
+
+De esta forma, los contenedores consumen **pocos recursos**, una cantidad comparable a ejecutar los procesos directamente (una máquina virtual consumiría mucho más).
+
+Los contenedores también tienen sus propios procesos de ejecución **aislados** (normalmente solo un proceso), sistema de archivos y red, simplificando el despliegue, la seguridad, el desarrollo, etc.
+
+## Qué es una Imagen de Contenedor
+
+Un **contenedor** se ejecuta desde una **imagen de contenedor**.
+
+Una imagen de contenedor es una versión **estática** de todos los archivos, variables de entorno y el comando/programa por defecto que debería estar presente en un contenedor. **Estático** aquí significa que la imagen de contenedor **no se está ejecutando**, no está siendo ejecutada, son solo los archivos empaquetados y los metadatos.
+
+En contraste con una "**imagen de contenedor**" que son los contenidos estáticos almacenados, un "**contenedor**" normalmente se refiere a la instance en ejecución, lo que está siendo **ejecutado**.
+
+Cuando el **contenedor** se inicia y está en funcionamiento (iniciado a partir de una **imagen de contenedor**), puede crear o cambiar archivos, variables de entorno, etc. Esos cambios existirán solo en ese contenedor, pero no persistirán en la imagen de contenedor subyacente (no se guardarán en disco).
+
+Una imagen de contenedor es comparable al archivo de **programa** y sus contenidos, por ejemplo, `python` y algún archivo `main.py`.
+
+Y el **contenedor** en sí (en contraste con la **imagen de contenedor**) es la instance real en ejecución de la imagen, comparable a un **proceso**. De hecho, un contenedor solo se está ejecutando cuando tiene un **proceso en ejecución** (y normalmente es solo un proceso). El contenedor se detiene cuando no hay un proceso en ejecución en él.
+
+## Imágenes de Contenedor
+
+Docker ha sido una de las herramientas principales para crear y gestionar **imágenes de contenedor** y **contenedores**.
+
+Y hay un <a href="https://hub.docker.com/" class="external-link" target="_blank">Docker Hub</a> público con **imágenes de contenedores oficiales** pre-hechas para muchas herramientas, entornos, bases de datos y aplicaciones.
+
+Por ejemplo, hay una <a href="https://hub.docker.com/_/python" class="external-link" target="_blank">Imagen de Python</a> oficial.
+
+Y hay muchas otras imágenes para diferentes cosas como bases de datos, por ejemplo para:
+
+* <a href="https://hub.docker.com/_/postgres" class="external-link" target="_blank">PostgreSQL</a>
+* <a href="https://hub.docker.com/_/mysql" class="external-link" target="_blank">MySQL</a>
+* <a href="https://hub.docker.com/_/mongo" class="external-link" target="_blank">MongoDB</a>
+* <a href="https://hub.docker.com/_/redis" class="external-link" target="_blank">Redis</a>, etc.
+
+Usando una imagen de contenedor pre-hecha es muy fácil **combinar** y utilizar diferentes herramientas. Por ejemplo, para probar una nueva base de datos. En la mayoría de los casos, puedes usar las **imágenes oficiales**, y simplemente configurarlas con variables de entorno.
+
+De esta manera, en muchos casos puedes aprender sobre contenedores y Docker y reutilizar ese conocimiento con muchas herramientas y componentes diferentes.
+
+Así, ejecutarías **múltiples contenedores** con diferentes cosas, como una base de datos, una aplicación de Python, un servidor web con una aplicación frontend en React, y conectarlos entre sí a través de su red interna.
+
+Todos los sistemas de gestión de contenedores (como Docker o Kubernetes) tienen estas características de redes integradas en ellos.
+
+## Contenedores y Procesos
+
+Una **imagen de contenedor** normalmente incluye en sus metadatos el programa o comando por defecto que debería ser ejecutado cuando el **contenedor** se inicie y los parámetros que deben pasar a ese programa. Muy similar a lo que sería si estuviera en la línea de comandos.
+
+Cuando un **contenedor** se inicia, ejecutará ese comando/programa (aunque puedes sobrescribirlo y hacer que ejecute un comando/programa diferente).
+
+Un contenedor está en ejecución mientras el **proceso principal** (comando o programa) esté en ejecución.
+
+Un contenedor normalmente tiene un **proceso único**, pero también es posible iniciar subprocesos desde el proceso principal, y de esa manera tendrás **múltiples procesos** en el mismo contenedor.
+
+Pero no es posible tener un contenedor en ejecución sin **al menos un proceso en ejecución**. Si el proceso principal se detiene, el contenedor se detiene.
+
+## Construir una Imagen de Docker para FastAPI
+
+¡Bien, construyamos algo ahora! 🚀
+
+Te mostraré cómo construir una **imagen de Docker** para FastAPI **desde cero**, basada en la imagen **oficial de Python**.
+
+Esto es lo que querrías hacer en **la mayoría de los casos**, por ejemplo:
+
+* Usando **Kubernetes** o herramientas similares
+* Al ejecutar en un **Raspberry Pi**
+* Usando un servicio en la nube que ejecutaría una imagen de contenedor por ti, etc.
+
+### Requisitos del Paquete
+
+Normalmente tendrías los **requisitos del paquete** para tu aplicación en algún archivo.
+
+Dependería principalmente de la herramienta que uses para **instalar** esos requisitos.
+
+La forma más común de hacerlo es tener un archivo `requirements.txt` con los nombres de los paquetes y sus versiones, uno por línea.
+
+Por supuesto, usarías las mismas ideas que leíste en [Acerca de las versiones de FastAPI](versions.md){.internal-link target=_blank} para establecer los rangos de versiones.
+
+Por ejemplo, tu `requirements.txt` podría verse así:
+
+```
+fastapi[standard]>=0.113.0,<0.114.0
+pydantic>=2.7.0,<3.0.0
+```
+
+Y normalmente instalarías esas dependencias de los paquetes con `pip`, por ejemplo:
+
+<div class="termy">
+
+```console
+$ pip install -r requirements.txt
+---> 100%
+Successfully installed fastapi pydantic
+```
+
+</div>
+
+/// info | Información
+
+Existen otros formatos y herramientas para definir e instalar dependencias de paquetes.
+
+///
+
+### Crear el Código de **FastAPI**
+
+* Crea un directorio `app` y entra en él.
+* Crea un archivo vacío `__init__.py`.
+* Crea un archivo `main.py` con:
+
+```Python
+from typing import Union
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+    return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: Union[str, None] = None):
+    return {"item_id": item_id, "q": q}
+```
+
+### Dockerfile
+
+Ahora, en el mismo directorio del proyecto, crea un archivo `Dockerfile` con:
+
+```{ .dockerfile .annotate }
+# (1)!
+FROM python:3.9
+
+# (2)!
+WORKDIR /code
+
+# (3)!
+COPY ./requirements.txt /code/requirements.txt
+
+# (4)!
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+# (5)!
+COPY ./app /code/app
+
+# (6)!
+CMD ["fastapi", "run", "app/main.py", "--port", "80"]
+```
+
+1. Comenzar desde la imagen base oficial de Python.
+
+2. Establecer el directorio de trabajo actual a `/code`.
+
+    Aquí es donde pondremos el archivo `requirements.txt` y el directorio `app`.
+
+3. Copiar el archivo con los requisitos al directorio `/code`.
+
+    Copiar **solo** el archivo con los requisitos primero, no el resto del código.
+
+    Como este archivo **no cambia a menudo**, Docker lo detectará y usará la **caché** para este paso, habilitando la caché para el siguiente paso también.
+
+4. Instalar las dependencias de los paquetes en el archivo de requisitos.
+
+    La opción `--no-cache-dir` le dice a `pip` que no guarde los paquetes descargados localmente, ya que eso solo sería si `pip` fuese a ejecutarse de nuevo para instalar los mismos paquetes, pero ese no es el caso al trabajar con contenedores.
+
+    /// note | Nota
+
+    El `--no-cache-dir` está relacionado solo con `pip`, no tiene nada que ver con Docker o contenedores.
+
+    ///
+
+    La opción `--upgrade` le dice a `pip` que actualice los paquetes si ya están instalados.
+
+    Debido a que el paso anterior de copiar el archivo podría ser detectado por la **caché de Docker**, este paso también **usará la caché de Docker** cuando esté disponible.
+
+    Usar la caché en este paso te **ahorrará** mucho **tiempo** al construir la imagen una y otra vez durante el desarrollo, en lugar de **descargar e instalar** todas las dependencias **cada vez**.
+
+5. Copiar el directorio `./app` dentro del directorio `/code`.
+
+    Como esto contiene todo el código, que es lo que **cambia con más frecuencia**, la **caché de Docker** no se utilizará para este u otros **pasos siguientes** fácilmente.
+
+    Así que es importante poner esto **cerca del final** del `Dockerfile`, para optimizar los tiempos de construcción de la imagen del contenedor.
+
+6. Establecer el **comando** para usar `fastapi run`, que utiliza Uvicorn debajo.
+
+    `CMD` toma una lista de cadenas, cada una de estas cadenas es lo que escribirías en la línea de comandos separado por espacios.
+
+    Este comando se ejecutará desde el **directorio de trabajo actual**, el mismo directorio `/code` que estableciste antes con `WORKDIR /code`.
+
+/// tip | Consejo
+
+Revisa qué hace cada línea haciendo clic en cada número en la burbuja del código. 👆
+
+///
+
+/// warning | Advertencia
+
+Asegúrate de **siempre** usar la **forma exec** de la instrucción `CMD`, como se explica a continuación.
+
+///
+
+#### Usar `CMD` - Forma Exec
+
+La instrucción Docker <a href="https://docs.docker.com/reference/dockerfile/#cmd" class="external-link" target="_blank">`CMD`</a> se puede escribir usando dos formas:
+
+✅ **Forma Exec**:
+
+```Dockerfile
+# ✅ Haz esto
+CMD ["fastapi", "run", "app/main.py", "--port", "80"]
+```
+
+⛔️ **Forma Shell**:
+
+```Dockerfile
+# ⛔️ No hagas esto
+CMD fastapi run app/main.py --port 80
+```
+
+Asegúrate de siempre usar la **forma exec** para garantizar que FastAPI pueda cerrarse de manera adecuada y que [los eventos de lifespan](../advanced/events.md){.internal-link target=_blank} sean disparados.
+
+Puedes leer más sobre esto en las <a href="https://docs.docker.com/reference/dockerfile/#shell-and-exec-form" class="external-link" target="_blank">documentación de Docker para formas de shell y exec</a>.
+
+Esto puede ser bastante notorio al usar `docker compose`. Consulta esta sección de preguntas frecuentes de Docker Compose para más detalles técnicos: <a href="https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop" class="external-link" target="_blank">¿Por qué mis servicios tardan 10 segundos en recrearse o detenerse?</a>.
+
+#### Estructura de Directorios
+
+Ahora deberías tener una estructura de directorios como:
+
+```
+.
+├── app
+│   ├── __init__.py
+│   └── main.py
+├── Dockerfile
+└── requirements.txt
+```
+
+#### Detrás de un Proxy de Terminación TLS
+
+Si estás ejecutando tu contenedor detrás de un Proxy de Terminación TLS (load balancer) como Nginx o Traefik, añade la opción `--proxy-headers`, esto le dirá a Uvicorn (a través de la CLI de FastAPI) que confíe en los headers enviados por ese proxy indicando que la aplicación se está ejecutando detrás de HTTPS, etc.
+
+```Dockerfile
+CMD ["fastapi", "run", "app/main.py", "--proxy-headers", "--port", "80"]
+```
+
+#### Cache de Docker
+
+Hay un truco importante en este `Dockerfile`, primero copiamos **el archivo con las dependencias solo**, no el resto del código. Déjame decirte por qué es así.
+
+```Dockerfile
+COPY ./requirements.txt /code/requirements.txt
+```
+
+Docker y otras herramientas **construyen** estas imágenes de contenedor **incrementalmente**, añadiendo **una capa sobre la otra**, empezando desde la parte superior del `Dockerfile` y añadiendo cualquier archivo creado por cada una de las instrucciones del `Dockerfile`.
+
+Docker y herramientas similares también usan una **caché interna** al construir la imagen, si un archivo no ha cambiado desde la última vez que se construyó la imagen del contenedor, entonces reutilizará la misma capa creada la última vez, en lugar de copiar el archivo de nuevo y crear una nueva capa desde cero.
+
+Solo evitar copiar archivos no mejora necesariamente las cosas mucho, pero porque se usó la caché para ese paso, puede **usar la caché para el siguiente paso**. Por ejemplo, podría usar la caché para la instrucción que instala las dependencias con:
+
+```Dockerfile
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+```
+
+El archivo con los requisitos de los paquetes **no cambiará con frecuencia**. Así que, al copiar solo ese archivo, Docker podrá **usar la caché** para ese paso.
+
+Y luego, Docker podrá **usar la caché para el siguiente paso** que descarga e instala esas dependencias. Y aquí es donde **ahorramos mucho tiempo**. ✨ ...y evitamos el aburrimiento de esperar. 😪😆
+
+Descargar e instalar las dependencias de los paquetes **podría llevar minutos**, pero usando la **caché** tomaría **segundos** como máximo.
+
+Y como estarías construyendo la imagen del contenedor una y otra vez durante el desarrollo para comprobar que los cambios en tu código funcionan, hay una gran cantidad de tiempo acumulado que te ahorrarías.
+
+Luego, cerca del final del `Dockerfile`, copiamos todo el código. Como esto es lo que **cambia con más frecuencia**, lo ponemos cerca del final, porque casi siempre, cualquier cosa después de este paso no podrá usar la caché.
+
+```Dockerfile
+COPY ./app /code/app
+```
+
+### Construir la Imagen de Docker
+
+Ahora que todos los archivos están en su lugar, vamos a construir la imagen del contenedor.
+
+* Ve al directorio del proyecto (donde está tu `Dockerfile`, conteniendo tu directorio `app`).
+* Construye tu imagen de FastAPI:
+
+<div class="termy">
+
+```console
+$ docker build -t myimage .
+
+---> 100%
+```
+
+</div>
+
+/// tip | Consejo
+
+Fíjate en el `.` al final, es equivalente a `./`, le indica a Docker el directorio a usar para construir la imagen del contenedor.
+
+En este caso, es el mismo directorio actual (`.`).
+
+///
+
+### Iniciar el Contenedor Docker
+
+* Ejecuta un contenedor basado en tu imagen:
+
+<div class="termy">
+
+```console
+$ docker run -d --name mycontainer -p 80:80 myimage
+```
+
+</div>
+
+## Revísalo
+
+Deberías poder revisarlo en la URL de tu contenedor de Docker, por ejemplo: <a href="http://192.168.99.100/items/5?q=somequery" class="external-link" target="_blank">http://192.168.99.100/items/5?q=somequery</a> o <a href="http://127.0.0.1/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1/items/5?q=somequery</a> (o equivalente, usando tu host de Docker).
+
+Verás algo como:
+
+```JSON
+{"item_id": 5, "q": "somequery"}
+```
+
+## Documentación Interactiva de la API
+
+Ahora puedes ir a <a href="http://192.168.99.100/docs" class="external-link" target="_blank">http://192.168.99.100/docs</a> o <a href="http://127.0.0.1/docs" class="external-link" target="_blank">http://127.0.0.1/docs</a> (o equivalente, usando tu host de Docker).
+
+Verás la documentación interactiva automática de la API (proporcionada por <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>):
+
+![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png)
+
+## Documentación Alternativa de la API
+
+Y también puedes ir a <a href="http://192.168.99.100/redoc" class="external-link" target="_blank">http://192.168.99.100/redoc</a> o <a href="http://127.0.0.1/redoc" class="external-link" target="_blank">http://127.0.0.1/redoc</a> (o equivalente, usando tu host de Docker).
+
+Verás la documentación alternativa automática (proporcionada por <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>):
+
+![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
+
+## Construir una Imagen de Docker con un FastAPI de Un Solo Archivo
+
+Si tu FastAPI es un solo archivo, por ejemplo, `main.py` sin un directorio `./app`, tu estructura de archivos podría verse así:
+
+```
+.
+├── Dockerfile
+├── main.py
+└── requirements.txt
+```
+
+Entonces solo tendrías que cambiar las rutas correspondientes para copiar el archivo dentro del `Dockerfile`:
+
+```{ .dockerfile .annotate hl_lines="10  13" }
+FROM python:3.9
+
+WORKDIR /code
+
+COPY ./requirements.txt /code/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+# (1)!
+COPY ./main.py /code/
+
+# (2)!
+CMD ["fastapi", "run", "main.py", "--port", "80"]
+```
+
+1. Copia el archivo `main.py` directamente al directorio `/code` (sin ningún directorio `./app`).
+
+2. Usa `fastapi run` para servir tu aplicación en el archivo único `main.py`.
+
+Cuando pasas el archivo a `fastapi run`, detectará automáticamente que es un archivo único y no parte de un paquete y sabrá cómo importarlo y servir tu aplicación FastAPI. 😎
+
+## Conceptos de Despliegue
+
+Hablemos nuevamente de algunos de los mismos [Conceptos de Despliegue](concepts.md){.internal-link target=_blank} en términos de contenedores.
+
+Los contenedores son principalmente una herramienta para simplificar el proceso de **construcción y despliegue** de una aplicación, pero no imponen un enfoque particular para manejar estos **conceptos de despliegue**, y hay varias estrategias posibles.
+
+La **buena noticia** es que con cada estrategia diferente hay una forma de cubrir todos los conceptos de despliegue. 🎉
+
+Revisemos estos **conceptos de despliegue** en términos de contenedores:
+
+* HTTPS
+* Ejecutar en el inicio
+* Reinicios
+* Replicación (el número de procesos en ejecución)
+* Memoria
+* Pasos previos antes de comenzar
+
+## HTTPS
+
+Si nos enfocamos solo en la **imagen de contenedor** para una aplicación FastAPI (y luego el **contenedor** en ejecución), HTTPS normalmente sería manejado **externamente** por otra herramienta.
+
+Podría ser otro contenedor, por ejemplo, con <a href="https://traefik.io/" class="external-link" target="_blank">Traefik</a>, manejando **HTTPS** y la adquisición **automática** de **certificados**.
+
+/// tip | Consejo
+
+Traefik tiene integraciones con Docker, Kubernetes, y otros, por lo que es muy fácil configurar y configurar HTTPS para tus contenedores con él.
+
+///
+
+Alternativamente, HTTPS podría ser manejado por un proveedor de la nube como uno de sus servicios (mientras que la aplicación aún se ejecuta en un contenedor).
+
+## Ejecutar en el Inicio y Reinicios
+
+Normalmente hay otra herramienta encargada de **iniciar y ejecutar** tu contenedor.
+
+Podría ser **Docker** directamente, **Docker Compose**, **Kubernetes**, un **servicio en la nube**, etc.
+
+En la mayoría (o todas) de las casos, hay una opción sencilla para habilitar la ejecución del contenedor al inicio y habilitar los reinicios en caso de fallos. Por ejemplo, en Docker, es la opción de línea de comandos `--restart`.
+
+Sin usar contenedores, hacer que las aplicaciones se ejecuten al inicio y con reinicios puede ser engorroso y difícil. Pero al **trabajar con contenedores** en la mayoría de los casos, esa funcionalidad se incluye por defecto. ✨
+
+## Replicación - Número de Procesos
+
+Si tienes un <abbr title="Un grupo de máquinas que están configuradas para estar conectadas y trabajar juntas de alguna manera.">cluster</abbr> de máquinas con **Kubernetes**, Docker Swarm Mode, Nomad, u otro sistema complejo similar para gestionar contenedores distribuidos en varias máquinas, entonces probablemente querrás manejar la **replicación** a nivel de **cluster** en lugar de usar un **gestor de procesos** (como Uvicorn con workers) en cada contenedor.
+
+Uno de esos sistemas de gestión de contenedores distribuidos como Kubernetes normalmente tiene alguna forma integrada de manejar la **replicación de contenedores** mientras aún soporta el **load balancing** para las requests entrantes. Todo a nivel de **cluster**.
+
+En esos casos, probablemente desearías construir una **imagen de Docker desde cero** como se [explica arriba](#dockerfile), instalando tus dependencias, y ejecutando **un solo proceso de Uvicorn** en lugar de usar múltiples workers de Uvicorn.
+
+### Load Balancer
+
+Al usar contenedores, normalmente tendrías algún componente **escuchando en el puerto principal**. Podría posiblemente ser otro contenedor que es también un **Proxy de Terminación TLS** para manejar **HTTPS** o alguna herramienta similar.
+
+Como este componente tomaría la **carga** de las requests y las distribuiría entre los workers de una manera (esperablemente) **balanceada**, también se le llama comúnmente **Load Balancer**.
+
+/// tip | Consejo
+
+El mismo componente **Proxy de Terminación TLS** usado para HTTPS probablemente también sería un **Load Balancer**.
+
+///
+
+Y al trabajar con contenedores, el mismo sistema que usas para iniciarlos y gestionarlos ya tendría herramientas internas para transmitir la **comunicación en red** (e.g., requests HTTP) desde ese **load balancer** (que también podría ser un **Proxy de Terminación TLS**) a los contenedores con tu aplicación.
+
+### Un Load Balancer - Múltiples Contenedores Worker
+
+Al trabajar con **Kubernetes** u otros sistemas de gestión de contenedores distribuidos similares, usar sus mecanismos de red internos permitiría que el único **load balancer** que está escuchando en el **puerto** principal transmita la comunicación (requests) a posiblemente **múltiples contenedores** ejecutando tu aplicación.
+
+Cada uno de estos contenedores ejecutando tu aplicación normalmente tendría **solo un proceso** (e.g., un proceso Uvicorn ejecutando tu aplicación FastAPI). Todos serían **contenedores idénticos**, ejecutando lo mismo, pero cada uno con su propio proceso, memoria, etc. De esa forma, aprovecharías la **paralelización** en **diferentes núcleos** de la CPU, o incluso en **diferentes máquinas**.
+
+Y el sistema de contenedores distribuido con el **load balancer** **distribuiría las requests** a cada uno de los contenedores **replicados** que ejecutan tu aplicación **en turnos**. Así, cada request podría ser manejado por uno de los múltiples **contenedores replicados** ejecutando tu aplicación.
+
+Y normalmente este **load balancer** podría manejar requests que vayan a *otras* aplicaciones en tu cluster (p. ej., a un dominio diferente, o bajo un prefijo de ruta de URL diferente), y transmitiría esa comunicación a los contenedores correctos para *esa otra* aplicación ejecutándose en tu cluster.
+
+### Un Proceso por Contenedor
+
+En este tipo de escenario, probablemente querrías tener **un solo proceso (Uvicorn) por contenedor**, ya que ya estarías manejando la replicación a nivel de cluster.
+
+Así que, en este caso, **no** querrías tener múltiples workers en el contenedor, por ejemplo, con la opción de línea de comandos `--workers`. Querrías tener solo un **proceso Uvicorn por contenedor** (pero probablemente múltiples contenedores).
+
+Tener otro gestor de procesos dentro del contenedor (como sería con múltiples workers) solo añadiría **complejidad innecesaria** que probablemente ya estés manejando con tu sistema de cluster.
+
+### Contenedores con Múltiples Procesos y Casos Especiales
+
+Por supuesto, hay **casos especiales** donde podrías querer tener **un contenedor** con varios **worker processes de Uvicorn** dentro.
+
+En esos casos, puedes usar la opción de línea de comandos `--workers` para establecer el número de workers que deseas ejecutar:
+
+```{ .dockerfile .annotate }
+FROM python:3.9
+
+WORKDIR /code
+
+COPY ./requirements.txt /code/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+COPY ./app /code/app
+
+# (1)!
+CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"]
+```
+
+1. Aquí usamos la opción de línea de comandos `--workers` para establecer el número de workers a 4.
+
+Aquí hay algunos ejemplos de cuándo eso podría tener sentido:
+
+#### Una Aplicación Simple
+
+Podrías querer un gestor de procesos en el contenedor si tu aplicación es **lo suficientemente simple** que pueda ejecutarse en un **servidor único**, no un cluster.
+
+#### Docker Compose
+
+Podrías estar desplegando en un **servidor único** (no un cluster) con **Docker Compose**, por lo que no tendrías una forma fácil de gestionar la replicación de contenedores (con Docker Compose) mientras se preserva la red compartida y el **load balancing**.
+
+Entonces podrías querer tener **un solo contenedor** con un **gestor de procesos** iniciando **varios worker processes** dentro.
+
+---
+
+El punto principal es que, **ninguna** de estas son **reglas escritas en piedra** que debas seguir a ciegas. Puedes usar estas ideas para **evaluar tu propio caso de uso** y decidir cuál es el mejor enfoque para tu sistema, verificando cómo gestionar los conceptos de:
+
+* Seguridad - HTTPS
+* Ejecutar en el inicio
+* Reinicios
+* Replicación (el número de procesos en ejecución)
+* Memoria
+* Pasos previos antes de comenzar
+
+## Memoria
+
+Si ejecutas **un solo proceso por contenedor**, tendrás una cantidad de memoria más o menos bien definida, estable y limitada consumida por cada uno de esos contenedores (más de uno si están replicados).
+
+Y luego puedes establecer esos mismos límites de memoria y requisitos en tus configuraciones para tu sistema de gestión de contenedores (por ejemplo, en **Kubernetes**). De esa manera, podrá **replicar los contenedores** en las **máquinas disponibles** teniendo en cuenta la cantidad de memoria necesaria por ellos, y la cantidad disponible en las máquinas en el cluster.
+
+Si tu aplicación es **simple**, probablemente esto **no será un problema**, y puede que no necesites especificar límites de memoria estrictos. Pero si estás **usando mucha memoria** (por ejemplo, con modelos de **Machine Learning**), deberías verificar cuánta memoria estás consumiendo y ajustar el **número de contenedores** que se ejecutan en **cada máquina** (y tal vez agregar más máquinas a tu cluster).
+
+Si ejecutas **múltiples procesos por contenedor**, tendrás que asegurarte de que el número de procesos iniciados no **consuma más memoria** de la que está disponible.
+
+## Pasos Previos Antes de Comenzar y Contenedores
+
+Si estás usando contenedores (por ejemplo, Docker, Kubernetes), entonces hay dos enfoques principales que puedes usar.
+
+### Múltiples Contenedores
+
+Si tienes **múltiples contenedores**, probablemente cada uno ejecutando un **proceso único** (por ejemplo, en un cluster de **Kubernetes**), entonces probablemente querrías tener un **contenedor separado** realizando el trabajo de los **pasos previos** en un solo contenedor, ejecutando un solo proceso, **antes** de ejecutar los contenedores worker replicados.
+
+/// info | Información
+
+Si estás usando Kubernetes, probablemente sería un <a href="https://kubernetes.io/docs/concepts/workloads/pods/init-containers/" class="external-link" target="_blank">Contenedor de Inicialización</a>.
+
+///
+
+Si en tu caso de uso no hay problema en ejecutar esos pasos previos **múltiples veces en paralelo** (por ejemplo, si no estás ejecutando migraciones de base de datos, sino simplemente verificando si la base de datos está lista), entonces también podrías simplemente ponerlos en cada contenedor justo antes de iniciar el proceso principal.
+
+### Un Contenedor Único
+
+Si tienes una configuración simple, con un **contenedor único** que luego inicia múltiples **worker processes** (o también solo un proceso), entonces podrías ejecutar esos pasos previos en el mismo contenedor, justo antes de iniciar el proceso con la aplicación.
+
+### Imagen Base de Docker
+
+Solía haber una imagen official de Docker de FastAPI: <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>. Pero ahora está obsoleta. ⛔️
+
+Probablemente **no** deberías usar esta imagen base de Docker (o cualquier otra similar).
+
+Si estás usando **Kubernetes** (u otros) y ya estás configurando la **replicación** a nivel de cluster, con múltiples **contenedores**. En esos casos, es mejor que **construyas una imagen desde cero** como se describe arriba: [Construir una Imagen de Docker para FastAPI](#build-a-docker-image-for-fastapi).
+
+Y si necesitas tener múltiples workers, puedes simplemente utilizar la opción de línea de comandos `--workers`.
+
+/// note | Detalles Técnicos
+
+La imagen de Docker se creó cuando Uvicorn no soportaba gestionar y reiniciar workers muertos, por lo que era necesario usar Gunicorn con Uvicorn, lo que añadía bastante complejidad, solo para que Gunicorn gestionara y reiniciara los worker processes de Uvicorn.
+
+Pero ahora que Uvicorn (y el comando `fastapi`) soportan el uso de `--workers`, no hay razón para utilizar una imagen base de Docker en lugar de construir la tuya propia (es prácticamente la misma cantidad de código 😅).
+
+///
+
+## Desplegar la Imagen del Contenedor
+
+Después de tener una Imagen de Contenedor (Docker) hay varias maneras de desplegarla.
+
+Por ejemplo:
+
+* Con **Docker Compose** en un servidor único
+* Con un cluster de **Kubernetes**
+* Con un cluster de Docker Swarm Mode
+* Con otra herramienta como Nomad
+* Con un servicio en la nube que tome tu imagen de contenedor y la despliegue
+
+## Imagen de Docker con `uv`
+
+Si estás usando <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">uv</a> para instalar y gestionar tu proyecto, puedes seguir su <a href="https://docs.astral.sh/uv/guides/integration/docker/" class="external-link" target="_blank">guía de Docker de uv</a>.
+
+## Resumen
+
+Usando sistemas de contenedores (por ejemplo, con **Docker** y **Kubernetes**) se vuelve bastante sencillo manejar todos los **conceptos de despliegue**:
+
+* HTTPS
+* Ejecutar en el inicio
+* Reinicios
+* Replicación (el número de procesos en ejecución)
+* Memoria
+* Pasos previos antes de comenzar
+
+En la mayoría de los casos, probablemente no querrás usar ninguna imagen base, y en su lugar **construir una imagen de contenedor desde cero** basada en la imagen oficial de Docker de Python.
+
+Teniendo en cuenta el **orden** de las instrucciones en el `Dockerfile` y la **caché de Docker** puedes **minimizar los tiempos de construcción**, para maximizar tu productividad (y evitar el aburrimiento). 😎

docs/es/docs/deployment/https.md

@@ -0,0 +1,199 @@
+# Sobre HTTPS
+
+Es fácil asumir que HTTPS es algo que simplemente está "activado" o no.
+
+Pero es mucho más complejo que eso.
+
+/// tip | Consejo
+
+Si tienes prisa o no te importa, continúa con las siguientes secciones para ver instrucciones paso a paso para configurar todo con diferentes técnicas.
+
+///
+
+Para **aprender los conceptos básicos de HTTPS**, desde una perspectiva de consumidor, revisa <a href="https://howhttps.works/" class="external-link" target="_blank">https://howhttps.works/</a>.
+
+Ahora, desde una **perspectiva de desarrollador**, aquí hay varias cosas a tener en cuenta al pensar en HTTPS:
+
+* Para HTTPS, **el servidor** necesita **tener "certificados"** generados por un **tercero**.
+    * Esos certificados en realidad son **adquiridos** del tercero, no "generados".
+* Los certificados tienen una **vida útil**.
+    * Ellos **expiran**.
+    * Y luego necesitan ser **renovados**, **adquiridos nuevamente** del tercero.
+* La encriptación de la conexión ocurre a nivel de **TCP**.
+    * Esa es una capa **debajo de HTTP**.
+    * Por lo tanto, el manejo de **certificados y encriptación** se realiza **antes de HTTP**.
+* **TCP no sabe acerca de "dominios"**. Solo sobre direcciones IP.
+    * La información sobre el **dominio específico** solicitado va en los **datos HTTP**.
+* Los **certificados HTTPS** "certifican" un **cierto dominio**, pero el protocolo y la encriptación ocurren a nivel de TCP, **antes de saber** con cuál dominio se está tratando.
+* **Por defecto**, eso significaría que solo puedes tener **un certificado HTTPS por dirección IP**.
+    * No importa cuán grande sea tu servidor o qué tan pequeña pueda ser cada aplicación que tengas en él.
+    * Sin embargo, hay una **solución** para esto.
+* Hay una **extensión** para el protocolo **TLS** (el que maneja la encriptación a nivel de TCP, antes de HTTP) llamada **<a href="https://en.wikipedia.org/wiki/Server_Name_Indication" class="external-link" target="_blank"><abbr title="Server Name Indication">SNI</abbr></a>**.
+    * Esta extensión SNI permite que un solo servidor (con una **sola dirección IP**) tenga **varios certificados HTTPS** y sirva **múltiples dominios/aplicaciones HTTPS**.
+    * Para que esto funcione, un componente (programa) **único** que se ejecute en el servidor, escuchando en la **dirección IP pública**, debe tener **todos los certificados HTTPS** en el servidor.
+* **Después** de obtener una conexión segura, el protocolo de comunicación sigue siendo **HTTP**.
+    * Los contenidos están **encriptados**, aunque se envién con el **protocolo HTTP**.
+
+Es una práctica común tener **un programa/servidor HTTP** ejecutándose en el servidor (la máquina, host, etc.) y **gestionando todas las partes de HTTPS**: recibiendo los **requests HTTPS encriptados**, enviando los **requests HTTP desencriptados** a la aplicación HTTP real que se ejecuta en el mismo servidor (la aplicación **FastAPI**, en este caso), tomando el **response HTTP** de la aplicación, **encriptándolo** usando el **certificado HTTPS** adecuado y enviándolo de vuelta al cliente usando **HTTPS**. Este servidor a menudo se llama un **<a href="https://en.wikipedia.org/wiki/TLS_termination_proxy" class="external-link" target="_blank">TLS Termination Proxy</a>**.
+
+Algunas de las opciones que podrías usar como un TLS Termination Proxy son:
+
+* Traefik (que también puede manejar la renovación de certificados)
+* Caddy (que también puede manejar la renovación de certificados)
+* Nginx
+* HAProxy
+
+## Let's Encrypt
+
+Antes de Let's Encrypt, estos **certificados HTTPS** eran vendidos por terceros.
+
+El proceso para adquirir uno de estos certificados solía ser complicado, requerir bastante papeleo y los certificados eran bastante costosos.
+
+Pero luego se creó **<a href="https://letsencrypt.org/" class="external-link" target="_blank">Let's Encrypt</a>**.
+
+Es un proyecto de la Linux Foundation. Proporciona **certificados HTTPS de forma gratuita**, de manera automatizada. Estos certificados usan toda la seguridad criptográfica estándar, y tienen una corta duración (aproximadamente 3 meses), por lo que la **seguridad es en realidad mejor** debido a su corta vida útil.
+
+Los dominios son verificados de manera segura y los certificados se generan automáticamente. Esto también permite automatizar la renovación de estos certificados.
+
+La idea es automatizar la adquisición y renovación de estos certificados para que puedas tener **HTTPS seguro, gratuito, para siempre**.
+
+## HTTPS para Desarrolladores
+
+Aquí tienes un ejemplo de cómo podría ser una API HTTPS, paso a paso, prestando atención principalmente a las ideas importantes para los desarrolladores.
+
+### Nombre de Dominio
+
+Probablemente todo comenzaría adquiriendo un **nombre de dominio**. Luego, lo configurarías en un servidor DNS (posiblemente tu mismo proveedor de la nube).
+
+Probablemente conseguirías un servidor en la nube (una máquina virtual) o algo similar, y tendría una **dirección IP pública** <abbr title="Que no cambia">fija</abbr>.
+
+En el/los servidor(es) DNS configurarías un registro (un "`A record`") para apuntar **tu dominio** a la **dirección IP pública de tu servidor**.
+
+Probablemente harías esto solo una vez, la primera vez, al configurar todo.
+
+/// tip | Consejo
+
+Esta parte del Nombre de Dominio es mucho antes de HTTPS, pero como todo depende del dominio y la dirección IP, vale la pena mencionarlo aquí.
+
+///
+
+### DNS
+
+Ahora centrémonos en todas las partes realmente de HTTPS.
+
+Primero, el navegador consultaría con los **servidores DNS** cuál es la **IP del dominio**, en este caso, `someapp.example.com`.
+
+Los servidores DNS le dirían al navegador que use una **dirección IP** específica. Esa sería la dirección IP pública utilizada por tu servidor, que configuraste en los servidores DNS.
+
+<img src="/img/deployment/https/https01.drawio.svg">
+
+### Inicio del Handshake TLS
+
+El navegador luego se comunicaría con esa dirección IP en el **puerto 443** (el puerto HTTPS).
+
+La primera parte de la comunicación es solo para establecer la conexión entre el cliente y el servidor y decidir las claves criptográficas que usarán, etc.
+
+<img src="/img/deployment/https/https02.drawio.svg">
+
+Esta interacción entre el cliente y el servidor para establecer la conexión TLS se llama **handshake TLS**.
+
+### TLS con Extensión SNI
+
+**Solo un proceso** en el servidor puede estar escuchando en un **puerto** específico en una **dirección IP** específica. Podría haber otros procesos escuchando en otros puertos en la misma dirección IP, pero solo uno para cada combinación de dirección IP y puerto.
+
+TLS (HTTPS) utiliza el puerto específico `443` por defecto. Así que ese es el puerto que necesitaríamos.
+
+Como solo un proceso puede estar escuchando en este puerto, el proceso que lo haría sería el **TLS Termination Proxy**.
+
+El TLS Termination Proxy tendría acceso a uno o más **certificados TLS** (certificados HTTPS).
+
+Usando la **extensión SNI** discutida anteriormente, el TLS Termination Proxy verificaría cuál de los certificados TLS (HTTPS) disponibles debería usar para esta conexión, usando el que coincida con el dominio esperado por el cliente.
+
+En este caso, usaría el certificado para `someapp.example.com`.
+
+<img src="/img/deployment/https/https03.drawio.svg">
+
+El cliente ya **confía** en la entidad que generó ese certificado TLS (en este caso Let's Encrypt, pero lo veremos más adelante), por lo que puede **verificar** que el certificado sea válido.
+
+Luego, usando el certificado, el cliente y el TLS Termination Proxy **deciden cómo encriptar** el resto de la **comunicación TCP**. Esto completa la parte de **Handshake TLS**.
+
+Después de esto, el cliente y el servidor tienen una **conexión TCP encriptada**, esto es lo que proporciona TLS. Y luego pueden usar esa conexión para iniciar la comunicación **HTTP real**.
+
+Y eso es lo que es **HTTPS**, es simplemente HTTP simple **dentro de una conexión TLS segura** en lugar de una conexión TCP pura (sin encriptar).
+
+/// tip | Consejo
+
+Ten en cuenta que la encriptación de la comunicación ocurre a nivel de **TCP**, no a nivel de HTTP.
+
+///
+
+### Request HTTPS
+
+Ahora que el cliente y el servidor (específicamente el navegador y el TLS Termination Proxy) tienen una **conexión TCP encriptada**, pueden iniciar la **comunicación HTTP**.
+
+Así que, el cliente envía un **request HTTPS**. Esto es simplemente un request HTTP a través de una conexión TLS encriptada.
+
+<img src="/img/deployment/https/https04.drawio.svg">
+
+### Desencriptar el Request
+
+El TLS Termination Proxy usaría la encriptación acordada para **desencriptar el request**, y transmitiría el **request HTTP simple (desencriptado)** al proceso que ejecuta la aplicación (por ejemplo, un proceso con Uvicorn ejecutando la aplicación FastAPI).
+
+<img src="/img/deployment/https/https05.drawio.svg">
+
+### Response HTTP
+
+La aplicación procesaría el request y enviaría un **response HTTP simple (sin encriptar)** al TLS Termination Proxy.
+
+<img src="/img/deployment/https/https06.drawio.svg">
+
+### Response HTTPS
+
+El TLS Termination Proxy entonces **encriptaría el response** usando la criptografía acordada antes (que comenzó con el certificado para `someapp.example.com`), y lo enviaría de vuelta al navegador.
+
+Luego, el navegador verificaría que el response sea válido y encriptado con la clave criptográfica correcta, etc. Entonces **desencriptaría el response** y lo procesaría.
+
+<img src="/img/deployment/https/https07.drawio.svg">
+
+El cliente (navegador) sabrá que el response proviene del servidor correcto porque está utilizando la criptografía que acordaron usando el **certificado HTTPS** anteriormente.
+
+### Múltiples Aplicaciones
+
+En el mismo servidor (o servidores), podrían haber **múltiples aplicaciones**, por ejemplo, otros programas API o una base de datos.
+
+Solo un proceso puede estar gestionando la IP y puerto específica (el TLS Termination Proxy en nuestro ejemplo) pero las otras aplicaciones/procesos pueden estar ejecutándose en el/los servidor(es) también, siempre y cuando no intenten usar la misma **combinación de IP pública y puerto**.
+
+<img src="/img/deployment/https/https08.drawio.svg">
+
+De esa manera, el TLS Termination Proxy podría gestionar HTTPS y certificados para **múltiples dominios**, para múltiples aplicaciones, y luego transmitir los requests a la aplicación correcta en cada caso.
+
+### Renovación de Certificados
+
+En algún momento en el futuro, cada certificado **expiraría** (alrededor de 3 meses después de haberlo adquirido).
+
+Y entonces, habría otro programa (en algunos casos es otro programa, en algunos casos podría ser el mismo TLS Termination Proxy) que hablaría con Let's Encrypt y renovaría el/los certificado(s).
+
+<img src="/img/deployment/https/https.drawio.svg">
+
+Los **certificados TLS** están **asociados con un nombre de dominio**, no con una dirección IP.
+
+Entonces, para renovar los certificados, el programa de renovación necesita **probar** a la autoridad (Let's Encrypt) que de hecho **"posee" y controla ese dominio**.
+
+Para hacer eso, y para acomodar diferentes necesidades de aplicaciones, hay varias formas en que puede hacerlo. Algunas formas populares son:
+
+* **Modificar algunos registros DNS**.
+    * Para esto, el programa de renovación necesita soportar las API del proveedor de DNS, por lo que, dependiendo del proveedor de DNS que estés utilizando, esto podría o no ser una opción.
+* **Ejecutarse como un servidor** (al menos durante el proceso de adquisición del certificado) en la dirección IP pública asociada con el dominio.
+    * Como dijimos anteriormente, solo un proceso puede estar escuchando en una IP y puerto específicos.
+    * Esta es una de las razones por las que es muy útil cuando el mismo TLS Termination Proxy también se encarga del proceso de renovación del certificado.
+    * De lo contrario, podrías tener que detener momentáneamente el TLS Termination Proxy, iniciar el programa de renovación para adquirir los certificados, luego configurarlos con el TLS Termination Proxy, y luego reiniciar el TLS Termination Proxy. Esto no es ideal, ya que tus aplicaciones no estarán disponibles durante el tiempo que el TLS Termination Proxy esté apagado.
+
+Todo este proceso de renovación, mientras aún se sirve la aplicación, es una de las principales razones por las que querrías tener un **sistema separado para gestionar el HTTPS** con un TLS Termination Proxy en lugar de simplemente usar los certificados TLS con el servidor de aplicaciones directamente (por ejemplo, Uvicorn).
+
+## Resumen
+
+Tener **HTTPS** es muy importante y bastante **crítico** en la mayoría de los casos. La mayor parte del esfuerzo que como desarrollador tienes que poner en torno a HTTPS es solo sobre **entender estos conceptos** y cómo funcionan.
+
+Pero una vez que conoces la información básica de **HTTPS para desarrolladores** puedes combinar y configurar fácilmente diferentes herramientas para ayudarte a gestionar todo de una manera sencilla.
+
+En algunos de los siguientes capítulos, te mostraré varios ejemplos concretos de cómo configurar **HTTPS** para aplicaciones **FastAPI**. 🔒

docs/es/docs/deployment/index.md

@@ -0,0 +1,21 @@
+# Despliegue
+
+Desplegar una aplicación **FastAPI** es relativamente fácil.
+
+## Qué Significa Despliegue
+
+**Desplegar** una aplicación significa realizar los pasos necesarios para hacerla **disponible para los usuarios**.
+
+Para una **API web**, normalmente implica ponerla en una **máquina remota**, con un **programa de servidor** que proporcione buen rendimiento, estabilidad, etc., para que tus **usuarios** puedan **acceder** a la aplicación de manera eficiente y sin interrupciones o problemas.
+
+Esto contrasta con las etapas de **desarrollo**, donde estás constantemente cambiando el código, rompiéndolo y arreglándolo, deteniendo y reiniciando el servidor de desarrollo, etc.
+
+## Estrategias de Despliegue
+
+Hay varias maneras de hacerlo dependiendo de tu caso de uso específico y las herramientas que utilices.
+
+Podrías **desplegar un servidor** tú mismo utilizando una combinación de herramientas, podrías usar un **servicio en la nube** que hace parte del trabajo por ti, u otras opciones posibles.
+
+Te mostraré algunos de los conceptos principales que probablemente deberías tener en cuenta al desplegar una aplicación **FastAPI** (aunque la mayoría se aplica a cualquier otro tipo de aplicación web).
+
+Verás más detalles a tener en cuenta y algunas de las técnicas para hacerlo en las siguientes secciones. ✨

docs/es/docs/deployment/manually.md

@@ -0,0 +1,169 @@
+# Ejecutar un Servidor Manualmente
+
+## Usa el Comando `fastapi run`
+
+En resumen, usa `fastapi run` para servir tu aplicación FastAPI:
+
+<div class="termy">
+
+```console
+$ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:single">main.py</u>
+<font color="#3465A4">INFO    </font> Usando path <font color="#3465A4">main.py</font>
+<font color="#3465A4">INFO    </font> Path absoluto resuelto <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
+<font color="#3465A4">INFO    </font> Buscando una estructura de archivos de paquete desde directorios con archivos <font color="#3465A4">__init__.py</font>
+<font color="#3465A4">INFO    </font> Importando desde <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
+
+ ╭─ <font color="#8AE234"><b>Archivo de módulo de Python</b></font> ─╮
+ │                      │
+ │  🐍 main.py          │
+ │                      │
+ ╰──────────────────────╯
+
+<font color="#3465A4">INFO    </font> Importando módulo <font color="#4E9A06">main</font>
+<font color="#3465A4">INFO    </font> Encontrada aplicación FastAPI importable
+
+ ╭─ <font color="#8AE234"><b>Aplicación FastAPI importable</b></font> ─╮
+ │                          │
+ │  <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822">  </span>  │
+ │                          │
+ ╰──────────────────────────╯
+
+<font color="#3465A4">INFO    </font> Usando la cadena de import <font color="#8AE234"><b>main:app</b></font>
+
+ <font color="#4E9A06">╭─────────── CLI de FastAPI - Modo Producción ───────────╮</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">│  Sirviendo en: http://0.0.0.0:8000                    │</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">│  Docs de API: http://0.0.0.0:8000/docs               │</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">│  Corriendo en modo producción, para desarrollo usa:  │</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">│  </font><font color="#8AE234"><b>fastapi dev</b></font><font color="#4E9A06">                                        │</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">╰─────────────────────────────────────────────────────╯</font>
+
+<font color="#4E9A06">INFO</font>:     Iniciado el proceso del servidor [<font color="#06989A">2306215</font>]
+<font color="#4E9A06">INFO</font>:     Esperando el inicio de la aplicación.
+<font color="#4E9A06">INFO</font>:     Inicio de la aplicación completado.
+<font color="#4E9A06">INFO</font>:     Uvicorn corriendo en <b>http://0.0.0.0:8000</b> (Presiona CTRL+C para salir)
+```
+
+</div>
+
+Eso funcionaría para la mayoría de los casos. 😎
+
+Podrías usar ese comando, por ejemplo, para iniciar tu app **FastAPI** en un contenedor, en un servidor, etc.
+
+## Servidores ASGI
+
+Vamos a profundizar un poquito en los detalles.
+
+FastAPI usa un estándar para construir frameworks de web y servidores de Python llamado <abbr title="Asynchronous Server Gateway Interface">ASGI</abbr>. FastAPI es un framework web ASGI.
+
+Lo principal que necesitas para ejecutar una aplicación **FastAPI** (o cualquier otra aplicación ASGI) en una máquina de servidor remota es un programa de servidor ASGI como **Uvicorn**, que es el que viene por defecto en el comando `fastapi`.
+
+Hay varias alternativas, incluyendo:
+
+* <a href="https://www.uvicorn.dev/" class="external-link" target="_blank">Uvicorn</a>: un servidor ASGI de alto rendimiento.
+* <a href="https://hypercorn.readthedocs.io/" class="external-link" target="_blank">Hypercorn</a>: un servidor ASGI compatible con HTTP/2 y Trio entre otras funcionalidades.
+* <a href="https://github.com/django/daphne" class="external-link" target="_blank">Daphne</a>: el servidor ASGI construido para Django Channels.
+* <a href="https://github.com/emmett-framework/granian" class="external-link" target="_blank">Granian</a>: Un servidor HTTP Rust para aplicaciones en Python.
+* <a href="https://unit.nginx.org/howto/fastapi/" class="external-link" target="_blank">NGINX Unit</a>: NGINX Unit es un runtime para aplicaciones web ligero y versátil.
+
+## Máquina Servidor y Programa Servidor
+
+Hay un pequeño detalle sobre los nombres que hay que tener en cuenta. 💡
+
+La palabra "**servidor**" se utiliza comúnmente para referirse tanto al computador remoto/en la nube (la máquina física o virtual) como al programa que se está ejecutando en esa máquina (por ejemplo, Uvicorn).
+
+Solo ten en cuenta que cuando leas "servidor" en general, podría referirse a una de esas dos cosas.
+
+Al referirse a la máquina remota, es común llamarla **servidor**, pero también **máquina**, **VM** (máquina virtual), **nodo**. Todos esos se refieren a algún tipo de máquina remota, generalmente con Linux, donde ejecutas programas.
+
+## Instala el Programa del Servidor
+
+Cuando instalas FastAPI, viene con un servidor de producción, Uvicorn, y puedes iniciarlo con el comando `fastapi run`.
+
+Pero también puedes instalar un servidor ASGI manualmente.
+
+Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, actívalo, y luego puedes instalar la aplicación del servidor.
+
+Por ejemplo, para instalar Uvicorn:
+
+<div class="termy">
+
+```console
+$ pip install "uvicorn[standard]"
+
+---> 100%
+```
+
+</div>
+
+Un proceso similar se aplicaría a cualquier otro programa de servidor ASGI.
+
+/// tip | Consejo
+
+Al añadir `standard`, Uvicorn instalará y usará algunas dependencias adicionales recomendadas.
+
+Eso incluye `uvloop`, el reemplazo de alto rendimiento para `asyncio`, que proporciona un gran impulso de rendimiento en concurrencia.
+
+Cuando instalas FastAPI con algo como `pip install "fastapi[standard]"` ya obtienes `uvicorn[standard]` también.
+
+///
+
+## Ejecuta el Programa del Servidor
+
+Si instalaste un servidor ASGI manualmente, normalmente necesitarías pasar una cadena de import en un formato especial para que importe tu aplicación FastAPI:
+
+<div class="termy">
+
+```console
+$ uvicorn main:app --host 0.0.0.0 --port 80
+
+<span style="color: green;">INFO</span>:     Uvicorn corriendo en http://0.0.0.0:80 (Presiona CTRL+C para salir)
+```
+
+</div>
+
+/// note | Nota
+
+El comando `uvicorn main:app` se refiere a:
+
+* `main`: el archivo `main.py` (el "módulo" de Python).
+* `app`: el objeto creado dentro de `main.py` con la línea `app = FastAPI()`.
+
+Es equivalente a:
+
+```Python
+from main import app
+```
+
+///
+
+Cada programa alternativo de servidor ASGI tendría un comando similar, puedes leer más en su respectiva documentación.
+
+/// warning | Advertencia
+
+Uvicorn y otros servidores soportan una opción `--reload` que es útil durante el desarrollo.
+
+La opción `--reload` consume muchos más recursos, es más inestable, etc.
+
+Ayuda mucho durante el **desarrollo**, pero **no** deberías usarla en **producción**.
+
+///
+
+## Conceptos de Despliegue
+
+Estos ejemplos ejecutan el programa del servidor (por ejemplo, Uvicorn), iniciando **un solo proceso**, escuchando en todas las IPs (`0.0.0.0`) en un puerto predefinido (por ejemplo, `80`).
+
+Esta es la idea básica. Pero probablemente querrás encargarte de algunas cosas adicionales, como:
+
+* Seguridad - HTTPS
+* Ejecución en el arranque
+* Reinicios
+* Replicación (el número de procesos ejecutándose)
+* Memoria
+* Pasos previos antes de comenzar
+
+Te contaré más sobre cada uno de estos conceptos, cómo pensarlos, y algunos ejemplos concretos con estrategias para manejarlos en los próximos capítulos. 🚀

docs/es/docs/deployment/server-workers.md

@@ -0,0 +1,152 @@
+# Servidores Workers - Uvicorn con Workers
+
+Vamos a revisar esos conceptos de despliegue de antes:
+
+* Seguridad - HTTPS
+* Ejecución al inicio
+* Reinicios
+* **Replicación (el número de procesos en ejecución)**
+* Memoria
+* Pasos previos antes de empezar
+
+Hasta este punto, con todos los tutoriales en la documentación, probablemente has estado ejecutando un **programa de servidor**, por ejemplo, usando el comando `fastapi`, que ejecuta Uvicorn, corriendo un **solo proceso**.
+
+Al desplegar aplicaciones probablemente querrás tener algo de **replicación de procesos** para aprovechar **múltiples núcleos** y poder manejar más requests.
+
+Como viste en el capítulo anterior sobre [Conceptos de Despliegue](concepts.md){.internal-link target=_blank}, hay múltiples estrategias que puedes usar.
+
+Aquí te mostraré cómo usar **Uvicorn** con **worker processes** usando el comando `fastapi` o el comando `uvicorn` directamente.
+
+/// info | Información
+
+Si estás usando contenedores, por ejemplo con Docker o Kubernetes, te contaré más sobre eso en el próximo capítulo: [FastAPI en Contenedores - Docker](docker.md){.internal-link target=_blank}.
+
+En particular, cuando corras en **Kubernetes** probablemente **no** querrás usar workers y en cambio correr **un solo proceso de Uvicorn por contenedor**, pero te contaré sobre eso más adelante en ese capítulo.
+
+///
+
+## Múltiples Workers
+
+Puedes iniciar múltiples workers con la opción de línea de comando `--workers`:
+
+//// tab | `fastapi`
+
+Si usas el comando `fastapi`:
+
+<div class="termy">
+
+```console
+$ <pre> <font color="#4E9A06">fastapi</font> run --workers 4 <u style="text-decoration-style:single">main.py</u>
+<font color="#3465A4">INFO    </font> Using path <font color="#3465A4">main.py</font>
+<font color="#3465A4">INFO    </font> Resolved absolute path <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
+<font color="#3465A4">INFO    </font> Searching for package file structure from directories with <font color="#3465A4">__init__.py</font> files
+<font color="#3465A4">INFO    </font> Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
+
+ ╭─ <font color="#8AE234"><b>Python module file</b></font> ─╮
+ │                      │
+ │  🐍 main.py          │
+ │                      │
+ ╰──────────────────────╯
+
+<font color="#3465A4">INFO    </font> Importing module <font color="#4E9A06">main</font>
+<font color="#3465A4">INFO    </font> Found importable FastAPI app
+
+ ╭─ <font color="#8AE234"><b>Importable FastAPI app</b></font> ─╮
+ │                          │
+ │  <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822">  </span>  │
+ │                          │
+ ╰──────────────────────────╯
+
+<font color="#3465A4">INFO    </font> Using import string <font color="#8AE234"><b>main:app</b></font>
+
+ <font color="#4E9A06">╭─────────── FastAPI CLI - Production mode ───────────╮</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">│  Serving at: http://0.0.0.0:8000                    │</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">│  API docs: http://0.0.0.0:8000/docs                 │</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">│  Running in production mode, for development use:   │</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">│  </font><font color="#8AE234"><b>fastapi dev</b></font><font color="#4E9A06">                                        │</font>
+ <font color="#4E9A06">│                                                     │</font>
+ <font color="#4E9A06">╰─────────────────────────────────────────────────────╯</font>
+
+<font color="#4E9A06">INFO</font>:     Uvicorn running on <b>http://0.0.0.0:8000</b> (Press CTRL+C to quit)
+<font color="#4E9A06">INFO</font>:     Started parent process [<font color="#34E2E2"><b>27365</b></font>]
+<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">27368</font>]
+<font color="#4E9A06">INFO</font>:     Waiting for application startup.
+<font color="#4E9A06">INFO</font>:     Application startup complete.
+<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">27369</font>]
+<font color="#4E9A06">INFO</font>:     Waiting for application startup.
+<font color="#4E9A06">INFO</font>:     Application startup complete.
+<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">27370</font>]
+<font color="#4E9A06">INFO</font>:     Waiting for application startup.
+<font color="#4E9A06">INFO</font>:     Application startup complete.
+<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">27367</font>]
+<font color="#4E9A06">INFO</font>:     Waiting for application startup.
+<font color="#4E9A06">INFO</font>:     Application startup complete.
+</pre>
+```
+
+</div>
+
+////
+
+//// tab | `uvicorn`
+
+Si prefieres usar el comando `uvicorn` directamente:
+
+<div class="termy">
+
+```console
+$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
+<font color="#A6E22E">INFO</font>:     Uvicorn running on <b>http://0.0.0.0:8080</b> (Press CTRL+C to quit)
+<font color="#A6E22E">INFO</font>:     Started parent process [<font color="#A1EFE4"><b>27365</b></font>]
+<font color="#A6E22E">INFO</font>:     Started server process [<font color="#A1EFE4">27368</font>]
+<font color="#A6E22E">INFO</font>:     Waiting for application startup.
+<font color="#A6E22E">INFO</font>:     Application startup complete.
+<font color="#A6E22E">INFO</font>:     Started server process [<font color="#A1EFE4">27369</font>]
+<font color="#A6E22E">INFO</font>:     Waiting for application startup.
+<font color="#A6E22E">INFO</font>:     Application startup complete.
+<font color="#A6E22E">INFO</font>:     Started server process [<font color="#A1EFE4">27370</font>]
+<font color="#A6E22E">INFO</font>:     Waiting for application startup.
+<font color="#A6E22E">INFO</font>:     Application startup complete.
+<font color="#A6E22E">INFO</font>:     Started server process [<font color="#A1EFE4">27367</font>]
+<font color="#A6E22E">INFO</font>:     Waiting for application startup.
+<font color="#A6E22E">INFO</font>:     Application startup complete.
+```
+
+</div>
+
+////
+
+La única opción nueva aquí es `--workers` indicando a Uvicorn que inicie 4 worker processes.
+
+También puedes ver que muestra el **PID** de cada proceso, `27365` para el proceso padre (este es el **gestor de procesos**) y uno para cada worker process: `27368`, `27369`, `27370`, y `27367`.
+
+## Conceptos de Despliegue
+
+Aquí viste cómo usar múltiples **workers** para **paralelizar** la ejecución de la aplicación, aprovechar los **múltiples núcleos** del CPU, y poder servir **más requests**.
+
+De la lista de conceptos de despliegue de antes, usar workers ayudaría principalmente con la parte de **replicación**, y un poquito con los **reinicios**, pero aún necesitas encargarte de los otros:
+
+* **Seguridad - HTTPS**
+* **Ejecución al inicio**
+* ***Reinicios***
+* Replicación (el número de procesos en ejecución)
+* **Memoria**
+* **Pasos previos antes de empezar**
+
+## Contenedores y Docker
+
+En el próximo capítulo sobre [FastAPI en Contenedores - Docker](docker.md){.internal-link target=_blank} te explicaré algunas estrategias que podrías usar para manejar los otros **conceptos de despliegue**.
+
+Te mostraré cómo **construir tu propia imagen desde cero** para ejecutar un solo proceso de Uvicorn. Es un proceso sencillo y probablemente es lo que querrías hacer al usar un sistema de gestión de contenedores distribuido como **Kubernetes**.
+
+## Resumen
+
+Puedes usar múltiples worker processes con la opción CLI `--workers` con los comandos `fastapi` o `uvicorn` para aprovechar los **CPUs de múltiples núcleos**, para ejecutar **múltiples procesos en paralelo**.
+
+Podrías usar estas herramientas e ideas si estás instalando **tu propio sistema de despliegue** mientras te encargas tú mismo de los otros conceptos de despliegue.
+
+Revisa el próximo capítulo para aprender sobre **FastAPI** con contenedores (por ejemplo, Docker y Kubernetes). Verás que esas herramientas tienen formas sencillas de resolver los otros **conceptos de despliegue** también. ✨

docs/es/docs/deployment/versions.md

@@ -0,0 +1,93 @@
+# Sobre las versiones de FastAPI
+
+**FastAPI** ya se está utilizando en producción en muchas aplicaciones y sistemas. Y la cobertura de tests se mantiene al 100%. Pero su desarrollo sigue avanzando rápidamente.
+
+Se añaden nuevas funcionalidades con frecuencia, se corrigen bugs regularmente, y el código sigue mejorando continuamente.
+
+Por eso las versiones actuales siguen siendo `0.x.x`, esto refleja que cada versión podría tener potencialmente cambios incompatibles. Esto sigue las convenciones de <a href="https://semver.org/" class="external-link" target="_blank">Semantic Versioning</a>.
+
+Puedes crear aplicaciones de producción con **FastAPI** ahora mismo (y probablemente ya lo has estado haciendo desde hace algún tiempo), solo debes asegurarte de que utilizas una versión que funciona correctamente con el resto de tu código.
+
+## Fijar tu versión de `fastapi`
+
+Lo primero que debes hacer es "fijar" la versión de **FastAPI** que estás usando a la versión específica más reciente que sabes que funciona correctamente para tu aplicación.
+
+Por ejemplo, digamos que estás utilizando la versión `0.112.0` en tu aplicación.
+
+Si usas un archivo `requirements.txt` podrías especificar la versión con:
+
+```txt
+fastapi[standard]==0.112.0
+```
+
+eso significaría que usarías exactamente la versión `0.112.0`.
+
+O también podrías fijarla con:
+
+```txt
+fastapi[standard]>=0.112.0,<0.113.0
+```
+
+eso significaría que usarías las versiones `0.112.0` o superiores, pero menores que `0.113.0`, por ejemplo, una versión `0.112.2` todavía sería aceptada.
+
+Si utilizas cualquier otra herramienta para gestionar tus instalaciones, como `uv`, Poetry, Pipenv, u otras, todas tienen una forma que puedes usar para definir versiones específicas para tus paquetes.
+
+## Versiones disponibles
+
+Puedes ver las versiones disponibles (por ejemplo, para revisar cuál es la más reciente) en las [Release Notes](../release-notes.md){.internal-link target=_blank}.
+
+## Sobre las versiones
+
+Siguiendo las convenciones del Semantic Versioning, cualquier versión por debajo de `1.0.0` podría potencialmente añadir cambios incompatibles.
+
+FastAPI también sigue la convención de que cualquier cambio de versión "PATCH" es para corrección de bugs y cambios no incompatibles.
+
+/// tip | Consejo
+
+El "PATCH" es el último número, por ejemplo, en `0.2.3`, la versión PATCH es `3`.
+
+///
+
+Así que deberías poder fijar a una versión como:
+
+```txt
+fastapi>=0.45.0,<0.46.0
+```
+
+Los cambios incompatibles y nuevas funcionalidades se añaden en versiones "MINOR".
+
+/// tip | Consejo
+
+El "MINOR" es el número en el medio, por ejemplo, en `0.2.3`, la versión MINOR es `2`.
+
+///
+
+## Actualizando las versiones de FastAPI
+
+Deberías añadir tests para tu aplicación.
+
+Con **FastAPI** es muy fácil (gracias a Starlette), revisa la documentación: [Testing](../tutorial/testing.md){.internal-link target=_blank}
+
+Después de tener tests, puedes actualizar la versión de **FastAPI** a una más reciente, y asegurarte de que todo tu código está funcionando correctamente ejecutando tus tests.
+
+Si todo está funcionando, o después de hacer los cambios necesarios, y todos tus tests pasan, entonces puedes fijar tu `fastapi` a esa nueva versión más reciente.
+
+## Sobre Starlette
+
+No deberías fijar la versión de `starlette`.
+
+Diferentes versiones de **FastAPI** utilizarán una versión más reciente específica de Starlette.
+
+Así que, puedes simplemente dejar que **FastAPI** use la versión correcta de Starlette.
+
+## Sobre Pydantic
+
+Pydantic incluye los tests para **FastAPI** con sus propios tests, así que nuevas versiones de Pydantic (por encima de `1.0.0`) siempre son compatibles con FastAPI.
+
+Puedes fijar Pydantic a cualquier versión por encima de `1.0.0` que funcione para ti.
+
+Por ejemplo:
+
+```txt
+pydantic>=2.7.0,<3.0.0
+```

docs/es/docs/environment-variables.md

@@ -0,0 +1,298 @@
+# Variables de Entorno
+
+/// tip | Consejo
+
+Si ya sabes qué son las "variables de entorno" y cómo usarlas, siéntete libre de saltarte esto.
+
+///
+
+Una variable de entorno (también conocida como "**env var**") es una variable que vive **fuera** del código de Python, en el **sistema operativo**, y podría ser leída por tu código de Python (o por otros programas también).
+
+Las variables de entorno pueden ser útiles para manejar **configuraciones** de aplicaciones, como parte de la **instalación** de Python, etc.
+
+## Crear y Usar Variables de Entorno
+
+Puedes **crear** y usar variables de entorno en la **shell (terminal)**, sin necesidad de Python:
+
+//// tab | Linux, macOS, Windows Bash
+
+<div class="termy">
+
+```console
+// Podrías crear una env var MY_NAME con
+$ export MY_NAME="Wade Wilson"
+
+// Luego podrías usarla con otros programas, como
+$ echo "Hello $MY_NAME"
+
+Hello Wade Wilson
+```
+
+</div>
+
+////
+
+//// tab | Windows PowerShell
+
+<div class="termy">
+
+```console
+// Crea una env var MY_NAME
+$ $Env:MY_NAME = "Wade Wilson"
+
+// Úsala con otros programas, como
+$ echo "Hello $Env:MY_NAME"
+
+Hello Wade Wilson
+```
+
+</div>
+
+////
+
+## Leer Variables de Entorno en Python
+
+También podrías crear variables de entorno **fuera** de Python, en la terminal (o con cualquier otro método), y luego **leerlas en Python**.
+
+Por ejemplo, podrías tener un archivo `main.py` con:
+
+```Python hl_lines="3"
+import os
+
+name = os.getenv("MY_NAME", "World")
+print(f"Hello {name} from Python")
+```
+
+/// tip | Consejo
+
+El segundo argumento de <a href="https://docs.python.org/3.8/library/os.html#os.getenv" class="external-link" target="_blank">`os.getenv()`</a> es el valor por defecto a retornar.
+
+Si no se proporciona, es `None` por defecto; aquí proporcionamos `"World"` como el valor por defecto para usar.
+
+///
+
+Luego podrías llamar a ese programa Python:
+
+//// tab | Linux, macOS, Windows Bash
+
+<div class="termy">
+
+```console
+// Aquí todavía no configuramos la env var
+$ python main.py
+
+// Como no configuramos la env var, obtenemos el valor por defecto
+
+Hello World from Python
+
+// Pero si creamos una variable de entorno primero
+$ export MY_NAME="Wade Wilson"
+
+// Y luego llamamos al programa nuevamente
+$ python main.py
+
+// Ahora puede leer la variable de entorno
+
+Hello Wade Wilson from Python
+```
+
+</div>
+
+////
+
+//// tab | Windows PowerShell
+
+<div class="termy">
+
+```console
+// Aquí todavía no configuramos la env var
+$ python main.py
+
+// Como no configuramos la env var, obtenemos el valor por defecto
+
+Hello World from Python
+
+// Pero si creamos una variable de entorno primero
+$ $Env:MY_NAME = "Wade Wilson"
+
+// Y luego llamamos al programa nuevamente
+$ python main.py
+
+// Ahora puede leer la variable de entorno
+
+Hello Wade Wilson from Python
+```
+
+</div>
+
+////
+
+Dado que las variables de entorno pueden configurarse fuera del código, pero pueden ser leídas por el código, y no tienen que ser almacenadas (committed en `git`) con el resto de los archivos, es común usarlas para configuraciones o **ajustes**.
+
+También puedes crear una variable de entorno solo para una **invocación específica de un programa**, que está disponible solo para ese programa, y solo durante su duración.
+
+Para hacer eso, créala justo antes del programa en sí, en la misma línea:
+
+<div class="termy">
+
+```console
+// Crea una env var MY_NAME en línea para esta llamada del programa
+$ MY_NAME="Wade Wilson" python main.py
+
+// Ahora puede leer la variable de entorno
+
+Hello Wade Wilson from Python
+
+// La env var ya no existe después
+$ python main.py
+
+Hello World from Python
+```
+
+</div>
+
+/// tip | Consejo
+
+Puedes leer más al respecto en <a href="https://12factor.net/config" class="external-link" target="_blank">The Twelve-Factor App: Config</a>.
+
+///
+
+## Tipos y Validación
+
+Estas variables de entorno solo pueden manejar **strings de texto**, ya que son externas a Python y deben ser compatibles con otros programas y el resto del sistema (e incluso con diferentes sistemas operativos, como Linux, Windows, macOS).
+
+Esto significa que **cualquier valor** leído en Python desde una variable de entorno **será un `str`**, y cualquier conversión a un tipo diferente o cualquier validación tiene que hacerse en el código.
+
+Aprenderás más sobre cómo usar variables de entorno para manejar **configuraciones de aplicación** en la [Guía del Usuario Avanzado - Ajustes y Variables de Entorno](./advanced/settings.md){.internal-link target=_blank}.
+
+## Variable de Entorno `PATH`
+
+Hay una variable de entorno **especial** llamada **`PATH`** que es utilizada por los sistemas operativos (Linux, macOS, Windows) para encontrar programas a ejecutar.
+
+El valor de la variable `PATH` es un string largo que consiste en directorios separados por dos puntos `:` en Linux y macOS, y por punto y coma `;` en Windows.
+
+Por ejemplo, la variable de entorno `PATH` podría verse así:
+
+//// tab | Linux, macOS
+
+```plaintext
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+Esto significa que el sistema debería buscar programas en los directorios:
+
+* `/usr/local/bin`
+* `/usr/bin`
+* `/bin`
+* `/usr/sbin`
+* `/sbin`
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32
+```
+
+Esto significa que el sistema debería buscar programas en los directorios:
+
+* `C:\Program Files\Python312\Scripts`
+* `C:\Program Files\Python312`
+* `C:\Windows\System32`
+
+////
+
+Cuando escribes un **comando** en la terminal, el sistema operativo **busca** el programa en **cada uno de esos directorios** listados en la variable de entorno `PATH`.
+
+Por ejemplo, cuando escribes `python` en la terminal, el sistema operativo busca un programa llamado `python` en el **primer directorio** de esa lista.
+
+Si lo encuentra, entonces lo **utilizará**. De lo contrario, continúa buscando en los **otros directorios**.
+
+### Instalando Python y Actualizando el `PATH`
+
+Cuando instalas Python, se te podría preguntar si deseas actualizar la variable de entorno `PATH`.
+
+//// tab | Linux, macOS
+
+Digamos que instalas Python y termina en un directorio `/opt/custompython/bin`.
+
+Si dices que sí para actualizar la variable de entorno `PATH`, entonces el instalador añadirá `/opt/custompython/bin` a la variable de entorno `PATH`.
+
+Podría verse así:
+
+```plaintext
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin
+```
+
+De esta manera, cuando escribes `python` en la terminal, el sistema encontrará el programa Python en `/opt/custompython/bin` (el último directorio) y usará ese.
+
+////
+
+//// tab | Windows
+
+Digamos que instalas Python y termina en un directorio `C:\opt\custompython\bin`.
+
+Si dices que sí para actualizar la variable de entorno `PATH`, entonces el instalador añadirá `C:\opt\custompython\bin` a la variable de entorno `PATH`.
+
+```plaintext
+C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin
+```
+
+De esta manera, cuando escribes `python` en la terminal, el sistema encontrará el programa Python en `C:\opt\custompython\bin` (el último directorio) y usará ese.
+
+////
+
+Entonces, si escribes:
+
+<div class="termy">
+
+```console
+$ python
+```
+
+</div>
+
+//// tab | Linux, macOS
+
+El sistema **encontrará** el programa `python` en `/opt/custompython/bin` y lo ejecutará.
+
+Esto sería más o menos equivalente a escribir:
+
+<div class="termy">
+
+```console
+$ /opt/custompython/bin/python
+```
+
+</div>
+
+////
+
+//// tab | Windows
+
+El sistema **encontrará** el programa `python` en `C:\opt\custompython\bin\python` y lo ejecutará.
+
+Esto sería más o menos equivalente a escribir:
+
+<div class="termy">
+
+```console
+$ C:\opt\custompython\bin\python
+```
+
+</div>
+
+////
+
+Esta información será útil al aprender sobre [Entornos Virtuales](virtual-environments.md){.internal-link target=_blank}.
+
+## Conclusión
+
+Con esto deberías tener una comprensión básica de qué son las **variables de entorno** y cómo usarlas en Python.
+
+También puedes leer más sobre ellas en la <a href="https://en.wikipedia.org/wiki/Environment_variable" class="external-link" target="_blank">Wikipedia para Variable de Entorno</a>.
+
+En muchos casos no es muy obvio cómo las variables de entorno serían útiles y aplicables de inmediato. Pero siguen apareciendo en muchos escenarios diferentes cuando estás desarrollando, así que es bueno conocerlas.
+
+Por ejemplo, necesitarás esta información en la siguiente sección, sobre [Entornos Virtuales](virtual-environments.md).

docs/es/docs/fastapi-cli.md

@@ -0,0 +1,75 @@
+# FastAPI CLI
+
+**FastAPI CLI** es un programa de línea de comandos que puedes usar para servir tu aplicación FastAPI, gestionar tu proyecto FastAPI, y más.
+
+Cuando instalas FastAPI (por ejemplo, con `pip install "fastapi[standard]"`), incluye un paquete llamado `fastapi-cli`, este paquete proporciona el comando `fastapi` en la terminal.
+
+Para ejecutar tu aplicación FastAPI en modo de desarrollo, puedes usar el comando `fastapi dev`:
+
+<div class="termy">
+
+```console
+$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid">main.py</u>
+
+  <span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span>  Starting development server 🚀
+
+             Searching for package file structure from directories with
+             <font color="#3465A4">__init__.py</font> files
+             Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
+
+   <span style="background-color:#007166"><font color="#D3D7CF"> module </font></span>  🐍 main.py
+
+     <span style="background-color:#007166"><font color="#D3D7CF"> code </font></span>  Importing the FastAPI app object from the module with the
+             following code:
+
+             <u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>
+
+      <span style="background-color:#007166"><font color="#D3D7CF"> app </font></span>  Using import string: <font color="#3465A4">main:app</font>
+
+   <span style="background-color:#007166"><font color="#D3D7CF"> server </font></span>  Server started at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font>
+   <span style="background-color:#007166"><font color="#D3D7CF"> server </font></span>  Documentation at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000/docs</u></font>
+
+      <span style="background-color:#007166"><font color="#D3D7CF"> tip </font></span>  Running in development mode, for production use:
+             <b>fastapi run</b>
+
+             Logs:
+
+     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Will watch for changes in these directories:
+             <b>[</b><font color="#4E9A06">&apos;/home/user/code/awesomeapp&apos;</font><b>]</b>
+     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Uvicorn running on <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font> <b>(</b>Press CTRL+C to
+             quit<b>)</b>
+     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started reloader process <b>[</b><font color="#34E2E2"><b>383138</b></font><b>]</b> using WatchFiles
+     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Started server process <b>[</b><font color="#34E2E2"><b>383153</b></font><b>]</b>
+     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Waiting for application startup.
+     <span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span>  Application startup complete.
+```
+
+</div>
+
+El programa de línea de comandos llamado `fastapi` es **FastAPI CLI**.
+
+FastAPI CLI toma el path de tu programa Python (por ejemplo, `main.py`), detecta automáticamente la `FastAPI` instance (comúnmente llamada `app`), determina el proceso de import correcto, y luego la sirve.
+
+Para producción usarías `fastapi run` en su lugar. 🚀
+
+Internamente, **FastAPI CLI** usa <a href="https://www.uvicorn.dev" class="external-link" target="_blank">Uvicorn</a>, un servidor ASGI de alto rendimiento y listo para producción. 😎
+
+## `fastapi dev`
+
+Ejecutar `fastapi dev` inicia el modo de desarrollo.
+
+Por defecto, **auto-reload** está habilitado, recargando automáticamente el servidor cuando realizas cambios en tu código. Esto consume muchos recursos y podría ser menos estable que cuando está deshabilitado. Deberías usarlo solo para desarrollo. También escucha en la dirección IP `127.0.0.1`, que es la IP para que tu máquina se comunique solo consigo misma (`localhost`).
+
+## `fastapi run`
+
+Ejecutar `fastapi run` inicia FastAPI en modo de producción por defecto.
+
+Por defecto, **auto-reload** está deshabilitado. También escucha en la dirección IP `0.0.0.0`, lo que significa todas las direcciones IP disponibles, de esta manera será accesible públicamente por cualquiera que pueda comunicarse con la máquina. Esta es la manera en la que normalmente lo ejecutarías en producción, por ejemplo, en un contenedor.
+
+En la mayoría de los casos tendrías (y deberías) tener un "proxy de terminación" manejando HTTPS por ti, esto dependerá de cómo despliegues tu aplicación, tu proveedor podría hacer esto por ti, o podrías necesitar configurarlo tú mismo.
+
+/// tip | Consejo
+
+Puedes aprender más al respecto en la [documentación de despliegue](deployment/index.md){.internal-link target=_blank}.
+
+///

docs/es/docs/features.md

@@ -0,0 +1,201 @@
+# Funcionalidades
+
+## Funcionalidades de FastAPI
+
+**FastAPI** te ofrece lo siguiente:
+
+### Basado en estándares abiertos
+
+* <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank"><strong>OpenAPI</strong></a> para la creación de APIs, incluyendo declaraciones de <abbr title="también conocido como: endpoints, rutas">path</abbr> <abbr title="también conocido como métodos HTTP, como POST, GET, PUT, DELETE">operations</abbr>, parámetros, request bodies, seguridad, etc.
+* Documentación automática de modelos de datos con <a href="https://json-schema.org/" class="external-link" target="_blank"><strong>JSON Schema</strong></a> (ya que OpenAPI en sí mismo está basado en JSON Schema).
+* Diseñado alrededor de estos estándares, tras un estudio meticuloso. En lugar de ser una capa adicional.
+* Esto también permite el uso de **generación de código cliente automática** en muchos idiomas.
+
+### Documentación automática
+
+Interfaces web de documentación y exploración de APIs interactivas. Como el framework está basado en OpenAPI, hay múltiples opciones, 2 incluidas por defecto.
+
+* <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank"><strong>Swagger UI</strong></a>, con exploración interactiva, llama y prueba tu API directamente desde el navegador.
+
+![Interacción Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png)
+
+* Documentación alternativa de API con <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank"><strong>ReDoc</strong></a>.
+
+![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png)
+
+### Solo Python moderno
+
+Todo está basado en declaraciones estándar de **tipos en Python** (gracias a Pydantic). Sin nueva sintaxis que aprender. Solo Python moderno estándar.
+
+Si necesitas un repaso de 2 minutos sobre cómo usar tipos en Python (aunque no uses FastAPI), revisa el tutorial corto: [Tipos en Python](python-types.md){.internal-link target=_blank}.
+
+Escribes Python estándar con tipos:
+
+```Python
+from datetime import date
+
+from pydantic import BaseModel
+
+# Declara una variable como un str
+# y obtiene soporte del editor dentro de la función
+def main(user_id: str):
+    return user_id
+
+
+# Un modelo de Pydantic
+class User(BaseModel):
+    id: int
+    name: str
+    joined: date
+```
+
+Que luego puede ser usado como:
+
+```Python
+my_user: User = User(id=3, name="John Doe", joined="2018-07-19")
+
+second_user_data = {
+    "id": 4,
+    "name": "Mary",
+    "joined": "2018-11-30",
+}
+
+my_second_user: User = User(**second_user_data)
+```
+
+/// info | Información
+
+`**second_user_data` significa:
+
+Pasa las claves y valores del dict `second_user_data` directamente como argumentos de clave-valor, equivalente a: `User(id=4, name="Mary", joined="2018-11-30")`
+
+///
+
+### Soporte del editor
+
+Todo el framework fue diseñado para ser fácil e intuitivo de usar, todas las decisiones fueron probadas en múltiples editores incluso antes de comenzar el desarrollo, para asegurar la mejor experiencia de desarrollo.
+
+En las encuestas a desarrolladores de Python, es claro <a href="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features" class="external-link" target="_blank">que una de las funcionalidades más usadas es el "autocompletado"</a>.
+
+Todo el framework **FastAPI** está basado para satisfacer eso. El autocompletado funciona en todas partes.
+
+Rara vez necesitarás regresar a la documentación.
+
+Aquí está cómo tu editor podría ayudarte:
+
+* en <a href="https://code.visualstudio.com/" class="external-link" target="_blank">Visual Studio Code</a>:
+
+![soporte del editor](https://fastapi.tiangolo.com/img/vscode-completion.png)
+
+* en <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>:
+
+![soporte del editor](https://fastapi.tiangolo.com/img/pycharm-completion.png)
+
+Obtendrás autocompletado en código que podrías considerar imposible antes. Por ejemplo, la clave `price` dentro de un cuerpo JSON (que podría haber estado anidado) que proviene de un request.
+
+No más escribir nombres de claves incorrectos, yendo de un lado a otro entre la documentación, o desplazándote hacia arriba y abajo para encontrar si finalmente usaste `username` o `user_name`.
+
+### Breve
+
+Tiene **valores predeterminados** sensatos para todo, con configuraciones opcionales en todas partes. Todos los parámetros se pueden ajustar finamente para hacer lo que necesitas y para definir el API que necesitas.
+
+Pero por defecto, todo **"simplemente funciona"**.
+
+### Validación
+
+* Validación para la mayoría (¿o todas?) de los **tipos de datos** de Python, incluyendo:
+    * Objetos JSON (`dict`).
+    * Array JSON (`list`) definiendo tipos de elementos.
+    * Campos de cadena de caracteres (`str`), definiendo longitudes mínimas y máximas.
+    * Números (`int`, `float`) con valores mínimos y máximos, etc.
+
+* Validación para tipos más exóticos, como:
+    * URL.
+    * Email.
+    * UUID.
+    * ...y otros.
+
+Toda la validación es manejada por **Pydantic**, una herramienta bien establecida y robusta.
+
+### Seguridad y autenticación
+
+Seguridad y autenticación integradas. Sin ningún compromiso con bases de datos o modelos de datos.
+
+Todos los esquemas de seguridad definidos en OpenAPI, incluyendo:
+
+* HTTP Básico.
+* **OAuth2** (también con **tokens JWT**). Revisa el tutorial sobre [OAuth2 con JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}.
+* API keys en:
+    * Headers.
+    * Parámetros de query.
+    * Cookies, etc.
+
+Además de todas las características de seguridad de Starlette (incluyendo **cookies de sesión**).
+
+Todo construido como herramientas y componentes reutilizables que son fáciles de integrar con tus sistemas, almacenes de datos, bases de datos relacionales y NoSQL, etc.
+
+### Inyección de dependencias
+
+FastAPI incluye un sistema de <abbr title='también conocido como "componentes", "recursos", "servicios", "proveedores"'><strong>Inyección de Dependencias</strong></abbr> extremadamente fácil de usar, pero extremadamente potente.
+
+* Incluso las dependencias pueden tener dependencias, creando una jerarquía o **"gráfico de dependencias"**.
+* Todo **manejado automáticamente** por el framework.
+* Todas las dependencias pueden requerir datos de los requests y **aumentar las restricciones de la path operation** y la documentación automática.
+* **Validación automática** incluso para los parámetros de *path operation* definidos en las dependencias.
+* Soporte para sistemas de autenticación de usuario complejos, **conexiones a bases de datos**, etc.
+* **Sin compromisos** con bases de datos, frontends, etc. Pero fácil integración con todos ellos.
+
+### "Plug-ins" ilimitados
+
+O de otra manera, no hay necesidad de ellos, importa y usa el código que necesitas.
+
+Cualquier integración está diseñada para ser tan simple de usar (con dependencias) que puedes crear un "plug-in" para tu aplicación en 2 líneas de código usando la misma estructura y sintaxis utilizada para tus *path operations*.
+
+### Probado
+
+* 100% de <abbr title="La cantidad de código que se prueba automáticamente">cobertura de tests</abbr>.
+* Código completamente <abbr title="Anotaciones de tipos en Python, con esto tu editor y herramientas externas pueden ofrecerte mejor soporte">anotado con tipos</abbr>.
+* Usado en aplicaciones en producción.
+
+## Funcionalidades de Starlette
+
+**FastAPI** es totalmente compatible con (y está basado en) <a href="https://www.starlette.dev/" class="external-link" target="_blank"><strong>Starlette</strong></a>. Así que, cualquier código adicional de Starlette que tengas, también funcionará.
+
+`FastAPI` es en realidad una subclase de `Starlette`. Así que, si ya conoces o usas Starlette, la mayoría de las funcionalidades funcionarán de la misma manera.
+
+Con **FastAPI** obtienes todas las funcionalidades de **Starlette** (ya que FastAPI es simplemente Starlette potenciado):
+
+* Rendimiento seriamente impresionante. Es <a href="https://github.com/encode/starlette#performance" class="external-link" target="_blank">uno de los frameworks de Python más rápidos disponibles, a la par de **NodeJS** y **Go**</a>.
+* Soporte para **WebSocket**.
+* Tareas en segundo plano en el mismo proceso.
+* Eventos de inicio y apagado.
+* Cliente de prueba basado en HTTPX.
+* **CORS**, GZip, archivos estáticos, responses en streaming.
+* Soporte para **Session y Cookie**.
+* Cobertura de tests del 100%.
+* Código completamente anotado con tipos.
+
+## Funcionalidades de Pydantic
+
+**FastAPI** es totalmente compatible con (y está basado en) <a href="https://docs.pydantic.dev/" class="external-link" target="_blank"><strong>Pydantic</strong></a>. Por lo tanto, cualquier código adicional de Pydantic que tengas, también funcionará.
+
+Incluyendo paquetes externos también basados en Pydantic, como <abbr title="Object-Relational Mapper">ORM</abbr>s, <abbr title="Object-Document Mapper">ODM</abbr>s para bases de datos.
+
+Esto también significa que, en muchos casos, puedes pasar el mismo objeto que obtienes de un request **directamente a la base de datos**, ya que todo se valida automáticamente.
+
+Lo mismo aplica al revés, en muchos casos puedes simplemente pasar el objeto que obtienes de la base de datos **directamente al cliente**.
+
+Con **FastAPI** obtienes todas las funcionalidades de **Pydantic** (ya que FastAPI está basado en Pydantic para todo el manejo de datos):
+
+* **Sin complicaciones**:
+    * Sin micro-lenguaje de definición de esquemas nuevo que aprender.
+    * Si conoces los tipos en Python sabes cómo usar Pydantic.
+* Se lleva bien con tu **<abbr title="Entorno de Desarrollo Integrado, similar a un editor de código">IDE</abbr>/<abbr title="Un programa que verifica errores de código">linter</abbr>/cerebro**:
+    * Porque las estructuras de datos de pydantic son solo instances de clases que defines; autocompletado, linting, mypy y tu intuición deberían funcionar correctamente con tus datos validados.
+* Valida **estructuras complejas**:
+    * Uso de modelos jerárquicos de Pydantic, `List` y `Dict` de `typing` de Python, etc.
+    * Y los validadores permiten definir, verificar y documentar de manera clara y fácil esquemas de datos complejos como JSON Schema.
+    * Puedes tener objetos JSON profundamente **anidados** y validarlos todos y anotarlos.
+* **Extensible**:
+    * Pydantic permite definir tipos de datos personalizados o puedes extender la validación con métodos en un modelo decorados con el decorador validator.
+* Cobertura de tests del 100%.

docs/es/docs/help-fastapi.md

@@ -0,0 +1,269 @@
+# Ayuda a FastAPI - Consigue Ayuda
+
+¿Te gusta **FastAPI**?
+
+¿Te gustaría ayudar a FastAPI, a otros usuarios y al autor?
+
+¿O te gustaría conseguir ayuda con **FastAPI**?
+
+Hay formas muy sencillas de ayudar (varias implican solo uno o dos clics).
+
+Y también hay varias formas de conseguir ayuda.
+
+## Suscríbete al boletín
+
+Puedes suscribirte al (esporádico) boletín [**FastAPI and friends**](newsletter.md){.internal-link target=_blank} para mantenerte al día sobre:
+
+* Noticias sobre FastAPI y amigos 🚀
+* Guías 📝
+* Funcionalidades ✨
+* Cambios importantes 🚨
+* Consejos y trucos ✅
+
+## Sigue a FastAPI en X (Twitter)
+
+<a href="https://x.com/fastapi" class="external-link" target="_blank">Sigue a @fastapi en **X (Twitter)**</a> para obtener las últimas noticias sobre **FastAPI**. 🐦
+
+## Dale una estrella a **FastAPI** en GitHub
+
+Puedes "darle una estrella" a FastAPI en GitHub (haciendo clic en el botón de estrella en la parte superior derecha): <a href="https://github.com/fastapi/fastapi" class="external-link" target="_blank">https://github.com/fastapi/fastapi</a>. ⭐️
+
+Al agregar una estrella, otros usuarios podrán encontrarlo más fácilmente y ver que ya ha sido útil para otros.
+
+## Observa el repositorio de GitHub para lanzamientos
+
+Puedes "observar" FastAPI en GitHub (haciendo clic en el botón "watch" en la parte superior derecha): <a href="https://github.com/fastapi/fastapi" class="external-link" target="_blank">https://github.com/fastapi/fastapi</a>. 👀
+
+Allí puedes seleccionar "Releases only".
+
+Al hacerlo, recibirás notificaciones (en tu email) cada vez que haya un nuevo lanzamiento (una nueva versión) de **FastAPI** con correcciones de bugs y nuevas funcionalidades.
+
+## Conéctate con el autor
+
+Puedes conectar <a href="https://tiangolo.com" class="external-link" target="_blank">conmigo (Sebastián Ramírez / `tiangolo`)</a>, el autor.
+
+Puedes:
+
+* <a href="https://github.com/tiangolo" class="external-link" target="_blank">Seguirme en **GitHub**</a>.
+    * Ver otros proyectos de Código Abierto que he creado y que podrían ayudarte.
+    * Seguirme para ver cuándo creo un nuevo proyecto de Código Abierto.
+* <a href="https://x.com/tiangolo" class="external-link" target="_blank">Seguirme en **X (Twitter)**</a> o <a href="https://fosstodon.org/@tiangolo" class="external-link" target="_blank">Mastodon</a>.
+    * Contarme cómo usas FastAPI (me encanta oír eso).
+    * Enterarte cuando hago anuncios o lanzo nuevas herramientas.
+    * También puedes <a href="https://x.com/fastapi" class="external-link" target="_blank">seguir @fastapi en X (Twitter)</a> (una cuenta aparte).
+* <a href="https://www.linkedin.com/in/tiangolo/" class="external-link" target="_blank">Seguirme en **LinkedIn**</a>.
+    * Enterarte cuando hago anuncios o lanzo nuevas herramientas (aunque uso X (Twitter) más a menudo 🤷‍♂).
+* Leer lo que escribo (o seguirme) en <a href="https://dev.to/tiangolo" class="external-link" target="_blank">**Dev.to**</a> o <a href="https://medium.com/@tiangolo" class="external-link" target="_blank">**Medium**</a>.
+    * Leer otras ideas, artículos, y leer sobre las herramientas que he creado.
+    * Seguirme para leer lo que publico nuevo.
+
+## Twittea sobre **FastAPI**
+
+<a href="https://x.com/compose/tweet?text=I'm loving @fastapi because... https://github.com/fastapi/fastapi" class="external-link" target="_blank">Twittea sobre **FastAPI**</a> y dime a mí y a otros por qué te gusta. 🎉
+
+Me encanta escuchar cómo se está utilizando **FastAPI**, qué te ha gustado, en qué proyecto/empresa lo estás usando, etc.
+
+## Vota por FastAPI
+
+* <a href="https://www.slant.co/options/34241/~fastapi-review" class="external-link" target="_blank">Vota por **FastAPI** en Slant</a>.
+* <a href="https://alternativeto.net/software/fastapi/about/" class="external-link" target="_blank">Vota por **FastAPI** en AlternativeTo</a>.
+* <a href="https://stackshare.io/pypi-fastapi" class="external-link" target="_blank">Di que usas **FastAPI** en StackShare</a>.
+
+## Ayuda a otros con preguntas en GitHub
+
+Puedes intentar ayudar a otros con sus preguntas en:
+
+* <a href="https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered" class="external-link" target="_blank">GitHub Discussions</a>
+* <a href="https://github.com/fastapi/fastapi/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aquestion+-label%3Aanswered+" class="external-link" target="_blank">GitHub Issues</a>
+
+En muchos casos, probablemente ya conozcas la respuesta a esas preguntas. 🤓
+
+Si estás ayudando mucho a la gente con sus preguntas, te convertirás en un [FastAPI Expert](fastapi-people.md#fastapi-experts){.internal-link target=_blank} oficial. 🎉
+
+Solo recuerda, el punto más importante es: trata de ser amable. La gente llega con sus frustraciones y, en muchos casos, no pregunta de la mejor manera, pero haz todo lo posible por ser amable. 🤗
+
+La idea es que la comunidad de **FastAPI** sea amable y acogedora. Al mismo tiempo, no aceptes acoso o comportamiento irrespetuoso hacia los demás. Tenemos que cuidarnos unos a otros.
+
+---
+
+Aquí te explico cómo ayudar a otros con preguntas (en discusiones o issues):
+
+### Entiende la pregunta
+
+* Revisa si puedes entender cuál es el **propósito** y el caso de uso de la persona que pregunta.
+
+* Luego revisa si la pregunta (la gran mayoría son preguntas) es **clara**.
+
+* En muchos casos, la pregunta planteada es sobre una solución imaginaria del usuario, pero podría haber una **mejor**. Si puedes entender mejor el problema y el caso de uso, podrías sugerir una mejor **solución alternativa**.
+
+* Si no puedes entender la pregunta, pide más **detalles**.
+
+### Reproduce el problema
+
+En la mayoría de los casos y preguntas hay algo relacionado con el **código original** de la persona.
+
+En muchos casos solo copiarán un fragmento del código, pero eso no es suficiente para **reproducir el problema**.
+
+* Puedes pedirles que proporcionen un <a href="https://stackoverflow.com/help/minimal-reproducible-example" class="external-link" target="_blank">ejemplo mínimo, reproducible</a>, que puedas **copiar-pegar** y ejecutar localmente para ver el mismo error o comportamiento que están viendo, o para entender mejor su caso de uso.
+
+* Si te sientes muy generoso, puedes intentar **crear un ejemplo** así tú mismo, solo basado en la descripción del problema. Solo ten en cuenta que esto podría llevar mucho tiempo y podría ser mejor pedirles que aclaren el problema primero.
+
+### Sugerir soluciones
+
+* Después de poder entender la pregunta, puedes darles un posible **respuesta**.
+
+* En muchos casos, es mejor entender su **problema subyacente o caso de uso**, porque podría haber una mejor manera de resolverlo que lo que están intentando hacer.
+
+### Pide cerrar
+
+Si responden, hay una alta probabilidad de que hayas resuelto su problema, felicidades, ¡**eres un héroe**! 🦸
+
+* Ahora, si eso resolvió su problema, puedes pedirles que:
+
+    * En GitHub Discussions: marquen el comentario como la **respuesta**.
+    * En GitHub Issues: **cierren** el issue.
+
+## Observa el repositorio de GitHub
+
+Puedes "observar" FastAPI en GitHub (haciendo clic en el botón "watch" en la parte superior derecha): <a href="https://github.com/fastapi/fastapi" class="external-link" target="_blank">https://github.com/fastapi/fastapi</a>. 👀
+
+Si seleccionas "Watching" en lugar de "Releases only", recibirás notificaciones cuando alguien cree un nuevo issue o pregunta. También puedes especificar que solo deseas que te notifiquen sobre nuevos issues, discusiones, PRs, etc.
+
+Luego puedes intentar ayudarlos a resolver esas preguntas.
+
+## Haz preguntas
+
+Puedes <a href="https://github.com/fastapi/fastapi/discussions/new?category=questions" class="external-link" target="_blank">crear una nueva pregunta</a> en el repositorio de GitHub, por ejemplo, para:
+
+* Hacer una **pregunta** o preguntar sobre un **problema**.
+* Sugerir una nueva **funcionalidad**.
+
+**Nota**: si lo haces, entonces te voy a pedir que también ayudes a otros. 😉
+
+## Revisa Pull Requests
+
+Puedes ayudarme a revisar pull requests de otros.
+
+De nuevo, por favor, haz tu mejor esfuerzo por ser amable. 🤗
+
+---
+
+Aquí está lo que debes tener en cuenta y cómo revisar un pull request:
+
+### Entiende el problema
+
+* Primero, asegúrate de **entender el problema** que el pull request está intentando resolver. Podría tener una discusión más larga en una GitHub Discussion o issue.
+
+* También hay una buena posibilidad de que el pull request no sea realmente necesario porque el problema se puede resolver de una manera **diferente**. Entonces puedes sugerir o preguntar sobre eso.
+
+### No te preocupes por el estilo
+
+* No te preocupes demasiado por cosas como los estilos de los mensajes de commit, yo haré squash y merge personalizando el commit manualmente.
+
+* Tampoco te preocupes por las reglas de estilo, hay herramientas automatizadas verificando eso.
+
+Y si hay alguna otra necesidad de estilo o consistencia, pediré directamente eso, o agregaré commits encima con los cambios necesarios.
+
+### Revisa el código
+
+* Revisa y lee el código, ve si tiene sentido, **ejecútalo localmente** y ve si realmente resuelve el problema.
+
+* Luego **comenta** diciendo que hiciste eso, así sabré que realmente lo revisaste.
+
+/// info | Información
+
+Desafortunadamente, no puedo simplemente confiar en PRs que solo tienen varias aprobaciones.
+
+Varias veces ha sucedido que hay PRs con 3, 5 o más aprobaciones, probablemente porque la descripción es atractiva, pero cuando reviso los PRs, en realidad están rotos, tienen un bug, o no resuelven el problema que dicen resolver. 😅
+
+Así que, es realmente importante que realmente leas y ejecutes el código, y me hagas saber en los comentarios que lo hiciste. 🤓
+
+///
+
+* Si el PR se puede simplificar de alguna manera, puedes pedir eso, pero no hay necesidad de ser demasiado exigente, podría haber muchos puntos de vista subjetivos (y yo tendré el mío también 🙈), así que es mejor si puedes centrarte en las cosas fundamentales.
+
+### Tests
+
+* Ayúdame a verificar que el PR tenga **tests**.
+
+* Verifica que los tests **fallen** antes del PR. 🚨
+
+* Luego verifica que los tests **pasen** después del PR. ✅
+
+* Muchos PRs no tienen tests, puedes **recordarles** que agreguen tests, o incluso puedes **sugerir** algunos tests tú mismo. Eso es una de las cosas que consume más tiempo y puedes ayudar mucho con eso.
+
+* Luego también comenta lo que intentaste, de esa manera sabré que lo revisaste. 🤓
+
+## Crea un Pull Request
+
+Puedes [contribuir](contributing.md){.internal-link target=_blank} al código fuente con Pull Requests, por ejemplo:
+
+* Para corregir un error tipográfico que encontraste en la documentación.
+* Para compartir un artículo, video o podcast que creaste o encontraste sobre FastAPI <a href="https://github.com/fastapi/fastapi/edit/master/docs/en/data/external_links.yml" class="external-link" target="_blank">editando este archivo</a>.
+    * Asegúrate de agregar tu enlace al inicio de la sección correspondiente.
+* Para ayudar a [traducir la documentación](contributing.md#translations){.internal-link target=_blank} a tu idioma.
+    * También puedes ayudar a revisar las traducciones creadas por otros.
+* Para proponer nuevas secciones de documentación.
+* Para corregir un issue/bug existente.
+    * Asegúrate de agregar tests.
+* Para agregar una nueva funcionalidad.
+    * Asegúrate de agregar tests.
+    * Asegúrate de agregar documentación si es relevante.
+
+## Ayuda a Mantener FastAPI
+
+¡Ayúdame a mantener **FastAPI**! 🤓
+
+Hay mucho trabajo por hacer, y para la mayoría de ello, **TÚ** puedes hacerlo.
+
+Las tareas principales que puedes hacer ahora son:
+
+* [Ayudar a otros con preguntas en GitHub](#help-others-with-questions-in-github){.internal-link target=_blank} (ver la sección arriba).
+* [Revisar Pull Requests](#review-pull-requests){.internal-link target=_blank} (ver la sección arriba).
+
+Esas dos tareas son las que **consumen más tiempo**. Ese es el trabajo principal de mantener FastAPI.
+
+Si puedes ayudarme con eso, **me estás ayudando a mantener FastAPI** y asegurando que siga **avanzando más rápido y mejor**. 🚀
+
+## Únete al chat
+
+Únete al servidor de chat 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">Discord</a> 👥 y charla con otros en la comunidad de FastAPI.
+
+/// tip | Consejo
+
+Para preguntas, házlas en <a href="https://github.com/fastapi/fastapi/discussions/new?category=questions" class="external-link" target="_blank">GitHub Discussions</a>, hay muchas más probabilidades de que recibas ayuda de parte de los [FastAPI Experts](fastapi-people.md#fastapi-experts){.internal-link target=_blank}.
+
+Usa el chat solo para otras conversaciones generales.
+
+///
+
+### No uses el chat para preguntas
+
+Ten en cuenta que dado que los chats permiten una "conversación más libre", es fácil hacer preguntas que son demasiado generales y más difíciles de responder, por lo que es posible que no recibas respuestas.
+
+En GitHub, la plantilla te guiará para escribir la pregunta correcta para que puedas obtener más fácilmente una buena respuesta, o incluso resolver el problema por ti mismo antes de preguntar. Y en GitHub puedo asegurarme de responder siempre todo, incluso si lleva tiempo. No puedo hacer eso personalmente con los sistemas de chat. 😅
+
+Las conversaciones en los sistemas de chat tampoco son tan fácilmente buscables como en GitHub, por lo que las preguntas y respuestas podrían perderse en la conversación. Y solo las que están en GitHub cuentan para convertirse en un [FastAPI Expert](fastapi-people.md#fastapi-experts){.internal-link target=_blank}, por lo que probablemente recibirás más atención en GitHub.
+
+Por otro lado, hay miles de usuarios en los sistemas de chat, por lo que hay muchas posibilidades de que encuentres a alguien con quien hablar allí, casi todo el tiempo. 😄
+
+## Patrocina al autor
+
+También puedes apoyar financieramente al autor (a mí) a través de <a href="https://github.com/sponsors/tiangolo" class="external-link" target="_blank">GitHub sponsors</a>.
+
+Allí podrías comprarme un café ☕️ para decir gracias. 😄
+
+Y también puedes convertirte en un sponsor de Plata o de Oro para FastAPI. 🏅🎉
+
+## Patrocina las herramientas que impulsan FastAPI
+
+Como habrás visto en la documentación, FastAPI se apoya en los hombros de gigantes, Starlette y Pydantic.
+
+También puedes patrocinar:
+
+* <a href="https://github.com/sponsors/samuelcolvin" class="external-link" target="_blank">Samuel Colvin (Pydantic)</a>
+* <a href="https://github.com/sponsors/encode" class="external-link" target="_blank">Encode (Starlette, Uvicorn)</a>
+
+---
+
+¡Gracias! 🚀

docs/es/docs/history-design-future.md

@@ -0,0 +1,79 @@
+# Historia, Diseño y Futuro
+
+Hace algún tiempo, <a href="https://github.com/fastapi/fastapi/issues/3#issuecomment-454956920" class="external-link" target="_blank">un usuario de **FastAPI** preguntó</a>:
+
+> ¿Cuál es la historia de este proyecto? Parece haber surgido de la nada y ser increíble en pocas semanas [...]
+
+Aquí hay un poquito de esa historia.
+
+## Alternativas
+
+He estado creando APIs con requisitos complejos durante varios años (Machine Learning, sistemas distribuidos, trabajos asíncronos, bases de datos NoSQL, etc.), liderando varios equipos de desarrolladores.
+
+Como parte de eso, necesitaba investigar, probar y usar muchas alternativas.
+
+La historia de **FastAPI** es en gran parte la historia de sus predecesores.
+
+Como se dice en la sección [Alternativas](alternatives.md){.internal-link target=_blank}:
+
+<blockquote markdown="1">
+
+**FastAPI** no existiría si no fuera por el trabajo previo de otros.
+
+Ha habido muchas herramientas creadas antes que han ayudado a inspirar su creación.
+
+He estado evitando la creación de un nuevo framework durante varios años. Primero traté de resolver todas las funcionalidades cubiertas por **FastAPI** usando varios frameworks, complementos y herramientas diferentes.
+
+Pero en algún momento, no había otra opción que crear algo que proporcionara todas estas funcionalidades, tomando las mejores ideas de herramientas anteriores y combinándolas de la mejor manera posible, usando funcionalidades del lenguaje que ni siquiera estaban disponibles antes (anotaciones de tipos de Python 3.6+).
+
+</blockquote>
+
+## Investigación
+
+Al usar todas las alternativas anteriores, tuve la oportunidad de aprender de todas ellas, tomar ideas y combinarlas de la mejor manera que pude encontrar para mí y los equipos de desarrolladores con los que he trabajado.
+
+Por ejemplo, estaba claro que idealmente debería estar basado en las anotaciones de tipos estándar de Python.
+
+También, el mejor enfoque era usar estándares ya existentes.
+
+Entonces, antes de siquiera empezar a programar **FastAPI**, pasé varios meses estudiando las especificaciones de OpenAPI, JSON Schema, OAuth2, etc. Entendiendo su relación, superposición y diferencias.
+
+## Diseño
+
+Luego pasé algún tiempo diseñando la "API" de desarrollador que quería tener como usuario (como desarrollador usando FastAPI).
+
+Probé varias ideas en los editores de Python más populares: PyCharm, VS Code, editores basados en Jedi.
+
+Según la última <a href="https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools" class="external-link" target="_blank">Encuesta de Desarrolladores de Python</a>, estos editores cubren alrededor del 80% de los usuarios.
+
+Esto significa que **FastAPI** fue específicamente probado con los editores usados por el 80% de los desarrolladores de Python. Y como la mayoría de los otros editores tienden a funcionar de manera similar, todos sus beneficios deberían funcionar prácticamente para todos los editores.
+
+De esa manera, pude encontrar las mejores maneras de reducir la duplicación de código tanto como fuera posible, para tener autocompletado en todas partes, chequeos de tipos y errores, etc.
+
+Todo de una manera que proporcionara la mejor experiencia de desarrollo para todos los desarrolladores.
+
+## Requisitos
+
+Después de probar varias alternativas, decidí que iba a usar <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">**Pydantic**</a> por sus ventajas.
+
+Luego contribuí a este, para hacerlo totalmente compatible con JSON Schema, para soportar diferentes maneras de definir declaraciones de restricciones, y para mejorar el soporte de los editores (chequeo de tipos, autocompletado) basado en las pruebas en varios editores.
+
+Durante el desarrollo, también contribuí a <a href="https://www.starlette.dev/" class="external-link" target="_blank">**Starlette**</a>, el otro requisito clave.
+
+## Desarrollo
+
+Para cuando comencé a crear el propio **FastAPI**, la mayoría de las piezas ya estaban en su lugar, el diseño estaba definido, los requisitos y herramientas estaban listos, y el conocimiento sobre los estándares y especificaciones estaba claro y fresco.
+
+## Futuro
+
+A este punto, ya está claro que **FastAPI** con sus ideas está siendo útil para muchas personas.
+
+Está siendo elegido sobre alternativas anteriores por adaptarse mejor a muchos casos de uso.
+
+Muchos desarrolladores y equipos ya dependen de **FastAPI** para sus proyectos (incluyéndome a mí y a mi equipo).
+
+Pero aún así, hay muchas mejoras y funcionalidades por venir.
+
+**FastAPI** tiene un gran futuro por delante.
+
+Y [tu ayuda](help-fastapi.md){.internal-link target=_blank} es muy apreciada.

docs/es/docs/how-to/conditional-openapi.md

@@ -0,0 +1,56 @@
+# OpenAPI Condicional
+
+Si lo necesitaras, podrías usar configuraciones y variables de entorno para configurar OpenAPI condicionalmente según el entorno, e incluso desactivarlo por completo.
+
+## Sobre seguridad, APIs y documentación
+
+Ocultar las interfaces de usuario de la documentación en producción *no debería* ser la forma de proteger tu API.
+
+Eso no añade ninguna seguridad extra a tu API, las *path operations* seguirán estando disponibles donde están.
+
+Si hay una falla de seguridad en tu código, seguirá existiendo.
+
+Ocultar la documentación solo hace que sea más difícil entender cómo interactuar con tu API y podría dificultar más depurarla en producción. Podría considerarse simplemente una forma de <a href="https://en.wikipedia.org/wiki/Security_through_obscurity" class="external-link" target="_blank">Seguridad mediante oscuridad</a>.
+
+Si quieres asegurar tu API, hay varias cosas mejores que puedes hacer, por ejemplo:
+
+* Asegúrate de tener modelos Pydantic bien definidos para tus request bodies y responses.
+* Configura los permisos y roles necesarios usando dependencias.
+* Nunca guardes contraseñas en texto plano, solo hashes de contraseñas.
+* Implementa y utiliza herramientas criptográficas bien conocidas, como Passlib y JWT tokens, etc.
+* Añade controles de permisos más detallados con OAuth2 scopes donde sea necesario.
+* ...etc.
+
+No obstante, podrías tener un caso de uso muy específico donde realmente necesites desactivar la documentación de la API para algún entorno (por ejemplo, para producción) o dependiendo de configuraciones de variables de entorno.
+
+## OpenAPI condicional desde configuraciones y variables de entorno
+
+Puedes usar fácilmente las mismas configuraciones de Pydantic para configurar tu OpenAPI generado y las interfaces de usuario de la documentación.
+
+Por ejemplo:
+
+{* ../../docs_src/conditional_openapi/tutorial001.py hl[6,11] *}
+
+Aquí declaramos la configuración `openapi_url` con el mismo valor predeterminado de `"/openapi.json"`.
+
+Y luego la usamos al crear la app de `FastAPI`.
+
+Entonces podrías desactivar OpenAPI (incluyendo las UI de documentación) configurando la variable de entorno `OPENAPI_URL` a una string vacía, así:
+
+<div class="termy">
+
+```console
+$ OPENAPI_URL= uvicorn main:app
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+</div>
+
+Luego, si vas a las URLs en `/openapi.json`, `/docs`, o `/redoc`, solo obtendrás un error `404 Not Found` como:
+
+```JSON
+{
+    "detail": "Not Found"
+}
+```

docs/es/docs/how-to/configure-swagger-ui.md

@@ -0,0 +1,70 @@
+# Configurar Swagger UI
+
+Puedes configurar algunos <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">parámetros adicionales de Swagger UI</a>.
+
+Para configurarlos, pasa el argumento `swagger_ui_parameters` al crear el objeto de la app `FastAPI()` o a la función `get_swagger_ui_html()`.
+
+`swagger_ui_parameters` recibe un diccionario con las configuraciones pasadas directamente a Swagger UI.
+
+FastAPI convierte las configuraciones a **JSON** para hacerlas compatibles con JavaScript, ya que eso es lo que Swagger UI necesita.
+
+## Desactivar el resaltado de sintaxis
+
+Por ejemplo, podrías desactivar el resaltado de sintaxis en Swagger UI.
+
+Sin cambiar la configuración, el resaltado de sintaxis está activado por defecto:
+
+<img src="/img/tutorial/extending-openapi/image02.png">
+
+Pero puedes desactivarlo estableciendo `syntaxHighlight` en `False`:
+
+{* ../../docs_src/configure_swagger_ui/tutorial001.py hl[3] *}
+
+...y entonces Swagger UI ya no mostrará el resaltado de sintaxis:
+
+<img src="/img/tutorial/extending-openapi/image03.png">
+
+## Cambiar el tema
+
+De la misma manera, podrías configurar el tema del resaltado de sintaxis con la clave `"syntaxHighlight.theme"` (ten en cuenta que tiene un punto en el medio):
+
+{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *}
+
+Esa configuración cambiaría el tema de color del resaltado de sintaxis:
+
+<img src="/img/tutorial/extending-openapi/image04.png">
+
+## Cambiar los parámetros predeterminados de Swagger UI
+
+FastAPI incluye algunos parámetros de configuración predeterminados apropiados para la mayoría de los casos de uso.
+
+Incluye estas configuraciones predeterminadas:
+
+{* ../../fastapi/openapi/docs.py ln[8:23] hl[17:23] *}
+
+Puedes sobrescribir cualquiera de ellos estableciendo un valor diferente en el argumento `swagger_ui_parameters`.
+
+Por ejemplo, para desactivar `deepLinking` podrías pasar estas configuraciones a `swagger_ui_parameters`:
+
+{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
+
+## Otros parámetros de Swagger UI
+
+Para ver todas las demás configuraciones posibles que puedes usar, lee la <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">documentación oficial de los parámetros de Swagger UI</a>.
+
+## Configuraciones solo de JavaScript
+
+Swagger UI también permite otras configuraciones que son objetos **solo de JavaScript** (por ejemplo, funciones de JavaScript).
+
+FastAPI también incluye estas configuraciones `presets` solo de JavaScript:
+
+```JavaScript
+presets: [
+    SwaggerUIBundle.presets.apis,
+    SwaggerUIBundle.SwaggerUIStandalonePreset
+]
+```
+
+Estos son objetos de **JavaScript**, no strings, por lo que no puedes pasarlos directamente desde código de Python.
+
+Si necesitas usar configuraciones solo de JavaScript como esas, puedes usar uno de los métodos anteriores. Sobrescribe toda la *path operation* de Swagger UI y escribe manualmente cualquier JavaScript que necesites.

docs/es/docs/how-to/custom-docs-ui-assets.md

@@ -0,0 +1,185 @@
+# Recursos Estáticos Personalizados para la Docs UI (Self-Hosting)
+
+La documentación de la API utiliza **Swagger UI** y **ReDoc**, y cada uno de estos necesita algunos archivos JavaScript y CSS.
+
+Por defecto, esos archivos se sirven desde un <abbr title="Content Delivery Network: Un servicio, normalmente compuesto de varios servidores, que proporciona archivos estáticos, como JavaScript y CSS. Se utiliza comúnmente para servir esos archivos desde el servidor más cercano al cliente, mejorando el rendimiento.">CDN</abbr>.
+
+Pero es posible personalizarlo, puedes establecer un CDN específico, o servir los archivos tú mismo.
+
+## CDN Personalizado para JavaScript y CSS
+
+Digamos que quieres usar un <abbr title="Content Delivery Network">CDN</abbr> diferente, por ejemplo, quieres usar `https://unpkg.com/`.
+
+Esto podría ser útil si, por ejemplo, vives en un país que restringe algunas URLs.
+
+### Desactiva la documentación automática
+
+El primer paso es desactivar la documentación automática, ya que por defecto, esos usan el CDN predeterminado.
+
+Para desactivarlos, establece sus URLs en `None` cuando crees tu aplicación de `FastAPI`:
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[8] *}
+
+### Incluye la documentación personalizada
+
+Ahora puedes crear las *path operations* para la documentación personalizada.
+
+Puedes reutilizar las funciones internas de FastAPI para crear las páginas HTML para la documentación, y pasarles los argumentos necesarios:
+
+* `openapi_url`: la URL donde la página HTML para la documentación puede obtener el OpenAPI esquema de tu API. Puedes usar aquí el atributo `app.openapi_url`.
+* `title`: el título de tu API.
+* `oauth2_redirect_url`: puedes usar `app.swagger_ui_oauth2_redirect_url` aquí para usar el valor predeterminado.
+* `swagger_js_url`: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivo **JavaScript**. Esta es la URL personalizada del CDN.
+* `swagger_css_url`: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivo **CSS**. Esta es la URL personalizada del CDN.
+
+Y de manera similar para ReDoc...
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[2:6,11:19,22:24,27:33] *}
+
+/// tip | Consejo
+
+La *path operation* para `swagger_ui_redirect` es una herramienta cuando utilizas OAuth2.
+
+Si integras tu API con un proveedor OAuth2, podrás autenticarte y regresar a la documentación de la API con las credenciales adquiridas. E interactuar con ella usando la autenticación real de OAuth2.
+
+Swagger UI lo manejará detrás de escena para ti, pero necesita este auxiliar de "redirección".
+
+///
+
+### Crea una *path operation* para probarlo
+
+Ahora, para poder probar que todo funciona, crea una *path operation*:
+
+{* ../../docs_src/custom_docs_ui/tutorial001.py hl[36:38] *}
+
+### Pruébalo
+
+Ahora, deberías poder ir a tu 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>, y recargar la página, cargará esos recursos desde el nuevo CDN.
+
+## Self-hosting de JavaScript y CSS para la documentación
+
+El self-hosting de JavaScript y CSS podría ser útil si, por ejemplo, necesitas que tu aplicación siga funcionando incluso offline, sin acceso a Internet, o en una red local.
+
+Aquí verás cómo servir esos archivos tú mismo, en la misma aplicación de FastAPI, y configurar la documentación para usarla.
+
+### Estructura de archivos del proyecto
+
+Supongamos que la estructura de archivos de tu proyecto se ve así:
+
+```
+.
+├── app
+│   ├── __init__.py
+│   ├── main.py
+```
+
+Ahora crea un directorio para almacenar esos archivos estáticos.
+
+Tu nueva estructura de archivos podría verse así:
+
+```
+.
+├── app
+│   ├── __init__.py
+│   ├── main.py
+└── static/
+```
+
+### Descarga los archivos
+
+Descarga los archivos estáticos necesarios para la documentación y ponlos en ese directorio `static/`.
+
+Probablemente puedas hacer clic derecho en cada enlace y seleccionar una opción similar a `Guardar enlace como...`.
+
+**Swagger UI** utiliza los archivos:
+
+* <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js" class="external-link" target="_blank">`swagger-ui-bundle.js`</a>
+* <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css" class="external-link" target="_blank">`swagger-ui.css`</a>
+
+Y **ReDoc** utiliza el archivo:
+
+* <a href="https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js" class="external-link" target="_blank">`redoc.standalone.js`</a>
+
+Después de eso, tu estructura de archivos podría verse así:
+
+```
+.
+├── app
+│   ├── __init__.py
+│   ├── main.py
+└── static
+    ├── redoc.standalone.js
+    ├── swagger-ui-bundle.js
+    └── swagger-ui.css
+```
+
+### Sirve los archivos estáticos
+
+* Importa `StaticFiles`.
+* "Monta" una instance de `StaticFiles()` en un path específico.
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[7,11] *}
+
+### Prueba los archivos estáticos
+
+Inicia tu aplicación y ve a <a href="http://127.0.0.1:8000/static/redoc.standalone.js" class="external-link" target="_blank">http://127.0.0.1:8000/static/redoc.standalone.js</a>.
+
+Deberías ver un archivo JavaScript muy largo de **ReDoc**.
+
+Podría comenzar con algo como:
+
+```JavaScript
+/*! For license information please see redoc.standalone.js.LICENSE.txt */
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")):
+...
+```
+
+Eso confirma que puedes servir archivos estáticos desde tu aplicación, y que colocaste los archivos estáticos para la documentación en el lugar correcto.
+
+Ahora podemos configurar la aplicación para usar esos archivos estáticos para la documentación.
+
+### Desactiva la documentación automática para archivos estáticos
+
+Igual que cuando usas un CDN personalizado, el primer paso es desactivar la documentación automática, ya que esos usan el CDN por defecto.
+
+Para desactivarlos, establece sus URLs en `None` cuando crees tu aplicación de `FastAPI`:
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[9] *}
+
+### Incluye la documentación personalizada para archivos estáticos
+
+Y de la misma manera que con un CDN personalizado, ahora puedes crear las *path operations* para la documentación personalizada.
+
+Nuevamente, puedes reutilizar las funciones internas de FastAPI para crear las páginas HTML para la documentación, y pasarles los argumentos necesarios:
+
+* `openapi_url`: la URL donde la página HTML para la documentación puede obtener el OpenAPI esquema de tu API. Puedes usar aquí el atributo `app.openapi_url`.
+* `title`: el título de tu API.
+* `oauth2_redirect_url`: puedes usar `app.swagger_ui_oauth2_redirect_url` aquí para usar el valor predeterminado.
+* `swagger_js_url`: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivo **JavaScript**. **Este es el que tu propia aplicación está sirviendo ahora**.
+* `swagger_css_url`: la URL donde el HTML para tu documentación de Swagger UI puede obtener el archivo **CSS**. **Este es el que tu propia aplicación está sirviendo ahora**.
+
+Y de manera similar para ReDoc...
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[2:6,14:22,25:27,30:36] *}
+
+/// tip | Consejo
+
+La *path operation* para `swagger_ui_redirect` es una herramienta cuando utilizas OAuth2.
+
+Si integras tu API con un proveedor OAuth2, podrás autenticarte y regresar a la documentación de la API con las credenciales adquiridas. Y interactuar con ella usando la autenticación real de OAuth2.
+
+Swagger UI lo manejará detrás de escena para ti, pero necesita este auxiliar de "redirección".
+
+///
+
+### Crea una *path operation* para probar archivos estáticos
+
+Ahora, para poder probar que todo funciona, crea una *path operation*:
+
+{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *}
+
+### Prueba la UI de Archivos Estáticos
+
+Ahora, deberías poder desconectar tu WiFi, ir a tu 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>, y recargar la página.
+
+E incluso sin Internet, podrás ver la documentación de tu API e interactuar con ella.

docs/es/docs/how-to/custom-request-and-route.md

@@ -0,0 +1,109 @@
+# Clase personalizada de Request y APIRoute
+
+En algunos casos, puede que quieras sobrescribir la lógica utilizada por las clases `Request` y `APIRoute`.
+
+En particular, esta puede ser una buena alternativa a la lógica en un middleware.
+
+Por ejemplo, si quieres leer o manipular el request body antes de que sea procesado por tu aplicación.
+
+/// danger | Advertencia
+
+Esta es una funcionalidad "avanzada".
+
+Si apenas estás comenzando con **FastAPI**, quizás quieras saltar esta sección.
+
+///
+
+## Casos de uso
+
+Algunos casos de uso incluyen:
+
+* Convertir cuerpos de requests no-JSON a JSON (por ejemplo, <a href="https://msgpack.org/index.html" class="external-link" target="_blank">`msgpack`</a>).
+* Descomprimir cuerpos de requests comprimidos con gzip.
+* Registrar automáticamente todos los request bodies.
+
+## Manejo de codificaciones personalizadas de request body
+
+Veamos cómo hacer uso de una subclase personalizada de `Request` para descomprimir requests gzip.
+
+Y una subclase de `APIRoute` para usar esa clase de request personalizada.
+
+### Crear una clase personalizada `GzipRequest`
+
+/// tip | Consejo
+
+Este es un ejemplo sencillo para demostrar cómo funciona. Si necesitas soporte para Gzip, puedes usar el [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank} proporcionado.
+
+///
+
+Primero, creamos una clase `GzipRequest`, que sobrescribirá el método `Request.body()` para descomprimir el cuerpo si hay un header apropiado.
+
+Si no hay `gzip` en el header, no intentará descomprimir el cuerpo.
+
+De esa manera, la misma clase de ruta puede manejar requests comprimidos con gzip o no comprimidos.
+
+{* ../../docs_src/custom_request_and_route/tutorial001.py hl[8:15] *}
+
+### Crear una clase personalizada `GzipRoute`
+
+A continuación, creamos una subclase personalizada de `fastapi.routing.APIRoute` que hará uso de `GzipRequest`.
+
+Esta vez, sobrescribirá el método `APIRoute.get_route_handler()`.
+
+Este método devuelve una función. Y esa función es la que recibirá un request y devolverá un response.
+
+Aquí lo usamos para crear un `GzipRequest` a partir del request original.
+
+{* ../../docs_src/custom_request_and_route/tutorial001.py hl[18:26] *}
+
+/// note | Detalles técnicos
+
+Un `Request` tiene un atributo `request.scope`, que es simplemente un `dict` de Python que contiene los metadatos relacionados con el request.
+
+Un `Request` también tiene un `request.receive`, que es una función para "recibir" el cuerpo del request.
+
+El `dict` `scope` y la función `receive` son ambos parte de la especificación ASGI.
+
+Y esas dos cosas, `scope` y `receive`, son lo que se necesita para crear una nueva *Request instance*.
+
+Para aprender más sobre el `Request`, revisa <a href="https://www.starlette.dev/requests/" class="external-link" target="_blank">la documentación de Starlette sobre Requests</a>.
+
+///
+
+La única cosa que la función devuelta por `GzipRequest.get_route_handler` hace diferente es convertir el `Request` en un `GzipRequest`.
+
+Haciendo esto, nuestro `GzipRequest` se encargará de descomprimir los datos (si es necesario) antes de pasarlos a nuestras *path operations*.
+
+Después de eso, toda la lógica de procesamiento es la misma.
+
+Pero debido a nuestros cambios en `GzipRequest.body`, el request body se descomprimirá automáticamente cuando sea cargado por **FastAPI** si es necesario.
+
+## Accediendo al request body en un manejador de excepciones
+
+/// tip | Consejo
+
+Para resolver este mismo problema, probablemente sea mucho más fácil usar el `body` en un manejador personalizado para `RequestValidationError` ([Manejo de Errores](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
+
+Pero este ejemplo sigue siendo válido y muestra cómo interactuar con los componentes internos.
+
+///
+
+También podemos usar este mismo enfoque para acceder al request body en un manejador de excepciones.
+
+Todo lo que necesitamos hacer es manejar el request dentro de un bloque `try`/`except`:
+
+{* ../../docs_src/custom_request_and_route/tutorial002.py hl[13,15] *}
+
+Si ocurre una excepción, la `Request instance` aún estará en el alcance, así que podemos leer y hacer uso del request body cuando manejamos el error:
+
+{* ../../docs_src/custom_request_and_route/tutorial002.py hl[16:18] *}
+
+## Clase personalizada `APIRoute` en un router
+
+También puedes establecer el parámetro `route_class` de un `APIRouter`:
+
+{* ../../docs_src/custom_request_and_route/tutorial003.py hl[26] *}
+
+En este ejemplo, las *path operations* bajo el `router` usarán la clase personalizada `TimedRoute`, y tendrán un header `X-Response-Time` extra en el response con el tiempo que tomó generar el response:
+
+{* ../../docs_src/custom_request_and_route/tutorial003.py hl[13:20] *}

docs/es/docs/how-to/extending-openapi.md

@@ -0,0 +1,80 @@
+# Extender OpenAPI
+
+Hay algunos casos en los que podrías necesitar modificar el esquema de OpenAPI generado.
+
+En esta sección verás cómo hacerlo.
+
+## El proceso normal
+
+El proceso normal (por defecto) es el siguiente.
+
+Una aplicación (instance) de `FastAPI` tiene un método `.openapi()` que se espera que devuelva el esquema de OpenAPI.
+
+Como parte de la creación del objeto de la aplicación, se registra una *path operation* para `/openapi.json` (o para lo que sea que configures tu `openapi_url`).
+
+Simplemente devuelve un response JSON con el resultado del método `.openapi()` de la aplicación.
+
+Por defecto, lo que hace el método `.openapi()` es revisar la propiedad `.openapi_schema` para ver si tiene contenido y devolverlo.
+
+Si no lo tiene, lo genera usando la función de utilidad en `fastapi.openapi.utils.get_openapi`.
+
+Y esa función `get_openapi()` recibe como parámetros:
+
+* `title`: El título de OpenAPI, mostrado en la documentación.
+* `version`: La versión de tu API, por ejemplo `2.5.0`.
+* `openapi_version`: La versión de la especificación OpenAPI utilizada. Por defecto, la más reciente: `3.1.0`.
+* `summary`: Un breve resumen de la API.
+* `description`: La descripción de tu API, esta puede incluir markdown y se mostrará en la documentación.
+* `routes`: Una list de rutas, estas son cada una de las *path operations* registradas. Se toman de `app.routes`.
+
+/// info | Información
+
+El parámetro `summary` está disponible en OpenAPI 3.1.0 y versiones superiores, soportado por FastAPI 0.99.0 y superiores.
+
+///
+
+## Sobrescribir los valores por defecto
+
+Usando la información anterior, puedes usar la misma función de utilidad para generar el esquema de OpenAPI y sobrescribir cada parte que necesites.
+
+Por ejemplo, vamos a añadir <a href="https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo" class="external-link" target="_blank">la extensión OpenAPI de ReDoc para incluir un logo personalizado</a>.
+
+### **FastAPI** normal
+
+Primero, escribe toda tu aplicación **FastAPI** como normalmente:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[1,4,7:9] *}
+
+### Generar el esquema de OpenAPI
+
+Luego, usa la misma función de utilidad para generar el esquema de OpenAPI, dentro de una función `custom_openapi()`:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[2,15:21] *}
+
+### Modificar el esquema de OpenAPI
+
+Ahora puedes añadir la extensión de ReDoc, agregando un `x-logo` personalizado al "objeto" `info` en el esquema de OpenAPI:
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[22:24] *}
+
+### Cachear el esquema de OpenAPI
+
+Puedes usar la propiedad `.openapi_schema` como un "cache", para almacenar tu esquema generado.
+
+De esa forma, tu aplicación no tendrá que generar el esquema cada vez que un usuario abra la documentación de tu API.
+
+Se generará solo una vez, y luego se usará el mismo esquema cacheado para las siguientes requests.
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[13:14,25:26] *}
+
+### Sobrescribir el método
+
+Ahora puedes reemplazar el método `.openapi()` por tu nueva función.
+
+{* ../../docs_src/extending_openapi/tutorial001.py hl[29] *}
+
+### Revisa
+
+Una vez que vayas a <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a> verás que estás usando tu logo personalizado (en este ejemplo, el logo de **FastAPI**):
+
+<img src="/img/tutorial/extending-openapi/image01.png">

docs/es/docs/how-to/general.md

@@ -0,0 +1,39 @@
+# General - Cómo Hacer - Recetas
+
+Aquí tienes varias indicaciones hacia otros lugares en la documentación, para preguntas generales o frecuentes.
+
+## Filtrar Datos - Seguridad
+
+Para asegurarte de que no devuelves más datos de los que deberías, lee la documentación para [Tutorial - Modelo de Response - Tipo de Retorno](../tutorial/response-model.md){.internal-link target=_blank}.
+
+## Etiquetas de Documentación - OpenAPI
+
+Para agregar etiquetas a tus *path operations*, y agruparlas en la interfaz de usuario de la documentación, lee la documentación para [Tutorial - Configuraciones de Path Operation - Etiquetas](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}.
+
+## Resumen y Descripción de Documentación - OpenAPI
+
+Para agregar un resumen y descripción a tus *path operations*, y mostrarlos en la interfaz de usuario de la documentación, lee la documentación para [Tutorial - Configuraciones de Path Operation - Resumen y Descripción](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}.
+
+## Documentación de Descripción de Response - OpenAPI
+
+Para definir la descripción del response, mostrada en la interfaz de usuario de la documentación, lee la documentación para [Tutorial - Configuraciones de Path Operation - Descripción del Response](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}.
+
+## Documentar la Deprecación de una *Path Operation* - OpenAPI
+
+Para deprecar una *path operation*, y mostrarla en la interfaz de usuario de la documentación, lee la documentación para [Tutorial - Configuraciones de Path Operation - Deprecación](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}.
+
+## Convertir cualquier Dato a Compatible con JSON
+
+Para convertir cualquier dato a compatible con JSON, lee la documentación para [Tutorial - Codificador Compatible con JSON](../tutorial/encoder.md){.internal-link target=_blank}.
+
+## Metadatos OpenAPI - Documentación
+
+Para agregar metadatos a tu esquema de OpenAPI, incluyendo una licencia, versión, contacto, etc, lee la documentación para [Tutorial - Metadatos y URLs de Documentación](../tutorial/metadata.md){.internal-link target=_blank}.
+
+## URL Personalizada de OpenAPI
+
+Para personalizar la URL de OpenAPI (o eliminarla), lee la documentación para [Tutorial - Metadatos y URLs de Documentación](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}.
+
+## URLs de Documentación de OpenAPI
+
+Para actualizar las URLs usadas para las interfaces de usuario de documentación generadas automáticamente, lee la documentación para [Tutorial - Metadatos y URLs de Documentación](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}.

docs/es/docs/how-to/graphql.md

@@ -0,0 +1,60 @@
+# GraphQL
+
+Como **FastAPI** se basa en el estándar **ASGI**, es muy fácil integrar cualquier paquete de **GraphQL** que también sea compatible con ASGI.
+
+Puedes combinar las *path operations* normales de FastAPI con GraphQL en la misma aplicación.
+
+/// tip | Consejo
+
+**GraphQL** resuelve algunos casos de uso muy específicos.
+
+Tiene **ventajas** y **desventajas** en comparación con las **APIs web** comunes.
+
+Asegúrate de evaluar si los **beneficios** para tu caso de uso compensan los **inconvenientes**. 🤓
+
+///
+
+## Paquetes de GraphQL
+
+Aquí algunos de los paquetes de **GraphQL** que tienen soporte **ASGI**. Podrías usarlos con **FastAPI**:
+
+* <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a> 🍓
+    * Con <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">documentación para FastAPI</a>
+* <a href="https://ariadnegraphql.org/" class="external-link" target="_blank">Ariadne</a>
+    * Con <a href="https://ariadnegraphql.org/docs/fastapi-integration" class="external-link" target="_blank">documentación para FastAPI</a>
+* <a href="https://tartiflette.io/" class="external-link" target="_blank">Tartiflette</a>
+    * Con <a href="https://tartiflette.github.io/tartiflette-asgi/" class="external-link" target="_blank">Tartiflette ASGI</a> para proporcionar integración con ASGI
+* <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a>
+    * Con <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a>
+
+## GraphQL con Strawberry
+
+Si necesitas o quieres trabajar con **GraphQL**, <a href="https://strawberry.rocks/" class="external-link" target="_blank">**Strawberry**</a> es el paquete **recomendado** ya que tiene un diseño muy similar al diseño de **FastAPI**, todo basado en **anotaciones de tipos**.
+
+Dependiendo de tu caso de uso, podrías preferir usar un paquete diferente, pero si me preguntas, probablemente te sugeriría probar **Strawberry**.
+
+Aquí tienes una pequeña vista previa de cómo podrías integrar Strawberry con FastAPI:
+
+{* ../../docs_src/graphql/tutorial001.py hl[3,22,25:26] *}
+
+Puedes aprender más sobre Strawberry en la <a href="https://strawberry.rocks/" class="external-link" target="_blank">documentación de Strawberry</a>.
+
+Y también la documentación sobre <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">Strawberry con FastAPI</a>.
+
+## `GraphQLApp` viejo de Starlette
+
+Las versiones anteriores de Starlette incluían una clase `GraphQLApp` para integrar con <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a>.
+
+Fue deprecada de Starlette, pero si tienes código que lo usaba, puedes fácilmente **migrar** a <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a>, que cubre el mismo caso de uso y tiene una **interfaz casi idéntica**.
+
+/// tip | Consejo
+
+Si necesitas GraphQL, aún te recomendaría revisar <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a>, ya que se basa en anotaciones de tipos en lugar de clases y tipos personalizados.
+
+///
+
+## Aprende Más
+
+Puedes aprender más sobre **GraphQL** en la <a href="https://graphql.org/" class="external-link" target="_blank">documentación oficial de GraphQL</a>.
+
+También puedes leer más sobre cada uno de esos paquetes descritos arriba en sus enlaces.

docs/es/docs/how-to/index.md

@@ -0,0 +1,13 @@
+# How To - Recetas
+
+Aquí verás diferentes recetas o guías de "cómo hacer" para **varios temas**.
+
+La mayoría de estas ideas serían más o menos **independientes**, y en la mayoría de los casos solo deberías estudiarlas si aplican directamente a **tu proyecto**.
+
+Si algo parece interesante y útil para tu proyecto, adelante y revísalo, pero de lo contrario, probablemente puedas simplemente omitirlas.
+
+/// tip | Consejo
+
+Si quieres **aprender FastAPI** de una manera estructurada (recomendado), ve y lee el [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} capítulo por capítulo.
+
+///

docs/es/docs/how-to/separate-openapi-schemas.md

@@ -0,0 +1,104 @@
+# Separación de Esquemas OpenAPI para Entrada y Salida o No
+
+Al usar **Pydantic v2**, el OpenAPI generado es un poco más exacto y **correcto** que antes. 😎
+
+De hecho, en algunos casos, incluso tendrá **dos JSON Schemas** en OpenAPI para el mismo modelo Pydantic, para entrada y salida, dependiendo de si tienen **valores por defecto**.
+
+Veamos cómo funciona eso y cómo cambiarlo si necesitas hacerlo.
+
+## Modelos Pydantic para Entrada y Salida
+
+Digamos que tienes un modelo Pydantic con valores por defecto, como este:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}
+
+### Modelo para Entrada
+
+Si usas este modelo como entrada, como aquí:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *}
+
+...entonces el campo `description` **no será requerido**. Porque tiene un valor por defecto de `None`.
+
+### Modelo de Entrada en la Documentación
+
+Puedes confirmar eso en la documentación, el campo `description` no tiene un **asterisco rojo**, no está marcado como requerido:
+
+<div class="screenshot">
+<img src="/img/tutorial/separate-openapi-schemas/image01.png">
+</div>
+
+### Modelo para Salida
+
+Pero si usas el mismo modelo como salida, como aquí:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py hl[19] *}
+
+...entonces, porque `description` tiene un valor por defecto, si **no devuelves nada** para ese campo, aún tendrá ese **valor por defecto**.
+
+### Modelo para Datos de Response de Salida
+
+Si interactúas con la documentación y revisas el response, aunque el código no agregó nada en uno de los campos `description`, el response JSON contiene el valor por defecto (`null`):
+
+<div class="screenshot">
+<img src="/img/tutorial/separate-openapi-schemas/image02.png">
+</div>
+
+Esto significa que **siempre tendrá un valor**, solo que a veces el valor podría ser `None` (o `null` en JSON).
+
+Eso significa que, los clientes que usan tu API no tienen que comprobar si el valor existe o no, pueden **asumir que el campo siempre estará allí**, pero solo que en algunos casos tendrá el valor por defecto de `None`.
+
+La forma de describir esto en OpenAPI es marcar ese campo como **requerido**, porque siempre estará allí.
+
+Debido a eso, el JSON Schema para un modelo puede ser diferente dependiendo de si se usa para **entrada o salida**:
+
+* para **entrada** el `description` **no será requerido**
+* para **salida** será **requerido** (y posiblemente `None`, o en términos de JSON, `null`)
+
+### Modelo para Salida en la Documentación
+
+También puedes revisar el modelo de salida en la documentación, **ambos** `name` y `description` están marcados como **requeridos** con un **asterisco rojo**:
+
+<div class="screenshot">
+<img src="/img/tutorial/separate-openapi-schemas/image03.png">
+</div>
+
+### Modelo para Entrada y Salida en la Documentación
+
+Y si revisas todos los esquemas disponibles (JSON Schemas) en OpenAPI, verás que hay dos, uno `Item-Input` y uno `Item-Output`.
+
+Para `Item-Input`, `description` **no es requerido**, no tiene un asterisco rojo.
+
+Pero para `Item-Output`, `description` **es requerido**, tiene un asterisco rojo.
+
+<div class="screenshot">
+<img src="/img/tutorial/separate-openapi-schemas/image04.png">
+</div>
+
+Con esta funcionalidad de **Pydantic v2**, la documentación de tu API es más **precisa**, y si tienes clientes y SDKs autogenerados, también serán más precisos, con una mejor **experiencia para desarrolladores** y consistencia. 🎉
+
+## No Separar Esquemas
+
+Ahora, hay algunos casos donde podrías querer tener el **mismo esquema para entrada y salida**.
+
+Probablemente el caso principal para esto es si ya tienes algún código cliente/SDKs autogenerado y no quieres actualizar todo el código cliente/SDKs autogenerado aún, probablemente querrás hacerlo en algún momento, pero tal vez no ahora.
+
+En ese caso, puedes desactivar esta funcionalidad en **FastAPI**, con el parámetro `separate_input_output_schemas=False`.
+
+/// info | Información
+
+El soporte para `separate_input_output_schemas` fue agregado en FastAPI `0.102.0`. 🤓
+
+///
+
+{* ../../docs_src/separate_openapi_schemas/tutorial002_py310.py hl[10] *}
+
+### Mismo Esquema para Modelos de Entrada y Salida en la Documentación
+
+Y ahora habrá un único esquema para entrada y salida para el modelo, solo `Item`, y tendrá `description` como **no requerido**:
+
+<div class="screenshot">
+<img src="/img/tutorial/separate_openapi_schemas/image05.png">
+</div>
+
+Este es el mismo comportamiento que en Pydantic v1. 🤓

docs/es/docs/how-to/testing-database.md

@@ -0,0 +1,7 @@
+# Probando una Base de Datos
+
+Puedes estudiar sobre bases de datos, SQL y SQLModel en la <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">documentación de SQLModel</a>. 🤓
+
+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>. ✨
+
+Ese tutorial incluye una sección sobre <a href="https://sqlmodel.tiangolo.com/tutorial/fastapi/tests/" class="external-link" target="_blank">cómo probar bases de datos SQL</a>. 😎

docs/es/docs/index.md

@@ -0,0 +1,496 @@
+# FastAPI
+
+<style>
+.md-content .md-typeset h1 { display: none; }
+</style>
+
+<p align="center">
+  <a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a>
+</p>
+<p align="center">
+    <em>FastAPI framework, alto rendimiento, fácil de aprender, rápido de programar, listo para producción</em>
+</p>
+<p align="center">
+<a href="https://github.com/fastapi/fastapi/actions?query=workflow%3ATest+event%3Apush+branch%3Amaster" target="_blank">
+    <img src="https://github.com/fastapi/fastapi/actions/workflows/test.yml/badge.svg?event=push&branch=master" alt="Test">
+</a>
+<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/fastapi/fastapi" target="_blank">
+    <img src="https://coverage-badge.samuelcolvin.workers.dev/fastapi/fastapi.svg" alt="Coverage">
+</a>
+<a href="https://pypi.org/project/fastapi" target="_blank">
+    <img src="https://img.shields.io/pypi/v/fastapi?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+<a href="https://pypi.org/project/fastapi" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/fastapi.svg?color=%2334D058" alt="Supported Python versions">
+</a>
+</p>
+
+---
+
+**Documentación**: <a href="https://fastapi.tiangolo.com" target="_blank">https://fastapi.tiangolo.com</a>
+
+**Código Fuente**: <a href="https://github.com/fastapi/fastapi" target="_blank">https://github.com/fastapi/fastapi</a>
+
+---
+
+FastAPI es un framework web moderno, rápido (de alto rendimiento), para construir APIs con Python basado en las anotaciones de tipos estándar de Python.
+
+Las características clave son:
+
+* **Rápido**: Muy alto rendimiento, a la par con **NodeJS** y **Go** (gracias a Starlette y Pydantic). [Uno de los frameworks Python más rápidos disponibles](#performance).
+* **Rápido de programar**: Aumenta la velocidad para desarrollar funcionalidades en aproximadamente un 200% a 300%. *
+* **Menos bugs**: Reduce en aproximadamente un 40% los errores inducidos por humanos (desarrolladores). *
+* **Intuitivo**: Gran soporte para editores. <abbr title="también conocido como autocompletado, IntelliSense">Autocompletado</abbr> en todas partes. Menos tiempo depurando.
+* **Fácil**: Diseñado para ser fácil de usar y aprender. Menos tiempo leyendo documentación.
+* **Corto**: Minimiza la duplicación de código. Múltiples funcionalidades desde cada declaración de parámetro. Menos bugs.
+* **Robusto**: Obtén código listo para producción. Con documentación interactiva automática.
+* **Basado en estándares**: Basado (y completamente compatible) con los estándares abiertos para APIs: <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> (anteriormente conocido como Swagger) y <a href="https://json-schema.org/" class="external-link" target="_blank">JSON Schema</a>.
+
+<small>* estimación basada en pruebas con un equipo de desarrollo interno, construyendo aplicaciones de producción.</small>
+
+## Sponsors
+
+<!-- sponsors -->
+
+{% if sponsors %}
+{% for sponsor in sponsors.gold -%}
+<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a>
+{% endfor -%}
+{%- for sponsor in sponsors.silver -%}
+<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a>
+{% endfor %}
+{% endif %}
+
+<!-- /sponsors -->
+
+<a href="https://fastapi.tiangolo.com/fastapi-people/#sponsors" class="external-link" target="_blank">Otros sponsors</a>
+
+## Opiniones
+
+"_[...] Estoy usando **FastAPI** un montón estos días. [...] De hecho, estoy planeando usarlo para todos los servicios de **ML de mi equipo en Microsoft**. Algunos de ellos se están integrando en el núcleo del producto **Windows** y algunos productos de **Office**._"
+
+<div style="text-align: right; margin-right: 10%;">Kabir Khan - <strong>Microsoft</strong> <a href="https://github.com/fastapi/fastapi/pull/26" target="_blank"><small>(ref)</small></a></div>
+
+---
+
+"_Adoptamos el paquete **FastAPI** para crear un servidor **REST** que pueda ser consultado para obtener **predicciones**. [para Ludwig]_"
+
+<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, y Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/" target="_blank"><small>(ref)</small></a></div>
+
+---
+
+"_**Netflix** se complace en anunciar el lanzamiento de código abierto de nuestro framework de orquestación de **gestión de crisis**: **Dispatch**! [construido con **FastAPI**]_"
+
+<div style="text-align: right; margin-right: 10%;">Kevin Glisson, Marc Vilanova, Forest Monsen - <strong>Netflix</strong> <a href="https://netflixtechblog.com/introducing-dispatch-da4b8a2a8072" target="_blank"><small>(ref)</small></a></div>
+
+---
+
+"_Estoy súper emocionado con **FastAPI**. ¡Es tan divertido!_"
+
+<div style="text-align: right; margin-right: 10%;">Brian Okken - <strong><a href="https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855" target="_blank">host del podcast Python Bytes</a></strong> <a href="https://x.com/brianokken/status/1112220079972728832" target="_blank"><small>(ref)</small></a></div>
+
+---
+
+"_Honestamente, lo que has construido parece súper sólido y pulido. En muchos aspectos, es lo que quería que **Hug** fuera; es realmente inspirador ver a alguien construir eso._"
+
+<div style="text-align: right; margin-right: 10%;">Timothy Crosley - <strong><a href="https://github.com/hugapi/hug" target="_blank">creador de Hug</a></strong> <a href="https://news.ycombinator.com/item?id=19455465" target="_blank"><small>(ref)</small></a></div>
+
+---
+
+"_Si estás buscando aprender un **framework moderno** para construir APIs REST, échale un vistazo a **FastAPI** [...] Es rápido, fácil de usar y fácil de aprender [...]_"
+
+"_Nos hemos cambiado a **FastAPI** para nuestras **APIs** [...] Creo que te gustará [...]_"
+
+<div style="text-align: right; margin-right: 10%;">Ines Montani - Matthew Honnibal - <strong><a href="https://explosion.ai" target="_blank">fundadores de Explosion AI</a> - <a href="https://spacy.io" target="_blank">creadores de spaCy</a></strong> <a href="https://x.com/_inesmontani/status/1144173225322143744" target="_blank"><small>(ref)</small></a> - <a href="https://x.com/honnibal/status/1144031421859655680" target="_blank"><small>(ref)</small></a></div>
+
+---
+
+"_Si alguien está buscando construir una API de Python para producción, altamente recomendaría **FastAPI**. Está **hermosamente diseñado**, es **simple de usar** y **altamente escalable**, se ha convertido en un **componente clave** en nuestra estrategia de desarrollo API primero y está impulsando muchas automatizaciones y servicios como nuestro Ingeniero Virtual TAC._"
+
+<div style="text-align: right; margin-right: 10%;">Deon Pillsbury - <strong>Cisco</strong> <a href="https://www.linkedin.com/posts/deonpillsbury_cisco-cx-python-activity-6963242628536487936-trAp/" target="_blank"><small>(ref)</small></a></div>
+
+---
+
+## **Typer**, el FastAPI de las CLIs
+
+<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a>
+
+Si estás construyendo una aplicación de <abbr title="Interfaz de Línea de Comandos">CLI</abbr> para ser usada en el terminal en lugar de una API web, revisa <a href="https://typer.tiangolo.com/" class="external-link" target="_blank">**Typer**</a>.
+
+**Typer** es el hermano pequeño de FastAPI. Y está destinado a ser el **FastAPI de las CLIs**. ⌨️ 🚀
+
+## Requisitos
+
+FastAPI se apoya en hombros de gigantes:
+
+* <a href="https://www.starlette.dev/" class="external-link" target="_blank">Starlette</a> para las partes web.
+* <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> para las partes de datos.
+
+## Instalación
+
+Crea y activa un <a href="https://fastapi.tiangolo.com/virtual-environments/" class="external-link" target="_blank">entorno virtual</a> y luego instala FastAPI:
+
+<div class="termy">
+
+```console
+$ pip install "fastapi[standard]"
+
+---> 100%
+```
+
+</div>
+
+**Nota**: Asegúrate de poner `"fastapi[standard]"` entre comillas para asegurar que funcione en todas las terminales.
+
+## Ejemplo
+
+### Créalo
+
+* Crea un archivo `main.py` con:
+
+```Python
+from typing import Union
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+    return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: Union[str, None] = None):
+    return {"item_id": item_id, "q": q}
+```
+
+<details markdown="1">
+<summary>O usa <code>async def</code>...</summary>
+
+Si tu código usa `async` / `await`, usa `async def`:
+
+```Python hl_lines="9  14"
+from typing import Union
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+async def read_root():
+    return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int, q: Union[str, None] = None):
+    return {"item_id": item_id, "q": q}
+```
+
+**Nota**:
+
+Si no lo sabes, revisa la sección _"¿Con prisa?"_ sobre <a href="https://fastapi.tiangolo.com/async/#in-a-hurry" target="_blank">`async` y `await` en la documentación</a>.
+
+</details>
+
+### Córrelo
+
+Corre el servidor con:
+
+<div class="termy">
+
+```console
+$ fastapi dev main.py
+
+ ╭────────── FastAPI CLI - Development mode ───────────╮
+ │                                                     │
+ │  Serving at: http://127.0.0.1:8000                  │
+ │                                                     │
+ │  API docs: http://127.0.0.1:8000/docs               │
+ │                                                     │
+ │  Running in development mode, for production use:   │
+ │                                                     │
+ │  fastapi run                                        │
+ │                                                     │
+ ╰─────────────────────────────────────────────────────╯
+
+INFO:     Will watch for changes in these directories: ['/home/user/code/awesomeapp']
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [2248755] using WatchFiles
+INFO:     Started server process [2248757]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+```
+
+</div>
+
+<details markdown="1">
+<summary>Acerca del comando <code>fastapi dev main.py</code>...</summary>
+
+El comando `fastapi dev` lee tu archivo `main.py`, detecta la app **FastAPI** en él y arranca un servidor usando <a href="https://www.uvicorn.dev" class="external-link" target="_blank">Uvicorn</a>.
+
+Por defecto, `fastapi dev` comenzará con auto-recarga habilitada para el desarrollo local.
+
+Puedes leer más sobre esto en la <a href="https://fastapi.tiangolo.com/fastapi-cli/" target="_blank">documentación del CLI de FastAPI</a>.
+
+</details>
+
+### Revísalo
+
+Abre tu navegador en <a href="http://127.0.0.1:8000/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>.
+
+Verás el response JSON como:
+
+```JSON
+{"item_id": 5, "q": "somequery"}
+```
+
+Ya creaste una API que:
+
+* Recibe requests HTTP en los _paths_ `/` y `/items/{item_id}`.
+* Ambos _paths_ toman _operaciones_ `GET` (también conocidas como métodos HTTP).
+* El _path_ `/items/{item_id}` tiene un _parámetro de path_ `item_id` que debe ser un `int`.
+* El _path_ `/items/{item_id}` tiene un _parámetro de query_ `q` opcional que es un `str`.
+
+### Documentación interactiva de la API
+
+Ahora ve a <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 interactiva automática de la API (proporcionada por <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>):
+
+![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png)
+
+### Documentación de API Alternativa
+
+Y ahora, ve a <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
+
+Verás la documentación alternativa automática (proporcionada por <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>):
+
+![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
+
+## Actualización del Ejemplo
+
+Ahora modifica el archivo `main.py` para recibir un body desde un request `PUT`.
+
+Declara el body usando tipos estándar de Python, gracias a Pydantic.
+
+```Python hl_lines="4  9-12  25-27"
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+    name: str
+    price: float
+    is_offer: Union[bool, None] = None
+
+
+@app.get("/")
+def read_root():
+    return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: Union[str, None] = None):
+    return {"item_id": item_id, "q": q}
+
+
+@app.put("/items/{item_id}")
+def update_item(item_id: int, item: Item):
+    return {"item_name": item.name, "item_id": item_id}
+```
+
+El servidor `fastapi dev` debería recargarse automáticamente.
+
+### Actualización de la Documentación Interactiva de la API
+
+Ahora ve a <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
+
+* La documentación interactiva de la API se actualizará automáticamente, incluyendo el nuevo body:
+
+![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png)
+
+* Haz clic en el botón "Try it out", te permite llenar los parámetros e interactuar directamente con la API:
+
+![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png)
+
+* Luego haz clic en el botón "Execute", la interfaz de usuario se comunicará con tu API, enviará los parámetros, obtendrá los resultados y los mostrará en la pantalla:
+
+![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png)
+
+### Actualización de la Documentación Alternativa de la API
+
+Y ahora, ve a <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
+
+* La documentación alternativa también reflejará el nuevo parámetro de query y body:
+
+![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png)
+
+### Resumen
+
+En resumen, declaras **una vez** los tipos de parámetros, body, etc. como parámetros de función.
+
+Lo haces con tipos estándar modernos de Python.
+
+No tienes que aprender una nueva sintaxis, los métodos o clases de un paquete específico, etc.
+
+Solo **Python** estándar.
+
+Por ejemplo, para un `int`:
+
+```Python
+item_id: int
+```
+
+o para un modelo `Item` más complejo:
+
+```Python
+item: Item
+```
+
+...y con esa única declaración obtienes:
+
+* Soporte para editores, incluyendo:
+    * Autocompletado.
+    * Chequeo de tipos.
+* Validación de datos:
+    * Errores automáticos y claros cuando los datos son inválidos.
+    * Validación incluso para objetos JSON profundamente anidados.
+* <abbr title="también conocido como: serialización, parsing, marshalling">Conversión</abbr> de datos de entrada: de la red a los datos y tipos de Python. Leyendo desde:
+    * JSON.
+    * Parámetros de path.
+    * Parámetros de query.
+    * Cookies.
+    * Headers.
+    * Forms.
+    * Archivos.
+* <abbr title="también conocido como: serialización, parsing, marshalling">Conversión</abbr> de datos de salida: convirtiendo de datos y tipos de Python a datos de red (como JSON):
+    * Convertir tipos de Python (`str`, `int`, `float`, `bool`, `list`, etc).
+    * Objetos `datetime`.
+    * Objetos `UUID`.
+    * Modelos de base de datos.
+    * ...y muchos más.
+* Documentación interactiva automática de la API, incluyendo 2 interfaces de usuario alternativas:
+    * Swagger UI.
+    * ReDoc.
+
+---
+
+Volviendo al ejemplo de código anterior, **FastAPI**:
+
+* Validará que haya un `item_id` en el path para requests `GET` y `PUT`.
+* Validará que el `item_id` sea del tipo `int` para requests `GET` y `PUT`.
+    * Si no lo es, el cliente verá un error útil y claro.
+* Comprobará si hay un parámetro de query opcional llamado `q` (como en `http://127.0.0.1:8000/items/foo?q=somequery`) para requests `GET`.
+    * Como el parámetro `q` está declarado con `= None`, es opcional.
+    * Sin el `None` sería requerido (como lo es el body en el caso con `PUT`).
+* Para requests `PUT` a `/items/{item_id}`, leerá el body como JSON:
+    * Comprobará que tiene un atributo requerido `name` que debe ser un `str`.
+    * Comprobará que tiene un atributo requerido `price` que debe ser un `float`.
+    * Comprobará que tiene un atributo opcional `is_offer`, que debe ser un `bool`, si está presente.
+    * Todo esto también funcionaría para objetos JSON profundamente anidados.
+* Convertirá de y a JSON automáticamente.
+* Documentará todo con OpenAPI, que puede ser usado por:
+    * Sistemas de documentación interactiva.
+    * Sistemas de generación automática de código cliente, para muchos lenguajes.
+* Proporcionará 2 interfaces web de documentación interactiva directamente.
+
+---
+
+Solo tocamos los conceptos básicos, pero ya te haces una idea de cómo funciona todo.
+
+Intenta cambiar la línea con:
+
+```Python
+    return {"item_name": item.name, "item_id": item_id}
+```
+
+...desde:
+
+```Python
+        ... "item_name": item.name ...
+```
+
+...a:
+
+```Python
+        ... "item_price": item.price ...
+```
+
+...y observa cómo tu editor autocompleta los atributos y conoce sus tipos:
+
+![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png)
+
+Para un ejemplo más completo incluyendo más funcionalidades, ve al <a href="https://fastapi.tiangolo.com/tutorial/">Tutorial - Guía del Usuario</a>.
+
+**Alerta de spoilers**: el tutorial - guía del usuario incluye:
+
+* Declaración de **parámetros** desde otros lugares diferentes como: **headers**, **cookies**, **campos de formulario** y **archivos**.
+* Cómo establecer **restricciones de validación** como `maximum_length` o `regex`.
+* Un sistema de **<abbr title="también conocido como componentes, recursos, proveedores, servicios, inyectables">Inyección de Dependencias</abbr>** muy poderoso y fácil de usar.
+* Seguridad y autenticación, incluyendo soporte para **OAuth2** con **tokens JWT** y autenticación **HTTP Basic**.
+* Técnicas más avanzadas (pero igualmente fáciles) para declarar **modelos JSON profundamente anidados** (gracias a Pydantic).
+* Integración con **GraphQL** usando <a href="https://strawberry.rocks" class="external-link" target="_blank">Strawberry</a> y otros paquetes.
+* Muchas funcionalidades extra (gracias a Starlette) como:
+    * **WebSockets**
+    * pruebas extremadamente fáciles basadas en HTTPX y `pytest`
+    * **CORS**
+    * **Sesiones de Cookies**
+    * ...y más.
+
+## Rendimiento
+
+Benchmarks independientes de TechEmpower muestran aplicaciones **FastAPI** ejecutándose bajo Uvicorn como <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">uno de los frameworks Python más rápidos disponibles</a>, solo por debajo de Starlette y Uvicorn (usados internamente por FastAPI). (*)
+
+Para entender más sobre esto, ve la sección <a href="https://fastapi.tiangolo.com/benchmarks/" class="internal-link" target="_blank">Benchmarks</a>.
+
+## Dependencias
+
+FastAPI depende de Pydantic y Starlette.
+
+### Dependencias `standard`
+
+Cuando instalas FastAPI con `pip install "fastapi[standard]"` viene con el grupo `standard` de dependencias opcionales:
+
+Usadas por Pydantic:
+
+* <a href="https://github.com/JoshData/python-email-validator" target="_blank"><code>email-validator</code></a> - para validación de correos electrónicos.
+
+Usadas por Starlette:
+
+* <a href="https://www.python-httpx.org" target="_blank"><code>httpx</code></a> - Requerido si deseas usar el `TestClient`.
+* <a href="https://jinja.palletsprojects.com" target="_blank"><code>jinja2</code></a> - Requerido si deseas usar la configuración de plantilla predeterminada.
+* <a href="https://github.com/Kludex/python-multipart" target="_blank"><code>python-multipart</code></a> - Requerido si deseas soportar <abbr title="convertir el string que viene de un request HTTP en datos de Python">"parsing"</abbr> de forms, con `request.form()`.
+
+Usadas por FastAPI / Starlette:
+
+* <a href="https://www.uvicorn.dev" target="_blank"><code>uvicorn</code></a> - para el servidor que carga y sirve tu aplicación. Esto incluye `uvicorn[standard]`, que incluye algunas dependencias (por ejemplo, `uvloop`) necesarias para servir con alto rendimiento.
+* `fastapi-cli` - para proporcionar el comando `fastapi`.
+
+### Sin Dependencias `standard`
+
+Si no deseas incluir las dependencias opcionales `standard`, puedes instalar con `pip install fastapi` en lugar de `pip install "fastapi[standard]"`.
+
+### Dependencias Opcionales Adicionales
+
+Existen algunas dependencias adicionales que podrías querer instalar.
+
+Dependencias opcionales adicionales de Pydantic:
+
+* <a href="https://docs.pydantic.dev/latest/usage/pydantic_settings/" target="_blank"><code>pydantic-settings</code></a> - para la gestión de configuraciones.
+* <a href="https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/" target="_blank"><code>pydantic-extra-types</code></a> - para tipos extra para ser usados con Pydantic.
+
+Dependencias opcionales adicionales de FastAPI:
+
+* <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - Requerido si deseas usar `ORJSONResponse`.
+* <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - Requerido si deseas usar `UJSONResponse`.
+
+## Licencia
+
+Este proyecto tiene licencia bajo los términos de la licencia MIT.

docs/es/docs/learn/index.md

@@ -0,0 +1,5 @@
+# Aprende
+
+Aquí están las secciones introductorias y los tutoriales para aprender **FastAPI**.
+
+Podrías considerar esto un **libro**, un **curso**, la forma **oficial** y recomendada de aprender FastAPI. 😎

docs/es/docs/project-generation.md

@@ -0,0 +1,28 @@
+# Plantilla Full Stack FastAPI
+
+Las plantillas, aunque normalmente vienen con una configuración específica, están diseñadas para ser flexibles y personalizables. Esto te permite modificarlas y adaptarlas a los requisitos de tu proyecto, haciéndolas un excelente punto de partida. 🏁
+
+Puedes usar esta plantilla para comenzar, ya que incluye gran parte de la configuración inicial, seguridad, base de datos y algunos endpoints de API ya hechos para ti.
+
+Repositorio de GitHub: <a href="https://github.com/tiangolo/full-stack-fastapi-template" class="external-link" target="_blank">Plantilla Full Stack FastAPI</a>
+
+## Plantilla Full Stack FastAPI - Tecnología y Funcionalidades
+
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) para la API del backend en Python.
+    - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) para las interacciones con bases de datos SQL en Python (ORM).
+    - 🔍 [Pydantic](https://docs.pydantic.dev), utilizado por FastAPI, para la validación de datos y gestión de configuraciones.
+    - 💾 [PostgreSQL](https://www.postgresql.org) como base de datos SQL.
+- 🚀 [React](https://react.dev) para el frontend.
+    - 💃 Usando TypeScript, hooks, [Vite](https://vitejs.dev), y otras partes de una stack moderna de frontend.
+    - 🎨 [Chakra UI](https://chakra-ui.com) para los componentes del frontend.
+    - 🤖 Un cliente de frontend generado automáticamente.
+    - 🧪 [Playwright](https://playwright.dev) para pruebas End-to-End.
+    - 🦇 Soporte para modo oscuro.
+- 🐋 [Docker Compose](https://www.docker.com) para desarrollo y producción.
+- 🔒 Hashing seguro de contraseñas por defecto.
+- 🔑 Autenticación con tokens JWT.
+- 📫 Recuperación de contraseñas basada en email.
+- ✅ Pruebas con [Pytest](https://pytest.org).
+- 📞 [Traefik](https://traefik.io) como proxy inverso / balanceador de carga.
+- 🚢 Instrucciones de despliegue usando Docker Compose, incluyendo cómo configurar un proxy Traefik frontend para manejar certificados HTTPS automáticos.
+- 🏭 CI (integración continua) y CD (despliegue continuo) basados en GitHub Actions.

docs/es/docs/python-types.md

@@ -0,0 +1,576 @@
+# Introducción a Tipos en Python
+
+Python tiene soporte para "anotaciones de tipos" opcionales (también llamadas "type hints").
+
+Estas **"anotaciones de tipos"** o type hints son una sintaxis especial que permite declarar el <abbr title="por ejemplo: str, int, float, bool">tipo</abbr> de una variable.
+
+Al declarar tipos para tus variables, los editores y herramientas te pueden proporcionar un mejor soporte.
+
+Este es solo un **tutorial rápido / recordatorio** sobre las anotaciones de tipos en Python. Cubre solo lo mínimo necesario para usarlas con **FastAPI**... que en realidad es muy poco.
+
+**FastAPI** se basa completamente en estas anotaciones de tipos, dándole muchas ventajas y beneficios.
+
+Pero incluso si nunca usas **FastAPI**, te beneficiaría aprender un poco sobre ellas.
+
+/// note | Nota
+
+Si eres un experto en Python, y ya sabes todo sobre las anotaciones de tipos, salta al siguiente capítulo.
+
+///
+
+## Motivación
+
+Comencemos con un ejemplo simple:
+
+{* ../../docs_src/python_types/tutorial001.py *}
+
+Llamar a este programa genera:
+
+```
+John Doe
+```
+
+La función hace lo siguiente:
+
+* Toma un `first_name` y `last_name`.
+* Convierte la primera letra de cada uno a mayúsculas con `title()`.
+* <abbr title="Los une, como uno. Con el contenido de uno después del otro.">Concatena</abbr> ambos con un espacio en el medio.
+
+{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+
+### Edítalo
+
+Es un programa muy simple.
+
+Pero ahora imagina que lo escribieras desde cero.
+
+En algún momento habrías empezado la definición de la función, tenías los parámetros listos...
+
+Pero luego tienes que llamar "ese método que convierte la primera letra a mayúscula".
+
+¿Era `upper`? ¿Era `uppercase`? `first_uppercase`? `capitalize`?
+
+Entonces, pruebas con el amigo del viejo programador, el autocompletado del editor.
+
+Escribes el primer parámetro de la función, `first_name`, luego un punto (`.`) y luego presionas `Ctrl+Espacio` para activar el autocompletado.
+
+Pero, tristemente, no obtienes nada útil:
+
+<img src="/img/python-types/image01.png">
+
+### Añadir tipos
+
+Modifiquemos una sola línea de la versión anterior.
+
+Cambiaremos exactamente este fragmento, los parámetros de la función, de:
+
+```Python
+    first_name, last_name
+```
+
+a:
+
+```Python
+    first_name: str, last_name: str
+```
+
+Eso es todo.
+
+Esas son las "anotaciones de tipos":
+
+{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+
+Eso no es lo mismo que declarar valores predeterminados como sería con:
+
+```Python
+    first_name="john", last_name="doe"
+```
+
+Es una cosa diferente.
+
+Estamos usando dos puntos (`:`), no igualdades (`=`).
+
+Y agregar anotaciones de tipos normalmente no cambia lo que sucede de lo que ocurriría sin ellas.
+
+Pero ahora, imagina que nuevamente estás en medio de la creación de esa función, pero con anotaciones de tipos.
+
+En el mismo punto, intentas activar el autocompletado con `Ctrl+Espacio` y ves:
+
+<img src="/img/python-types/image02.png">
+
+Con eso, puedes desplazarte, viendo las opciones, hasta que encuentres la que "te suene":
+
+<img src="/img/python-types/image03.png">
+
+## Más motivación
+
+Revisa esta función, ya tiene anotaciones de tipos:
+
+{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+
+Porque el editor conoce los tipos de las variables, no solo obtienes autocompletado, también obtienes chequeo de errores:
+
+<img src="/img/python-types/image04.png">
+
+Ahora sabes que debes corregirlo, convertir `age` a un string con `str(age)`:
+
+{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+
+## Declaración de tipos
+
+Acabas de ver el lugar principal para declarar anotaciones de tipos. Como parámetros de función.
+
+Este también es el lugar principal donde los utilizarías con **FastAPI**.
+
+### Tipos simples
+
+Puedes declarar todos los tipos estándar de Python, no solo `str`.
+
+Puedes usar, por ejemplo:
+
+* `int`
+* `float`
+* `bool`
+* `bytes`
+
+{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+
+### Tipos genéricos con parámetros de tipo
+
+Hay algunas estructuras de datos que pueden contener otros valores, como `dict`, `list`, `set` y `tuple`. Y los valores internos también pueden tener su propio tipo.
+
+Estos tipos que tienen tipos internos se denominan tipos "**genéricos**". Y es posible declararlos, incluso con sus tipos internos.
+
+Para declarar esos tipos y los tipos internos, puedes usar el módulo estándar de Python `typing`. Existe específicamente para soportar estas anotaciones de tipos.
+
+#### Versiones más recientes de Python
+
+La sintaxis que utiliza `typing` es **compatible** con todas las versiones, desde Python 3.6 hasta las versiones más recientes, incluyendo Python 3.9, Python 3.10, etc.
+
+A medida que avanza Python, las **versiones más recientes** vienen con soporte mejorado para estas anotaciones de tipos y en muchos casos ni siquiera necesitarás importar y usar el módulo `typing` para declarar las anotaciones de tipos.
+
+Si puedes elegir una versión más reciente de Python para tu proyecto, podrás aprovechar esa simplicidad adicional.
+
+En toda la documentación hay ejemplos compatibles con cada versión de Python (cuando hay una diferencia).
+
+Por ejemplo, "**Python 3.6+**" significa que es compatible con Python 3.6 o superior (incluyendo 3.7, 3.8, 3.9, 3.10, etc). Y "**Python 3.9+**" significa que es compatible con Python 3.9 o superior (incluyendo 3.10, etc).
+
+Si puedes usar las **últimas versiones de Python**, utiliza los ejemplos para la última versión, esos tendrán la **mejor y más simple sintaxis**, por ejemplo, "**Python 3.10+**".
+
+#### Lista
+
+Por ejemplo, vamos a definir una variable para ser una `list` de `str`.
+
+//// tab | Python 3.9+
+
+Declara la variable, con la misma sintaxis de dos puntos (`:`).
+
+Como tipo, pon `list`.
+
+Como la lista es un tipo que contiene algunos tipos internos, los pones entre corchetes:
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+De `typing`, importa `List` (con una `L` mayúscula):
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
+
+Declara la variable, con la misma sintaxis de dos puntos (`:`).
+
+Como tipo, pon el `List` que importaste de `typing`.
+
+Como la lista es un tipo que contiene algunos tipos internos, los pones entre corchetes:
+
+```Python hl_lines="4"
+{!> ../../docs_src/python_types/tutorial006.py!}
+```
+
+////
+
+/// info | Información
+
+Esos tipos internos en los corchetes se denominan "parámetros de tipo".
+
+En este caso, `str` es el parámetro de tipo pasado a `List` (o `list` en Python 3.9 y superior).
+
+///
+
+Eso significa: "la variable `items` es una `list`, y cada uno de los ítems en esta lista es un `str`".
+
+/// tip | Consejo
+
+Si usas Python 3.9 o superior, no tienes que importar `List` de `typing`, puedes usar el mismo tipo `list` regular en su lugar.
+
+///
+
+Al hacer eso, tu editor puede proporcionar soporte incluso mientras procesa elementos de la lista:
+
+<img src="/img/python-types/image05.png">
+
+Sin tipos, eso es casi imposible de lograr.
+
+Nota que la variable `item` es uno de los elementos en la lista `items`.
+
+Y aún así, el editor sabe que es un `str` y proporciona soporte para eso.
+
+#### Tuple y Set
+
+Harías lo mismo para declarar `tuple`s y `set`s:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial007_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1  4"
+{!> ../../docs_src/python_types/tutorial007.py!}
+```
+
+////
+
+Esto significa:
+
+* La variable `items_t` es un `tuple` con 3 ítems, un `int`, otro `int`, y un `str`.
+* La variable `items_s` es un `set`, y cada uno de sus ítems es del tipo `bytes`.
+
+#### Dict
+
+Para definir un `dict`, pasas 2 parámetros de tipo, separados por comas.
+
+El primer parámetro de tipo es para las claves del `dict`.
+
+El segundo parámetro de tipo es para los valores del `dict`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1  4"
+{!> ../../docs_src/python_types/tutorial008.py!}
+```
+
+////
+
+Esto significa:
+
+* La variable `prices` es un `dict`:
+    * Las claves de este `dict` son del tipo `str` (digamos, el nombre de cada ítem).
+    * Los valores de este `dict` son del tipo `float` (digamos, el precio de cada ítem).
+
+#### Union
+
+Puedes declarar que una variable puede ser cualquier de **varios tipos**, por ejemplo, un `int` o un `str`.
+
+En Python 3.6 y posterior (incluyendo Python 3.10) puedes usar el tipo `Union` de `typing` y poner dentro de los corchetes los posibles tipos a aceptar.
+
+En Python 3.10 también hay una **nueva sintaxis** donde puedes poner los posibles tipos separados por una <abbr title='también llamado "operador OR a nivel de bits", pero ese significado no es relevante aquí'>barra vertical (`|`)</abbr>.
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1  4"
+{!> ../../docs_src/python_types/tutorial008b.py!}
+```
+
+////
+
+En ambos casos, esto significa que `item` podría ser un `int` o un `str`.
+
+#### Posiblemente `None`
+
+Puedes declarar que un valor podría tener un tipo, como `str`, pero que también podría ser `None`.
+
+En Python 3.6 y posteriores (incluyendo Python 3.10) puedes declararlo importando y usando `Optional` del módulo `typing`.
+
+```Python hl_lines="1  4"
+{!../../docs_src/python_types/tutorial009.py!}
+```
+
+Usar `Optional[str]` en lugar de solo `str` te permitirá al editor ayudarte a detectar errores donde podrías estar asumiendo que un valor siempre es un `str`, cuando en realidad también podría ser `None`.
+
+`Optional[Something]` es realmente un atajo para `Union[Something, None]`, son equivalentes.
+
+Esto también significa que en Python 3.10, puedes usar `Something | None`:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1  4"
+{!> ../../docs_src/python_types/tutorial009.py!}
+```
+
+////
+
+//// tab | Python 3.8+ alternative
+
+```Python hl_lines="1  4"
+{!> ../../docs_src/python_types/tutorial009b.py!}
+```
+
+////
+
+#### Uso de `Union` u `Optional`
+
+Si estás usando una versión de Python inferior a 3.10, aquí tienes un consejo desde mi punto de vista muy **subjetivo**:
+
+* 🚨 Evita usar `Optional[SomeType]`
+* En su lugar ✨ **usa `Union[SomeType, None]`** ✨.
+
+Ambos son equivalentes y debajo son lo mismo, pero recomendaría `Union` en lugar de `Optional` porque la palabra "**opcional**" parecería implicar que el valor es opcional, y en realidad significa "puede ser `None`", incluso si no es opcional y aún es requerido.
+
+Creo que `Union[SomeType, None]` es más explícito sobre lo que significa.
+
+Se trata solo de las palabras y nombres. Pero esas palabras pueden afectar cómo tú y tus compañeros de equipo piensan sobre el código.
+
+Como ejemplo, tomemos esta función:
+
+{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+
+El parámetro `name` está definido como `Optional[str]`, pero **no es opcional**, no puedes llamar a la función sin el parámetro:
+
+```Python
+say_hi()  # ¡Oh, no, esto lanza un error! 😱
+```
+
+El parámetro `name` sigue siendo **requerido** (no *opcional*) porque no tiene un valor predeterminado. Aún así, `name` acepta `None` como valor:
+
+```Python
+say_hi(name=None)  # Esto funciona, None es válido 🎉
+```
+
+La buena noticia es que, una vez que estés en Python 3.10, no tendrás que preocuparte por eso, ya que podrás simplemente usar `|` para definir uniones de tipos:
+
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
+
+Y entonces no tendrás que preocuparte por nombres como `Optional` y `Union`. 😎
+
+#### Tipos genéricos
+
+Estos tipos que toman parámetros de tipo en corchetes se llaman **Tipos Genéricos** o **Genéricos**, por ejemplo:
+
+//// tab | Python 3.10+
+
+Puedes usar los mismos tipos integrados como genéricos (con corchetes y tipos dentro):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+Y lo mismo que con Python 3.8, desde el módulo `typing`:
+
+* `Union`
+* `Optional` (lo mismo que con Python 3.8)
+* ...y otros.
+
+En Python 3.10, como alternativa a usar los genéricos `Union` y `Optional`, puedes usar la <abbr title='también llamado "operador OR a nivel de bits", pero ese significado no es relevante aquí'>barra vertical (`|`)</abbr> para declarar uniones de tipos, eso es mucho mejor y más simple.
+
+////
+
+//// tab | Python 3.9+
+
+Puedes usar los mismos tipos integrados como genéricos (con corchetes y tipos dentro):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+Y lo mismo que con Python 3.8, desde el módulo `typing`:
+
+* `Union`
+* `Optional`
+* ...y otros.
+
+////
+
+//// tab | Python 3.8+
+
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ...y otros.
+
+////
+
+### Clases como tipos
+
+También puedes declarar una clase como el tipo de una variable.
+
+Digamos que tienes una clase `Person`, con un nombre:
+
+{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+
+Luego puedes declarar una variable para que sea de tipo `Person`:
+
+{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+
+Y luego, nuevamente, obtienes todo el soporte del editor:
+
+<img src="/img/python-types/image06.png">
+
+Nota que esto significa "`one_person` es una **instance** de la clase `Person`".
+
+No significa "`one_person` es la **clase** llamada `Person`".
+
+## Modelos Pydantic
+
+<a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> es un paquete de Python para realizar la validación de datos.
+
+Declaras la "forma" de los datos como clases con atributos.
+
+Y cada atributo tiene un tipo.
+
+Entonces creas un instance de esa clase con algunos valores y validará los valores, los convertirá al tipo adecuado (si es el caso) y te dará un objeto con todos los datos.
+
+Y obtienes todo el soporte del editor con ese objeto resultante.
+
+Un ejemplo de la documentación oficial de Pydantic:
+
+//// tab | Python 3.10+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011_py310.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python
+{!> ../../docs_src/python_types/tutorial011.py!}
+```
+
+////
+
+/// info | Información
+
+Para saber más sobre <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic, revisa su documentación</a>.
+
+///
+
+**FastAPI** está completamente basado en Pydantic.
+
+Verás mucho más de todo esto en práctica en el [Tutorial - Guía del Usuario](tutorial/index.md){.internal-link target=_blank}.
+
+/// tip | Consejo
+
+Pydantic tiene un comportamiento especial cuando utilizas `Optional` o `Union[Something, None]` sin un valor por defecto, puedes leer más sobre ello en la documentación de Pydantic sobre <a href="https://docs.pydantic.dev/2.3/usage/models/#required-fields" class="external-link" target="_blank">Required Optional fields</a>.
+
+///
+
+## Anotaciones de tipos con metadata
+
+Python también tiene una funcionalidad que permite poner **<abbr title="Datos sobre los datos, en este caso, información sobre el tipo, por ejemplo, una descripción.">metadata</abbr> adicional** en estas anotaciones de tipos usando `Annotated`.
+
+//// tab | Python 3.9+
+
+En Python 3.9, `Annotated` es parte de la librería estándar, así que puedes importarlo desde `typing`.
+
+```Python hl_lines="1  4"
+{!> ../../docs_src/python_types/tutorial013_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+En versiones por debajo de Python 3.9, importas `Annotated` de `typing_extensions`.
+
+Ya estará instalado con **FastAPI**.
+
+```Python hl_lines="1  4"
+{!> ../../docs_src/python_types/tutorial013.py!}
+```
+
+////
+
+Python en sí no hace nada con este `Annotated`. Y para los editores y otras herramientas, el tipo sigue siendo `str`.
+
+Pero puedes usar este espacio en `Annotated` para proporcionar a **FastAPI** metadata adicional sobre cómo quieres que se comporte tu aplicación.
+
+Lo importante a recordar es que **el primer *parámetro de tipo*** que pasas a `Annotated` es el **tipo real**. El resto es solo metadata para otras herramientas.
+
+Por ahora, solo necesitas saber que `Annotated` existe, y que es Python estándar. 😎
+
+Luego verás lo **poderoso** que puede ser.
+
+/// tip | Consejo
+
+El hecho de que esto sea **Python estándar** significa que seguirás obteniendo la **mejor experiencia de desarrollador posible** en tu editor, con las herramientas que usas para analizar y refactorizar tu código, etc. ✨
+
+Y también que tu código será muy compatible con muchas otras herramientas y paquetes de Python. 🚀
+
+///
+
+## Anotaciones de tipos en **FastAPI**
+
+**FastAPI** aprovecha estas anotaciones de tipos para hacer varias cosas.
+
+Con **FastAPI** declaras parámetros con anotaciones de tipos y obtienes:
+
+* **Soporte del editor**.
+* **Chequeo de tipos**.
+
+...y **FastAPI** usa las mismas declaraciones para:
+
+* **Definir requerimientos**: de parámetros de path de la request, parámetros de query, headers, bodies, dependencias, etc.
+* **Convertir datos**: de la request al tipo requerido.
+* **Validar datos**: provenientes de cada request:
+    * Generando **errores automáticos** devueltos al cliente cuando los datos son inválidos.
+* **Documentar** la API usando OpenAPI:
+    * Que luego es usada por las interfaces de documentación interactiva automática.
+
+Todo esto puede sonar abstracto. No te preocupes. Verás todo esto en acción en el [Tutorial - Guía del Usuario](tutorial/index.md){.internal-link target=_blank}.
+
+Lo importante es que al usar tipos estándar de Python, en un solo lugar (en lugar de agregar más clases, decoradores, etc.), **FastAPI** hará gran parte del trabajo por ti.
+
+/// info | Información
+
+Si ya revisaste todo el tutorial y volviste para ver más sobre tipos, un buen recurso es <a href="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html" class="external-link" target="_blank">la "cheat sheet" de `mypy`</a>.
+
+///

docs/es/docs/resources/index.md

@@ -0,0 +1,3 @@
+# Recursos
+
+Recursos adicionales, enlaces externos, artículos y más. ✈️

docs/es/docs/tutorial/background-tasks.md

@@ -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.dev/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.dev/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.

docs/es/docs/tutorial/bigger-applications.md

@@ -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.drawio.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.drawio.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.

docs/es/docs/tutorial/body-fields.md

@@ -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.

docs/es/docs/tutorial/body-multiple-params.md

@@ -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.

docs/es/docs/tutorial/body-nested-models.md

@@ -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

docs/es/docs/tutorial/body-updates.md

@@ -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}.
+
+///

docs/es/docs/tutorial/body.md

@@ -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}.

docs/es/docs/tutorial/cookie-param-models.md

@@ -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**. 😎

docs/es/docs/tutorial/cookie-params.md

@@ -0,0 +1,35 @@
+# Parámetros de Cookie
+
+Puedes definir parámetros de Cookie de la misma manera que defines los parámetros `Query` y `Path`.
+
+## Importar `Cookie`
+
+Primero importa `Cookie`:
+
+{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
+
+## Declarar parámetros de `Cookie`
+
+Luego declara los parámetros de cookie usando la misma estructura que con `Path` y `Query`.
+
+Puedes definir el valor por defecto así como toda la validación extra o los parámetros de anotación:
+
+{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *}
+
+/// note | Detalles Técnicos
+
+`Cookie` es una clase "hermana" de `Path` y `Query`. También hereda de la misma clase común `Param`.
+
+Pero recuerda que cuando importas `Query`, `Path`, `Cookie` y otros desde `fastapi`, en realidad son funciones que devuelven clases especiales.
+
+///
+
+/// info | Información
+
+Para declarar cookies, necesitas usar `Cookie`, porque de lo contrario los parámetros serían interpretados como parámetros de query.
+
+///
+
+## Resumen
+
+Declara cookies con `Cookie`, usando el mismo patrón común que `Query` y `Path`.

docs/es/docs/tutorial/cors.md

@@ -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.
+
+///

docs/es/docs/tutorial/debugging.md

@@ -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">

docs/es/docs/tutorial/dependencies/classes-as-dependencies.md

@@ -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.
+
+///

docs/es/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md

@@ -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*.

docs/es/docs/tutorial/dependencies/dependencies-with-yield.md

@@ -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.
+
+///

docs/es/docs/tutorial/dependencies/global-dependencies.md

@@ -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*.

docs/es/docs/tutorial/dependencies/index.md

@@ -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.

docs/es/docs/tutorial/dependencies/sub-dependencies.md

@@ -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á.
+
+///

docs/es/docs/tutorial/encoder.md

@@ -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.
+
+///

docs/es/docs/tutorial/extra-data-types.md

@@ -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] *}

docs/es/docs/tutorial/extra-models.md

@@ -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.

docs/es/docs/tutorial/first-steps.md

@@ -0,0 +1,331 @@
+# Primeros Pasos
+
+El archivo FastAPI más simple podría verse así:
+
+{* ../../docs_src/first_steps/tutorial001.py *}
+
+Copia eso en un archivo `main.py`.
+
+Ejecuta el servidor en vivo:
+
+<div class="termy">
+
+```console
+$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:single">main.py</u>
+<font color="#3465A4">INFO    </font> Using path <font color="#3465A4">main.py</font>
+<font color="#3465A4">INFO    </font> Resolved absolute path <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
+<font color="#3465A4">INFO    </font> Searching for package file structure from directories with <font color="#3465A4">__init__.py</font> files
+<font color="#3465A4">INFO    </font> Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
+
+ ╭─ <font color="#8AE234"><b>Python module file</b></font> ─╮
+ │                      │
+ │  🐍 main.py          │
+ │                      │
+ ╰──────────────────────╯
+
+<font color="#3465A4">INFO    </font> Importing module <font color="#4E9A06">main</font>
+<font color="#3465A4">INFO    </font> Found importable FastAPI app
+
+ ╭─ <font color="#8AE234"><b>Importable FastAPI app</b></font> ─╮
+ │                          │
+ │  <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822">  </span>  │
+ │                          │
+ ╰──────────────────────────╯
+
+<font color="#3465A4">INFO    </font> Using import string <font color="#8AE234"><b>main:app</b></font>
+
+ <span style="background-color:#C4A000"><font color="#2E3436">╭────────── FastAPI CLI - Development mode ───────────╮</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  Serving at: http://127.0.0.1:8000                  │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  API docs: http://127.0.0.1:8000/docs               │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  Running in development mode, for production use:   │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  </font></span><span style="background-color:#C4A000"><font color="#555753"><b>fastapi run</b></font></span><span style="background-color:#C4A000"><font color="#2E3436">                                        │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">╰─────────────────────────────────────────────────────╯</font></span>
+
+<font color="#4E9A06">INFO</font>:     Will watch for changes in these directories: [&apos;/home/user/code/awesomeapp&apos;]
+<font color="#4E9A06">INFO</font>:     Uvicorn running on <b>http://127.0.0.1:8000</b> (Press CTRL+C to quit)
+<font color="#4E9A06">INFO</font>:     Started reloader process [<font color="#34E2E2"><b>2265862</b></font>] using <font color="#34E2E2"><b>WatchFiles</b></font>
+<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">2265873</font>]
+<font color="#4E9A06">INFO</font>:     Waiting for application startup.
+<font color="#4E9A06">INFO</font>:     Application startup complete.
+```
+
+</div>
+
+En el resultado, hay una línea con algo como:
+
+```hl_lines="4"
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+Esa línea muestra la URL donde tu aplicación está siendo servida, en tu máquina local.
+
+### Compruébalo
+
+Abre tu navegador en <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>.
+
+Verás el response JSON como:
+
+```JSON
+{"message": "Hello World"}
+```
+
+### Documentación interactiva de la API
+
+Ahora ve a <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 interactiva automática de la API (proporcionada por <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>):
+
+![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png)
+
+### Documentación alternativa de la API
+
+Y ahora, ve a <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
+
+Verás la documentación alternativa automática (proporcionada por <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>):
+
+![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
+
+### OpenAPI
+
+**FastAPI** genera un "esquema" con toda tu API utilizando el estándar **OpenAPI** para definir APIs.
+
+#### "Esquema"
+
+Un "esquema" es una definición o descripción de algo. No el código que lo implementa, sino solo una descripción abstracta.
+
+#### Esquema de la API
+
+En este caso, <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> es una especificación que dicta cómo definir un esquema de tu API.
+
+Esta definición de esquema incluye los paths de tu API, los posibles parámetros que toman, etc.
+
+#### Esquema de Datos
+
+El término "esquema" también podría referirse a la forma de algunos datos, como el contenido JSON.
+
+En ese caso, significaría los atributos del JSON, los tipos de datos que tienen, etc.
+
+#### OpenAPI y JSON Schema
+
+OpenAPI define un esquema de API para tu API. Y ese esquema incluye definiciones (o "esquemas") de los datos enviados y recibidos por tu API utilizando **JSON Schema**, el estándar para esquemas de datos JSON.
+
+#### Revisa el `openapi.json`
+
+Si tienes curiosidad por cómo se ve el esquema OpenAPI en bruto, FastAPI automáticamente genera un JSON (esquema) con las descripciones de toda tu API.
+
+Puedes verlo directamente en: <a href="http://127.0.0.1:8000/openapi.json" class="external-link" target="_blank">http://127.0.0.1:8000/openapi.json</a>.
+
+Mostrará un JSON que empieza con algo como:
+
+```JSON
+{
+    "openapi": "3.1.0",
+    "info": {
+        "title": "FastAPI",
+        "version": "0.1.0"
+    },
+    "paths": {
+        "/items/": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+
+
+
+...
+```
+
+#### Para qué sirve OpenAPI
+
+El esquema OpenAPI es lo que impulsa los dos sistemas de documentación interactiva incluidos.
+
+Y hay docenas de alternativas, todas basadas en OpenAPI. Podrías añadir fácilmente cualquiera de esas alternativas a tu aplicación construida con **FastAPI**.
+
+También podrías usarlo para generar código automáticamente, para clientes que se comuniquen con tu API. Por ejemplo, aplicaciones frontend, móviles o IoT.
+
+## Recapitulación, paso a paso
+
+### Paso 1: importa `FastAPI`
+
+{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
+
+`FastAPI` es una clase de Python que proporciona toda la funcionalidad para tu API.
+
+/// note | Detalles Técnicos
+
+`FastAPI` es una clase que hereda directamente de `Starlette`.
+
+Puedes usar toda la funcionalidad de <a href="https://www.starlette.dev/" class="external-link" target="_blank">Starlette</a> con `FastAPI` también.
+
+///
+
+### Paso 2: crea una "instance" de `FastAPI`
+
+{* ../../docs_src/first_steps/tutorial001.py hl[3] *}
+
+Aquí la variable `app` será una "instance" de la clase `FastAPI`.
+
+Este será el punto principal de interacción para crear toda tu API.
+
+### Paso 3: crea una *path operation*
+
+#### Path
+
+"Path" aquí se refiere a la última parte de la URL empezando desde la primera `/`.
+
+Así que, en una URL como:
+
+```
+https://example.com/items/foo
+```
+
+...el path sería:
+
+```
+/items/foo
+```
+
+/// info
+
+Un "path" también es comúnmente llamado "endpoint" o "ruta".
+
+///
+
+Mientras construyes una API, el "path" es la forma principal de separar "concerns" y "resources".
+
+#### Operación
+
+"Operación" aquí se refiere a uno de los "métodos" HTTP.
+
+Uno de:
+
+* `POST`
+* `GET`
+* `PUT`
+* `DELETE`
+
+...y los más exóticos:
+
+* `OPTIONS`
+* `HEAD`
+* `PATCH`
+* `TRACE`
+
+En el protocolo HTTP, puedes comunicarte con cada path usando uno (o más) de estos "métodos".
+
+---
+
+Al construir APIs, normalmente usas estos métodos HTTP específicos para realizar una acción específica.
+
+Normalmente usas:
+
+* `POST`: para crear datos.
+* `GET`: para leer datos.
+* `PUT`: para actualizar datos.
+* `DELETE`: para eliminar datos.
+
+Así que, en OpenAPI, cada uno de los métodos HTTP se llama una "operation".
+
+Vamos a llamarlas "**operaciones**" también.
+
+#### Define un *path operation decorator*
+
+{* ../../docs_src/first_steps/tutorial001.py hl[6] *}
+
+El `@app.get("/")` le dice a **FastAPI** que la función justo debajo se encarga de manejar requests que vayan a:
+
+* el path `/`
+* usando una <abbr title="un método HTTP GET"><code>get</code> operation</abbr>
+
+/// info | Información sobre `@decorator`
+
+Esa sintaxis `@algo` en Python se llama un "decorador".
+
+Lo pones encima de una función. Como un bonito sombrero decorativo (supongo que de ahí viene el término).
+
+Un "decorador" toma la función de abajo y hace algo con ella.
+
+En nuestro caso, este decorador le dice a **FastAPI** que la función de abajo corresponde al **path** `/` con una **operation** `get`.
+
+Es el "**path operation decorator**".
+
+///
+
+También puedes usar las otras operaciones:
+
+* `@app.post()`
+* `@app.put()`
+* `@app.delete()`
+
+Y los más exóticos:
+
+* `@app.options()`
+* `@app.head()`
+* `@app.patch()`
+* `@app.trace()`
+
+/// tip
+
+Eres libre de usar cada operación (método HTTP) como quieras.
+
+**FastAPI** no fuerza ningún significado específico.
+
+La información aquí se presenta como una guía, no un requisito.
+
+Por ejemplo, cuando usas GraphQL normalmente realizas todas las acciones usando solo operaciones `POST`.
+
+///
+
+### Paso 4: define la **path operation function**
+
+Esta es nuestra "**path operation function**":
+
+* **path**: es `/`.
+* **operation**: es `get`.
+* **function**: es la función debajo del "decorador" (debajo de `@app.get("/")`).
+
+{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
+
+Esta es una función de Python.
+
+Será llamada por **FastAPI** cuando reciba un request en la URL "`/`" usando una operación `GET`.
+
+En este caso, es una función `async`.
+
+---
+
+También podrías definirla como una función normal en lugar de `async def`:
+
+{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
+
+/// note | Nota
+
+Si no sabes la diferencia, revisa la sección [Async: *"¿Tienes prisa?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+///
+
+### Paso 5: retorna el contenido
+
+{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
+
+Puedes retornar un `dict`, `list`, valores singulares como `str`, `int`, etc.
+
+También puedes retornar modelos de Pydantic (verás más sobre eso más adelante).
+
+Hay muchos otros objetos y modelos que serán automáticamente convertidos a JSON (incluyendo ORMs, etc). Intenta usar tus favoritos, es altamente probable que ya sean compatibles.
+
+## Recapitulación
+
+* Importa `FastAPI`.
+* Crea una instancia `app`.
+* Escribe un **path operation decorator** usando decoradores como `@app.get("/")`.
+* Define una **path operation function**; por ejemplo, `def root(): ...`.
+* Ejecuta el servidor de desarrollo usando el comando `fastapi dev`.

docs/es/docs/tutorial/handling-errors.md

@@ -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.dev/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.

docs/es/docs/tutorial/header-param-models.md

@@ -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**. 😎

docs/es/docs/tutorial/header-params.md

@@ -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.

docs/es/docs/tutorial/index.md

@@ -0,0 +1,102 @@
+# Tutorial - Guía del Usuario
+
+Este tutorial te muestra cómo usar **FastAPI** con la mayoría de sus funcionalidades, paso a paso.
+
+Cada sección se basa gradualmente en las anteriores, pero está estructurada para separar temas, de manera que puedas ir directamente a cualquier sección específica para resolver tus necesidades específicas de API.
+
+También está diseñado para funcionar como una referencia futura para que puedas volver y ver exactamente lo que necesitas.
+
+## Ejecuta el código
+
+Todos los bloques de código pueden ser copiados y usados directamente (de hecho, son archivos Python probados).
+
+Para ejecutar cualquiera de los ejemplos, copia el código a un archivo `main.py`, y comienza `fastapi dev` con:
+
+<div class="termy">
+
+```console
+$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:single">main.py</u>
+<font color="#3465A4">INFO    </font> Using path <font color="#3465A4">main.py</font>
+<font color="#3465A4">INFO    </font> Resolved absolute path <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
+<font color="#3465A4">INFO    </font> Searching for package file structure from directories with <font color="#3465A4">__init__.py</font> files
+<font color="#3465A4">INFO    </font> Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
+
+ ╭─ <font color="#8AE234"><b>Python module file</b></font> ─╮
+ │                      │
+ │  🐍 main.py          │
+ │                      │
+ ╰──────────────────────╯
+
+<font color="#3465A4">INFO    </font> Importing module <font color="#4E9A06">main</font>
+<font color="#3465A4">INFO    </font> Found importable FastAPI app
+
+ ╭─ <font color="#8AE234"><b>Importable FastAPI app</b></font> ─╮
+ │                          │
+ │  <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822">  </span>  │
+ │                          │
+ ╰──────────────────────────╯
+
+<font color="#3465A4">INFO    </font> Using import string <font color="#8AE234"><b>main:app</b></font>
+
+ <span style="background-color:#C4A000"><font color="#2E3436">╭────────── FastAPI CLI - Development mode ───────────╮</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  Serving at: http://127.0.0.1:8000                  │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  API docs: http://127.0.0.1:8000/docs               │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  Running in development mode, for production use:   │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│  </font></span><span style="background-color:#C4A000"><font color="#555753"><b>fastapi run</b></font></span><span style="background-color:#C4A000"><font color="#2E3436">                                        │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
+ <span style="background-color:#C4A000"><font color="#2E3436">╰─────────────────────────────────────────────────────╯</font></span>
+
+<font color="#4E9A06">INFO</font>:     Will watch for changes in these directories: [&apos;/home/user/code/awesomeapp&apos;]
+<font color="#4E9A06">INFO</font>:     Uvicorn running on <b>http://127.0.0.1:8000</b> (Press CTRL+C to quit)
+<font color="#4E9A06">INFO</font>:     Started reloader process [<font color="#34E2E2"><b>2265862</b></font>] using <font color="#34E2E2"><b>WatchFiles</b></font>
+<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">2265873</font>]
+<font color="#4E9A06">INFO</font>:     Waiting for application startup.
+<font color="#4E9A06">INFO</font>:     Application startup complete.
+</pre>
+```
+
+</div>
+
+Es **ALTAMENTE recomendable** que escribas o copies el código, lo edites y lo ejecutes localmente.
+
+Usarlo en tu editor es lo que realmente te muestra los beneficios de FastAPI, al ver cuán poco código tienes que escribir, todos los chequeos de tipos, autocompletado, etc.
+
+---
+
+## Instalar FastAPI
+
+El primer paso es instalar FastAPI.
+
+Asegúrate de crear un [entorno virtual](../virtual-environments.md){.internal-link target=_blank}, actívalo, y luego **instala FastAPI**:
+
+<div class="termy">
+
+```console
+$ pip install "fastapi[standard]"
+
+---> 100%
+```
+
+</div>
+
+/// note | Nota
+
+Cuando instalas con `pip install "fastapi[standard]"` viene con algunas dependencias opcionales estándar por defecto.
+
+Si no quieres tener esas dependencias opcionales, en su lugar puedes instalar `pip install fastapi`.
+
+///
+
+## Guía Avanzada del Usuario
+
+También hay una **Guía Avanzada del Usuario** que puedes leer después de esta **Tutorial - Guía del Usuario**.
+
+La **Guía Avanzada del Usuario** se basa en esta, utiliza los mismos conceptos y te enseña algunas funcionalidades adicionales.
+
+Pero primero deberías leer la **Tutorial - Guía del Usuario** (lo que estás leyendo ahora mismo).
+
+Está diseñada para que puedas construir una aplicación completa solo con la **Tutorial - Guía del Usuario**, y luego extenderla de diferentes maneras, dependiendo de tus necesidades, utilizando algunas de las ideas adicionales de la **Guía Avanzada del Usuario**.

docs/es/docs/tutorial/metadata.md

@@ -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] *}

docs/es/docs/tutorial/middleware.md

@@ -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.dev/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.

docs/es/docs/tutorial/path-operation-configuration.md

@@ -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*.

docs/es/docs/tutorial/path-params-numeric-validations.md

@@ -0,0 +1,154 @@
+# 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:
+
+{* ../../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.
+
+///

docs/es/docs/tutorial/path-params.md

@@ -0,0 +1,257 @@
+# Parámetros de Path
+
+Puedes declarar "parámetros" o "variables" de path con la misma sintaxis que se usa en los format strings de Python:
+
+{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+
+El valor del parámetro de path `item_id` se pasará a tu función como el argumento `item_id`.
+
+Así que, si ejecutas este ejemplo y vas a <a href="http://127.0.0.1:8000/items/foo" class="external-link" target="_blank">http://127.0.0.1:8000/items/foo</a>, verás un response de:
+
+```JSON
+{"item_id":"foo"}
+```
+
+## Parámetros de path con tipos
+
+Puedes declarar el tipo de un parámetro de path en la función, usando anotaciones de tipos estándar de Python:
+
+{* ../../docs_src/path_params/tutorial002.py hl[7] *}
+
+En este caso, `item_id` se declara como un `int`.
+
+/// check | Revisa
+
+Esto te dará soporte del editor dentro de tu función, con chequeo de errores, autocompletado, etc.
+
+///
+
+## Conversión de datos
+
+Si ejecutas este ejemplo y abres tu navegador en <a href="http://127.0.0.1:8000/items/3" class="external-link" target="_blank">http://127.0.0.1:8000/items/3</a>, verás un response de:
+
+```JSON
+{"item_id":3}
+```
+
+/// check | Revisa
+
+Nota que el valor que tu función recibió (y devolvió) es `3`, como un `int` de Python, no un string `"3"`.
+
+Entonces, con esa declaración de tipo, **FastAPI** te ofrece <abbr title="converting the string that comes from an HTTP request into Python data">"parsing"</abbr> automático de requests.
+
+///
+
+## Validación de datos
+
+Pero si vas al navegador en <a href="http://127.0.0.1:8000/items/foo" class="external-link" target="_blank">http://127.0.0.1:8000/items/foo</a>, verás un bonito error HTTP de:
+
+```JSON
+{
+  "detail": [
+    {
+      "type": "int_parsing",
+      "loc": [
+        "path",
+        "item_id"
+      ],
+      "msg": "Input should be a valid integer, unable to parse string as an integer",
+      "input": "foo"
+    }
+  ]
+}
+```
+
+porque el parámetro de path `item_id` tenía un valor de `"foo"`, que no es un `int`.
+
+El mismo error aparecería si proporcionaras un `float` en lugar de un `int`, como en: <a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a>
+
+/// check | Revisa
+
+Entonces, con la misma declaración de tipo de Python, **FastAPI** te ofrece validación de datos.
+
+Nota que el error también indica claramente el punto exacto donde la validación falló.
+
+Esto es increíblemente útil mientras desarrollas y depuras código que interactúa con tu API.
+
+///
+
+## Documentación
+
+Y cuando abras tu navegador 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 una documentación de API automática e interactiva como:
+
+<img src="/img/tutorial/path-params/image01.png">
+
+/// check | Revisa
+
+Nuevamente, solo con esa misma declaración de tipo de Python, **FastAPI** te ofrece documentación automática e interactiva (integrando Swagger UI).
+
+Nota que el parámetro de path está declarado como un entero.
+
+///
+
+## Beneficios basados en estándares, documentación alternativa
+
+Y porque el esquema generado es del estándar <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md" class="external-link" target="_blank">OpenAPI</a>, hay muchas herramientas compatibles.
+
+Debido a esto, el propio **FastAPI** proporciona una documentación de API alternativa (usando ReDoc), a la cual puedes acceder en <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>:
+
+<img src="/img/tutorial/path-params/image02.png">
+
+De la misma manera, hay muchas herramientas compatibles. Incluyendo herramientas de generación de código para muchos lenguajes.
+
+## Pydantic
+
+Toda la validación de datos se realiza internamente con <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a>, así que obtienes todos los beneficios de esta. Y sabes que estás en buenas manos.
+
+Puedes usar las mismas declaraciones de tipo con `str`, `float`, `bool` y muchos otros tipos de datos complejos.
+
+Varios de estos se exploran en los siguientes capítulos del tutorial.
+
+## El orden importa
+
+Al crear *path operations*, puedes encontrarte en situaciones donde tienes un path fijo.
+
+Como `/users/me`, imaginemos que es para obtener datos sobre el usuario actual.
+
+Y luego también puedes tener un path `/users/{user_id}` para obtener datos sobre un usuario específico por algún ID de usuario.
+
+Debido a que las *path operations* se evalúan en orden, necesitas asegurarte de que el path para `/users/me` se declara antes que el de `/users/{user_id}`:
+
+{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
+
+De lo contrario, el path para `/users/{user_id}` también coincidiría para `/users/me`, "pensando" que está recibiendo un parámetro `user_id` con un valor de `"me"`.
+
+De manera similar, no puedes redefinir una path operation:
+
+{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
+
+La primera siempre será utilizada ya que el path coincide primero.
+
+## Valores predefinidos
+
+Si tienes una *path operation* que recibe un *path parameter*, pero quieres que los valores posibles válidos del *path parameter* estén predefinidos, puedes usar un <abbr title="Enumeration">`Enum`</abbr> estándar de Python.
+
+### Crear una clase `Enum`
+
+Importa `Enum` y crea una subclase que herede de `str` y de `Enum`.
+
+Al heredar de `str`, la documentación de la API podrá saber que los valores deben ser de tipo `string` y podrá representarlos correctamente.
+
+Luego crea atributos de clase con valores fijos, que serán los valores válidos disponibles:
+
+{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
+
+/// info | Información
+
+<a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">Las enumeraciones (o enums) están disponibles en Python</a> desde la versión 3.4.
+
+///
+
+/// tip | Consejo
+
+Si te estás preguntando, "AlexNet", "ResNet" y "LeNet" son solo nombres de <abbr title="Técnicamente, arquitecturas de modelos de Deep Learning">modelos</abbr> de Machine Learning.
+
+///
+
+### Declarar un *path parameter*
+
+Luego crea un *path parameter* con una anotación de tipo usando la clase enum que creaste (`ModelName`):
+
+{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+
+### Revisa la documentación
+
+Como los valores disponibles para el *path parameter* están predefinidos, la documentación interactiva puede mostrarlos de manera ordenada:
+
+<img src="/img/tutorial/path-params/image03.png">
+
+### Trabajando con *enumeraciones* de Python
+
+El valor del *path parameter* será un *miembro* de enumeración.
+
+#### Comparar *miembros* de enumeraciones
+
+Puedes compararlo con el *miembro* de enumeración en tu enum creada `ModelName`:
+
+{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+
+#### Obtener el valor de *enumeración*
+
+Puedes obtener el valor actual (un `str` en este caso) usando `model_name.value`, o en general, `your_enum_member.value`:
+
+{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+
+/// tip | Consejo
+
+También podrías acceder al valor `"lenet"` con `ModelName.lenet.value`.
+
+///
+
+#### Devolver *miembros* de enumeración
+
+Puedes devolver *miembros de enum* desde tu *path operation*, incluso anidados en un cuerpo JSON (por ejemplo, un `dict`).
+
+Serán convertidos a sus valores correspondientes (cadenas en este caso) antes de devolverlos al cliente:
+
+{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+
+En tu cliente recibirás un response JSON como:
+
+```JSON
+{
+  "model_name": "alexnet",
+  "message": "Deep Learning FTW!"
+}
+```
+
+## Parámetros de path conteniendo paths
+
+Imaginemos que tienes una *path operation* con un path `/files/{file_path}`.
+
+Pero necesitas que `file_path` en sí mismo contenga un *path*, como `home/johndoe/myfile.txt`.
+
+Entonces, la URL para ese archivo sería algo como: `/files/home/johndoe/myfile.txt`.
+
+### Soporte de OpenAPI
+
+OpenAPI no soporta una manera de declarar un *path parameter* para que contenga un *path* dentro, ya que eso podría llevar a escenarios que son difíciles de probar y definir.
+
+Sin embargo, todavía puedes hacerlo en **FastAPI**, usando una de las herramientas internas de Starlette.
+
+Y la documentación seguiría funcionando, aunque no agregue ninguna documentación indicando que el parámetro debe contener un path.
+
+### Convertidor de Path
+
+Usando una opción directamente de Starlette puedes declarar un *path parameter* conteniendo un *path* usando una URL como:
+
+```
+/files/{file_path:path}
+```
+
+En este caso, el nombre del parámetro es `file_path`, y la última parte, `:path`, indica que el parámetro debería coincidir con cualquier *path*.
+
+Así que, puedes usarlo con:
+
+{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+
+/// tip | Consejo
+
+Podrías necesitar que el parámetro contenga `/home/johndoe/myfile.txt`, con una barra inclinada (`/`) inicial.
+
+En ese caso, la URL sería: `/files//home/johndoe/myfile.txt`, con una doble barra inclinada (`//`) entre `files` y `home`.
+
+///
+
+## Resumen
+
+Con **FastAPI**, al usar declaraciones de tipo estándar de Python, cortas e intuitivas, obtienes:
+
+* Soporte del editor: chequeo de errores, autocompletado, etc.
+* "<abbr title="converting the string that comes from an HTTP request into Python data">parsing</abbr>" de datos
+* Validación de datos
+* Anotación de API y documentación automática
+
+Y solo tienes que declararlos una vez.
+
+Probablemente esa sea la principal ventaja visible de **FastAPI** en comparación con otros frameworks alternativos (aparte del rendimiento bruto).

docs/es/docs/tutorial/query-param-models.md

@@ -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. 🤫
+
+///

docs/es/docs/tutorial/query-params-str-validations.md

@@ -0,0 +1,499 @@
+# 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, 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.

docs/es/docs/tutorial/query-params.md

@@ -0,0 +1,185 @@
+# Parámetros de Query
+
+Cuando declaras otros parámetros de función que no son parte de los parámetros de path, son automáticamente interpretados como parámetros de "query".
+
+{* ../../docs_src/query_params/tutorial001.py hl[9] *}
+
+La query es el conjunto de pares clave-valor que van después del `?` en una URL, separados por caracteres `&`.
+
+Por ejemplo, en la URL:
+
+```
+http://127.0.0.1:8000/items/?skip=0&limit=10
+```
+
+...los parámetros de query son:
+
+* `skip`: con un valor de `0`
+* `limit`: con un valor de `10`
+
+Como son parte de la URL, son "naturalmente" strings.
+
+Pero cuando los declaras con tipos de Python (en el ejemplo anterior, como `int`), son convertidos a ese tipo y validados respecto a él.
+
+Todo el mismo proceso que se aplica para los parámetros de path también se aplica para los parámetros de query:
+
+* Soporte del editor (obviamente)
+* <abbr title="convirtiendo el string que viene de un request HTTP en datos de Python">"Parsing"</abbr> de datos
+* Validación de datos
+* Documentación automática
+
+## Valores por defecto
+
+Como los parámetros de query no son una parte fija de un path, pueden ser opcionales y pueden tener valores por defecto.
+
+En el ejemplo anterior, tienen valores por defecto de `skip=0` y `limit=10`.
+
+Entonces, ir a la URL:
+
+```
+http://127.0.0.1:8000/items/
+```
+
+sería lo mismo que ir a:
+
+```
+http://127.0.0.1:8000/items/?skip=0&limit=10
+```
+
+Pero si vas a, por ejemplo:
+
+```
+http://127.0.0.1:8000/items/?skip=20
+```
+
+Los valores de los parámetros en tu función serán:
+
+* `skip=20`: porque lo configuraste en la URL
+* `limit=10`: porque ese era el valor por defecto
+
+## Parámetros opcionales
+
+De la misma manera, puedes declarar parámetros de query opcionales, estableciendo su valor por defecto en `None`:
+
+{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
+
+/// check | Revisa
+
+Además, nota que **FastAPI** es lo suficientemente inteligente para notar que el parámetro de path `item_id` es un parámetro de path y `q` no lo es, por lo tanto, es un parámetro de query.
+
+///
+
+## Conversión de tipos en parámetros de query
+
+También puedes declarar tipos `bool`, y serán convertidos:
+
+{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}
+
+En este caso, si vas a:
+
+```
+http://127.0.0.1:8000/items/foo?short=1
+```
+
+o
+
+```
+http://127.0.0.1:8000/items/foo?short=True
+```
+
+o
+
+```
+http://127.0.0.1:8000/items/foo?short=true
+```
+
+o
+
+```
+http://127.0.0.1:8000/items/foo?short=on
+```
+
+o
+
+```
+http://127.0.0.1:8000/items/foo?short=yes
+```
+
+o cualquier otra variación (mayúsculas, primera letra en mayúscula, etc.), tu función verá el parámetro `short` con un valor `bool` de `True`. De lo contrario, será `False`.
+
+## Múltiples parámetros de path y de query
+
+Puedes declarar múltiples parámetros de path y de query al mismo tiempo, **FastAPI** sabe cuál es cuál.
+
+Y no tienes que declararlos en un orden específico.
+
+Serán detectados por nombre:
+
+{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
+
+## Parámetros de query requeridos
+
+Cuando declaras un valor por defecto para parámetros que no son de path (por ahora, solo hemos visto parámetros de query), entonces no es requerido.
+
+Si no quieres agregar un valor específico pero solo hacer que sea opcional, establece el valor por defecto como `None`.
+
+Pero cuando quieres hacer un parámetro de query requerido, simplemente no declares ningún valor por defecto:
+
+{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+
+Aquí el parámetro de query `needy` es un parámetro de query requerido de tipo `str`.
+
+Si abres en tu navegador una URL como:
+
+```
+http://127.0.0.1:8000/items/foo-item
+```
+
+...sin agregar el parámetro requerido `needy`, verás un error como:
+
+```JSON
+{
+  "detail": [
+    {
+      "type": "missing",
+      "loc": [
+        "query",
+        "needy"
+      ],
+      "msg": "Field required",
+      "input": null
+    }
+  ]
+}
+```
+
+Como `needy` es un parámetro requerido, necesitarías establecerlo en la URL:
+
+```
+http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
+```
+
+...esto funcionaría:
+
+```JSON
+{
+    "item_id": "foo-item",
+    "needy": "sooooneedy"
+}
+```
+
+Y por supuesto, puedes definir algunos parámetros como requeridos, algunos con un valor por defecto, y algunos enteramente opcionales:
+
+{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
+
+En este caso, hay 3 parámetros de query:
+
+* `needy`, un `str` requerido.
+* `skip`, un `int` con un valor por defecto de `0`.
+* `limit`, un `int` opcional.
+
+/// tip | Consejo
+
+También podrías usar `Enum`s de la misma manera que con [Parámetros de Path](path-params.md#predefined-values){.internal-link target=_blank}.
+
+///

docs/es/docs/tutorial/request-files.md

@@ -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.

docs/es/docs/tutorial/request-form-models.md

@@ -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. 😎

docs/es/docs/tutorial/request-forms-and-files.md

@@ -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.

docs/es/docs/tutorial/request-forms.md

@@ -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.

docs/es/docs/tutorial/response-model.md

@@ -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.