PEP 610 – 설치된 배포 패키지의 직접 URL 출처 기록

Author:: Stéphane Bidoul <stephane.bidoul at gmail.com>, Chris Jerdonek <chris.jerdonek at gmail.com>
Sponsor:: Alyssa Coghlan <ncoghlan at gmail.com>
BDFL-Delegate:: Pradyun Gedam <pradyunsg at gmail.com>
Discussions-To:: Discourse thread
Status:: Final
Type:: Standards Track
Topic:: Packaging
Created:: 21-Apr-2019
Post-History:
Resolution:: Discourse message

Table of Contents

번역·라이선스 안내

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

Important

This PEP is a historical document. The up-to-date, canonical spec, Recording the Direct URL Origin of installed distributions, is maintained on the PyPA specs page.

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

초록

관련 PEP 440에 따라 배포판은 이름과 버전 또는 직접 URL 참조로 식별할 수 있습니다(PEP440 Direct References를 참조하십시오). 설치 후 이름과 버전은 프로젝트 메타데이터에 기록되지만, 현재는 배포 패키지가 직접 URL 참조로 식별된 경우 사용된 URL의 세부 정보를 얻을 방법이 없습니다.

이 제안은 설치 프런트엔드가 설치된 배포 패키지에 추가하여, 설치된 패키지 데이터베이스를 검사하는 소비자가 사용할 수 있도록 직접 URL 출처를 기록하는 추가 메타데이터를 정의합니다(PEP 376 참조).

동기

이 PEP의 원래 동기는 더 광범위한 상황에서 Python 환경을 재현할 수 있도록 “freeze” 작업을 지원하는 도구를 허용하는 것이었습니다.

구체적으로 이 PEP는 직접 URL 참조에서 설치된 배포 패키지가 존재할 때 pip freeze의 동작을 개선하는 등, pip issue #609를 해결하려는 요구에서 시작되었습니다. 이를 구현하기 위한 최선의 방안에 관한 thread on discuss.python.org에 이어 작성되었습니다.

직접 URL 참조를 통한 설치

pip와 같은 Python 설치 프로그램은 패키지 색인에서 배포 패키지를 다운로드하고 설치할 수 있습니다. 또한 PEP440 Direct References에서 표준화된 대로, 소스 아카이브와 버전 관리 시스템(VCS) 저장소의 임의 URL을 지정하는 요구 사항에서 소스 코드를 다운로드하고 설치할 수도 있습니다.

다시 말해, 관련된 설치 모드는 두 가지가 있습니다.

설치할 패키지가 이름과 버전 지정자로 지정되는 경우:

이 경우 설치 프로그램은 패키지 색인에서 (또는 pip의 경우 선택적으로 --find-links를 사용하여) 설치할 배포 패키지를 찾습니다.

설치할 패키지가 직접 URL 참조로 지정되는 경우:

이 경우 설치 프로그램은 URL에 지정된 항목(일반적으로 휠, 소스 아카이브 또는 VCS 저장소)을 다운로드하여 설치합니다.
이 모드에서 설치 프로그램은 일반적으로 임시 디렉터리에 소스 코드를 다운로드하고, 필요한 경우 PEP 517 빌드 백엔드를 호출하여 휠을 생성한 다음, 휠을 설치하고 임시 디렉터리를 삭제합니다.

설치 후에는 사용자가 패키지를 다운로드하도록 요청한 URL의 흔적이 사용자 시스템에 남지 않습니다.

환경 고정

Pip에는 설치된 Python 배포 패키지 데이터베이스를 검사하여 요구 사항 목록을 생성하는 pip freeze라는 명령도 있습니다. 이 명령의 주요 목적은 사용자가 나중에 가능한 한 높은 충실도로 동일한 환경을 다시 설치할 수 있도록 요구 사항 목록을 생성하는 데 도움을 주는 것입니다.

pip 버전 19.3부터 pip freeze 명령은 설치된 각 배포 패키지에 대해 name==version 행을 출력합니다(편집 가능 설치는 제외합니다). 동일한 환경을 다시 설치한다는 목표를 달성하려면 (name, version) 튜플이 배포 패키지의 변경 불가능한 버전을 가리켜야 합니다. 변경 불가능성은 Warehouse와 같은 패키지 색인에서 보장합니다. 사용할 패키지 색인은 일반적으로 설치 프로그램의 환경 매개변수나 명령줄 매개변수에서 확인할 수 있습니다.

따라서 이 고정 메커니즘은 설치 모드 1(즉, 설치할 패키지가 이름과 버전 지정자로 지정된 경우)에서 잘 작동합니다.

설치 모드 2, 즉 설치할 패키지가 직접 URL 참조로 지정된 경우에는 name==version 튜플만으로 동일한 배포 패키지를 다시 설치하기에 분명히 충분하지 않으며, 고정 명령 사용자는 원래 요청된 URL이 출력되기를 기대합니다.

위의 추론은 pip freeze이외에 설치된 Python 배포 패키지 데이터베이스에서 Pipfile.lock을 비롯한 유사한 형식을 생성하려는 도구에도 동일하게 적용됩니다. 달리 명시하지 않는 한, 이 문서에서는 이러한 작업을 가리키는 일반적인 용어로 “freeze”를 사용합니다.

애플리케이션 통합자에게 VCS URL을 통한 설치가 중요한 이유

애플리케이션 통합자는 아직 릴리스되지 않은 Python 배포판 버전을 안정적으로 설치하고 동결할 수 있어야 합니다. 예를 들어 개발자가 의존성의 아직 릴리스되지 않은 패치 버전을 배포해야 하는 경우, 유지 관리자가 업데이트된 버전을 릴리스할 때까지 해당 패치가 포함된 VCS 브랜치에서 의존성을 직접 설치하는 것이 일반적입니다.

이러한 경우에는 가능한 한 높은 충실도로 재현 가능한 빌드를 생성하기 위해, “freeze”가 설치된 정확한 VCS 참조(가능한 경우 커밋 해시)를 고정하는 것이 중요합니다.

VCS URL에 사용할 수 있는 추가 출처 메타데이터

VCS URL에는 설치 시에만 사용할 수 있으며 내부 검사와 특정 워크플로에 유용한 추가 출처 정보가 있습니다. 예를 들어 VCS URL에서 리비전을 설치할 때 도구는 해당 리비전이 브랜치, 태그 또는 (Git의 경우) ref에 해당하는지 확인할 수 있습니다. 이 정보는 설치된 배포판 데이터베이스를 검사할 때 사용하여 어떤 버전이 설치되었는지에 관한 더 많은 정보를 사용자에게 전달할 수 있습니다(예: 브랜치 또는 태그가 설치되었는지, 설치되었다면 해당 브랜치 또는 태그의 이름). 또한 태그만 불변성의 의미를 가지므로, 태그 형식을 사용하여 PEP 440 직접 참조 URL을 구성할 수 있는지도 알 수 있습니다.

리비전이 변경 가능한 경우(예: 브랜치와 Git ref), 이 정보를 알면 사용자가 추적 중인 브랜치의 최신 버전으로 업데이트하거나 로컬에서 검토 중인 풀 리퀘스트의 최신 버전으로 업데이트하는 등의 워크플로를 사용할 수 있습니다. 반대로 리비전이 태그인 경우 도구는 사전에(예: 네트워크 호출 없이) 업데이트가 필요하지 않다는 것을 알 수 있습니다.

URL 자체와 마찬가지로 VCS 저장소를 사용할 수 있을 때 설치 시 이 정보가 기록되지 않으면, 이 정보는 결국 손실됩니다.

“editable” 설치에 관한 참고 사항

pip의 editable 설치 모드는 대략적으로 개발 목적으로 사용자가 로컬 디렉터리를 sys.path에 삽입할 수 있도록 합니다. 이 모드는 VCS URL에서 editable이 아닌 설치를 수행하면 설치 후 출처 추적이 끊긴다는 사실을 우회하기 위해 다소 남용되고 있습니다. 실제로 editable 설치는 체크아웃 디렉터리에 VCS 출처를 암묵적으로 기록하므로, “freeze”를 실행할 때 해당 정보를 복구할 수 있습니다.

이 우회 방법은 유용하지만 취약하고 editable 모드의 목적에 관해 혼란을 일으키며, 배포판을 setuptools로 설치할 수 있을 때만 작동합니다(즉, 다른 PEP 517 빌드 백엔드에서는 사용할 수 없습니다).

이 PEP가 구현되면 VCS 참조에서 pip freeze가 올바르게 작동하도록 하기 위해 editable 설치를 사용할 필요가 더 이상 없습니다.

근거

이 PEP는 설치된 배포판의 .dist-info 디렉터리에 새로운 direct_url.json 메타데이터 파일을 지정합니다.

지정된 필드는 소스 아카이브와 VCS URLs supported by pip를 재현하기에 충분합니다. 또한 PEP440 Direct References와 Pipfile and Pipfile.lock 항목을 재현하기에도 충분합니다. 마지막으로 VCS 체크아웃이 존재함으로써 editable 설치에 이미 사용할 수 있는 설치 버전의 브랜치, 태그 및/또는 Git ref 출처를 기록하기에도 충분합니다.

이러한 유형의 정보를 인코딩하는 방법이 이미 세 가지 이상 존재하므로, 이 PEP는 직접 URL 참조가 요구 사항 또는 잠금 파일에 최종적으로 어떤 방식으로 인코딩되어야 하는지에 관해 어떠한 가정도 하지 않도록 딕셔너리 형식을 사용합니다. 이 선택에 관한 추가 논의는 아래의 Alternatives 섹션도 참조하십시오.

유사한 기능이 있는지 확인하고 이 사양에서 필드를 선택하고 이름을 정하는 데 참고하기 위해 Ruby의 bundler 매뉴얼에서 정보를 가져왔습니다.

JSON 형식은 향후 추가 필드를 추가할 수 있도록 합니다.

사양

이 PEP는 설치된 배포판의 Direct URL Origin을 기록하기 위해 .dist-info 디렉터리에 direct_url.json 파일을 지정합니다.

이 메타데이터 파일의 이름과 의미에 대한 정식 출처는 Recording the Direct URL Origin of installed distributions 문서입니다.

이 파일은 직접 URL 참조를 지정하는 요구 사항( VCS URL 포함)에서 배포판을 설치할 때 설치 프로그램이 반드시 생성해야 합니다.

다른 유형의 요구 사항(즉, 이름과 버전 지정자)에서 배포판을 설치할 때는 이 파일을 절대로 생성해서는 안 됩니다.

이 JSON 파일은 딕셔너리여야 하며, RFC 8259를 준수하고 UTF-8로 인코딩되어야 합니다.

존재하는 경우, 최소 두 개의 필드를 포함해야 합니다. 첫 번째 필드는 url이며, 유형은 string입니다. url이 가리키는 대상에 따라 두 번째 필드는 vcs_info (url이 VCS 참조인 경우), archive_info (url이 소스 아카이브 또는 휠인 경우) 또는 dir_info (url이 로컬 디렉터리인 경우) 중 하나여야 합니다. 이러한 정보 필드는 아래에 정의된 가능한 키를 포함하는 하위 딕셔너리를 값으로 가지며, 이 하위 딕셔너리는 비어 있을 수도 있습니다.

보안상의 이유로 url에서 민감한 인증 정보는 제거해야 합니다.

그러나 URL의 user:password 섹션은 다음 정규 표현식과 일치하는 환경 변수로 구성할 수 있습니다.:

\$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?

또한 URL의 user:password 섹션은 잘 알려져 있으며 보안상 민감하지 않은 문자열일 수 있습니다. 일반적인 예로는 ssh://git@gitlab.com과 같은 URL에서 git을 들 수 있습니다.

url이 VCS 저장소를 가리키는 경우, vcs_info 키는 다음 키를 포함하는 딕셔너리로 존재해야 합니다.

vcs키(유형 string)가 존재해야 하며, VCS의 이름(즉, git, hg, bzr, svn 중 하나)을 포함해야 합니다. 다른 VCS는 이 사양을 수정하는 PEP를 작성하여 등록하는 것이 좋습니다. url 값은 해당 VCS와 호환되어야 하므로, 설치 프로그램은 이를 변환하지 않고 VCS의 checkout/download 명령에 전달할 수 있어야 합니다.
requested_revision 키(유형 string)는 설치할 브랜치/태그/ref/커밋/리비전 등을 (VCS와 호환되는 형식으로) 지정하여 포함할 수 있습니다.
설치된 정확한 커밋/리비전 번호를 포함하는 commit_id 키(유형 string)가 존재해야 합니다. VCS가 커밋 해시 기반 리비전 식별자를 지원하는 경우, 설치된 소스 코드의 변경 불가능한 버전을 참조할 수 있도록 해당 커밋 해시를 commit_id로 사용해야 합니다.
설치 프로그램이 요청된 리비전에 관한 추가 정보를 확인할 수 있다면 resolved_revision 및/또는 resolved_revision_type 필드를 추가할 수 있습니다. 요청된 URL에 리비전이 제공되지 않은 경우, resolved_revision에는 설치된 기본 브랜치가 포함될 수 있으며 resolved_revision_type은 branch가 됩니다. 설치 프로그램이 requested_revision이 태그였다고 판단하는 경우, 값이 tag인 resolved_revision_type을 추가할 수 있습니다.

url이 소스 아카이브 또는 휠을 가리키는 경우, archive_info 키는 다음 키를 포함하는 딕셔너리로 존재해야 합니다.

hash 키(유형 string)가 존재하는 것이 좋으며, 값은 <hash-algorithm>=<expected-hash>이어야 합니다. 소스 아카이브의 해시에는 최신 버전의 표준 라이브러리 hashlib 모듈이 무조건 제공하는 해시만 사용하는 것이 좋습니다. 이 글을 작성하는 시점에 해당 목록은 ‘md5’, ‘sha1’, ‘sha224’, ‘sha256’, ‘sha384’ 및 ‘sha512’로 구성됩니다.

url이 로컬 디렉터리를 가리키는 경우, dir_info 키는 다음 키를 포함하는 딕셔너리로 존재해야 합니다.

editable (유형: boolean): 배포 패키지가 편집 가능 모드로 설치된 경우 true이고, 그렇지 않은 경우 false입니다. 누락된 경우 기본값은 false입니다.

url이 로컬 디렉터리를 가리키는 경우, file 스킴을 사용해야 하며 RFC 8089를 준수해야 합니다. 특히 경로 구성 요소는 절대 경로여야 합니다. 상대 경로를 절대 경로로 변환할 때 심볼릭 링크를 보존하는 것이 좋습니다.

Note

요청된 URL이 file:// 스킴을 사용하고 우연히 VCS 체크아웃을 포함하는 로컬 디렉터리를 가리키는 경우, 설치 프로그램은 VCS 정보를 추론하려고 시도해서는 안 되며 따라서 direct_url.json에 vcs_info와 같은 VCS 관련 정보를 출력해서도 안 됩니다.

최상위 subdirectory 필드는 VCS 저장소, 소스 아카이브 또는 로컬 디렉터리의 루트에 상대적인 디렉터리 경로를 포함하여, pyproject.toml또는 setup.py가 위치한 곳을 지정할 수 있습니다.

Note

일반적으로 설치 프로그램은 direct_url.json을 생성할 때 요청된 URL에 제공된 정보를 가능한 한 많이 보존해야 합니다. 예를 들어, user:password 환경 변수는 보존되어야 하며 requested_revision은 요청된 URL에 제공된 리비전을 가능한 한 충실하게 반영해야 합니다. 그러나 이 정보는 commit_id와 같은 더 정확한 데이터로 보강됩니다.

등록된 VCS

이 절에는 등록된 VCS가 나열되어 있으며, vcs, requested_revision및 vcs_info의 기타 필드를 사용하는 방법에 관한 확장된 VCS별 정보와 경우에 따라 추가적인 VCS별 필드가 포함되어 있습니다. 도구는 다른 VCS도 지원할 수 있지만, 이 명세를 수정하는 PEP를 작성하여 해당 VCS를 등록하는 것이 권장됩니다. vcs필드는 명령 이름(소문자화된 이름)이어야 합니다. 해당 VCS를 지원하는 데 필요한 추가 필드는 VCS 명령 이름을 접두사로 사용해야 합니다.

Git

홈페이지

https://git-scm.com/

VCS 명령

git

vcs필드

git

requested_revision필드

태그 이름, 브랜치 이름, Git ref, 커밋 해시, 축약된 커밋 해시 또는 기타 commit-ish입니다.

commit_id필드

커밋 해시(16진수 40자로 된 sha1)입니다.

Note

설치 프로그램은 git show-ref및 git symbolic-ref명령을 사용하여 requested_revision이 Git ref에 해당하는지 확인할 수 있습니다. 이어서, refs/tags/로 시작하는 ref는 태그에 해당하고, 클론한 후 refs/remotes/origin/으로 시작하는 ref는 브랜치에 해당합니다.

Mercurial

홈페이지

https://www.mercurial-scm.org/

VCS 명령

hg

vcs필드

hg

requested_revision필드

태그 이름, 브랜치 이름, 변경 집합 ID 또는 축약된 변경 집합 ID입니다.

commit_id필드

변경 집합 ID(16진수 40자)입니다.

Bazaar

홈 페이지

https://bazaar.canonical.com/

VCS 명령

bzr

vcs 필드

bzr

requested_revision 필드

태그 이름, 브랜치 이름 또는 리비전 ID입니다.

commit_id 필드

리비전 ID입니다.

Subversion

홈 페이지

https://subversion.apache.org/

VCS 명령

svn

vcs 필드

svn

requested_revision 필드

requested_revision은 svn checkout의 --revision 옵션과 호환되어야 합니다. Subversion에서 브랜치 또는 태그는 url의 일부입니다.

commit_id 필드

Subversion은 전역적으로 고유한 식별자를 지원하지 않으므로, 이 필드는 해당 저장소의 Subversion 리비전 번호입니다.

예제

예제 direct_url.json

소스 아카이브:

{
    "url": "https://github.com/pypa/pip/archive/1.3.1.zip",
    "archive_info": {
        "hash": "sha256=2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8"
    }
}

태그 및 커밋 해시가 포함된 Git URL:

{
    "url": "https://github.com/pypa/pip.git",
    "vcs_info": {
        "vcs": "git",
        "requested_revision": "1.3.1",
        "resolved_revision_type": "tag",
        "commit_id": "7921be1537eac1e97bc40179a57f0349c2aee67d"
    }
}

로컬 디렉터리:

{
    "url": "file:///home/user/project",
    "dir_info": {}
}

편집 가능 모드로 설치된 로컬 디렉터리:

{
    "url": "file:///home/user/project",
    "dir_info": {
        "editable": true
    }
}

예시 pip 명령과 direct_url.json에 미치는 영향

direct_url.json을 생성하는 명령:

pip install https://example.com/app-1.0.tgz
pip install https://example.com/app-1.0.whl
pip install “git+https://example.com/repo/app.git#egg=app&subdirectory=setup”
pip install ./app
pip install file:///home/user/app
pip install –editable “git+https://example.com/repo/app.git#egg=app&subdirectory=setup” (이 경우 url은 git 저장소가 복제된 로컬 디렉터리가 되며, dir_info가 "editable": true와 함께 존재하고 vcs_info는 설정되지 않습니다)
pip install -e ./app

생성하지 않는 direct_url.json 명령

pip install app
pip install app –no-index –find-links https://example.com/

사용 사례

환경 “고정”

설치된 Python 배포판 데이터베이스에서 요구 사항을 생성하는 pip freeze와 같은 도구는 direct_url.json이 존재하는 경우 이를 활용해야 하며, 더 높은 충실도의 출력을 생성하기 위해 버전 메타데이터보다 우선해야 합니다. vcs 직접 URL 참조가 있는 경우, 원래 설치된 버전에 최대한 높은 충실도를 제공하기 위해 commit_id 필드를 우선적으로 사용해야 합니다. 해당 도구의 요구 사항 형식이 지원하는 경우, tag값이 있으면 그 값도 출력하는 것이 권장됩니다. 이는 해당 값이 불변 의미론을 가지기 때문입니다. 도구는 사용자의 필요에 따라 다른 접근 방식을 선택할 수 있습니다.
이 PEP의 초기 버전은 편집 가능한 설치나 로컬 디렉터리로부터의 설치를 포함하는 환경을 재현 가능하게 만들려고 시도하지는 않지만, 그러한 환경을 쉽게 식별할 수 있게 만들려고 시도한다는 점에 유의하십시오. 이 명세의 url과 dir_info 필드를 통해 로컬 프로젝트 디렉터리를 찾아냄으로써, 도구는 자신의 사용 사례에 맞는 어떤 전략이든 구현할 수 있습니다.

하위 호환성

이 PEP는 .dist-info 디렉터리에 새 파일을 명시하므로, 하위 호환성에 미치는 영향은 없습니다.

대안

PEP 426의 source_url

현재 철회된 PEP 426은 source_url 메타데이터 항목을 명시합니다. 이는 distlib에도 구현되어 있습니다.

이것은 sdist에서 사용하기 위한, 다소 다른 목적으로 의도되었습니다.

이 형식은 pip 요구사항 URL의 subdirectory 옵션에 대한 지원이 없습니다. 동일한 제약이 PEP440 Direct References에도 존재합니다.

또한 URL의 user:password 부분에 있는 환경 변수에 대한 명시적인 지원이 없습니다.

키/값 확장 메커니즘을 도입하고 PEP 440에서 user:password에 대한 환경 변수 지원을 추가해야, 이 PEP에서 사용할 수 있습니다.

Python 개선 제안 한국어 번역

PEP 610 – 설치된 배포 패키지의 직접 URL 출처 기록

초록

동기

직접 URL 참조를 통한 설치

환경 고정

애플리케이션 통합자에게 VCS URL을 통한 설치가 중요한 이유

VCS URL에 사용할 수 있는 추가 출처 메타데이터

“editable” 설치에 관한 참고 사항

근거

사양

등록된 VCS

Git

Mercurial

Bazaar

Subversion

예제

예제 direct_url.json

예시 pip 명령과 direct_url.json에 미치는 영향

사용 사례

하위 호환성

대안

PEP 426의 source_url

리비전 대 참조

참고 문헌

감사의 말

Copyright