Buenas Prácticas para Entornos
Reglas prácticas para mantener los entornos de Python aislados, reproducibles y amigables para el equipo.
Cómo Usar Esta Lista
- Aplica estas reglas al iniciar un nuevo repositorio o al incorporar a un compañero de equipo.
- Aplica los elementos relacionados con CI en las comprobaciones de las solicitudes de extracción (pull requests).
- Revisa trimestralmente a medida que evolucionan las herramientas (uv, ruff).
A - Aislamiento
- Un entorno virtual por proyecto. Nunca instales dependencias del proyecto en el Python del sistema.
- Confirma
.python-versiono fija la versión enpyproject.toml. Todos ejecutan el mismo intérprete. - Añade
.venv/a.gitignore. Los entornos son reproducibles a partir de los archivos de bloqueo (lockfiles), no se copian. - Documenta los tres comandos de arranque en el README. Clonar, sincronizar, probar: nada más es necesario.
B - Reproducibilidad
- Confirma el archivo de bloqueo (
uv.lock,poetry.lockopdm.lock). La CI y producción instalan paquetes idénticos. - Usa
uv sync --frozen(o equivalente) en CI. Las compilaciones fallan si el archivo de bloqueo está obsoleto. - Declara
requires-pythonenpyproject.toml. Bloquea las instalaciones en intérpretes no compatibles. - Separa los grupos de dependencias de desarrollo y producción. Los contenedores de producción excluyen pytest, ruff, mypy.
C - Estructura del Proyecto
- Usa la estructura
src/con instalaciones editables. Las pruebas importan el paquete instalado, no la raíz del repositorio. - Mantén toda la configuración en
pyproject.toml. Un archivo para metadatos, dependencias, ruff, pytest, mypy. - Prefiere
uvpara nuevos proyectos. Instalaciones rápidas, archivo de bloqueo integrado, gestión de versiones de Python. - Usa el modo de espacio de trabajo (workspace mode) para monorepos. Los paquetes locales se referencian entre sí sin trucos de rutas.
D - Seguridad y Acceso
- Nunca confirmes credenciales o tokens. Usa variables de entorno, secretos de CI o
~/.netrc. - Audita las dependencias regularmente. Ejecuta
pip-auditouv pip auditen CI semanalmente. - Fija los paquetes internos a un índice privado. Documenta la URL del índice y la autenticación para la CI.
- Usa HTTPS para todos los índices de paquetes. No uses HTTP sin cifrar en las canalizaciones de producción.
E - Flujo de Trabajo en Equipo
- Estandariza un gestor de paquetes por repositorio. No mezcles archivos de bloqueo de pip, Poetry y uv.
- Ejecuta
uv lockdespués de cualquier cambio de dependencia. Manténpyproject.tomly el archivo de bloqueo sincronizados. - Exporta
requirements.txtsolo para etapas heredadas de Docker. El archivo de bloqueo es la fuente de verdad. - Prueba el arranque del README en una máquina limpia trimestralmente. Detecta la deriva de la documentación antes que los nuevos miembros del equipo.
Preguntas Frecuentes
¿Deben las bibliotecas confirmar archivos de bloqueo?
Las bibliotecas publican rangos de versiones. Las aplicaciones y servicios deben confirmar archivos de bloqueo.
¿uv o Poetry para un nuevo equipo?
uv por velocidad y simplicidad. Poetry si el equipo ya tiene flujos de trabajo y formación maduros con Poetry.
¿Cómo migro desde requirements.txt?
Crea pyproject.toml, importa las dependencias con uv add o pdm import, genera un archivo de bloqueo, elimina requirements.txt.
¿Qué va en .gitignore además de .venv?
__pycache__/, *.egg-info/, .mypy_cache/, .ruff_cache/, dist/, .env.
¿Debe la CI crear el venv o usar uno en caché?
Caché del venv indexado por el hash del archivo de bloqueo. Recrear cuando el hash cambie.
¿Cómo manejo dependencias específicas de la plataforma?
Usa marcadores de entorno en pyproject.toml: sys_platform == 'win32'.
¿Un único venv global para todos los proyectos?
No. El aislamiento previene conflictos de versiones entre proyectos.
¿Cuándo debo actualizar Python?
Cuando finaliza el soporte de seguridad para tu versión actual o cuando necesitas nuevas características del lenguaje. Prueba primero en una rama.
¿Cómo comparto variables de entorno de forma segura?
.env.example con valores ficticios en el repositorio. .env real ignorado por git. La CI usa almacenes de secretos.
¿Qué pasa con Docker y los venvs?
En Docker, instala las dependencias globalmente en el contenedor (no se necesita venv). En el host, usa siempre un venv.
Relacionado
- Conceptos Básicos de Entornos y Empaquetado - para empezar
- uv - La Cadena de Herramientas Rápida - cadena de herramientas recomendada
- Resolución de Dependencias y Archivos de Bloqueo - política de fijación
- Gestión de Versiones de Python - estrategia de versiones
Versiones de la Pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.