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된 배포판을 숨기며, 사용자가 해당 배포판으로 직접 이동하면 알림과 함께 표시합니다.

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

3. PyPI 자체에는 프로젝트 전체(즉, 모든 릴리스와 배포판)에 적용되는 프로젝트 상태가 있습니다. 프로젝트 상태에는 유지 관리자가 제어할 수 있는 상태와 색인 관리자가 제어할 수 있는 상태가 모두 있습니다:
   • PyPI 관리자는 프로젝트를 “격리(quarantine)”할 수 있습니다. 격리는 강화된 yank처럼 동작합니다: 격리되어 있는 동안 프로젝트 전체를 설치할 수 없으며, 관리자만 격리를 해제할 수 있습니다.
   • 프로젝트 소유자는 프로젝트를 “보관(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

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

색인 의미론:

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

설치 프로그램 의미: 없음.

archived

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

색인 의미론:

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

설치 프로그램 의미:

• 설치 프로그램은 프로젝트의 보관 처리에 대해 경고를 표시할 수 있습니다(MAY).

quarantined

설명: 프로젝트가 악성 코드 등의 이유로 일반적으로 사용하기에 안전하지 않은 것으로 간주됩니다.

색인 의미론:

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

설치 프로그램 의미:

• 설치 프로그램은 프로젝트의 격리에 대해 경고를 표시할 수 있습니다(MAY). 다만 색인이 설치할 배포를 하나도 제공하지 않으므로 이는 사실상 의미가 없습니다.

deprecated

설명: 프로젝트가 더 이상 쓸모없는 것으로 간주되며, 다른 프로젝트로 대체되었을 수 있습니다.

색인 의미론:

• 이 상태는 active와 같은 의미론을 가집니다.

설치 프로그램 의미:

• 설치 프로그램은 프로젝트의 폐지에 대해 경고를 표시할 수 있습니다(MAY).

색인 API의 상태 마커

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

아래에 설명하는 HTML 및 JSON 단순 색인의 모든 변경 사항은 루트 색인 응답이 아닌 프로젝트별 수준, 즉 각 프로젝트의 색인 응답 안에서 이루어집니다. 이 PEP는 루트 색인 응답에 대한 변경을 제안하지 않습니다.

HTML 색인

단순 저장소 API에 다음과 같은 변경이 이루어집니다:

• 프로젝트별 색인은 pypi:repository-version을 1.4로 정의해야 합니다(MUST).
• 프로젝트별 색인은 적절한 pypi:project-status 메타 태그를 추가하고, 그 content에 프로젝트의 상태 마커를 지정해야 합니다(SHOULD). 프로젝트가 active로 표시된 경우 색인은 pypi:project-status 메타 태그를 생략할 수 있습니다(MAY).
• 프로젝트별 색인은 pypi:project-status-reason 메타 태그를 포함할 수 있으며(MAY), 그 content에는 프로젝트의 상태를 설명하는 자유 형식 텍스트를 지정합니다. 프로젝트가 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에서는 릴리스 철회(yanking) 시 허용되는 자유 형식 텍스트와 유사한 방식으로, 사용자가 제어하는 메타데이터를 포함하도록 프로젝트 상태 메커니즘을 확장할 수 있습니다.

보안 영향

이 PEP는 프로젝트 상태 마커 추가와 관련된 긍정적이거나 부정적인 보안 영향을 확인하지 못했습니다.

교육 방법

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

• 일반 패키지 유지 관리자에게는 프로젝트 상태 마커를 설정할 수 있다는 점을 알려야 합니다. 예를 들어 이를 통해 다운스트림에 프로젝트가 보관 처리되었거나 폐지되었음을 알릴 수 있습니다.

  이 PEP가 수락되면, 이 PEP의 작성자는 PyPI와 협력해 유지 관리자를 위한 적절한 문서와 안내를 마련할 것입니다. 여기에는 기능 발표 블로그 게시물과 PyPI 사용자 문서의 갱신이 포함됩니다.

• 설치 프로그램과 색인의 유지 관리자에게는 새 프로젝트 상태 마커와 그 해석 방법을 알려야 합니다.

  이 PEP가 채택되면, 이 PEP의 저자들이 PyPI에 이를 구현할 것이며, 이 구현은 다른 색인을 위한 참조 구현 역할을 할 것입니다.

  이 PEP는 설치 프로그램의 동작 변경을 의무화하지 않습니다. 다만 이 PEP가 수락되면, 이 PEP의 작성자는 널리 쓰이는 설치 프로그램(예: pip)의 유지 관리자와 협력해 각 설치 프로그램이 프로젝트 상태를 어느 정도까지 표시할지 정할 수 있도록 도울 것입니다.

기각된 아이디어

“예약된” 키 사용하기

이 PEP의 대안 하나는 프로젝트 상태 마커를 직접 표준화하지 않고, 표준에 이미 있는 메커니즘을 사용하여 비표준 방식으로 마커를 전달하는 것입니다.

예를 들어 JSON 단순 색인에는 다음과 같이 적혀 있습니다.

(어느 수준에서든) 밑줄로 시작하는 키는 색인 서버가 사용하는 비공개 키로 예약되어 있습니다. 향후 어떤 표준도 이러한 키에 의미를 부여하지 않을 것입니다.

결과적으로 다음과 같은 방식은 표준을 준수하는 것이 됩니다.

{
  "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의 비표준 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.