PEP 792 – 단순 색인의 프로젝트 상태 표지

Author:

William Woodruff <william at yossarian.net>, Facundo Tuesca <facundo.tuesca at trailofbits.com>

Sponsor:

Donald Stufft <donald at stufft.io>

PEP-Delegate:

Donald Stufft <donald at stufft.io>

Discussions-To:

Discourse thread

Status:

Final

Type:

Standards Track

Topic:

Packaging

Created:

21-May-2025

Post-History:

03-Feb-2025, 09-Jun-2025

Resolution:

08-Jul-2025

---

Table of Contents

• 초록
• 근거 및 동기
• 명세
  • 프로젝트 상태 표지
    • active
    • archived
    • quarantined
    • deprecated
  • 인덱스 API의 상태 마커
    • HTML 인덱스
    • JSON 인덱스
• 향후 고려 사항
• 보안 영향
• 이 내용을 가르치는 방법
• 거부된 아이디어
  • “예약된” 키 사용
  • PyPI의 비표준 JSON API에 있는 프로젝트 마커
  • 여러 프로젝트 상태 마커를 동시에 사용하기
• 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, Project Status Markers, is maintained on the PyPA specs page.

×

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

초록

이 PEP는 색인에서 제공하는 표준화된 프로젝트 상태 표지 집합과 HTML 및 JSON 단순 색인에서 해당 표지를 전달하기 위한 메커니즘을 제안합니다.

근거 및 동기

프로젝트의 “상태”는 중요한 메타데이터이며, Python 패키징 생태계의 규모와 복잡성이 모두 증가하면서 그 중요성이 더욱 커지고 있습니다. 프로젝트 상태(또는 최근 활동과 같은 대리 지표)는 프로젝트가 유지 관리되고 있는지 또는 다른 측면에서 사용에 적합한지를 판단하는 데 유용합니다.

Python 패키징에는 프로젝트의 “상태”를 전달하기 위한 서로 다른 메커니즘이 최소 세 가지 있습니다.

1. 배포 패키지는 PEP 301에서 처음 명시된 대로 메타데이터에 Trove 분류자를 포함할 수 있습니다. 지원되는 분류자 목록은 PyPA가 관리하며, Development Status 계층을 포함합니다. 예를 들어, 배포 패키지는 해당 배포 패키지의 프로젝트가 비활성 상태임을 나타내기 위해 Development Status :: 7 - Inactive 분류자를 포함할 수 있습니다.

   Trove 분류자는 유연하지만 상당한 제한도 따릅니다. 즉, 기계가 읽을 수 있고 PyPI와 같은 색인에 렌더링되지만, 유지 관리자가 프로젝트의 개발 상태를 업데이트하려 할 때마다 하나 이상의 새 배포 패키지를 업로드해야 합니다. 또한 Python 패키징 생태계에서 배포 패키지는 사실상 변경 불가능하므로, 프로젝트의 현재 상태를 반영하도록 이전 배포 패키지의 분류자를 업데이트할 수 없습니다.

2. 색인은 PEP 592에서 처음 명시된 대로 배포 패키지와 릴리스를 “yanked” 상태로 표시할 수 있습니다. Yank된 배포 패키지는 의존성 해결 대상이 될 수 없습니다.

   배포 패키지가 yank되면 HTML 색인에서는 data-yanked로, JSON 색인에서는 yanked: bool | str로 표시됩니다. 또한 PyPI와 같은 색인은 기본적으로 yank된 배포 패키지를 숨기며, 사용자가 해당 배포 패키지로 직접 이동하면 알림과 함께 이를 표시합니다.

   Yanking은 Trove 분류자처럼 기계가 읽을 수 있지만, 범용 목적이 아니라 단일 목적입니다. 사용자는 특정 배포 패키지를 yank하는 자유 형식 텍스트 사유를 지정할 수 있지만, yanking의 의미론은 고정되어 있으며, 기계가 해당 자유 형식 텍스트 사유를 바탕으로 프로젝트 상태를 신뢰성 있게 추론할 수 없습니다.

3. PyPI 자체에는 프로젝트 전체(즉, 모든 릴리스와 배포 패키지)에 적용되는 프로젝트 상태가 있습니다. 프로젝트 상태에는 유지 관리자가 제어할 수 있는 상태와 색인 관리자가 제어할 수 있는 상태가 모두 있습니다.
   • PyPI 관리자는 프로젝트를 “quarantine”할 수 있습니다. Quarantine은 강화된 yank처럼 동작합니다. quarantine된 동안 프로젝트 전체를 계속 설치할 수 없으며, 관리자만 quarantine을 해제할 수 있습니다.
   • 프로젝트 소유자는 프로젝트를 “archive”할 수 있습니다. 프로젝트를 아카이브하면 해당 프로젝트에 대한 새 릴리스 및 배포 패키지 업로드가 비활성화되지만, 그 외에는 프로젝트를 다운로드할 수 있는 기능에 영향을 주지 않습니다.

   프로젝트 상태는 원칙적으로 기계가 읽을 수 있지만, 현재 PyPI의 어떤 API를 통해서도 노출되지 않습니다. 대신 PyPI는 각 프로젝트의 사용자 대상(즉, 색인이 아닌) 웹 페이지에 프로젝트 상태를 렌더링합니다.

요약하면, Python 패키징에서 프로젝트의 “상태”를 전달하는 방법은 여러 가지입니다. 그러나 그중 어느 것도 우리가 원하는 네 가지 특성을 충족하지 않습니다. 현재 기계가 읽을 수 있고, 일반적이며(즉, 둘 이상의 가능한 상태를 전달하며), 색인에 종속되지 않고, 릴리스별 또는 배포 패키지별이 아니라 프로젝트 전체에 적용되는 프로젝트 상태 표시자는 없습니다.

Mechanism	Machine-readable	General	Index-agnostic	Project-wide
Trove classifiers	✅	✅	✅	❌
Yanking	✅	❌	✅	✅
PyPI project statuses	✅	✅	❌	✅

이 PEP는 네 가지 조건을 모두 충족하는 색인에 종속되지 않는 메커니즘으로 PyPI의 프로젝트 상태를 채택할 것을 제안합니다.

명세

이 PEP는 프로젝트 상태 표지 집합과 해당 표지를 표준 HTML 및 JSON 색인에 표시하는 방식이라는 두 가지 측면을 명시합니다.

프로젝트 상태 표지

이 PEP는 다음 프로젝트 상태 표식을 제안합니다.

프로젝트에는 항상 정확히 하나의 상태가 있습니다. 상태가 명시적으로 기록되지 않은 경우 프로젝트는 active 상태인 것으로 간주됩니다.

색인은 필요에 따라 이 PEP에 명시된 상태 마커의 일부를 MAY구현할 수 있습니다.

이 PEP는 어떤 주체(즉, 프로젝트 유지 관리자, 색인 관리자 등)가 어떤 상태를 설정하고 해제할 수 있는지를 규정하지 않습니다.

active

설명: 프로젝트가 활성 상태입니다. 프로젝트의 기본 상태입니다.

색인 의미론:

• 프로젝트를 호스팅하는 색인은 프로젝트에 새 배포 패키지를 업로드하는 것을 반드시 허용해야 합니다.
• 색인은 프로젝트의 기존 배포 패키지를 다운로드할 수 있도록 반드시 제공해야 합니다.

설치 프로그램 의미론: 없습니다.

archived

설명: 프로젝트가 앞으로 업데이트될 것으로 예상되지 않습니다.

색인 의미론:

• 프로젝트를 호스팅하는 색인은 프로젝트에 새 배포 패키지를 업로드하는 것을 허용해서는 안 됩니다.
• 색인은 프로젝트의 기존 배포 패키지를 다운로드할 수 있도록 제공해야 합니다.

설치 프로그램 의미론:

• 설치 도구는 프로젝트가 보관 처리되었다는 경고를 생성할 수 있습니다.

quarantined

설명: 프로젝트는 일반적으로 사용하기에 안전하지 않은 것으로 간주됩니다. 예를 들어 악성 코드 때문일 수 있습니다.

색인 의미론:

• 프로젝트를 호스팅하는 색인은 프로젝트에 새 배포 패키지를 업로드하는 것을 허용해서는 안 됩니다.
• 색인은 프로젝트의 어떤 배포 패키지도 다운로드할 수 있도록 제공해서는 안 됩니다.

설치 프로그램 의미론:

• 설치 도구는 프로젝트의 격리에 관한 경고를 생성할 수 있습니다, 하지만 그렇게 해도 사실상 의미가 없습니다(색인이 설치할 배포 패키지를 제공하지 않을 것이기 때문입니다).

deprecated

설명: 프로젝트는 더 이상 사용되지 않는 것으로 간주되며, 다른 프로젝트로 대체되었을 수 있습니다.

색인 의미론:

• 이 상태는 active와 동일한 의미론을 가집니다.

설치 프로그램 의미론:

• 설치 도구는 프로젝트의 사용 중단에 관한 경고를 생성할 수 있습니다.

인덱스 API의 상태 마커

이 PEP는 인덱스 API 버전 1.4를 정의합니다.

아래 HTML 및 JSON 단순 인덱스에 대한 모든 변경 사항은 루트 인덱스 응답이 아니라 프로젝트별 수준, 즉 각 프로젝트의 인덱스 응답 내부에서 발생합니다. 이 PEP에서는 루트 인덱스 응답 변경을 제안하지 않습니다.

HTML 인덱스

다음 변경 사항이 단순 저장소 API에 적용됩니다.

• 프로젝트별 인덱스는 pypi:repository-version을 1.4로 정의해야 MUST 합니다.
• 프로젝트별 인덱스는 프로젝트의 상태 마커를 content에 담은 적절한 pypi:project-status 메타 태그를 추가해야 SHOULD 합니다. 프로젝트가 active로 표시된 경우 인덱스는 pypi:project-status 메타 태그를 생략할 수 MAY 있습니다.
• 프로젝트별 인덱스는 프로젝트의 상태를 맥락화하는 자유 형식 텍스트를 content에 담은 pypi:project-status-reason 메타 태그를 포함할 수 MAY 있습니다. 프로젝트가 active로 표시되었거나 이유가 제공되지 않은 경우 인덱스는 pypi:project-status-reason 메타 태그를 생략할 수 MAY 있습니다.

예를 들어, sampleproject가 quarantined로 표시된 후 다음은 유효한 HTML 인덱스 응답입니다.

 <!DOCTYPE html>
 <html>
   <head>
     <meta name="pypi:repository-version" content="1.4">
     <meta name="pypi:project-status" content="quarantined">
     <meta name="pypi:project-status-reason" content="the project is haunted">
     <title>Links for sampleproject</title>
   </head>
   <body>
     <h1>Links for sampleproject</h1>
   </body>
 </html>

위의 quarantined의미에 따라 인덱스 응답에는 해당 프로젝트의 배포 링크가 포함되지 않는다는 점에 유의하십시오.

JSON 인덱스

다음 변경 사항이 JSON 단순 인덱스에 적용됩니다.

• 프로젝트별 인덱스는 meta.api-version을 1.4로 정의해야 MUST 합니다.
• 프로젝트별 인덱스는 JSON 응답에 프로젝트의 상태 마커를 값으로 갖는 project-status.state 키를 포함해야 SHOULD 합니다. 프로젝트가 active로 표시된 경우 인덱스는 project-status.state 키를 생략할 수 MAY 있습니다.
• 프로젝트별 인덱스는 JSON 응답에 프로젝트의 상태를 맥락화하는 자유 형식 텍스트를 값으로 갖는 project-status.reason 키를 포함할 수 MAY 있습니다. 프로젝트가 active로 표시되었거나 이유가 제공되지 않은 경우 인덱스는 project-status.reason 키를 생략할 수 MAY 있습니다.

예를 들어, sampleproject가 quarantined로 표시된 후 다음은 유효한 JSON 인덱스 응답입니다.

 {
   "meta": {
     "api-version": "1.4"
   },
   "project-status": {
     "status": "quarantined",
     "reason": "the project is haunted"
   },
   "alternate-locations": [],
   "files": [],
   "name": "sampleproject",
   "versions": [
     "1.2.0",
     "1.3.0",
     "1.3.1",
     "2.0.0",
     "3.0.0",
     "4.0.0"
   ]
 }

HTML 인덱스와 마찬가지로 JSON 응답에는 quarantined프로젝트의 배포 링크가 포함되지 않는다는 점에 유의하십시오.

향후 고려 사항

이 PEP는 프로젝트 상태 마커 네 가지만 정의합니다: active, archived, quarantined, deprecated.

향후 PEP(또는 PyPA 표준화 프로세스)는 필요에 따라 추가 프로젝트 상태 마커를 정의할 수 있습니다. 향후 메타데이터 변경으로 “개방형” 상태 마커, 즉 인덱스와 설치 프로그램이 허용되는 상태의 단일 공통 목록을 반드시 공유하지 않아도 되는 상태 마커를 허용하지 않는 한, 향후 상태 마커에는 메타데이터 버전 상향이 필요할 수 있습니다.

이 PEP에서 명시한 것처럼 프로젝트 상태 마커는 “bare”이며, 프로젝트 보관 처리에 대한 설명과 같은 사용자 제어 메타데이터를 추가로 전달하지 않습니다.

향후 PEP는 릴리스 철회 중 허용되는 자유 형식 텍스트와 유사한 방식으로 프로젝트 상태 메커니즘을 확장하여 사용자 제어 메타데이터를 포함할 수 있습니다.

보안 영향

이 PEP는 프로젝트 상태 마커 추가와 관련된 긍정적 또는 부정적 보안 영향을 식별하지 않습니다.

이 내용을 가르치는 방법

이 PEP에 관해 Python 커뮤니티를 교육하는 데에는 두 가지 측면이 있습니다.

• 일반 패키지 관리자는 프로젝트 상태 마커를 설정할 수 있음을 안내받아야 하며, 예를 들어 프로젝트가 보관되었거나 더 이상 사용되지 않음을 다운스트림 사용자에게 알릴 수 있어야 합니다.

  이 PEP가 승인되면, 이 PEP의 작성자는 기능 공지 블로그 게시물과 PyPI’s user documentation 업데이트를 비롯한 관리자 대상의 적절한 문서 및 커뮤니케이션에 관해 PyPI와 협력합니다.

• 설치 프로그램 및 색인 관리자는 새로운 프로젝트 상태 마커와 이를 해석하는 방법을 안내받아야 합니다.

  이 PEP가 승인되면, 이 PEP의 작성자는 PyPI에서 이를 구현하여 다른 색인을 위한 참조 구현으로 제공합니다.

  이 PEP는 설치 프로그램 동작의 어떠한 변경도 의무화하지 않습니다. 그러나 이 PEP가 승인되면, 이 PEP의 작성자는 인기 있는 설치 프로그램(예: pip)의 관리자와 협력하여 각 관리자가 프로젝트 상태를 어느 정도까지 표시할지 결정하는 데 도움을 제공합니다.

거부된 아이디어

“예약된” 키 사용

이 PEP의 한 가지 대안은 프로젝트 상태 마커를 직접 표준화하지 않고, 대신 표준 내부의 기존 메커니즘을 사용하여 비표준적인 방식으로 이를 전달하는 것입니다.

예를 들어, JSON simple index는 다음과 같이 설명합니다.

어느 수준에서든 선행 밑줄이 있는 키는 색인 서버에서 사용하기 위한 비공개 키로 예약됩니다. 향후 어떤 표준도 그러한 키에 의미를 부여하지 않습니다.

실제로 이는 다음과 같은 방식이 표준을 준수함을 의미합니다.

{
  "meta": {
    "api-version": "1.4"
  },
  "_project-status": "quarantined",
  "alternate-locations": [],
  "files": [],
  "name": "sampleproject",
  "versions": [
    "1.2.0",
    "1.3.0",
    "1.3.1",
    "2.0.0",
    "3.0.0",
    "4.0.0"
  ]
}

그러나 이 접근 방식에는 몇 가지 단점이 있습니다.

• 표준에 부합하는 도구(예: pip, pip-audit 및 uv)는 “예약된” 키를 사용하는 것이 허용될 수 없다고 판단할 수 있습니다. 해당 키에는 표준 의미론이나 호환성 속성이 없기 때문입니다.
• “예약된” 접근 방식은 JSON 단순 색인에만 적합하며, HTML 단순 색인에는 이에 상응하는 메커니즘이 없습니다. 이는 HTML 단순 색인의 소비자뿐 아니라 JSON 색인을 사용할 수 있지만 HTML 색인만 노출하는 미러 구현에도 불리하게 작용합니다.

PyPI의 비표준 JSON API에 있는 프로젝트 마커

표준화를 피하는 또 다른 대안은 프로젝트 상태 마커를 노출하되, PyPI의 non-standard JSON API에서만 노출하는 것입니다. PyPI는 이 API의 레이아웃을 완전히 제어하므로, PEP나 밑줄 접두사 없이 project-status 또는 유사한 키를 포함할 수 있습니다.

이는 위의 “예약된” 키 접근 방식과 유사한 단점이 있으며, 더 일반적으로는 표준 API와 비표준 API 간의 차이를 심화합니다.

여러 프로젝트 상태 마커를 동시에 사용하기

이 PEP의 이전 버전에서는 여러 프로젝트 마커를 동시에 지원하는 방안을 제안하는 것을 고려했습니다. 예를 들어 프로젝트를 archived와 quarantined로 모두 표시할 수 있습니다.

검토 후, 이는 복잡성 문제로 거부되었습니다. 여러 프로젝트 상태 마커를 사용하려면 해당 의미를 병합할 때의 충돌 해결 메커니즘과 어떤 마커가 배타적인지를 나타내는 상태 머신을 PEP에서 지정해야 하기 때문입니다(예를 들어, active는 개념적으로 다른 모든 마커와 배타적인 반면, archived와 quarantined는 개념적으로 서로 호환됩니다).

Copyright

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