Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python 개선 제안 한국어 번역

PEP 345 – Python 소프트웨어 패키지를 위한 메타데이터 1.2

Author:
Richard Jones <richard at python.org>
Discussions-To:
Distutils-SIG list
Status:
Superseded
Type:
Standards Track
Topic:
Packaging
Created:
28-Apr-2005
Python-Version:
2.7
Post-History:
22-Dec-2009
Replaces:
314
Superseded-By:
566
Resolution:
Python-Dev thread
Table of Contents

번역·라이선스 안내

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

Important

This PEP is a historical document. The up-to-date, canonical spec, Core metadata specifications, is maintained on the PyPA specs page.

×

See the PyPA specification update process for how to propose changes.

초록

이 PEP는 Python 배포에 메타데이터를 추가하는 메커니즘을 설명합니다. 여기에는 필드 이름과 그 의미 및 사용법에 관한 세부 사항이 포함됩니다.

이 문서는 메타데이터 형식의 버전 1.2를 명세합니다. 버전 1.0은 PEP 241에 명세되어 있습니다. 버전 1.1은 PEP 314에 명세되어 있습니다.

메타데이터 형식 버전 1.2는 Python 소프트웨어의 서드파티 패키징을 더 쉽게 하기 위해 고안된 여러 선택적 필드를 추가합니다. 이 필드들은 “Requires-Python”, “Requires-External”, “Requires-Dist”, “Provides-Dist”, “Obsoletes-Dist”입니다. 이 버전은 “Platform”(플랫폼) 필드도 변경합니다. 또한 “Maintainer”(유지 관리자), “Maintainer-email”, “Project-URL”의 세 가지 새 필드가 추가되었습니다.

마지막으로, 이 새 버전은 environment markers도 추가합니다.

필드

이 절은 지원되는 각 메타데이터 필드의 이름과 의미를 명세합니다.

“(Multiple use)”로 표시된 필드는 하나의 PKG-INFO 파일에서 여러 번 지정할 수 있습니다. 그 밖의 필드는 PKG-INFO 파일에 한 번만 나타날 수 있습니다. “(optional)”로 표시된 필드는 유효한 PKG-INFO 파일에 반드시 나타날 필요는 없습니다. 다른 모든 필드는 반드시 있어야 합니다.

Metadata-Version (메타데이터 버전)

파일 형식의 버전입니다. “1.2”만이 유일하게 허용되는 값입니다.

예시:

Metadata-Version: 1.2

Name

배포판의 이름입니다.

예시:

Name: BeagleVote

버전

배포판의 버전 번호를 담은 문자열입니다. 이 필드는 반드시 PEP 440에 명세된 형식이어야 합니다.

예시:

Version: 1.0a2

Platform (플랫폼, 여러 번 사용 가능)

배포가 지원하는 운영 체제 중 “Operating System” Trove 분류자에 나열되지 않은 운영 체제를 설명하는 플랫폼 명세입니다. 아래의 “Classifier”를 참조하십시오.

예시:

Platform: ObscureUnix
Platform: RareDOS

Supported-Platform (지원 플랫폼, 여러 번 사용 가능)

PKG-INFO 파일을 포함하는 바이너리 배포는 메타데이터의 Supported-Platform 필드를 사용하여 해당 바이너리 배포가 컴파일된 OS와 CPU 플랫폼을 지정합니다. Supported-Platform(지원 플랫폼) 필드의 의미는 이 PEP에서 명세하지 않습니다.

예시:

Supported-Platform: RedHat 7.2
Supported-Platform: i386-win32-2791

요약

배포판이 하는 일을 한 줄로 요약한 것입니다.

예시:

Summary: A module for collecting votes from beagles.

Description (선택)

배포판에 대한 더 긴 설명으로, 여러 단락에 걸칠 수 있습니다. 메타데이터를 다루는 소프트웨어는 이 필드의 최대 크기를 가정해서는 안 되지만, 그렇다고 해서 사용 설명서를 통째로 설명에 넣어서는 안 됩니다.

이 필드의 내용은 reStructuredText 마크업 [1]을 사용하여 작성할 수 있습니다. 메타데이터를 다루는 프로그램에서 마크업 지원은 선택 사항이며, 프로그램은 필드의 내용을 있는 그대로 표시할 수도 있습니다. 따라서 작성자는 마크업을 보수적으로 사용해야 합니다.

RFC 822 형식에서 빈 줄과 들여쓰기된 줄을 지원하려면, 모든 CRLF 문자 뒤에 공백 7개와 파이프(“|”) 문자를 붙여야 합니다. 그 결과, Description 필드는 RFC 822 Section 3.1.1 파서가 해석할 수 있는 접힌(folded) 필드로 인코딩됩니다.

예시:

Description: This project provides powerful math functions
        |For example, you can use ``sum()`` to sum numbers:
        |
        |Example::
        |
        |    >>> sum(1, 2)
        |    3
        |

이 인코딩은 RFC 822 리더를 사용하여 필드를 펼칠 때, CRLF 뒤에 공백 7개와 파이프 문자가 오는 모든 부분을 CRLF 하나로 바꾸어야 함을 의미합니다.

Keywords (키워드, 선택 사항)

더 큰 카탈로그에서 배포판을 검색하는 데 도움이 되도록 사용할 추가 키워드 목록입니다.

예시:

Keywords: dog puppy voting election

Home-page (선택)

배포판 홈페이지의 URL을 담은 문자열입니다.

예시:

Home-page: http://www.example.com/~cschultz/bvote/

Download-URL

이 버전의 배포판을 내려받을 수 있는 URL을 담은 문자열입니다. (즉, URL은 “…/BeagleVote-latest.tgz”와 같은 형태여서는 안 되며, “…/BeagleVote-0.45.tgz”와 같은 형태여야 합니다.)

Author (선택)

최소한 작성자의 이름을 담은 문자열이며, 추가 연락처 정보를 제공할 수도 있습니다.

예시:

Author: C. Schultz, Universal Features Syndicate,
        Los Angeles, CA <cschultz@peanuts.example.com>

Author-email (선택)

작성자의 이메일 주소를 담은 문자열입니다. RFC 822 From: 헤더에서 허용되는 형식으로 이름과 이메일 주소를 담을 수 있습니다.

예시:

Author-email: "C. Schultz" <cschultz@example.com>

Maintainer (유지 관리자, 선택 사항)

최소한 유지 관리자의 이름을 포함하는 문자열이며, 추가 연락처 정보를 제공할 수도 있습니다.

이 필드는 원저자가 아닌 다른 사람이 프로젝트를 유지 관리하는 경우에 사용하기 위한 것임에 유의하십시오. Author와 같다면 생략해야 합니다.

예시:

Maintainer: C. Schultz, Universal Features Syndicate,
        Los Angeles, CA <cschultz@peanuts.example.com>

Maintainer-email (유지 관리자 이메일, 선택 사항)

유지 관리자의 이메일 주소를 포함하는 문자열입니다. RFC 822 From: 헤더에 유효한 형식으로 이름과 이메일 주소를 포함할 수 있습니다.

이 필드는 원저자가 아닌 다른 사람이 프로젝트를 유지 관리하는 경우에 사용하기 위한 것임에 유의하십시오. Author-email과 같다면 생략해야 합니다.

예시:

Maintainer-email: "C. Schultz" <cschultz@example.com>

License (라이선스, 선택 사항)

라이선스가 “License” Trove 분류자 중에서 선택한 것이 아닌 경우, 배포 패키지에 적용되는 라이선스를 나타내는 텍스트입니다. 아래의 “Classifier”를 참조하십시오. 이 필드는 Classifier 필드를 통해 명명된 라이선스의 특정 버전을 지정하거나, 그러한 라이선스의 변형 또는 예외를 나타내는 데에도 사용할 수 있습니다.

예시:

License: This software may only be obtained by sending the
        author a postcard, and then the user promises not
        to redistribute it.

License: GPL version 3, excluding DRM provisions

Classifier (여러 번 사용 가능)

각 항목은 배포 패키지에 대한 단일 분류 값을 제공하는 문자열입니다. 분류자는 PEP 301에 설명되어 있습니다.

예시:

Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console (Text Based)

Requires-Dist (여러 번 사용 가능)

각 항목은 이 배포 패키지가 필요로 하는 다른 distutils 프로젝트의 이름을 나타내는 문자열을 담습니다.

요구 사항 문자열의 형식은 distutils 프로젝트 이름(예를 들어 Name: 필드에 있는 것과 같은 형식)과 동일하며, 선택적으로 괄호 안에 버전 선언이 뒤따를 수 있습니다.

distutils 프로젝트 이름은 Python Package Index에 있는 이름과 일치해야 합니다.

버전 선언은 Version Specifiers에 설명된 규칙을 따라야 합니다.

예시:

Requires-Dist: pkginfo
Requires-Dist: PasteDeploy
Requires-Dist: zope.interface (>3.5.0)

Provides-Dist (여러 번 사용 가능)

각 항목은 이 배포 패키지에 포함된 Distutils 프로젝트의 이름을 나타내는 문자열을 담습니다. 이 필드에는 Name 필드로 식별되는 프로젝트가 반드시 포함되어야 하며, 그 뒤에 버전이 따라옵니다: Name (Version).

배포 패키지는 추가 이름을 제공할 수 있으며, 예를 들어 여러 프로젝트가 함께 묶여 있음을 나타내는 데 사용할 수 있습니다. 예를 들어, ZODB 프로젝트의 소스 배포판은 역사적으로 transaction 프로젝트를 포함해 왔으며, 이 프로젝트는 현재 별도의 배포로 제공됩니다. 이러한 소스 배포판을 설치하면 ZODB와 transaction 모두에 대한 요구 사항이 충족됩니다.

배포 패키지는 별도로 배포되는 어떤 프로젝트에도 해당하지 않는 “가상” 프로젝트 이름을 제공할 수도 있습니다. 이러한 이름은 여러 프로젝트 중 하나가 제공할 수 있는 추상적인 기능을 나타내는 데 사용할 수 있습니다. 예를 들어 여러 프로젝트가 특정 ORM에서 사용할 RDBMS 바인딩을 제공할 수 있습니다. 각 프로젝트는 자신이 ORM-bindings를 제공한다고 선언할 수 있으며, 이를 통해 다른 프로젝트는 그중 최대 하나가 설치되어 있다는 것에만 의존할 수 있습니다.

버전 선언을 제공할 수 있으며, 제공하는 경우 Version Specifiers에 설명된 규칙을 따라야 합니다. 버전을 지정하지 않으면 배포판의 버전 번호가 암묵적으로 적용됩니다.

예시:

Provides-Dist: OtherProject
Provides-Dist: AnotherProject (3.4)
Provides-Dist: virtual_package

Obsoletes-Dist (여러 번 사용 가능)

각 항목은 이 배포판이 쓸모없게 만드는 distutils 프로젝트의 배포판을 설명하는 문자열을 담습니다. 즉, 두 프로젝트를 동시에 설치해서는 안 된다는 뜻입니다.

버전 선언을 제공할 수 있습니다. 버전 번호는 Version Specifiers에 명시된 형식을 따라야 합니다.

이 필드는 주로 프로젝트 이름이 바뀌는 경우에 사용될 것입니다. 예를 들어 Gorgon 2.3이 Torqued Python 1.0에 흡수되는 경우입니다. Torqued Python을 설치할 때는 Gorgon 배포판을 제거해야 합니다.

예시:

Obsoletes-Dist: Gorgon
Obsoletes-Dist: OtherProject (<3.0)

Requires-Python

이 필드는 배포판이 호환성을 보장하는 Python 버전을 지정합니다.

버전 번호는 Version Specifiers에 명시된 형식을 따라야 합니다.

예시:

Requires-Python: 2.5
Requires-Python: >2.1
Requires-Python: >=2.3.4
Requires-Python: >=2.5,<2.7

Requires-External (여러 번 사용 가능)

각 항목은 배포판이 사용될 시스템의 의존성을 설명하는 문자열을 담습니다. 이 필드는 다운스트림 프로젝트 유지 관리자에게 힌트를 제공하기 위한 것이며, distutils 배포에 의미 있는 의미를 갖지 않습니다.

요구 사항 문자열의 형식은 외부 의존성의 이름이며, 그 뒤에 괄호로 감싼 버전 선언을 선택적으로 붙일 수 있습니다.

이 필드의 버전 번호는 Python이 아닌 소프트웨어 릴리스를 가리키므로 PEP 440에 명시된 형식을 따를 필요가 없습니다. 대신 해당 외부 의존성이 사용하는 버전 체계를 따라야 합니다.

사용할 문자열에 관한 특별한 규칙은 없다는 점에 유의하십시오.

예시:

Requires-External: C
Requires-External: libpng (>=1.5)

Project-URL (여러 번 사용 가능)

프로젝트의 추가 URL과 그 레이블을 쉼표로 구분하여 담은 문자열입니다. 메타데이터에 “Home-page” 필드 외에 나열할 다른 URL이 있을 때 이 필드를 사용해야 합니다.

예시:

Project-URL: Bug Tracker, https://github.com/pypa/setuptools/issues
Project-URL: Documentation, https://setuptools.readthedocs.io/
Project-URL: Funding, https://donate.pypi.org

레이블은 자유 형식 텍스트이며, 최대 길이는 32자입니다. PyPI에 업로드된 배포판은 랜딩 페이지의 “Project links” 섹션 아래에 이러한 추가 항목이 표시된다는 점에 유의하십시오.

버전 지정자

버전 지정자는 쉼표로 구분된 일련의 조건 연산자와 버전 번호로 이루어집니다. 조건 연산자는 “<”, “>”, “<=”, “>=”, “==”, “!=” 중 하나여야 합니다.

조건 연산자는 개수에 제한 없이 지정할 수 있습니다. 예를 들어 “>1.0, !=1.3.4, <2.0” 문자열은 올바른 버전 선언입니다. 쉼표(“,”)는 and 연산자와 같습니다.

각 버전 번호는 PEP 440에 명시된 형식을 따라야 합니다.

버전이 주어지면 항상 같은 값으로 시작하는 모든 버전을 포함합니다. 예를 들어 Python의 “2.5” 버전에는 “2.5.2”나 “2.5.3” 같은 버전이 포함됩니다. 이 경우 사전 릴리스와 사후 릴리스는 제외됩니다. 따라서 이 예에서 “2.5”를 사용하면 “2.5a1” 같은 버전은 포함되지 않습니다. 범위의 첫 번째 버전이 필요하다면 명시적으로 지정해야 합니다. 이 예에서는 “2.5.0”이 됩니다.

일부 프로젝트는 “2.5.x” 시리즈의 첫 릴리스에서 “.0” 접미사를 생략할 수 있다는 점에 유의하십시오:

  • 2.5
  • 2.5.1
  • 2.5.2
  • 등.

이 경우 전체 범위를 나타내는 “2.5” 표기법과의 혼동을 피하기 위해 “2.5.0”을 명시적으로 사용해야 합니다. 이 문제를 완전히 피하려면 한 시리즈 안에서 같은 길이의 체계를 사용하는 것이 권장됩니다.

몇 가지 예는 다음과 같습니다.

  • Requires-Dist: zope.interface (3.1): 3.1로 시작하는 모든 버전이며, 사후 릴리스와 사전 릴리스는 제외합니다.
  • Requires-Dist: zope.interface (3.1.0): 3.1.0으로 시작하는 모든 버전이며, 사후 릴리스와 사전 릴리스는 제외합니다. 이 프로젝트는 3자리를 넘는 숫자를 사용하지 않으므로, 이는 “3.1.0 릴리스만”을 의미하기도 합니다.
  • Requires-Python: 3: 어떤 것이든 상관없이 모든 Python 3 버전이며, 사후 릴리스와 사전 릴리스는 제외합니다.
  • Requires-Python: >=2.6,<3: Python 2.6 또는 2.7의 모든 버전이며, 2.6의 사후 릴리스와 2.7의 사전 및 사후 릴리스를 포함합니다. Python 3의 사전 릴리스는 제외합니다.
  • Requires-Python: 2.6.2: “>=2.6.2,<2.6.3”과 동등합니다. 따라서 이는 Python 2.6.2만 포함합니다. 물론 Python의 버전 번호가 4자리였다면 2.6.2 시리즈의 모든 버전을 포함했을 것입니다.
  • Requires-Python: 2.5.0: “>=2.5.0,<2.5.1”과 동등합니다.
  • Requires-Dist: zope.interface (3.1,!=3.1.3): 3.1로 시작하는 모든 버전이며, 3.1의 사후 릴리스와 사전 릴리스를 제외하고 또한 “3.1.3”으로 시작하는 모든 버전도 제외합니다. 이 프로젝트의 경우, 이는 “3.1 시리즈의 모든 버전이되 3.1.3은 제외”를 의미합니다. 이는 다음과 동등합니다: “>=3.1,!=3.1.3,<3.2”.

환경 마커

환경 마커는 실행 환경에 관한 조건을 추가하기 위해 필드 끝의 세미콜론(“;”) 뒤에 덧붙일 수 있는 마커입니다.

다음은 이러한 마커를 사용하는 필드의 몇 가지 예입니다:

Requires-Dist: pywin32 (>1.0); sys.platform == 'win32'
Obsoletes-Dist: pywin31; sys.platform == 'win32'
Requires-Dist: foo (1,!=1.3); platform.machine == 'i386'
Requires-Dist: bar; python_version == '2.4' or python_version == '2.5'
Requires-External: libxslt; 'linux' in sys.platform

이 기능의 바탕이 되는 마이크로 언어는 가능한 한 가장 단순합니다. == 및 in 연산자(그리고 그 반대 연산자)로 문자열만 비교하며, 표현식을 조합할 수 있습니다. 따라서 파이썬 사용자가 아닌 사람도 쉽게 이해할 수 있습니다.

의사 문법은 다음과 같습니다.

EXPR [in|==|!=|not in] EXPR [or|and] ...

여기서 EXPR는 다음 중 하나에 해당합니다.

  • python_version = ‘%s.%s’ % (sys.version_info[0], sys.version_info[1])
  • python_full_version = sys.version.split()[0]
  • os.name = os.name
  • sys.platform = sys.platform
  • platform.version = platform.version()
  • platform.machine = platform.machine()
  • platform.python_implementation = platform.python_implementation()
  • '2.4' 또는 'win32' 같은 자유 문자열

in은 문자열에만 사용할 수 있습니다. 즉, 오른쪽에 튜플이나 리스트 같은 다른 시퀀스를 사용할 수 없다는 점에 유의하십시오.

이 마커를 활용할 수 있는 필드는 다음과 같습니다.

  • Requires-External
  • Requires-Dist
  • Provides-Dist
  • Obsoletes-Dist
  • Classifier

PEP 314와의 차이점 요약

  • Metadata-Version(메타데이터 버전)은 이제 1.2입니다.
  • 환경 마커를 추가했습니다.
  • 변경된 필드:
    • Platform (플랫폼, 문법 변경)
    • Author-email (선택 필드로 변경)
  • 추가된 필드:
    • Maintainer (유지 관리자)
    • Maintainer-email (유지 관리자 이메일)
    • Requires-Python
    • Requires-External
    • Requires-Dist
    • Provides-Dist
    • Obsoletes-Dist
    • Project-URL
  • 폐기된 필드:
    • Requires (Requires-Dist로 대체됨)
    • Provides (Provides-Dist로 대체됨)
    • Obsoletes (Obsoletes-Dist로 대체됨)

참고 문헌

이 문서는 메타데이터 형식 버전 1.2를 명세합니다. 버전 1.0은 PEP 241에 명세되어 있습니다. 버전 1.1은 PEP 314에 명세되어 있습니다.

Acknowledgements

Fred Drake, Anthony Baxter and Matthias Klose have all contributed to the ideas presented in this PEP.

Tres Seaver, Jim Fulton, Marc-André Lemburg, Martin von Löwis, Tarek Ziadé, David Lyon and other people at the Distutils-SIG have contributed to the new updated version.