[Final] PEP 700 - Additional Fields for the Simple API for Package Indexes
원문 링크: PEP 700 - Additional Fields for the Simple API for Package Indexes
상태: Final 유형: Standards Track 작성일: 21-Oct-2022
PEP 700: Simple Package Index를 위한 추가 필드
개요
PEP 700은 Python Package Index (PyPI)와 같은 Simple Repository API의 JSON 형식에 세 가지 필드를 추가하는 제안입니다. 이 제안은 PyPI의 기존 JSON API를 대체하여 클라이언트가 표준을 준수하는 인덱스를 더 쉽게 활용할 수 있도록 돕는 것을 목표로 합니다.
주요 추가 필드는 다음과 같습니다:
- 프로젝트의 모든 게시된 버전을 가져올 수 있는 필드
- 프로젝트 파일의 크기(size) 및 업로드 시간(upload-time)을 포함하는 필드
이 새로운 필드들은 “프로젝트 세부 정보(project details)” URL에서 반환되는 데이터의 일부입니다.
도입 배경 (Rationale)
PEP 691에서 Simple API의 JSON 형식이 도입되면서, Simple API는 PyPI JSON API와 거의 동등한 기능을 제공하게 되었습니다. PEP 700은 이전에 JSON API를 통해서만 접근 가능했던 몇 가지 필드를 추가하여, PyPI 특정 클라이언트들이 임의의 표준 준수 인덱스를 지원할 수 있도록 합니다.
명세 (Specification)
이 명세는 Simple Repository API의 버전 1.1을 정의합니다. HTML API의 경우 버전 1.0과 변경 사항이 없지만, JSON API에는 다음과 같은 변경 사항이 적용됩니다:
api-version은 1.1 이상을 지정해야 합니다.- 최상위(top level)에 새로운
versions키가 추가됩니다. files데이터에size및upload-time이라는 두 개의 새로운 “파일 정보” 키가 추가됩니다.- 선행 밑줄(leading underscore)이 있는 키(모든 레벨에서)는 인덱스 서버 사용을 위한 비공개(private)로 예약됩니다. 향후 어떤 표준도 이러한 키에 의미를 부여하지 않을 것입니다.
versions 및 size 키는 필수(mandatory)입니다. upload-time 키는 선택 사항(optional)입니다.
버전 (Versions)
PEP 691에 정의된 name, files, meta 키 외에도 최상위에 versions라는 추가 키가 반드시 존재해야 합니다. 이 키는 해당 프로젝트에 업로드된 모든 프로젝트 버전을 지정하는 버전 문자열(string) 목록을 포함해야 합니다. 이 값은 논리적으로 집합(set)이므로 중복을 포함할 수 없으며, 값의 순서는 중요하지 않습니다.
files 키에 나열된 모든 파일은 versions 키의 버전 중 하나와 연결되어야 합니다. versions 키는 연결된 파일이 없는 버전(서버에 파일이 업로드되지 않은 버전의 개념이 있는 경우)을 포함할 수 있습니다.
서버는 PEP 440 도입 이전의 “레거시(legacy)” 데이터를 보유할 수 있으므로, 버전 문자열은 현재 PEP 440 버전을 요구할 수 없으며, 따라서 PEP 440 규칙을 사용하여 정렬할 수 있다고 가정할 수 없습니다. 그러나 서버는 가능한 경우 정규화된 PEP 440 버전을 사용해야 합니다.
추가 파일 정보 (Additional file information)
files 키에 두 개의 새로운 키가 추가됩니다.
size: 이 필드는 필수입니다. 바이트(bytes) 단위의 파일 크기를 나타내는 정수(integer)를 포함해야 합니다.upload-time: 이 필드는 선택 사항입니다. 존재하는 경우, 파일이 인덱스에 업로드된 시간을 나타내는yyyy-mm-ddThh:mm:ss.ffffffZ형식의 유효한 ISO 8601 날짜/시간 문자열을 포함해야 합니다.Z접미사가 나타내듯이, 업로드 시간은 UTC 시간대(timezone)를 사용해야 합니다. 타임스탬프의 초 단위 소수 부분(.ffffff부분)은 선택 사항이며, 존재하는 경우 최대 6자리의 정밀도를 포함할 수 있습니다. 서버가 파일의 업로드 시간 정보를 기록하지 않는 경우,upload-time키를 생략할 수 있습니다.
FAQ
이 데이터를 HTML API에도 추가하지 않는 이유는 무엇인가요?
이 데이터의 대부분의 소비자는 현재 PyPI JSON API에서 이 데이터를 가져올 가능성이 높으므로 이미 JSON을 파싱할 것으로 예상됩니다. HTML API의 기존 소비자는 이전에 이 데이터를 필요로 하지 않았습니다.
이것이 HTML API가 더 이상 사용되지 않는다는 것을 의미하나요?
아닙니다. PEP 691의 FAQ는 HTML API가 더 이상 사용되지 않음을 명확히 했으며, 이 PEP는 해당 입장을 변경하지 않습니다. 그러나 이 PEP에서 도입된 새로운 데이터에 접근하려는 클라이언트는 JSON API를 사용해야 합니다.
Simple API가 Warehouse JSON 및 XML-RPC API를 대체하나요?
가능한 경우 클라이언트는 JSON 또는 XML-RPC API보다 Simple API를 선호해야 합니다. Simple 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 구현은 큰 정수를 올바르게 처리하는 데 주의를 기울여야 할 수 있지만, 이는 큰 문제가 될 것으로 예상되지 않습니다.
PEP 440 버전을 요구하지 않는 이유는 무엇인가요?
이 PEP가 작성될 당시 PyPI는 여전히 “레거시” 버전의 프로젝트와 파일을 포함하고 제공했습니다. PEP 440 버전을 요구하면 PyPI가 기존 콘텐츠를 제공하면서 이 명세를 따르는 것이 불가능해질 것입니다.
이상적으로는 미래의 어느 시점에 Simple Index API가 PEP 440 버전을 요구하도록 업데이트될 것이며, 그때 이 명세도 이를 반영하도록 업데이트되어야 합니다. 그러나 이러한 변경은 PyPI를 포함한 기존 인덱스 제공업체와 비준수 프로젝트 및/또는 파일을 지원 중단하고 제거하기 위해 조정되어야 합니다.
“최신 버전(latest version)” 값을 제공하지 않는 이유는 무엇인가요?
PEP 440 버전의 경우, 클라이언트가 직접 계산하기 쉽습니다 (packaging 라이브러리를 사용하여 latest = max(Version(s) for s in proj["versions"])). 비표준 버전의 경우, 잘 정의된 순서가 없으므로 클라이언트가 자신의 필요에 맞는 규칙을 결정해야 합니다. 서버가 최신 버전 값을 제공하도록 요구하면 클라이언트의 선택권을 제한하게 됩니다.
클라이언트가 사용할 수 있는 데이터로부터 계산할 수 없는 “최신” 버전의 명시적인 개념을 가진 서버는 원하는 경우 해당 정보를 클라이언트에 전달하기 위해 비표준의 밑줄 접두사 키를 제공할 수 있습니다.# PEP 700: Simple Package Index를 위한 추가 필드
개요
PEP 700은 Python Package Index (PyPI)와 같은 Simple Repository API의 JSON 형식에 세 가지 필드를 추가하는 제안입니다. 이 제안은 PEP 691에서 정의된 “Simple Repository API”의 JSON 형식을 확장하여, 클라이언트가 이전에 HTML로만 제공되었던 데이터를 더 쉽게 쿼리할 수 있도록 합니다. 궁극적으로, PyPI의 JSON API를 대체하여 클라이언트가 표준을 준수하는 다양한 인덱스를 활용할 수 있도록 돕는 것을 목표로 합니다.
주요 추가 필드는 다음과 같습니다:
- 프로젝트의 모든 게시된 버전을 검색할 수 있는 필드
- 프로젝트 파일의 크기(
size) 및 업로드 시간(upload-time)을 포함하는 필드
이 새로운 필드들은 “프로젝트 세부 정보(project details)” URL에서 반환되는 데이터의 일부입니다.
도입 배경 (Rationale)
PEP 691을 통해 Simple API의 JSON 형식이 도입되면서, Simple API는 PyPI JSON API와 거의 동등한 기능을 제공하게 되었습니다. PEP 700은 이전에 PyPI JSON API를 통해서만 접근 가능했던 몇 가지 필드를 추가하여, 기존에 Warehouse 특정 클라이언트들이 임의의 표준 준수 인덱스를 지원할 수 있도록 합니다.
명세 (Specification)
이 명세는 Simple Repository API의 버전 1.1을 정의합니다. HTML 버전의 API에는 버전 1.0과 비교하여 변경 사항이 없지만, JSON 버전의 API에는 다음 변경 사항이 적용됩니다:
api-version은 1.1 이상을 지정해야 합니다.- 최상위(top level)에 새로운
versions키가 추가됩니다. files데이터에size및upload-time이라는 두 개의 새로운 “파일 정보” 키가 추가됩니다.- 선행 밑줄(예:
_private_key)이 있는 키(모든 레벨에서)는 인덱스 서버 사용을 위한 비공개(private)로 예약됩니다. 향후 어떤 표준도 이러한 키에 의미를 부여하지 않을 것입니다.
versions 및 size 키는 필수(mandatory)입니다. upload-time 키는 선택 사항(optional)입니다.
버전 (Versions)
PEP 691에 정의된 name, files, meta 키 외에도, 최상위에 versions라는 추가 키가 반드시 존재해야 합니다. 이 키는 해당 프로젝트에 업로드된 모든 프로젝트 버전을 지정하는 버전 문자열(string) 목록을 포함해야 합니다. 이 값은 논리적으로 집합(set)이므로 중복을 포함할 수 없으며, 값의 순서는 중요하지 않습니다.
files 키에 나열된 모든 파일은 versions 키의 버전 중 하나와 연결되어야 합니다. versions 키는 연결된 파일이 없는 버전(예: 서버에 파일이 업로드되지 않은 버전의 개념이 있는 경우)을 포함할 수 있습니다.
서버는 PEP 440 도입 이전의 “레거시(legacy)” 데이터를 보유할 수 있으므로, 버전 문자열은 현재 PEP 440 버전을 요구할 수 없으며, 따라서 PEP 440 규칙을 사용하여 정렬할 수 있다고 가정할 수 없습니다. 그러나 서버는 가능한 경우 정규화된 PEP 440 버전을 사용해야 합니다.
추가 파일 정보 (Additional file information)
files 키에 두 개의 새로운 키가 추가됩니다.
size: 이 필드는 필수입니다. 바이트(bytes) 단위의 파일 크기를 나타내는 정수(integer)를 포함해야 합니다.upload-time: 이 필드는 선택 사항입니다. 존재하는 경우, 파일이 인덱스에 업로드된 시간을 나타내는yyyy-mm-ddThh:mm:ss.ffffffZ형식의 유효한 ISO 8601 날짜/시간 문자열을 포함해야 합니다.Z접미사가 나타내듯이, 업로드 시간은 UTC 시간대(timezone)를 사용해야 합니다. 타임스탬프의 초 단위 소수 부분(.ffffff부분)은 선택 사항이며, 존재하는 경우 최대 6자리의 정밀도를 포함할 수 있습니다. 서버가 파일의 업로드 시간 정보를 기록하지 않는 경우,upload-time키를 생략할 수 있습니다.
FAQ
이 데이터를 HTML API에도 추가하지 않는 이유는 무엇인가요?
이 데이터의 대부분의 소비자는 현재 PyPI JSON API에서 데이터를 가져올 가능성이 높으므로 이미 JSON을 파싱(parsing)할 것으로 예상됩니다. HTML API의 기존 소비자는 이전에 이 데이터를 필요로 하지 않았습니다.
이것이 HTML API가 더 이상 사용되지 않는다는 것을 의미하나요?
아닙니다. PEP 691의 FAQ는 HTML API가 더 이상 사용되지 않음을 명확히 했으며, 이 PEP는 해당 입장을 변경하지 않습니다. 그러나 이 PEP에서 도입된 새로운 데이터에 접근하려는 클라이언트는 JSON API를 사용해야 합니다. 또한, 인덱스 제공자가 이 데이터를 제공하려면 JSON 형식을 제공해야 합니다.
Simple API가 Warehouse JSON 및 XML-RPC API를 대체하나요?
가능한 경우 클라이언트는 JSON 또는 XML-RPC API보다 Simple API를 선호해야 합니다. Simple API는 표준화되어 모든 인덱스에서 사용할 수 있다고 가정할 수 있지만, 후자는 Warehouse 프로젝트에만 해당되기 때문입니다.
이 PEP는 Simple API가 JSON API를 대체할 수 있도록 더 가깝게 만들지만, Simple API가 기존 Warehouse API가 다루는 모든 기능을 복제할 것이라는 공식적인 정책은 없습니다. Simple API에 대한 제안된 추가 사항은 여전히 개별적인 장점에 따라 고려될 것이며, 프로젝트의 파일을 찾는 주요 사용 사례에 대해 API가 간단하고 빨라야 한다는 요구 사항은 가장 중요한 고려 사항으로 남을 것입니다.
다른 날짜 형식을 허용하지 않는 이유는 무엇인가요?
ISO 8601 표준은 복잡하며, 클라이언트가 이를 처리하도록 요구하는 것은 가치가 적은 것으로 보입니다. Python 표준 라이브러리의 datetime 모듈은 ISO 8601 문자열을 파싱하는 메서드를 제공하지만, 사용자가 Python을 사용하지 않고 인덱스 데이터에 접근하기를 원할 수도 있습니다 (예: curl의 출력을 jq로 파이프하는 경우). 단일하고 잘 정의된 형식을 갖는 것이 이를 더 쉽게 만들고, 중요한 단점은 없습니다.
파일 크기가 JSON 숫자에 너무 큰 경우는 어떻게 처리하나요?
JSON 표준은 숫자를 해석하는 방법을 지정하지 않습니다. Python은 JSON 파일에서 임의 길이의 정수를 읽고 쓸 수 있으므로, Python으로 작성된 코드에는 문제가 되지 않습니다. 비-Python 구현은 큰 정수를 올바르게 처리하는 데 주의를 기울여야 할 수 있지만, 이는 큰 문제가 될 것으로 예상되지 않습니다.
PEP 440 버전을 요구하지 않는 이유는 무엇인가요?
이 PEP가 작성될 당시 PyPI는 여전히 “레거시(legacy)” 버전의 프로젝트와 파일을 포함하고 제공했습니다. PEP 440 버전을 요구하면 PyPI가 기존 콘텐츠를 제공하면서 이 명세를 따르는 것이 불가능해질 것입니다.
이상적으로는 미래의 어느 시점에 Simple Index API가 PEP 440 버전을 요구하도록 업데이트될 것이며, 그때 이 명세도 이를 반영하도록 업데이트되어야 합니다. 그러나 이러한 변경은 PyPI를 포함한 기존 인덱스 제공업체와 비준수 프로젝트 및/또는 파일을 지원 중단하고 제거하기 위해 조정되어야 합니다.
“최신 버전(latest version)” 값을 제공하지 않는 이유는 무엇인가요?
PEP 440 버전의 경우, 클라이언트가 직접 계산하기 쉽습니다 (예: packaging 라이브러리를 사용하여 latest = max(Version(s) for s in proj["versions"])). 비표준 버전의 경우, 잘 정의된 순서가 없으므로 클라이언트가 자신의 필요에 맞는 규칙을 결정해야 합니다. 서버가 최신 버전 값을 제공하도록 요구하면 클라이언트의 선택권을 제한하게 됩니다.
클라이언트가 사용할 수 있는 데이터로부터 계산할 수 없는 “최신” 버전의 명시적인 개념을 가진 서버는 원하는 경우 해당 정보를 클라이언트에 전달하기 위해 비표준의 밑줄 접두사 키를 제공할 수 있습니다.
⚠️ 알림: 이 문서는 AI를 활용하여 번역되었으며, 기술적 정확성을 보장하지 않습니다. 정확한 내용은 반드시 원문을 확인하시기 바랍니다.
Comments