Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python 개선 제안 한국어 번역

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

번역·라이선스 안내

이 비공식 한국어 번역은 원문 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. 메타데이터 1.0은 배포물의 홈페이지 URL을 담는 단일 사용 필드인 Home-page를 도입했습니다.
    Home-page: https://example.com/sampleproject
  2. 메타데이터 1.1은 현재 배포물을 내려받기에 적합한 URL을 담는 보완적인 단일 사용 필드인 Download-URL을 도입했습니다.
    Download-URL: https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
  3. 메타데이터 1.2는 레이블과 URL의 쌍을 담는 다중 사용 필드인 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을 사용 중단된 것으로 간주할 것을 제안합니다. 이 폐지는 패키지 메타데이터 생산자(예: 빌드 백엔드와 패키징 도구)와 패키지 색인(예: PyPI) 모두에 영향을 미칩니다.

메타데이터 생산자

이 PEP는 메타데이터 생산자에 대해 다음과 같이 규정합니다:

  • 메타데이터 1.2 이상을 생성할 때 생산자는 Project-URL만 출력해야 하며(SHOULD), Home-page나 Download-URL 필드는 출력하지 않아야 합니다(SHOULD NOT).

이 규정은 코어 메타데이터에서 URL 필드가 선택 사항이라는 점을 바꾸지 않습니다. 즉, 생산자는 재량에 따라 Project-URL을 완전히 생략할 수 있습니다(MAY).

이 PEP는 Home-page나 Download-URL에 대한 지원을 곧바로 완전히 제거할 것을 제안하지 않습니다. 다만, 아직 명세되지 않은 새로운 메이저 코어 메타데이터 버전이 이렇게 폐지된 필드를 제거하여 폐지 주기를 어떻게 마무리할 수 있을지에 대한 생각은 향후 고려 사항를 참조하십시오.

마찬가지로, 이 PEP는 메타데이터 생산자가 정규화된 레이블을 출력할 것을 제안하지 않습니다. 레이블 정규화는 오로지 처리 및 소비 측(즉, 색인과 그 밖의 배포 메타데이터 소비자 내부)에서만 수행됩니다.

패키지 색인

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

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

이 규정은 색인의 URL 처리가 선택 사항이라는 점을 바꾸지 않습니다. 즉, 업로드된 배포 내의 URL을 처리하지 않는 색인은 계속해서 모든 URL 필드를 완전히 무시해도 됩니다.

마찬가지로, 이 규정은 색인이 배포 메타데이터에 수행한 정규화를 영구적으로 저장해야 한다는 뜻이 아닙니다. 즉, 이 PEP는 사용자에게 보여 주기 위한 목적으로 레이블 정규화를 규정하는 것이며, 업로드된 배포나 그 “사이드카” PEP 658 메타데이터 파일을 수정하기 위한 목적으로 규정하는 것이 아닙니다.

Project-URL 레이블에 대한 관례

위에서 제안한 폐지를 위해서는 현재 비공식적인 Home-page, Download-URL, 그리고 이에 상응하는 Project-URL 사이의 관계를 공식화해야 합니다.

이 공식화는 두 부분으로 구성됩니다:

  1. 색인 측에서 처리할 때 Project-URL 레이블을 정규화하는 규칙 집합;
  2. 색인이 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 구두점과 공백을 삭제한 다음 그 결과를 소문자로 변환하면 레이블이 정규화됩니다.

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

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

배포 메타데이터를 처리할 때 패키지 색인은 주어진 레이블이 이후 특수 처리 대상인 잘 알려진 레이블인지 판단하기 위해 레이블 정규화를 수행하는 것이 좋습니다(SHOULD). 잘 알려지지 않은 레이블은 반드시(MUST) 정규화되지 않은 형태로 처리해야 합니다.

정규화는 중복된 Project-URL 레이블에 관한 기존 의미를 변경하지 않습니다. 다시 말해, 정규화로 인해 프로젝트 메타데이터에 중복된 레이블이 생길 수 있지만, 이는 이미 허용되던 것과 같은 방식으로만 가능합니다(코어 메타데이터 명세는 레이블이 고유해야 한다고 규정하지 않기 때문입니다).

정규화된 메타데이터 필드의 발췌 예시는 부록 A에 있습니다.

잘 알려진 레이블

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

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

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

색인은 적절한 경우 위에서 제안한 사람이 읽기 쉬운 대응 표현을 UI 요소에 사용할 수 있습니다(MAY). 또는 색인은 UI 요소에 쓸 적절한 대응 표현을 직접 정할 수도 있습니다(MAY).

패키저와 메타데이터 생성자는 특정 URL 의도를 패키지 색인과 다운스트림에 전달하기 위해, 정규화하면 이 레이블(또는 그 별칭)이 되는 레이블은 무엇이든 사용할 수 있습니다(MAY).

마찬가지로 색인은 이 레이블이 붙은 URL의 렌더링이나 표시 방식을 특화할 수 있습니다(MAY). 예를 들어 레이블마다 적절한 아이콘이나 툴팁을 표시할 수 있습니다.

색인은 추가적인 레이블이나 URL의 렌더링 또는 표시 방식도 특화할 수 있습니다(MAY). 여기에는 잘 알려진 레이블로 시작하는 레이블과 알려진 서비스 제공자 도메인(예: 문서 호스팅이나 이슈 추적용 도메인)을 가리키는 URL이 포함되며, 이에 국한되지 않습니다.

이 PEP는 잘 알려진 레이블 목록이 고정된 채로 유지되기 어렵다는 점과, 앞으로 목록에 항목을 추가할 때 공식 PEP 절차나 새 메타데이터 버전에 따르는 부담이 필요해서는 안 된다는 점을 인정합니다. 따라서 이 PEP는 위 목록을 PyPA 명세 안의 “살아 있는” 목록으로 만들 것을 제안합니다.

하위 호환성

제한적인 영향

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

  • 패키징 도구: 코어 메타데이터의 정확성이나 형식 적합성에는 변화가 없습니다. 이 PEP는 폐지와 함께 동작 개선을 제안하지만, 현재(그리고 과거에) 생성된 모든 메타데이터는 각 버전의 규칙에 따라 계속 유효합니다.
  • 패키지 색인: 색인은 계속해서 올바른 형식의 코어 메타데이터를 기대하며, 동작상의 변화는 없습니다. 색인은 위에서 설명한 대로 이제 폐기된 필드가 있으면 경고나 알림을 내보낼 수 있습니다(MAY).

향후 고려 사항

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

다만, 메타데이터 생산자 및 Project-URL 레이블에 대한 관례에 따라, 코어 메타데이터 표준의 새로운 메이저 릴리스를 위한 향후 목표로 다음과 같은 것들을 고려할 수 있습니다:

  • 다음 메이저 코어 메타데이터 버전에서 Home-page와 Download-URL 지원을 완전히 제거. 제거되는 경우, 패키지 색인과 소비자는 새 메이저 버전의 메타데이터가 이러한 필드를 포함하고 있으면 해당 메타데이터를 반드시 거부해야 합니다.
  • 레이블 정규화를 강제합니다. 강제하는 경우, 패키지 생성자는 배포 메타데이터를 생성할 때 정규화된 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)이 잘 알려진 레이블이 아니므로 정규화되지 않습니다.