| version: | 0.9 |
|---|
This document describes the setup.cfg, an ini-style configuration file used by Packaging to replace the setup.py file used by Distutils. This specification is language-agnostic, and will therefore repeat some information that’s already documented for Python in the configparser.RawConfigParser documentation.
The ini-style format used in the configuration file is a simple collection of sections that group sets of key-value fields separated by = or : and optional whitespace. Lines starting with # or ; are comments and will be ignored. Empty lines are also ignored. Example:
[section1]
# comment
name = value
name2 = "other value"
[section2]
foo = bar
Here are a set of rules to parse values:
Examples:
[section]
foo = one
two
three
bar = false
baz = 1.3
boo = "ok"
beee = "wqdqw pojpj w\"ddq"
A configuration file can be extended (i.e. included) by other files. For this, a DEFAULT section must contain an extends key whose value points to one or more files which will be merged into the current files by adding new sections and fields. If a file loaded by extends contains sections or keys that already exist in the original file, they will not override the previous values.
Contents of one.cfg:
[section1]
name = value
[section2]
foo = foo from one.cfg
Contents of two.cfg:
[DEFAULT]
extends = one.cfg
[section2]
foo = foo from two.cfg
baz = baz from two.cfg
The result of parsing two.cfg is equivalent to this file:
[section1]
name = value
[section2]
foo = foo from one.cfg
baz = baz from two.cfg
Example use of multi-line notation to include more than one file:
[DEFAULT]
extends = one.cfg
two.cfg
When several files are provided, they are processed sequentially, following the precedence rules explained above. This means that the list of files should go from most specialized to most common.
Tools will need to provide a way to produce a merged version of the file. This will be useful to let users publish a single file.
Each section contains a description of its options.
The sections are:
Contains global options for Packaging. This section is shared with Distutils.
Defined Packaging command. A command is defined by its fully qualified name. optional, multi
Examples:
[global]
commands =
package.setup.CustomSdistCommand
package.setup.BdistDeb
Defined Packaging compiler. A compiler is defined by its fully qualified name. optional, multi
Example:
[global]
compilers =
hotcompiler.SmartCCompiler
Defines a list of callables to be called right after the setup.cfg file is read, before any other processing. Each value is a Python dotted name to an object, which has to be defined in a module present in the project directory alonside setup.cfg or on Python’s sys.path (see Finding hooks). The callables are executed in the order they’re found in the file; if one of them cannot be found, tools should not stop, but for example produce a warning and continue with the next line. Each callable receives the configuration as a dictionary (keys are setup.cfg sections, values are dictionaries of fields) and can make any change to it. optional, multi
Example:
[global]
setup_hooks = _setuphooks.customize_config
The metadata section contains the metadata for the project as described in PEP 345. Field names are case-insensitive.
Fields:
One extra field not present in PEP 345 is supported:
Example:
[metadata]
name = pypi2rpm
version = 0.1
author = Tarek Ziadé
author-email = tarek@ziade.org
summary = Script that transforms an sdist archive into a RPM package
description-file = README
home-page = http://bitbucket.org/tarek/pypi2rpm/wiki/Home
project-url:
Repository, http://bitbucket.org/tarek/pypi2rpm/
RSS feed, https://bitbucket.org/tarek/pypi2rpm/rss
classifier =
Development Status :: 3 - Alpha
License :: OSI Approved :: Mozilla Public License 1.1 (MPL 1.1)
You should not give any explicit value for metadata-version: it will be guessed from the fields present in the file.
This section describes the files included in the project.
Example:
[files]
packages_root = src
packages =
pypi2rpm
pypi2rpm.command
scripts =
pypi2rpm/pypi2rpm.py
extra_files =
setup.py
README
Note
The setup.cfg configuration file is included by default. Contrary to Distutils, README (or README.txt) and setup.py are not included by default.
This section describes the files used by the project which must not be installed in the same place that python modules or libraries, they are called resources. They are for example documentation files, script files, databases, etc...
For declaring resources, you must use this notation:
source = destination
Data-files are declared in the resources field in the file section, for example:
[files]
resources =
source1 = destination1
source2 = destination2
The source part of the declaration are relative paths of resources files (using unix path separator /). For example, if you’ve this source tree:
foo/
doc/
doc.man
scripts/
foo.sh
Your setup.cfg will look like:
[files]
resources =
doc/doc.man = destination_doc
scripts/foo.sh = destination_scripts
The final paths where files will be placed are composed by : source + destination. In the previous example, doc/doc.man will be placed in destination_doc/doc/doc.man and scripts/foo.sh will be placed in destination_scripts/scripts/foo.sh. (If you want more control on the final path, take a look at Defining a base prefix).
The destination part of resources declaration are paths with categories. Indeed, it’s generally a bad idea to give absolute path as it will be cross incompatible. So, you must use resources categories in your destination declaration. Categories will be replaced by their real path at the installation time. Using categories is all benefit, your declaration will be simpler, cross platform and it will allow packager to place resources files where they want without breaking your code.
Categories can be specified by using this syntax:
{category}
Default categories are:
A special category also exists {distribution.name} that will be replaced by the name of the distribution, but as most of the defaults categories use them, so it’s not necessary to add {distribution.name} into your destination.
If you use categories in your declarations, and you are encouraged to do, final path will be:
source + destination_expanded
For example, if you have this setup.cfg:
[metadata]
name = foo
[files]
resources =
doc/doc.man = {doc}
And if {doc} is replaced by {datadir}/doc/{distribution.name}, final path will be:
{datadir}/doc/foo/doc/doc.man
Where {datafir} category will be platform-dependent.
When you declare source file, you can use a glob-like syntax to match multiples file, for example:
scripts/* = {script}
Will match all the files in the scripts directory and placed them in the script category.
Glob tokens are:
- *: match all files.
- ?: match any character.
- **: match any level of tree recursion (even 0).
- {}: will match any part separated by comma (example: {sh,bat}).
The order of declaration is important if one file match multiple rules. The last rules matched by file is used, this is useful if you have this source tree:
foo/
doc/
index.rst
setup.rst
documentation.txt
doc.tex
README
And you want all the files in the doc directory to be placed in {doc} category, but README must be placed in {help} category, instead of listing all the files one by one, you can declare them in this way:
[files]
resources =
doc/* = {doc}
doc/README = {help}
You can exclude some files of resources declaration by giving no destination, it can be useful if you have a non-resources file in the same directory of resources files:
foo/
doc/
RELEASES
doc.tex
documentation.txt
docu.rst
Your files section will be:
[files]
resources =
doc/* = {doc}
doc/RELEASES =
When you define your resources, you can have more control of how the final path is computed.
By default, the final path is:
destination + source
This can generate long paths, for example (example_final_path):
{datadir}/doc/foo/doc/doc.man
When you declare your source, you can use whitespace to split the source in prefix suffix. So, for example, if you have this source:
docs/ doc.man
The prefix is “docs/” and the suffix is “doc.html”.
Note
Separator can be placed after a path separator or replace it. So these two sources are equivalent:
docs/ doc.man
docs doc.man
Note
Glob syntax is working the same way with standard source and split source. So these rules:
docs/*
docs/ *
docs *
Will match all the files in the docs directory.
When you use split source, the final path is computed this way:
destination + prefix
So for example, if you have this setup.cfg:
[metadata]
name = foo
[files]
resources =
doc/ doc.man = {doc}
And if {doc} is replaced by {datadir}/doc/{distribution.name}, final path will be:
{datadir}/doc/foo/doc.man
This part is intended for system administrators or downstream OS packagers.
The real paths of categories are registered in the sysconfig.cfg file installed in your python installation. This file uses an ini format too. The content of the file is organized into several sections:
Standard categories paths are platform independent, they generally refers to other categories, which are platform dependent. sysconfig will choose these category from sections matching os.name. For example:
doc = {datadir}/doc/{distribution.name}
It refers to datadir category, which can be different between platforms. In posix system, it may be:
datadir = /usr/share
So the final path will be:
doc = /usr/share/doc/{distribution.name}
The platform-dependent categories are:
These examples are incremental but work unitarily.
Source tree:
babar-1.0/
README
babar.sh
launch.sh
babar.py
setup.cfg:
[files]
resources =
README = {doc}
*.sh = {scripts}
So babar.sh and launch.sh will be placed in {scripts} directory.
Now let’s move all the scripts into a scripts directory.
Source tree:
babar-1.1/
README
scripts/
babar.sh
launch.sh
LAUNCH
babar.py
setup.cfg:
[files]
resources =
README = {doc}
scripts/ LAUNCH = {doc}
scripts/ *.sh = {scripts}
It’s important to use the separator after scripts/ to install all the shell scripts into {scripts} instead of {scripts}/scripts.
Now let’s add some docs.
Source tree:
babar-1.2/
README
scripts/
babar.sh
launch.sh
LAUNCH
docs/
api
man
babar.py
setup.cfg:
[files]
resources =
README = {doc}
scripts/ LAUNCH = {doc}
scripts/ *.sh = {scripts}
doc/ * = {doc}
doc/ man = {man}
You want to place all the file in the docs script into {doc} category, instead of man, which must be placed into {man} category, we will use the order of declaration of globs to choose the destination, the last glob that match the file is used.
Now let’s add some scripts for windows users.
Source tree:
babar-1.3/
README
doc/
api
man
scripts/
babar.sh
launch.sh
babar.bat
launch.bat
LAUNCH
setup.cfg:
[files]
resources =
README = {doc}
scripts/ LAUNCH = {doc}
scripts/ *.{sh,bat} = {scripts}
doc/ * = {doc}
doc/ man = {man}
We use brace expansion syntax to place all the shell and batch scripts into {scripts} category.
If a project includes extension modules written in C or C++, each one of them needs to have its options defined in a dedicated section. Here’s an example:
[files]
packages = coconut
[extension: coconut._fastcoconut]
language = cxx
sources = cxx_src/cononut_utils.cxx
cxx_src/python_module.cxx
include_dirs = /usr/include/gecode
/usr/include/blitz
extra_compile_args =
-fPIC -O2
-DGECODE_VERSION=$(./gecode_version) -- sys.platform != 'win32'
/DGECODE_VERSION=win32 -- sys.platform == 'win32'
The section name must start with extension:; the right-hand part is used as the full name (including a parent package, if any) of the extension. Whitespace around the extension name is allowed. If the extension module is not standalone (e.g. _bisect) but part of a package (e.g. thing._speedups), the parent package must be listed in the packages field. Valid fields and their values are listed in the documentation of the packaging.compiler.extension.Extension class; values documented as Python lists translate to multi-line values in the configuration file. In addition, multi-line values accept environment markers on each line, after a --.
To pass options to commands without having to type them on the command line for each invocation, you can write them in the setup.cfg file, in a section named after the command. Example:
[sdist]
# special function to add custom files
manifest-builders = package.setup.list_extra_files
[build]
use-2to3 = True
[build_ext]
inplace = on
[check]
strict = on
all = on
Option values given in the configuration file can be overriden on the command line. See Writing the Setup Configuration File for more information.
These sections are also used to define command hooks.
Every section can have fields that are not part of this specification. They are called extensions.
An extension field starts with X-. Example:
[metadata]
name = Distribute
X-Debian-Name = python-distribute
The versioning scheme for this specification is MAJOR.MINOR. Changes in the specification will cause the version number to be updated.
Changes to the minor number reflect backwards-compatible changes:
The major number will be incremented for backwards-incompatible changes:
As a consequence, a tool written to consume 1.5 has these properties:
A tool written to produce 1.x should have these properties:
This specification includes work and feedback from these people:
(If your name is missing, please let us know.)