Ticket #6262: setuptools.txt

File setuptools.txt, 145.3 KB (added by nielx, 9 years ago)

Test

Line 
1======================================================
2Building and Distributing Packages with ``setuptools``
3======================================================
4
5``setuptools`` is a collection of enhancements to the Python ``distutils``
6(for Python 2.3.5 and up on most platforms; 64-bit platforms require a minimum
7of Python 2.4) that allow you to more easily build and distribute Python
8packages, especially ones that have dependencies on other packages.
9
10Packages built and distributed using ``setuptools`` look to the user like
11ordinary Python packages based on the ``distutils``. Your users don't need to
12install or even know about setuptools in order to use them, and you don't
13have to include the entire setuptools package in your distributions. By
14including just a single `bootstrap module`_ (an 8K .py file), your package will
15automatically download and install ``setuptools`` if the user is building your
16package from source and doesn't have a suitable version already installed.
17
18.. _bootstrap module: http://peak.telecommunity.com/dist/ez_setup.py
19
20Feature Highlights:
21
22* Automatically find/download/install/upgrade dependencies at build time using
23 the `EasyInstall tool <http://peak.telecommunity.com/DevCenter/EasyInstall>`_,
24 which supports downloading via HTTP, FTP, Subversion, and SourceForge, and
25 automatically scans web pages linked from PyPI to find download links. (It's
26 the closest thing to CPAN currently available for Python.)
27
28* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
29 a single-file importable distribution format
30
31* Include data files inside your package directories, where your code can
32 actually use them. (Python 2.4 distutils also supports this feature, but
33 setuptools provides the feature for Python 2.3 packages also, and supports
34 accessing data files in zipped packages too.)
35
36* Automatically include all packages in your source tree, without listing them
37 individually in setup.py
38
39* Automatically include all relevant files in your source distributions,
40 without needing to create a ``MANIFEST.in`` file, and without having to force
41 regeneration of the ``MANIFEST`` file when your source tree changes.
42
43* Automatically generate wrapper scripts or Windows (console and GUI) .exe
44 files for any number of "main" functions in your project. (Note: this is not
45 a py2exe replacement; the .exe files rely on the local Python installation.)
46
47* Transparent Pyrex support, so that your setup.py can list ``.pyx`` files and
48 still work even when the end-user doesn't have Pyrex installed (as long as
49 you include the Pyrex-generated C in your source distribution)
50
51* Command aliases - create project-specific, per-user, or site-wide shortcut
52 names for commonly used commands and options
53
54* PyPI upload support - upload your source distributions and eggs to PyPI
55
56* Deploy your project in "development mode", such that it's available on
57 ``sys.path``, yet can still be edited directly from its source checkout.
58
59* Easily extend the distutils with new commands or ``setup()`` arguments, and
60 distribute/reuse your extensions for multiple projects, without copying code.
61
62* Create extensible applications and frameworks that automatically discover
63 extensions, using simple "entry points" declared in a project's setup script.
64
65In addition to the PyPI downloads, the development version of ``setuptools``
66is available from the `Python SVN sandbox`_, and in-development versions of the
67`0.6 branch`_ are available as well.
68
69.. _0.6 branch: http://svn.python.org/projects/sandbox/branches/setuptools-0.6/#egg=setuptools-dev06
70
71.. _Python SVN sandbox: http://svn.python.org/projects/sandbox/trunk/setuptools/#egg=setuptools-dev
72
73.. contents:: **Table of Contents**
74
75.. _ez_setup.py: `bootstrap module`_
76
77
78-----------------
79Developer's Guide
80-----------------
81
82
83Installing ``setuptools``
84=========================
85
86Please follow the `EasyInstall Installation Instructions`_ to install the
87current stable version of setuptools. In particular, be sure to read the
88section on `Custom Installation Locations`_ if you are installing anywhere
89other than Python's ``site-packages`` directory.
90
91.. _EasyInstall Installation Instructions: http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
92
93.. _Custom Installation Locations: http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations
94
95If you want the current in-development version of setuptools, you should first
96install a stable version, and then run::
97
98 ez_setup.py setuptools==dev
99
100This will download and install the latest development (i.e. unstable) version
101of setuptools from the Python Subversion sandbox.
102
103
104Basic Use
105=========
106
107For basic use of setuptools, just import things from setuptools instead of
108the distutils. Here's a minimal setup script using setuptools::
109
110 from setuptools import setup, find_packages
111 setup(
112 name = "HelloWorld",
113 version = "0.1",
114 packages = find_packages(),
115 )
116
117As you can see, it doesn't take much to use setuptools in a project.
118Just by doing the above, this project will be able to produce eggs, upload to
119PyPI, and automatically include all packages in the directory where the
120setup.py lives. See the `Command Reference`_ section below to see what
121commands you can give to this setup script.
122
123Of course, before you release your project to PyPI, you'll want to add a bit
124more information to your setup script to help people find or learn about your
125project. And maybe your project will have grown by then to include a few
126dependencies, and perhaps some data files and scripts::
127
128 from setuptools import setup, find_packages
129 setup(
130 name = "HelloWorld",
131 version = "0.1",
132 packages = find_packages(),
133 scripts = ['say_hello.py'],
134
135 # Project uses reStructuredText, so ensure that the docutils get
136 # installed or upgraded on the target machine
137 install_requires = ['docutils>=0.3'],
138
139 package_data = {
140 # If any package contains *.txt or *.rst files, include them:
141 '': ['*.txt', '*.rst'],
142 # And include any *.msg files found in the 'hello' package, too:
143 'hello': ['*.msg'],
144 }
145
146 # metadata for upload to PyPI
147 author = "Me",
148 author_email = "me@example.com",
149 description = "This is an Example Package",
150 license = "PSF",
151 keywords = "hello world example examples",
152 url = "http://example.com/HelloWorld/", # project home page, if any
153
154 # could also include long_description, download_url, classifiers, etc.
155 )
156
157In the sections that follow, we'll explain what most of these ``setup()``
158arguments do (except for the metadata ones), and the various ways you might use
159them in your own project(s).
160
161
162Specifying Your Project's Version
163---------------------------------
164
165Setuptools can work well with most versioning schemes; there are, however, a
166few special things to watch out for, in order to ensure that setuptools and
167EasyInstall can always tell what version of your package is newer than another
168version. Knowing these things will also help you correctly specify what
169versions of other projects your project depends on.
170
171A version consists of an alternating series of release numbers and pre-release
172or post-release tags. A release number is a series of digits punctuated by
173dots, such as ``2.4`` or ``0.5``. Each series of digits is treated
174numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the
175same release number, denoting the first subrelease of release 2. But ``2.10``
176is the *tenth* subrelease of release 2, and so is a different and newer release
177from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also
178ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``.
179
180Following a release number, you can have either a pre-release or post-release
181tag. Pre-release tags make a version be considered *older* than the version
182they are appended to. So, revision ``2.4`` is *newer* than revision ``2.4c1``,
183which in turn is newer than ``2.4b1`` or ``2.4a1``. Postrelease tags make
184a version be considered *newer* than the version they are appended to. So,
185revisions like ``2.4-1`` and ``2.4pl3`` are newer than ``2.4``, but are *older*
186than ``2.4.1`` (which has a higher release number).
187
188A pre-release tag is a series of letters that are alphabetically before
189"final". Some examples of prerelease tags would include ``alpha``, ``beta``,
190``a``, ``c``, ``dev``, and so on. You do not have to place a dot before
191the prerelease tag if it's immediately after a number, but it's okay to do
192so if you prefer. Thus, ``2.4c1`` and ``2.4.c1`` both represent release
193candidate 1 of version ``2.4``, and are treated as identical by setuptools.
194
195In addition, there are three special prerelease tags that are treated as if
196they were the letter ``c``: ``pre``, ``preview``, and ``rc``. So, version
197``2.4rc1``, ``2.4pre1`` and ``2.4preview1`` are all the exact same version as
198``2.4c1``, and are treated as identical by setuptools.
199
200A post-release tag is either a series of letters that are alphabetically
201greater than or equal to "final", or a dash (``-``). Post-release tags are
202generally used to separate patch numbers, port numbers, build numbers, revision
203numbers, or date stamps from the release number. For example, the version
204``2.4-r1263`` might denote Subversion revision 1263 of a post-release patch of
205version ``2.4``. Or you might use ``2.4-20051127`` to denote a date-stamped
206post-release.
207
208Notice that after each pre or post-release tag, you are free to place another
209release number, followed again by more pre- or post-release tags. For example,
210``0.6a9.dev-r41475`` could denote Subversion revision 41475 of the in-
211development version of the ninth alpha of release 0.6. Notice that ``dev`` is
212a pre-release tag, so this version is a *lower* version number than ``0.6a9``,
213which would be the actual ninth alpha of release 0.6. But the ``-r41475`` is
214a post-release tag, so this version is *newer* than ``0.6a9.dev``.
215
216For the most part, setuptools' interpretation of version numbers is intuitive,
217but here are a few tips that will keep you out of trouble in the corner cases:
218
219* Don't use ``-`` or any other character than ``.`` as a separator, unless you
220 really want a post-release. Remember that ``2.1-rc2`` means you've
221 *already* released ``2.1``, whereas ``2.1rc2`` and ``2.1.c2`` are candidates
222 you're putting out *before* ``2.1``. If you accidentally distribute copies
223 of a post-release that you meant to be a pre-release, the only safe fix is to
224 bump your main release number (e.g. to ``2.1.1``) and re-release the project.
225
226* Don't stick adjoining pre-release tags together without a dot or number
227 between them. Version ``1.9adev`` is the ``adev`` prerelease of ``1.9``,
228 *not* a development pre-release of ``1.9a``. Use ``.dev`` instead, as in
229 ``1.9a.dev``, or separate the prerelease tags with a number, as in
230 ``1.9a0dev``. ``1.9a.dev``, ``1.9a0dev``, and even ``1.9.a.dev`` are
231 identical versions from setuptools' point of view, so you can use whatever
232 scheme you prefer.
233
234* If you want to be certain that your chosen numbering scheme works the way
235 you think it will, you can use the ``pkg_resources.parse_version()`` function
236 to compare different version numbers::
237
238 >>> from pkg_resources import parse_version
239 >>> parse_version('1.9.a.dev') == parse_version('1.9a0dev')
240 True
241 >>> parse_version('2.1-rc2') < parse_version('2.1')
242 False
243 >>> parse_version('0.6a9dev-r41475') < parse_version('0.6a9')
244 True
245
246Once you've decided on a version numbering scheme for your project, you can
247have setuptools automatically tag your in-development releases with various
248pre- or post-release tags. See the following sections for more details:
249
250* `Tagging and "Daily Build" or "Snapshot" Releases`_
251* `Managing "Continuous Releases" Using Subversion`_
252* The `egg_info`_ command
253
254
255New and Changed ``setup()`` Keywords
256====================================
257
258The following keyword arguments to ``setup()`` are added or changed by
259``setuptools``. All of them are optional; you do not have to supply them
260unless you need the associated ``setuptools`` feature.
261
262``include_package_data``
263 If set to ``True``, this tells ``setuptools`` to automatically include any
264 data files it finds inside your package directories, that are either under
265 CVS or Subversion control, or which are specified by your ``MANIFEST.in``
266 file. For more information, see the section below on `Including Data
267 Files`_.
268
269``exclude_package_data``
270 A dictionary mapping package names to lists of glob patterns that should
271 be *excluded* from your package directories. You can use this to trim back
272 any excess files included by ``include_package_data``. For a complete
273 description and examples, see the section below on `Including Data Files`_.
274
275``package_data``
276 A dictionary mapping package names to lists of glob patterns. For a
277 complete description and examples, see the section below on `Including
278 Data Files`_. You do not need to use this option if you are using
279 ``include_package_data``, unless you need to add e.g. files that are
280 generated by your setup script and build process. (And are therefore not
281 in source control or are files that you don't want to include in your
282 source distribution.)
283
284``zip_safe``
285 A boolean (True or False) flag specifying whether the project can be
286 safely installed and run from a zip file. If this argument is not
287 supplied, the ``bdist_egg`` command will have to analyze all of your
288 project's contents for possible problems each time it buids an egg.
289
290``install_requires``
291 A string or list of strings specifying what other distributions need to
292 be installed when this one is. See the section below on `Declaring
293 Dependencies`_ for details and examples of the format of this argument.
294
295``entry_points``
296 A dictionary mapping entry point group names to strings or lists of strings
297 defining the entry points. Entry points are used to support dynamic
298 discovery of services or plugins provided by a project. See `Dynamic
299 Discovery of Services and Plugins`_ for details and examples of the format
300 of this argument. In addition, this keyword is used to support `Automatic
301 Script Creation`_.
302
303``extras_require``
304 A dictionary mapping names of "extras" (optional features of your project)
305 to strings or lists of strings specifying what other distributions must be
306 installed to support those features. See the section below on `Declaring
307 Dependencies`_ for details and examples of the format of this argument.
308
309``setup_requires``
310 A string or list of strings specifying what other distributions need to
311 be present in order for the *setup script* to run. ``setuptools`` will
312 attempt to obtain these (even going so far as to download them using
313 ``EasyInstall``) before processing the rest of the setup script or commands.
314 This argument is needed if you are using distutils extensions as part of
315 your build process; for example, extensions that process setup() arguments
316 and turn them into EGG-INFO metadata files.
317
318 (Note: projects listed in ``setup_requires`` will NOT be automatically
319 installed on the system where the setup script is being run. They are
320 simply downloaded to the setup directory if they're not locally available
321 already. If you want them to be installed, as well as being available
322 when the setup script is run, you should add them to ``install_requires``
323 **and** ``setup_requires``.)
324
325``dependency_links``
326 A list of strings naming URLs to be searched when satisfying dependencies.
327 These links will be used if needed to install packages specified by
328 ``setup_requires`` or ``tests_require``. They will also be written into
329 the egg's metadata for use by tools like EasyInstall to use when installing
330 an ``.egg`` file.
331
332``namespace_packages``
333 A list of strings naming the project's "namespace packages". A namespace
334 package is a package that may be split across multiple project
335 distributions. For example, Zope 3's ``zope`` package is a namespace
336 package, because subpackages like ``zope.interface`` and ``zope.publisher``
337 may be distributed separately. The egg runtime system can automatically
338 merge such subpackages into a single parent package at runtime, as long
339 as you declare them in each project that contains any subpackages of the
340 namespace package, and as long as the namespace package's ``__init__.py``
341 does not contain any code. See the section below on `Namespace Packages`_
342 for more information.
343
344``test_suite``
345 A string naming a ``unittest.TestCase`` subclass (or a package or module
346 containing one or more of them, or a method of such a subclass), or naming
347 a function that can be called with no arguments and returns a
348 ``unittest.TestSuite``. If the named suite is a module, and the module
349 has an ``additional_tests()`` function, it is called and the results are
350 added to the tests to be run. If the named suite is a package, any
351 submodules and subpackages are recursively added to the overall test suite.
352
353 Specifying this argument enables use of the `test`_ command to run the
354 specified test suite, e.g. via ``setup.py test``. See the section on the
355 `test`_ command below for more details.
356
357``tests_require``
358 If your project's tests need one or more additional packages besides those
359 needed to install it, you can use this option to specify them. It should
360 be a string or list of strings specifying what other distributions need to
361 be present for the package's tests to run. When you run the ``test``
362 command, ``setuptools`` will attempt to obtain these (even going
363 so far as to download them using ``EasyInstall``). Note that these
364 required projects will *not* be installed on the system where the tests
365 are run, but only downloaded to the project's setup directory if they're
366 not already installed locally.
367
368.. _test_loader:
369
370``test_loader``
371 If you would like to use a different way of finding tests to run than what
372 setuptools normally uses, you can specify a module name and class name in
373 this argument. The named class must be instantiable with no arguments, and
374 its instances must support the ``loadTestsFromNames()`` method as defined
375 in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will
376 pass only one test "name" in the `names` argument: the value supplied for
377 the ``test_suite`` argument. The loader you specify may interpret this
378 string in any way it likes, as there are no restrictions on what may be
379 contained in a ``test_suite`` string.
380
381 The module name and class name must be separated by a ``:``. The default
382 value of this argument is ``"setuptools.command.test:ScanningLoader"``. If
383 you want to use the default ``unittest`` behavior, you can specify
384 ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This
385 will prevent automatic scanning of submodules and subpackages.
386
387 The module and class you specify here may be contained in another package,
388 as long as you use the ``tests_require`` option to ensure that the package
389 containing the loader class is available when the ``test`` command is run.
390
391``eager_resources``
392 A list of strings naming resources that should be extracted together, if
393 any of them is needed, or if any C extensions included in the project are
394 imported. This argument is only useful if the project will be installed as
395 a zipfile, and there is a need to have all of the listed resources be
396 extracted to the filesystem *as a unit*. Resources listed here
397 should be '/'-separated paths, relative to the source root, so to list a
398 resource ``foo.png`` in package ``bar.baz``, you would include the string
399 ``bar/baz/foo.png`` in this argument.
400
401 If you only need to obtain resources one at a time, or you don't have any C
402 extensions that access other files in the project (such as data files or
403 shared libraries), you probably do NOT need this argument and shouldn't
404 mess with it. For more details on how this argument works, see the section
405 below on `Automatic Resource Extraction`_.
406
407
408Using ``find_packages()``
409-------------------------
410
411For simple projects, it's usually easy enough to manually add packages to
412the ``packages`` argument of ``setup()``. However, for very large projects
413(Twisted, PEAK, Zope, Chandler, etc.), it can be a big burden to keep the
414package list updated. That's what ``setuptools.find_packages()`` is for.
415
416``find_packages()`` takes a source directory, and a list of package names or
417patterns to exclude. If omitted, the source directory defaults to the same
418directory as the setup script. Some projects use a ``src`` or ``lib``
419directory as the root of their source tree, and those projects would of course
420use ``"src"`` or ``"lib"`` as the first argument to ``find_packages()``. (And
421such projects also need something like ``package_dir = {'':'src'}`` in their
422``setup()`` arguments, but that's just a normal distutils thing.)
423
424Anyway, ``find_packages()`` walks the target directory, and finds Python
425packages by looking for ``__init__.py`` files. It then filters the list of
426packages using the exclusion patterns.
427
428Exclusion patterns are package names, optionally including wildcards. For
429example, ``find_packages(exclude=["*.tests"])`` will exclude all packages whose
430last name part is ``tests``. Or, ``find_packages(exclude=["*.tests",
431"*.tests.*"])`` will also exclude any subpackages of packages named ``tests``,
432but it still won't exclude a top-level ``tests`` package or the children
433thereof. In fact, if you really want no ``tests`` packages at all, you'll need
434something like this::
435
436 find_packages(exclude=["*.tests", "*.tests.*", "tests.*", "tests"])
437
438in order to cover all the bases. Really, the exclusion patterns are intended
439to cover simpler use cases than this, like excluding a single, specified
440package and its subpackages.
441
442Regardless of the target directory or exclusions, the ``find_packages()``
443function returns a list of package names suitable for use as the ``packages``
444argument to ``setup()``, and so is usually the easiest way to set that
445argument in your setup script. Especially since it frees you from having to
446remember to modify your setup script whenever your project grows additional
447top-level packages or subpackages.
448
449
450Automatic Script Creation
451=========================
452
453Packaging and installing scripts can be a bit awkward with the distutils. For
454one thing, there's no easy way to have a script's filename match local
455conventions on both Windows and POSIX platforms. For another, you often have
456to create a separate file just for the "main" script, when your actual "main"
457is a function in a module somewhere. And even in Python 2.4, using the ``-m``
458option only works for actual ``.py`` files that aren't installed in a package.
459
460``setuptools`` fixes all of these problems by automatically generating scripts
461for you with the correct extension, and on Windows it will even create an
462``.exe`` file so that users don't have to change their ``PATHEXT`` settings.
463The way to use this feature is to define "entry points" in your setup script
464that indicate what function the generated script should import and run. For
465example, to create two console scripts called ``foo`` and ``bar``, and a GUI
466script called ``baz``, you might do something like this::
467
468 setup(
469 # other arguments here...
470 entry_points = {
471 'console_scripts': [
472 'foo = my_package.some_module:main_func',
473 'bar = other_module:some_func',
474 ],
475 'gui_scripts': [
476 'baz = my_package_gui.start_func',
477 ]
478 }
479 )
480
481When this project is installed on non-Windows platforms (using "setup.py
482install", "setup.py develop", or by using EasyInstall), a set of ``foo``,
483``bar``, and ``baz`` scripts will be installed that import ``main_func`` and
484``some_func`` from the specified modules. The functions you specify are called
485with no arguments, and their return value is passed to ``sys.exit()``, so you
486can return an errorlevel or message to print to stderr.
487
488On Windows, a set of ``foo.exe``, ``bar.exe``, and ``baz.exe`` launchers are
489created, alongside a set of ``foo.py``, ``bar.py``, and ``baz.pyw`` files. The
490``.exe`` wrappers find and execute the right version of Python to run the
491``.py`` or ``.pyw`` file.
492
493You may define as many "console script" and "gui script" entry points as you
494like, and each one can optionally specify "extras" that it depends on, that
495will be added to ``sys.path`` when the script is run. For more information on
496"extras", see the section below on `Declaring Extras`_. For more information
497on "entry points" in general, see the section below on `Dynamic Discovery of
498Services and Plugins`_.
499
500
501"Eggsecutable" Scripts
502----------------------
503
504Occasionally, there are situations where it's desirable to make an ``.egg``
505file directly executable. You can do this by including an entry point such
506as the following::
507
508 setup(
509 # other arguments here...
510 entry_points = {
511 'setuptools.installation': [
512 'eggsecutable = my_package.some_module:main_func',
513 ]
514 }
515 )
516
517Any eggs built from the above setup script will include a short excecutable
518prelude that imports and calls ``main_func()`` from ``my_package.some_module``.
519The prelude can be run on Unix-like platforms (including Mac and Linux) by
520invoking the egg with ``/bin/sh``, or by enabling execute permissions on the
521``.egg`` file. For the executable prelude to run, the appropriate version of
522Python must be available via the ``PATH`` environment variable, under its
523"long" name. That is, if the egg is built for Python 2.3, there must be a
524``python2.3`` executable present in a directory on ``PATH``.
525
526This feature is primarily intended to support bootstrapping the installation of
527setuptools itself on non-Windows platforms, but may also be useful for other
528projects as well.
529
530IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or
531invoked via symlinks. They *must* be invoked using their original filename, in
532order to ensure that, once running, ``pkg_resources`` will know what project
533and version is in use. The header script will check this and exit with an
534error if the ``.egg`` file has been renamed or is invoked via a symlink that
535changes its base name.
536
537
538Declaring Dependencies
539======================
540
541``setuptools`` supports automatically installing dependencies when a package is
542installed, and including information about dependencies in Python Eggs (so that
543package management tools like EasyInstall can use the information).
544
545``setuptools`` and ``pkg_resources`` use a common syntax for specifying a
546project's required dependencies. This syntax consists of a project's PyPI
547name, optionally followed by a comma-separated list of "extras" in square
548brackets, optionally followed by a comma-separated list of version
549specifiers. A version specifier is one of the operators ``<``, ``>``, ``<=``,
550``>=``, ``==`` or ``!=``, followed by a version identifier. Tokens may be
551separated by whitespace, but any whitespace or nonstandard characters within a
552project name or version identifier must be replaced with ``-``.
553
554Version specifiers for a given project are internally sorted into ascending
555version order, and used to establish what ranges of versions are acceptable.
556Adjacent redundant conditions are also consolidated (e.g. ``">1, >2"`` becomes
557``">1"``, and ``"<2,<3"`` becomes ``"<3"``). ``"!="`` versions are excised from
558the ranges they fall within. A project's version is then checked for
559membership in the resulting ranges. (Note that providing conflicting conditions
560for the same version (e.g. "<2,>=2" or "==2,!=2") is meaningless and may
561therefore produce bizarre results.)
562
563Here are some example requirement specifiers::
564
565 docutils >= 0.3
566
567 # comment lines and \ continuations are allowed in requirement strings
568 BazSpam ==1.1, ==1.2, ==1.3, ==1.4, ==1.5, \
569 ==1.6, ==1.7 # and so are line-end comments
570
571 PEAK[FastCGI, reST]>=0.5a4
572
573 setuptools==0.5a7
574
575The simplest way to include requirement specifiers is to use the
576``install_requires`` argument to ``setup()``. It takes a string or list of
577strings containing requirement specifiers. If you include more than one
578requirement in a string, each requirement must begin on a new line.
579
580This has three effects:
581
5821. When your project is installed, either by using EasyInstall, ``setup.py
583 install``, or ``setup.py develop``, all of the dependencies not already
584 installed will be located (via PyPI), downloaded, built (if necessary),
585 and installed.
586
5872. Any scripts in your project will be installed with wrappers that verify
588 the availability of the specified dependencies at runtime, and ensure that
589 the correct versions are added to ``sys.path`` (e.g. if multiple versions
590 have been installed).
591
5923. Python Egg distributions will include a metadata file listing the
593 dependencies.
594
595Note, by the way, that if you declare your dependencies in ``setup.py``, you do
596*not* need to use the ``require()`` function in your scripts or modules, as
597long as you either install the project or use ``setup.py develop`` to do
598development work on it. (See `"Development Mode"`_ below for more details on
599using ``setup.py develop``.)
600
601
602Dependencies that aren't in PyPI
603--------------------------------
604
605If your project depends on packages that aren't registered in PyPI, you may
606still be able to depend on them, as long as they are available for download
607as an egg, in the standard distutils ``sdist`` format, or as a single ``.py``
608file. You just need to add some URLs to the ``dependency_links`` argument to
609``setup()``.
610
611The URLs must be either:
612
6131. direct download URLs, or
6142. the URLs of web pages that contain direct download links
615
616In general, it's better to link to web pages, because it is usually less
617complex to update a web page than to release a new version of your project.
618You can also use a SourceForge ``showfiles.php`` link in the case where a
619package you depend on is distributed via SourceForge.
620
621If you depend on a package that's distributed as a single ``.py`` file, you
622must include an ``"#egg=project-version"`` suffix to the URL, to give a project
623name and version number. (Be sure to escape any dashes in the name or version
624by replacing them with underscores.) EasyInstall will recognize this suffix
625and automatically create a trivial ``setup.py`` to wrap the single ``.py`` file
626as an egg.
627
628The ``dependency_links`` option takes the form of a list of URL strings. For
629example, the below will cause EasyInstall to search the specified page for
630eggs or source distributions, if the package's dependencies aren't already
631installed::
632
633 setup(
634 ...
635 dependency_links = [
636 "http://peak.telecommunity.com/snapshots/"
637 ],
638 )
639
640
641.. _Declaring Extras:
642
643
644Declaring "Extras" (optional features with their own dependencies)
645------------------------------------------------------------------
646
647Sometimes a project has "recommended" dependencies, that are not required for
648all uses of the project. For example, a project might offer optional PDF
649output if ReportLab is installed, and reStructuredText support if docutils is
650installed. These optional features are called "extras", and setuptools allows
651you to define their requirements as well. In this way, other projects that
652require these optional features can force the additional requirements to be
653installed, by naming the desired extras in their ``install_requires``.
654
655For example, let's say that Project A offers optional PDF and reST support::
656
657 setup(
658 name="Project-A",
659 ...
660 extras_require = {
661 'PDF': ["ReportLab>=1.2", "RXP"],
662 'reST': ["docutils>=0.3"],
663 }
664 )
665
666As you can see, the ``extras_require`` argument takes a dictionary mapping
667names of "extra" features, to strings or lists of strings describing those
668features' requirements. These requirements will *not* be automatically
669installed unless another package depends on them (directly or indirectly) by
670including the desired "extras" in square brackets after the associated project
671name. (Or if the extras were listed in a requirement spec on the EasyInstall
672command line.)
673
674Extras can be used by a project's `entry points`_ to specify dynamic
675dependencies. For example, if Project A includes a "rst2pdf" script, it might
676declare it like this, so that the "PDF" requirements are only resolved if the
677"rst2pdf" script is run::
678
679 setup(
680 name="Project-A",
681 ...
682 entry_points = {
683 'console_scripts':
684 ['rst2pdf = project_a.tools.pdfgen [PDF]'],
685 ['rst2html = project_a.tools.htmlgen'],
686 # more script entry points ...
687 }
688 )
689
690Projects can also use another project's extras when specifying dependencies.
691For example, if project B needs "project A" with PDF support installed, it
692might declare the dependency like this::
693
694 setup(
695 name="Project-B",
696 install_requires = ["Project-A[PDF]"],
697 ...
698 )
699
700This will cause ReportLab to be installed along with project A, if project B is
701installed -- even if project A was already installed. In this way, a project
702can encapsulate groups of optional "downstream dependencies" under a feature
703name, so that packages that depend on it don't have to know what the downstream
704dependencies are. If a later version of Project A builds in PDF support and
705no longer needs ReportLab, or if it ends up needing other dependencies besides
706ReportLab in order to provide PDF support, Project B's setup information does
707not need to change, but the right packages will still be installed if needed.
708
709Note, by the way, that if a project ends up not needing any other packages to
710support a feature, it should keep an empty requirements list for that feature
711in its ``extras_require`` argument, so that packages depending on that feature
712don't break (due to an invalid feature name). For example, if Project A above
713builds in PDF support and no longer needs ReportLab, it could change its
714setup to this::
715
716 setup(
717 name="Project-A",
718 ...
719 extras_require = {
720 'PDF': [],
721 'reST': ["docutils>=0.3"],
722 }
723 )
724
725so that Package B doesn't have to remove the ``[PDF]`` from its requirement
726specifier.
727
728
729Including Data Files
730====================
731
732The distutils have traditionally allowed installation of "data files", which
733are placed in a platform-specific location. However, the most common use case
734for data files distributed with a package is for use *by* the package, usually
735by including the data files in the package directory.
736
737Setuptools offers three ways to specify data files to be included in your
738packages. First, you can simply use the ``include_package_data`` keyword,
739e.g.::
740
741 from setuptools import setup, find_packages
742 setup(
743 ...
744 include_package_data = True
745 )
746
747This tells setuptools to install any data files it finds in your packages. The
748data files must be under CVS or Subversion control, or else they must be
749specified via the distutils' ``MANIFEST.in`` file. (They can also be tracked
750by another revision control system, using an appropriate plugin. See the
751section below on `Adding Support for Other Revision Control Systems`_ for
752information on how to write such plugins.)
753
754If you want finer-grained control over what files are included (for example, if
755you have documentation files in your package directories and want to exclude
756them from installation), then you can also use the ``package_data`` keyword,
757e.g.::
758
759 from setuptools import setup, find_packages
760 setup(
761 ...
762 package_data = {
763 # If any package contains *.txt or *.rst files, include them:
764 '': ['*.txt', '*.rst'],
765 # And include any *.msg files found in the 'hello' package, too:
766 'hello': ['*.msg'],
767 }
768 )
769
770The ``package_data`` argument is a dictionary that maps from package names to
771lists of glob patterns. The globs may include subdirectory names, if the data
772files are contained in a subdirectory of the package. For example, if the
773package tree looks like this::
774
775 setup.py
776 src/
777 mypkg/
778 __init__.py
779 mypkg.txt
780 data/
781 somefile.dat
782 otherdata.dat
783
784The setuptools setup file might look like this::
785
786 from setuptools import setup, find_packages
787 setup(
788 ...
789 packages = find_packages('src'), # include all packages under src
790 package_dir = {'':'src'}, # tell distutils packages are under src
791
792 package_data = {
793 # If any package contains *.txt files, include them:
794 '': ['*.txt'],
795 # And include any *.dat files found in the 'data' subdirectory
796 # of the 'mypkg' package, also:
797 'mypkg': ['data/*.dat'],
798 }
799 )
800
801Notice that if you list patterns in ``package_data`` under the empty string,
802these patterns are used to find files in every package, even ones that also
803have their own patterns listed. Thus, in the above example, the ``mypkg.txt``
804file gets included even though it's not listed in the patterns for ``mypkg``.
805
806Also notice that if you use paths, you *must* use a forward slash (``/``) as
807the path separator, even if you are on Windows. Setuptools automatically
808converts slashes to appropriate platform-specific separators at build time.
809
810(Note: although the ``package_data`` argument was previously only available in
811``setuptools``, it was also added to the Python ``distutils`` package as of
812Python 2.4; there is `some documentation for the feature`__ available on the
813python.org website.)
814
815__ http://docs.python.org/dist/node11.html
816
817Sometimes, the ``include_package_data`` or ``package_data`` options alone
818aren't sufficient to precisely define what files you want included. For
819example, you may want to include package README files in your revision control
820system and source distributions, but exclude them from being installed. So,
821setuptools offers an ``exclude_package_data`` option as well, that allows you
822to do things like this::
823
824 from setuptools import setup, find_packages
825 setup(
826 ...
827 packages = find_packages('src'), # include all packages under src
828 package_dir = {'':'src'}, # tell distutils packages are under src
829
830 include_package_data = True, # include everything in source control
831
832 # ...but exclude README.txt from all packages
833 exclude_package_data = { '': ['README.txt'] },
834 )
835
836The ``exclude_package_data`` option is a dictionary mapping package names to
837lists of wildcard patterns, just like the ``package_data`` option. And, just
838as with that option, a key of ``''`` will apply the given pattern(s) to all
839packages. However, any files that match these patterns will be *excluded*
840from installation, even if they were listed in ``package_data`` or were
841included as a result of using ``include_package_data``.
842
843In summary, the three options allow you to:
844
845``include_package_data``
846 Accept all data files and directories matched by ``MANIFEST.in`` or found
847 in source control.
848
849``package_data``
850 Specify additional patterns to match files and directories that may or may
851 not be matched by ``MANIFEST.in`` or found in source control.
852
853``exclude_package_data``
854 Specify patterns for data files and directories that should *not* be
855 included when a package is installed, even if they would otherwise have
856 been included due to the use of the preceding options.
857
858NOTE: Due to the way the distutils build process works, a data file that you
859include in your project and then stop including may be "orphaned" in your
860project's build directories, requiring you to run ``setup.py clean --all`` to
861fully remove them. This may also be important for your users and contributors
862if they track intermediate revisions of your project using Subversion; be sure
863to let them know when you make changes that remove files from inclusion so they
864can run ``setup.py clean --all``.
865
866
867Accessing Data Files at Runtime
868-------------------------------
869
870Typically, existing programs manipulate a package's ``__file__`` attribute in
871order to find the location of data files. However, this manipulation isn't
872compatible with PEP 302-based import hooks, including importing from zip files
873and Python Eggs. It is strongly recommended that, if you are using data files,
874you should use the `Resource Management API`_ of ``pkg_resources`` to access
875them. The ``pkg_resources`` module is distributed as part of setuptools, so if
876you're using setuptools to distribute your package, there is no reason not to
877use its resource management API. See also `Accessing Package Resources`_ for
878a quick example of converting code that uses ``__file__`` to use
879``pkg_resources`` instead.
880
881.. _Resource Management API: http://peak.telecommunity.com/DevCenter/PythonEggs#resource-management
882.. _Accessing Package Resources: http://peak.telecommunity.com/DevCenter/PythonEggs#accessing-package-resources
883
884
885Non-Package Data Files
886----------------------
887
888The ``distutils`` normally install general "data files" to a platform-specific
889location (e.g. ``/usr/share``). This feature intended to be used for things
890like documentation, example configuration files, and the like. ``setuptools``
891does not install these data files in a separate location, however. They are
892bundled inside the egg file or directory, alongside the Python modules and
893packages. The data files can also be accessed using the `Resource Management
894API`_, by specifying a ``Requirement`` instead of a package name::
895
896 from pkg_resources import Requirement, resource_filename
897 filename = resource_filename(Requirement.parse("MyProject"),"sample.conf")
898
899The above code will obtain the filename of the "sample.conf" file in the data
900root of the "MyProject" distribution.
901
902Note, by the way, that this encapsulation of data files means that you can't
903actually install data files to some arbitrary location on a user's machine;
904this is a feature, not a bug. You can always include a script in your
905distribution that extracts and copies your the documentation or data files to
906a user-specified location, at their discretion. If you put related data files
907in a single directory, you can use ``resource_filename()`` with the directory
908name to get a filesystem directory that then can be copied with the ``shutil``
909module. (Even if your package is installed as a zipfile, calling
910``resource_filename()`` on a directory will return an actual filesystem
911directory, whose contents will be that entire subtree of your distribution.)
912
913(Of course, if you're writing a new package, you can just as easily place your
914data files or directories inside one of your packages, rather than using the
915distutils' approach. However, if you're updating an existing application, it
916may be simpler not to change the way it currently specifies these data files.)
917
918
919Automatic Resource Extraction
920-----------------------------
921
922If you are using tools that expect your resources to be "real" files, or your
923project includes non-extension native libraries or other files that your C
924extensions expect to be able to access, you may need to list those files in
925the ``eager_resources`` argument to ``setup()``, so that the files will be
926extracted together, whenever a C extension in the project is imported.
927
928This is especially important if your project includes shared libraries *other*
929than distutils-built C extensions, and those shared libraries use file
930extensions other than ``.dll``, ``.so``, or ``.dylib``, which are the
931extensions that setuptools 0.6a8 and higher automatically detects as shared
932libraries and adds to the ``native_libs.txt`` file for you. Any shared
933libraries whose names do not end with one of those extensions should be listed
934as ``eager_resources``, because they need to be present in the filesystem when
935he C extensions that link to them are used.
936
937The ``pkg_resources`` runtime for compressed packages will automatically
938extract *all* C extensions and ``eager_resources`` at the same time, whenever
939*any* C extension or eager resource is requested via the ``resource_filename()``
940API. (C extensions are imported using ``resource_filename()`` internally.)
941This ensures that C extensions will see all of the "real" files that they
942expect to see.
943
944Note also that you can list directory resource names in ``eager_resources`` as
945well, in which case the directory's contents (including subdirectories) will be
946extracted whenever any C extension or eager resource is requested.
947
948Please note that if you're not sure whether you need to use this argument, you
949don't! It's really intended to support projects with lots of non-Python
950dependencies and as a last resort for crufty projects that can't otherwise
951handle being compressed. If your package is pure Python, Python plus data
952files, or Python plus C, you really don't need this. You've got to be using
953either C or an external program that needs "real" files in your project before
954there's any possibility of ``eager_resources`` being relevant to your project.
955
956
957Extensible Applications and Frameworks
958======================================
959
960
961.. _Entry Points:
962
963Dynamic Discovery of Services and Plugins
964-----------------------------------------
965
966``setuptools`` supports creating libraries that "plug in" to extensible
967applications and frameworks, by letting you register "entry points" in your
968project that can be imported by the application or framework.
969
970For example, suppose that a blogging tool wants to support plugins
971that provide translation for various file types to the blog's output format.
972The framework might define an "entry point group" called ``blogtool.parsers``,
973and then allow plugins to register entry points for the file extensions they
974support.
975
976This would allow people to create distributions that contain one or more
977parsers for different file types, and then the blogging tool would be able to
978find the parsers at runtime by looking up an entry point for the file
979extension (or mime type, or however it wants to).
980
981Note that if the blogging tool includes parsers for certain file formats, it
982can register these as entry points in its own setup script, which means it
983doesn't have to special-case its built-in formats. They can just be treated
984the same as any other plugin's entry points would be.
985
986If you're creating a project that plugs in to an existing application or
987framework, you'll need to know what entry points or entry point groups are
988defined by that application or framework. Then, you can register entry points
989in your setup script. Here are a few examples of ways you might register an
990``.rst`` file parser entry point in the ``blogtool.parsers`` entry point group,
991for our hypothetical blogging tool::
992
993 setup(
994 # ...
995 entry_points = {'blogtool.parsers': '.rst = some_module:SomeClass'}
996 )
997
998 setup(
999 # ...
1000 entry_points = {'blogtool.parsers': ['.rst = some_module:a_func']}
1001 )
1002
1003 setup(
1004 # ...
1005 entry_points = """
1006 [blogtool.parsers]
1007 .rst = some.nested.module:SomeClass.some_classmethod [reST]
1008 """,
1009 extras_require = dict(reST = "Docutils>=0.3.5")
1010 )
1011
1012The ``entry_points`` argument to ``setup()`` accepts either a string with
1013``.ini``-style sections, or a dictionary mapping entry point group names to
1014either strings or lists of strings containing entry point specifiers. An
1015entry point specifier consists of a name and value, separated by an ``=``
1016sign. The value consists of a dotted module name, optionally followed by a
1017``:`` and a dotted identifier naming an object within the module. It can
1018also include a bracketed list of "extras" that are required for the entry
1019point to be used. When the invoking application or framework requests loading
1020of an entry point, any requirements implied by the associated extras will be
1021passed to ``pkg_resources.require()``, so that an appropriate error message
1022can be displayed if the needed package(s) are missing. (Of course, the
1023invoking app or framework can ignore such errors if it wants to make an entry
1024point optional if a requirement isn't installed.)
1025
1026
1027Defining Additional Metadata
1028----------------------------
1029
1030Some extensible applications and frameworks may need to define their own kinds
1031of metadata to include in eggs, which they can then access using the
1032``pkg_resources`` metadata APIs. Ordinarily, this is done by having plugin
1033developers include additional files in their ``ProjectName.egg-info``
1034directory. However, since it can be tedious to create such files by hand, you
1035may want to create a distutils extension that will create the necessary files
1036from arguments to ``setup()``, in much the same way that ``setuptools`` does
1037for many of the ``setup()`` arguments it adds. See the section below on
1038`Creating distutils Extensions`_ for more details, especially the subsection on
1039`Adding new EGG-INFO Files`_.
1040
1041
1042"Development Mode"
1043==================
1044
1045Under normal circumstances, the ``distutils`` assume that you are going to
1046build a distribution of your project, not use it in its "raw" or "unbuilt"
1047form. If you were to use the ``distutils`` that way, you would have to rebuild
1048and reinstall your project every time you made a change to it during
1049development.
1050
1051Another problem that sometimes comes up with the ``distutils`` is that you may
1052need to do development on two related projects at the same time. You may need
1053to put both projects' packages in the same directory to run them, but need to
1054keep them separate for revision control purposes. How can you do this?
1055
1056Setuptools allows you to deploy your projects for use in a common directory or
1057staging area, but without copying any files. Thus, you can edit each project's
1058code in its checkout directory, and only need to run build commands when you
1059change a project's C extensions or similarly compiled files. You can even
1060deploy a project into another project's checkout directory, if that's your
1061preferred way of working (as opposed to using a common independent staging area
1062or the site-packages directory).
1063
1064To do this, use the ``setup.py develop`` command. It works very similarly to
1065``setup.py install`` or the EasyInstall tool, except that it doesn't actually
1066install anything. Instead, it creates a special ``.egg-link`` file in the
1067deployment directory, that links to your project's source code. And, if your
1068deployment directory is Python's ``site-packages`` directory, it will also
1069update the ``easy-install.pth`` file to include your project's source code,
1070thereby making it available on ``sys.path`` for all programs using that Python
1071installation.
1072
1073In addition, the ``develop`` command creates wrapper scripts in the target
1074script directory that will run your in-development scripts after ensuring that
1075all your ``install_requires`` packages are available on ``sys.path``.
1076
1077You can deploy the same project to multiple staging areas, e.g. if you have
1078multiple projects on the same machine that are sharing the same project you're
1079doing development work.
1080
1081When you're done with a given development task, you can remove the project
1082source from a staging area using ``setup.py develop --uninstall``, specifying
1083the desired staging area if it's not the default.
1084
1085There are several options to control the precise behavior of the ``develop``
1086command; see the section on the `develop`_ command below for more details.
1087
1088Note that you can also apply setuptools commands to non-setuptools projects,
1089using commands like this::
1090
1091 python -c "import setuptools; execfile('setup.py')" develop
1092
1093That is, you can simply list the normal setup commands and options following
1094the quoted part.
1095
1096
1097Distributing a ``setuptools``-based project
1098===========================================
1099
1100Using ``setuptools``... Without bundling it!
1101---------------------------------------------
1102
1103Your users might not have ``setuptools`` installed on their machines, or even
1104if they do, it might not be the right version. Fixing this is easy; just
1105download `ez_setup.py`_, and put it in the same directory as your ``setup.py``
1106script. (Be sure to add it to your revision control system, too.) Then add
1107these two lines to the very top of your setup script, before the script imports
1108anything from setuptools::
1109
1110 import ez_setup
1111 ez_setup.use_setuptools()
1112
1113That's it. The ``ez_setup`` module will automatically download a matching
1114version of ``setuptools`` from PyPI, if it isn't present on the target system.
1115Whenever you install an updated version of setuptools, you should also update
1116your projects' ``ez_setup.py`` files, so that a matching version gets installed
1117on the target machine(s).
1118
1119By the way, setuptools supports the new PyPI "upload" command, so you can use
1120``setup.py sdist upload`` or ``setup.py bdist_egg upload`` to upload your
1121source or egg distributions respectively. Your project's current version must
1122be registered with PyPI first, of course; you can use ``setup.py register`` to
1123do that. Or you can do it all in one step, e.g. ``setup.py register sdist
1124bdist_egg upload`` will register the package, build source and egg
1125distributions, and then upload them both to PyPI, where they'll be easily
1126found by other projects that depend on them.
1127
1128(By the way, if you need to distribute a specific version of ``setuptools``,
1129you can specify the exact version and base download URL as parameters to the
1130``use_setuptools()`` function. See the function's docstring for details.)
1131
1132
1133What Your Users Should Know
1134---------------------------
1135
1136In general, a setuptools-based project looks just like any distutils-based
1137project -- as long as your users have an internet connection and are installing
1138to ``site-packages``, that is. But for some users, these conditions don't
1139apply, and they may become frustrated if this is their first encounter with
1140a setuptools-based project. To keep these users happy, you should review the
1141following topics in your project's installation instructions, if they are
1142relevant to your project and your target audience isn't already familiar with
1143setuptools and ``easy_install``.
1144
1145Network Access
1146 If your project is using ``ez_setup``, you should inform users of the need
1147 to either have network access, or to preinstall the correct version of
1148 setuptools using the `EasyInstall installation instructions`_. Those
1149 instructions also have tips for dealing with firewalls as well as how to
1150 manually download and install setuptools.
1151
1152Custom Installation Locations
1153 You should inform your users that if they are installing your project to
1154 somewhere other than the main ``site-packages`` directory, they should
1155 first install setuptools using the instructions for `Custom Installation
1156 Locations`_, before installing your project.
1157
1158Your Project's Dependencies
1159 If your project depends on other projects that may need to be downloaded
1160 from PyPI or elsewhere, you should list them in your installation
1161 instructions, or tell users how to find out what they are. While most
1162 users will not need this information, any users who don't have unrestricted
1163 internet access may have to find, download, and install the other projects
1164 manually. (Note, however, that they must still install those projects
1165 using ``easy_install``, or your project will not know they are installed,
1166 and your setup script will try to download them again.)
1167
1168 If you want to be especially friendly to users with limited network access,
1169 you may wish to build eggs for your project and its dependencies, making
1170 them all available for download from your site, or at least create a page
1171 with links to all of the needed eggs. In this way, users with limited
1172 network access can manually download all the eggs to a single directory,
1173 then use the ``-f`` option of ``easy_install`` to specify the directory
1174 to find eggs in. Users who have full network access can just use ``-f``
1175 with the URL of your download page, and ``easy_install`` will find all the
1176 needed eggs using your links directly. This is also useful when your
1177 target audience isn't able to compile packages (e.g. most Windows users)
1178 and your package or some of its dependencies include C code.
1179
1180Subversion or CVS Users and Co-Developers
1181 Users and co-developers who are tracking your in-development code using
1182 CVS, Subversion, or some other revision control system should probably read
1183 this manual's sections regarding such development. Alternately, you may
1184 wish to create a quick-reference guide containing the tips from this manual
1185 that apply to your particular situation. For example, if you recommend
1186 that people use ``setup.py develop`` when tracking your in-development
1187 code, you should let them know that this needs to be run after every update
1188 or commit.
1189
1190 Similarly, if you remove modules or data files from your project, you
1191 should remind them to run ``setup.py clean --all`` and delete any obsolete
1192 ``.pyc`` or ``.pyo``. (This tip applies to the distutils in general, not
1193 just setuptools, but not everybody knows about them; be kind to your users
1194 by spelling out your project's best practices rather than leaving them
1195 guessing.)
1196
1197Creating System Packages
1198 Some users want to manage all Python packages using a single package
1199 manager, and sometimes that package manager isn't ``easy_install``!
1200 Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and
1201 ``bdist_dumb`` formats for system packaging. If a user has a locally-
1202 installed "bdist" packaging tool that internally uses the distutils
1203 ``install`` command, it should be able to work with ``setuptools``. Some
1204 examples of "bdist" formats that this should work with include the
1205 ``bdist_nsi`` and ``bdist_msi`` formats for Windows.
1206
1207 However, packaging tools that build binary distributions by running
1208 ``setup.py install`` on the command line or as a subprocess will require
1209 modification to work with setuptools. They should use the
1210 ``--single-version-externally-managed`` option to the ``install`` command,
1211 combined with the standard ``--root`` or ``--record`` options.
1212 See the `install command`_ documentation below for more details. The
1213 ``bdist_deb`` command is an example of a command that currently requires
1214 this kind of patching to work with setuptools.
1215
1216 If you or your users have a problem building a usable system package for
1217 your project, please report the problem via the `mailing list`_ so that
1218 either the "bdist" tool in question or setuptools can be modified to
1219 resolve the issue.
1220
1221
1222
1223Managing Multiple Projects
1224--------------------------
1225
1226If you're managing several projects that need to use ``ez_setup``, and you are
1227using Subversion as your revision control system, you can use the
1228"svn:externals" property to share a single copy of ``ez_setup`` between
1229projects, so that it will always be up-to-date whenever you check out or update
1230an individual project, without having to manually update each project to use
1231a new version.
1232
1233However, because Subversion only supports using directories as externals, you
1234have to turn ``ez_setup.py`` into ``ez_setup/__init__.py`` in order to do this,
1235then create "externals" definitions that map the ``ez_setup`` directory into
1236each project. Also, if any of your projects use ``find_packages()`` on their
1237setup directory, you will need to exclude the resulting ``ez_setup`` package,
1238to keep it from being included in your distributions, e.g.::
1239
1240 setup(
1241 ...
1242 packages = find_packages(exclude=['ez_setup']),
1243 )
1244
1245Of course, the ``ez_setup`` package will still be included in your packages'
1246source distributions, as it needs to be.
1247
1248For your convenience, you may use the following external definition, which will
1249track the latest version of setuptools::
1250
1251 ez_setup svn://svn.eby-sarna.com/svnroot/ez_setup
1252
1253You can set this by executing this command in your project directory::
1254
1255 svn propedit svn:externals .
1256
1257And then adding the line shown above to the file that comes up for editing.
1258
1259
1260Setting the ``zip_safe`` flag
1261-----------------------------
1262
1263For maximum performance, Python packages are best installed as zip files.
1264Not all packages, however, are capable of running in compressed form, because
1265they may expect to be able to access either source code or data files as
1266normal operating system files. So, ``setuptools`` can install your project
1267as a zipfile or a directory, and its default choice is determined by the
1268project's ``zip_safe`` flag.
1269
1270You can pass a True or False value for the ``zip_safe`` argument to the
1271``setup()`` function, or you can omit it. If you omit it, the ``bdist_egg``
1272command will analyze your project's contents to see if it can detect any
1273conditions that would prevent it from working in a zipfile. It will output
1274notices to the console about any such conditions that it finds.
1275
1276Currently, this analysis is extremely conservative: it will consider the
1277project unsafe if it contains any C extensions or datafiles whatsoever. This
1278does *not* mean that the project can't or won't work as a zipfile! It just
1279means that the ``bdist_egg`` authors aren't yet comfortable asserting that
1280the project *will* work. If the project contains no C or data files, and does
1281no ``__file__`` or ``__path__`` introspection or source code manipulation, then
1282there is an extremely solid chance the project will work when installed as a
1283zipfile. (And if the project uses ``pkg_resources`` for all its data file
1284access, then C extensions and other data files shouldn't be a problem at all.
1285See the `Accessing Data Files at Runtime`_ section above for more information.)
1286
1287However, if ``bdist_egg`` can't be *sure* that your package will work, but
1288you've checked over all the warnings it issued, and you are either satisfied it
1289*will* work (or if you want to try it for yourself), then you should set
1290``zip_safe`` to ``True`` in your ``setup()`` call. If it turns out that it
1291doesn't work, you can always change it to ``False``, which will force
1292``setuptools`` to install your project as a directory rather than as a zipfile.
1293
1294Of course, the end-user can still override either decision, if they are using
1295EasyInstall to install your package. And, if you want to override for testing
1296purposes, you can just run ``setup.py easy_install --zip-ok .`` or ``setup.py
1297easy_install --always-unzip .`` in your project directory. to install the
1298package as a zipfile or directory, respectively.
1299
1300In the future, as we gain more experience with different packages and become
1301more satisfied with the robustness of the ``pkg_resources`` runtime, the
1302"zip safety" analysis may become less conservative. However, we strongly
1303recommend that you determine for yourself whether your project functions
1304correctly when installed as a zipfile, correct any problems if you can, and
1305then make an explicit declaration of ``True`` or ``False`` for the ``zip_safe``
1306flag, so that it will not be necessary for ``bdist_egg`` or ``EasyInstall`` to
1307try to guess whether your project can work as a zipfile.
1308
1309
1310Namespace Packages
1311------------------
1312
1313Sometimes, a large package is more useful if distributed as a collection of
1314smaller eggs. However, Python does not normally allow the contents of a
1315package to be retrieved from more than one location. "Namespace packages"
1316are a solution for this problem. When you declare a package to be a namespace
1317package, it means that the package has no meaningful contents in its
1318``__init__.py``, and that it is merely a container for modules and subpackages.
1319
1320The ``pkg_resources`` runtime will then automatically ensure that the contents
1321of namespace packages that are spread over multiple eggs or directories are
1322combined into a single "virtual" package.
1323
1324The ``namespace_packages`` argument to ``setup()`` lets you declare your
1325project's namespace packages, so that they will be included in your project's
1326metadata. The argument should list the namespace packages that the egg
1327participates in. For example, the ZopeInterface project might do this::
1328
1329 setup(
1330 # ...
1331 namespace_packages = ['zope']
1332 )
1333
1334because it contains a ``zope.interface`` package that lives in the ``zope``
1335namespace package. Similarly, a project for a standalone ``zope.publisher``
1336would also declare the ``zope`` namespace package. When these projects are
1337installed and used, Python will see them both as part of a "virtual" ``zope``
1338package, even though they will be installed in different locations.
1339
1340Namespace packages don't have to be top-level packages. For example, Zope 3's
1341``zope.app`` package is a namespace package, and in the future PEAK's
1342``peak.util`` package will be too.
1343
1344Note, by the way, that your project's source tree must include the namespace
1345packages' ``__init__.py`` files (and the ``__init__.py`` of any parent
1346packages), in a normal Python package layout. These ``__init__.py`` files
1347*must* contain the line::
1348
1349 __import__('pkg_resources').declare_namespace(__name__)
1350
1351This code ensures that the namespace package machinery is operating and that
1352the current package is registered as a namespace package.
1353
1354You must NOT include any other code and data in a namespace package's
1355``__init__.py``. Even though it may appear to work during development, or when
1356projects are installed as ``.egg`` files, it will not work when the projects
1357are installed using "system" packaging tools -- in such cases the
1358``__init__.py`` files will not be installed, let alone executed.
1359
1360You must include the ``declare_namespace()`` line in the ``__init__.py`` of
1361*every* project that has contents for the namespace package in question, in
1362order to ensure that the namespace will be declared regardless of which
1363project's copy of ``__init__.py`` is loaded first. If the first loaded
1364``__init__.py`` doesn't declare it, it will never *be* declared, because no
1365other copies will ever be loaded!)
1366
1367
1368TRANSITIONAL NOTE
1369~~~~~~~~~~~~~~~~~
1370
1371Setuptools 0.6a automatically calls ``declare_namespace()`` for you at runtime,
1372but the 0.7a versions will *not*. This is because the automatic declaration
1373feature has some negative side effects, such as needing to import all namespace
1374packages during the initialization of the ``pkg_resources`` runtime, and also
1375the need for ``pkg_resources`` to be explicitly imported before any namespace
1376packages work at all. Beginning with the 0.7a releases, you'll be responsible
1377for including your own declaration lines, and the automatic declaration feature
1378will be dropped to get rid of the negative side effects.
1379
1380During the remainder of the 0.6 development cycle, therefore, setuptools will
1381warn you about missing ``declare_namespace()`` calls in your ``__init__.py``
1382files, and you should correct these as soon as possible before setuptools 0.7a1
1383is released. Namespace packages without declaration lines will not work
1384correctly once a user has upgraded to setuptools 0.7a1, so it's important that
1385you make this change now in order to avoid having your code break in the field.
1386Our apologies for the inconvenience, and thank you for your patience.
1387
1388
1389
1390Tagging and "Daily Build" or "Snapshot" Releases
1391------------------------------------------------
1392
1393When a set of related projects are under development, it may be important to
1394track finer-grained version increments than you would normally use for e.g.
1395"stable" releases. While stable releases might be measured in dotted numbers
1396with alpha/beta/etc. status codes, development versions of a project often
1397need to be tracked by revision or build number or even build date. This is
1398especially true when projects in development need to refer to one another, and
1399therefore may literally need an up-to-the-minute version of something!
1400
1401To support these scenarios, ``setuptools`` allows you to "tag" your source and
1402egg distributions by adding one or more of the following to the project's
1403"official" version identifier:
1404
1405* A manually-specified pre-release tag, such as "build" or "dev", or a
1406 manually-specified post-release tag, such as a build or revision number
1407 (``--tag-build=STRING, -bSTRING``)
1408
1409* A "last-modified revision number" string generated automatically from
1410 Subversion's metadata (assuming your project is being built from a Subversion
1411 "working copy") (``--tag-svn-revision, -r``)
1412
1413* An 8-character representation of the build date (``--tag-date, -d``), as
1414 a postrelease tag
1415
1416You can add these tags by adding ``egg_info`` and the desired options to
1417the command line ahead of the ``sdist`` or ``bdist`` commands that you want
1418to generate a daily build or snapshot for. See the section below on the
1419`egg_info`_ command for more details.
1420
1421(Also, before you release your project, be sure to see the section above on
1422`Specifying Your Project's Version`_ for more information about how pre- and
1423post-release tags affect how setuptools and EasyInstall interpret version
1424numbers. This is important in order to make sure that dependency processing
1425tools will know which versions of your project are newer than others.)
1426
1427Finally, if you are creating builds frequently, and either building them in a
1428downloadable location or are copying them to a distribution server, you should
1429probably also check out the `rotate`_ command, which lets you automatically
1430delete all but the N most-recently-modified distributions matching a glob
1431pattern. So, you can use a command line like::
1432
1433 setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
1434
1435to build an egg whose version info includes 'DEV-rNNNN' (where NNNN is the
1436most recent Subversion revision that affected the source tree), and then
1437delete any egg files from the distribution directory except for the three
1438that were built most recently.
1439
1440If you have to manage automated builds for multiple packages, each with
1441different tagging and rotation policies, you may also want to check out the
1442`alias`_ command, which would let each package define an alias like ``daily``
1443that would perform the necessary tag, build, and rotate commands. Then, a
1444simpler script or cron job could just run ``setup.py daily`` in each project
1445directory. (And, you could also define sitewide or per-user default versions
1446of the ``daily`` alias, so that projects that didn't define their own would
1447use the appropriate defaults.)
1448
1449
1450Generating Source Distributions
1451-------------------------------
1452
1453``setuptools`` enhances the distutils' default algorithm for source file
1454selection, so that all files managed by CVS or Subversion in your project tree
1455are included in any source distribution you build. This is a big improvement
1456over having to manually write a ``MANIFEST.in`` file and try to keep it in
1457sync with your project. So, if you are using CVS or Subversion, and your
1458source distributions only need to include files that you're tracking in
1459revision control, don't create a a ``MANIFEST.in`` file for your project.
1460(And, if you already have one, you might consider deleting it the next time
1461you would otherwise have to change it.)
1462
1463(NOTE: other revision control systems besides CVS and Subversion can be
1464supported using plugins; see the section below on `Adding Support for Other
1465Revision Control Systems`_ for information on how to write such plugins.)
1466
1467If you need to include automatically generated files, or files that are kept in
1468an unsupported revision control system, you'll need to create a ``MANIFEST.in``
1469file to specify any files that the default file location algorithm doesn't
1470catch. See the distutils documentation for more information on the format of
1471the ``MANIFEST.in`` file.
1472
1473But, be sure to ignore any part of the distutils documentation that deals with
1474``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you
1475from these issues and doesn't work the same way in any case. Unlike the
1476distutils, setuptools regenerates the source distribution manifest file
1477every time you build a source distribution, and it builds it inside the
1478project's ``.egg-info`` directory, out of the way of your main project
1479directory. You therefore need not worry about whether it is up-to-date or not.
1480
1481Indeed, because setuptools' approach to determining the contents of a source
1482distribution is so much simpler, its ``sdist`` command omits nearly all of
1483the options that the distutils' more complex ``sdist`` process requires. For
1484all practical purposes, you'll probably use only the ``--formats`` option, if
1485you use any option at all.
1486
1487(By the way, if you're using some other revision control system, you might
1488consider creating and publishing a `revision control plugin for setuptools`_.)
1489
1490
1491.. _revision control plugin for setuptools: `Adding Support for Other Revision Control Systems`_
1492
1493
1494Making your package available for EasyInstall
1495---------------------------------------------
1496
1497If you use the ``register`` command (``setup.py register``) to register your
1498package with PyPI, that's most of the battle right there. (See the
1499`docs for the register command`_ for more details.)
1500
1501.. _docs for the register command: http://docs.python.org/dist/package-index.html
1502
1503If you also use the `upload`_ command to upload actual distributions of your
1504package, that's even better, because EasyInstall will be able to find and
1505download them directly from your project's PyPI page.
1506
1507However, there may be reasons why you don't want to upload distributions to
1508PyPI, and just want your existing distributions (or perhaps a Subversion
1509checkout) to be used instead.
1510
1511So here's what you need to do before running the ``register`` command. There
1512are three ``setup()`` arguments that affect EasyInstall:
1513
1514``url`` and ``download_url``
1515 These become links on your project's PyPI page. EasyInstall will examine
1516 them to see if they link to a package ("primary links"), or whether they are
1517 HTML pages. If they're HTML pages, EasyInstall scans all HREF's on the
1518 page for primary links
1519
1520``long_description``
1521 EasyInstall will check any URLs contained in this argument to see if they
1522 are primary links.
1523
1524A URL is considered a "primary link" if it is a link to a .tar.gz, .tgz, .zip,
1525.egg, .egg.zip, .tar.bz2, or .exe file, or if it has an ``#egg=project`` or
1526``#egg=project-version`` fragment identifier attached to it. EasyInstall
1527attempts to determine a project name and optional version number from the text
1528of a primary link *without* downloading it. When it has found all the primary
1529links, EasyInstall will select the best match based on requested version,
1530platform compatibility, and other criteria.
1531
1532So, if your ``url`` or ``download_url`` point either directly to a downloadable
1533source distribution, or to HTML page(s) that have direct links to such, then
1534EasyInstall will be able to locate downloads automatically. If you want to
1535make Subversion checkouts available, then you should create links with either
1536``#egg=project`` or ``#egg=project-version`` added to the URL. You should
1537replace ``project`` and ``version`` with the values they would have in an egg
1538filename. (Be sure to actually generate an egg and then use the initial part
1539of the filename, rather than trying to guess what the escaped form of the
1540project name and version number will be.)
1541
1542Note that Subversion checkout links are of lower precedence than other kinds
1543of distributions, so EasyInstall will not select a Subversion checkout for
1544downloading unless it has a version included in the ``#egg=`` suffix, and
1545it's a higher version than EasyInstall has seen in any other links for your
1546project.
1547
1548As a result, it's a common practice to use mark checkout URLs with a version of
1549"dev" (i.e., ``#egg=projectname-dev``), so that users can do something like
1550this::
1551
1552 easy_install --editable projectname==dev
1553
1554in order to check out the in-development version of ``projectname``.
1555
1556
1557Managing "Continuous Releases" Using Subversion
1558-----------------------------------------------
1559
1560If you expect your users to track in-development versions of your project via
1561Subversion, there are a few additional steps you should take to ensure that
1562things work smoothly with EasyInstall. First, you should add the following
1563to your project's ``setup.cfg`` file::
1564
1565 [egg_info]
1566 tag_build = .dev
1567 tag_svn_revision = 1
1568
1569This will tell ``setuptools`` to generate package version numbers like
1570``1.0a1.dev-r1263``, which will be considered to be an *older* release than
1571``1.0a1``. Thus, when you actually release ``1.0a1``, the entire egg
1572infrastructure (including ``setuptools``, ``pkg_resources`` and EasyInstall)
1573will know that ``1.0a1`` supersedes any interim snapshots from Subversion, and
1574handle upgrades accordingly.
1575
1576(Note: the project version number you specify in ``setup.py`` should always be
1577the *next* version of your software, not the last released version.
1578Alternately, you can leave out the ``tag_build=.dev``, and always use the
1579*last* release as a version number, so that your post-1.0 builds are labelled
1580``1.0-r1263``, indicating a post-1.0 patchlevel. Most projects so far,
1581however, seem to prefer to think of their project as being a future version
1582still under development, rather than a past version being patched. It is of
1583course possible for a single project to have both situations, using
1584post-release numbering on release branches, and pre-release numbering on the
1585trunk. But you don't have to make things this complex if you don't want to.)
1586
1587Commonly, projects releasing code from Subversion will include a PyPI link to
1588their checkout URL (as described in the previous section) with an
1589``#egg=projectname-dev`` suffix. This allows users to request EasyInstall
1590to download ``projectname==dev`` in order to get the latest in-development
1591code. Note that if your project depends on such in-progress code, you may wish
1592to specify your ``install_requires`` (or other requirements) to include
1593``==dev``, e.g.::
1594
1595 install_requires = ["OtherProject>=0.2a1.dev-r143,==dev"]
1596
1597The above example says, "I really want at least this particular development
1598revision number, but feel free to follow and use an ``#egg=OtherProject-dev``
1599link if you find one". This avoids the need to have actual source or binary
1600distribution snapshots of in-development code available, just to be able to
1601depend on the latest and greatest a project has to offer.
1602
1603A final note for Subversion development: if you are using SVN revision tags
1604as described in this section, it's a good idea to run ``setup.py develop``
1605after each Subversion checkin or update, because your project's version number
1606will be changing, and your script wrappers need to be updated accordingly.
1607
1608Also, if the project's requirements have changed, the ``develop`` command will
1609take care of fetching the updated dependencies, building changed extensions,
1610etc. Be sure to also remind any of your users who check out your project
1611from Subversion that they need to run ``setup.py develop`` after every update
1612in order to keep their checkout completely in sync.
1613
1614
1615Making "Official" (Non-Snapshot) Releases
1616~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1617
1618When you make an official release, creating source or binary distributions,
1619you will need to override the tag settings from ``setup.cfg``, so that you
1620don't end up registering versions like ``foobar-0.7a1.dev-r34832``. This is
1621easy to do if you are developing on the trunk and using tags or branches for
1622your releases - just make the change to ``setup.cfg`` after branching or
1623tagging the release, so the trunk will still produce development snapshots.
1624
1625Alternately, if you are not branching for releases, you can override the
1626default version options on the command line, using something like::
1627
1628 python setup.py egg_info -RDb "" sdist bdist_egg register upload
1629
1630The first part of this command (``egg_info -RDb ""``) will override the
1631configured tag information, before creating source and binary eggs, registering
1632the project with PyPI, and uploading the files. Thus, these commands will use
1633the plain version from your ``setup.py``, without adding the Subversion
1634revision number or build designation string.
1635
1636Of course, if you will be doing this a lot, you may wish to create a personal
1637alias for this operation, e.g.::
1638
1639 python setup.py alias -u release egg_info -RDb ""
1640
1641You can then use it like this::
1642
1643 python setup.py release sdist bdist_egg register upload
1644
1645Or of course you can create more elaborate aliases that do all of the above.
1646See the sections below on the `egg_info`_ and `alias`_ commands for more ideas.
1647
1648
1649
1650Distributing Extensions compiled with Pyrex
1651-------------------------------------------
1652
1653``setuptools`` includes transparent support for building Pyrex extensions, as
1654long as you define your extensions using ``setuptools.Extension``, *not*
1655``distutils.Extension``. You must also not import anything from Pyrex in
1656your setup script.
1657
1658If you follow these rules, you can safely list ``.pyx`` files as the source
1659of your ``Extension`` objects in the setup script. ``setuptools`` will detect
1660at build time whether Pyrex is installed or not. If it is, then ``setuptools``
1661will use it. If not, then ``setuptools`` will silently change the
1662``Extension`` objects to refer to the ``.c`` counterparts of the ``.pyx``
1663files, so that the normal distutils C compilation process will occur.
1664
1665Of course, for this to work, your source distributions must include the C
1666code generated by Pyrex, as well as your original ``.pyx`` files. This means
1667that you will probably want to include current ``.c`` files in your revision
1668control system, rebuilding them whenever you check changes in for the ``.pyx``
1669source files. This will ensure that people tracking your project in CVS or
1670Subversion will be able to build it even if they don't have Pyrex installed,
1671and that your source releases will be similarly usable with or without Pyrex.
1672
1673
1674-----------------
1675Command Reference
1676-----------------
1677
1678.. _alias:
1679
1680``alias`` - Define shortcuts for commonly used commands
1681=======================================================
1682
1683Sometimes, you need to use the same commands over and over, but you can't
1684necessarily set them as defaults. For example, if you produce both development
1685snapshot releases and "stable" releases of a project, you may want to put
1686the distributions in different places, or use different ``egg_info`` tagging
1687options, etc. In these cases, it doesn't make sense to set the options in
1688a distutils configuration file, because the values of the options changed based
1689on what you're trying to do.
1690
1691Setuptools therefore allows you to define "aliases" - shortcut names for
1692an arbitrary string of commands and options, using ``setup.py alias aliasname
1693expansion``, where aliasname is the name of the new alias, and the remainder of
1694the command line supplies its expansion. For example, this command defines
1695a sitewide alias called "daily", that sets various ``egg_info`` tagging
1696options::
1697
1698 setup.py alias --global-config daily egg_info --tag-svn-revision \
1699 --tag-build=development
1700
1701Once the alias is defined, it can then be used with other setup commands,
1702e.g.::
1703
1704 setup.py daily bdist_egg # generate a daily-build .egg file
1705 setup.py daily sdist # generate a daily-build source distro
1706 setup.py daily sdist bdist_egg # generate both
1707
1708The above commands are interpreted as if the word ``daily`` were replaced with
1709``egg_info --tag-svn-revision --tag-build=development``.
1710
1711Note that setuptools will expand each alias *at most once* in a given command
1712line. This serves two purposes. First, if you accidentally create an alias
1713loop, it will have no effect; you'll instead get an error message about an
1714unknown command. Second, it allows you to define an alias for a command, that
1715uses that command. For example, this (project-local) alias::
1716
1717 setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg
1718
1719redefines the ``bdist_egg`` command so that it always runs the ``rotate``
1720command afterwards to delete all but the newest egg file. It doesn't loop
1721indefinitely on ``bdist_egg`` because the alias is only expanded once when
1722used.
1723
1724You can remove a defined alias with the ``--remove`` (or ``-r``) option, e.g.::
1725
1726 setup.py alias --global-config --remove daily
1727
1728would delete the "daily" alias we defined above.
1729
1730Aliases can be defined on a project-specific, per-user, or sitewide basis. The
1731default is to define or remove a project-specific alias, but you can use any of
1732the `configuration file options`_ (listed under the `saveopts`_ command, below)
1733to determine which distutils configuration file an aliases will be added to
1734(or removed from).
1735
1736Note that if you omit the "expansion" argument to the ``alias`` command,
1737you'll get output showing that alias' current definition (and what
1738configuration file it's defined in). If you omit the alias name as well,
1739you'll get a listing of all current aliases along with their configuration
1740file locations.
1741
1742
1743``bdist_egg`` - Create a Python Egg for the project
1744===================================================
1745
1746This command generates a Python Egg (``.egg`` file) for the project. Python
1747Eggs are the preferred binary distribution format for EasyInstall, because they
1748are cross-platform (for "pure" packages), directly importable, and contain
1749project metadata including scripts and information about the project's
1750dependencies. They can be simply downloaded and added to ``sys.path``
1751directly, or they can be placed in a directory on ``sys.path`` and then
1752automatically discovered by the egg runtime system.
1753
1754This command runs the `egg_info`_ command (if it hasn't already run) to update
1755the project's metadata (``.egg-info``) directory. If you have added any extra
1756metadata files to the ``.egg-info`` directory, those files will be included in
1757the new egg file's metadata directory, for use by the egg runtime system or by
1758any applications or frameworks that use that metadata.
1759
1760You won't usually need to specify any special options for this command; just
1761use ``bdist_egg`` and you're done. But there are a few options that may
1762be occasionally useful:
1763
1764``--dist-dir=DIR, -d DIR``
1765 Set the directory where the ``.egg`` file will be placed. If you don't
1766 supply this, then the ``--dist-dir`` setting of the ``bdist`` command
1767 will be used, which is usually a directory named ``dist`` in the project
1768 directory.
1769
1770``--plat-name=PLATFORM, -p PLATFORM``
1771 Set the platform name string that will be embedded in the egg's filename
1772 (assuming the egg contains C extensions). This can be used to override
1773 the distutils default platform name with something more meaningful. Keep
1774 in mind, however, that the egg runtime system expects to see eggs with
1775 distutils platform names, so it may ignore or reject eggs with non-standard
1776 platform names. Similarly, the EasyInstall program may ignore them when
1777 searching web pages for download links. However, if you are
1778 cross-compiling or doing some other unusual things, you might find a use
1779 for this option.
1780
1781``--exclude-source-files``
1782 Don't include any modules' ``.py`` files in the egg, just compiled Python,
1783 C, and data files. (Note that this doesn't affect any ``.py`` files in the
1784 EGG-INFO directory or its subdirectories, since for example there may be
1785 scripts with a ``.py`` extension which must still be retained.) We don't
1786 recommend that you use this option except for packages that are being
1787 bundled for proprietary end-user applications, or for "embedded" scenarios
1788 where space is at an absolute premium. On the other hand, if your package
1789 is going to be installed and used in compressed form, you might as well
1790 exclude the source because Python's ``traceback`` module doesn't currently
1791 understand how to display zipped source code anyway, or how to deal with
1792 files that are in a different place from where their code was compiled.
1793
1794There are also some options you will probably never need, but which are there
1795because they were copied from similar ``bdist`` commands used as an example for
1796creating this one. They may be useful for testing and debugging, however,
1797which is why we kept them:
1798
1799``--keep-temp, -k``
1800 Keep the contents of the ``--bdist-dir`` tree around after creating the
1801 ``.egg`` file.
1802
1803``--bdist-dir=DIR, -b DIR``
1804 Set the temporary directory for creating the distribution. The entire
1805 contents of this directory are zipped to create the ``.egg`` file, after
1806 running various installation commands to copy the package's modules, data,
1807 and extensions here.
1808
1809``--skip-build``
1810 Skip doing any "build" commands; just go straight to the
1811 install-and-compress phases.
1812
1813
1814.. _develop:
1815
1816``develop`` - Deploy the project source in "Development Mode"
1817=============================================================
1818
1819This command allows you to deploy your project's source for use in one or more
1820"staging areas" where it will be available for importing. This deployment is
1821done in such a way that changes to the project source are immediately available
1822in the staging area(s), without needing to run a build or install step after
1823each change.
1824
1825The ``develop`` command works by creating an ``.egg-link`` file (named for the
1826project) in the given staging area. If the staging area is Python's
1827``site-packages`` directory, it also updates an ``easy-install.pth`` file so
1828that the project is on ``sys.path`` by default for all programs run using that
1829Python installation.
1830
1831The ``develop`` command also installs wrapper scripts in the staging area (or
1832a separate directory, as specified) that will ensure the project's dependencies
1833are available on ``sys.path`` before running the project's source scripts.
1834And, it ensures that any missing project dependencies are available in the
1835staging area, by downloading and installing them if necessary.
1836
1837Last, but not least, the ``develop`` command invokes the ``build_ext -i``
1838command to ensure any C extensions in the project have been built and are
1839up-to-date, and the ``egg_info`` command to ensure the project's metadata is
1840updated (so that the runtime and wrappers know what the project's dependencies
1841are). If you make any changes to the project's setup script or C extensions,
1842you should rerun the ``develop`` command against all relevant staging areas to
1843keep the project's scripts, metadata and extensions up-to-date. Most other
1844kinds of changes to your project should not require any build operations or
1845rerunning ``develop``, but keep in mind that even minor changes to the setup
1846script (e.g. changing an entry point definition) require you to re-run the
1847``develop`` or ``test`` commands to keep the distribution updated.
1848
1849Here are some of the options that the ``develop`` command accepts. Note that
1850they affect the project's dependencies as well as the project itself, so if you
1851have dependencies that need to be installed and you use ``--exclude-scripts``
1852(for example), the dependencies' scripts will not be installed either! For
1853this reason, you may want to use EasyInstall to install the project's
1854dependencies before using the ``develop`` command, if you need finer control
1855over the installation options for dependencies.
1856
1857``--uninstall, -u``
1858 Un-deploy the current project. You may use the ``--install-dir`` or ``-d``
1859 option to designate the staging area. The created ``.egg-link`` file will
1860 be removed, if present and it is still pointing to the project directory.
1861 The project directory will be removed from ``easy-install.pth`` if the
1862 staging area is Python's ``site-packages`` directory.
1863
1864 Note that this option currently does *not* uninstall script wrappers! You
1865 must uninstall them yourself, or overwrite them by using EasyInstall to
1866 activate a different version of the package. You can also avoid installing
1867 script wrappers in the first place, if you use the ``--exclude-scripts``
1868 (aka ``-x``) option when you run ``develop`` to deploy the project.
1869
1870``--multi-version, -m``
1871 "Multi-version" mode. Specifying this option prevents ``develop`` from
1872 adding an ``easy-install.pth`` entry for the project(s) being deployed, and
1873 if an entry for any version of a project already exists, the entry will be
1874 removed upon successful deployment. In multi-version mode, no specific
1875 version of the package is available for importing, unless you use
1876 ``pkg_resources.require()`` to put it on ``sys.path``, or you are running
1877 a wrapper script generated by ``setuptools`` or EasyInstall. (In which
1878 case the wrapper script calls ``require()`` for you.)
1879
1880 Note that if you install to a directory other than ``site-packages``,
1881 this option is automatically in effect, because ``.pth`` files can only be
1882 used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
1883 the ``--install-dir`` or ``-d`` option (or they are set via configuration
1884 file(s)) your project and its dependencies will be deployed in multi-
1885 version mode.
1886
1887``--install-dir=DIR, -d DIR``
1888 Set the installation directory (staging area). If this option is not
1889 directly specified on the command line or in a distutils configuration
1890 file, the distutils default installation location is used. Normally, this
1891 will be the ``site-packages`` directory, but if you are using distutils
1892 configuration files, setting things like ``prefix`` or ``install_lib``,
1893 then those settings are taken into account when computing the default
1894 staging area.
1895
1896``--script-dir=DIR, -s DIR``
1897 Set the script installation directory. If you don't supply this option
1898 (via the command line or a configuration file), but you *have* supplied
1899 an ``--install-dir`` (via command line or config file), then this option
1900 defaults to the same directory, so that the scripts will be able to find
1901 their associated package installation. Otherwise, this setting defaults
1902 to the location where the distutils would normally install scripts, taking
1903 any distutils configuration file settings into account.
1904
1905``--exclude-scripts, -x``
1906 Don't deploy script wrappers. This is useful if you don't want to disturb
1907 existing versions of the scripts in the staging area.
1908
1909``--always-copy, -a``
1910 Copy all needed distributions to the staging area, even if they
1911 are already present in another directory on ``sys.path``. By default, if
1912 a requirement can be met using a distribution that is already available in
1913 a directory on ``sys.path``, it will not be copied to the staging area.
1914
1915``--egg-path=DIR``
1916 Force the generated ``.egg-link`` file to use a specified relative path
1917 to the source directory. This can be useful in circumstances where your
1918 installation directory is being shared by code running under multiple
1919 platforms (e.g. Mac and Windows) which have different absolute locations
1920 for the code under development, but the same *relative* locations with
1921 respect to the installation directory. If you use this option when
1922 installing, you must supply the same relative path when uninstalling.
1923
1924In addition to the above options, the ``develop`` command also accepts all of
1925the same options accepted by ``easy_install``. If you've configured any
1926``easy_install`` settings in your ``setup.cfg`` (or other distutils config
1927files), the ``develop`` command will use them as defaults, unless you override
1928them in a ``[develop]`` section or on the command line.
1929
1930
1931``easy_install`` - Find and install packages
1932============================================
1933
1934This command runs the `EasyInstall tool
1935<http://peak.telecommunity.com/DevCenter/EasyInstall>`_ for you. It is exactly
1936equivalent to running the ``easy_install`` command. All command line arguments
1937following this command are consumed and not processed further by the distutils,
1938so this must be the last command listed on the command line. Please see
1939the EasyInstall documentation for the options reference and usage examples.
1940Normally, there is no reason to use this command via the command line, as you
1941can just use ``easy_install`` directly. It's only listed here so that you know
1942it's a distutils command, which means that you can:
1943
1944* create command aliases that use it,
1945* create distutils extensions that invoke it as a subcommand, and
1946* configure options for it in your ``setup.cfg`` or other distutils config
1947 files.
1948
1949
1950.. _egg_info:
1951
1952``egg_info`` - Create egg metadata and set build tags
1953=====================================================
1954
1955This command performs two operations: it updates a project's ``.egg-info``
1956metadata directory (used by the ``bdist_egg``, ``develop``, and ``test``
1957commands), and it allows you to temporarily change a project's version string,
1958to support "daily builds" or "snapshot" releases. It is run automatically by
1959the ``sdist``, ``bdist_egg``, ``develop``, ``register``, and ``test`` commands
1960in order to update the project's metadata, but you can also specify it
1961explicitly in order to temporarily change the project's version string while
1962executing other commands. (It also generates the``.egg-info/SOURCES.txt``
1963manifest file, which is used when you are building source distributions.)
1964
1965In addition to writing the core egg metadata defined by ``setuptools`` and
1966required by ``pkg_resources``, this command can be extended to write other
1967metadata files as well, by defining entry points in the ``egg_info.writers``
1968group. See the section on `Adding new EGG-INFO Files`_ below for more details.
1969Note that using additional metadata writers may require you to include a
1970``setup_requires`` argument to ``setup()`` in order to ensure that the desired
1971writers are available on ``sys.path``.
1972
1973
1974Release Tagging Options
1975-----------------------
1976
1977The following options can be used to modify the project's version string for
1978all remaining commands on the setup command line. The options are processed
1979in the order shown, so if you use more than one, the requested tags will be
1980added in the following order:
1981
1982``--tag-build=NAME, -b NAME``
1983 Append NAME to the project's version string. Due to the way setuptools
1984 processes "pre-release" version suffixes beginning with the letters "a"
1985 through "e" (like "alpha", "beta", and "candidate"), you will usually want
1986 to use a tag like ".build" or ".dev", as this will cause the version number
1987 to be considered *lower* than the project's default version. (If you
1988 want to make the version number *higher* than the default version, you can
1989 always leave off --tag-build and then use one or both of the following
1990 options.)
1991
1992 If you have a default build tag set in your ``setup.cfg``, you can suppress
1993 it on the command line using ``-b ""`` or ``--tag-build=""`` as an argument
1994 to the ``egg_info`` command.
1995
1996``--tag-svn-revision, -r``
1997 If the current directory is a Subversion checkout (i.e. has a ``.svn``
1998 subdirectory, this appends a string of the form "-rNNNN" to the project's
1999 version string, where NNNN is the revision number of the most recent
2000 modification to the current directory, as obtained from the ``svn info``
2001 command.
2002
2003 If the current directory is not a Subversion checkout, the command will
2004 look for a ``PKG-INFO`` file instead, and try to find the revision number
2005 from that, by looking for a "-rNNNN" string at the end of the version
2006 number. (This is so that building a package from a source distribution of
2007 a Subversion snapshot will produce a binary with the correct version
2008 number.)
2009
2010 If there is no ``PKG-INFO`` file, or the version number contained therein
2011 does not end with ``-r`` and a number, then ``-r0`` is used.
2012
2013``--no-svn-revision, -R``
2014 Don't include the Subversion revision in the version number. This option
2015 is included so you can override a default setting put in ``setup.cfg``.
2016
2017``--tag-date, -d``
2018 Add a date stamp of the form "-YYYYMMDD" (e.g. "-20050528") to the
2019 project's version number.
2020
2021``--no-date, -D``
2022 Don't include a date stamp in the version number. This option is included
2023 so you can override a default setting in ``setup.cfg``.
2024
2025
2026(Note: Because these options modify the version number used for source and
2027binary distributions of your project, you should first make sure that you know
2028how the resulting version numbers will be interpreted by automated tools
2029like EasyInstall. See the section above on `Specifying Your Project's
2030Version`_ for an explanation of pre- and post-release tags, as well as tips on
2031how to choose and verify a versioning scheme for your your project.)
2032
2033For advanced uses, there is one other option that can be set, to change the
2034location of the project's ``.egg-info`` directory. Commands that need to find
2035the project's source directory or metadata should get it from this setting:
2036
2037
2038Other ``egg_info`` Options
2039--------------------------
2040
2041``--egg-base=SOURCEDIR, -e SOURCEDIR``
2042 Specify the directory that should contain the .egg-info directory. This
2043 should normally be the root of your project's source tree (which is not
2044 necessarily the same as your project directory; some projects use a ``src``
2045 or ``lib`` subdirectory as the source root). You should not normally need
2046 to specify this directory, as it is normally determined from the
2047 ``package_dir`` argument to the ``setup()`` function, if any. If there is
2048 no ``package_dir`` set, this option defaults to the current directory.
2049
2050
2051``egg_info`` Examples
2052---------------------
2053
2054Creating a dated "nightly build" snapshot egg::
2055
2056 python setup.py egg_info --tag-date --tag-build=DEV bdist_egg
2057
2058Creating and uploading a release with no version tags, even if some default
2059tags are specified in ``setup.cfg``::
2060
2061 python setup.py egg_info -RDb "" sdist bdist_egg register upload
2062
2063(Notice that ``egg_info`` must always appear on the command line *before* any
2064commands that you want the version changes to apply to.)
2065
2066
2067.. _install command:
2068
2069``install`` - Run ``easy_install`` or old-style installation
2070============================================================
2071
2072The setuptools ``install`` command is basically a shortcut to run the
2073``easy_install`` command on the current project. However, for convenience
2074in creating "system packages" of setuptools-based projects, you can also
2075use this option:
2076
2077``--single-version-externally-managed``
2078 This boolean option tells the ``install`` command to perform an "old style"
2079 installation, with the addition of an ``.egg-info`` directory so that the
2080 installed project will still have its metadata available and operate
2081 normally. If you use this option, you *must* also specify the ``--root``
2082 or ``--record`` options (or both), because otherwise you will have no way
2083 to identify and remove the installed files.
2084
2085This option is automatically in effect when ``install`` is invoked by another
2086distutils command, so that commands like ``bdist_wininst`` and ``bdist_rpm``
2087will create system packages of eggs. It is also automatically in effect if
2088you specify the ``--root`` option.
2089
2090
2091``install_egg_info`` - Install an ``.egg-info`` directory in ``site-packages``
2092==============================================================================
2093
2094Setuptools runs this command as part of ``install`` operations that use the
2095``--single-version-externally-managed`` options. You should not invoke it
2096directly; it is documented here for completeness and so that distutils
2097extensions such as system package builders can make use of it. This command
2098has only one option:
2099
2100``--install-dir=DIR, -d DIR``
2101 The parent directory where the ``.egg-info`` directory will be placed.
2102 Defaults to the same as the ``--install-dir`` option specified for the
2103 ``install_lib`` command, which is usually the system ``site-packages``
2104 directory.
2105
2106This command assumes that the ``egg_info`` command has been given valid options
2107via the command line or ``setup.cfg``, as it will invoke the ``egg_info``
2108command and use its options to locate the project's source ``.egg-info``
2109directory.
2110
2111
2112.. _rotate:
2113
2114``rotate`` - Delete outdated distribution files
2115===============================================
2116
2117As you develop new versions of your project, your distribution (``dist``)
2118directory will gradually fill up with older source and/or binary distribution
2119files. The ``rotate`` command lets you automatically clean these up, keeping
2120only the N most-recently modified files matching a given pattern.
2121
2122``--match=PATTERNLIST, -m PATTERNLIST``
2123 Comma-separated list of glob patterns to match. This option is *required*.
2124 The project name and ``-*`` is prepended to the supplied patterns, in order
2125 to match only distributions belonging to the current project (in case you
2126 have a shared distribution directory for multiple projects). Typically,
2127 you will use a glob pattern like ``.zip`` or ``.egg`` to match files of
2128 the specified type. Note that each supplied pattern is treated as a
2129 distinct group of files for purposes of selecting files to delete.
2130
2131``--keep=COUNT, -k COUNT``
2132 Number of matching distributions to keep. For each group of files
2133 identified by a pattern specified with the ``--match`` option, delete all
2134 but the COUNT most-recently-modified files in that group. This option is
2135 *required*.
2136
2137``--dist-dir=DIR, -d DIR``
2138 Directory where the distributions are. This defaults to the value of the
2139 ``bdist`` command's ``--dist-dir`` option, which will usually be the
2140 project's ``dist`` subdirectory.
2141
2142**Example 1**: Delete all .tar.gz files from the distribution directory, except
2143for the 3 most recently modified ones::
2144
2145 setup.py rotate --match=.tar.gz --keep=3
2146
2147**Example 2**: Delete all Python 2.3 or Python 2.4 eggs from the distribution
2148directory, except the most recently modified one for each Python version::
2149
2150 setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1
2151
2152
2153.. _saveopts:
2154
2155``saveopts`` - Save used options to a configuration file
2156========================================================
2157
2158Finding and editing ``distutils`` configuration files can be a pain, especially
2159since you also have to translate the configuration options from command-line
2160form to the proper configuration file format. You can avoid these hassles by
2161using the ``saveopts`` command. Just add it to the command line to save the
2162options you used. For example, this command builds the project using
2163the ``mingw32`` C compiler, then saves the --compiler setting as the default
2164for future builds (even those run implicitly by the ``install`` command)::
2165
2166 setup.py build --compiler=mingw32 saveopts
2167
2168The ``saveopts`` command saves all options for every commmand specified on the
2169command line to the project's local ``setup.cfg`` file, unless you use one of
2170the `configuration file options`_ to change where the options are saved. For
2171example, this command does the same as above, but saves the compiler setting
2172to the site-wide (global) distutils configuration::
2173
2174 setup.py build --compiler=mingw32 saveopts -g
2175
2176Note that it doesn't matter where you place the ``saveopts`` command on the
2177command line; it will still save all the options specified for all commands.
2178For example, this is another valid way to spell the last example::
2179
2180 setup.py saveopts -g build --compiler=mingw32
2181
2182Note, however, that all of the commands specified are always run, regardless of
2183where ``saveopts`` is placed on the command line.
2184
2185
2186Configuration File Options
2187--------------------------
2188
2189Normally, settings such as options and aliases are saved to the project's
2190local ``setup.cfg`` file. But you can override this and save them to the
2191global or per-user configuration files, or to a manually-specified filename.
2192
2193``--global-config, -g``
2194 Save settings to the global ``distutils.cfg`` file inside the ``distutils``
2195 package directory. You must have write access to that directory to use
2196 this option. You also can't combine this option with ``-u`` or ``-f``.
2197
2198``--user-config, -u``
2199 Save settings to the current user's ``~/.pydistutils.cfg`` (POSIX) or
2200 ``$HOME/pydistutils.cfg`` (Windows) file. You can't combine this option
2201 with ``-g`` or ``-f``.
2202
2203``--filename=FILENAME, -f FILENAME``
2204 Save settings to the specified configuration file to use. You can't
2205 combine this option with ``-g`` or ``-u``. Note that if you specify a
2206 non-standard filename, the ``distutils`` and ``setuptools`` will not
2207 use the file's contents. This option is mainly included for use in
2208 testing.
2209
2210These options are used by other ``setuptools`` commands that modify
2211configuration files, such as the `alias`_ and `setopt`_ commands.
2212
2213
2214.. _setopt:
2215
2216``setopt`` - Set a distutils or setuptools option in a config file
2217==================================================================
2218
2219This command is mainly for use by scripts, but it can also be used as a quick
2220and dirty way to change a distutils configuration option without having to
2221remember what file the options are in and then open an editor.
2222
2223**Example 1**. Set the default C compiler to ``mingw32`` (using long option
2224names)::
2225
2226 setup.py setopt --command=build --option=compiler --set-value=mingw32
2227
2228**Example 2**. Remove any setting for the distutils default package
2229installation directory (short option names)::
2230
2231 setup.py setopt -c install -o install_lib -r
2232
2233
2234Options for the ``setopt`` command:
2235
2236``--command=COMMAND, -c COMMAND``
2237 Command to set the option for. This option is required.
2238
2239``--option=OPTION, -o OPTION``
2240 The name of the option to set. This option is required.
2241
2242``--set-value=VALUE, -s VALUE``
2243 The value to set the option to. Not needed if ``-r`` or ``--remove`` is
2244 set.
2245
2246``--remove, -r``
2247 Remove (unset) the option, instead of setting it.
2248
2249In addition to the above options, you may use any of the `configuration file
2250options`_ (listed under the `saveopts`_ command, above) to determine which
2251distutils configuration file the option will be added to (or removed from).
2252
2253
2254.. _test:
2255
2256``test`` - Build package and run a unittest suite
2257=================================================
2258
2259When doing test-driven development, or running automated builds that need
2260testing before they are deployed for downloading or use, it's often useful
2261to be able to run a project's unit tests without actually deploying the project
2262anywhere, even using the ``develop`` command. The ``test`` command runs a
2263project's unit tests without actually deploying it, by temporarily putting the
2264project's source on ``sys.path``, after first running ``build_ext -i`` and
2265``egg_info`` to ensure that any C extensions and project metadata are
2266up-to-date.
2267
2268To use this command, your project's tests must be wrapped in a ``unittest``
2269test suite by either a function, a ``TestCase`` class or method, or a module
2270or package containing ``TestCase`` classes. If the named suite is a module,
2271and the module has an ``additional_tests()`` function, it is called and the
2272result (which must be a ``unittest.TestSuite``) is added to the tests to be
2273run. If the named suite is a package, any submodules and subpackages are
2274recursively added to the overall test suite. (Note: if your project specifies
2275a ``test_loader``, the rules for processing the chosen ``test_suite`` may
2276differ; see the `test_loader`_ documentation for more details.)
2277
2278Note that many test systems including ``doctest`` support wrapping their
2279non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test
2280package that does not support this, we suggest you encourage its developers to
2281implement test suite support, as this is a convenient and standard way to
2282aggregate a collection of tests to be run under a common test harness.
2283
2284By default, tests will be run in the "verbose" mode of the ``unittest``
2285package's text test runner, but you can get the "quiet" mode (just dots) if
2286you supply the ``-q`` or ``--quiet`` option, either as a global option to
2287the setup script (e.g. ``setup.py -q test``) or as an option for the ``test``
2288command itself (e.g. ``setup.py test -q``). There is one other option
2289available:
2290
2291``--test-suite=NAME, -s NAME``
2292 Specify the test suite (or module, class, or method) to be run
2293 (e.g. ``some_module.test_suite``). The default for this option can be
2294 set by giving a ``test_suite`` argument to the ``setup()`` function, e.g.::
2295
2296 setup(
2297 # ...
2298 test_suite = "my_package.tests.test_all"
2299 )
2300
2301 If you did not set a ``test_suite`` in your ``setup()`` call, and do not
2302 provide a ``--test-suite`` option, an error will occur.
2303
2304
2305.. _upload:
2306
2307``upload`` - Upload source and/or egg distributions to PyPI
2308===========================================================
2309
2310PyPI now supports uploading project files for redistribution; uploaded files
2311are easily found by EasyInstall, even if you don't have download links on your
2312project's home page.
2313
2314Although Python 2.5 will support uploading all types of distributions to PyPI,
2315setuptools only supports source distributions and eggs. (This is partly
2316because PyPI's upload support is currently broken for various other file
2317types.) To upload files, you must include the ``upload`` command *after* the
2318``sdist`` or ``bdist_egg`` commands on the setup command line. For example::
2319
2320 setup.py bdist_egg upload # create an egg and upload it
2321 setup.py sdist upload # create a source distro and upload it
2322 setup.py sdist bdist_egg upload # create and upload both
2323
2324Note that to upload files for a project, the corresponding version must already
2325be registered with PyPI, using the distutils ``register`` command. It's
2326usually a good idea to include the ``register`` command at the start of the
2327command line, so that any registration problems can be found and fixed before
2328building and uploading the distributions, e.g.::
2329
2330 setup.py register sdist bdist_egg upload
2331
2332This will update PyPI's listing for your project's current version.
2333
2334Note, by the way, that the metadata in your ``setup()`` call determines what
2335will be listed in PyPI for your package. Try to fill out as much of it as
2336possible, as it will save you a lot of trouble manually adding and updating
2337your PyPI listings. Just put it in ``setup.py`` and use the ``register``
2338comamnd to keep PyPI up to date.
2339
2340The ``upload`` command has a few options worth noting:
2341
2342``--sign, -s``
2343 Sign each uploaded file using GPG (GNU Privacy Guard). The ``gpg`` program
2344 must be available for execution on the system ``PATH``.
2345
2346``--identity=NAME, -i NAME``
2347 Specify the identity or key name for GPG to use when signing. The value of
2348 this option will be passed through the ``--local-user`` option of the
2349 ``gpg`` program.
2350
2351``--show-response``
2352 Display the full response text from server; this is useful for debugging
2353 PyPI problems.
2354
2355``--repository=URL, -r URL``
2356 The URL of the repository to upload to. Defaults to
2357 http://pypi.python.org/pypi (i.e., the main PyPI installation).
2358
2359
2360------------------------------------
2361Extending and Reusing ``setuptools``
2362------------------------------------
2363
2364Creating ``distutils`` Extensions
2365=================================
2366
2367It can be hard to add new commands or setup arguments to the distutils. But
2368the ``setuptools`` package makes it a bit easier, by allowing you to distribute
2369a distutils extension as a separate project, and then have projects that need
2370the extension just refer to it in their ``setup_requires`` argument.
2371
2372With ``setuptools``, your distutils extension projects can hook in new
2373commands and ``setup()`` arguments just by defining "entry points". These
2374are mappings from command or argument names to a specification of where to
2375import a handler from. (See the section on `Dynamic Discovery of Services and
2376Plugins`_ above for some more background on entry points.)
2377
2378
2379Adding Commands
2380---------------
2381
2382You can add new ``setup`` commands by defining entry points in the
2383``distutils.commands`` group. For example, if you wanted to add a ``foo``
2384command, you might add something like this to your distutils extension
2385project's setup script::
2386
2387 setup(
2388 # ...
2389 entry_points = {
2390 "distutils.commands": [
2391 "foo = mypackage.some_module:foo",
2392 ],
2393 },
2394 )
2395
2396(Assuming, of course, that the ``foo`` class in ``mypackage.some_module`` is
2397a ``setuptools.Command`` subclass.)
2398
2399Once a project containing such entry points has been activated on ``sys.path``,
2400(e.g. by running "install" or "develop" with a site-packages installation
2401directory) the command(s) will be available to any ``setuptools``-based setup
2402scripts. It is not necessary to use the ``--command-packages`` option or
2403to monkeypatch the ``distutils.command`` package to install your commands;
2404``setuptools`` automatically adds a wrapper to the distutils to search for
2405entry points in the active distributions on ``sys.path``. In fact, this is
2406how setuptools' own commands are installed: the setuptools project's setup
2407script defines entry points for them!
2408
2409
2410Adding ``setup()`` Arguments
2411----------------------------
2412
2413Sometimes, your commands may need additional arguments to the ``setup()``
2414call. You can enable this by defining entry points in the
2415``distutils.setup_keywords`` group. For example, if you wanted a ``setup()``
2416argument called ``bar_baz``, you might add something like this to your
2417distutils extension project's setup script::
2418
2419 setup(
2420 # ...
2421 entry_points = {
2422 "distutils.commands": [
2423 "foo = mypackage.some_module:foo",
2424 ],
2425 "distutils.setup_keywords": [
2426 "bar_baz = mypackage.some_module:validate_bar_baz",
2427 ],
2428 },
2429 )
2430
2431The idea here is that the entry point defines a function that will be called
2432to validate the ``setup()`` argument, if it's supplied. The ``Distribution``
2433object will have the initial value of the attribute set to ``None``, and the
2434validation function will only be called if the ``setup()`` call sets it to
2435a non-None value. Here's an example validation function::
2436
2437 def assert_bool(dist, attr, value):
2438 """Verify that value is True, False, 0, or 1"""
2439 if bool(value) != value:
2440 raise DistutilsSetupError(
2441 "%r must be a boolean value (got %r)" % (attr,value)
2442 )
2443
2444Your function should accept three arguments: the ``Distribution`` object,
2445the attribute name, and the attribute value. It should raise a
2446``DistutilsSetupError`` (from the ``distutils.error`` module) if the argument
2447is invalid. Remember, your function will only be called with non-None values,
2448and the default value of arguments defined this way is always None. So, your
2449commands should always be prepared for the possibility that the attribute will
2450be ``None`` when they access it later.
2451
2452If more than one active distribution defines an entry point for the same
2453``setup()`` argument, *all* of them will be called. This allows multiple
2454distutils extensions to define a common argument, as long as they agree on
2455what values of that argument are valid.
2456
2457Also note that as with commands, it is not necessary to subclass or monkeypatch
2458the distutils ``Distribution`` class in order to add your arguments; it is
2459sufficient to define the entry points in your extension, as long as any setup
2460script using your extension lists your project in its ``setup_requires``
2461argument.
2462
2463
2464Adding new EGG-INFO Files
2465-------------------------
2466
2467Some extensible applications or frameworks may want to allow third parties to
2468develop plugins with application or framework-specific metadata included in
2469the plugins' EGG-INFO directory, for easy access via the ``pkg_resources``
2470metadata API. The easiest way to allow this is to create a distutils extension
2471to be used from the plugin projects' setup scripts (via ``setup_requires``)
2472that defines a new setup keyword, and then uses that data to write an EGG-INFO
2473file when the ``egg_info`` command is run.
2474
2475The ``egg_info`` command looks for extension points in an ``egg_info.writers``
2476group, and calls them to write the files. Here's a simple example of a
2477distutils extension defining a setup argument ``foo_bar``, which is a list of
2478lines that will be written to ``foo_bar.txt`` in the EGG-INFO directory of any
2479project that uses the argument::
2480
2481 setup(
2482 # ...
2483 entry_points = {
2484 "distutils.setup_keywords": [
2485 "foo_bar = setuptools.dist:assert_string_list",
2486 ],
2487 "egg_info.writers": [
2488 "foo_bar.txt = setuptools.command.egg_info:write_arg",
2489 ],
2490 },
2491 )
2492
2493This simple example makes use of two utility functions defined by setuptools
2494for its own use: a routine to validate that a setup keyword is a sequence of
2495strings, and another one that looks up a setup argument and writes it to
2496a file. Here's what the writer utility looks like::
2497
2498 def write_arg(cmd, basename, filename):
2499 argname = os.path.splitext(basename)[0]
2500 value = getattr(cmd.distribution, argname, None)
2501 if value is not None:
2502 value = '\n'.join(value)+'\n'
2503 cmd.write_or_delete_file(argname, filename, value)
2504
2505As you can see, ``egg_info.writers`` entry points must be a function taking
2506three arguments: a ``egg_info`` command instance, the basename of the file to
2507write (e.g. ``foo_bar.txt``), and the actual full filename that should be
2508written to.
2509
2510In general, writer functions should honor the command object's ``dry_run``
2511setting when writing files, and use the ``distutils.log`` object to do any
2512console output. The easiest way to conform to this requirement is to use
2513the ``cmd`` object's ``write_file()``, ``delete_file()``, and
2514``write_or_delete_file()`` methods exclusively for your file operations. See
2515those methods' docstrings for more details.
2516
2517
2518Adding Support for Other Revision Control Systems
2519-------------------------------------------------
2520
2521If you would like to create a plugin for ``setuptools`` to find files in other
2522source control systems besides CVS and Subversion, you can do so by adding an
2523entry point to the ``setuptools.file_finders`` group. The entry point should
2524be a function accepting a single directory name, and should yield
2525all the filenames within that directory (and any subdirectories thereof) that
2526are under revision control.
2527
2528For example, if you were going to create a plugin for a revision control system
2529called "foobar", you would write a function something like this::
2530
2531 def find_files_for_foobar(dirname):
2532 # loop to yield paths that start with `dirname`
2533
2534And you would register it in a setup script using something like this::
2535
2536 entry_points = {
2537 "setuptools.file_finders": [
2538 "foobar = my_foobar_module:find_files_for_foobar"
2539 ]
2540 }
2541
2542Then, anyone who wants to use your plugin can simply install it, and their
2543local setuptools installation will be able to find the necessary files.
2544
2545It is not necessary to distribute source control plugins with projects that
2546simply use the other source control system, or to specify the plugins in
2547``setup_requires``. When you create a source distribution with the ``sdist``
2548command, setuptools automatically records what files were found in the
2549``SOURCES.txt`` file. That way, recipients of source distributions don't need
2550to have revision control at all. However, if someone is working on a package
2551by checking out with that system, they will need the same plugin(s) that the
2552original author is using.
2553
2554A few important points for writing revision control file finders:
2555
2556* Your finder function MUST return relative paths, created by appending to the
2557 passed-in directory name. Absolute paths are NOT allowed, nor are relative
2558 paths that reference a parent directory of the passed-in directory.
2559
2560* Your finder function MUST accept an empty string as the directory name,
2561 meaning the current directory. You MUST NOT convert this to a dot; just
2562 yield relative paths. So, yielding a subdirectory named ``some/dir`` under
2563 the current directory should NOT be rendered as ``./some/dir`` or
2564 ``/somewhere/some/dir``, but *always* as simply ``some/dir``
2565
2566* Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully
2567 with the absence of needed programs (i.e., ones belonging to the revision
2568 control system itself. It *may*, however, use ``distutils.log.warn()`` to
2569 inform the user of the missing program(s).
2570
2571
2572Subclassing ``Command``
2573-----------------------
2574
2575Sorry, this section isn't written yet, and neither is a lot of what's below
2576this point, except for the change log. You might want to `subscribe to changes
2577in this page <setuptools?action=subscribe>`_ to see when new documentation is
2578added or updated.
2579
2580XXX
2581
2582
2583Reusing ``setuptools`` Code
2584===========================
2585
2586``ez_setup``
2587------------
2588
2589XXX
2590
2591
2592``setuptools.archive_util``
2593---------------------------
2594
2595XXX
2596
2597
2598``setuptools.sandbox``
2599----------------------
2600
2601XXX
2602
2603
2604``setuptools.package_index``
2605----------------------------
2606
2607XXX
2608
2609
2610----------------------------
2611Release Notes/Change History
2612----------------------------
2613
26140.6final
2615 * Fixed a missing files problem when using Windows source distributions on
2616 non-Windows platforms, due to distutils not handling manifest file line
2617 endings correctly.
2618
2619 * Updated Pyrex support to work with Pyrex 0.9.6 and higher.
2620
2621 * Minor changes for Jython compatibility, including skipping tests that can't
2622 work on Jython.
2623
2624 * Fixed not installing eggs in ``install_requires`` if they were also used for
2625 ``setup_requires`` or ``tests_require``.
2626
2627 * Fixed not fetching eggs in ``install_requires`` when running tests.
2628
2629 * Allow ``ez_setup.use_setuptools()`` to upgrade existing setuptools
2630 installations when called from a standalone ``setup.py``.
2631
2632 * Added a warning if a namespace package is declared, but its parent package
2633 is not also declared as a namespace.
2634
2635 * Support Subversion 1.5
2636
2637 * Removed use of deprecated ``md5`` module if ``hashlib`` is available
2638
2639 * Fixed ``bdist_wininst upload`` trying to upload the ``.exe`` twice
2640
2641 * Fixed ``bdist_egg`` putting a ``native_libs.txt`` in the source package's
2642 ``.egg-info``, when it should only be in the built egg's ``EGG-INFO``.
2643
2644 * Ensure that _full_name is set on all shared libs before extensions are
2645 checked for shared lib usage. (Fixes a bug in the experimental shared
2646 library build support.)
2647
2648 * Fix to allow unpacked eggs containing native libraries to fail more
2649 gracefully under Google App Engine (with an ``ImportError`` loading the
2650 C-based module, instead of getting a ``NameError``).
2651
26520.6c7
2653 * Fixed ``distutils.filelist.findall()`` crashing on broken symlinks, and
2654 ``egg_info`` command failing on new, uncommitted SVN directories.
2655
2656 * Fix import problems with nested namespace packages installed via
2657 ``--root`` or ``--single-version-externally-managed``, due to the
2658 parent package not having the child package as an attribute.
2659
26600.6c6
2661 * Added ``--egg-path`` option to ``develop`` command, allowing you to force
2662 ``.egg-link`` files to use relative paths (allowing them to be shared across
2663 platforms on a networked drive).
2664
2665 * Fix not building binary RPMs correctly.
2666
2667 * Fix "eggsecutables" (such as setuptools' own egg) only being runnable with
2668 bash-compatible shells.
2669
2670 * Fix ``#!`` parsing problems in Windows ``.exe`` script wrappers, when there
2671 was whitespace inside a quoted argument or at the end of the ``#!`` line
2672 (a regression introduced in 0.6c4).
2673
2674 * Fix ``test`` command possibly failing if an older version of the project
2675 being tested was installed on ``sys.path`` ahead of the test source
2676 directory.
2677
2678 * Fix ``find_packages()`` treating ``ez_setup`` and directories with ``.`` in
2679 their names as packages.
2680
26810.6c5
2682 * Fix uploaded ``bdist_rpm`` packages being described as ``bdist_egg``
2683 packages under Python versions less than 2.5.
2684
2685 * Fix uploaded ``bdist_wininst`` packages being described as suitable for
2686 "any" version by Python 2.5, even if a ``--target-version`` was specified.
2687
26880.6c4
2689 * Overhauled Windows script wrapping to support ``bdist_wininst`` better.
2690 Scripts installed with ``bdist_wininst`` will always use ``#!python.exe`` or
2691 ``#!pythonw.exe`` as the executable name (even when built on non-Windows
2692 platforms!), and the wrappers will look for the executable in the script's
2693 parent directory (which should find the right version of Python).
2694
2695 * Fix ``upload`` command not uploading files built by ``bdist_rpm`` or
2696 ``bdist_wininst`` under Python 2.3 and 2.4.
2697
2698 * Add support for "eggsecutable" headers: a ``#!/bin/sh`` script that is
2699 prepended to an ``.egg`` file to allow it to be run as a script on Unix-ish
2700 platforms. (This is mainly so that setuptools itself can have a single-file
2701 installer on Unix, without doing multiple downloads, dealing with firewalls,
2702 etc.)
2703
2704 * Fix problem with empty revision numbers in Subversion 1.4 ``entries`` files
2705
2706 * Use cross-platform relative paths in ``easy-install.pth`` when doing
2707 ``develop`` and the source directory is a subdirectory of the installation
2708 target directory.
2709
2710 * Fix a problem installing eggs with a system packaging tool if the project
2711 contained an implicit namespace package; for example if the ``setup()``
2712 listed a namespace package ``foo.bar`` without explicitly listing ``foo``
2713 as a namespace package.
2714
27150.6c3
2716 * Fixed breakages caused by Subversion 1.4's new "working copy" format
2717
27180.6c2
2719 * The ``ez_setup`` module displays the conflicting version of setuptools (and
2720 its installation location) when a script requests a version that's not
2721 available.
2722
2723 * Running ``setup.py develop`` on a setuptools-using project will now install
2724 setuptools if needed, instead of only downloading the egg.
2725
27260.6c1
2727 * Fixed ``AttributeError`` when trying to download a ``setup_requires``
2728 dependency when a distribution lacks a ``dependency_links`` setting.
2729
2730 * Made ``zip-safe`` and ``not-zip-safe`` flag files contain a single byte, so
2731 as to play better with packaging tools that complain about zero-length
2732 files.
2733
2734 * Made ``setup.py develop`` respect the ``--no-deps`` option, which it
2735 previously was ignoring.
2736
2737 * Support ``extra_path`` option to ``setup()`` when ``install`` is run in
2738 backward-compatibility mode.
2739
2740 * Source distributions now always include a ``setup.cfg`` file that explicitly
2741 sets ``egg_info`` options such that they produce an identical version number
2742 to the source distribution's version number. (Previously, the default
2743 version number could be different due to the use of ``--tag-date``, or if
2744 the version was overridden on the command line that built the source
2745 distribution.)
2746
27470.6b4
2748 * Fix ``register`` not obeying name/version set by ``egg_info`` command, if
2749 ``egg_info`` wasn't explicitly run first on the same command line.
2750
2751 * Added ``--no-date`` and ``--no-svn-revision`` options to ``egg_info``
2752 command, to allow suppressing tags configured in ``setup.cfg``.
2753
2754 * Fixed redundant warnings about missing ``README`` file(s); it should now
2755 appear only if you are actually a source distribution.
2756
27570.6b3
2758 * Fix ``bdist_egg`` not including files in subdirectories of ``.egg-info``.
2759
2760 * Allow ``.py`` files found by the ``include_package_data`` option to be
2761 automatically included. Remove duplicate data file matches if both
2762 ``include_package_data`` and ``package_data`` are used to refer to the same
2763 files.
2764
27650.6b1
2766 * Strip ``module`` from the end of compiled extension modules when computing
2767 the name of a ``.py`` loader/wrapper. (Python's import machinery ignores
2768 this suffix when searching for an extension module.)
2769
27700.6a11
2771 * Added ``test_loader`` keyword to support custom test loaders
2772
2773 * Added ``setuptools.file_finders`` entry point group to allow implementing
2774 revision control plugins.
2775
2776 * Added ``--identity`` option to ``upload`` command.
2777
2778 * Added ``dependency_links`` to allow specifying URLs for ``--find-links``.
2779
2780 * Enhanced test loader to scan packages as well as modules, and call
2781 ``additional_tests()`` if present to get non-unittest tests.
2782
2783 * Support namespace packages in conjunction with system packagers, by omitting
2784 the installation of any ``__init__.py`` files for namespace packages, and
2785 adding a special ``.pth`` file to create a working package in
2786 ``sys.modules``.
2787
2788 * Made ``--single-version-externally-managed`` automatic when ``--root`` is
2789 used, so that most system packagers won't require special support for
2790 setuptools.
2791
2792 * Fixed ``setup_requires``, ``tests_require``, etc. not using ``setup.cfg`` or
2793 other configuration files for their option defaults when installing, and
2794 also made the install use ``--multi-version`` mode so that the project
2795 directory doesn't need to support .pth files.
2796
2797 * ``MANIFEST.in`` is now forcibly closed when any errors occur while reading
2798 it. Previously, the file could be left open and the actual error would be
2799 masked by problems trying to remove the open file on Windows systems.
2800
28010.6a10
2802 * Fixed the ``develop`` command ignoring ``--find-links``.
2803
28040.6a9
2805 * The ``sdist`` command no longer uses the traditional ``MANIFEST`` file to
2806 create source distributions. ``MANIFEST.in`` is still read and processed,
2807 as are the standard defaults and pruning. But the manifest is built inside
2808 the project's ``.egg-info`` directory as ``SOURCES.txt``, and it is rebuilt
2809 every time the ``egg_info`` command is run.
2810
2811 * Added the ``include_package_data`` keyword to ``setup()``, allowing you to
2812 automatically include any package data listed in revision control or
2813 ``MANIFEST.in``
2814
2815 * Added the ``exclude_package_data`` keyword to ``setup()``, allowing you to
2816 trim back files included via the ``package_data`` and
2817 ``include_package_data`` options.
2818
2819 * Fixed ``--tag-svn-revision`` not working when run from a source
2820 distribution.
2821
2822 * Added warning for namespace packages with missing ``declare_namespace()``
2823
2824 * Added ``tests_require`` keyword to ``setup()``, so that e.g. packages
2825 requiring ``nose`` to run unit tests can make this dependency optional
2826 unless the ``test`` command is run.
2827
2828 * Made all commands that use ``easy_install`` respect its configuration
2829 options, as this was causing some problems with ``setup.py install``.
2830
2831 * Added an ``unpack_directory()`` driver to ``setuptools.archive_util``, so
2832 that you can process a directory tree through a processing filter as if it
2833 were a zipfile or tarfile.
2834
2835 * Added an internal ``install_egg_info`` command to use as part of old-style
2836 ``install`` operations, that installs an ``.egg-info`` directory with the
2837 package.
2838
2839 * Added a ``--single-version-externally-managed`` option to the ``install``
2840 command so that you can more easily wrap a "flat" egg in a system package.
2841
2842 * Enhanced ``bdist_rpm`` so that it installs single-version eggs that
2843 don't rely on a ``.pth`` file. The ``--no-egg`` option has been removed,
2844 since all RPMs are now built in a more backwards-compatible format.
2845
2846 * Support full roundtrip translation of eggs to and from ``bdist_wininst``
2847 format. Running ``bdist_wininst`` on a setuptools-based package wraps the
2848 egg in an .exe that will safely install it as an egg (i.e., with metadata
2849 and entry-point wrapper scripts), and ``easy_install`` can turn the .exe
2850 back into an ``.egg`` file or directory and install it as such.
2851
2852
28530.6a8
2854 * Fixed some problems building extensions when Pyrex was installed, especially
2855 with Python 2.4 and/or packages using SWIG.
2856
2857 * Made ``develop`` command accept all the same options as ``easy_install``,
2858 and use the ``easy_install`` command's configuration settings as defaults.
2859
2860 * Made ``egg_info --tag-svn-revision`` fall back to extracting the revision
2861 number from ``PKG-INFO`` in case it is being run on a source distribution of
2862 a snapshot taken from a Subversion-based project.
2863
2864 * Automatically detect ``.dll``, ``.so`` and ``.dylib`` files that are being
2865 installed as data, adding them to ``native_libs.txt`` automatically.
2866
2867 * Fixed some problems with fresh checkouts of projects that don't include
2868 ``.egg-info/PKG-INFO`` under revision control and put the project's source
2869 code directly in the project directory. If such a package had any
2870 requirements that get processed before the ``egg_info`` command can be run,
2871 the setup scripts would fail with a "Missing 'Version:' header and/or
2872 PKG-INFO file" error, because the egg runtime interpreted the unbuilt
2873 metadata in a directory on ``sys.path`` (i.e. the current directory) as
2874 being a corrupted egg. Setuptools now monkeypatches the distribution
2875 metadata cache to pretend that the egg has valid version information, until
2876 it has a chance to make it actually be so (via the ``egg_info`` command).
2877
28780.6a5
2879 * Fixed missing gui/cli .exe files in distribution. Fixed bugs in tests.
2880
28810.6a3
2882 * Added ``gui_scripts`` entry point group to allow installing GUI scripts
2883 on Windows and other platforms. (The special handling is only for Windows;
2884 other platforms are treated the same as for ``console_scripts``.)
2885
28860.6a2
2887 * Added ``console_scripts`` entry point group to allow installing scripts
2888 without the need to create separate script files. On Windows, console
2889 scripts get an ``.exe`` wrapper so you can just type their name. On other
2890 platforms, the scripts are written without a file extension.
2891
28920.6a1
2893 * Added support for building "old-style" RPMs that don't install an egg for
2894 the target package, using a ``--no-egg`` option.
2895
2896 * The ``build_ext`` command now works better when using the ``--inplace``
2897 option and multiple Python versions. It now makes sure that all extensions
2898 match the current Python version, even if newer copies were built for a
2899 different Python version.
2900
2901 * The ``upload`` command no longer attaches an extra ``.zip`` when uploading
2902 eggs, as PyPI now supports egg uploads without trickery.
2903
2904 * The ``ez_setup`` script/module now displays a warning before downloading
2905 the setuptools egg, and attempts to check the downloaded egg against an
2906 internal MD5 checksum table.
2907
2908 * Fixed the ``--tag-svn-revision`` option of ``egg_info`` not finding the
2909 latest revision number; it was using the revision number of the directory
2910 containing ``setup.py``, not the highest revision number in the project.
2911
2912 * Added ``eager_resources`` setup argument
2913
2914 * The ``sdist`` command now recognizes Subversion "deleted file" entries and
2915 does not include them in source distributions.
2916
2917 * ``setuptools`` now embeds itself more thoroughly into the distutils, so that
2918 other distutils extensions (e.g. py2exe, py2app) will subclass setuptools'
2919 versions of things, rather than the native distutils ones.
2920
2921 * Added ``entry_points`` and ``setup_requires`` arguments to ``setup()``;
2922 ``setup_requires`` allows you to automatically find and download packages
2923 that are needed in order to *build* your project (as opposed to running it).
2924
2925 * ``setuptools`` now finds its commands, ``setup()`` argument validators, and
2926 metadata writers using entry points, so that they can be extended by
2927 third-party packages. See `Creating distutils Extensions`_ above for more
2928 details.
2929
2930 * The vestigial ``depends`` command has been removed. It was never finished
2931 or documented, and never would have worked without EasyInstall - which it
2932 pre-dated and was never compatible with.
2933
29340.5a12
2935 * The zip-safety scanner now checks for modules that might be used with
2936 ``python -m``, and marks them as unsafe for zipping, since Python 2.4 can't
2937 handle ``-m`` on zipped modules.
2938
29390.5a11
2940 * Fix breakage of the "develop" command that was caused by the addition of
2941 ``--always-unzip`` to the ``easy_install`` command.
2942
29430.5a9
2944 * Include ``svn:externals`` directories in source distributions as well as
2945 normal subversion-controlled files and directories.
2946
2947 * Added ``exclude=patternlist`` option to ``setuptools.find_packages()``
2948
2949 * Changed --tag-svn-revision to include an "r" in front of the revision number
2950 for better readability.
2951
2952 * Added ability to build eggs without including source files (except for any
2953 scripts, of course), using the ``--exclude-source-files`` option to
2954 ``bdist_egg``.
2955
2956 * ``setup.py install`` now automatically detects when an "unmanaged" package
2957 or module is going to be on ``sys.path`` ahead of a package being installed,
2958 thereby preventing the newer version from being imported. If this occurs,
2959 a warning message is output to ``sys.stderr``, but installation proceeds
2960 anyway. The warning message informs the user what files or directories
2961 need deleting, and advises them they can also use EasyInstall (with the
2962 ``--delete-conflicting`` option) to do it automatically.
2963
2964 * The ``egg_info`` command now adds a ``top_level.txt`` file to the metadata
2965 directory that lists all top-level modules and packages in the distribution.
2966 This is used by the ``easy_install`` command to find possibly-conflicting
2967 "unmanaged" packages when installing the distribution.
2968
2969 * Added ``zip_safe`` and ``namespace_packages`` arguments to ``setup()``.
2970 Added package analysis to determine zip-safety if the ``zip_safe`` flag
2971 is not given, and advise the author regarding what code might need changing.
2972
2973 * Fixed the swapped ``-d`` and ``-b`` options of ``bdist_egg``.
2974
29750.5a8
2976 * The "egg_info" command now always sets the distribution metadata to "safe"
2977 forms of the distribution name and version, so that distribution files will
2978 be generated with parseable names (i.e., ones that don't include '-' in the
2979 name or version). Also, this means that if you use the various ``--tag``
2980 options of "egg_info", any distributions generated will use the tags in the
2981 version, not just egg distributions.
2982
2983 * Added support for defining command aliases in distutils configuration files,
2984 under the "[aliases]" section. To prevent recursion and to allow aliases to
2985 call the command of the same name, a given alias can be expanded only once
2986 per command-line invocation. You can define new aliases with the "alias"
2987 command, either for the local, global, or per-user configuration.
2988
2989 * Added "rotate" command to delete old distribution files, given a set of
2990 patterns to match and the number of files to keep. (Keeps the most
2991 recently-modified distribution files matching each pattern.)
2992
2993 * Added "saveopts" command that saves all command-line options for the current
2994 invocation to the local, global, or per-user configuration file. Useful for
2995 setting defaults without having to hand-edit a configuration file.
2996
2997 * Added a "setopt" command that sets a single option in a specified distutils
2998 configuration file.
2999
30000.5a7
3001 * Added "upload" support for egg and source distributions, including a bug
3002 fix for "upload" and a temporary workaround for lack of .egg support in
3003 PyPI.
3004
30050.5a6
3006 * Beefed up the "sdist" command so that if you don't have a MANIFEST.in, it
3007 will include all files under revision control (CVS or Subversion) in the
3008 current directory, and it will regenerate the list every time you create a
3009 source distribution, not just when you tell it to. This should make the
3010 default "do what you mean" more often than the distutils' default behavior
3011 did, while still retaining the old behavior in the presence of MANIFEST.in.
3012
3013 * Fixed the "develop" command always updating .pth files, even if you
3014 specified ``-n`` or ``--dry-run``.
3015
3016 * Slightly changed the format of the generated version when you use
3017 ``--tag-build`` on the "egg_info" command, so that you can make tagged
3018 revisions compare *lower* than the version specified in setup.py (e.g. by
3019 using ``--tag-build=dev``).
3020
30210.5a5
3022 * Added ``develop`` command to ``setuptools``-based packages. This command
3023 installs an ``.egg-link`` pointing to the package's source directory, and
3024 script wrappers that ``execfile()`` the source versions of the package's
3025 scripts. This lets you put your development checkout(s) on sys.path without
3026 having to actually install them. (To uninstall the link, use
3027 use ``setup.py develop --uninstall``.)
3028
3029 * Added ``egg_info`` command to ``setuptools``-based packages. This command
3030 just creates or updates the "projectname.egg-info" directory, without
3031 building an egg. (It's used by the ``bdist_egg``, ``test``, and ``develop``
3032 commands.)
3033
3034 * Enhanced the ``test`` command so that it doesn't install the package, but
3035 instead builds any C extensions in-place, updates the ``.egg-info``
3036 metadata, adds the source directory to ``sys.path``, and runs the tests
3037 directly on the source. This avoids an "unmanaged" installation of the
3038 package to ``site-packages`` or elsewhere.
3039
3040 * Made ``easy_install`` a standard ``setuptools`` command, moving it from
3041 the ``easy_install`` module to ``setuptools.command.easy_install``. Note
3042 that if you were importing or extending it, you must now change your imports
3043 accordingly. ``easy_install.py`` is still installed as a script, but not as
3044 a module.
3045
30460.5a4
3047 * Setup scripts using setuptools can now list their dependencies directly in
3048 the setup.py file, without having to manually create a ``depends.txt`` file.
3049 The ``install_requires`` and ``extras_require`` arguments to ``setup()``
3050 are used to create a dependencies file automatically. If you are manually
3051 creating ``depends.txt`` right now, please switch to using these setup
3052 arguments as soon as practical, because ``depends.txt`` support will be
3053 removed in the 0.6 release cycle. For documentation on the new arguments,
3054 see the ``setuptools.dist.Distribution`` class.
3055
3056 * Setup scripts using setuptools now always install using ``easy_install``
3057 internally, for ease of uninstallation and upgrading.
3058
30590.5a1
3060 * Added support for "self-installation" bootstrapping. Packages can now
3061 include ``ez_setup.py`` in their source distribution, and add the following
3062 to their ``setup.py``, in order to automatically bootstrap installation of
3063 setuptools as part of their setup process::
3064
3065 from ez_setup import use_setuptools
3066 use_setuptools()
3067
3068 from setuptools import setup
3069 # etc...
3070
30710.4a2
3072 * Added ``ez_setup.py`` installer/bootstrap script to make initial setuptools
3073 installation easier, and to allow distributions using setuptools to avoid
3074 having to include setuptools in their source distribution.
3075
3076 * All downloads are now managed by the ``PackageIndex`` class (which is now
3077 subclassable and replaceable), so that embedders can more easily override
3078 download logic, give download progress reports, etc. The class has also
3079 been moved to the new ``setuptools.package_index`` module.
3080
3081 * The ``Installer`` class no longer handles downloading, manages a temporary
3082 directory, or tracks the ``zip_ok`` option. Downloading is now handled
3083 by ``PackageIndex``, and ``Installer`` has become an ``easy_install``
3084 command class based on ``setuptools.Command``.
3085
3086 * There is a new ``setuptools.sandbox.run_setup()`` API to invoke a setup
3087 script in a directory sandbox, and a new ``setuptools.archive_util`` module
3088 with an ``unpack_archive()`` API. These were split out of EasyInstall to
3089 allow reuse by other tools and applications.
3090
3091 * ``setuptools.Command`` now supports reinitializing commands using keyword
3092 arguments to set/reset options. Also, ``Command`` subclasses can now set
3093 their ``command_consumes_arguments`` attribute to ``True`` in order to
3094 receive an ``args`` option containing the rest of the command line.
3095
30960.3a2
3097 * Added new options to ``bdist_egg`` to allow tagging the egg's version number
3098 with a subversion revision number, the current date, or an explicit tag
3099 value. Run ``setup.py bdist_egg --help`` to get more information.
3100
3101 * Misc. bug fixes
3102
31030.3a1
3104 * Initial release.
3105
3106
3107Mailing List and Bug Tracker
3108============================
3109
3110Please use the `distutils-sig mailing list`_ for questions and discussion about
3111setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
3112confirmed via the list are actual bugs, and which you have reduced to a minimal
3113set of steps to reproduce.
3114
3115.. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/
3116.. _setuptools bug tracker: http://bugs.python.org/setuptools/
3117