1 .. _setup-script:

     2 

     3 ************************

     4 Writing the Setup Script

     5 ************************

     6 

     7 The setup script is the centre of all activity in building, distributing, and

     8 installing modules using the Distutils.  The main purpose of the setup script is

     9 to describe your module distribution to the Distutils, so that the various

    10 commands that operate on your modules do the right thing.  As we saw in section

    11 :ref:`distutils-simple-example` above, the setup script consists mainly of a call to

    12 :func:`setup`, and most information supplied to the Distutils by the module

    13 developer is supplied as keyword arguments to :func:`setup`.

    14 

    15 Here's a slightly more involved example, which we'll follow for the next couple

    16 of sections: the Distutils' own setup script.  (Keep in mind that although the

    17 Distutils are included with Python 1.6 and later, they also have an independent

    18 existence so that Python 1.5.2 users can use them to install other module

    19 distributions.  The Distutils' own setup script, shown here, is used to install

    20 the package into Python 1.5.2.) ::

    21 

    22    #!/usr/bin/env python

    23 

    24    from distutils.core import setup

    25 

    26    setup(name='Distutils',

    27          version='1.0',

    28          description='Python Distribution Utilities',

    29          author='Greg Ward',

    30          author_email='gward@python.net',

    31          url='http://www.python.org/sigs/distutils-sig/',

    32          packages=['distutils', 'distutils.command'],

    33         )

    34 

    35 There are only two differences between this and the trivial one-file

    36 distribution presented in section :ref:`distutils-simple-example`: more metadata, and the

    37 specification of pure Python modules by package, rather than by module.  This is

    38 important since the Distutils consist of a couple of dozen modules split into

    39 (so far) two packages; an explicit list of every module would be tedious to

    40 generate and difficult to maintain.  For more information on the additional

    41 meta-data, see section :ref:`meta-data`.

    42 

    43 Note that any pathnames (files or directories) supplied in the setup script

    44 should be written using the Unix convention, i.e. slash-separated.  The

    45 Distutils will take care of converting this platform-neutral representation into

    46 whatever is appropriate on your current platform before actually using the

    47 pathname.  This makes your setup script portable across operating systems, which

    48 of course is one of the major goals of the Distutils.  In this spirit, all

    49 pathnames in this document are slash-separated.

    50 

    51 This, of course, only applies to pathnames given to Distutils functions.  If

    52 you, for example, use standard Python functions such as :func:`glob.glob` or

    53 :func:`os.listdir` to specify files, you should be careful to write portable

    54 code instead of hardcoding path separators::

    55 

    56    glob.glob(os.path.join('mydir', 'subdir', '*.html'))

    57    os.listdir(os.path.join('mydir', 'subdir'))

    58 

    59 

    60 .. _listing-packages:

    61 

    62 Listing whole packages

    63 ======================

    64 

    65 The :option:`packages` option tells the Distutils to process (build, distribute,

    66 install, etc.) all pure Python modules found in each package mentioned in the

    67 :option:`packages` list.  In order to do this, of course, there has to be a

    68 correspondence between package names and directories in the filesystem.  The

    69 default correspondence is the most obvious one, i.e. package :mod:`distutils` is

    70 found in the directory :file:`distutils` relative to the distribution root.

    71 Thus, when you say ``packages = ['foo']`` in your setup script, you are

    72 promising that the Distutils will find a file :file:`foo/__init__.py` (which

    73 might be spelled differently on your system, but you get the idea) relative to

    74 the directory where your setup script lives.  If you break this promise, the

    75 Distutils will issue a warning but still process the broken package anyways.

    76 

    77 If you use a different convention to lay out your source directory, that's no

    78 problem: you just have to supply the :option:`package_dir` option to tell the

    79 Distutils about your convention.  For example, say you keep all Python source

    80 under :file:`lib`, so that modules in the "root package" (i.e., not in any

    81 package at all) are in :file:`lib`, modules in the :mod:`foo` package are in

    82 :file:`lib/foo`, and so forth.  Then you would put ::

    83 

    84    package_dir = {'': 'lib'}

    85 

    86 in your setup script.  The keys to this dictionary are package names, and an

    87 empty package name stands for the root package.  The values are directory names

    88 relative to your distribution root.  In this case, when you say ``packages =

    89 ['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.

    90 

    91 Another possible convention is to put the :mod:`foo` package right in

    92 :file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc.  This would be

    93 written in the setup script as ::

    94 

    95    package_dir = {'foo': 'lib'}

    96 

    97 A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly

    98 applies to all packages below *package*, so the :mod:`foo.bar` case is

    99 automatically handled here.  In this example, having ``packages = ['foo',

   100 'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and

   101 :file:`lib/bar/__init__.py`.  (Keep in mind that although :option:`package_dir`

   102 applies recursively, you must explicitly list all packages in

   103 :option:`packages`: the Distutils will *not* recursively scan your source tree

   104 looking for any directory with an :file:`__init__.py` file.)

   105 

   106 

   107 .. _listing-modules:

   108 

   109 Listing individual modules

   110 ==========================

   111 

   112 For a small module distribution, you might prefer to list all modules rather

   113 than listing packages---especially the case of a single module that goes in the

   114 "root package" (i.e., no package at all).  This simplest case was shown in

   115 section :ref:`distutils-simple-example`; here is a slightly more involved example::

   116 

   117    py_modules = ['mod1', 'pkg.mod2']

   118 

   119 This describes two modules, one of them in the "root" package, the other in the

   120 :mod:`pkg` package.  Again, the default package/directory layout implies that

   121 these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and

   122 that :file:`pkg/__init__.py` exists as well. And again, you can override the

   123 package/directory correspondence using the :option:`package_dir` option.

   124 

   125 

   126 .. _describing-extensions:

   127 

   128 Describing extension modules

   129 ============================

   130 

   131 Just as writing Python extension modules is a bit more complicated than writing

   132 pure Python modules, describing them to the Distutils is a bit more complicated.

   133 Unlike pure modules, it's not enough just to list modules or packages and expect

   134 the Distutils to go out and find the right files; you have to specify the

   135 extension name, source file(s), and any compile/link requirements (include

   136 directories, libraries to link with, etc.).

   137 

   138 .. XXX read over this section

   139 

   140 All of this is done through another keyword argument to :func:`setup`, the

   141 :option:`ext_modules` option.  :option:`ext_modules` is just a list of

   142 :class:`Extension` instances, each of which describes a single extension module.

   143 Suppose your distribution includes a single extension, called :mod:`foo` and

   144 implemented by :file:`foo.c`.  If no additional instructions to the

   145 compiler/linker are needed, describing this extension is quite simple::

   146 

   147    Extension('foo', ['foo.c'])

   148 

   149 The :class:`Extension` class can be imported from :mod:`distutils.core` along

   150 with :func:`setup`.  Thus, the setup script for a module distribution that

   151 contains only this one extension and nothing else might be::

   152 

   153    from distutils.core import setup, Extension

   154    setup(name='foo',

   155          version='1.0',

   156          ext_modules=[Extension('foo', ['foo.c'])],

   157          )

   158 

   159 The :class:`Extension` class (actually, the underlying extension-building

   160 machinery implemented by the :command:`build_ext` command) supports a great deal

   161 of flexibility in describing Python extensions, which is explained in the

   162 following sections.

   163 

   164 

   165 Extension names and packages

   166 ----------------------------

   167 

   168 The first argument to the :class:`Extension` constructor is always the name of

   169 the extension, including any package names.  For example, ::

   170 

   171    Extension('foo', ['src/foo1.c', 'src/foo2.c'])

   172 

   173 describes an extension that lives in the root package, while ::

   174 

   175    Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])

   176 

   177 describes the same extension in the :mod:`pkg` package.  The source files and

   178 resulting object code are identical in both cases; the only difference is where

   179 in the filesystem (and therefore where in Python's namespace hierarchy) the

   180 resulting extension lives.

   181 

   182 If you have a number of extensions all in the same package (or all under the

   183 same base package), use the :option:`ext_package` keyword argument to

   184 :func:`setup`.  For example, ::

   185 

   186    setup(...,

   187          ext_package='pkg',

   188          ext_modules=[Extension('foo', ['foo.c']),

   189                       Extension('subpkg.bar', ['bar.c'])],

   190         )

   191 

   192 will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to

   193 :mod:`pkg.subpkg.bar`.

   194 

   195 

   196 Extension source files

   197 ----------------------

   198 

   199 The second argument to the :class:`Extension` constructor is a list of source

   200 files.  Since the Distutils currently only support C, C++, and Objective-C

   201 extensions, these are normally C/C++/Objective-C source files.  (Be sure to use

   202 appropriate extensions to distinguish C++\ source files: :file:`.cc` and

   203 :file:`.cpp` seem to be recognized by both Unix and Windows compilers.)

   204 

   205 However, you can also include SWIG interface (:file:`.i`) files in the list; the

   206 :command:`build_ext` command knows how to deal with SWIG extensions: it will run

   207 SWIG on the interface file and compile the resulting C/C++ file into your

   208 extension.

   209 

   210 **\*\*** SWIG support is rough around the edges and largely untested! **\*\***

   211 

   212 This warning notwithstanding, options to SWIG can be currently passed like

   213 this::

   214 

   215    setup(...,

   216          ext_modules=[Extension('_foo', ['foo.i'], 

   217                                 swig_opts=['-modern', '-I../include'])],

   218          py_modules=['foo'],

   219         )

   220 

   221 Or on the commandline like this::

   222 

   223    > python setup.py build_ext --swig-opts="-modern -I../include"

   224 

   225 On some platforms, you can include non-source files that are processed by the

   226 compiler and included in your extension.  Currently, this just means Windows

   227 message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for

   228 Visual C++. These will be compiled to binary resource (:file:`.res`) files and

   229 linked into the executable.

   230 

   231 

   232 Preprocessor options

   233 --------------------

   234 

   235 Three optional arguments to :class:`Extension` will help if you need to specify

   236 include directories to search or preprocessor macros to define/undefine:

   237 ``include_dirs``, ``define_macros``, and ``undef_macros``.

   238 

   239 For example, if your extension requires header files in the :file:`include`

   240 directory under your distribution root, use the ``include_dirs`` option::

   241 

   242    Extension('foo', ['foo.c'], include_dirs=['include'])

   243 

   244 You can specify absolute directories there; if you know that your extension will

   245 only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get

   246 away with ::

   247 

   248    Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])

   249 

   250 You should avoid this sort of non-portable usage if you plan to distribute your

   251 code: it's probably better to write C code like  ::

   252 

   253    #include <X11/Xlib.h>

   254 

   255 If you need to include header files from some other Python extension, you can

   256 take advantage of the fact that header files are installed in a consistent way

   257 by the Distutils :command:`install_header` command.  For example, the Numerical

   258 Python header files are installed (on a standard Unix installation) to

   259 :file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ

   260 according to your platform and Python installation.)  Since the Python include

   261 directory---\ :file:`/usr/local/include/python1.5` in this case---is always

   262 included in the search path when building Python extensions, the best approach

   263 is to write C code like  ::

   264 

   265    #include <Numerical/arrayobject.h>

   266 

   267 If you must put the :file:`Numerical` include directory right into your header

   268 search path, though, you can find that directory using the Distutils

   269 :mod:`distutils.sysconfig` module::

   270 

   271    from distutils.sysconfig import get_python_inc

   272    incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')

   273    setup(...,

   274          Extension(..., include_dirs=[incdir]),

   275          )

   276 

   277 Even though this is quite portable---it will work on any Python installation,

   278 regardless of platform---it's probably easier to just write your C code in the

   279 sensible way.

   280 

   281 You can define and undefine pre-processor macros with the ``define_macros`` and

   282 ``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``

   283 tuples, where ``name`` is the name of the macro to define (a string) and

   284 ``value`` is its value: either a string or ``None``.  (Defining a macro ``FOO``

   285 to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with

   286 most compilers, this sets ``FOO`` to the string ``1``.)  ``undef_macros`` is

   287 just a list of macros to undefine.

   288 

   289 For example::

   290 

   291    Extension(...,

   292              define_macros=[('NDEBUG', '1'),

   293                             ('HAVE_STRFTIME', None)],

   294              undef_macros=['HAVE_FOO', 'HAVE_BAR'])

   295 

   296 is the equivalent of having this at the top of every C source file::

   297 

   298    #define NDEBUG 1

   299    #define HAVE_STRFTIME

   300    #undef HAVE_FOO

   301    #undef HAVE_BAR

   302 

   303 

   304 Library options

   305 ---------------

   306 

   307 You can also specify the libraries to link against when building your extension,

   308 and the directories to search for those libraries.  The ``libraries`` option is

   309 a list of libraries to link against, ``library_dirs`` is a list of directories

   310 to search for libraries at  link-time, and ``runtime_library_dirs`` is a list of

   311 directories to  search for shared (dynamically loaded) libraries at run-time.

   312 

   313 For example, if you need to link against libraries known to be in the standard

   314 library search path on target systems ::

   315 

   316    Extension(...,

   317              libraries=['gdbm', 'readline'])

   318 

   319 If you need to link with libraries in a non-standard location, you'll have to

   320 include the location in ``library_dirs``::

   321 

   322    Extension(...,

   323              library_dirs=['/usr/X11R6/lib'],

   324              libraries=['X11', 'Xt'])

   325 

   326 (Again, this sort of non-portable construct should be avoided if you intend to

   327 distribute your code.)

   328 

   329 **\*\*** Should mention clib libraries here or somewhere else! **\*\***

   330 

   331 

   332 Other options

   333 -------------

   334 

   335 There are still some other options which can be used to handle special cases.

   336 

   337 The :option:`extra_objects` option is a list of object files to be passed to the

   338 linker. These files must not have extensions, as the default extension for the

   339 compiler is used.

   340 

   341 :option:`extra_compile_args` and :option:`extra_link_args` can be used to

   342 specify additional command line options for the respective compiler and linker

   343 command lines.

   344 

   345 :option:`export_symbols` is only useful on Windows.  It can contain a list of

   346 symbols (functions or variables) to be exported. This option is not needed when

   347 building compiled extensions: Distutils  will automatically add ``initmodule``

   348 to the list of exported symbols.

   349 

   350 

   351 Relationships between Distributions and Packages

   352 ================================================

   353 

   354 A distribution may relate to packages in three specific ways:

   355 

   356 #. It can require packages or modules.

   357 

   358 #. It can provide packages or modules.

   359 

   360 #. It can obsolete packages or modules.

   361 

   362 These relationships can be specified using keyword arguments to the

   363 :func:`distutils.core.setup` function.

   364 

   365 Dependencies on other Python modules and packages can be specified by supplying

   366 the *requires* keyword argument to :func:`setup`. The value must be a list of

   367 strings.  Each string specifies a package that is required, and optionally what

   368 versions are sufficient.

   369 

   370 To specify that any version of a module or package is required, the string

   371 should consist entirely of the module or package name. Examples include

   372 ``'mymodule'`` and ``'xml.parsers.expat'``.

   373 

   374 If specific versions are required, a sequence of qualifiers can be supplied in

   375 parentheses.  Each qualifier may consist of a comparison operator and a version

   376 number.  The accepted comparison operators are::

   377 

   378    <    >    ==

   379    <=   >=   !=

   380 

   381 These can be combined by using multiple qualifiers separated by commas (and

   382 optional whitespace).  In this case, all of the qualifiers must be matched; a

   383 logical AND is used to combine the evaluations.

   384 

   385 Let's look at a bunch of examples:

   386 

   387 +-------------------------+----------------------------------------------+

   388 | Requires Expression     | Explanation                                  |

   389 +=========================+==============================================+

   390 | ``==1.0``               | Only version ``1.0`` is compatible           |

   391 +-------------------------+----------------------------------------------+

   392 | ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |

   393 |                         | is compatible, except ``1.5.1``              |

   394 +-------------------------+----------------------------------------------+

   395 

   396 Now that we can specify dependencies, we also need to be able to specify what we

   397 provide that other distributions can require.  This is done using the *provides*

   398 keyword argument to :func:`setup`. The value for this keyword is a list of

   399 strings, each of which names a Python module or package, and optionally

   400 identifies the version.  If the version is not specified, it is assumed to match

   401 that of the distribution.

   402 

   403 Some examples:

   404 

   405 +---------------------+----------------------------------------------+

   406 | Provides Expression | Explanation                                  |

   407 +=====================+==============================================+

   408 | ``mypkg``           | Provide ``mypkg``, using the distribution    |

   409 |                     | version                                      |

   410 +---------------------+----------------------------------------------+

   411 | ``mypkg (1.1)``     | Provide ``mypkg`` version 1.1, regardless of |

   412 |                     | the distribution version                     |

   413 +---------------------+----------------------------------------------+

   414 

   415 A package can declare that it obsoletes other packages using the *obsoletes*

   416 keyword argument.  The value for this is similar to that of the *requires*

   417 keyword: a list of strings giving module or package specifiers.  Each specifier

   418 consists of a module or package name optionally followed by one or more version

   419 qualifiers.  Version qualifiers are given in parentheses after the module or

   420 package name.

   421 

   422 The versions identified by the qualifiers are those that are obsoleted by the

   423 distribution being described.  If no qualifiers are given, all versions of the

   424 named module or package are understood to be obsoleted.

   425 

   426 

   427 Installing Scripts

   428 ==================

   429 

   430 So far we have been dealing with pure and non-pure Python modules, which are

   431 usually not run by themselves but imported by scripts.

   432 

   433 Scripts are files containing Python source code, intended to be started from the

   434 command line.  Scripts don't require Distutils to do anything very complicated.

   435 The only clever feature is that if the first line of the script starts with

   436 ``#!`` and contains the word "python", the Distutils will adjust the first line

   437 to refer to the current interpreter location. By default, it is replaced with

   438 the current interpreter location.  The :option:`--executable` (or :option:`-e`)

   439 option will allow the interpreter path to be explicitly overridden.

   440 

   441 The :option:`scripts` option simply is a list of files to be handled in this

   442 way.  From the PyXML setup script::

   443 

   444    setup(...,

   445          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']

   446          )

   447 

   448 

   449 Installing Package Data

   450 =======================

   451 

   452 Often, additional files need to be installed into a package.  These files are

   453 often data that's closely related to the package's implementation, or text files

   454 containing documentation that might be of interest to programmers using the

   455 package.  These files are called :dfn:`package data`.

   456 

   457 Package data can be added to packages using the ``package_data`` keyword

   458 argument to the :func:`setup` function.  The value must be a mapping from

   459 package name to a list of relative path names that should be copied into the

   460 package.  The paths are interpreted as relative to the directory containing the

   461 package (information from the ``package_dir`` mapping is used if appropriate);

   462 that is, the files are expected to be part of the package in the source

   463 directories. They may contain glob patterns as well.

   464 

   465 The path names may contain directory portions; any necessary directories will be

   466 created in the installation.

   467 

   468 For example, if a package should contain a subdirectory with several data files,

   469 the files can be arranged like this in the source tree::

   470 

   471    setup.py

   472    src/

   473        mypkg/

   474            __init__.py

   475            module.py

   476            data/

   477                tables.dat

   478                spoons.dat

   479                forks.dat

   480 

   481 The corresponding call to :func:`setup` might be::

   482 

   483    setup(...,

   484          packages=['mypkg'],

   485          package_dir={'mypkg': 'src/mypkg'},

   486          package_data={'mypkg': ['data/*.dat']},

   487          )

   488 

   489 .. versionadded:: 2.4

   490 

   491 

   492 Installing Additional Files

   493 ===========================

   494 

   495 The :option:`data_files` option can be used to specify additional files needed

   496 by the module distribution: configuration files, message catalogs, data files,

   497 anything which doesn't fit in the previous categories.

   498 

   499 :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the

   500 following way::

   501 

   502    setup(...,

   503          data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),

   504                      ('config', ['cfg/data.cfg']),

   505                      ('/etc/init.d', ['init-script'])]

   506         )

   507 

   508 Note that you can specify the directory names where the data files will be

   509 installed, but you cannot rename the data files themselves.

   510 

   511 Each (*directory*, *files*) pair in the sequence specifies the installation

   512 directory and the files to install there.  If *directory* is a relative path, it

   513 is interpreted relative to the installation prefix (Python's ``sys.prefix`` for

   514 pure-Python packages, ``sys.exec_prefix`` for packages that contain extension

   515 modules).  Each file name in *files* is interpreted relative to the

   516 :file:`setup.py` script at the top of the package source distribution.  No

   517 directory information from *files* is used to determine the final location of

   518 the installed file; only the name of the file is used.

   519 

   520 You can specify the :option:`data_files` options as a simple sequence of files

   521 without specifying a target directory, but this is not recommended, and the

   522 :command:`install` command will print a warning in this case. To install data

   523 files directly in the target directory, an empty string should be given as the

   524 directory.

   525 

   526 

   527 .. _meta-data:

   528 

   529 Additional meta-data

   530 ====================

   531 

   532 The setup script may include additional meta-data beyond the name and version.

   533 This information includes:

   534 

   535 +----------------------+---------------------------+-----------------+--------+

   536 | Meta-Data            | Description               | Value           | Notes  |

   537 +======================+===========================+=================+========+

   538 | ``name``             | name of the package       | short string    | \(1)   |

   539 +----------------------+---------------------------+-----------------+--------+

   540 | ``version``          | version of this release   | short string    | (1)(2) |

   541 +----------------------+---------------------------+-----------------+--------+

   542 | ``author``           | package author's name     | short string    | \(3)   |

   543 +----------------------+---------------------------+-----------------+--------+

   544 | ``author_email``     | email address of the      | email address   | \(3)   |

   545 |                      | package author            |                 |        |

   546 +----------------------+---------------------------+-----------------+--------+

   547 | ``maintainer``       | package maintainer's name | short string    | \(3)   |

   548 +----------------------+---------------------------+-----------------+--------+

   549 | ``maintainer_email`` | email address of the      | email address   | \(3)   |

   550 |                      | package maintainer        |                 |        |

   551 +----------------------+---------------------------+-----------------+--------+

   552 | ``url``              | home page for the package | URL             | \(1)   |

   553 +----------------------+---------------------------+-----------------+--------+

   554 | ``description``      | short, summary            | short string    |        |

   555 |                      | description of the        |                 |        |

   556 |                      | package                   |                 |        |

   557 +----------------------+---------------------------+-----------------+--------+

   558 | ``long_description`` | longer description of the | long string     |        |

   559 |                      | package                   |                 |        |

   560 +----------------------+---------------------------+-----------------+--------+

   561 | ``download_url``     | location where the        | URL             | \(4)   |

   562 |                      | package may be downloaded |                 |        |

   563 +----------------------+---------------------------+-----------------+--------+

   564 | ``classifiers``      | a list of classifiers     | list of strings | \(4)   |

   565 +----------------------+---------------------------+-----------------+--------+

   566 

   567 Notes:

   568 

   569 (1)

   570    These fields are required.

   571 

   572 (2)

   573    It is recommended that versions take the form *major.minor[.patch[.sub]]*.

   574 

   575 (3)

   576    Either the author or the maintainer must be identified.

   577 

   578 (4)

   579    These fields should not be used if your package is to be compatible with Python

   580    versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website

   581    <http://pypi.python.org/pypi>`_.

   582 

   583 'short string'

   584    A single line of text, not more than 200 characters.

   585 

   586 'long string'

   587    Multiple lines of plain text in reStructuredText format (see

   588    http://docutils.sf.net/).

   589 

   590 'list of strings'

   591    See below.

   592 

   593 None of the string values may be Unicode.

   594 

   595 Encoding the version information is an art in itself. Python packages generally

   596 adhere to the version format *major.minor[.patch][sub]*. The major number is 0

   597 for initial, experimental releases of software. It is incremented for releases

   598 that represent major milestones in a package. The minor number is incremented

   599 when important new features are added to the package. The patch number

   600 increments when bug-fix releases are made. Additional trailing version

   601 information is sometimes used to indicate sub-releases.  These are

   602 "a1,a2,...,aN" (for alpha releases, where functionality and API may change),

   603 "b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"

   604 (for final pre-release release testing). Some examples:

   605 

   606 0.1.0

   607    the first, experimental release of a package

   608 

   609 1.0.1a2

   610    the second alpha release of the first patch version of 1.0

   611 

   612 :option:`classifiers` are specified in a python list::

   613 

   614    setup(...,

   615          classifiers=[

   616              'Development Status :: 4 - Beta',

   617              'Environment :: Console',

   618              'Environment :: Web Environment',

   619              'Intended Audience :: End Users/Desktop',

   620              'Intended Audience :: Developers',

   621              'Intended Audience :: System Administrators',

   622              'License :: OSI Approved :: Python Software Foundation License',

   623              'Operating System :: MacOS :: MacOS X',

   624              'Operating System :: Microsoft :: Windows',

   625              'Operating System :: POSIX',

   626              'Programming Language :: Python',

   627              'Topic :: Communications :: Email',

   628              'Topic :: Office/Business',

   629              'Topic :: Software Development :: Bug Tracking',

   630              ],

   631          )

   632 

   633 If you wish to include classifiers in your :file:`setup.py` file and also wish

   634 to remain backwards-compatible with Python releases prior to 2.2.3, then you can

   635 include the following code fragment in your :file:`setup.py` before the

   636 :func:`setup` call. ::

   637 

   638    # patch distutils if it can't cope with the "classifiers" or

   639    # "download_url" keywords

   640    from sys import version

   641    if version < '2.2.3':

   642        from distutils.dist import DistributionMetadata

   643        DistributionMetadata.classifiers = None

   644        DistributionMetadata.download_url = None

   645 

   646 

   647 Debugging the setup script

   648 ==========================

   649 

   650 Sometimes things go wrong, and the setup script doesn't do what the developer

   651 wants.

   652 

   653 Distutils catches any exceptions when running the setup script, and print a

   654 simple error message before the script is terminated.  The motivation for this

   655 behaviour is to not confuse administrators who don't know much about Python and

   656 are trying to install a package.  If they get a big long traceback from deep

   657 inside the guts of Distutils, they may think the package or the Python

   658 installation is broken because they don't read all the way down to the bottom

   659 and see that it's a permission problem.

   660 

   661 On the other hand, this doesn't help the developer to find the cause of the

   662 failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set

   663 to anything except an empty string, and distutils will now print detailed

   664 information what it is doing, and prints the full traceback in case an exception

   665 occurs.

   666 

   667