PEP 833 – HTML 단순 저장소 API 동결

Author:: William Woodruff <william at yossarian.net>
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-Apr-2026
Post-History:: 13-Apr-2026, 21-Apr-2026
Resolution:: 20-May-2026

Table of Contents

초록
근거 및 동기
명세
향후 고려 사항
보안 영향
이 내용을 가르치는 방법
거부된 아이디어
- 아무것도 하지 않기
- HTML 표현을 공격적으로 제거하기
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, Simple repository API, is maintained on the PyPA specs page.

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

초록

이 PEP는 단순 저장소 API의 표준 HTML 표현을 동결할 것을 제안합니다. 이는 PEP 503에서 최초로 명시되었으며 이후 PEP들에서 업데이트되었습니다.

이 PEP의 맥락에서 “동결”은 표준화 과정의 관점에서 HTML 표현이 완성된 것으로 간주되며, 향후 PEP에서 업데이트되어서는 SHOULD NOT 한다는 의미입니다. 대신 향후 PEP는 표준 JSON 표현을 대상으로 SHOULD 합니다. 이는 PEP 691에서 최초로 명시되었습니다.

마찬가지로, 이 PEP의 HTML 표현 동결은 설치 프로그램이 HTML 표현 지원을 제거해야 한다거나, (PyPI와 같은) 색인이 HTML 표현 제공을 중단할 것이거나 중단해야 한다고 규정하지 않습니다.

근거 및 동기

Python 패키지 색인에 HTML 표현을 사용하는 것은 Python 패키징을 표준화하려는 노력보다 앞섭니다. 따라서 PEP 503에서 표준화된 HTML 표현은 기존 관행, 특히 PyPI의 관행을 형식화한 것이지 설계한 것이 아닙니다.

Python 패키지 색인의 HTML 표현은 Python 패키징 생태계에 훌륭하게 기여해 왔습니다. 모든 색인과 설치 도구가 지원하는 기준 표현으로 기능했으며, 설치 도구 및 미러와의 하위 호환성을 유지하면서 PyPI가 색인 표시를 점진적으로 현대화할 수 있도록 했습니다. PEP 629, PEP 714, PEP 740, PEP 792를 비롯한 많은 PEP가 이러한 접근 방식의 실행 가능성을 보여 줍니다.

동시에 Python 패키징 전반이 현대화됨에 따라 HTML 표현에는 여러 한계가 점점 더 분명하고 중요하게 드러났습니다.

HTML 표현은 하위 호환성 때문에 경직되어 있습니다. 이러한 경직성 때문에 새로운 메타데이터를 표현하기가 어렵고, 이를 시도하는 PEP는 기존 소비자가 HTML 구조에 대해 갖는 가정을 방해하지 않기 위해 일반적으로 변경 사항을 <meta> 태그나 data- 속성에 억지로 끼워 넣어야 합니다.
이러한 억지 삽입 과정에서는 HTML 색인을 수정하는 PEP가 구조화된 데이터를 인코딩하기 위한 구문도 고안해야 합니다. 예를 들어 PEP 792는 pypi:project-status 및 pypi:project-status-reason이라는 메타 태그를 추가하여 JSON 표현에 자연스럽게 나타나는 객체 표현을 사실상 평탄화합니다.

마찬가지로 HTML 표현의 경직성은 최적화 장벽이 됩니다. PEP 658은 색인이 단순 저장소 API를 통해 배포 메타데이터를 제공하도록 허용하지만, HTML 표현 안에 해당 메타데이터를 간단하면서도 하위 호환성을 유지하는 방식으로 인코딩할 방법이 없기 때문에 설치 도구는 비교적 적은 양의 정보를 가져오기 위해 추가 HTTP 왕복을 수행해야 합니다. PEP 740도 유사한 접근 방식을 채택하며, 이에 따른 오버헤드 영향도 유사합니다.

실제로 일부 색인 PEP는 HTML 표현을 전혀 수정하지 않고 대신 JSON 표현에만 집중하기로 했습니다. PEP 700은 예를 들어 배포별 메타데이터 및 JSON 표현에 최상위 versions 키를 도입하지만 HTML 표현은 수정하지 않습니다. 이에 대한 최초의 근거는 HTML 소비자가 새로운 메타데이터를 필요로 할 가능성이 낮다는 것이었습니다.
이와 관련하여 HTML 표현을 타사에서 사용하는 방식은 종종 취약합니다. 구문상 유효하고 의미론적이지 않은 PyPI HTML 표현의 변경조차도 공백을 포함한 HTML의 정확한 구조에 대한 부적절한 가정 때문에 장애를 일으키는 것으로 알려져 있습니다.
반면 JSON 표현의 사용은 견고한 JSON 구문 분석 라이브러리가 널리 사용되므로 의미론적이지 않은 변경에 더 강건합니다. HTML을 견고하게 처리하는 것은 자연스럽게 가능하지만, 소비자는 정규 표현식 및 이와 유사한 애드혹 구문 분석 기법을 사용하는 취약한 접근 방식을 선호하여 HTML 구문 분석의 인식된 복잡성과 일반성을 피하려는 유혹을 받는 경우가 많습니다.
실제로 HTML 표현의 점진적 개선에 대한 도입은 제한적입니다. PyPI 자체는 일반적으로 새로운 기능을 도입하지만, 타사 색인, 특히 기업용으로 판매되는 색인은 PEP 503에서 최초로 정의된 절대적인 최소 표현만 제공하는 경우가 많습니다.
그 결과 HTML 표현이 개선되었을 때조차 많은 소비자는 그러한 개선의 혜택을 받지 못합니다.

종합하면 이러한 한계로 인해 HTML 표현은 (1) 강건한 방식으로 확장하기 어려운 경우가 많고, (2) 표준화 과정에서 현대화를 위해 노력하더라도 많은 소비자가 Python 패키징과 상호 작용하는 방식에 관해서는 사실상 동결되어 있습니다.

이 PEP의 목적은 이러한 현재 상태를 공식화하는 것입니다.

명세

단순 저장소 API의 HTML 표현은 Python 패키징 표준화 과정의 목적상 동결됩니다. 향후 Python 패키징 PEP는 단순 저장소 API의 기본 형식으로 JSON 표현을 대상으로 MUST 합니다. 해당 PEP는 HTML 표현을 변경해서는 SHOULD NOT 합니다.

이 PEP는 PyPI에서 HTML 표현의 지위를 변경하지 않으며 설치 도구의 동작 변경을 규정하지 않습니다.

이러한 동결의 한 가지 기능적 결과는 단순 저장소 API에 대한 향후 변경 사항이 현재와 같이 버전 관리되지만, 버전 관리 표시에 변경 사항이 적용되는 표현은 JSON 표현뿐이라는 것입니다. 예를 들어 향후 PEP가 단순 저장소 API의 버전 1.5를 도입하더라도 HTML 표현은 다음 버전 관리 표시를 유지합니다:

<meta name="pypi:repository-version" content="1.4">

본 명세서는 HTML 표현의 향후 업데이트 금지를 설명할 때 의도적으로 MUST NOT 대신 SHOULD NOT을 사용합니다. 향후 PEP은 HTML 표현을 업데이트할 수도 있지만, 본 명세서는 두 표현을 대칭적으로 변경하려는 바람을 넘어서는 구체적이고 설득력 있는 이유 없이 그렇게 하는 것을 권장하지 않습니다.

향후 고려 사항

이 PEP는 인덱스와 설치 프로그램이 HTML 표현을 처리하는 방식에 어떠한 변경도 규정하지 않습니다.

2026년 4월 현재, 인덱스나 설치 프로그램에서 HTML 표현에 대한 지원을 완전히 제거할 가능성은 비현실적입니다. HTML 표현은 생태계에 단순히 너무 중요하며, 이를 제거하려는 노력은 극도로 부당하고 불합리한 혼란을 초래할 것입니다.

그러나 향후 HTML 표현이 상상할 수 없을 정도로 완전히 제거되거나 레거시/기본 비활성화 흐름으로 전환될 가능성을 배제할 수는 없습니다. 이 PEP는 그러한 미래를 배제하지 않지만, 그렇다고 이를 제안하지도 않습니다.

Python 패키징 커뮤니티는 HTML 표현을 완전히 제거하기 어렵거나 실행 불가능하게 만드는 동작과 관련하여 다음을 비롯한 몇 가지 중요한 관찰을 제시했습니다.

기본값이라는 특성상 HTML 표현은 내부적으로 도입하기가 매우 쉽습니다. 어떠한 (명시적) 콘텐츠 협상도 필요하지 않으며, CDN이나 최소한의 HTTP 서버(예: python -m http.server)를 통해 간단히 제공되는 경우가 많습니다.
JSON 표현도 기술적으로는 콘텐츠 협상이 필요하지 않지만, 실제로 이를 사용하는 클라이언트는 동일한 URL이 두 표현을 모두 제공한다는 가정 때문에 명시적인 콘텐츠 협상을 수행할 것으로 예상합니다. 따라서 HTML 표현을 제거하려는 향후 노력에는 JSON 표현을 더 간단하게 도입할 수 있는 방안이 필요할 가능성이 높습니다.
Python 표준 라이브러리에 증분 HTML 구문 분석을 위한 html.parser가 포함되어 있으므로, 현재 HTML 표현은 pip와 같은 설치 프로그램이 증분적으로 구문 분석하기 더 쉽습니다. 이는 대규모 HTML 인덱스 응답, 예를 들어 수백 또는 수천 개의 배포 패키지가 포함된 패키지의 상세 응답에서 발생하는 메모리 오버헤드를 완화하는 데 도움이 됩니다.
반면 Python 표준 라이브러리에는 현재 증분 JSON 파서가 없습니다. 증분 JSON 구문 분석은 실행 불가능한 작업이 아니며(증분 HTML 구문 분석보다 엄밀히 말해 덜 복잡합니다), 표준 라이브러리 솔루션이 없다는 점은 도입 장벽을 초래합니다. HTML 표현을 제거하려는 향후 노력에는 pip 내부에서 증분 JSON 구문 분석을 지원하는 견고한 표준 라이브러리 솔루션(또는 허용 가능한 방식으로 vendoring할 수 있는 서드파티 솔루션)이 필요할 가능성이 높습니다.

보안 영향

이 PEP는 단순 저장소 API의 HTML 표현을 동결하는 것과 관련된 긍정적 또는 부정적 보안 영향을 식별하지 않습니다.

이 내용을 가르치는 방법

이 PEP는 Python 패키징 표준 절차를 목적으로 단순 저장소 API의 HTML 표현만 동결하므로, 이 PEP가 최종 사용자에게 미치는 영향은 제한적입니다.

그러나 인덱스 표현을 현대화하려는 서드파티 인덱스에 대해서는, 이 PEP가 채택될 경우 다음을 제안합니다.

이 PEP의 작성자들은 PyPI의 유지 관리자들과 적절한 대외 문서 및 커뮤니케이션을 조율하며, 적절하다고 판단되는 경우 PyPI blog에 발표하는 것을 포함합니다.
이 PEP의 작성자들은 단순 저장소 API의 living standard에 적절한 변경을 적용하며, HTML 표현이 향후 업데이트를 받지 않는다는 점과 향후 업데이트의 혜택을 받으려는 소비자는 대신 JSON 표현을 우선해야 한다는 점을 나타내기 위해 적절한 경우 주의 사항과 강조 문구를 포함합니다.