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

Co-authored-by: Alejandra <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: User <[email protected]>

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/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.io/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/?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
+
+[email protected] 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/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.io/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/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.io/responses/#set-cookie" class="external-link" target="_blank">documentación en 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/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, Twitter, etc. Lo usan para proporcionar permisos específicos a usuarios y aplicaciones.
+
+Cada vez que te "logueas con" Facebook, Google, GitHub, Microsoft, 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="[email protected]" 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 `"[email protected]"`.
+
+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="[email protected]"
+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.io/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.io/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.io/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.io/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.io/websockets/" class="external-link" target="_blank">La clase `WebSocket`</a>.
+* <a href="https://www.starlette.io/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.io/" 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.org/" 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

@@ -241,7 +241,7 @@ 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 regresen.
+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.
 

docs/es/docs/deployment/cloud.md

@@ -0,0 +1,18 @@
+# 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.platform.sh/languages/python.html?utm_source=fastapi-signup&utm_medium=banner&utm_campaign=FastAPI-signup-June-2023" class="external-link" target="_blank">Platform.sh</a>
+* <a href="https://docs.porter.run/language-specific-guides/fastapi" class="external-link" target="_blank">Porter</a>
+* <a href="https://www.withcoherence.com/?utm_medium=advertising&utm_source=fastapi&utm_campaign=website" class="external-link" target="_blank">Coherence</a>
+* <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.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 👇](#build-a-docker-image-for-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.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.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.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.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.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.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.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.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.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/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.org/" 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/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.org" 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/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 Twitter
+
+<a href="https://twitter.com/fastapi" class="external-link" target="_blank">Sigue a @fastapi en **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://twitter.com/tiangolo" class="external-link" target="_blank">Seguirme en **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://twitter.com/fastapi" class="external-link" target="_blank">seguir @fastapi en 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 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://twitter.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.io/" 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,191 @@
+# 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@next/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
+/*!
+ * ReDoc - OpenAPI/Swagger-generated API Reference Documentation
+ * -------------------------------------------------------------
+ *   Version: "2.0.0-rc.18"
+ *   Repo: https://github.com/Redocly/redoc
+ */
+!function(e,t){"object"==typeof exports&&"object"==typeof m
+
+...
+```
+
+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.io/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/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/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.io/background/" class="external-link" target="_blank">`starlette.background`</a>.
+
+Se importa/incluye directamente en FastAPI para que puedas importarla desde `fastapi` y evitar importar accidentalmente la alternativa `BackgroundTask` (sin la `s` al final) de `starlette.background`.
+
+Al usar solo `BackgroundTasks` (y no `BackgroundTask`), es posible usarla como un parámetro de *path operation function* y dejar que **FastAPI** maneje el resto por ti, tal como cuando usas el objeto `Request` directamente.
+
+Todavía es posible usar `BackgroundTask` solo en FastAPI, pero debes crear el objeto en tu código y devolver una `Response` de Starlette incluyéndolo.
+
+Puedes ver más detalles en <a href="https://www.starlette.io/background/" class="external-link" target="_blank">la documentación oficial de Starlette sobre Background Tasks</a>.
+
+## Advertencia
+
+Si necesitas realizar una computación intensa en segundo plano y no necesariamente necesitas que se ejecute por el mismo proceso (por ejemplo, no necesitas compartir memoria, variables, etc.), podrías beneficiarte del uso de otras herramientas más grandes como <a href="https://docs.celeryq.dev" class="external-link" target="_blank">Celery</a>.
+
+Tienden a requerir configuraciones más complejas, un gestor de cola de mensajes/trabajos, como RabbitMQ o Redis, pero te permiten ejecutar tareas en segundo plano en múltiples procesos, y especialmente, en múltiples servidores.
+
+Pero si necesitas acceder a variables y objetos de la misma app de **FastAPI**, o necesitas realizar pequeñas tareas en segundo plano (como enviar una notificación por email), simplemente puedes usar `BackgroundTasks`.
+
+## Resumen
+
+Importa y usa `BackgroundTasks` con parámetros en *path operation functions* y dependencias para agregar tareas en segundo plano.

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

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/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="[email protected]")
+```
+
+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': '[email protected]',
+    '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="[email protected]",
+    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/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.io/exceptions/" class="external-link" target="_blank">las mismas utilidades de excepciones de Starlette</a>.
+
+Supongamos que tienes una excepción personalizada `UnicornException` que tú (o un paquete que usas) podría lanzar.
+
+Y quieres manejar esta excepción globalmente con FastAPI.
+
+Podrías agregar un manejador de excepciones personalizado con `@app.exception_handler()`:
+
+{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
+
+Aquí, si solicitas `/unicorns/yolo`, la *path operation* lanzará un `UnicornException`.
+
+Pero será manejado por el `unicorn_exception_handler`.
+
+Así que recibirás un error limpio, con un código de estado HTTP de `418` y un contenido JSON de:
+
+```JSON
+{"message": "Oops! yolo did something. There goes a rainbow..."}
+```
+
+/// note | Nota Técnica
+
+También podrías usar `from starlette.requests import Request` y `from starlette.responses import JSONResponse`.
+
+**FastAPI** ofrece las mismas `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette. Lo mismo con `Request`.
+
+///
+
+## Sobrescribir los manejadores de excepciones predeterminados
+
+**FastAPI** tiene algunos manejadores de excepciones predeterminados.
+
+Estos manejadores se encargan de devolver los responses JSON predeterminadas cuando lanzas un `HTTPException` y cuando el request tiene datos inválidos.
+
+Puedes sobrescribir estos manejadores de excepciones con los tuyos propios.
+
+### Sobrescribir excepciones de validación de request
+
+Cuando un request contiene datos inválidos, **FastAPI** lanza internamente un `RequestValidationError`.
+
+Y también incluye un manejador de excepciones predeterminado para ello.
+
+Para sobrescribirlo, importa el `RequestValidationError` y úsalo con `@app.exception_handler(RequestValidationError)` para decorar el manejador de excepciones.
+
+El manejador de excepciones recibirá un `Request` y la excepción.
+
+{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
+
+Ahora, si vas a `/items/foo`, en lugar de obtener el error JSON por defecto con:
+
+```JSON
+{
+    "detail": [
+        {
+            "loc": [
+                "path",
+                "item_id"
+            ],
+            "msg": "value is not a valid integer",
+            "type": "type_error.integer"
+        }
+    ]
+}
+```
+
+obtendrás una versión en texto, con:
+
+```
+1 validation error
+path -> item_id
+  value is not a valid integer (type=type_error.integer)
+```
+
+#### `RequestValidationError` vs `ValidationError`
+
+/// warning | Advertencia
+
+Estos son detalles técnicos que podrías omitir si no es importante para ti en este momento.
+
+///
+
+`RequestValidationError` es una subclase de <a href="https://docs.pydantic.dev/latest/concepts/models/#error-handling" class="external-link" target="_blank">`ValidationError`</a> de Pydantic.
+
+**FastAPI** la usa para que, si usas un modelo Pydantic en `response_model`, y tus datos tienen un error, lo verás en tu log.
+
+Pero el cliente/usuario no lo verá. En su lugar, el cliente recibirá un "Error Interno del Servidor" con un código de estado HTTP `500`.
+
+Debería ser así porque si tienes un `ValidationError` de Pydantic en tu *response* o en cualquier lugar de tu código (no en el *request* del cliente), en realidad es un bug en tu código.
+
+Y mientras lo arreglas, tus clientes/usuarios no deberían tener acceso a información interna sobre el error, ya que eso podría exponer una vulnerabilidad de seguridad.
+
+### Sobrescribir el manejador de errores de `HTTPException`
+
+De la misma manera, puedes sobrescribir el manejador de `HTTPException`.
+
+Por ejemplo, podrías querer devolver un response de texto plano en lugar de JSON para estos errores:
+
+{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
+
+/// note | Nota Técnica
+
+También podrías usar `from starlette.responses import PlainTextResponse`.
+
+**FastAPI** ofrece las mismas `starlette.responses` como `fastapi.responses` solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
+
+///
+
+### Usar el body de `RequestValidationError`
+
+El `RequestValidationError` contiene el `body` que recibió con datos inválidos.
+
+Podrías usarlo mientras desarrollas tu aplicación para registrar el body y depurarlo, devolverlo al usuario, etc.
+
+{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
+
+Ahora intenta enviar un ítem inválido como:
+
+```JSON
+{
+  "title": "towel",
+  "size": "XL"
+}
+```
+
+Recibirás un response que te dirá que los datos son inválidos conteniendo el body recibido:
+
+```JSON hl_lines="12-15"
+{
+  "detail": [
+    {
+      "loc": [
+        "body",
+        "size"
+      ],
+      "msg": "value is not a valid integer",
+      "type": "type_error.integer"
+    }
+  ],
+  "body": {
+    "title": "towel",
+    "size": "XL"
+  }
+}
+```
+
+#### `HTTPException` de FastAPI vs `HTTPException` de Starlette
+
+**FastAPI** tiene su propio `HTTPException`.
+
+Y la clase de error `HTTPException` de **FastAPI** hereda de la clase de error `HTTPException` de Starlette.
+
+La única diferencia es que el `HTTPException` de **FastAPI** acepta cualquier dato JSON-able para el campo `detail`, mientras que el `HTTPException` de Starlette solo acepta strings para ello.
+
+Así que puedes seguir lanzando un `HTTPException` de **FastAPI** como de costumbre en tu código.
+
+Pero cuando registras un manejador de excepciones, deberías registrarlo para el `HTTPException` de Starlette.
+
+De esta manera, si alguna parte del código interno de Starlette, o una extensión o complemento de Starlette, lanza un `HTTPException` de Starlette, tu manejador podrá capturarlo y manejarlo.
+
+En este ejemplo, para poder tener ambos `HTTPException` en el mismo código, las excepciones de Starlette son renombradas a `StarletteHTTPException`:
+
+```Python
+from starlette.exceptions import HTTPException as StarletteHTTPException
+```
+
+### Reutilizar los manejadores de excepciones de **FastAPI**
+
+Si quieres usar la excepción junto con los mismos manejadores de excepciones predeterminados de **FastAPI**, puedes importar y reutilizar los manejadores de excepciones predeterminados de `fastapi.exception_handlers`:
+
+{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
+
+En este ejemplo solo estás `print`eando el error con un mensaje muy expresivo, pero te haces una idea. Puedes usar la excepción y luego simplemente reutilizar los manejadores de excepciones predeterminados.

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/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.io/middleware/#corsmiddleware" class="external-link" target="_blank">la documentación de CORS de Starlette</a>.
+
+///
+
+/// note | Detalles Técnicos
+
+También podrías usar `from starlette.requests import Request`.
+
+**FastAPI** lo proporciona como una conveniencia para ti, el desarrollador. Pero viene directamente de Starlette.
+
+///
+
+### Antes y después de la `response`
+
+Puedes añadir código que se ejecute con la `request`, antes de que cualquier *path operation* la reciba.
+
+Y también después de que se genere la `response`, antes de devolverla.
+
+Por ejemplo, podrías añadir un custom header `X-Process-Time` que contenga el tiempo en segundos que tomó procesar la request y generar una response:
+
+{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
+
+/// tip | Consejo
+
+Aquí usamos <a href="https://docs.python.org/3/library/time.html#time.perf_counter" class="external-link" target="_blank">`time.perf_counter()`</a> en lugar de `time.time()` porque puede ser más preciso para estos casos de uso. 🤓
+
+///
+
+## Otros middlewares
+
+Más adelante puedes leer sobre otros middlewares en la [Guía del Usuario Avanzado: Middleware Avanzado](../advanced/middleware.md){.internal-link target=_blank}.
+
+Leerás sobre cómo manejar <abbr title="Cross-Origin Resource Sharing">CORS</abbr> con un middleware en la siguiente sección.

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

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

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.

docs/es/docs/tutorial/response-status-code.md

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

docs/es/docs/tutorial/schema-extra-example.md

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

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

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

docs/es/docs/tutorial/security/get-current-user.md

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

docs/es/docs/tutorial/security/index.md

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

docs/es/docs/tutorial/security/oauth2-jwt.md

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

docs/es/docs/tutorial/security/simple-oauth2.md

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

docs/es/docs/tutorial/sql-databases.md

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

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

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

docs/es/docs/tutorial/testing.md

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

docs/es/docs/virtual-environments.md

@@ -0,0 +1,842 @@
+# Entornos Virtuales
+
+Cuando trabajas en proyectos de Python probablemente deberías usar un **entorno virtual** (o un mecanismo similar) para aislar los paquetes que instalas para cada proyecto.
+
+/// info | Información
+
+Si ya sabes sobre entornos virtuales, cómo crearlos y usarlos, podrías querer saltar esta sección. 🤓
+
+///
+
+/// tip | Consejo
+
+Un **entorno virtual** es diferente de una **variable de entorno**.
+
+Una **variable de entorno** es una variable en el sistema que puede ser usada por programas.
+
+Un **entorno virtual** es un directorio con algunos archivos en él.
+
+///
+
+/// info | Información
+
+Esta página te enseñará cómo usar **entornos virtuales** y cómo funcionan.
+
+Si estás listo para adoptar una **herramienta que gestiona todo** por ti (incluyendo la instalación de Python), prueba <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">uv</a>.
+
+///
+
+## Crea un Proyecto
+
+Primero, crea un directorio para tu proyecto.
+
+Lo que normalmente hago es crear un directorio llamado `code` dentro de mi directorio de usuario.
+
+Y dentro de eso creo un directorio por proyecto.
+
+<div class="termy">
+
+```console
+// Ve al directorio principal
+$ cd
+// Crea un directorio para todos tus proyectos de código
+$ mkdir code
+// Entra en ese directorio de código
+$ cd code
+// Crea un directorio para este proyecto
+$ mkdir awesome-project
+// Entra en ese directorio del proyecto
+$ cd awesome-project
+```
+
+</div>
+
+## Crea un Entorno Virtual
+
+Cuando empiezas a trabajar en un proyecto de Python **por primera vez**, crea un entorno virtual **<abbr title="hay otras opciones, esto es solo una guía sencilla">dentro de tu proyecto</abbr>**.
+
+/// tip | Consejo
+
+Solo necesitas hacer esto **una vez por proyecto**, no cada vez que trabajas.
+
+///
+
+//// tab | `venv`
+
+Para crear un entorno virtual, puedes usar el módulo `venv` que viene con Python.
+
+<div class="termy">
+
+```console
+$ python -m venv .venv
+```
+
+</div>
+
+/// details | Qué significa ese comando
+
+* `python`: usa el programa llamado `python`
+* `-m`: llama a un módulo como un script, indicaremos cuál módulo a continuación
+* `venv`: usa el módulo llamado `venv` que normalmente viene instalado con Python
+* `.venv`: crea el entorno virtual en el nuevo directorio `.venv`
+
+///
+
+////
+
+//// tab | `uv`
+
+Si tienes instalado <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">`uv`</a>, puedes usarlo para crear un entorno virtual.
+
+<div class="termy">
+
+```console
+$ uv venv
+```
+
+</div>
+
+/// tip | Consejo
+
+Por defecto, `uv` creará un entorno virtual en un directorio llamado `.venv`.
+
+Pero podrías personalizarlo pasando un argumento adicional con el nombre del directorio.
+
+///
+
+////
+
+Ese comando crea un nuevo entorno virtual en un directorio llamado `.venv`.
+
+/// details | `.venv` u otro nombre
+
+Podrías crear el entorno virtual en un directorio diferente, pero hay una convención de llamarlo `.venv`.
+
+///
+
+## Activa el Entorno Virtual
+
+Activa el nuevo entorno virtual para que cualquier comando de Python que ejecutes o paquete que instales lo utilicen.
+
+/// tip | Consejo
+
+Haz esto **cada vez** que inicies una **nueva sesión de terminal** para trabajar en el proyecto.
+
+///
+
+//// tab | Linux, macOS
+
+<div class="termy">
+
+```console
+$ source .venv/bin/activate
+```
+
+</div>
+
+////
+
+//// tab | Windows PowerShell
+
+<div class="termy">
+
+```console
+$ .venv\Scripts\Activate.ps1
+```
+
+</div>
+
+////
+
+//// tab | Windows Bash
+
+O si usas Bash para Windows (por ejemplo, <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
+
+<div class="termy">
+
+```console
+$ source .venv/Scripts/activate
+```
+
+</div>
+
+////
+
+/// tip | Consejo
+
+Cada vez que instales un **nuevo paquete** en ese entorno, **activa** el entorno de nuevo.
+
+Esto asegura que si usas un programa de **terminal (<abbr title="command line interface">CLI</abbr>)** instalado por ese paquete, uses el de tu entorno virtual y no cualquier otro que podría estar instalado globalmente, probablemente con una versión diferente a la que necesitas.
+
+///
+
+## Verifica que el Entorno Virtual esté Activo
+
+Verifica que el entorno virtual esté activo (el comando anterior funcionó).
+
+/// tip | Consejo
+
+Esto es **opcional**, pero es una buena forma de **revisar** que todo está funcionando como se esperaba y estás usando el entorno virtual que pretendes.
+
+///
+
+//// tab | Linux, macOS, Windows Bash
+
+<div class="termy">
+
+```console
+$ which python
+
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+</div>
+
+Si muestra el binario de `python` en `.venv/bin/python`, dentro de tu proyecto (en este caso `awesome-project`), entonces funcionó. 🎉
+
+////
+
+//// tab | Windows PowerShell
+
+<div class="termy">
+
+```console
+$ Get-Command python
+
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+</div>
+
+Si muestra el binario de `python` en `.venv\Scripts\python`, dentro de tu proyecto (en este caso `awesome-project`), entonces funcionó. 🎉
+
+////
+
+## Actualiza `pip`
+
+/// tip | Consejo
+
+Si usas <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">`uv`</a> usarías eso para instalar cosas en lugar de `pip`, por lo que no necesitas actualizar `pip`. 😎
+
+///
+
+Si estás usando `pip` para instalar paquetes (viene por defecto con Python), deberías **actualizarlo** a la última versión.
+
+Muchos errores exóticos al instalar un paquete se resuelven simplemente actualizando `pip` primero.
+
+/// tip | Consejo
+
+Normalmente harías esto **una vez**, justo después de crear el entorno virtual.
+
+///
+
+Asegúrate de que el entorno virtual esté activo (con el comando anterior) y luego ejecuta:
+
+<div class="termy">
+
+```console
+$ python -m pip install --upgrade pip
+
+---> 100%
+```
+
+</div>
+
+## Añade `.gitignore`
+
+Si estás usando **Git** (deberías), añade un archivo `.gitignore` para excluir todo en tu `.venv` de Git.
+
+/// tip | Consejo
+
+Si usaste <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">`uv`</a> para crear el entorno virtual, ya lo hizo por ti, puedes saltarte este paso. 😎
+
+///
+
+/// tip | Consejo
+
+Haz esto **una vez**, justo después de crear el entorno virtual.
+
+///
+
+<div class="termy">
+
+```console
+$ echo "*" > .venv/.gitignore
+```
+
+</div>
+
+/// details | Qué significa ese comando
+
+* `echo "*"`: "imprimirá" el texto `*` en el terminal (la siguiente parte cambia eso un poco)
+* `>`: cualquier cosa impresa en el terminal por el comando a la izquierda de `>` no debería imprimirse, sino escribirse en el archivo que va a la derecha de `>`
+* `.gitignore`: el nombre del archivo donde debería escribirse el texto
+
+Y `*` para Git significa "todo". Así que, ignorará todo en el directorio `.venv`.
+
+Ese comando creará un archivo `.gitignore` con el contenido:
+
+```gitignore
+*
+```
+
+///
+
+## Instala Paquetes
+
+Después de activar el entorno, puedes instalar paquetes en él.
+
+/// tip | Consejo
+
+Haz esto **una vez** al instalar o actualizar los paquetes que necesita tu proyecto.
+
+Si necesitas actualizar una versión o agregar un nuevo paquete, **harías esto de nuevo**.
+
+///
+
+### Instala Paquetes Directamente
+
+Si tienes prisa y no quieres usar un archivo para declarar los requisitos de paquetes de tu proyecto, puedes instalarlos directamente.
+
+/// tip | Consejo
+
+Es una (muy) buena idea poner los paquetes y las versiones que necesita tu programa en un archivo (por ejemplo, `requirements.txt` o `pyproject.toml`).
+
+///
+
+//// tab | `pip`
+
+<div class="termy">
+
+```console
+$ pip install "fastapi[standard]"
+
+---> 100%
+```
+
+</div>
+
+////
+
+//// tab | `uv`
+
+Si tienes <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">`uv`</a>:
+
+<div class="termy">
+
+```console
+$ uv pip install "fastapi[standard]"
+---> 100%
+```
+
+</div>
+
+////
+
+### Instala desde `requirements.txt`
+
+Si tienes un `requirements.txt`, ahora puedes usarlo para instalar sus paquetes.
+
+//// tab | `pip`
+
+<div class="termy">
+
+```console
+$ pip install -r requirements.txt
+---> 100%
+```
+
+</div>
+
+////
+
+//// tab | `uv`
+
+Si tienes <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">`uv`</a>:
+
+<div class="termy">
+
+```console
+$ uv pip install -r requirements.txt
+---> 100%
+```
+
+</div>
+
+////
+
+/// details | `requirements.txt`
+
+Un `requirements.txt` con algunos paquetes podría verse así:
+
+```requirements.txt
+fastapi[standard]==0.113.0
+pydantic==2.8.0
+```
+
+///
+
+## Ejecuta Tu Programa
+
+Después de activar el entorno virtual, puedes ejecutar tu programa, y usará el Python dentro de tu entorno virtual con los paquetes que instalaste allí.
+
+<div class="termy">
+
+```console
+$ python main.py
+
+Hello World
+```
+
+</div>
+
+## Configura Tu Editor
+
+Probablemente usarías un editor, asegúrate de configurarlo para que use el mismo entorno virtual que creaste (probablemente lo autodetectará) para que puedas obtener autocompletado y errores en línea.
+
+Por ejemplo:
+
+* <a href="https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment" class="external-link" target="_blank">VS Code</a>
+* <a href="https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html" class="external-link" target="_blank">PyCharm</a>
+
+/// tip | Consejo
+
+Normalmente solo tendrías que hacer esto **una vez**, cuando crees el entorno virtual.
+
+///
+
+## Desactiva el Entorno Virtual
+
+Una vez que hayas terminado de trabajar en tu proyecto, puedes **desactivar** el entorno virtual.
+
+<div class="termy">
+
+```console
+$ deactivate
+```
+
+</div>
+
+De esta manera, cuando ejecutes `python` no intentará ejecutarse desde ese entorno virtual con los paquetes instalados allí.
+
+## Listo para Trabajar
+
+Ahora estás listo para empezar a trabajar en tu proyecto.
+
+/// tip | Consejo
+
+¿Quieres entender todo lo anterior?
+
+Continúa leyendo. 👇🤓
+
+///
+
+## Por qué Entornos Virtuales
+
+Para trabajar con FastAPI necesitas instalar <a href="https://www.python.org/" class="external-link" target="_blank">Python</a>.
+
+Después de eso, necesitarías **instalar** FastAPI y cualquier otro **paquete** que desees usar.
+
+Para instalar paquetes normalmente usarías el comando `pip` que viene con Python (o alternativas similares).
+
+Sin embargo, si solo usas `pip` directamente, los paquetes se instalarían en tu **entorno global de Python** (la instalación global de Python).
+
+### El Problema
+
+Entonces, ¿cuál es el problema de instalar paquetes en el entorno global de Python?
+
+En algún momento, probablemente terminarás escribiendo muchos programas diferentes que dependen de **diferentes paquetes**. Y algunos de estos proyectos en los que trabajas dependerán de **diferentes versiones** del mismo paquete. 😱
+
+Por ejemplo, podrías crear un proyecto llamado `philosophers-stone`, este programa depende de otro paquete llamado **`harry`, usando la versión `1`**. Así que, necesitas instalar `harry`.
+
+```mermaid
+flowchart LR
+    stone(philosophers-stone) -->|requires| harry-1[harry v1]
+```
+
+Luego, en algún momento después, creas otro proyecto llamado `prisoner-of-azkaban`, y este proyecto también depende de `harry`, pero este proyecto necesita **`harry` versión `3`**.
+
+```mermaid
+flowchart LR
+    azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]
+```
+
+Pero ahora el problema es, si instalas los paquetes globalmente (en el entorno global) en lugar de en un **entorno virtual local**, tendrás que elegir qué versión de `harry` instalar.
+
+Si deseas ejecutar `philosophers-stone` necesitarás primero instalar `harry` versión `1`, por ejemplo con:
+
+<div class="termy">
+
+```console
+$ pip install "harry==1"
+```
+
+</div>
+
+Y entonces terminarías con `harry` versión `1` instalada en tu entorno global de Python.
+
+```mermaid
+flowchart LR
+    subgraph global[global env]
+        harry-1[harry v1]
+    end
+    subgraph stone-project[philosophers-stone project]
+        stone(philosophers-stone) -->|requires| harry-1
+    end
+```
+
+Pero luego si deseas ejecutar `prisoner-of-azkaban`, necesitarás desinstalar `harry` versión `1` e instalar `harry` versión `3` (o simplemente instalar la versión `3` automáticamente desinstalaría la versión `1`).
+
+<div class="termy">
+
+```console
+$ pip install "harry==3"
+```
+
+</div>
+
+Y entonces terminarías con `harry` versión `3` instalada en tu entorno global de Python.
+
+Y si intentas ejecutar `philosophers-stone` de nuevo, hay una posibilidad de que **no funcione** porque necesita `harry` versión `1`.
+
+```mermaid
+flowchart LR
+    subgraph global[global env]
+        harry-1[<strike>harry v1</strike>]
+        style harry-1 fill:#ccc,stroke-dasharray: 5 5
+        harry-3[harry v3]
+    end
+    subgraph stone-project[philosophers-stone project]
+        stone(philosophers-stone) -.-x|⛔️| harry-1
+    end
+    subgraph azkaban-project[prisoner-of-azkaban project]
+        azkaban(prisoner-of-azkaban) --> |requires| harry-3
+    end
+```
+
+/// tip | Consejo
+
+Es muy común en los paquetes de Python intentar lo mejor para **evitar romper cambios** en **nuevas versiones**, pero es mejor estar seguro e instalar nuevas versiones intencionalmente y cuando puedas ejecutar las pruebas para verificar que todo está funcionando correctamente.
+
+///
+
+Ahora, imagina eso con **muchos** otros **paquetes** de los que dependen todos tus **proyectos**. Eso es muy difícil de manejar. Y probablemente terminarías ejecutando algunos proyectos con algunas **versiones incompatibles** de los paquetes, y sin saber por qué algo no está funcionando.
+
+Además, dependiendo de tu sistema operativo (por ejemplo, Linux, Windows, macOS), podría haber venido con Python ya instalado. Y en ese caso probablemente tenía algunos paquetes preinstalados con algunas versiones específicas **necesitadas por tu sistema**. Si instalas paquetes en el entorno global de Python, podrías terminar **rompiendo** algunos de los programas que vinieron con tu sistema operativo.
+
+## Dónde se Instalan los Paquetes
+
+Cuando instalas Python, crea algunos directorios con algunos archivos en tu computadora.
+
+Algunos de estos directorios son los encargados de tener todos los paquetes que instalas.
+
+Cuando ejecutas:
+
+<div class="termy">
+
+```console
+// No ejecutes esto ahora, solo es un ejemplo 🤓
+$ pip install "fastapi[standard]"
+---> 100%
+```
+
+</div>
+
+Eso descargará un archivo comprimido con el código de FastAPI, normalmente desde <a href="https://pypi.org/project/fastapi/" class="external-link" target="_blank">PyPI</a>.
+
+También **descargará** archivos para otros paquetes de los que depende FastAPI.
+
+Luego, **extraerá** todos esos archivos y los pondrá en un directorio en tu computadora.
+
+Por defecto, pondrá esos archivos descargados y extraídos en el directorio que viene con tu instalación de Python, eso es el **entorno global**.
+
+## Qué son los Entornos Virtuales
+
+La solución a los problemas de tener todos los paquetes en el entorno global es usar un **entorno virtual para cada proyecto** en el que trabajas.
+
+Un entorno virtual es un **directorio**, muy similar al global, donde puedes instalar los paquetes para un proyecto.
+
+De esta manera, cada proyecto tendrá su propio entorno virtual (directorio `.venv`) con sus propios paquetes.
+
+```mermaid
+flowchart TB
+    subgraph stone-project[philosophers-stone project]
+        stone(philosophers-stone) --->|requires| harry-1
+        subgraph venv1[.venv]
+            harry-1[harry v1]
+        end
+    end
+    subgraph azkaban-project[prisoner-of-azkaban project]
+        azkaban(prisoner-of-azkaban) --->|requires| harry-3
+        subgraph venv2[.venv]
+            harry-3[harry v3]
+        end
+    end
+    stone-project ~~~ azkaban-project
+```
+
+## Qué Significa Activar un Entorno Virtual
+
+Cuando activas un entorno virtual, por ejemplo con:
+
+//// tab | Linux, macOS
+
+<div class="termy">
+
+```console
+$ source .venv/bin/activate
+```
+
+</div>
+
+////
+
+//// tab | Windows PowerShell
+
+<div class="termy">
+
+```console
+$ .venv\Scripts\Activate.ps1
+```
+
+</div>
+
+////
+
+//// tab | Windows Bash
+
+O si usas Bash para Windows (por ejemplo, <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
+
+<div class="termy">
+
+```console
+$ source .venv/Scripts/activate
+```
+
+</div>
+
+////
+
+Ese comando creará o modificará algunas [variables de entorno](environment-variables.md){.internal-link target=_blank} que estarán disponibles para los siguientes comandos.
+
+Una de esas variables es la variable `PATH`.
+
+/// tip | Consejo
+
+Puedes aprender más sobre la variable de entorno `PATH` en la sección [Variables de Entorno](environment-variables.md#path-environment-variable){.internal-link target=_blank}.
+
+///
+
+Activar un entorno virtual agrega su path `.venv/bin` (en Linux y macOS) o `.venv\Scripts` (en Windows) a la variable de entorno `PATH`.
+
+Digamos que antes de activar el entorno, la variable `PATH` se veía así:
+
+//// tab | Linux, macOS
+
+```plaintext
+/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+Eso significa que el sistema buscaría programas en:
+
+* `/usr/bin`
+* `/bin`
+* `/usr/sbin`
+* `/sbin`
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Windows\System32
+```
+
+Eso significa que el sistema buscaría programas en:
+
+* `C:\Windows\System32`
+
+////
+
+Después de activar el entorno virtual, la variable `PATH` se vería algo así:
+
+//// tab | Linux, macOS
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+Eso significa que el sistema ahora comenzará a buscar primero los programas en:
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin
+```
+
+antes de buscar en los otros directorios.
+
+Así que, cuando escribas `python` en el terminal, el sistema encontrará el programa Python en
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+y utilizará ese.
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32
+```
+
+Eso significa que el sistema ahora comenzará a buscar primero los programas en:
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts
+```
+
+antes de buscar en los otros directorios.
+
+Así que, cuando escribas `python` en el terminal, el sistema encontrará el programa Python en
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+y utilizará ese.
+
+////
+
+Un detalle importante es que pondrá el path del entorno virtual al **comienzo** de la variable `PATH`. El sistema lo encontrará **antes** que cualquier otro Python disponible. De esta manera, cuando ejecutes `python`, utilizará el Python **del entorno virtual** en lugar de cualquier otro `python` (por ejemplo, un `python` de un entorno global).
+
+Activar un entorno virtual también cambia un par de otras cosas, pero esta es una de las cosas más importantes que hace.
+
+## Verificando un Entorno Virtual
+
+Cuando revisas si un entorno virtual está activo, por ejemplo con:
+
+//// tab | Linux, macOS, Windows Bash
+
+<div class="termy">
+
+```console
+$ which python
+
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+</div>
+
+////
+
+//// tab | Windows PowerShell
+
+<div class="termy">
+
+```console
+$ Get-Command python
+
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+</div>
+
+////
+
+Eso significa que el programa `python` que se utilizará es el que está **en el entorno virtual**.
+
+Usas `which` en Linux y macOS y `Get-Command` en Windows PowerShell.
+
+La forma en que funciona ese comando es que irá y revisará la variable de entorno `PATH`, pasando por **cada path en orden**, buscando el programa llamado `python`. Una vez que lo encuentre, te **mostrará el path** a ese programa.
+
+La parte más importante es que cuando llamas a `python`, ese es el exacto "`python`" que será ejecutado.
+
+Así que, puedes confirmar si estás en el entorno virtual correcto.
+
+/// tip | Consejo
+
+Es fácil activar un entorno virtual, obtener un Python, y luego **ir a otro proyecto**.
+
+Y el segundo proyecto **no funcionaría** porque estás usando el **Python incorrecto**, de un entorno virtual para otro proyecto.
+
+Es útil poder revisar qué `python` se está usando. 🤓
+
+///
+
+## Por qué Desactivar un Entorno Virtual
+
+Por ejemplo, podrías estar trabajando en un proyecto `philosophers-stone`, **activar ese entorno virtual**, instalar paquetes y trabajar con ese entorno.
+
+Y luego quieres trabajar en **otro proyecto** `prisoner-of-azkaban`.
+
+Vas a ese proyecto:
+
+<div class="termy">
+
+```console
+$ cd ~/code/prisoner-of-azkaban
+```
+
+</div>
+
+Si no desactivas el entorno virtual para `philosophers-stone`, cuando ejecutes `python` en el terminal, intentará usar el Python de `philosophers-stone`.
+
+<div class="termy">
+
+```console
+$ cd ~/code/prisoner-of-azkaban
+
+$ python main.py
+
+// Error importando sirius, no está instalado 😱
+Traceback (most recent call last):
+    File "main.py", line 1, in <module>
+        import sirius
+```
+
+</div>
+
+Pero si desactivas el entorno virtual y activas el nuevo para `prisoner-of-askaban` entonces cuando ejecutes `python` utilizará el Python del entorno virtual en `prisoner-of-azkaban`.
+
+<div class="termy">
+
+```console
+$ cd ~/code/prisoner-of-azkaban
+
+// No necesitas estar en el directorio antiguo para desactivar, puedes hacerlo donde sea que estés, incluso después de ir al otro proyecto 😎
+$ deactivate
+
+// Activa el entorno virtual en prisoner-of-azkaban/.venv 🚀
+$ source .venv/bin/activate
+
+// Ahora cuando ejecutes python, encontrará el paquete sirius instalado en este entorno virtual ✨
+$ python main.py
+
+I solemnly swear 🐺
+```
+
+</div>
+
+## Alternativas
+
+Esta es una guía simple para comenzar y enseñarte cómo funciona todo **por debajo**.
+
+Hay muchas **alternativas** para gestionar entornos virtuales, dependencias de paquetes (requisitos), proyectos.
+
+Una vez que estés listo y quieras usar una herramienta para **gestionar todo el proyecto**, dependencias de paquetes, entornos virtuales, etc. Te sugeriría probar <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">uv</a>.
+
+`uv` puede hacer muchas cosas, puede:
+
+* **Instalar Python** por ti, incluyendo diferentes versiones
+* Gestionar el **entorno virtual** para tus proyectos
+* Instalar **paquetes**
+* Gestionar **dependencias y versiones** de paquetes para tu proyecto
+* Asegurarse de que tengas un conjunto **exacto** de paquetes y versiones para instalar, incluidas sus dependencias, para que puedas estar seguro de que puedes ejecutar tu proyecto en producción exactamente igual que en tu computadora mientras desarrollas, esto se llama **locking**
+* Y muchas otras cosas
+
+## Conclusión
+
+Si leíste y comprendiste todo esto, ahora **sabes mucho más** sobre entornos virtuales que muchos desarrolladores por ahí. 🤓
+
+Conocer estos detalles probablemente te será útil en el futuro cuando estés depurando algo que parece complejo, pero sabrás **cómo funciona todo por debajo**. 😎