Mailman 3 May 2003 - Distutils-SIG

Current draft of PEP 314
by Andrew Kuchling May 14, 2003

May 14, 2003

[Crossposted to Distutils-SIG and Catalog-SIG; followups set to Distutils-SIG.] Here's the current draft of PEP 314, which updates the format of the PKG-INFO file originally specified in PEP 241. From the section "Summary of Differences From PEP 241": * Metadata-Version is now 1.1. * Added the Classifiers field from PEP 301. * Added fields: Download-URL, Requires, Provides, Obsoletes, Conflicts. The remaining open issue is whether to deprecate the 'license' and 'platform' keyword arguments to setup(), on the grounds that the 'classifiers' list contains entries for this, and there should be only one way to do it. Comments welcome. --amk (www.amk.ca) Dream? Give me your hand. -- Death, in SANDMAN #69: "The Kindly Ones:13" PEP: 314 Title: Metadata for Python Software Packages v1.1 Version: $Revision: 1.15 $ Last-Modified: $Date: 2003/05/14 17:12:55 $ Author: A.M. Kuchling <amk(a)amk.ca> Status: Draft Type: Standards Track Content-type: text/plain Created: 12-Apr-2003 Python-Version: 2.3 Post-History: 29-Apr-2003 Replaces: 241 Introduction This PEP describes a mechanism for adding metadata to Python packages. It includes specifics of the field names, and their semantics and usage. This document specifies version 1.1 of the metadata format. Version 1.0 is specified in PEP 241. Including Metadata in Packages The Distutils 'sdist' command will extract the metadata fields from the arguments and write them to a file in the generated zipfile or tarball. This file will be named PKG-INFO and will be placed in the top directory of the source distribution (where the README, INSTALL, and other files usually go). Developers may not provide their own PKG-INFO file. The "sdist" command will, if it detects an existing PKG-INFO file, terminate with an appropriate error message. This should prevent confusion caused by the PKG-INFO and setup.py files being out of sync. The PKG-INFO file format is a single set of RFC-822 headers parseable by the rfc822.py module. The field names listed in the following section are used as the header names. Fields This section specifies the names and semantics of each of the supported metadata fields. Fields marked with "(Multiple use)" may be specified multiple times in a single PKG-INFO file. Other fields may only occur once in a PKG-INFO file. Fields marked with "(optional)" are not required to appear in a valid PKG-INFO file; all other fields must be present. Metadata-Version Version of the file format; currently "1.0" and "1.1" are the only legal values here. Example: Metadata-Version: 1.1 Name The name of the package. Example: Name: BeagleVote Version A string containing the package's version number. This field should be parseable by one of the Version classes (StrictVersion or LooseVersion) in the distutils.version module. Example: Version: 1.0a2 Platform (multiple use) A comma-separated list of platform specifications, summarizing the operating systems supported by the package. The major supported platforms are listed below, but this list is necessarily incomplete. POSIX, MacOS, Windows, BeOS, PalmOS. Example: Platform: POSIX, Windows Supported-Platform (multiple use) Binary distributions containing a PKG-INFO file will use the Supported-Platform field in their metadata to specify the OS and CPU for which the binary package was compiled. The semantics of the Supported-Platform field are not specified in this PEP. Example: Supported-Platform: RedHat 7.2 Supported-Platform: i386-win32-2791 Summary A one-line summary of what the package does. Example: Summary: A module for collecting votes from beagles. Description (optional) A longer description of the package that can run to several paragraphs. Software that deals with metadata should not assume any maximum size for this field, though people shouldn't include their instruction manual as the description. The contents of this field can be written using reStructuredText markup [1]. For programs that work with the metadata, supporting markup is optional; programs can also display the contents of the field as-is. This means that authors should be conservative in the markup they use. Example: Description: This module collects votes from beagles in order to determine their electoral wishes. Do *not* try to use this module with basset hounds; it makes them grumpy. Keywords (optional) A list of additional keywords to be used to assist searching for the package in a larger catalog. Example: Keywords: dog puppy voting election Home-page (optional) A string containing the URL for the package's home page. Example: Home-page: http://www.example.com/~cschultz/bvote/ Download-URL A string containing the URL from which this version of the package can be downloaded. (This means that the URL can't be something like ".../package-latest.tgz", but instead must be "../package-0.45.tgz".) Author (optional) A string containing the author's name at a minimum; additional contact information may be provided. Example: Author: C. Schultz, Universal Features Syndicate, Los Angeles, CA <cschultz(a)peanuts.example.com> Author-email A string containing the author's e-mail address. It can contain a name and e-mail address in the legal forms for a RFC-822 'From:' header. It's not optional because cataloging systems can use the e-mail portion of this field as a unique key representing the author. A catalog might provide authors the ability to store their GPG key, personal home page, and other additional metadata *about the author*, and optionally the ability to associate several e-mail addresses with the same person. Author-related metadata fields are not covered by this PEP. Example: Author-email: "C. Schultz" <cschultz(a)example.com> License A string selected from a short list of choices, specifying the license covering the package. Some licenses result in the software being freely redistributable, so packagers and resellers can automatically know that they're free to redistribute the software. Other licenses will require a careful reading by a human to determine how the software can be repackaged and resold. The choices are: Artistic, BSD, DFSG, GNU GPL, GNU LGPL, "MIT", Mozilla PL, "public domain", Python, Qt PL, Zope PL, unknown, nocommercial, nosell, nosource, shareware, other Definitions of some of the licenses are: DFSG The license conforms to the Debian Free Software Guidelines, but does not use one of the other DFSG 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 and earlier 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 is freely redistributable. The list of redistributable licenses is: Artistic, BSD, DFSG, GNU GPL, GNU LGPL, "MIT", Mozilla PL, "public domain", Python, Qt PL, Zope PL, nosource, shareware Note that being redistributable does not mean a package qualifies as free software, 'nosource' and 'shareware' being examples. Example: License: MIT Classifier (multiple use) Each entry is a string giving a single classification value for the package. Classifiers are described in PEP 301 [2]. Examples: Classifier: Development Status :: 4 - Beta Classifier: Environment :: Console (Text Based) Requires (multiple use) Each entry contains a string describing some other component or module required by this package. The format of a requirement string is simple: an arbitrary sequence of characters, optionally followed by a version declaration within parentheses. Leading and trailing whitespace are ignored, and whitespace within the string is normalized to a single space. A version declaration is a series of conditional operators and version numbers, separated by commas. Conditional operators must be one of "<", ">", "<=", ">=", "==", and "!=". Version numbers must be in the format accepted by the distutils.version.StrictVersion class: two or three dot-separated numeric components, with an optional "pre-release" tag on the end consisting of the letter 'a' or 'b' followed by a number. Example version numbers are "1.0", "2.3a2", "1.3.99", Any number of conditional operators can be specified, e.g. the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. All of the following are possible requirement strings: "rfc822", "zlib (>=1.1.4)", "XML parser". There's no canonical list of what strings should be used; the Python community is left to choose its own standards. Example: Requires: re Requires: sys Requires: zlib Requires: pyexpat (>1.0) Requires: DB-API 2.0 module Provides (multiple use) Each entry contains a string describing a component or module that will be provided by this package once it is installed. These strings should match the ones used in Requirements fields. Version declarations cannot be supplied; instead the package's version number will be used. Example: Provides: xml Provides: xml.utils Provides: xml.utils.iso8601 Provides: xml.dom Obsoletes (multiple use) Each entry contains a string describing a component or module that this package renders obsolete, meaning that the two packages should not be installed at the same time. Version declarations can be supplied. The most common use of this field will be in case a package name changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install Torqued Python, the Gorgon package should be removed. Example: Obsoletes: Gorgon Conflicts (multiple use) Each entry contains a string describing a component or module that conflicts with this package, meaning that the two packages should not be installed at the same time. Version declarations can be supplied. Conflict resolution probably isn't very important for Python programs, because few extensions will cause problems for other extensions, unless they happen to be using the same package name. This field name is being defined here for future use. Conflicts: Gorgon Summary of Differences From PEP 241 * Metadata-Version is now 1.1. * Added the Classifiers field from PEP 301. * Added fields: Download-URL, Requires, Provides, Obsoletes, Conflicts. Open issues With the addition of the 'Classifiers' field, should the Platform and License fields be removed? Acknowledgements Richard Jones suggested using reST for the Description field. References [1] reStructuredText http://docutils.sourceforge.net/ [2] PEP 301 http://www.python.org/peps/pep-0301.html Copyright This document has been placed in the public domain. Local Variables: mode: indented-text indent-tabs-mode: nil End:

1 0

RE: [Distutils] backwards compatibility of distutils?
by Moore, Paul May 14, 2003

May 14, 2003

From: Andrew Kuchling [mailto:akuchlin@mems-exchange.org] > On Wed, May 14, 2003 at 04:22:25PM +0200, M.-A. Lemburg wrote: > > >If you're starting to go for Python 2.2 in distutils, then it'll > >become very hard for code publishers to provide Python 2.0/2.1 > >versions of their code and, yes, these version are still in use out > >there. > > I don't follow this. Publishers write a setup.py against the > Distutils API; this has to run on the Python version being used. In > implementing the API, the Distutils code can use 2.2 or not, but > that's irrelevant to publishers as long as the installed version of > Distutils actually runs. I think the issue is that the "distutils API" isn't entirely well- defined. My usage of the distutils API is entirely trivial, and I don't expect I'd have any problem with the version packaged with Python x.y using features in Python x.y. I'd just use the appropriate Python/distutils versions and run python setup.py bdist_wininst N times. Done. But people writing fancy setup.py code subclass Distutils classes, use "internal" utility modules (the fancy_getopt module comes to mind here), and who knows what else. These people (MAL is definitely one of them) have to worry a lot about setup.py compatibility with different distutils versions. This message would be more useful if I knew what the solution to the problem was :-) [I have a suspicion that it's "document the official API, and use the time machine", but I don't have the keys to the time machine...] Paul.

1 0

compilation error
by Keith Jackson May 14, 2003

May 14, 2003

Does anybody know why I'm getting the following error when compiling an extension module with gcc and distutils? The compile line works fine when I run it by hand, but when distutils runs it I get the following error: gcc: cannot specify -o with -c or -S and multiple compilations error: command 'gcc' failed with exit status 1 Here's the line that causes the error: gcc -DNDEBUG -O3 -I/sw/globus/globus/include/gcc32dbgpthr -I/sw/include/python2.2 -c src/ftpControl_wrap.c -o build/temp.darwin-6.4-PowerMacintosh-2.2/ftpControl_wrap.o Any thoughts? thx, --keith

2 2

Re: [Python-checkins] python/dist/src/Doc/dist dist.tex,1.53,1.54
by Fred L. Drake, Jr. May 14, 2003

May 14, 2003

Anthony Baxter writes: > It's probably worth noting that the reference manual I'm writing > (see the sandbox) and the existing two Distutils docs need to > interact in some way. I'm not sure what that is yet, though... I see two possibilities, and have a fairly strong preference for one: 1. Include it in the "Distributing Python Modules" document. This makes a lot of sense, since the most common users of this documentation will be people trying to make distutils do the right thing for their package. This is also not unreasonable for people trying to extend distutils to support additional compilers, binary packages, and the like. 2. Distutils could have a chapter in the Library Reference. This isn't unreasonable, it just doesn't have anything else to recommend it. Clearly, I prefer option 1. ;-) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

3 4

distutils reference documentation work in progress
by Anthony Baxter May 13, 2003

May 13, 2003

I've started on a complete reference for distutils and it's piles and piles of goodies. It's very much a work in progress right now (I doubt it's even completely valid LaTeX yet :) but there's a slab of it done at http://www.interlink.com.au/anthony/tmp/distref_tex.txt (wacky filename because Apache kept sending it as a blah/x-tex rather than as bloody text). It'll be updated fairly regularly as I work on it - it's good fodder for the tram rides to/from work. The documentation is largely based on the voluminous docstrings, with a sprinkling of magic organisational pixie dust. Feedback is more than welcome. Anthony

1 1

patch for interpreter destination location
by Tim Magill May 13, 2003

May 13, 2003

Hi, I'm interested in building distribution files in multiple spooling directories for delivery on multiple platforms. In doing so there was no way for me to set the location for the interpreter in the final destination rather than the spooling destination. Enclosed is a patch that allows me to specify the string to be substituted in the "#!" line at the beginning of scripts and a documentation fragment for the new option. Comments? thanks tim

2 2

multiple args in setup.cfg lines
by Federico Di Gregorio May 8, 2003

May 8, 2003

Hi *, this is my first post to this list, and i did not found a FAQ anyware, so just tell me to go RTFM if this is a know problem. To put it shortly i am trying to use a setup.cfg file with the following entry: [build_ext] include_dirs: /usr/include/postgresql /usr/include/postgresql/server that results in: -Iinclude_dirs: /usr/include/postgresql /usr/include/postgresql/server i.e., a missing -I on the second include directory. after reading the source for dist.py i understand why and i can see an easy fix (quote_splitting the line) but maybe there is a reason for not splitting or another (better) way to obtain what i want? anticipated thanks, federico p.s. why setup.cfg does not accept extra_{compile,link}_args? that would have solved my problem, even if in a quite dirty way. -- Federico Di Gregorio Debian GNU/Linux Developer fog(a)debian.org INIT.D Developer fog(a)initd.org Don't dream it. Be it. -- Dr. Frank'n'further

1 0

setup.py not being included with sdist
by Nicodemus May 5, 2003

May 5, 2003

Hail! I've been using distutils to create distributions of some scripts and libraries, and everything works as expected, except that the setup.py file is not included in the source distribution. For example, if I use the sample program from the python docs: # setup.py from distutils.core import setup setup(name="foo", version="1.0", py_modules=["foo"]) and run "python setup install", it creates a zipfile named "foo-1.0.zip", that contains the following files: foo-1.0/ foo-1.0/foo.py foo-1.0/PKG-INFO Shouldn't setup.py be included with the distribution? What am I doing wrong? Thanks in advance, Nicodemus.

3 2

AssertionError when building rpm under RedHat 9.1
by Ricardo Niederberger Cabral May 2, 2003

May 2, 2003

2 1

Switching off optimization for python setup.py config
by Michiel Jan Laurens de Hoon May 1, 2003

May 1, 2003

Dear pythoneers, Recently I ran into a bug in Numerical Python's eigenvalues function, causing it to hang on Cygwin. The bug is caused by Numerical Python being compiled with optimization, while a number of routines (the dlamc* functions in dlapack_lite.c) should be compiled without optimization to function properly (as described in the lapack documentation). In reading the distutils archives, it seems that the issue of changing optimization levels and other compiler flags has been raised before. From what I understand, the current version of distutils does not allow to change the optimization level. The problem seems to be that some compiler arguments are required for an extension module to work with Python, and cannot just be changed (for example, my Makefile has OPT=-DNDEBUG -g -O3 -Wall -Wstrict-prototypes in it, which is more than just optimization flags). Now what the dlamc* functions are really doing is to find out some machine parameters before the actual numerical routines are executed. In today's world of autoconf, automake, and python setup.py config, I would think that it makes more sense to let distutils' config step figure out the machine parameters, and hardwire the results into the source code with some #define's. This can be achieved by letting python setup.py config run the dlamc* routines. However, for this we need to switch off optimization for the trial compilations and runs done by python setup.py config. Is this possible with the current version of distutils? If not, would it be worthwhile to add this to distutils? We have more freedom in changing compiler switches for trial compilations than for the actual extension module, and I would think that this would be useful for cases other than Numerical Python. --Michiel. -- Michiel de Hoon, Assistant Professor University of Tokyo, Institute of Medical Science Human Genome Center 4-6-1 Shirokane-dai, Minato-ku Tokyo 108-8639 Japan http://bonsai.ims.u-tokyo.ac.jp/~mdehoon

4 4