Comprobador de Requisitos de Python y Conflictos

--- name: python-requirements-pin-and-conflict-checker description: Comprueba los archivos de requisitos y restricciones de pip sin conexión antes de que rompan una compilación - paquetes sin fijar y solo con límite inferior, conflictos de especificadores PEP 440 entre archivos y marcadores, referencias git sin hash de commit, rutas editables y locales, modo hash parcial, pre-lanzamientos, confusión de dependencias con --extra-index-url, índices http, backports de la biblioteca estándar, herramientas de desarrollo en archivos de tiempo de ejecución y desviación de pip freeze. Incluye un verificador de la biblioteca estándar de Python con --self-test. --- # Verificador de Fijación y Conflictos de Requisitos de Python Ayudas a desarrolladores de Python e ingenieros de DevOps a hacer que `pip install -r requirements.txt` sea aburrido: las mismas versiones en cada máquina, sin ResolutionImpossible a las 2 a.m., sin paquetes obtenidos silenciosamente del índice equivocado. La mayoría de las instalaciones rotas provienen de unos pocos patrones que son visibles en los propios archivos: un archivo de restricciones que contradice un requisito, `requests` sin fijar, una dependencia git en `@main`, una línea con `--hash` que cambia todo el archivo al modo hash, o un índice extra que permite que un paquete público eclipse a uno interno. Lees cada archivo que pip leería, verificas los especificadores con reglas reales de PEP 440, y conviertes el resultado en una lista corta de correcciones y un plan de archivo de bloqueo. ## Archivos en esta habilidad - `scripts/req_check.py` - analiza archivos de requisitos como lo hace pip (incluye `-r`, restricciones `-c`, continuaciones de línea, comentarios, extras, marcadores PEP 508, `--hash`, opciones de índice, líneas VCS/URL/editables), evalúa especificadores PEP 440 incluyendo `~=`, comodines y pre-lanzamientos, busca una versión que satisfaga cada especificador por entorno de marcador, compara con la salida de `pip freeze`, e informa hallazgos PR01-PR14 (solo biblioteca estándar de Python 3.8+, sin red) - `references/specifiers-and-markers.md` - operadores PEP 440, reglas de pre-lanzamiento, restricciones vs requisitos, evaluación de marcadores, y por qué el verificador no puede ver dependencias transitivas - `references/pinning-strategy.md` - aplicaciones vs bibliotecas, el flujo de trabajo requirements.in + bloqueo, hashes, índices e higiene de la cadena de suministro, y qué significa cada código de hallazgo - `templates/requirements-review.md` - la revisión para devolver - `examples/requirements.txt` - un servicio de facturación Django con un error tipográfico, una dependencia de rama git, un índice extra, numpy dividido por marcador, Django duplicado, enum34 y pytest en tiempo de ejecución - `examples/constraints.txt` - el archivo de restricciones del equipo de plataforma que contradice dos de esos requisitos - `examples/req-report.md` - la salida real del verificador en esos archivos ## Flujo de trabajo ### 1. Recopilar las entradas Pide cada archivo que pip lee para el objetivo: el archivo de requisitos principal, cualquier cosa que incluya con `-r` o `-c`, más la configuración de `pip.conf` / `PIP_INDEX_URL` / `PIP_EXTRA_INDEX_URL` de CI y Dockerfiles (las opciones de índice fuera del archivo son invisibles para el verificador; agrégalas a mano). Pregunta si el proyecto es una **aplicación** (servicio desplegado, imagen de notebook, CLI enviado como contenedor: se esperan fijaciones) o una **biblioteca** (instalada por otros proyectos: se esperan rangos), qué versiones de Python y plataformas objetivo tiene, y un `pip freeze` del entorno que se comporta mal. ### 2. Ejecutar el verificador ``` python3 scripts/req_check.py examples/requirements.txt python3 scripts/req_check.py requirements.txt --python 3.12 --platform linux python3 scripts/req_check.py requirements.txt requirements-dev.txt --installed freeze.txt python3 scripts/req_check.py requirements.txt --mode lib --json python3 scripts/req_check.py --self-test ``` Salida 0 = sin hallazgos altos, 1 = hallazgos altos, 2 = un archivo no pudo leerse. Sin `--python`, cada combinación de marcadores se verifica como su propio entorno; con él, las líneas cuyos marcadores no aplican se descartan. Sin un shell, ve línea por línea con `references/specifiers-and-markers.md` y prueba los especificadores combinados de cada paquete contra una versión concreta. ### 3. Leer el resultado - Bloqueadores de instalación primero: PR03 (ninguna versión satisface los especificadores combinados), PR07 (modo hash parcial), PR13 (líneas que pip rechaza). Estos fallan antes de que cualquier cosa se instale. - Cadena de suministro: PR09 índice extra, PR10 http o hosts de confianza, PR05 referencias git que pueden moverse, PR11 paquetes falsos o peligrosos (`sklearn`, `enum34`, `pycrypto`). - Reproducibilidad: PR01 sin fijar y PR02 rangos abiertos en aplicaciones; en bibliotecas, PR02 marca fijaciones exactas que forzarían versiones a los usuarios. - Desviación: PR12 muestra dónde difiere el entorno en ejecución de los archivos. - Limpiezas: PR04 duplicados, PR06 rutas editables/locales, PR08 pre-lanzamientos, PR14 herramientas de desarrollo en archivos de tiempo de ejecución. ### 4. Corregir y bloquear Resuelve cada conflicto decidiendo qué lado es correcto (a menudo la restricción está desactualizada; revisa el registro de cambios de la versión más nueva), luego mueve los rangos a nivel de intención a `requirements.in` y genera el bloqueo fijado y con hash con pip-tools o uv (`references/pinning-strategy.md`). Vuelve a ejecutar el verificador en el bloqueo: debería volver sin hallazgos altos o medios. Nunca "arregles" un conflicto eliminando la restricción sin preguntar quién la posee. ### 5. Entregar Completa `templates/requirements-review.md`: veredicto, bloqueadores con líneas de reemplazo exactas, cambios de cadena de suministro, el flujo de trabajo de bloqueo y comandos de CI, y un propietario para cada cambio. ## Resultado de ejemplo En `examples/requirements.txt` el verificador encuentra 6 hallazgos altos. Dos conflictos hacen fallar a pip: `urllib3>=2.2` contra la restricción de plataforma `urllib3<2`, y `numpy>=2.1` contra la restricción `numpy==1.26.4` para Python 3.9+ (la rama de Python < 3.9 está bien). `pandas=2.2.3` usa un solo `=` y es rechazado. `pdf-stamp` se instala editable desde `@main`, el índice interno se agrega con `--extra-index-url` (riesgo de confusión de dependencias para `acme-billing-core`), y `enum34` rompe el `enum` de la biblioteca estándar en Python moderno. Medio y bajo: `whitenoise` y `urllib3` de extremo abierto, la instalación editable, Django declarado dos veces como `Django` y `django`, y `pytest` en el archivo de tiempo de ejecución. ## Reglas - Lee cada archivo que pip lee, incluyendo restricciones e inclusiones; un solo archivo aislado oculta conflictos. - Usa semántica PEP 440, no comparación de cadenas (`2.10` > `2.9`, `~=2.1` permite 2.9 pero no 3.0, `<2.0` excluye `2.0rc1`). - Di claramente que el verificador solo ve paquetes declarados: los conflictos transitivos y CVEs necesitan el resolvedor (`pip install --dry-run`, `pip-compile`, `uv pip compile`) y `pip-audit`. - Prefiere un archivo de bloqueo generado por una herramienta sobre fijaciones manuales; nunca inventes números de versión - tómalos del entorno actual, el bloqueo, o el registro de cambios del paquete. - Trata los hallazgos de índice y VCS como problemas de seguridad, no de estilo.