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 소프트웨어의 제3자 패키징을 더 쉽게 만들기 위해 설계된 여러 선택적 필드가 추가됩니다. 이러한 필드는 “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

Version

배포판의 버전 번호를 포함하는 문자열입니다. 이 필드는 PEP 440에서 지정한 형식이어야 합니다.

예제:

Version: 1.0a2

Platform (여러 번 사용)

“Operating System” Trove 분류자에 나열되지 않은, 배포판이 지원하는 운영 체제를 설명하는 Platform 사양입니다. 아래의 “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.

설명(선택 사항)

여러 단락에 걸쳐 이어질 수 있는 배포판에 대한 긴 설명입니다. 메타데이터를 처리하는 소프트웨어는 이 필드의 최대 크기를 가정해서는 안 되지만, 사용자는 설명에 사용 설명서 전체를 포함해서는 안 됩니다.

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

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

예제:

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: 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과 해당 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” 섹션에 이러한 추가 항목이 표시된다는 점에 유의하십시오.

Version Specifiers

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

조건 연산자는 원하는 개수만큼 지정할 수 있습니다. 예를 들어 문자열 “>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”.

환경 마커

environment marker는 세미콜론(“;”) 뒤 필드 끝에 추가하여 실행 환경에 관한 조건을 추가할 수 있는 마커입니다.

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

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.