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에 accepted on 2020-08-20되었습니다. PyPI는 merged an implementation을 2020-01-28에 병합하여 이 PEP를 “Final”로 표시했습니다.

초록

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

근거

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

이 방법은 최신 버전의 클라이언트가 저장소가 구현하려는 모든 기능을 지원하는지 판별하는 데는 상당히 잘 작동하지만, 저장소가 이전 버전의 클라이언트가 이해하지 못할 수도 있는 기능을 지원한다는 사실을 이전 버전의 클라이언트에 알리거나, 해당 클라이언트가 저장소의 출력을 올바르게 이해하지 못할 수 있음을 나타내는 메시지를 제공하는 데는 아무런 도움이 되지 않습니다.

이러한 일이 발생한 상황의 한 예로 python-requires 메타데이터의 단계적 도입을 들 수 있습니다. 기존 클라이언트는 여전히 저장소를 성공적으로 사용할 수 있었지만, 최종 사용자를 위해 더 나은 파일을 선택하도록 동작을 결정하는 데 도움이 되었을 이 새로운 데이터 조각을 이해할 수 없었습니다.

개요

이 PEP는 Simple API 페이지에 대한 모든 성공적인 요청의 응답에 메타 태그를 포함할 것을 제안합니다. 이 태그에는 “pypi:repository-version”이라는 name 속성과 PEP 440과 호환되는 버전 번호인 content가 포함되며, 이 버전 번호는 추가로 Major.Minor만 사용하고 PEP 440이 지원하는 다른 추가 기능은 전혀 사용하지 않도록 제한됩니다.

결과적으로 다음과 같은 형태가 됩니다.:

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

저장소 버전을 해석할 때:

주 버전을 증가시키는 것은 하위 호환성이 없는 변경을 나타내는 데 사용되며, 이에 따라 기존 클라이언트가 더 이상 API를 의미 있게 사용할 수 있을 것으로 기대되지 않습니다.
부 버전을 증가시키는 것은 하위 호환성이 있는 변경을 나타내는 데 사용되며, 이에 따라 기존 클라이언트가 여전히 API를 의미 있게 사용할 수 있을 것으로 기대됩니다.

기존 클라이언트가 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).