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라고도 알려진 소스 배포판의 표준 이름 지정 체계를 설명합니다. sdist는 Python 패키지의 소스 코드를 포함하는 임의의 아카이브 파일과는 구별되며, 패키징 도구에 배포판 정보를 전달하는 데 사용할 수 있습니다.

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

동기

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

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 훅을 실행하는 것을 의미하며, 상당한 오버헤드가 발생합니다.

근거

sdist 형식을 위한 특수한 파일 이름 체계를 만들면, 파일 이름에서 확인할 수 있는 메타데이터만 필요한 경우 이 PEP를 통해 도구가 시간 소모적인 메타데이터 검증 단계에서 벗어날 수 있습니다.

이 PEP는 현재 sdist 구현에서 사용되는 오랜 파일 이름 규칙에 대한 공식 명세 역할도 합니다. 파일 이름에는 배포판의 이름과 버전이 포함되므로, 필요한 모든 정보가 파일 이름에 있는 경우 도구가 파일을 다운로드하거나 압축을 풀거나 조사에 필요한 비용이 큰 메타데이터 생성을 수행하지 않고도 배포판을 식별할 수 있습니다.

명세

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

distribution은 PEP 345에서 정의하고 the wheel spec 에 설명된 대로 정규화한 배포판의 이름입니다. 예를 들어 'pip', 'flit_core'가 있습니다.
version은 PEP 440에서 정의하고 해당 PEP의 규칙에 따라 정규화한 배포판의 버전입니다. 예를 들어 20.2가 있습니다.

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

sdist 파일을 생성하는 코드는 이 명세에 일치하는 이름을 파일에 지정해야 합니다. 이 명명 규칙을 요구하도록 PEP 517에서 정의한 build_sdist 훅의 사양이 확장됩니다.

sdist 파일을 처리하는 코드는 파일 이름을 간단히 구문 분석하여 배포판의 이름과 버전을 확인할 수 있으며, sdist 내용에서 메타데이터를 생성하거나 읽어서 해당 정보를 검증할 필요는 없습니다.

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

하위 호환성

새로운 파일 이름 체계는 sdist 파일에 대한 현재의 비공식 이름 지정 규칙의 부분집합이므로, 이 표준을 준수하는 파일을 생성하거나 게시하는 도구는 이전 이름 지정 규칙만 이해하는 이전 도구에서도 읽을 수 있습니다.

sdist 파일 이름을 사용하는 도구는 기술적으로 파일이 새 표준을 사용하는지 레거시 형식을 사용하는지 판별할 수 없습니다. 그러나 PyPI의 파일 이름을 검토한 결과, 파일의 37%는 하이픈이 여러 개 있거나 전혀 없기 때문에 명백한 레거시 형식이며, 나머지 파일은 이 PEP에 따라 구문 분석하면 0.004%의 경우를 제외하고 모두 올바른 결과를 제공합니다.

현재 sdist를 사용하는 도구는 완전히 올바르게 작동하려면 파일 이름에서 구문 분석한 이름과 버전을 잠정적인 것으로 취급하고, 파일을 다운로드하여 실제 메타데이터를 생성하거나(sdist가 PEP 643에 부합하는 경우에는 메타데이터를 읽어) 이를 확인해야 합니다. 이 사양을 지원하는 도구는 파일 이름에서 가져온 이름과 버전을 확정적인 것으로 취급할 수 있습니다. 이론적으로는 레거시 파일 이름이 이 PEP를 준수한다고 가정할 경우 오류가 발생할 위험이 있지만, 실제로는 이러한 가능성이 거의 없다고 보입니다.

거부된 아이디어

sdist 메타데이터 사양에 의존하기

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

그러나 이는 충분한 것으로 간주되지 않습니다. 여러 중요한 경우(예를 들어 패키지 색인에서 파일 이름을 읽는 경우)에 애플리케이션이 파일 이름에만 액세스할 수 있으며, 메타데이터를 읽으려면 비용이 많이 들 수 있는 다운로드가 필요하기 때문입니다.

전용 파일 확장자를 사용하기

이 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는 이전 규칙과 새 규칙에서 동일하게 파싱되므로, 이는 그다지 큰 이점이 아닙니다.