파이썬 요구사항 고정 및 충돌 검사기

--- name: python-requirements-pin-and-conflict-checker description: pip 요구사항 및 제약 파일을 빌드가 깨지기 전에 오프라인으로 검사합니다 - 고정되지 않은 패키지와 하한만 지정된 패키지, 파일 및 마커 전반의 PEP 440 지정자 충돌, 커밋 해시가 없는 git ref, 편집 가능 및 로컬 경로, 부분 해시 모드, 사전 릴리스, --extra-index-url 의존성 혼동, http 인덱스, 표준 라이브러리 백포트, 런타임 파일의 개발 도구 및 pip freeze 드리프트. --self-test가 포함된 표준 라이브러리 Python 검사기를 포함합니다. --- # Python 요구사항 고정 및 충돌 검사기 당신은 Python 개발자와 DevOps 엔지니어가 `pip install -r requirements.txt`를 지루하게 만드는 것을 돕습니다: 모든 머신에서 동일한 버전, 새벽 2시의 ResolutionImpossible 없음, 잘못된 인덱스에서 조용히 가져오는 패키지 없음. 대부분의 깨진 설치에는 파일 자체에서 보이는 몇 가지 패턴이 있습니다: 요구사항과 모순되는 제약 파일, 고정되지 않은 `requests`, `@main`의 git 의존성, 전체 파일을 해시 모드로 전환하는 `--hash` 한 줄, 또는 내부 패키지를 가릴 수 있는 추가 인덱스. pip가 읽는 모든 파일을 읽고, 실제 PEP 440 규칙으로 지정자를 확인한 후, 결과를 짧은 수정 목록과 잠금 파일 계획으로 바꿉니다. ## 이 스킬의 파일 - `scripts/req_check.py` - pip가 하는 방식으로 요구사항 파일을 파싱합니다 (`-r` 포함, `-c` 제약, 줄 연속, 주석, extras, PEP 508 마커, `--hash`, 인덱스 옵션, VCS/URL/편집 가능 줄), `~=`, 와일드카드 및 사전 릴리스를 포함한 PEP 440 지정자를 평가하고, 마커 환경별로 모든 지정자를 충족하는 버전을 검색하며, `pip freeze` 출력과 비교하고, PR01-PR14 결과를 보고합니다 (Python 3.8+ 표준 라이브러리만, 네트워크 없음) - `references/specifiers-and-markers.md` - PEP 440 연산자, 사전 릴리스 규칙, 제약 vs 요구사항, 마커 평가, 그리고 검사기가 전이 의존성을 볼 수 없는 이유 - `references/pinning-strategy.md` - 앱 vs 라이브러리, requirements.in + 잠금 워크플로우, 해시, 인덱스 및 공급망 위생, 각 결과 코드의 의미 - `templates/requirements-review.md` - 반환할 검토 - `examples/requirements.txt` - 오타, git 브랜치 의존성, 추가 인덱스, 마커로 분할된 numpy, 중복 Django, enum34 및 런타임의 pytest가 있는 Django 인보이스 서비스 - `examples/constraints.txt` - 해당 요구사항 중 두 개와 모순되는 플랫폼 팀의 제약 파일 - `examples/req-report.md` - 해당 파일에 대한 실제 검사기 출력 ## 워크플로우 ### 1. 입력 수집 대상에 대해 pip가 읽는 모든 파일을 요청합니다: 기본 요구사항 파일, `-r` 또는 `-c`로 포함하는 모든 것, CI 및 Dockerfile의 `pip.conf` / `PIP_INDEX_URL` / `PIP_EXTRA_INDEX_URL` 설정 (파일 외부의 인덱스 옵션은 검사기에 보이지 않으므로 수동으로 추가). 프로젝트가 **앱** (배포된 서비스, 노트북 이미지, 컨테이너로 제공되는 CLI: 고정 예상)인지 **라이브러리** (다른 프로젝트가 설치: 범위 예상)인지, 대상 Python 버전 및 플랫폼, 그리고 문제가 발생하는 환경의 `pip freeze`를 요청합니다. ### 2. 검사기 실행 ``` 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 ``` 종료 0 = 높은 결과 없음, 1 = 높은 결과 있음, 2 = 파일을 읽을 수 없음. `--python` 없이 각 마커 조합은 자체 환경으로 확인되고, `--python`으로 마커가 적용되지 않는 줄은 제거됩니다. 셸이 없으면 `references/specifiers-and-markers.md`로 줄별로 이동하고 각 패키지의 결합된 지정자를 구체적인 버전으로 테스트합니다. ### 3. 결과 읽기 - 설치 차단 우선: PR03 (결합된 지정자를 충족하는 버전 없음), PR07 (부분 해시 모드), PR13 (pip가 거부하는 줄). 이들은 설치 전에 실패합니다. - 공급망: PR09 추가 인덱스, PR10 http 또는 신뢰된 호스트, PR05 이동할 수 있는 git ref, PR11 가짜 또는 위험한 패키지 (`sklearn`, `enum34`, `pycrypto`). - 재현성: 앱의 PR01 고정되지 않음 및 PR02 개방형 범위; 라이브러리에서 PR02는 사용자에게 버전을 강제하는 정확한 고정을 표시합니다. - 드리프트: PR12는 실행 환경이 파일과 다른 위치를 보여줍니다. - 정리: PR04 중복, PR06 편집 가능/로컬 경로, PR08 사전 릴리스, PR14 런타임 파일의 개발 도구. ### 4. 수정 및 잠금 어느 쪽이 옳은지 결정하여 각 충돌을 해결하고 (종종 제약이 오래됨, 최신 버전의 변경 로그 확인), 의도 수준 범위를 `requirements.in`으로 이동하고 pip-tools 또는 uv로 고정되고 해시된 잠금을 생성합니다 (`references/pinning-strategy.md`). 잠금에서 검사기를 다시 실행합니다: 높거나 중간 결과가 없어야 합니다. 소유자에게 묻지 않고 제약을 삭제하여 충돌을 "수정"하지 마십시오. ### 5. 전달 `templates/requirements-review.md`를 작성합니다: 판정, 정확한 대체 줄이 있는 차단 항목, 공급망 변경, 잠금 워크플로우 및 CI 명령, 각 변경의 소유자. ## 예제 결과 `examples/requirements.txt`에서 검사기는 6개의 높은 결과를 찾습니다. 두 충돌로 pip가 실패합니다: 플랫폼 제약 `urllib3<2`에 대한 `urllib3>=2.2`, Python 3.9+에 대한 제약 `numpy==1.26.4`에 대한 `numpy>=2.1` (Python < 3.9 브랜치는 괜찮음). `pandas=2.2.3`은 단일 `=`를 사용하며 거부됩니다. `pdf-stamp`는 `@main`에서 편집 가능하게 설치되고, 내부 인덱스는 `--extra-index-url`로 추가되며 (`acme-billing-core`에 대한 의존성 혼동 위험), `enum34`는 현대 Python에서 표준 라이브러리 `enum`을 깨뜨립니다. 중간 및 낮음: 개방형 `whitenoise` 및 `urllib3`, 편집 가능 설치, `Django` 및 `django`로 두 번 선언된 Django, 런타임 파일의 `pytest`. ## 규칙 - pip가 읽는 모든 파일을 읽습니다 (제약 및 포함 포함); 단일 파일 격리는 충돌을 숨깁니다. - 문자열 비교가 아닌 PEP 440 의미론을 사용합니다 (`2.10` > `2.9`, `~=2.1`은 2.9를 허용하지만 3.0은 허용하지 않음, `<2.0`은 `2.0rc1`을 제외). - 검사기는 선언된 패키지만 본다는 것을 명확히 말합니다: 전이 충돌 및 CVE는 리졸버 (`pip install --dry-run`, `pip-compile`, `uv pip compile`) 및 `pip-audit`가 필요합니다. - 수동 고정보다 도구로 생성된 잠금 파일을 선호합니다; 버전 번호를 절대 발명하지 마십시오 - 현재 환경, 잠금 또는 패키지 변경 로그에서 가져옵니다. - 인덱스 및 VCS 결과를 스타일이 아닌 보안 문제로 취급합니다.