Lista de verificación de configuración del entorno
Python 3.14, uv, editor y configuración de herramientas: obtén desde la clonación hasta las pruebas en verde en minutos en macOS o Linux.
Cómo usar esta lista de verificación
- Completa en orden en una máquina nueva o en una clonación de repositorio nueva.
- Marca cada casilla antes de pasar a los pasos específicos de la aplicación.
- Si un paso falla, detente y soluciona el problema; no omitas los pasos de lockfile o venv.
- Pega las versiones exactas de
pyproject.tomlal informar problemas de configuración.
Runtime Principal
- Instalar uv 0.6+:
curl -LsSf https://astral.sh/uv/install.sh | sho el administrador de paquetes según la política de la organización. - Instalar Python 3.14:
uv python install 3.14si no está instalado en todo el sistema. - Clonar repositorio: Clave SSH configurada;
git clone git@github.com:acme/service.git. - Entrar al proyecto:
cd service- confirma la presencia depyproject.tomlyuv.lock. - Sincronizar dependencias:
uv sync --all-extras(o--extra devsegún README).
Herramientas de Calidad
- Ejecutar linter:
uv run ruff check .- cero errores en una rama principal limpia. - Comprobar formato:
uv run ruff format --check .o formatear una vez. - Ejecutar pruebas:
uv run pytest -q- suite completa o subconjunto del README para la primera pasada. - Comprobación de tipos (si está configurada):
uv run mypy src/ouv run pyright. - Instalar pre-commit:
uv run pre-commit instally luegopre-commit run --all-files.
Configuración de la Aplicación
- Copiar plantilla de entorno:
cp .env.example .env- completar los valores locales desde 1Password/documento de bóveda. - Nunca confirmar
.env: Confirmar que está listado en.gitignore. - Base de datos (si es necesario): Docker compose
docker compose up -d dbo Postgres local documentado. - Migraciones:
uv run alembic upgrade headomigratede Django según el proyecto. - Iniciar servidor de desarrollo:
uv run uvicorn app.main:app --reload- hacercurl /health.
Editor y Git
- Intérprete de Python del editor: Apuntar a
.venv/bin/pythoncreado por uv. - Extensión Ruff: Formatear al guardar alineado con la longitud de línea de
pyproject.toml. - Identidad de Git:
user.nameyuser.emailconfigurados (Configuración de Git). - GitHub CLI (opcional):
gh auth loginpara el flujo de trabajo de PR. - PATH del shell:
~/.local/binpara herramientas pipx (httpie, copier).
Puerta de Verificación
- Repetir CI localmente: Mismos comandos que en
.github/workflows/pr.yml(ruff, pytest, mypy). - Prueba HTTP básica:
curl -sf http://localhost:8000/healthdevuelve 200. - Saneamiento de importación:
uv run python -c "import app"sinImportError. - Bloqueadores documentados: Abrir un issue o hilo de Slack con la salida de error exacta si algún paso falla.
- Confirmar con un compañero: Captura de pantalla o pegar el resumen de la terminal en el ticket de incorporación.
Preguntas frecuentes
¿uv sync falla en Apple Silicon?
Verificar las ruedas para dependencias nativas (torch, etc.) - usar extras documentados o índice solo para CPU.
¿Se seleccionó la versión incorrecta de Python?
uv python pin 3.14 en el proyecto o archivo .python-version según README.
¿poetry.lock en una rama antigua?
Seguir la nota de migración del README - puede que necesites hacer rebase primero sobre el commit de migración de uv.
¿Desarrolladores de Windows?
Se recomienda WSL2 Ubuntu; la misma lista de verificación dentro de WSL.
Relacionados
- uv - La Cadena de Herramientas Rápida - Profundidad de uv
- Lista de verificación de incorporación de desarrolladores - rampa completa
- Python en la Shell - uso de la shell
- Gestión de versiones de Python - política de versiones
Versiones de la pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), 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+.