Important
This PEP is a historical document. The up-to-date, canonical spec,Core metadata specifications, is maintained on thePyPA specs page.
×
See thePyPA specification update process for how to propose changes.
This PEP describes a mechanism for adding metadata to Pythonpackages. It includes specifics of the field names, and theirsemantics and usage.
The Distutils ‘sdist’ command will be modified to extract themetadata fields from the arguments and write them to a file in thegenerated zipfile or tarball. This file will be named PKG-INFOand will be placed in the top directory of the sourcedistribution (where the README, INSTALL, and other files usuallygo).
Developers may not provide their own PKG-INFO file. The “sdist”command will, if it detects an existing PKG-INFO file, terminatewith an appropriate error message. This should prevent confusioncaused by the PKG-INFO and setup.py files being out of sync.
The PKG-INFO file format is a single set ofRFC 822 headersparseable by the rfc822.py module. The field names listed in thefollowing section are used as the header names. There’s noextension mechanism in this simple format; the Catalog and DistutilsSIGs will aim at getting a more flexible format ready for Python 2.2.
This section specifies the names and semantics of each of thesupported metadata fields.
Fields marked with “(Multiple use)” may be specified multipletimes in a single PKG-INFO file. Other fields may only occuronce in a PKG-INFO file. Fields marked with “(optional)” arenot required to appear in a valid PKG-INFO file, all otherfields must be present.
Version of the file format; currently “1.0” is the onlylegal value here.
Example:
Metadata-Version:1.0
The name of the package.
Example:
Name:BeagleVote
A string containing the package’s version number. Thisfield should be parseable by one of the Version classes(StrictVersion or LooseVersion) in the distutils.versionmodule.
Example:
Version:1.0a2
A comma-separated list of platform specifications, summarizingthe operating systems supported by the package. The majorsupported platforms are listed below, but this list isnecessarily incomplete.
POSIX,MacOS,Windows,BeOS,PalmOS.
Binary distributions will use the Supported-Platform field intheir metadata to specify the OS and CPU for which the binarypackage was compiled. The semantics of the Supported-Platformare not specified in this PEP.
Example:
Platform:POSIX,Windows
A one-line summary of what the package does.
Example:
Summary:Amoduleforcollectingvotesfrombeagles.
A longer description of the package that can run to severalparagraphs. (Software that deals with metadata should notassume any maximum size for this field, though one hopes thatpeople won’t include their instruction manual as thelong-description.)
Example:
Description:Thismodulecollectsvotesfrombeaglesinordertodeterminetheirelectoralwishes.DoNOTtrytousethismodulewithbassethounds;itmakesthemgrumpy.
A list of additional keywords to be used to assist searchingfor the package in a larger catalog.
Example:
Keywords:dogpuppyvotingelection
A string containing the URL for the package’s home page.
Example:
Home-page:http://www.example.com/~cschultz/bvote/
A string containing at a minimum the author’s name. Contactinformation can also be added, separating each line withnewlines.
Example:
Author:C.SchultzUniversalFeaturesSyndicateLosAngeles,CA
A string containing the author’s e-mail address. It can containa name and e-mail address in the legal forms for aRFC 822‘From:’ header. It’s not optional because cataloging systemscan use the e-mail portion of this field as a unique keyrepresenting the author. A catalog might provide authors theability to store their GPG key, personal home page, and otheradditional metadataabout the author, and optionally theability to associate several e-mail addresses with the sameperson. Author-related metadata fields are not covered by thisPEP.
Example:
Author-email:"C. Schultz"<cschultz@example.com>
A string selected from a short list of choices, specifying thelicense covering the package. Some licenses result in thesoftware being freely redistributable, so packagers andresellers can automatically know that they’re free toredistribute the software. Other licenses will requirea careful reading by a human to determine how the software can berepackaged and resold.
The choices are:
Artistic,BSD,DFSG,GNUGPL,GNULGPL,"MIT",MozillaPL,"public domain",Python,QtPL,ZopePL,unknown,nocommercial,nosell,nosource,shareware,other
Definitions of some of the licenses are:
| DFSG | The license conforms to the Debian Free SoftwareGuidelines, but does not use one of the otherDFSG conforming licenses listed here.More information is available at:http://www.debian.org/social_contract#guidelines |
| Python | Python 1.6 or higher license. Version 1.5.2 andearlier are under the MIT license. |
| public domain | Software is public domain, not copyrighted. |
| unknown | Status is not known |
| nocommercial | Free private use but commercial use not permitted |
| nosell | Free use but distribution for profit by arrangement |
| nosource | Freely distributable but no source code |
| shareware | Payment is requested if software is used |
| other | General category for other non-DFSG licenses |
Some of these licenses can be interpreted to mean the software isfreely redistributable. The list of redistributable licenses is:
Artistic,BSD,DFSG,GNUGPL,GNULGPL,"MIT",MozillaPL,"public domain",Python,QtPL,ZopePL,nosource,shareware
Note that being redistributable does not mean a packagequalifies as free software, ‘nosource’ and ‘shareware’ beingexamples.
Example:
License:MIT
Many changes and rewrites to this document were suggested by thereaders of the Distutils SIG. In particular, Sean Reifschneideroften contributed actual text for inclusion in this PEP.
The list of licenses was compiled using the SourceForge licenselist and the CTAN license list compiled by Graham Williams; CareyEvans also offered several useful suggestions on this list.
This document has been placed in the public domain.
Source:https://github.com/python/peps/blob/main/peps/pep-0241.rst
Last modified:2024-10-06 16:27:00 GMT