PEP 753 – 핵심 메타데이터의 통일된 프로젝트 URL

Author:: William Woodruff <william at yossarian.net>, Facundo Tuesca <facundo.tuesca at trailofbits.com>
Sponsor:: Barry Warsaw <barry at python.org>
PEP-Delegate:: Paul Moore <p.f.moore at gmail.com>
Discussions-To:: Discourse thread
Status:: Final
Type:: Standards Track
Topic:: Packaging
Created:: 29-Aug-2024
Post-History:: 26-Aug-2024, 03-Sep-2024
Resolution:: 10-Oct-2024

Table of Contents

초록
근거 및 동기
사양
- 메타데이터 생성자
- 패키지 색인
Project-URL 레이블에 관한 규약
- 레이블 정규화
- 잘 알려진 레이블
하위 호환성
- 제한적인 영향
향후 고려 사항
보안 관련 영향
이 내용을 가르치는 방법
부록 A: 레이블 정규화 예제
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, Well-known Project URLs in Metadata, is maintained on the PyPA specs page.

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

초록

이 PEP는 색인(예: PyPI) 및 기타 핵심 메타데이터 소비자가 핵심 메타데이터를 처리하는 방식에 대해 서로 구별되는 두 가지 변경을 권고합니다:

Home-page및 Download-URL필드를 이에 상응하는 Project-URL필드로 대체하여 폐기합니다;
소비자 측 메타데이터 처리 중 Project-URL레이블을 정규화하고 의미를 부여하기 위한 규칙 세트입니다.

근거 및 동기

Python의 표준 핵심 메타데이터는 다양한 표준화된 주요 버전과 함께 수년에 걸쳐 여러 차례 개정되었습니다.

이러한 핵심 메타데이터 개정에서는 URL을 통해 패키지와 외부 리소스 간의 관계를 표현하는 다양한 메커니즘이 도입되었습니다:

메타데이터 1.0에서는 배포판의 홈페이지 URL을 포함하는 한 번만 사용하는 Home-page필드를 도입했습니다.
```
Home-page: https://example.com/sampleproject
```
메타데이터 1.1에서는 현재 배포판을 다운로드하는 데 적합한 URL을 포함하는 보완적인 한 번만 사용하는 Download-URL필드를 도입했습니다.
```
Download-URL: https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
```

메타데이터 1.2에서는 레이블과 URL의 쌍을 포함하는 multiple-use필드인 Project-URL을 도입했습니다. 각 레이블은 URL의 의미를 전달하는 자유 형식의 텍스트입니다.

Project-URL: Homepage, https://example.com/sampleproject
Project-URL: Download, https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
Project-URL: Documentation, https://example.com/sampleproject/docs

메타데이터 2.1, 2.2 및 2.3에서는 이러한 필드의 동작을 최초에 명시된 대로 유지합니다.

Project-URL은 자유 형식의 레이블을 허용하고 여러 번 사용할 수 있으므로, Home-page와 Download-URL의 값을 대신 Project-URL안에 표현하기 위한 비공식 규칙이 생겨났습니다.

이러한 규칙은 널리 채택되었으며, PEP 621에서는 project.home-page필드 대신 project.urls 테이블만 제공하도록 명시적으로 선택했습니다. 다음은 PEP 621에서 거부된 아이디어입니다:

핵심 메타데이터가 이를 지원하지만, 프로젝트 URL에 단일 필드를 사용하면서 동시에 전체 테이블도 지원하는 것은 중복되고 혼란스러워 보였습니다.

이 PEP는 생겨난 비공식 규칙을 공식화하고, Home-page와 Download-URL을 이에 상응하는 Project-URL표현을 우선하여 폐기된 것으로 명시적으로 문서화하기 위해 작성되었습니다.

사양

이 PEP는 Home-page와 Download-URL을 deprecated로 간주할 것을 제안합니다. 이러한 폐기는 패키지 메타데이터 생성자(예: 빌드 백엔드 및 패키징 도구)와 패키지 색인(예: PyPI) 모두에 영향을 미칩니다.

메타데이터 생성자

이 PEP는 메타데이터 생성자에 대해 다음을 규정합니다:

메타데이터 1.2 이상을 생성할 때 생성자는 Project-URL만 내보내야 하며(SHOULD), Home-page또는 Download-URL필드는 내보내서는 안 됩니다(SHOULD NOT).

이러한 규정은 핵심 메타데이터에서 URL 필드가 선택 사항이라는 점을 변경하지 않습니다. 다시 말해, 생성자는 재량에 따라 Project-URL을 전혀 생략할 수 있습니다(MAY).

이 PEP는 Home-page또는 Download-URL지원을 완전히 제거할 것을 제안하지 않습니다. 그러나 아직 명시되지 않은 새로운 주요 핵심 메타데이터 버전이 이러한 폐기된 필드를 제거하여 폐기 절차를 완료할 수 있는 방법에 대한 의견은 향후 고려 사항 을 참조하십시오.

마찬가지로, 이 PEP는 메타데이터 생산자가 normalized labels를 내보내도록 제안하지 않습니다. 레이블 정규화는 처리 및 소비 측면, 즉 배포 메타데이터의 색인 및 기타 소비자 내부에서만 수행됩니다.

패키지 색인

이 PEP는 패키지 색인에 대해 다음을 규정합니다:

배포의 메타데이터가 버전 1.2 이상인 경우(예: 웹 페이지에 렌더링하기 위해), 색인은 URL의 출처로 Project-URL필드를 Home-page및 Download-URL보다 반드시 우선해야 하며, 후자가 명시적으로 제공된 경우에도 그러합니다.
배포의 메타데이터에 Home-page및 Download-URL 필드만 포함된 경우, 색인은 해당 필드를 무시하고 메타데이터에 URL이 제공되지 않은 것처럼 처리할 것을 선택할 수 있습니다. 이 경우 색인은 업로드 주체에 적절한 경고 또는 알림을 제시해야 합니다.
- 이 경고 또는 알림을 표시하는 메커니즘은 인덱스마다 다르므로 지정되지 않습니다. 예를 들어, 인덱스는 업로드 요청에 대한 HTTP 응답에 경고를 표시하거나 프로젝트의 유지 관리자에게 이메일 또는 기타 알림을 보낼 수 있습니다.
배포의 메타데이터에 두 필드 집합이 모두 포함된 경우, 색인은 해당 배포를 즉시 거부할 것을 선택할 수 있습니다. 그러나 향후의 지정되지 않은 주요 메타데이터 버전에서 Home-page 및 Download-URL 지원을 공식적으로 제거할 때까지는 이렇게 하는 것을 권장하지 않습니다.
버전 1.2 이상인 메타데이터의 해석에 대한 변경으로 인해 이전에 인식되던 URL이 더 이상 인식되지 않게 되는 경우, 그러한 변경은 이전에 업로드된 패키지에 소급 적용해서는 안 됩니다.

이러한 규정은 인덱스의 URL 처리 선택 사항을 변경하지 않습니다. 다시 말해, 업로드된 배포판 내의 URL을 처리하지 않는 인덱스는 계속해서 모든 URL 필드를 완전히 무시할 수 있습니다.

마찬가지로 이러한 규정은 인덱스가 배포판의 메타데이터에 수행하는 정규화를 유지해야 한다는 의미가 아닙니다. 다시 말해, 이 PEP는 사용자에게 표시하기 위한 레이블 정규화를 규정하는 것이며, 업로드된 배포판 또는 해당 “sidecar” PEP 658 메타데이터 파일을 수정하기 위한 정규화를 규정하는 것이 아닙니다.

`Project-URL` 레이블에 관한 규약

위에서 제안한 사용 중단은 현재 비공식적인 Home-page, Download-URL 및 이에 대응하는 Project-URL 간의 관계를 공식화해야 합니다.

이 공식화에는 두 부분이 있습니다.

인덱스 측 처리 중 Project-URL 레이블을 정규화하기 위한 규칙 집합;
인덱스가 URL 표시를 특수화할 수 있는 “잘 알려진” 정규화 레이블 값 집합.

레이블 정규화

핵심 메타데이터 사양은 Project-URL 레이블이 32자로 제한된 자유 텍스트라고 규정합니다.

이 PEP는 핵심 메타데이터 사양에 “정규화된” 레이블이라는 개념을 추가할 것을 제안합니다. 레이블 정규화는 다음 Python 함수로 정의됩니다.

import string
def normalize_label(label: str) -> str:
    chars_to_remove = string.punctuation + string.whitespace
    removal_map = str.maketrans("", "", chars_to_remove)
    return label.translate(removal_map).lower()

쉽게 말해, 레이블은 모든 ASCII 문장 부호와 공백을 삭제한 다음 결과를 소문자로 변환하여 normalized됩니다.

다음 표는 정규화 전(raw)과 후의 레이블 예시를 보여줍니다:

원본	정규화됨
`Homepage`	`homepage`
`Home-page`	`homepage`
`Home page`	`homepage`
`Change_Log`	`changelog`
`What's New?`	`whatsnew`

배포 메타데이터를 처리할 때, 패키지 색인은 주어진 레이블이 이후의 특수 처리를 위한 잘 알려진 레이블인지 판단하기 위해 레이블 정규화를 수행해야 합니다. 잘 알려지지 않은 레이블은 정규화되지 않은 형태로 처리해야 합니다.

정규화는 중복된 Project-URL레이블을 둘러싼 기존 의미를 변경하지 않습니다. 다시 말해, 정규화로 인해 프로젝트 메타데이터에 중복 레이블이 생길 수 있지만, 레이블이 고유해야 한다고 규정하지 않는 핵심 메타데이터 사양에서 이미 허용하던 것과 동일한 방식으로만 발생합니다.

정규화된 메타데이터 필드의 발췌 예는 부록 A에 제공됩니다.

잘 알려진 레이블

위의 정규화 규칙에 더해, 이 PEP는 “잘 알려진” Project-URL 레이블과 그 별칭 및 사람이 읽을 수 있는 대응 표현으로 구성된 고정된(확장 가능한) 집합을 제안합니다.

다음 표는 정규화된 형태로 이러한 레이블을 나열합니다:

레이블(사람이 읽을 수 있는 형태)	설명	별칭
`homepage` (Homepage)	프로젝트의 홈페이지	(없음)
`source` (Source Code)	프로젝트가 호스팅하는 소스 코드 또는 저장소	`repository`, `sourcecode`, `github`
`download` (Download)	현재 배포본의 다운로드 URL로, `Download-URL`과 동일합니다.	(없음)
`changelog` (Changelog)	프로젝트의 포괄적인 변경 이력	`changes`, `whatsnew`, `history`
`releasenotes` (Release Notes)	프로젝트의 엄선된 릴리스 노트	(none)
`documentation` (문서)	프로젝트의 온라인 문서	`docs`
`issues` (이슈 트래커)	프로젝트의 버그 트래커	`bugs`, `issue`, `tracker`, `issuetracker`, `bugtracker`
`funding` (펀딩)	펀딩 정보	`sponsor`, `donate`, `donation`

색인은 적절한 경우 위에서 제안된 사람이 읽을 수 있는 대응어를 UI 요소에 사용할 수 있습니다. 또는 색인은 UI 요소에 사용할 적절한 사람이 읽을 수 있는 동등한 표현을 자체적으로 선택하도록 MAY할 수 있습니다.

패키징 담당자와 메타데이터 생성자는 패키지 색인과 다운스트림에 특정 URL 의도를 전달하기 위해 이러한 레이블(또는 그 별칭)로 정규화되는 레이블을 사용하도록 MAY선택할 수 있습니다.

마찬가지로 색인은 이러한 레이블이 지정된 URL의 렌더링 또는 표시를 특화하도록 MAY할 수 있습니다. 예를 들어 각 레이블에 적절한 아이콘이나 툴팁을 표시할 수 있습니다.

색인은 잘 알려진 레이블로 시작하는 레이블과 알려진 서비스 제공자 도메인을 참조하는 URL(예: 문서 호스팅 또는 이슈 추적용 URL)을 포함하여 추가 레이블이나 URL의 렌더링 또는 표시를 MAY특화할 수도 있습니다.

이 PEP는 잘 알려진 레이블 목록이 정적으로 유지될 가능성이 낮으며, 이후 목록에 추가되는 항목에 공식 PEP 절차나 새로운 메타데이터 버전과 관련된 오버헤드가 필요하지 않아야 한다고 봅니다. 따라서 이 PEP는 위 목록을 PyPA 사양내에서 “살아 있는” 목록으로 만들 것을 제안합니다.

하위 호환성

제한적인 영향

이 PEP는 기존 패키징 도구나 패키지 색인에 거의 또는 전혀 영향을 미치지 않을 것으로 예상됩니다.

패키징 도구: 핵심 메타데이터의 정확성이나 올바른 형식에는 변경 사항이 없습니다. 이 PEP는 사용 중단과 동작 개선을 제안하지만, 현재 및 과거에 생성된 모든 메타데이터는 각각의 버전 규칙에 따라 계속 유효합니다.
패키지 색인: 색인은 동작 변경 없이 올바른 형식의 핵심 메타데이터를 계속 요구합니다. 색인은 이제 사용 중단된 필드가 존재할 경우 위에서 설명한 대로경고나 알림을 MAY발행할 수 있습니다.

향후 고려 사항

이 PEP는 향후 메타데이터 변경을 규정하거나 요구하지 않습니다.

그러나 메타데이터 생성자 및 Project-URL 레이블에 관한 규약에 따라, 핵심 메타데이터 표준의 새로운 주 버전에 대해 다음과 같은 잠재적인 향후 목표를 식별합니다.

다음 핵심 메타데이터 주 버전에서 Home-page및 Download-URL지원을 완전히 제거합니다. 제거되는 경우 패키지 색인과 소비자는 해당 메타데이터가 새로운 주 버전일 때 이러한 필드를 포함하는 메타데이터를 MUST거부해야 합니다.
레이블 정규화의 적용 적용되는 경우 패키지 생성자는 배포 메타데이터를 생성할 때 정규화된 Project-URL레이블만 MUST출력해야 하며, 패키지 색인과 소비자는 정규화되지 않은 레이블을 포함하는 배포 패키지를 MUST거부해야 합니다. 참고: 정규화를 요구하면 레이블을 소문자 텍스트로만 제한하고 공백과 구두점을 제외할 뿐입니다. 이는 프로젝트 URL을 “잘 알려진” 레이블만 사용하는 것으로 제한하지 않습니다.

이러한 잠재적인 변경 사항은 하위 호환성이 없으므로 이 절에만 포함합니다. 이 PEP의 수락은 향후 메타데이터 개정에서 실제로 이러한 변경을 수행할 것을 약속하지 않습니다.

보안 관련 영향

이 PEP는 Home-page및 Download-URL사용 중단이나 레이블 정규화와 관련된 긍정적 또는 부정적 보안 영향을 식별하지 않습니다.

이 내용을 가르치는 방법

이 PEP의 변경 사항은 패키징 생태계 사용자층 대부분에게 투명해야 합니다. 이 PEP 변경의 주요 수혜자는 패키징 도구 작성자와 색인 유지 관리자이며, 이들은 생성하고 확인하는 고유 URL 필드의 수를 줄일 수 있습니다.

색인이 제안된 대로 Home-page및 Download-URL을 무시하기로 선택하는 경우, 소수의 패키지 유지 관리자는 자신이 선택한 색인에서 새로운 경고나 알림을 확인할 수 있습니다. 마찬가지로 소수의 패키지 유지 관리자는 URL이 사용 중단된 필드에만 존재하는 경우 자신이 선택한 색인이 더 이상 해당 URL을 렌더링하지 않는 것을 확인할 수 있습니다. 그러나 이 PEP가 제안하는 변경 사항으로 인해 패키지 유지 관리자가 거부된 패키지 업로드나 패키징 작업 흐름에 대한 기타 호환성을 깨뜨리는 변경 사항을 겪어서는 안 됩니다.

색인에서 URL 표시 방식에 대한 경고나 변경 사항을 관찰하는 사람은 누구나 Python Packaging User Guide 및 PyPI’s user documentation와 같은 공식 패키징 리소스를 통해 이 PEP의 동작에 대해 안내받을 수 있으며, 후자는 이미 PyPI의 URL 처리 동작에 대한 비공식적인 설명을 포함하고 있습니다.

이 PEP가 수락되면, 이 PEP의 작성자들은 위에서 언급한 리소스를 업데이트하고 상호 연결하기 위해 조율합니다.

부록 A: 레이블 정규화 예제

이 부록에서는 색인 측 처리 전후의 배포 패키지 메타데이터에서 발췌한 예시를 제공합니다:

Project-URL: Home-page, https://example.com
Project-URL: Homepage, https://another.example.com
Project-URL: Source, https://github.com/example/example
Project-URL: GitHub, https://github.com/example/example
Project-URL: Another Service, https://custom.example.com

이후:

Project-URL: homepage, https://example.com
Project-URL: homepage, https://another.example.com
Project-URL: source, https://github.com/example/example
Project-URL: github, https://github.com/example/example
Project-URL: Another Service, https://custom.example.com

특히 다음 사항을 관찰하십시오:

정규화된 중복 항목은 보존됩니다(Home-page와 Homepage가 모두 homepage가 됩니다);
Source와 GitHub는 모두 각각의 형태로 정규화되지만, github는 source로 변환되지 않습니다.
Another Service는 정규화되지 않습니다. 그 정규형(anotherservice)이 well-known label이 아니기 때문입니다.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.