[Draft] PEP 804 - An external dependency registry and name mapping mechanism

원문 링크: PEP 804 - An external dependency registry and name mapping mechanism

상태: Draft 유형: Standards Track 작성일: 03-Sep-2025

PEP 804: 외부 의존성 레지스트리 및 이름 매핑 메커니즘

초록 (Abstract)

PEP 804는 패키징 도구들이 PEP 725에서 소개된 외부 의존성 식별자(DepURL)를 다른 패키지 저장소의 해당 식별자로 매핑할 수 있게 하는 이름 매핑 메커니즘을 정의합니다. 이 메커니즘은 파이썬 패키지가 PyPI 외부에 존재하는 빌드 및 런타임 의존성을 효과적으로 관리할 수 있도록 돕습니다.

동기 (Motivation)

PyPI의 패키지들은 PyPI에 존재하지 않는 빌드 및 런타임 의존성을 요구하는 경우가 많습니다. PEP 725는 이러한 의존성을 표현하기 위한 메타데이터를 도입했습니다. 그러나 파이썬 패키지에서 구체적인 외부 의존성 메타데이터를 사용하려면 주어진 의존성 식별자를 다른 생태계에서 사용되는 명세로 매핑해야 합니다.

이러한 매핑은 다음과 같은 이점을 제공합니다.

  • 자동 매핑 활성화: 도구들이 외부 의존성을 다른 패키징 저장소/생태계의 패키지로 자동으로 매핑할 수 있도록 합니다.
  • 오류 메시지 개선: 파이썬 패키지 설치 프로그램 및 빌드 프런트엔드에서 발생하는 오류 메시지에 사용자 시스템의 관련 시스템 패키지 관리자가 사용하는 패키지 이름과 함께 필요한 외부 의존성을 포함시킵니다.
  • 설치 지침 쿼리: 사용자가 해당 이름을 직접 쿼리하여 설치 지침을 얻을 수 있도록 합니다.

Linux 배포판, conda, Homebrew, Spack, Nix와 같은 패키징 생태계는 파이썬 패키지에 대한 완전한 의존성 집합을 필요로 합니다. 이들은 pyp2rpm (Fedora), Grayskull (conda), dh_python (Debian)과 같은 도구를 사용하여 업스트림 파이썬 패키지의 메타데이터에서 의존성 정보를 자동으로 생성하려고 시도합니다. PEP 725 이전에는 pyproject.toml이나 다른 표준 메타데이터 파일에 외부 의존성 메타데이터가 없었기 때문에 수동으로 처리되었습니다. 이 PEP는 자동 변환을 가능하게 하여 파이썬 패키징을 더 쉽고 안정적으로 만듭니다.

근거 (Rationale)

선례 (Prior Art)

다른 패키징 생태계에서도 유사한 문제 해결을 위한 선례가 있습니다.

  • R 언어: R 패키지용 시스템 요구 사항(System Requirements)을 가지고 있으며, apt-get과 같은 패키지 관리자의 설치 명령어로 외부 의존성 메타데이터를 번역하는 중앙 레지스트리가 있습니다. 이 시스템은 Ubuntu에서 패키지 빌드 성공률을 78.1%에서 95.8%로, CentOS 7에서 77.8%에서 93.7%로 향상시켰습니다.
  • RPM 기반 배포판 (Fedora): pyp2rpm에서 규칙 기반 구현(NameConvertor)을 사용합니다. PyPI 패키지의 RPM 이름은 일반적으로 f"python-{pypi_package_name}" 형식입니다.
  • Gentoo: dev-python/ 카테고리와 잘 정의된 규칙을 사용하여 파이썬 패키지 이름을 지정합니다.
  • Conda-forge: PyPI와 동일한 기본 이름을 사용하지만, 이름 충돌이나 이름 변경으로 인해 많은 예외가 있습니다 (예: PyTorch는 PyPI에서 torch이지만 conda-forge에서는 pytorch).
  • OpenStack 생태계: pkg-map과 bindep을 통해 Linux 배포판에 대한 매핑 노력을 처리합니다.

이러한 선례들은 매핑의 필요성과 함께, 중앙 집중화된 접근 방식과 분산된 접근 방식의 장단점을 보여줍니다.

거버넌스 및 유지보수 비용 (Governance and Maintenance Costs of Name Mappings)

다수의 패키징 생태계에 대한 외부 의존성 매핑 유지보수 비용은 잠재적으로 높습니다. PEP 804는 다음과 같이 레지스트리를 정의하여 비용을 분산시킵니다.

  • 중앙 관리 기관: 인식된 DepURL 및 알려진 생태계 매핑 목록을 유지합니다.
  • 대상 패키징 생태계: 실제 매핑 자체를 유지보수합니다.

따라서 이 시스템은 특정 생태계에 대한 옵트인(opt-in) 방식이며, 관련 유지보수 비용이 분산됩니다.

패키지 관리자별 설치 명령어 생성 (Generating Package Manager-Specific Install Commands)

파이썬 패키지 작성자는 종종 외부 의존성에 대한 설치 지침을 문서화합니다. 이 지침은 작성하고 최신 상태로 유지하기 어려울 뿐만 아니라, 일반적으로 한두 개의 플랫폼만 다룹니다. 예를 들어, SciPy의 외부 빌드 의존성(C/C++/Fortran 컴파일러, OpenBLAS, pkg-config) 설치 지침은 배포판마다 상당히 다릅니다.

이 PEP의 레지스트리를 사용하면, “이 생태계의 모든 외부 의존성에 대한 패키지 관리자 설치 명령어를 표시”하는 도구 명령을 통해 설치 지침을 더 포괄적이고 쉽게 유지보수할 수 있습니다. 각 생태계 매핑은 호환되는 패키지 관리자 목록과 패키지를 설치하고 쿼리하는 방법에 대한 템플릿화된 지침을 제공할 수 있습니다.

레지스트리 설계 (Registry Design)

매핑 인프라는 다음 구성 요소와 속성을 제시하도록 설계되었습니다.

  • 중앙 레지스트리: PEP 725 식별자(DepURL)의 중앙 레지스트리이며, 최소한 잘 알려진 일반 및 가상 식별자를 포함합니다.
  • 알려진 생태계 목록: 생태계 유지보수자가 이름 매핑을 등록할 수 있습니다.
  • 표준화된 스키마: 매핑이 어떻게 구조화되어야 하는지 정의합니다. 각 매핑은 지원되는 패키지 관리자가 어떻게 작동하는지에 대한 프로그래밍 방식의 세부 정보도 제공할 수 있습니다.

이 모든 문서는 JSON 파일로 제공되며, JSON 스키마에 의해 유효성이 검사됩니다. 이러한 리소스를 쿼리하고 활용하기 위한 파이썬 라이브러리 및 CLI도 제공됩니다.

명세 (Specification)

세 가지 스키마가 제안됩니다.

  1. 중앙 레지스트리 (Central Registry): PEP 725에서 도입된 알려진 DepURL의 중앙 레지스트리입니다. 이는 어떤 식별자가 정식(canonical)으로 인식되는지 정의하며, 알려진 별칭(aliases)도 포함합니다. 각 항목은 id 필드에 유효한 DepURL을 제공해야 하며, 선택적으로 자유 형식의 설명 텍스트를 포함할 수 있습니다. provides 필드를 통해 다른 항목을 참조할 수도 있으며, 이는 별칭이나 가상 패키지 구현에 유용합니다. 이 중앙 레지스트리는 [external] 테이블의 유효성을 검사할 수 있게 합니다. Twine과 같은 업로더는 식별자가 정식인지 확인하고, PyPI와 같은 인덱스 서버는 필요한 경우 아티팩트를 거부할 수 있습니다.

  2. 매핑 (Mappings): 중앙 레지스트리에서 사용 가능한 정식 항목을 제공하는 생태계별 식별자를 지정합니다. 매핑은 주로 딕셔너리 목록으로 구성되며, 각 항목은 id (정식 DepURL), description (선택적 설명), specs (생태계별 패키지 식별자), specs_from (다른 매핑 항목에서 specs를 가져옴), urls (관련 리소스로의 링크) 필드를 가집니다. 매핑은 또한 package_managers 섹션을 통해 해당 생태계에서 사용 가능한 패키지 관리자와 사용 방법을 지정해야 합니다. 여기에는 패키지 관리자의 이름, 설치 및 쿼리 명령, PEP 440 버전 지정자를 대상 패키지 관리자의 구문으로 매핑하는 방법에 대한 정보가 포함됩니다.

  3. 알려진 생태계 (Known Ecosystems): 알려진 생태계 목록은 해당 매핑의 정식 URL을 보고하고 각 생태계에 짧은 식별자를 할당하는 두 가지 역할을 합니다. 이 식별자는 로컬 파일 시스템에서 매핑 파일을 찾을 수 있도록 파일 이름에 사용되어야 합니다. Linux 배포판의 경우, os-release의 ID 매개변수로 보고된 식별자를 사용해야 합니다.

스키마 세부 정보 (Schema Details)

레지스트리 및 매핑을 완전히 표준화하기 위해 세 가지 JSON 스키마 문서가 제공됩니다.

  • 중앙 레지스트리 스키마 (central-registry.schema.json)
  • 알려진 생태계 스키마 (known-ecosystems.schema.json)
  • 매핑 스키마 (mappings.schema.json)

예시 (Examples)

pyproject-external CLI 및 API를 통해 이 이름 매핑 메커니즘이 어떻게 사용될 수 있는지 예시를 제공합니다.

  • pyproject-external CLI: [external] 테이블에 정의된 외부 의존성을 DepURL로 표시하거나, 자동 감지된 생태계에 매핑하여 표시하거나, 해당 외부 의존성을 설치하는 명령어를 생성할 수 있습니다. 또한, 중앙 레지스트리에 대해 [external] 테이블의 유효성을 검사하여 식별자가 정식인지 확인할 수 있습니다.
  • pyproject-external API: 파이썬 API를 통해 이러한 작업을 프로그래밍 방식으로 수행할 수 있습니다.
  • Grayskull: Conda 레시피 생성기인 Grayskull에 프로토타입 개념 증명(proof of concept) 구현이 기여되었습니다.

하위 호환성 (Backwards Compatibility)

이 제안은 하위 호환성에 영향을 미치지 않습니다.

보안 영향 (Security Implications)

이 제안은 기존 프로젝트에 어떠한 보안 영향도 주지 않습니다. 제안된 스키마, 레지스트리 및 매핑은 다운스트림 도구가 자유롭게 사용할 수 있는 리소스입니다. 다만, 향후 구현자들을 위한 몇 가지 권고사항이 있습니다. 매핑 스키마는 명령 실행 지침(package_managers[].commands)을 인코딩하는 필드를 제안하는데, 변조된 매핑은 이 지침을 변경할 수 있습니다. 따라서 도구는 온라인 소스에서 매핑을 가져오기 위해 인터넷 연결에 의존해서는 안 되며, 관련 문서를 벤더링(vendoring)하거나, 미리 패키징된 오프라인 배포본에 의존하거나, 가져온 문서의 진위 확인을 위한 모범 사례를 구현해야 합니다. 설치 명령은 사용자 시스템 구성을 변경할 가능성이 있으므로, 도구는 외부 의존성 설치를 위해 임시적이고 격리된 환경을 생성하는 것을 선호해야 합니다.

교육 방법 (How to Teach This)

이 PEP의 내용을 숙지해야 할 주요 대상은 네 그룹입니다.

  • 중앙 DepURL 레지스트리 유지보수자: 잘 알려진 DepURL 목록 및 매핑된 생태계를 관리합니다. 새로운 DepURL 정의에 대한 명확한 규칙을 준수해야 합니다.
  • 패키징 생태계 유지보수자: 해당 생태계의 매핑을 최신 상태로 유지합니다. 자동화된 스크립트나 주기적인 알림을 통해 매핑을 업데이트하는 것이 권장됩니다.
  • 외부 의존성을 필요로 하는 파이썬 프로젝트 유지보수자: 패키지에 필요한 외부 의존성을 가장 잘 나타내는 DepURL을 결정합니다. 중앙 레지스트리 문서와 예시를 통해 도움을 받을 수 있습니다.
  • 외부 의존성 메타데이터를 가진 패키지의 최종 사용자: 기본적으로 사용자 경험의 변화는 없지만, 외부 런타임 의존성으로 인해 영향을 받을 수 있는 경우, 호환되는 도구를 설치하여 옵트인해야 합니다. 누락된 매핑 항목에 대한 정보성 오류 메시지를 받아 문제 해결에 참여할 수 있습니다.

거부된 아이디어 (Rejected Ideas)

몇 가지 대안적인 아이디어가 고려되었으나 다음과 같은 이유로 거부되었습니다.

  • 동일한 기관이 관리하는 중앙 집중식 매핑: PyPI 규모에서 여러 생태계에 대한 매핑 유지보수 부담은 비현실적입니다. 따라서 중앙 기관은 중앙 레지스트리와 알려진 생태계 목록만 관리하고, 매핑 유지보수는 대상 생태계에서 처리하는 것으로 제안되었습니다.
  • 생태계별 패키지 변형 허용: dep:debian/libsymspg2-dev와 같은 생태계별 변형 식별자는 문법적으로 유효하지만, 중앙 레지스트리에서는 일반적인 식별자를 선호합니다. 이는 가능한 한 생태계에 구애받지 않는(ecosystem-agnostic) 메타데이터를 장려하기 위함입니다.
  • 중앙 레지스트리에 더 많은 패키지 메타데이터 추가: 중앙 레지스트리에는 DepURL 목록과 최소한의 식별용 메타데이터(설명, 관련 URL)만 포함해야 합니다. 추가 세부 정보는 대상 생태계에서 자체 매핑을 통해 주석 처리하도록 제안되었습니다.
  • PyPI 프로젝트를 대상 생태계의 재패키징된 대응물에 매핑: 이 PEP의 제안은 PyPI -> 생태계 매핑을 직접 고려하지 않지만, 동일한 스키마를 이 목적으로 재사용할 수 있습니다.

부록 B: 가상 버전 관리 제안 (Appendix B: Virtual Versioning Proposal)

가상 의존성은 비가상 의존성과 동일한 구문으로 버전 관리될 수 있지만, 그 의미는 모호할 수 있습니다. 중앙 레지스트리 유지보수자들이 이러한 의미를 표준화할 때 고려할 몇 가지 제안이 있습니다.

  • OpenMP: 표준의 MAJOR.MINOR 버전을 따릅니다 (예: >=4.5).
  • BLAS/LAPACK: Reference LAPACK에서 사용하는 버전 관리(MAJOR.MINOR.MICRO)를 사용합니다 (예: >=3.10.0).
  • 컴파일러: 언어 표준을 구현하며, C, C++, Fortran의 경우 연도별로 버전이 지정됩니다. 올바른 정렬을 위해 4자리 연도 사용을 권장합니다 (예: C99는 >=1999).

⚠️ 알림: 이 문서는 AI를 활용하여 번역되었으며, 기술적 정확성을 보장하지 않습니다. 정확한 내용은 반드시 원문을 확인하시기 바랍니다.

Comments