PEP 629 – PyPI Simple API의 버전 관리

Author:: Donald Stufft <donald at stufft.io>
BDFL-Delegate:: Brett Cannon <brett at python.org>
Discussions-To:: Discourse thread
Status:: Final
Type:: Standards Track
Topic:: Packaging
Created:: 16-Jul-2020
Post-History:: 16-Jul-2020

Table of Contents

초록
근거
개요
- 클라이언트
기각된 아이디어
- 헤더 사용
- URL 사용
Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

Note

이 PEP는 2020-08-20에 승인되었습니다. PyPI는 2020-01-28에 구현을 병합했으며, 이에 따라 이 PEP는 “Final”로 표시되었습니다.

초록

이 PEP는 특정 저장소가 simple API의 어떤 기능을 지원하는지 클라이언트가 판단할 수 있도록 simple API의 버전 관리 방법을 추가할 것을 제안합니다.

근거

Simple API가 발전해 나가면 클라이언트는 저장소가 어떤 기능을 지원하는지 판별할 수 있기를 원합니다. 현재는 이를 확인할 방법이 없습니다. 응답 데이터를 살펴보고 특정 기능이 사용되고 있는 것처럼 보이는지 확인하여 새 기능을 감지하려고 시도하는 방법뿐입니다.

이 방식은 최신 버전의 클라이언트가 자신이 구현하려는 기능을 저장소가 모두 지원하는지 판별하는 데에는 꽤 잘 동작합니다. 그러나 오래된 버전의 클라이언트에게 그 클라이언트가 이해하지 못할 수도 있는 기능을 저장소가 지원한다는 사실을 알려 주지는 못합니다. 또한 클라이언트가 저장소의 출력을 올바르게 이해하지 못하고 있을 수 있다는 메시지를 표시할 수도 없습니다.

실제로 이런 일이 있었던 예로 python-requires 메타데이터를 단계적으로 도입했던 경우를 들 수 있습니다. 기존 클라이언트는 여전히 저장소를 문제없이 사용할 수 있었지만, 이 새로운 데이터를 이해하지 못했습니다. 이 데이터를 이해했다면 최종 사용자를 위해 더 적합한 파일을 선택하도록 동작을 결정할 수 있었을 것입니다.

개요

이 PEP는 simple API 페이지에 대한 모든 성공적인 요청의 응답에 meta 태그를 포함할 것을 제안합니다. 이 태그는 값이 “pypi:repository-version”(저장소 버전)인 name 속성과 PEP 440과 호환되는 버전 번호인 content를 가집니다. 이 버전 번호는 반드시 Major.Minor 형식이어야 하며, PEP 440이 지원하는 추가 기능은 전혀 사용할 수 없습니다.

최종적으로는 다음과 같은 모습이 됩니다.:

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

저장소 버전은 다음과 같이 해석합니다.

메이저 버전을 올리는 것은 하위 호환성이 없는 변경을 나타냅니다. 즉, 기존 클라이언트가 더 이상 API를 의미 있게 사용할 수 없을 것으로 예상되는 변경입니다.
마이너 버전을 올리는 것은 하위 호환성이 있는 변경을 나타냅니다. 즉, 기존 클라이언트가 여전히 API를 의미 있게 사용할 수 있을 것으로 예상되는 변경입니다.

이 PEP는 기존 클라이언트가 API를 “의미 있게” 계속 사용할 수 있어야 한다는 대략적인 기준만 제시합니다. 구체적으로 무엇이 하위 호환성이 없는 변경이고 무엇이 하위 호환성이 있는 변경인지는 향후 PEP의 재량에 맡기며, 여기에는 기능의 추가와 기존 기능의 수정 및 제거가 포함될 수 있습니다.

이 PEP는 메이저 버전이 올라가는 일은 결코 없을 것이며, 향후 API를 크게 발전시킬 때에는 API 발전을 위한 다른 메커니즘을 사용할 것으로 예상합니다. 그러나 메이저 버전은 향후 버전과의 모호함을 없애기 위해 포함됩니다(예를 들어, /v2/에 위치하는 가상의 simple api v2가 있을 때 저장소 버전(repository-version)이 2 이상으로 설정되어 있다면 혼란스러울 것입니다).

이 PEP는 현재 API 버전을 “1.0”으로 정하며, 앞으로 Simple API를 더 발전시키는 PEP는 마이너 버전 번호를 올릴 것으로 예상합니다.

클라이언트

Simple API를 사용하는 클라이언트는 각 응답에서 저장소 버전을 확인해야 하며(SHOULD), 해당 데이터가 없으면 반드시 버전 1.0으로 간주해야 합니다(MUST).

예상보다 높은 메이저 버전을 만나면 클라이언트는 반드시 사용자에게 적절한 오류 메시지를 표시하고 즉시 실패해야 합니다(MUST).

예상보다 높은 마이너 버전을 만나면 클라이언트는 사용자에게 적절한 메시지로 경고해야 합니다(SHOULD).

클라이언트는 저장소가 어떤 기능을 사용하는지 판단하기 위해 기능 감지를 계속 사용할 수도 있습니다(MAY).