PEP 503 – 단순 저장소 API

Author:: Donald Stufft <donald at stufft.io>
BDFL-Delegate:: Donald Stufft <donald at stufft.io>
Discussions-To:: Distutils-SIG list
Status:: Final
Type:: Standards Track
Topic:: Packaging
Created:: 04-Sep-2015
Post-History:: 04-Sep-2015
Resolution:: Distutils-SIG message

Table of Contents

초록
사양
- 정규화된 이름
- 변경 사항
Copyright

번역·라이선스 안내

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

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.

초록

Python 패키지 저장소의 구현과 이를 사용하는 도구는 많이 존재합니다. 이들 중 “단순” 저장소 API가 어떤 형태인지 정의하는 표준 구현은 PyPI를 구동하는 구현입니다. 이 문서는 해당 API를 명시하고, 단순 저장소 API의 모든 구현에 올바른 동작이 무엇인지 문서화합니다.

사양

단순 API를 구현하는 저장소는 베이스 URL로 정의되며, 이는 모든 추가 URL이 그 하위에 위치하는 최상위 URL입니다. 이 API가 “simple” 저장소로 명명된 것은 PyPI의 기본 URL이 https://pypi.org/simple/이기 때문입니다.

Note

이 문서의 이후 모든 URL은 이 기본 URL을 기준으로 상대적입니다(따라서 PyPI의 URL이 주어지면, /foo/라는 URL은 https://pypi.org/simple/foo/가 될 것입니다).

저장소 내에서 루트 URL(기본 URL을 나타내는 이 PEP에서는 /)은 저장소의 각 프로젝트마다 하나의 앵커 요소가 있는 유효한 HTML5 페이지여야 합니다. 앵커 태그의 텍스트는 프로젝트의 이름이어야 하며, href 속성은 해당 프로젝트의 URL로 연결되어야 합니다. 예시는 다음과 같습니다.:

<!DOCTYPE html>
<html>
  <body>
    <a href="/frob/">frob</a>
    <a href="/spamspamspam/">spamspamspam</a>
  </body>
</html>

루트 URL 아래에는 저장소에 포함된 각 개별 프로젝트마다 하나의 URL이 존재합니다. 이 URL의 형식은 /<project>/이며, 여기서 <project>는 해당 프로젝트의 정규화된 이름으로 대체됩니다. 따라서 “HolyGrail”이라는 프로젝트의 URL은 /holygrail/과 같은 형태가 됩니다. 이 URL은 프로젝트의 각 파일마다 하나의 앵커 요소가 있는 유효한 HTML5 페이지를 반환해야 합니다. href 속성은 다운로드할 파일의 위치로 연결되는 URL이어야 하며, 앵커 태그의 텍스트는 URL의 마지막 경로 구성 요소(파일 이름)와 일치해야 합니다. URL에는 다음 구문을 따르는 URL 프래그먼트 형식의 해시가 포함되어야 합니다: #<hashname>=<hashvalue>. 여기서 <hashname>은 해시 함수의 소문자 이름(예: sha256)이고 <hashvalue>는 16진수로 인코딩된 다이제스트입니다.

위의 내용에 더하여 다음 제약 조건이 API에 적용됩니다.

HTML5 페이지로 응답하는 모든 URL은 /로 끝나야 하며, 저장소는 /가 없는 URL을 끝에 /를 추가한 URL로 리디렉션해야 합니다.
URL은 올바른 위치를 가리키기만 한다면 절대 URL 또는 상대 URL일 수 있습니다.
파일을 저장소와 관련하여 어디에 호스팅해야 하는지에 대한 제약은 없습니다.
필요한 앵커 요소가 존재하는 한 API 페이지에는 다른 HTML 요소가 있어도 됩니다.
저장소는 정규화되지 않은 URL을 표준 정규화 URL로 MAY 리디렉션할 수 있습니다(예: /Foobar/를 /foobar/로 리디렉션할 수 있습니다). 그러나 클라이언트는 이 리디렉션에 MUST NOT의존해야 하며 MUST정규화된 URL을 요청해야 합니다.
저장소는 Python 표준 라이브러리의 hashlib 모듈을 통해 사용 가능하도록 보장된 해시 함수 중 하나를 선택해야 합니다(현재는 md5, sha1, sha224, sha256, sha384, sha512입니다). 현재 권장 사항은 sha256을 사용하는 것입니다.
특정 배포 파일에 대한 GPG 서명이 있는 경우, 해당 서명은 파일과 같은 이름에 .asc를 덧붙인 이름으로 파일과 함께 있어야 합니다. 따라서 /packages/HolyGrail-1.0.tar.gz 파일이 존재하고 연결된 서명이 있다면 서명은 /packages/HolyGrail-1.0.tar.gz.asc에 위치합니다.
저장소는 파일 링크에 data-gpg-sig속성을 MAY 포함할 수 있으며, GPG 서명이 있는지 여부를 나타내는 값으로 true 또는 false 중 하나를 지정할 수 있습니다. 이렇게 하는 저장소는 모든 링크에 해당 속성을 포함해야 합니다.
저장소는 파일 링크에 data-requires-python 속성을 MAY 포함할 수 있습니다. 이는 해당 릴리스에 대해 PEP 345에 명시된 Requires-Python 메타데이터 필드를 노출합니다. 이 속성이 있으면 설치 도구는 요구 사항을 충족하지 않는 Python 버전에 설치할 때 해당 다운로드를 SHOULD 무시해야 합니다. 예를 들어 다음과 같습니다.:
```
<a href="..." data-requires-python="&gt;=3">...</a>
```
속성 값에서 <와 >는 각각 < 및 >로 HTML 인코딩해야 합니다.

정규화된 이름

이 PEP에서는 “정규화된” 프로젝트 이름이라는 개념을 참조합니다. 관련 PEP 426에 따르면 이름에 사용할 수 있는 유효한 문자는 ASCII 알파벳, ASCII 숫자, ., -, _뿐입니다. 이름은 소문자로 변환하고 ., -, 또는 _ 문자가 연속해서 나타나는 모든 부분을 단일 -문자로 치환해야 합니다. 이는 Python에서 re 모듈을 사용하여 구현할 수 있습니다.:

import re

def normalize(name):
    return re.sub(r"[-_.]+", "-", name).lower()

변경 사항

선택적인 data-requires-python 속성은 2016년 7월에 추가되었습니다.

Copyright

This document has been placed in the public domain.