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는 원래 PEP 503에서 명세되고 이후 여러 PEP를 거쳐 갱신된 단순 저장소 API의 표준 HTML 표현을 동결할 것을 제안합니다.

이 PEP의 맥락에서 “동결”이란 HTML 표현이 표준화 절차의 관점에서 완결된 것으로 간주되며, 향후 PEP에 의해 갱신되어서는 안 된다(SHOULD NOT)는 것을 의미합니다. 대신 향후 PEP는 원래 PEP 691에서 명세된 표준 JSON 표현을 대상으로 해야 합니다(SHOULD).

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

근거와 동기

Python 패키지 색인에서 HTML 표현을 사용한 것은 Python 패키징을 표준화하려는 노력보다 먼저 시작되었습니다. 따라서 PEP 503으로 표준화된 HTML 표현은 설계라기보다는 기존 관행(특히 PyPI의 관행)의 형식화입니다.

Python 패키지 색인의 HTML 표현은 Python 패키징 생태계에 훌륭하게 기여해 왔습니다. HTML 표현은 모든 색인과 설치 프로그램이 지원하는 기준 표현 역할을 해 왔으며, 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 표현을 소비하는 방식은 흔히 취약합니다: 공백을 포함한 HTML의 정확한 구조에 대한 부적절한 가정 때문에, PyPI HTML 표현에 대한 문법적으로 유효하고 의미에 영향을 주지 않는 변경조차 파손을 일으키는 것으로 알려져 있습니다.
반면 JSON 표현의 소비는 견고한 JSON 파싱 라이브러리가 널리 보급되어 있는 덕분에 의미에 영향을 주지 않는 변경에 더 견고합니다. HTML을 견고하게 처리하는 것도 당연히 가능하지만, 소비자는 HTML 파싱이 복잡하고 범용적이라고 여겨 이를 피하고 정규 표현식이나 그와 유사한 임시방편적 파싱 기법을 사용하는 취약한 접근 방식을 택하고 싶은 유혹을 자주 받습니다.
실제로 HTML 표현의 점진적 개선이 채택되는 정도는 제한적입니다: PyPI 자체는 일반적으로 새 기능을 채택하지만, 서드파티 색인(특히 기업용 제품으로 판매되는 색인)은 원래 PEP 503에서 정의된 최소한의 표현만 제공하는 경우가 많습니다.
그 결과, HTML 표현이 개선되는 경우에도 많은 소비자는 그 개선의 혜택을 누리지 못합니다.

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

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

명세

단순 저장소 API의 HTML 표현은 Python 패키징 표준 절차의 목적상 동결됩니다. 향후 Python 패키징 PEP는 JSON 표현을 단순 저장소 API의 주된 형식으로 삼아야 합니다(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 표현을 더 간단하게 도입할 수 있는 방안이 필요할 가능성이 높습니다.
현재로서는 pip 같은 설치 프로그램이 HTML 표현을 점진적으로 파싱하기가 더 쉽습니다. Python 표준 라이브러리에 점진적 HTML 파싱을 위한 html.parser가 포함되어 있기 때문입니다. 이는 대규모 HTML 색인 응답, 예를 들어 수백 또는 수천 개의 배포물을 가진 패키지의 상세 응답에서 발생하는 메모리 오버헤드를 완화하는 데 도움이 됩니다.
반면에 Python 표준 라이브러리에는 현재 점진적 JSON 파서가 없습니다. 점진적 JSON 파싱이 비현실적인 것은 아니지만(그리고 점진적 HTML 파싱보다 확실히 덜 복잡하지만), 표준 라이브러리 차원의 해결책이 없다는 점이 도입 장벽이 됩니다. 향후 HTML 표현을 제거하려는 시도에는 pip 내에서 점진적 JSON 파싱을 위한 견고한 표준 라이브러리 해결책(또는 무리 없이 벤더링할 수 있는 서드파티 해결책)이 필요할 가능성이 높습니다.

보안 영향

이 PEP는 단순 저장소 API의 HTML 표현을 동결하는 것과 관련된 긍정적이거나 부정적인 보안 영향을 찾지 못했습니다.

교육 방법

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

그러나 색인 표현을 현대화하고자 하는 서드파티 색인을 위해, 이 PEP는 채택될 경우 다음을 제안합니다:

이 PEP의 작성자들은 적절한 공개 문서와 공지에 관해 PyPI 유지 관리자와 협의할 것이며, 필요하다고 판단되면 PyPI 블로그에 발표하는 것도 포함합니다.
이 PEP의 저자들은 단순 저장소 API의 living standard에 적절한 변경을 가할 것이며, 여기에는 HTML 표현이 향후 갱신을 받지 않는다는 점과 향후 갱신의 이점을 누리고자 하는 소비자는 대신 JSON 표현을 우선 사용해야 한다는 점을 알리는 경고문과 안내문을 적절한 곳에 추가하는 것이 포함됩니다.