PEP 625 – 소스 배포판의 파일 이름

Author:: Tzu-ping Chung <uranusjr at gmail.com>, Paul Moore <p.f.moore at gmail.com>
PEP-Delegate:: Pradyun Gedam <pradyunsg at gmail.com>
Discussions-To:: Discourse thread
Status:: Final
Type:: Standards Track
Topic:: Packaging
Created:: 08-Jul-2020
Post-History:: 08-Jul-2020
Resolution:: Discourse message

Table of Contents

초록
동기
근거
명세
하위 호환성
기각된 아이디어
미해결 문제
참고 문헌
Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

Important

This PEP is a historical document. The up-to-date, canonical spec, Source distribution file name, is maintained on the PyPA specs page.

See the PyPA specification update process for how to propose changes.

초록

이 PEP는 sdist라고도 불리는 소스 배포판(Source Distribution)의 표준 명명 체계를 설명합니다. sdist는 Python 패키지의 소스 코드를 담은 임의의 아카이브 파일과는 구별되며, 배포에 관한 정보를 패키징 도구에 전달하는 데 사용될 수 있습니다.

여기서 규정하는 표준 sdist는 특별한 형식의 파일 이름과 일반적인 .tar.gz 접미사를 가진, gzip으로 압축된 tar 파일입니다. tarball의 내용은 다른 명세에서 다루므로 이 PEP에서는 규정하지 않습니다.

동기

sdist는 Python 패키지의 “소스 코드”를 담은 Python 패키지 배포이며, 설치 시 wheel로 변환되려면 빌드 단계가 필요합니다. 이 형식은 흔히 PEP 427 wheel의 빌드되지 않은 대응물로 여겨지며, 패키징 생태계의 여러 부분에서 특별하게 취급됩니다.

sdist의 내용은 PEP 517과 PEP 643에 규정되어 있지만, 현재 sdist의 파일 이름은 불완전하게 규정되어 있습니다. 따라서 이 형식을 사용하는 쪽은 안에 포함된 배포판의 이름과 버전을 확인하려면 sdist를 내려받아 처리해야 합니다.

현재 설치 프로그램은 설치 과정을 돕기 위해 휴리스틱에 의존하여 파일 이름에서 이름이나 버전, 또는 둘 다를 추론합니다. 예를 들어 pip은 의존성 해결을 위해 배포의 프로젝트 이름과 버전을 얻고자 PEP 503 색인에서 가져온 sdist의 파일 이름을 파싱합니다. 그러나 명세가 없기 때문에 설치 프로그램은 추론한 데이터가 올바르다는 보장을 전혀 받지 못하며, 어느 시점에는 배포 메타데이터를 로컬에서 빌드하여 이를 검증해야 합니다.

사용자가 빌드 과정이 일어나리라 예상하지 않는 특정 부류의 작업에서는 이 빌드 단계가 불편을 초래합니다. pypa/pip#8387에 그 예가 설명되어 있습니다. pip download --no-deps --no-binary=numpy numpy 명령은 numpy의 sdist만 내려받을 것으로 예상됩니다. 의존성을 확인할 필요가 없고, 이름과 버전 모두 내려받은 파일 이름을 살펴보면 알 수 있기 때문입니다. 그러나 pip는 내려받은 아카이브가 이 관례를 따른다고 가정할 수 없으므로 메타데이터를 빌드하고 확인해야 합니다. PEP 518 프로젝트의 경우, 이는 PEP 517에 규정된 prepare_metadata_for_build_wheel 훅을 실행한다는 뜻이며, 이 때문에 상당한 오버헤드가 발생합니다.

근거

이 PEP는 sdist 형식에 특별한 파일 이름 체계를 만들어, 도구가 파일 이름에 담긴 메타데이터만 필요로 할 때 시간이 많이 드는 메타데이터 검증 단계를 거치지 않아도 되게 합니다.

이 PEP는 또한 현재 sdist 구현들이 오랫동안 사용해 온 파일 이름 관례의 공식 명세 역할도 합니다. 파일 이름에는 배포 이름과 버전이 들어 있으므로, 도구에 필요한 정보가 모두 파일 이름에 있다면 도구는 파일을 다운로드하고 압축을 풀고 인트로스펙션을 위해 비용이 큰 메타데이터 생성을 수행할 필요 없이 배포를 식별할 수 있습니다.

명세

sdist의 이름은 {distribution}-{version}.tar.gz여야 합니다.

distribution은 PEP 345에 정의된 배포판 이름이며, the wheel spec에 설명된 대로 정규화됩니다(예: 'pip', 'flit_core').
version은 PEP 440에 정의된 배포판 버전이며(예: 20.2), 해당 PEP의 규칙에 따라 정규화됩니다.

sdist는 pax 형식의 gzip 압축 tar 아카이브여야 하며, 표준 라이브러리 tarfile 모듈에서 열기 플래그 'r:gz'로 추출할 수 있어야 합니다.

sdist 파일을 생성하는 코드는 반드시(MUST) 이 명세에 맞는 이름을 파일에 부여해야 합니다. PEP 517의 build_sdist 훅 명세는 이 명명 관례를 요구하도록 확장됩니다.

sdist 파일을 처리하는 코드는 파일 이름을 파싱하는 것만으로 배포판 이름과 버전을 결정할 수 있으며(MAY), sdist 내용에서 메타데이터를 생성하거나 읽어 그 정보를 검증하지 않아도 됩니다.

규격에 맞는 sdist 파일은 .tar.gz 접미사가 있고 파일 이름에 하이픈이 하나만 있는지로 식별할 수 있습니다. 일부 레거시 파일도 이 기준에 부합할 수 있지만, 실제로는 문제가 되지 않을 것으로 예상됩니다. 자세한 내용은 이 문서의 “하위 호환성” 절을 참고하십시오.

하위 호환성

새 파일 이름 체계는 sdist 파일에 쓰이는 현재의 비공식 명명 관례의 부분집합입니다. 따라서 이 표준에 맞는 파일을 생성하거나 게시하는 도구가 만든 파일은 이전 명명 관례만 이해하는 기존 도구에서도 읽을 수 있습니다.

sdist 파일 이름을 사용하는 도구는 기술적으로 파일이 새 표준을 따르는지 레거시 형식을 따르는지 판별할 수 없습니다. 그러나 PyPI의 파일 이름을 검토한 결과, 파일의 37%는 하이픈이 여러 개이거나 없어서 명백히 레거시 형식이었습니다. 나머지 파일은 이 PEP에 따라 파싱하면 0.004%를 제외한 모든 경우에 올바른 결과가 나오는 것으로 확인되었습니다.

현재 sdist를 사용하는 도구가 완전히 정확하게 동작하려면, 파일 이름에서 파싱한 이름과 버전을 잠정적인 값으로 취급해야 합니다. 그리고 파일을 내려받아 실제 메타데이터를 생성하여(sdist가 PEP 643을 준수한다면 메타데이터를 읽어서) 이를 검증해야 합니다. 이 명세를 지원하는 도구는 파일 이름에서 얻은 이름과 버전을 확정적인 값으로 취급할 수 있습니다. 이론적으로는 레거시 파일 이름이 이 PEP를 준수한다고 가정할 경우 오류가 발생할 위험이 있지만, 실제로 그럴 가능성은 극히 낮은 것으로 보입니다.

기각된 아이디어

sdist 메타데이터 명세에 의존하기

이 PEP가 처음 작성된 이후, 신뢰할 수 있는 표준 sdist 메타데이터 형식을 정의하는 PEP 643이 승인되었습니다. 이를 통해 배포 메타데이터(특히 이름과 버전)를 정적으로 판별할 수 있습니다.

그러나 이것만으로는 충분하지 않다고 판단됩니다. 여러 중요한 경우(예를 들어 패키지 색인에서 파일 이름을 읽는 경우)에 애플리케이션은 파일 이름에만 접근할 수 있고, 메타데이터를 읽으려면 비용이 클 수 있는 다운로드가 필요하기 때문입니다.

전용 파일 확장자 사용하기

이 PEP의 원래 버전은 {distribution}-{version}.sdist라는 파일 이름을 제안했습니다. 이 방식은 명시적이라는 장점이 있습니다. 또한 향후 파일 이름 규칙을 다시 변경하지 않고도 저장 형식을 변경할 수 있게 해 줍니다.

그러나 새 확장자에는 상당한 호환성 문제가 있습니다. 현재 색인 서버는 알 수 없는 확장자를 허용하지 않을 수 있습니다. 새 확장자를 도입하면, 레거시 색인이 새 형식의 sdist를 호스팅하는 색인을 미러링하려는 경우와 같은 상황을 어떻게 처리해야 할지도 명확하지 않습니다. 프로젝트의 최신 버전에 대한 sdist를 생략하고 부분적으로만 미러링하는 것을 허용할 수 있습니까? 또한 새 형식을 생성하는 빌드 백엔드는 이전 형식만 허용하는 색인 서버와 호환되지 않습니다. 사용자가 빌드할 때 이전 버전의 백엔드를 요청할 방법이 없는 경우가 많으므로, 이로 인해 sdist를 빌드하고 업로드하는 것이 불가능해질 수 있습니다.

현재 널리 쓰이는 sdist 이름 규칙 확장하기

초기 논의에서 {distribution}-{version}.sdist.tar.gz라는 규칙이 제기되었습니다. 이 규칙은 현재 사용 가능한 설치 도구와의 하위 호환성 문제로 인해 폐기되었습니다. 예를 들어 pip 20.1은 distribution-1.0.sdist.tar.gz를 버전이 1.0.sdist인 프로젝트 distribution으로 파싱합니다. 이렇게 되면 sdist는 다운로드되지만 메타데이터가 일치하지 않아 설치에 실패하게 됩니다.

이 제안의 주요 장점은 도구가 새 형식의 이름을 더 쉽게 인식할 수 있다는 점이었습니다. 그러나 이름에 하이픈이 하나만 있는 모든 sdist는 이전 규칙과 새 규칙에서 똑같이 파싱되므로, 이는 그다지 중요한 이점이 아닙니다.