PEP 503 – Simple 저장소 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 패키지 저장소의 구현은 여러 가지이며, 이를 사용하는 도구도 많습니다. 그중에서 “simple” 저장소 API의 형태를 정의하는 표준 구현은 PyPI를 구동하는 구현입니다. 이 문서는 그 API를 명세하고, simple 저장소 API를 구현하는 모든 구현이 따라야 할 올바른 동작을 기술합니다.

명세

simple API를 구현하는 저장소는 기본 URL로 정의됩니다. 기본 URL은 다른 모든 URL이 그 아래에 놓이는 최상위 URL입니다. 이 API를 “simple” 저장소라고 부르는 까닭은 PyPI의 기본 URL이 https://pypi.org/simple/이기 때문입니다.

Note

이 문서에서 이후에 나오는 모든 URL은 이 기본 URL에 대한 상대 경로입니다(PyPI의 URL을 예로 들면, /foo/ URL은 https://pypi.org/simple/foo/가 됩니다.

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

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

루트 URL 아래에는 저장소에 들어 있는 개별 프로젝트마다 URL이 하나씩 더 있습니다. 이 URL의 형식은 /<project>/이며, <project>는 해당 프로젝트의 정규화된 이름으로 바뀝니다. 따라서 “HolyGrail”이라는 이름의 프로젝트는 /holygrail/ 같은 URL을 가집니다. 이 URL은 프로젝트의 파일마다 앵커 요소를 하나씩 담은 유효한 HTML5 페이지로 응답해야 합니다. href 속성은 내려받을 파일의 위치로 연결되는 URL이어야 하며(MUST), 앵커 태그의 텍스트는 URL의 마지막 경로 구성 요소(파일 이름)와 일치해야 합니다(MUST). URL에는 #<hashname>=<hashvalue> 문법의 URL 프래그먼트 형태로 해시를 포함해야 합니다(SHOULD). 여기서 <hashname>은 해시 함수의 소문자 이름(sha256 등)이고 <hashvalue>는 16진수로 인코딩된 다이제스트입니다.

위의 내용에 더해, API에는 다음과 같은 제약이 적용됩니다.

HTML5 페이지로 응답하는 모든 URL은 /로 끝나야 하며(MUST), 저장소는 /가 없는 URL을 끝에 /를 붙인 URL로 리디렉션하는 것이 좋습니다(SHOULD).
URL은 올바른 위치를 가리키기만 하면 절대 경로여도 되고 상대 경로여도 됩니다.
저장소를 기준으로 파일을 어디에 호스팅해야 하는지에 대한 제약은 없습니다.
필요한 앵커 요소만 있으면 API 페이지에 다른 HTML 요소가 얼마든지 있어도 됩니다.
저장소는 정규화되지 않은 URL을 표준 정규화 URL로 리디렉션할 수 있습니다(MAY)(예: /Foobar/를 /foobar/로 리디렉션할 수 있음). 그러나 클라이언트는 이 리디렉션에 의존해서는 안 되며(MUST NOT) 정규화된 URL을 요청해야 합니다(MUST).
저장소는 Python 표준 라이브러리의 hashlib 모듈에서 사용할 수 있음이 보장되는 해시 함수(현재 md5, sha1, sha224, sha256, sha384, sha512) 가운데 하나를 선택하는 것이 좋습니다(SHOULD). 현재 권장 사항은 sha256을 사용하는 것입니다.
특정 배포 파일에 GPG 서명이 있다면, 그 서명은 해당 파일과 같은 위치에 파일 이름 뒤에 .asc를 덧붙인 이름으로 있어야 합니다(MUST). 따라서 /packages/HolyGrail-1.0.tar.gz 파일이 있고 그 파일에 연결된 서명이 있다면, 서명은 /packages/HolyGrail-1.0.tar.gz.asc에 위치합니다.
저장소는 GPG 서명이 있는지를 나타내기 위해 파일 링크에 true 또는 false 값을 가진 data-gpg-sig 속성을 포함할 수 있습니다(MAY). 이렇게 하는 저장소는 모든 링크에 이 속성을 포함하는 것이 좋습니다(SHOULD).
저장소는 파일 링크에 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.