Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python 개선 제안 한국어 번역

PEP 700 – 패키지 색인을 위한 단순 API의 추가 필드

Author:
Paul Moore <p.f.moore at gmail.com>
PEP-Delegate:
Donald Stufft <donald at stufft.io>
Discussions-To:
Discourse thread
Status:
Final
Type:
Standards Track
Topic:
Packaging
Created:
21-Oct-2022
Post-History:
21-Oct-2022
Resolution:
19-Dec-2022
Table of Contents

번역·라이선스 안내

이 비공식 한국어 번역은 원문 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 691은 “단순 저장소 API”의 JSON 형식을 정의했습니다. 이를 통해 클라이언트는 PEP 503에서 정의된, 이전에는 HTML에서만 사용할 수 있었던 데이터를 더 쉽게 조회할 수 있게 되었습니다.

이 제안은 JSON 형식에 세 개의 필드를 추가하며, 이를 여러 상황에서 PyPI의 JSON API를 대신하여 사용할 수 있게 합니다.

  • 프로젝트의 게시된 모든 버전 목록을 검색할 수 있도록 하는 필드입니다.
  • 프로젝트 파일의 크기와 업로드 시간을 포함하는 필드입니다.

새로운 필드는 모두 “프로젝트 세부 정보” URL에서 반환되는 데이터의 일부입니다.

근거

단순 API의 JSON 형식이 PEP 691에서 도입됨에 따라, 단순 API는 PyPI JSON API만큼 거의 완전한 기능을 제공합니다. 이 PEP는 이전에 JSON API를 통해서만 사용할 수 있었던 여러 필드를 추가하여, 이전에 Warehouse에 특화되어 있던 더 많은 클라이언트가 임의의 표준 준수 색인을 지원할 수 있도록 합니다.

사양

이 사양은 단순 저장소 API의 버전 1.1을 정의합니다. API의 HTML 버전은 버전 1.0과 변경 사항이 없습니다. API의 JSON 버전에는 다음과 같은 변경 사항이 적용됩니다.

  • api-version은 버전 1.1 이상을 지정해야 합니다.
  • 최상위 수준에 새로운 versions 키가 추가됩니다.
  • 두 개의 새로운 “파일 정보” 키인 size 및 upload-time이 files 데이터에 추가됩니다.
  • 앞에 밑줄이 있는 키는 모든 수준에서 색인 서버의 비공개 용도로 예약됩니다. 향후 표준은 이러한 키에 어떠한 의미도 할당하지 않습니다.

versions 및 size 키는 필수입니다. upload-time 키는 선택 사항입니다.

버전

최상위 수준에는 PEP 691에서 정의한 키 name, files 및 meta에 더하여 추가 키 versions가 반드시 존재해야 합니다. 이 키에는 이 프로젝트에 업로드된 모든 프로젝트 버전을 지정하는 버전 문자열 목록이 반드시 포함되어야 합니다. 값은 논리적으로 집합이므로 중복을 포함할 수 없으며, 값의 순서는 중요하지 않습니다.

files 키에 나열된 모든 파일은 versions키의 버전 중 하나와 반드시 연결되어야 합니다. versions키에는 연결된 파일이 없는 버전이 포함될 수도 있습니다(서버에 이러한 개념이 있는 경우 파일이 업로드되지 않은 버전을 나타내기 위한 것입니다).

서버에는 PEP 440 채택 이전의 “레거시” 데이터가 저장되어 있을 수 있으므로, 현재 버전 문자열이 유효한 PEP 440 버전이어야 한다고 요구할 수 없으며, 따라서 PEP 440 규칙을 사용하여 순서를 정할 수 있다고 가정할 수도 없습니다. 그러나 서버는 가능한 경우 정규화된 PEP 440 버전을 사용해야 합니다.

추가 파일 정보

files 키에 두 개의 새로운 키가 추가됩니다.

  • size: 이 필드는 필수입니다. 파일 크기(바이트)를 나타내는 정수를 반드시 포함해야 합니다.
  • upload-time: 이 필드는 선택 사항입니다. 존재하는 경우, yyyy-mm-ddThh:mm:ss.ffffffZ 형식의 유효한 ISO 8601 날짜/시간 문자열을 반드시 포함해야 하며, 이는 파일이 인덱스에 업로드된 시간을 나타냅니다. Z 접미사가 나타내듯이, 업로드 시간은 반드시 UTC 시간대를 사용해야 합니다. 타임스탬프의 소수 초 부분(.ffffff 부분)은 선택 사항이며, 존재하는 경우 최대 6자리의 정밀도를 포함할 수 있습니다. 서버가 파일의 업로드 시간 정보를 기록하지 않는 경우 upload-time 키를 생략할 수 있습니다.

FAQ

이 데이터를 HTML API에도 추가하지 않는 이유는 무엇입니까?

HTML API에 이 데이터를 추가하는 것은 가능하지만, 이 데이터의 소비자 대다수는 현재 PyPI JSON API에서 데이터를 가져오고 있을 가능성이 높으므로 이미 JSON을 구문 분석할 것으로 예상됩니다. 기존의 HTML API 소비자에게는 이전에 이 데이터가 필요했던 적이 없습니다.

이는 HTML API가 더 이상 사용되지 않는다는 의미입니까?

아닙니다. PEP 691의 FAQ에서는 HTML API가 폐기되지 않는다는 점을 분명히 밝혔으며, 이 PEP는 그 입장을 변경하지 않습니다. 그러나 이 PEP가 도입한 새로운 데이터에 액세스하려는 클라이언트는 데이터를 가져오기 위해 JSON API를 사용해야 합니다. 또한 이를 제공하려는 인덱스는 JSON 형식을 제공해야 합니다.

간단한 API가 Warehouse JSON 및 XML-RPC API를 대체합니까?

가능한 경우 클라이언트는 JSON 또는 XML-RPC API보다 간단한 API를 우선 사용해야 합니다. 전자는 표준화되어 있고 모든 인덱스에서 사용할 수 있다고 가정할 수 있지만, 후자는 Warehouse 프로젝트 전용이기 때문입니다.

그러나 이 PEP가 간단한 API를 JSON API로 대체할 수 있는 단계에 더 가깝게 만들기는 하지만, 간단한 API가 기존 Warehouse API가 제공하는 모든 기능을 재현한다는 공식 정책은 없습니다. 간단한 API에 제안된 추가 사항은 여전히 각 사항의 장점에 따라 검토되며, 프로젝트의 파일을 찾는 주된 사용 사례에서 API가 간단하고 빨라야 한다는 요구 사항이 최우선 고려 사항으로 유지됩니다.

다른 날짜 형식을 허용하지 않는 이유는 무엇입니까?

ISO 8601 표준은 복잡하며, 클라이언트가 이를 처리하도록 요구하는 것은 별로 가치가 없어 보입니다. 표준 라이브러리의 datetime 모듈은 ISO 8601 문자열을 구문 분석하는 메서드를 제공하지만, 사용자가 Python을 사용하지 않고 인덱스 데이터에 액세스하려 할 수도 있습니다(예를 들어 curl의 출력을 jq로 파이프하는 경우). 하나의 잘 정의된 형식을 사용하면 이를 쉽게 처리할 수 있으며, 중대한 단점도 없습니다.

파일 크기가 JSON 숫자에 비해 너무 크면 어떻게 됩니까?

JSON 표준은 숫자를 어떻게 해석해야 하는지 지정하지 않습니다. Python은 JSON 파일에서 임의의 길이를 가진 정수를 읽고 쓸 수 있으므로 Python으로 작성된 코드에서는 문제가 되지 않습니다. Python이 아닌 구현에서는 큰 정수를 올바르게 처리하도록 주의해야 할 수 있지만, 이는 중대한 문제가 될 것으로 예상되지 않습니다.

PEP 440 버전을 요구하지 않는 이유는 무엇입니까?

이 PEP가 작성될 당시 PyPI에는 여전히 “레거시” 버전의 프로젝트와 파일이 포함되어 있었으며 이를 제공하고 있었습니다. 관련 PEP 440 버전을 요구하면 PyPI가 기존 콘텐츠를 계속 제공하면서 이 명세를 따르는 것이 불가능해집니다.

이상적으로는 향후 어느 시점에 간단한 인덱스 API가 PEP 440버전을 요구하도록 업데이트되어야 하며, 그때 이 사양도 이를 반영하도록 업데이트되어야 합니다. 그러나 해당 변경 사항은 PyPI를 포함한 기존 인덱스 제공자들과 조율되어야 하며, 이를 위해 규격을 준수하지 않는 프로젝트 및/또는 파일의 지원을 중단하고 제거해야 합니다.

“최신 버전” 값을 제공하지 않는 이유는 무엇입니까?

관련 PEP 440 버전의 경우, 클라이언트가 이를 수행하기는 충분히 쉽습니다(packaging 라이브러리와 latest = max(Version(s) for s in proj["versions"]) 사용). 비표준 버전의 경우에는 명확하게 정의된 순서가 없으므로, 클라이언트는 자신의 필요에 적합한 규칙을 결정해야 합니다. 서버에 최신 버전 값을 제공하도록 요구하면 클라이언트의 선택권을 빼앗게 됩니다.

클라이언트가 이용할 수 있는 데이터로 계산할 수 없는 “최신” 버전에 대한 명시적인 개념을 가진 서버는 원하는 경우 해당 정보를 클라이언트에 전달하기 위해 비표준 밑줄 접두사 키를 제공할 수 있습니다.