mirror of
https://github.com/fastapi/fastapi.git
synced 2026-09-11 21:07:50 -04:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 github-actions[bot]
|
c3e3e1635e |
No files matched your search
@@ -125,7 +125,7 @@ Adoptar y usar un estándar abierto para especificaciones de API, en lugar de us
|
||||
Y a integrar herramientas de interfaz de usuario basadas en estándares:
|
||||
|
||||
* [Swagger UI](https://github.com/swagger-api/swagger-ui)
|
||||
* [ReDoc](https://github.com/Rebilly/ReDoc)
|
||||
* [ReDoc](https://github.com/Redocly/redoc)
|
||||
|
||||
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**).
|
||||
|
||||
@@ -237,7 +237,7 @@ Generar el esquema OpenAPI automáticamente, desde el mismo código que define l
|
||||
|
||||
///
|
||||
|
||||
### [NestJS](https://nestjs.com/) (y [Angular](https://angular.io/)) { #nestjs-and-angular }
|
||||
### [NestJS](https://nestjs.com/) (y [Angular](https://angular.dev/)) { #nestjs-and-angular }
|
||||
|
||||
Esto ni siquiera es Python, NestJS es un framework de JavaScript (TypeScript) NodeJS inspirado por Angular.
|
||||
|
||||
@@ -273,7 +273,7 @@ Claramente inspiró a Uvicorn y Starlette, que actualmente son más rápidos que
|
||||
|
||||
/// tip | Inspiró a **FastAPI** a
|
||||
|
||||
Encontrar una manera de tener un rendimiento impresionante.
|
||||
Encontrar una manera de tener un rendimiento increíble.
|
||||
|
||||
Por eso **FastAPI** se basa en Starlette, ya que es el framework más rápido disponible (probado por benchmarks de terceros).
|
||||
|
||||
@@ -337,7 +337,7 @@ Dado que se basa en el estándar previo para frameworks web Python sincrónicos
|
||||
|
||||
/// note | Nota
|
||||
|
||||
Hug fue creado por Timothy Crosley, el mismo creador de [`isort`](https://github.com/timothycrosley/isort), una gran herramienta para ordenar automáticamente imports en archivos Python.
|
||||
Hug fue creado por Timothy Crosley, el mismo creador de [`isort`](https://github.com/PyCQA/isort), una gran herramienta para ordenar automáticamente imports en archivos Python.
|
||||
|
||||
///
|
||||
|
||||
@@ -401,7 +401,7 @@ Considero a **FastAPI** un "sucesor espiritual" de APIStar, mientras mejora y au
|
||||
|
||||
## Usado por **FastAPI** { #used-by-fastapi }
|
||||
|
||||
### [Pydantic](https://docs.pydantic.dev/) { #pydantic }
|
||||
### [Pydantic](https://pydantic.dev/docs/) { #pydantic }
|
||||
|
||||
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.
|
||||
|
||||
@@ -417,7 +417,7 @@ Manejar toda la validación de datos, serialización de datos y documentación a
|
||||
|
||||
///
|
||||
|
||||
### [Starlette](https://www.starlette.dev/) { #starlette }
|
||||
### [Starlette](https://starlette.dev/) { #starlette }
|
||||
|
||||
Starlette es un framework/toolkit <dfn title="El nuevo estándar para construir aplicaciones web asíncronas en Python">ASGI</dfn> liviano, ideal para construir servicios asyncio de alto rendimiento.
|
||||
|
||||
@@ -462,7 +462,7 @@ Por lo tanto, cualquier cosa que puedas hacer con Starlette, puedes hacerlo dire
|
||||
|
||||
///
|
||||
|
||||
### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn }
|
||||
### [Uvicorn](https://uvicorn.dev) { #uvicorn }
|
||||
|
||||
Uvicorn es un servidor ASGI extremadamente rápido, construido sobre uvloop y httptools.
|
||||
|
||||
|
||||
@@ -1,299 +1,11 @@
|
||||
# Variables de Entorno { #environment-variables }
|
||||
|
||||
Una **variable de entorno** (también conocida como una **env var**) es un valor que vive fuera de tu código de Python, en el sistema operativo, y puede ser leído por tu aplicación y otros programas.
|
||||
|
||||
/// tip | Consejo
|
||||
Las aplicaciones FastAPI comúnmente usan variables de entorno para configuración como URLs de bases de datos, credenciales de email y claves secretas.
|
||||
|
||||
Si ya sabes qué son las "variables de entorno" y cómo usarlas, siéntete libre de saltarte esto.
|
||||
Aprenderás cómo usarlas para configuración de aplicaciones en [Ajustes y Variables de Entorno](advanced/settings.md).
|
||||
|
||||
///
|
||||
## Aprende Más { #learn-more }
|
||||
|
||||
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 { #create-and-use-env-vars }
|
||||
|
||||
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 { #read-env-vars-in-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 [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) 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 [The Twelve-Factor App: Config](https://12factor.net/config).
|
||||
|
||||
///
|
||||
|
||||
## Tipos y Validación { #types-and-validation }
|
||||
|
||||
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).
|
||||
|
||||
## Variable de Entorno `PATH` { #path-environment-variable }
|
||||
|
||||
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` { #installing-python-and-updating-the-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).
|
||||
|
||||
## Conclusión { #conclusion }
|
||||
|
||||
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 [Wikipedia para Variable de Entorno](https://en.wikipedia.org/wiki/Environment_variable).
|
||||
|
||||
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).
|
||||
Lee la [guía de Variables de Entorno](https://tiangolo.com/guides/environment-variables/) para una explicación detallada y multiplataforma, incluyendo cómo crear y leer variables de entorno y cómo funciona la variable de entorno `PATH`.
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**FastAPI <abbr title="command line interface - interfaz de línea de comandos">CLI</abbr>** 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]"`), viene con un programa de línea de comandos que puedes ejecutar en la terminal.
|
||||
Cuando añades FastAPI a tu proyecto (por ejemplo, con `uv add "fastapi[standard]"`), viene con un programa de línea de comandos que puedes ejecutar en la terminal.
|
||||
|
||||
Para ejecutar tu aplicación FastAPI en modo de desarrollo, puedes usar el comando `fastapi dev`:
|
||||
|
||||
@@ -52,7 +52,7 @@ Para producción usarías `fastapi run` en lugar de `fastapi dev`. 🚀
|
||||
|
||||
///
|
||||
|
||||
Internamente, **FastAPI CLI** usa [Uvicorn](https://www.uvicorn.dev), un servidor ASGI de alto rendimiento y listo para producción. 😎
|
||||
Internamente, **FastAPI CLI** usa [Uvicorn](https://uvicorn.dev), un servidor ASGI de alto rendimiento y listo para producción. 😎
|
||||
|
||||
El CLI `fastapi` intentará detectar automáticamente la app de FastAPI que debe ejecutar, asumiendo que es un objeto llamado `app` en un archivo `main.py` (o un par de variantes más).
|
||||
|
||||
@@ -100,13 +100,13 @@ from backend.main import app
|
||||
También puedes pasar el path del archivo al comando `fastapi dev`, y adivinará el objeto app de FastAPI a usar:
|
||||
|
||||
```console
|
||||
$ fastapi dev main.py
|
||||
$ uv run fastapi dev main.py
|
||||
```
|
||||
|
||||
O también puedes pasar la opción `--entrypoint` al comando `fastapi dev`:
|
||||
|
||||
```console
|
||||
$ fastapi dev --entrypoint main:app
|
||||
$ uv run fastapi dev --entrypoint main:app
|
||||
```
|
||||
|
||||
Pero tendrías que recordar pasar el path\entrypoint correcto cada vez que llames al comando `fastapi`.
|
||||
@@ -119,6 +119,10 @@ 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`).
|
||||
|
||||
Antes de importar tu app, `fastapi dev` establece la variable de entorno `FASTAPI_ENV` en `development`. Si `FASTAPI_ENV` ya está establecida, se conserva su valor existente. Esto permite que el código de inicio de la app elija un comportamiento amigable para desarrollo mientras te permite proporcionar un entorno específico de la app como `staging`.
|
||||
|
||||
Los valores convencionales de `FASTAPI_ENV` son `development` y `production`. Actualmente `fastapi run` deja `FASTAPI_ENV` sin cambios, así que establécela explícitamente si tu app necesita detectar el modo de producción.
|
||||
|
||||
## `fastapi run` { #fastapi-run }
|
||||
|
||||
Ejecutar `fastapi run` inicia FastAPI en modo de producción.
|
||||
|
||||
@@ -19,7 +19,7 @@ Interfaces web de documentación y exploración de APIs interactivas. Como el fr
|
||||
|
||||
|
||||
|
||||
* Documentación alternativa de API con [**ReDoc**](https://github.com/Rebilly/ReDoc).
|
||||
* Documentación alternativa de API con [**ReDoc**](https://github.com/Redocly/redoc).
|
||||
|
||||
|
||||
|
||||
@@ -159,7 +159,7 @@ Cualquier integración está diseñada para ser tan simple de usar (con dependen
|
||||
|
||||
## Funcionalidades de Starlette { #starlette-features }
|
||||
|
||||
**FastAPI** es totalmente compatible con (y está basado en) [**Starlette**](https://www.starlette.dev/). Así que, cualquier código adicional de Starlette que tengas, también funcionará.
|
||||
**FastAPI** es totalmente compatible con (y está basado en) [**Starlette**](https://starlette.dev/). Así que, cualquier código adicional de Starlette que tengas, también funcionará.
|
||||
|
||||
`FastAPI` es en realidad una subclase de `Starlette`. Así que, si ya conoces o usas Starlette, la mayoría de las funcionalidades funcionarán de la misma manera.
|
||||
|
||||
@@ -177,7 +177,7 @@ Con **FastAPI** obtienes todas las funcionalidades de **Starlette** (ya que Fast
|
||||
|
||||
## Funcionalidades de Pydantic { #pydantic-features }
|
||||
|
||||
**FastAPI** es totalmente compatible con (y está basado en) [**Pydantic**](https://docs.pydantic.dev/). Por lo tanto, cualquier código adicional de Pydantic que tengas, también funcionará.
|
||||
**FastAPI** es totalmente compatible con (y está basado en) [**Pydantic**](https://pydantic.dev/docs/). Por lo tanto, cualquier código adicional de Pydantic que tengas, también funcionará.
|
||||
|
||||
Incluyendo paquetes externos también basados en Pydantic, como <abbr title="Object-Relational Mapper - Mapeador Objeto-Relacional">ORM</abbr>s y <abbr title="Object-Document Mapper - Mapeador Objeto-Documento">ODM</abbr>s para bases de datos.
|
||||
|
||||
|
||||
@@ -45,20 +45,6 @@ Puedes seguir [a mí (Sebastián Ramírez / `tiangolo`)](https://tiangolo.com),
|
||||
* [@tiangolo.com en **Bluesky**](https://bsky.app/profile/tiangolo.com)
|
||||
* [@tiangolo en **LinkedIn**](https://www.linkedin.com/in/tiangolo/).
|
||||
|
||||
## Ayuda a otros con preguntas en GitHub { #help-others-with-questions-in-github }
|
||||
|
||||
Puedes intentar ayudar a otros con sus preguntas en [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered).
|
||||
|
||||
En muchos casos, puede que 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) oficial. 🎉
|
||||
|
||||
Solo recuerda, el punto más importante es: intenta ser amable. 🤗
|
||||
|
||||
### Cómo ayudar { #how-to-help }
|
||||
|
||||
Sigue la [guía sobre cómo ayudar](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github) aquí.
|
||||
|
||||
## Haz preguntas { #ask-questions }
|
||||
|
||||
Puedes [crear una nueva pregunta](https://github.com/fastapi/fastapi/discussions/new?category=questions) en el repositorio de GitHub, por ejemplo para:
|
||||
@@ -68,7 +54,7 @@ Puedes [crear una nueva pregunta](https://github.com/fastapi/fastapi/discussions
|
||||
|
||||
## Únete al chat { #join-the-chat }
|
||||
|
||||
Únete al 👥 [servidor de chat de Discord](https://discord.gg/VQjSZaeJmf) 👥 y charla con otros en la comunidad de FastAPI.
|
||||
Únete al 👥 [servidor de chat de Discord](https://discord.com/invite/VQjSZaeJmf) 👥 y charla con otros en la comunidad de FastAPI.
|
||||
|
||||
/// tip | Consejo
|
||||
|
||||
@@ -85,3 +71,9 @@ Ten en cuenta que dado que los chats permiten una "conversación más libre", es
|
||||
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 tú mismo antes de preguntar.
|
||||
|
||||
Las conversaciones en los sistemas de chat tampoco son tan fáciles de buscar como en GitHub; se pierden.
|
||||
|
||||
## Prueba FastAPI Cloud { #try-fastapi-cloud }
|
||||
|
||||
La financiación principal de FastAPI y amigos viene de [**FastAPI Cloud**](https://fastapicloud.com), una plataforma para desplegar aplicaciones FastAPI de una forma simple y rápida, con un solo comando, `fastapi deploy`.
|
||||
|
||||
FastAPI Cloud está construido por el mismo equipo detrás de FastAPI. Puedes probarlo y considerarlo para tus proyectos.
|
||||
@@ -54,11 +54,11 @@ Todo de una manera que proporcionara la mejor experiencia de desarrollo para tod
|
||||
|
||||
## Requisitos { #requirements }
|
||||
|
||||
Después de probar varias alternativas, decidí que iba a usar [**Pydantic**](https://docs.pydantic.dev/) por sus ventajas.
|
||||
Después de probar varias alternativas, decidí que iba a usar [**Pydantic**](https://pydantic.dev/docs/) 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 [**Starlette**](https://www.starlette.dev/), el otro requisito clave.
|
||||
Durante el desarrollo, también contribuí a [**Starlette**](https://starlette.dev/), el otro requisito clave.
|
||||
|
||||
## Desarrollo { #development }
|
||||
|
||||
|
||||
+19
-17
@@ -110,7 +110,7 @@ Las funcionalidades clave son:
|
||||
</div>
|
||||
<div class="fastapi-opinions__panel" id="fo-panel-uber" role="tabpanel" aria-labelledby="fo-tab-uber" tabindex="0" hidden>
|
||||
<blockquote class="fastapi-opinions__quote">"Adoptamos el paquete <strong>FastAPI</strong> para crear un servidor <strong>REST</strong> que pueda ser consultado para obtener <strong>predicciones</strong>." <em>[para Ludwig]</em></blockquote>
|
||||
<div class="fastapi-opinions__attr">— Piero Molino, Yaroslav Dudin, Sai Sumanth Miryala, <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/">(ref)</a></div>
|
||||
<div class="fastapi-opinions__attr">— Piero Molino, Yaroslav Dudin, Sai Sumanth Miryala, <strong>Uber</strong> <a href="https://www.uber.com/us/en/blog/ludwig-v0-2/">(ref)</a></div>
|
||||
</div>
|
||||
<div class="fastapi-opinions__panel" id="fo-panel-netflix" role="tabpanel" aria-labelledby="fo-tab-netflix" tabindex="0" hidden>
|
||||
<blockquote class="fastapi-opinions__quote">"<strong>Netflix</strong> se complace en anunciar el lanzamiento open source de nuestro framework de orquestación de <strong>gestión de crisis</strong>: <strong>Dispatch</strong>!" <em>[construido con FastAPI]</em></blockquote>
|
||||
@@ -133,7 +133,7 @@ Las funcionalidades clave son:
|
||||
|
||||
"_Adoptamos el paquete **FastAPI** para crear un servidor **REST** que pueda ser consultado para obtener **predicciones**. [para Ludwig]_"
|
||||
|
||||
<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/"><small>(ref)</small></a></div>
|
||||
<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://www.uber.com/us/en/blog/ludwig-v0-2/"><small>(ref)</small></a></div>
|
||||
|
||||
---
|
||||
|
||||
@@ -175,17 +175,17 @@ Si estás construyendo una aplicación de <abbr title="Command Line Interface -
|
||||
|
||||
FastAPI se apoya en hombros de gigantes:
|
||||
|
||||
* [Starlette](https://www.starlette.dev/) para las partes web.
|
||||
* [Pydantic](https://docs.pydantic.dev/) para las partes de datos.
|
||||
* [Starlette](https://starlette.dev/) para las partes web.
|
||||
* [Pydantic](https://pydantic.dev/docs/) para las partes de datos.
|
||||
|
||||
## Instalación { #installation }
|
||||
|
||||
Crea y activa un [entorno virtual](https://fastapi.tiangolo.com/es/virtual-environments/) y luego instala FastAPI:
|
||||
Primero, [instala `uv`](https://docs.astral.sh/uv/getting-started/installation/), y luego añade FastAPI a tu proyecto:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ pip install "fastapi[standard]"
|
||||
$ uv add "fastapi[standard]"
|
||||
|
||||
---> 100%
|
||||
```
|
||||
@@ -194,6 +194,8 @@ $ pip install "fastapi[standard]"
|
||||
|
||||
**Nota**: Asegúrate de poner `"fastapi[standard]"` entre comillas para asegurar que funcione en todas las terminales.
|
||||
|
||||
Si prefieres usar `pip`, instala `fastapi[standard]` dentro de un entorno virtual. Mira la [guía de instalación](tutorial/#install-fastapi) para los pasos alternativos.
|
||||
|
||||
## Ejemplo { #example }
|
||||
|
||||
### Créalo { #create-it }
|
||||
@@ -250,7 +252,7 @@ Corre el servidor con:
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ fastapi dev
|
||||
$ uv run fastapi dev
|
||||
|
||||
╭────────── FastAPI CLI - Development mode ───────────╮
|
||||
│ │
|
||||
@@ -277,7 +279,7 @@ INFO: Application startup complete.
|
||||
<details markdown="1">
|
||||
<summary>Acerca del comando <code>fastapi dev</code>...</summary>
|
||||
|
||||
El comando `fastapi dev` lee tu archivo `main.py` automáticamente, detecta la app **FastAPI** en él y arranca un servidor usando [Uvicorn](https://www.uvicorn.dev).
|
||||
El comando `fastapi dev` lee tu archivo `main.py` automáticamente, detecta la app **FastAPI** en él y arranca un servidor usando [Uvicorn](https://uvicorn.dev).
|
||||
|
||||
Por defecto, `fastapi dev` comenzará con auto-recarga habilitada para el desarrollo local.
|
||||
|
||||
@@ -314,7 +316,7 @@ Verás la documentación interactiva automática de la API (proporcionada por [S
|
||||
|
||||
Y ahora, ve a [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc).
|
||||
|
||||
Verás la documentación alternativa automática (proporcionada por [ReDoc](https://github.com/Rebilly/ReDoc)):
|
||||
Verás la documentación alternativa automática (proporcionada por [ReDoc](https://github.com/Redocly/redoc)):
|
||||
|
||||
|
||||
|
||||
@@ -497,7 +499,7 @@ Opcionalmente puedes desplegar tu app de FastAPI en [FastAPI Cloud](https://fast
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ fastapi deploy
|
||||
$ uv run fastapi deploy
|
||||
|
||||
Deploying to FastAPI Cloud...
|
||||
|
||||
@@ -540,7 +542,7 @@ FastAPI depende de Pydantic y Starlette.
|
||||
|
||||
### Dependencias `standard` { #standard-dependencies }
|
||||
|
||||
Cuando instalas FastAPI con `pip install "fastapi[standard]"` viene con el grupo `standard` de dependencias opcionales:
|
||||
Cuando instalas FastAPI con `uv add "fastapi[standard]"` viene con el grupo `standard` de dependencias opcionales:
|
||||
|
||||
Usadas por Pydantic:
|
||||
|
||||
@@ -554,17 +556,17 @@ Usadas por Starlette:
|
||||
|
||||
Usadas por FastAPI:
|
||||
|
||||
* [`uvicorn`](https://www.uvicorn.dev) - para el servidor que carga y sirve tu aplicación. Esto incluye `uvicorn[standard]`, que incluye algunas dependencias (por ejemplo, `uvloop`) necesarias para servir con alto rendimiento.
|
||||
* [`uvicorn`](https://uvicorn.dev) - para el servidor que carga y sirve tu aplicación. Esto incluye `uvicorn[standard]`, que incluye algunas dependencias (por ejemplo, `uvloop`) necesarias para servir con alto rendimiento.
|
||||
* `fastapi-cli[standard]` - para proporcionar el comando `fastapi`.
|
||||
* Esto incluye `fastapi-cloud-cli`, que te permite desplegar tu aplicación de FastAPI en [FastAPI Cloud](https://fastapicloud.com).
|
||||
|
||||
### Sin Dependencias `standard` { #without-standard-dependencies }
|
||||
|
||||
Si no deseas incluir las dependencias opcionales `standard`, puedes instalar con `pip install fastapi` en lugar de `pip install "fastapi[standard]"`.
|
||||
Si no deseas incluir las dependencias opcionales `standard`, puedes instalar con `uv add fastapi` en lugar de `uv add "fastapi[standard]"`.
|
||||
|
||||
### Sin `fastapi-cloud-cli` { #without-fastapi-cloud-cli }
|
||||
|
||||
Si quieres instalar FastAPI con las dependencias standard pero sin `fastapi-cloud-cli`, puedes instalar con `pip install "fastapi[standard-no-fastapi-cloud-cli]"`.
|
||||
Si quieres instalar FastAPI con las dependencias standard pero sin `fastapi-cloud-cli`, puedes instalar con `uv add "fastapi[standard-no-fastapi-cloud-cli]"`.
|
||||
|
||||
### Dependencias Opcionales Adicionales { #additional-optional-dependencies }
|
||||
|
||||
@@ -572,13 +574,13 @@ Existen algunas dependencias adicionales que podrías querer instalar.
|
||||
|
||||
Dependencias opcionales adicionales de Pydantic:
|
||||
|
||||
* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - para la gestión de configuraciones.
|
||||
* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - para tipos extra para ser usados con Pydantic.
|
||||
* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - para la gestión de configuraciones.
|
||||
* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - para tipos extra para ser usados con Pydantic.
|
||||
|
||||
Dependencias opcionales adicionales de FastAPI:
|
||||
|
||||
* [`orjson`](https://github.com/ijl/orjson) - Requerido si deseas usar `ORJSONResponse`.
|
||||
* [`ujson`](https://github.com/esnme/ultrajson) - Requerido si deseas usar `UJSONResponse`.
|
||||
* [`ujson`](https://github.com/ultrajson/ultrajson) - Requerido si deseas usar `UJSONResponse`.
|
||||
|
||||
## Licencia { #license }
|
||||
|
||||
|
||||
@@ -4,13 +4,13 @@ Las plantillas, aunque normalmente vienen con una configuración específica, es
|
||||
|
||||
Puedes usar esta plantilla para comenzar, ya que incluye gran parte de la configuración inicial, seguridad, base de datos y algunos endpoints de API ya hechos para ti.
|
||||
|
||||
Repositorio de GitHub: [Plantilla Full Stack FastAPI](https://github.com/tiangolo/full-stack-fastapi-template)
|
||||
Repositorio de GitHub: [Plantilla Full Stack FastAPI](https://github.com/fastapi/full-stack-fastapi-template)
|
||||
|
||||
## Plantilla Full Stack FastAPI - Stack de tecnología y funcionalidades { #full-stack-fastapi-template-technology-stack-and-features }
|
||||
|
||||
- ⚡ [**FastAPI**](https://fastapi.tiangolo.com/es) para la API del backend en Python.
|
||||
- 🧰 [SQLModel](https://sqlmodel.tiangolo.com) para las interacciones con bases de datos SQL en Python (ORM).
|
||||
- 🔍 [Pydantic](https://docs.pydantic.dev), utilizado por FastAPI, para la validación de datos y gestión de configuraciones.
|
||||
- 🔍 [Pydantic](https://pydantic.dev/docs/), utilizado por FastAPI, para la validación de datos y gestión de configuraciones.
|
||||
- 💾 [PostgreSQL](https://www.postgresql.org) como base de datos SQL.
|
||||
- 🚀 [React](https://react.dev) para el frontend.
|
||||
- 💃 Usando TypeScript, hooks, Vite, y otras partes de una stack moderna de frontend.
|
||||
|
||||
@@ -269,7 +269,7 @@ No significa "`one_person` es la **clase** llamada `Person`".
|
||||
|
||||
## Modelos Pydantic { #pydantic-models }
|
||||
|
||||
[Pydantic](https://docs.pydantic.dev/) es un paquete de Python para realizar la validación de datos.
|
||||
[Pydantic](https://pydantic.dev/docs/) es un paquete de Python para realizar la validación de datos.
|
||||
|
||||
Declaras la "forma" de los datos como clases con atributos.
|
||||
|
||||
@@ -285,7 +285,7 @@ Un ejemplo de la documentación oficial de Pydantic:
|
||||
|
||||
/// note | Nota
|
||||
|
||||
Para saber más sobre [Pydantic, revisa su documentación](https://docs.pydantic.dev/).
|
||||
Para saber más sobre [Pydantic, revisa su documentación](https://pydantic.dev/docs/).
|
||||
|
||||
///
|
||||
|
||||
|
||||
@@ -1,864 +1,35 @@
|
||||
# Entornos Virtuales { #virtual-environments }
|
||||
|
||||
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.
|
||||
Cuando trabajas con proyectos de Python, deberías usar un **entorno virtual** para aislar los paquetes instalados para cada proyecto.
|
||||
|
||||
/// note | Nota
|
||||
|
||||
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.
|
||||
|
||||
///
|
||||
|
||||
/// note | Nota
|
||||
|
||||
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 [uv](https://github.com/astral-sh/uv).
|
||||
|
||||
///
|
||||
Para proyectos de FastAPI, recomiendo usar [uv](https://docs.astral.sh/uv/) para gestionar el proyecto, sus dependencias y su entorno virtual.
|
||||
|
||||
## Crea un Proyecto { #create-a-project }
|
||||
|
||||
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.
|
||||
Instala `uv` usando la [guía oficial de instalación](https://docs.astral.sh/uv/getting-started/installation/), y luego crea un 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
|
||||
$ uv init awesome-project --bare
|
||||
$ cd awesome-project
|
||||
$ uv add "fastapi[standard]"
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
## Crea un Entorno Virtual { #create-a-virtual-environment }
|
||||
`uv` crea un entorno virtual para el proyecto automáticamente. No necesitas crear ni activar uno tú mismo.
|
||||
|
||||
Cuando empiezas a trabajar en un proyecto de Python **por primera vez**, crea un entorno virtual **<dfn title="hay otras opciones, esto es solo una guía sencilla">dentro de tu proyecto</dfn>**.
|
||||
|
||||
/// 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.
|
||||
Ejecuta comandos dentro del entorno del proyecto con `uv run`, por ejemplo:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ python -m venv .venv
|
||||
$ uv run fastapi dev
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
/// details | Qué significa ese comando
|
||||
## Aprende Más { #learn-more }
|
||||
|
||||
* `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 [`uv`](https://github.com/astral-sh/uv), 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 { #activate-the-virtual-environment }
|
||||
|
||||
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, [Git Bash](https://gitforwindows.org/)):
|
||||
|
||||
<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 - interfaz de línea de comandos">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.
|
||||
|
||||
///
|
||||
|
||||
## Revisa que el Entorno Virtual esté Activo { #check-the-virtual-environment-is-active }
|
||||
|
||||
Revisa 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` { #upgrade-pip }
|
||||
|
||||
/// tip | Consejo
|
||||
|
||||
Si usas [`uv`](https://github.com/astral-sh/uv) 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>
|
||||
|
||||
/// tip | Consejo
|
||||
|
||||
A veces, podrías obtener un error **`No module named pip`** al intentar actualizar pip.
|
||||
|
||||
Si esto pasa, instala y actualiza pip usando el siguiente comando:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ python -m ensurepip --upgrade
|
||||
|
||||
---> 100%
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
Este comando instalará pip si aún no está instalado y también se asegura de que la versión instalada de pip sea al menos tan reciente como la disponible en `ensurepip`.
|
||||
|
||||
///
|
||||
|
||||
## Añade `.gitignore` { #add-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 [`uv`](https://github.com/astral-sh/uv) 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 la terminal (la siguiente parte cambia eso un poco)
|
||||
* `>`: cualquier cosa impresa en la 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 { #install-packages }
|
||||
|
||||
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 { #install-packages-directly }
|
||||
|
||||
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 [`uv`](https://github.com/astral-sh/uv):
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ uv pip install "fastapi[standard]"
|
||||
---> 100%
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
////
|
||||
|
||||
### Instala desde `requirements.txt` { #install-from-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 [`uv`](https://github.com/astral-sh/uv):
|
||||
|
||||
<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 { #run-your-program }
|
||||
|
||||
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 { #configure-your-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:
|
||||
|
||||
* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment)
|
||||
* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html)
|
||||
|
||||
/// tip | Consejo
|
||||
|
||||
Normalmente solo tendrías que hacer esto **una vez**, cuando crees el entorno virtual.
|
||||
|
||||
///
|
||||
|
||||
## Desactiva el Entorno Virtual { #deactivate-the-virtual-environment }
|
||||
|
||||
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 { #ready-to-work }
|
||||
|
||||
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 { #why-virtual-environments }
|
||||
|
||||
Para trabajar con FastAPI necesitas instalar [Python](https://www.python.org/).
|
||||
|
||||
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 { #the-problem }
|
||||
|
||||
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 { #where-are-packages-installed }
|
||||
|
||||
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 [PyPI](https://pypi.org/project/fastapi/).
|
||||
|
||||
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 { #what-are-virtual-environments }
|
||||
|
||||
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 { #what-does-activating-a-virtual-environment-mean }
|
||||
|
||||
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, [Git Bash](https://gitforwindows.org/)):
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ source .venv/Scripts/activate
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
////
|
||||
|
||||
Ese comando creará o modificará algunas [variables de entorno](environment-variables.md) 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).
|
||||
|
||||
///
|
||||
|
||||
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 la 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 la 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.
|
||||
|
||||
## Revisando un Entorno Virtual { #checking-a-virtual-environment }
|
||||
|
||||
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 { #why-deactivate-a-virtual-environment }
|
||||
|
||||
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 la 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-azkaban` 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 { #alternatives }
|
||||
|
||||
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 [uv](https://github.com/astral-sh/uv).
|
||||
|
||||
`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 { #conclusion }
|
||||
|
||||
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**. 😎
|
||||
Lee la [guía de Entornos Virtuales](https://tiangolo.com/guides/virtual-environments/) para aprender cómo funcionan los entornos virtuales por debajo, incluyendo la activación y el flujo de trabajo alternativo con `python -m venv` y `pip`.
|
||||
Reference in new issue
Block a user