PEP 700 – 패키지 색인용 Simple 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
번역·라이선스 안내
이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판
초록
PEP 691은 “Simple Repository API”(단순 저장소 API)의 JSON 형식을 정의했습니다. 이를 통해 클라이언트는 PEP 503에 정의된 대로 이전에는 HTML로만 제공되던 데이터를 더 쉽게 조회할 수 있게 되었습니다.
이 제안은 JSON 형식에 세 가지 필드를 추가하여, 여러 상황에서 PyPI의 JSON API 대신 JSON 형식을 사용할 수 있도록 합니다.
- 프로젝트에 게시된 모든 버전의 목록을 조회할 수 있게 하는 필드입니다.
- 프로젝트 파일의 크기와 업로드 시각을 담는 필드입니다.
새 필드는 모두 “프로젝트 상세” URL에서 반환되는 데이터의 일부입니다.
근거
PEP 691에서 Simple API의 JSON 형식이 도입되면서, Simple 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가 최상위 수준에 반드시(MUST) 존재해야 합니다. 이 키는 이 프로젝트에 업로드된 모든 프로젝트 버전을 지정하는 버전 문자열 목록을 반드시(MUST) 포함해야 합니다. 이 값은 논리적으로 집합이므로 중복을 포함할 수 없으며, 값의 순서는 의미가 없습니다.
files 키에 나열된 모든 파일은 versions 키에 있는 버전 중 하나와 반드시(MUST) 연관되어야 합니다. versions 키는 연관된 파일이 없는 버전을 포함할 수 있습니다(MAY)(서버에 그러한 개념이 있는 경우, 업로드된 파일이 없는 버전을 나타내기 위함입니다).
서버가 PEP 440 채택 이전의 “레거시” 데이터를 보유하고 있을 수 있으므로, 현재로서는 버전 문자열이 유효한 PEP 440 버전이어야 한다고 요구할 수 없으며, 따라서 PEP 440 규칙을 사용해 정렬할 수 있다고 가정할 수도 없다는 점에 유의하십시오. 그러나 서버는 가능한 경우 정규화된 PEP 440 버전을 사용해야 합니다(SHOULD).
추가 파일 정보
files 키에 두 개의 새로운 키가 추가됩니다.
size: 이 필드는 필수입니다. 이 필드에는 파일 크기를 바이트 단위로 나타낸 정수가 반드시 들어 있어야 합니다(MUST).upload-time: 이 필드는 선택 사항입니다. 이 필드가 있다면 파일이 색인에 업로드된 시각을 나타내는yyyy-mm-ddThh:mm:ss.ffffffZ형식의 유효한 ISO 8601 날짜/시간 문자열이 반드시 들어 있어야 합니다(MUST).Z접미사가 나타내듯이 업로드 시각은 반드시 UTC 시간대를 사용해야 합니다(MUST). 타임스탬프에서 소수점 이하 초 부분(.ffffff부분)은 선택 사항이며, 이 부분이 있다면 최대 6자리의 정밀도를 가질 수 있습니다. 서버가 파일의 업로드 시각 정보를 기록하지 않는다면upload-time키를 생략할 수 있습니다(MAY).
FAQ
이 데이터를 HTML API에도 추가하지 않는 이유는 무엇입니까?
이 데이터를 HTML API에 추가할 수도 있지만, 이 데이터를 사용하는 소비자 대다수는 현재 PyPI JSON API에서 데이터를 가져오고 있을 가능성이 높으므로 이미 JSON을 파싱할 준비가 되어 있을 것입니다. HTML API의 기존 소비자들은 지금까지 이 데이터가 필요한 적이 없었습니다.
이는 HTML API가 더 이상 쓸모없다는 뜻입니까?
아닙니다. PEP 691의 FAQ는 HTML API가 폐기 예정이 아니라는 점을 분명히 밝혔으며, 이 PEP도 그 입장을 바꾸지 않습니다. 다만 이 PEP에서 도입한 새 데이터에 접근하려는 클라이언트는 이 데이터를 얻기 위해 JSON API를 사용해야 합니다. 또한 이 데이터를 제공하려는 색인은 JSON 형식을 제공해야 합니다.
simple API가 Warehouse의 JSON API와 XML-RPC API를 대체합니까?
가능하다면 클라이언트는 JSON API나 XML-RPC API보다 simple API를 우선 사용해야 합니다. simple API는 표준화되어 있어 어느 색인에서나 제공된다고 가정할 수 있지만, JSON API와 XML-RPC API는 Warehouse 프로젝트에서만 제공되기 때문입니다.
그러나 이 PEP로 simple API가 JSON API를 대체하는 데 한 걸음 더 가까워지기는 했지만, simple API가 기존 Warehouse API의 기능을 모두 갖추게 된다는 공식 정책은 없습니다. simple API에 대한 추가 제안은 여전히 각각의 장점에 따라 검토될 것이며, 프로젝트의 파일을 찾는다는 주된 사용 사례에 대해 API가 단순하고 빨라야 한다는 요구 사항이 계속해서 가장 우선적인 고려 사항으로 남을 것입니다.
다른 날짜 형식을 허용하지 않는 이유는 무엇입니까?
ISO 8601 표준은 복잡하며, 클라이언트가 이 복잡성을 처리하도록 요구해서 얻을 이점이 거의 없어 보입니다. 표준 라이브러리의 datetime 모듈은 ISO 8601 문자열을 파싱하는 메서드를 제공하지만, 사용자가 Python을 사용하지 않고 색인 데이터에 접근하려 할 수도 있습니다(예를 들어 curl의 출력을 jq로 파이프하는 경우). 잘 정의된 단일 형식을 사용하면 이런 작업이 더 쉬워지며, 이렇다 할 단점도 없습니다.
파일 크기가 JSON 숫자로 표현하기에 너무 크면 어떻게 됩니까?
JSON 표준은 숫자를 어떻게 해석해야 하는지 규정하지 않습니다. Python은 JSON 파일에서 임의 길이의 정수를 읽고 쓸 수 있으므로, Python으로 작성한 코드에서는 이 점이 문제가 되지 않을 것입니다. Python이 아닌 Python 구현에서는 큰 정수를 올바르게 처리하도록 주의해야 할 수도 있지만, 이것이 심각한 문제가 될 것으로 예상하지는 않습니다.
PEP 440 버전을 요구하지 않는 이유는 무엇입니까?
이 PEP를 작성할 당시 PyPI에는 여전히 “레거시” 버전을 가진 프로젝트와 파일이 있었으며, PyPI는 이를 계속 제공하고 있었습니다. PEP 440 버전을 요구하면 PyPI가 기존 콘텐츠를 계속 제공하면서 이 명세를 따르는 것이 불가능해집니다.
이상적으로는 언젠가 simple 색인 API가 PEP 440 버전을 요구하도록 개정될 것이며, 그때 이 명세도 그에 맞게 개정해야 합니다. 다만 그런 변경을 하려면 PyPI를 비롯한 기존 색인 제공자들과 협의하여, 규격에 맞지 않는 프로젝트나 파일의 지원을 중단하고 이를 제거해야 합니다.
“최신 버전” 값을 제공하지 않는 이유는 무엇입니까?
PEP 440 버전의 경우 클라이언트가 직접 하기에 충분히 쉽습니다(packaging 라이브러리를 사용하여 latest = max(Version(s) for s in proj["versions"])). 비표준 버전에는 명확하게 정의된 순서가 없으므로, 클라이언트는 자신의 필요에 맞는 규칙을 스스로 결정해야 합니다. 서버에 최신 버전 값을 제공하도록 요구하면 클라이언트의 선택권을 빼앗게 됩니다.
어떤 버전이 “최신”인지에 대한 명시적인 개념이 있고 그것을 클라이언트가 이용할 수 있는 데이터로는 계산할 수 없는 서버는, 원한다면 그 정보를 클라이언트에 전달하기 위해 밑줄로 시작하는 비표준 키를 제공할 수 있습니다.
Copyright
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.