distributions. The Distutils' own setup script, shown here, is used to install
the package into Python 1.5.2.) ::
- #!/usr/bin/env python
+ #!/usr/bin/env python
- from distutils.core import setup
+ from distutils.core import setup
- setup(name='Distutils',
- version='1.0',
- description='Python Distribution Utilities',
- author='Greg Ward',
- author_email='gward@python.net',
- url='http://www.python.org/sigs/distutils-sig/',
- packages=['distutils', 'distutils.command'],
- )
+ setup(name='Distutils',
+ version='1.0',
+ description='Python Distribution Utilities',
+ author='Greg Ward',
+ author_email='gward@python.net',
+ url='http://www.python.org/sigs/distutils-sig/',
+ packages=['distutils', 'distutils.command'],
+ )
There are only two differences between this and the trivial one-file
distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
:func:`os.listdir` to specify files, you should be careful to write portable
code instead of hardcoding path separators::
- glob.glob(os.path.join('mydir', 'subdir', '*.html'))
- os.listdir(os.path.join('mydir', 'subdir'))
+ glob.glob(os.path.join('mydir', 'subdir', '*.html'))
+ os.listdir(os.path.join('mydir', 'subdir'))
.. _listing-packages:
package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
:file:`lib/foo`, and so forth. Then you would put ::
- package_dir = {'': 'lib'}
+ package_dir = {'': 'lib'}
in your setup script. The keys to this dictionary are package names, and an
empty package name stands for the root package. The values are directory names
:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be
written in the setup script as ::
- package_dir = {'foo': 'lib'}
+ package_dir = {'foo': 'lib'}
A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
applies to all packages below *package*, so the :mod:`foo.bar` case is
"root package" (i.e., no package at all). This simplest case was shown in
section :ref:`distutils-simple-example`; here is a slightly more involved example::
- py_modules = ['mod1', 'pkg.mod2']
+ py_modules = ['mod1', 'pkg.mod2']
This describes two modules, one of them in the "root" package, the other in the
:mod:`pkg` package. Again, the default package/directory layout implies that
implemented by :file:`foo.c`. If no additional instructions to the
compiler/linker are needed, describing this extension is quite simple::
- Extension('foo', ['foo.c'])
+ Extension('foo', ['foo.c'])
The :class:`Extension` class can be imported from :mod:`distutils.core` along
with :func:`setup`. Thus, the setup script for a module distribution that
contains only this one extension and nothing else might be::
- from distutils.core import setup, Extension
- setup(name='foo',
- version='1.0',
- ext_modules=[Extension('foo', ['foo.c'])],
- )
+ from distutils.core import setup, Extension
+ setup(name='foo',
+ version='1.0',
+ ext_modules=[Extension('foo', ['foo.c'])],
+ )
The :class:`Extension` class (actually, the underlying extension-building
machinery implemented by the :command:`build_ext` command) supports a great deal
The first argument to the :class:`Extension` constructor is always the name of
the extension, including any package names. For example, ::
- Extension('foo', ['src/foo1.c', 'src/foo2.c'])
+ Extension('foo', ['src/foo1.c', 'src/foo2.c'])
describes an extension that lives in the root package, while ::
- Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
+ Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
describes the same extension in the :mod:`pkg` package. The source files and
resulting object code are identical in both cases; the only difference is where
same base package), use the :option:`ext_package` keyword argument to
:func:`setup`. For example, ::
- setup(...,
- ext_package='pkg',
- ext_modules=[Extension('foo', ['foo.c']),
- Extension('subpkg.bar', ['bar.c'])],
- )
+ setup(...,
+ ext_package='pkg',
+ ext_modules=[Extension('foo', ['foo.c']),
+ Extension('subpkg.bar', ['bar.c'])],
+ )
will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
:mod:`pkg.subpkg.bar`.
This warning notwithstanding, options to SWIG can be currently passed like
this::
- setup(...,
- ext_modules=[Extension('_foo', ['foo.i'],
- swig_opts=['-modern', '-I../include'])],
- py_modules=['foo'],
- )
+ setup(...,
+ ext_modules=[Extension('_foo', ['foo.i'],
+ swig_opts=['-modern', '-I../include'])],
+ py_modules=['foo'],
+ )
Or on the commandline like this::
- > python setup.py build_ext --swig-opts="-modern -I../include"
+ > python setup.py build_ext --swig-opts="-modern -I../include"
On some platforms, you can include non-source files that are processed by the
compiler and included in your extension. Currently, this just means Windows
For example, if your extension requires header files in the :file:`include`
directory under your distribution root, use the ``include_dirs`` option::
- Extension('foo', ['foo.c'], include_dirs=['include'])
+ Extension('foo', ['foo.c'], include_dirs=['include'])
You can specify absolute directories there; if you know that your extension will
only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
away with ::
- Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
+ Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
You should avoid this sort of non-portable usage if you plan to distribute your
code: it's probably better to write C code like ::
- #include <X11/Xlib.h>
+ #include <X11/Xlib.h>
If you need to include header files from some other Python extension, you can
take advantage of the fact that header files are installed in a consistent way
included in the search path when building Python extensions, the best approach
is to write C code like ::
- #include <Numerical/arrayobject.h>
+ #include <Numerical/arrayobject.h>
If you must put the :file:`Numerical` include directory right into your header
search path, though, you can find that directory using the Distutils
:mod:`distutils.sysconfig` module::
- from distutils.sysconfig import get_python_inc
- incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
- setup(...,
- Extension(..., include_dirs=[incdir]),
- )
+ from distutils.sysconfig import get_python_inc
+ incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
+ setup(...,
+ Extension(..., include_dirs=[incdir]),
+ )
Even though this is quite portable---it will work on any Python installation,
regardless of platform---it's probably easier to just write your C code in the
For example::
- Extension(...,
- define_macros=[('NDEBUG', '1'),
- ('HAVE_STRFTIME', None)],
- undef_macros=['HAVE_FOO', 'HAVE_BAR'])
+ Extension(...,
+ define_macros=[('NDEBUG', '1'),
+ ('HAVE_STRFTIME', None)],
+ undef_macros=['HAVE_FOO', 'HAVE_BAR'])
is the equivalent of having this at the top of every C source file::
- #define NDEBUG 1
- #define HAVE_STRFTIME
- #undef HAVE_FOO
- #undef HAVE_BAR
+ #define NDEBUG 1
+ #define HAVE_STRFTIME
+ #undef HAVE_FOO
+ #undef HAVE_BAR
Library options
For example, if you need to link against libraries known to be in the standard
library search path on target systems ::
- Extension(...,
- libraries=['_gdbm', 'readline'])
+ Extension(...,
+ libraries=['gdbm', 'readline'])
If you need to link with libraries in a non-standard location, you'll have to
include the location in ``library_dirs``::
- Extension(...,
- library_dirs=['/usr/X11R6/lib'],
- libraries=['X11', 'Xt'])
+ Extension(...,
+ library_dirs=['/usr/X11R6/lib'],
+ libraries=['X11', 'Xt'])
(Again, this sort of non-portable construct should be avoided if you intend to
distribute your code.)
parentheses. Each qualifier may consist of a comparison operator and a version
number. The accepted comparison operators are::
- < > ==
- <= >= !=
+ < > ==
+ <= >= !=
These can be combined by using multiple qualifiers separated by commas (and
optional whitespace). In this case, all of the qualifiers must be matched; a
The :option:`scripts` option simply is a list of files to be handled in this
way. From the PyXML setup script::
- setup(...,
- scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
- )
+ setup(...,
+ scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
+ )
.. versionchanged:: 2.7
- All the scripts will also be added to the ``MANIFEST``
- file if no template is provided. See :ref:`manifest`.
+ All the scripts will also be added to the ``MANIFEST``
+ file if no template is provided. See :ref:`manifest`.
.. _distutils-installing-package-data:
For example, if a package should contain a subdirectory with several data files,
the files can be arranged like this in the source tree::
- setup.py
- src/
- mypkg/
- __init__.py
- module.py
- data/
- tables.dat
- spoons.dat
- forks.dat
+ setup.py
+ src/
+ mypkg/
+ __init__.py
+ module.py
+ data/
+ tables.dat
+ spoons.dat
+ forks.dat
The corresponding call to :func:`setup` might be::
- setup(...,
- packages=['mypkg'],
- package_dir={'mypkg': 'src/mypkg'},
- package_data={'mypkg': ['data/*.dat']},
- )
+ setup(...,
+ packages=['mypkg'],
+ package_dir={'mypkg': 'src/mypkg'},
+ package_data={'mypkg': ['data/*.dat']},
+ )
.. versionchanged:: 2.7
- All the files that match ``package_data`` will be added to the ``MANIFEST``
- file if no template is provided. See :ref:`manifest`.
+ All the files that match ``package_data`` will be added to the ``MANIFEST``
+ file if no template is provided. See :ref:`manifest`.
.. _distutils-additional-files:
:option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the
following way::
- setup(...,
- data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
- ('config', ['cfg/data.cfg']),
- ('/etc/init.d', ['init-script'])]
- )
+ setup(...,
+ data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
+ ('config', ['cfg/data.cfg']),
+ ('/etc/init.d', ['init-script'])]
+ )
Note that you can specify the directory names where the data files will be
installed, but you cannot rename the data files themselves.
directory.
.. versionchanged:: 2.7
- All the files that match ``data_files`` will be added to the ``MANIFEST``
- file if no template is provided. See :ref:`manifest`.
+ All the files that match ``data_files`` will be added to the ``MANIFEST``
+ file if no template is provided. See :ref:`manifest`.
| | description of the | | |
| | package | | |
+----------------------+---------------------------+-----------------+--------+
-| ``long_description`` | longer description of the | long string | |
+| ``long_description`` | longer description of the | long string | \(5) |
| | package | | |
+----------------------+---------------------------+-----------------+--------+
| ``download_url`` | location where the | URL | \(4) |
Notes:
(1)
- These fields are required.
+ These fields are required.
(2)
- It is recommended that versions take the form *major.minor[.patch[.sub]]*.
+ It is recommended that versions take the form *major.minor[.patch[.sub]]*.
(3)
- Either the author or the maintainer must be identified.
+ Either the author or the maintainer must be identified.
(4)
- These fields should not be used if your package is to be compatible with Python
- versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website
- <http://pypi.python.org/pypi>`_.
+ These fields should not be used if your package is to be compatible with Python
+ versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website
+ <http://pypi.python.org/pypi>`_.
+
+(5)
+ The ``long_description`` field is used by PyPI when you are registering a
+ package, to build its home page.
'short string'
- A single line of text, not more than 200 characters.
+ A single line of text, not more than 200 characters.
'long string'
- Multiple lines of plain text in reStructuredText format (see
- http://docutils.sf.net/).
+ Multiple lines of plain text in reStructuredText format (see
+ http://docutils.sf.net/).
'list of strings'
- See below.
+ See below.
Encoding the version information is an art in itself. Python packages generally
adhere to the version format *major.minor[.patch][sub]*. The major number is 0
(for final pre-release release testing). Some examples:
0.1.0
- the first, experimental release of a package
+ the first, experimental release of a package
1.0.1a2
- the second alpha release of the first patch version of 1.0
+ the second alpha release of the first patch version of 1.0
:option:`classifiers` are specified in a python list::
- setup(...,
- classifiers=[
- 'Development Status :: 4 - Beta',
- 'Environment :: Console',
- 'Environment :: Web Environment',
- 'Intended Audience :: End Users/Desktop',
- 'Intended Audience :: Developers',
- 'Intended Audience :: System Administrators',
- 'License :: OSI Approved :: Python Software Foundation License',
- 'Operating System :: MacOS :: MacOS X',
- 'Operating System :: Microsoft :: Windows',
- 'Operating System :: POSIX',
- 'Programming Language :: Python',
- 'Topic :: Communications :: Email',
- 'Topic :: Office/Business',
- 'Topic :: Software Development :: Bug Tracking',
- ],
- )
+ setup(...,
+ classifiers=[
+ 'Development Status :: 4 - Beta',
+ 'Environment :: Console',
+ 'Environment :: Web Environment',
+ 'Intended Audience :: End Users/Desktop',
+ 'Intended Audience :: Developers',
+ 'Intended Audience :: System Administrators',
+ 'License :: OSI Approved :: Python Software Foundation License',
+ 'Operating System :: MacOS :: MacOS X',
+ 'Operating System :: Microsoft :: Windows',
+ 'Operating System :: POSIX',
+ 'Programming Language :: Python',
+ 'Topic :: Communications :: Email',
+ 'Topic :: Office/Business',
+ 'Topic :: Software Development :: Bug Tracking',
+ ],
+ )
If you wish to include classifiers in your :file:`setup.py` file and also wish
to remain backwards-compatible with Python releases prior to 2.2.3, then you can
include the following code fragment in your :file:`setup.py` before the
:func:`setup` call. ::
- # patch distutils if it can't cope with the "classifiers" or
- # "download_url" keywords
- from sys import version
- if version < '2.2.3':
- from distutils.dist import DistributionMetadata
- DistributionMetadata.classifiers = None
- DistributionMetadata.download_url = None
+ # patch distutils if it can't cope with the "classifiers" or
+ # "download_url" keywords
+ from sys import version
+ if version < '2.2.3':
+ from distutils.dist import DistributionMetadata
+ DistributionMetadata.classifiers = None
+ DistributionMetadata.download_url = None
Debugging the setup script
to anything except an empty string, and distutils will now print detailed
information what it is doing, and prints the full traceback in case an exception
occurs.
-
-
projects / python / commitdiff