1 | ======================================================
|
---|
2 | Building 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
|
---|
7 | of Python 2.4) that allow you to more easily build and distribute Python
|
---|
8 | packages, especially ones that have dependencies on other packages.
|
---|
9 |
|
---|
10 | Packages built and distributed using ``setuptools`` look to the user like
|
---|
11 | ordinary Python packages based on the ``distutils``. Your users don't need to
|
---|
12 | install or even know about setuptools in order to use them, and you don't
|
---|
13 | have to include the entire setuptools package in your distributions. By
|
---|
14 | including just a single `bootstrap module`_ (an 8K .py file), your package will
|
---|
15 | automatically download and install ``setuptools`` if the user is building your
|
---|
16 | package from source and doesn't have a suitable version already installed.
|
---|
17 |
|
---|
18 | .. _bootstrap module: http://peak.telecommunity.com/dist/ez_setup.py
|
---|
19 |
|
---|
20 | Feature 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 |
|
---|
65 | In addition to the PyPI downloads, the development version of ``setuptools``
|
---|
66 | is 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 | -----------------
|
---|
79 | Developer's Guide
|
---|
80 | -----------------
|
---|
81 |
|
---|
82 |
|
---|
83 | Installing ``setuptools``
|
---|
84 | =========================
|
---|
85 |
|
---|
86 | Please follow the `EasyInstall Installation Instructions`_ to install the
|
---|
87 | current stable version of setuptools. In particular, be sure to read the
|
---|
88 | section on `Custom Installation Locations`_ if you are installing anywhere
|
---|
89 | other 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 |
|
---|
95 | If you want the current in-development version of setuptools, you should first
|
---|
96 | install a stable version, and then run::
|
---|
97 |
|
---|
98 | ez_setup.py setuptools==dev
|
---|
99 |
|
---|
100 | This will download and install the latest development (i.e. unstable) version
|
---|
101 | of setuptools from the Python Subversion sandbox.
|
---|
102 |
|
---|
103 |
|
---|
104 | Basic Use
|
---|
105 | =========
|
---|
106 |
|
---|
107 | For basic use of setuptools, just import things from setuptools instead of
|
---|
108 | the 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 |
|
---|
117 | As you can see, it doesn't take much to use setuptools in a project.
|
---|
118 | Just by doing the above, this project will be able to produce eggs, upload to
|
---|
119 | PyPI, and automatically include all packages in the directory where the
|
---|
120 | setup.py lives. See the `Command Reference`_ section below to see what
|
---|
121 | commands you can give to this setup script.
|
---|
122 |
|
---|
123 | Of course, before you release your project to PyPI, you'll want to add a bit
|
---|
124 | more information to your setup script to help people find or learn about your
|
---|
125 | project. And maybe your project will have grown by then to include a few
|
---|
126 | dependencies, 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 |
|
---|
157 | In the sections that follow, we'll explain what most of these ``setup()``
|
---|
158 | arguments do (except for the metadata ones), and the various ways you might use
|
---|
159 | them in your own project(s).
|
---|
160 |
|
---|
161 |
|
---|
162 | Specifying Your Project's Version
|
---|
163 | ---------------------------------
|
---|
164 |
|
---|
165 | Setuptools can work well with most versioning schemes; there are, however, a
|
---|
166 | few special things to watch out for, in order to ensure that setuptools and
|
---|
167 | EasyInstall can always tell what version of your package is newer than another
|
---|
168 | version. Knowing these things will also help you correctly specify what
|
---|
169 | versions of other projects your project depends on.
|
---|
170 |
|
---|
171 | A version consists of an alternating series of release numbers and pre-release
|
---|
172 | or post-release tags. A release number is a series of digits punctuated by
|
---|
173 | dots, such as ``2.4`` or ``0.5``. Each series of digits is treated
|
---|
174 | numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the
|
---|
175 | same release number, denoting the first subrelease of release 2. But ``2.10``
|
---|
176 | is the *tenth* subrelease of release 2, and so is a different and newer release
|
---|
177 | from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also
|
---|
178 | ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``.
|
---|
179 |
|
---|
180 | Following a release number, you can have either a pre-release or post-release
|
---|
181 | tag. Pre-release tags make a version be considered *older* than the version
|
---|
182 | they are appended to. So, revision ``2.4`` is *newer* than revision ``2.4c1``,
|
---|
183 | which in turn is newer than ``2.4b1`` or ``2.4a1``. Postrelease tags make
|
---|
184 | a version be considered *newer* than the version they are appended to. So,
|
---|
185 | revisions like ``2.4-1`` and ``2.4pl3`` are newer than ``2.4``, but are *older*
|
---|
186 | than ``2.4.1`` (which has a higher release number).
|
---|
187 |
|
---|
188 | A 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
|
---|
191 | the prerelease tag if it's immediately after a number, but it's okay to do
|
---|
192 | so if you prefer. Thus, ``2.4c1`` and ``2.4.c1`` both represent release
|
---|
193 | candidate 1 of version ``2.4``, and are treated as identical by setuptools.
|
---|
194 |
|
---|
195 | In addition, there are three special prerelease tags that are treated as if
|
---|
196 | they 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 |
|
---|
200 | A post-release tag is either a series of letters that are alphabetically
|
---|
201 | greater than or equal to "final", or a dash (``-``). Post-release tags are
|
---|
202 | generally used to separate patch numbers, port numbers, build numbers, revision
|
---|
203 | numbers, 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
|
---|
205 | version ``2.4``. Or you might use ``2.4-20051127`` to denote a date-stamped
|
---|
206 | post-release.
|
---|
207 |
|
---|
208 | Notice that after each pre or post-release tag, you are free to place another
|
---|
209 | release 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-
|
---|
211 | development version of the ninth alpha of release 0.6. Notice that ``dev`` is
|
---|
212 | a pre-release tag, so this version is a *lower* version number than ``0.6a9``,
|
---|
213 | which would be the actual ninth alpha of release 0.6. But the ``-r41475`` is
|
---|
214 | a post-release tag, so this version is *newer* than ``0.6a9.dev``.
|
---|
215 |
|
---|
216 | For the most part, setuptools' interpretation of version numbers is intuitive,
|
---|
217 | but 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 |
|
---|
246 | Once you've decided on a version numbering scheme for your project, you can
|
---|
247 | have setuptools automatically tag your in-development releases with various
|
---|
248 | pre- 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 |
|
---|
255 | New and Changed ``setup()`` Keywords
|
---|
256 | ====================================
|
---|
257 |
|
---|
258 | The following keyword arguments to ``setup()`` are added or changed by
|
---|
259 | ``setuptools``. All of them are optional; you do not have to supply them
|
---|
260 | unless 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 |
|
---|
408 | Using ``find_packages()``
|
---|
409 | -------------------------
|
---|
410 |
|
---|
411 | For simple projects, it's usually easy enough to manually add packages to
|
---|
412 | the ``packages`` argument of ``setup()``. However, for very large projects
|
---|
413 | (Twisted, PEAK, Zope, Chandler, etc.), it can be a big burden to keep the
|
---|
414 | package 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
|
---|
417 | patterns to exclude. If omitted, the source directory defaults to the same
|
---|
418 | directory as the setup script. Some projects use a ``src`` or ``lib``
|
---|
419 | directory as the root of their source tree, and those projects would of course
|
---|
420 | use ``"src"`` or ``"lib"`` as the first argument to ``find_packages()``. (And
|
---|
421 | such projects also need something like ``package_dir = {'':'src'}`` in their
|
---|
422 | ``setup()`` arguments, but that's just a normal distutils thing.)
|
---|
423 |
|
---|
424 | Anyway, ``find_packages()`` walks the target directory, and finds Python
|
---|
425 | packages by looking for ``__init__.py`` files. It then filters the list of
|
---|
426 | packages using the exclusion patterns.
|
---|
427 |
|
---|
428 | Exclusion patterns are package names, optionally including wildcards. For
|
---|
429 | example, ``find_packages(exclude=["*.tests"])`` will exclude all packages whose
|
---|
430 | last name part is ``tests``. Or, ``find_packages(exclude=["*.tests",
|
---|
431 | "*.tests.*"])`` will also exclude any subpackages of packages named ``tests``,
|
---|
432 | but it still won't exclude a top-level ``tests`` package or the children
|
---|
433 | thereof. In fact, if you really want no ``tests`` packages at all, you'll need
|
---|
434 | something like this::
|
---|
435 |
|
---|
436 | find_packages(exclude=["*.tests", "*.tests.*", "tests.*", "tests"])
|
---|
437 |
|
---|
438 | in order to cover all the bases. Really, the exclusion patterns are intended
|
---|
439 | to cover simpler use cases than this, like excluding a single, specified
|
---|
440 | package and its subpackages.
|
---|
441 |
|
---|
442 | Regardless of the target directory or exclusions, the ``find_packages()``
|
---|
443 | function returns a list of package names suitable for use as the ``packages``
|
---|
444 | argument to ``setup()``, and so is usually the easiest way to set that
|
---|
445 | argument in your setup script. Especially since it frees you from having to
|
---|
446 | remember to modify your setup script whenever your project grows additional
|
---|
447 | top-level packages or subpackages.
|
---|
448 |
|
---|
449 |
|
---|
450 | Automatic Script Creation
|
---|
451 | =========================
|
---|
452 |
|
---|
453 | Packaging and installing scripts can be a bit awkward with the distutils. For
|
---|
454 | one thing, there's no easy way to have a script's filename match local
|
---|
455 | conventions on both Windows and POSIX platforms. For another, you often have
|
---|
456 | to create a separate file just for the "main" script, when your actual "main"
|
---|
457 | is a function in a module somewhere. And even in Python 2.4, using the ``-m``
|
---|
458 | option 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
|
---|
461 | for 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.
|
---|
463 | The way to use this feature is to define "entry points" in your setup script
|
---|
464 | that indicate what function the generated script should import and run. For
|
---|
465 | example, to create two console scripts called ``foo`` and ``bar``, and a GUI
|
---|
466 | script 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 |
|
---|
481 | When this project is installed on non-Windows platforms (using "setup.py
|
---|
482 | install", "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
|
---|
485 | with no arguments, and their return value is passed to ``sys.exit()``, so you
|
---|
486 | can return an errorlevel or message to print to stderr.
|
---|
487 |
|
---|
488 | On Windows, a set of ``foo.exe``, ``bar.exe``, and ``baz.exe`` launchers are
|
---|
489 | created, 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 |
|
---|
493 | You may define as many "console script" and "gui script" entry points as you
|
---|
494 | like, and each one can optionally specify "extras" that it depends on, that
|
---|
495 | will 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
|
---|
497 | on "entry points" in general, see the section below on `Dynamic Discovery of
|
---|
498 | Services and Plugins`_.
|
---|
499 |
|
---|
500 |
|
---|
501 | "Eggsecutable" Scripts
|
---|
502 | ----------------------
|
---|
503 |
|
---|
504 | Occasionally, there are situations where it's desirable to make an ``.egg``
|
---|
505 | file directly executable. You can do this by including an entry point such
|
---|
506 | as 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 |
|
---|
517 | Any eggs built from the above setup script will include a short excecutable
|
---|
518 | prelude that imports and calls ``main_func()`` from ``my_package.some_module``.
|
---|
519 | The prelude can be run on Unix-like platforms (including Mac and Linux) by
|
---|
520 | invoking 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
|
---|
522 | Python 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 |
|
---|
526 | This feature is primarily intended to support bootstrapping the installation of
|
---|
527 | setuptools itself on non-Windows platforms, but may also be useful for other
|
---|
528 | projects as well.
|
---|
529 |
|
---|
530 | IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or
|
---|
531 | invoked via symlinks. They *must* be invoked using their original filename, in
|
---|
532 | order to ensure that, once running, ``pkg_resources`` will know what project
|
---|
533 | and version is in use. The header script will check this and exit with an
|
---|
534 | error if the ``.egg`` file has been renamed or is invoked via a symlink that
|
---|
535 | changes its base name.
|
---|
536 |
|
---|
537 |
|
---|
538 | Declaring Dependencies
|
---|
539 | ======================
|
---|
540 |
|
---|
541 | ``setuptools`` supports automatically installing dependencies when a package is
|
---|
542 | installed, and including information about dependencies in Python Eggs (so that
|
---|
543 | package management tools like EasyInstall can use the information).
|
---|
544 |
|
---|
545 | ``setuptools`` and ``pkg_resources`` use a common syntax for specifying a
|
---|
546 | project's required dependencies. This syntax consists of a project's PyPI
|
---|
547 | name, optionally followed by a comma-separated list of "extras" in square
|
---|
548 | brackets, optionally followed by a comma-separated list of version
|
---|
549 | specifiers. A version specifier is one of the operators ``<``, ``>``, ``<=``,
|
---|
550 | ``>=``, ``==`` or ``!=``, followed by a version identifier. Tokens may be
|
---|
551 | separated by whitespace, but any whitespace or nonstandard characters within a
|
---|
552 | project name or version identifier must be replaced with ``-``.
|
---|
553 |
|
---|
554 | Version specifiers for a given project are internally sorted into ascending
|
---|
555 | version order, and used to establish what ranges of versions are acceptable.
|
---|
556 | Adjacent redundant conditions are also consolidated (e.g. ``">1, >2"`` becomes
|
---|
557 | ``">1"``, and ``"<2,<3"`` becomes ``"<3"``). ``"!="`` versions are excised from
|
---|
558 | the ranges they fall within. A project's version is then checked for
|
---|
559 | membership in the resulting ranges. (Note that providing conflicting conditions
|
---|
560 | for the same version (e.g. "<2,>=2" or "==2,!=2") is meaningless and may
|
---|
561 | therefore produce bizarre results.)
|
---|
562 |
|
---|
563 | Here 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 |
|
---|
575 | The simplest way to include requirement specifiers is to use the
|
---|
576 | ``install_requires`` argument to ``setup()``. It takes a string or list of
|
---|
577 | strings containing requirement specifiers. If you include more than one
|
---|
578 | requirement in a string, each requirement must begin on a new line.
|
---|
579 |
|
---|
580 | This has three effects:
|
---|
581 |
|
---|
582 | 1. 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 |
|
---|
587 | 2. 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 |
|
---|
592 | 3. Python Egg distributions will include a metadata file listing the
|
---|
593 | dependencies.
|
---|
594 |
|
---|
595 | Note, 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
|
---|
597 | long as you either install the project or use ``setup.py develop`` to do
|
---|
598 | development work on it. (See `"Development Mode"`_ below for more details on
|
---|
599 | using ``setup.py develop``.)
|
---|
600 |
|
---|
601 |
|
---|
602 | Dependencies that aren't in PyPI
|
---|
603 | --------------------------------
|
---|
604 |
|
---|
605 | If your project depends on packages that aren't registered in PyPI, you may
|
---|
606 | still be able to depend on them, as long as they are available for download
|
---|
607 | as an egg, in the standard distutils ``sdist`` format, or as a single ``.py``
|
---|
608 | file. You just need to add some URLs to the ``dependency_links`` argument to
|
---|
609 | ``setup()``.
|
---|
610 |
|
---|
611 | The URLs must be either:
|
---|
612 |
|
---|
613 | 1. direct download URLs, or
|
---|
614 | 2. the URLs of web pages that contain direct download links
|
---|
615 |
|
---|
616 | In general, it's better to link to web pages, because it is usually less
|
---|
617 | complex to update a web page than to release a new version of your project.
|
---|
618 | You can also use a SourceForge ``showfiles.php`` link in the case where a
|
---|
619 | package you depend on is distributed via SourceForge.
|
---|
620 |
|
---|
621 | If you depend on a package that's distributed as a single ``.py`` file, you
|
---|
622 | must include an ``"#egg=project-version"`` suffix to the URL, to give a project
|
---|
623 | name and version number. (Be sure to escape any dashes in the name or version
|
---|
624 | by replacing them with underscores.) EasyInstall will recognize this suffix
|
---|
625 | and automatically create a trivial ``setup.py`` to wrap the single ``.py`` file
|
---|
626 | as an egg.
|
---|
627 |
|
---|
628 | The ``dependency_links`` option takes the form of a list of URL strings. For
|
---|
629 | example, the below will cause EasyInstall to search the specified page for
|
---|
630 | eggs or source distributions, if the package's dependencies aren't already
|
---|
631 | installed::
|
---|
632 |
|
---|
633 | setup(
|
---|
634 | ...
|
---|
635 | dependency_links = [
|
---|
636 | "http://peak.telecommunity.com/snapshots/"
|
---|
637 | ],
|
---|
638 | )
|
---|
639 |
|
---|
640 |
|
---|
641 | .. _Declaring Extras:
|
---|
642 |
|
---|
643 |
|
---|
644 | Declaring "Extras" (optional features with their own dependencies)
|
---|
645 | ------------------------------------------------------------------
|
---|
646 |
|
---|
647 | Sometimes a project has "recommended" dependencies, that are not required for
|
---|
648 | all uses of the project. For example, a project might offer optional PDF
|
---|
649 | output if ReportLab is installed, and reStructuredText support if docutils is
|
---|
650 | installed. These optional features are called "extras", and setuptools allows
|
---|
651 | you to define their requirements as well. In this way, other projects that
|
---|
652 | require these optional features can force the additional requirements to be
|
---|
653 | installed, by naming the desired extras in their ``install_requires``.
|
---|
654 |
|
---|
655 | For 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 |
|
---|
666 | As you can see, the ``extras_require`` argument takes a dictionary mapping
|
---|
667 | names of "extra" features, to strings or lists of strings describing those
|
---|
668 | features' requirements. These requirements will *not* be automatically
|
---|
669 | installed unless another package depends on them (directly or indirectly) by
|
---|
670 | including the desired "extras" in square brackets after the associated project
|
---|
671 | name. (Or if the extras were listed in a requirement spec on the EasyInstall
|
---|
672 | command line.)
|
---|
673 |
|
---|
674 | Extras can be used by a project's `entry points`_ to specify dynamic
|
---|
675 | dependencies. For example, if Project A includes a "rst2pdf" script, it might
|
---|
676 | declare 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 |
|
---|
690 | Projects can also use another project's extras when specifying dependencies.
|
---|
691 | For example, if project B needs "project A" with PDF support installed, it
|
---|
692 | might declare the dependency like this::
|
---|
693 |
|
---|
694 | setup(
|
---|
695 | name="Project-B",
|
---|
696 | install_requires = ["Project-A[PDF]"],
|
---|
697 | ...
|
---|
698 | )
|
---|
699 |
|
---|
700 | This will cause ReportLab to be installed along with project A, if project B is
|
---|
701 | installed -- even if project A was already installed. In this way, a project
|
---|
702 | can encapsulate groups of optional "downstream dependencies" under a feature
|
---|
703 | name, so that packages that depend on it don't have to know what the downstream
|
---|
704 | dependencies are. If a later version of Project A builds in PDF support and
|
---|
705 | no longer needs ReportLab, or if it ends up needing other dependencies besides
|
---|
706 | ReportLab in order to provide PDF support, Project B's setup information does
|
---|
707 | not need to change, but the right packages will still be installed if needed.
|
---|
708 |
|
---|
709 | Note, by the way, that if a project ends up not needing any other packages to
|
---|
710 | support a feature, it should keep an empty requirements list for that feature
|
---|
711 | in its ``extras_require`` argument, so that packages depending on that feature
|
---|
712 | don't break (due to an invalid feature name). For example, if Project A above
|
---|
713 | builds in PDF support and no longer needs ReportLab, it could change its
|
---|
714 | setup to this::
|
---|
715 |
|
---|
716 | setup(
|
---|
717 | name="Project-A",
|
---|
718 | ...
|
---|
719 | extras_require = {
|
---|
720 | 'PDF': [],
|
---|
721 | 'reST': ["docutils>=0.3"],
|
---|
722 | }
|
---|
723 | )
|
---|
724 |
|
---|
725 | so that Package B doesn't have to remove the ``[PDF]`` from its requirement
|
---|
726 | specifier.
|
---|
727 |
|
---|
728 |
|
---|
729 | Including Data Files
|
---|
730 | ====================
|
---|
731 |
|
---|
732 | The distutils have traditionally allowed installation of "data files", which
|
---|
733 | are placed in a platform-specific location. However, the most common use case
|
---|
734 | for data files distributed with a package is for use *by* the package, usually
|
---|
735 | by including the data files in the package directory.
|
---|
736 |
|
---|
737 | Setuptools offers three ways to specify data files to be included in your
|
---|
738 | packages. First, you can simply use the ``include_package_data`` keyword,
|
---|
739 | e.g.::
|
---|
740 |
|
---|
741 | from setuptools import setup, find_packages
|
---|
742 | setup(
|
---|
743 | ...
|
---|
744 | include_package_data = True
|
---|
745 | )
|
---|
746 |
|
---|
747 | This tells setuptools to install any data files it finds in your packages. The
|
---|
748 | data files must be under CVS or Subversion control, or else they must be
|
---|
749 | specified via the distutils' ``MANIFEST.in`` file. (They can also be tracked
|
---|
750 | by another revision control system, using an appropriate plugin. See the
|
---|
751 | section below on `Adding Support for Other Revision Control Systems`_ for
|
---|
752 | information on how to write such plugins.)
|
---|
753 |
|
---|
754 | If you want finer-grained control over what files are included (for example, if
|
---|
755 | you have documentation files in your package directories and want to exclude
|
---|
756 | them from installation), then you can also use the ``package_data`` keyword,
|
---|
757 | e.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 |
|
---|
770 | The ``package_data`` argument is a dictionary that maps from package names to
|
---|
771 | lists of glob patterns. The globs may include subdirectory names, if the data
|
---|
772 | files are contained in a subdirectory of the package. For example, if the
|
---|
773 | package 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 |
|
---|
784 | The 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 |
|
---|
801 | Notice that if you list patterns in ``package_data`` under the empty string,
|
---|
802 | these patterns are used to find files in every package, even ones that also
|
---|
803 | have their own patterns listed. Thus, in the above example, the ``mypkg.txt``
|
---|
804 | file gets included even though it's not listed in the patterns for ``mypkg``.
|
---|
805 |
|
---|
806 | Also notice that if you use paths, you *must* use a forward slash (``/``) as
|
---|
807 | the path separator, even if you are on Windows. Setuptools automatically
|
---|
808 | converts 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
|
---|
812 | Python 2.4; there is `some documentation for the feature`__ available on the
|
---|
813 | python.org website.)
|
---|
814 |
|
---|
815 | __ http://docs.python.org/dist/node11.html
|
---|
816 |
|
---|
817 | Sometimes, the ``include_package_data`` or ``package_data`` options alone
|
---|
818 | aren't sufficient to precisely define what files you want included. For
|
---|
819 | example, you may want to include package README files in your revision control
|
---|
820 | system and source distributions, but exclude them from being installed. So,
|
---|
821 | setuptools offers an ``exclude_package_data`` option as well, that allows you
|
---|
822 | to 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 |
|
---|
836 | The ``exclude_package_data`` option is a dictionary mapping package names to
|
---|
837 | lists of wildcard patterns, just like the ``package_data`` option. And, just
|
---|
838 | as with that option, a key of ``''`` will apply the given pattern(s) to all
|
---|
839 | packages. However, any files that match these patterns will be *excluded*
|
---|
840 | from installation, even if they were listed in ``package_data`` or were
|
---|
841 | included as a result of using ``include_package_data``.
|
---|
842 |
|
---|
843 | In 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 |
|
---|
858 | NOTE: Due to the way the distutils build process works, a data file that you
|
---|
859 | include in your project and then stop including may be "orphaned" in your
|
---|
860 | project's build directories, requiring you to run ``setup.py clean --all`` to
|
---|
861 | fully remove them. This may also be important for your users and contributors
|
---|
862 | if they track intermediate revisions of your project using Subversion; be sure
|
---|
863 | to let them know when you make changes that remove files from inclusion so they
|
---|
864 | can run ``setup.py clean --all``.
|
---|
865 |
|
---|
866 |
|
---|
867 | Accessing Data Files at Runtime
|
---|
868 | -------------------------------
|
---|
869 |
|
---|
870 | Typically, existing programs manipulate a package's ``__file__`` attribute in
|
---|
871 | order to find the location of data files. However, this manipulation isn't
|
---|
872 | compatible with PEP 302-based import hooks, including importing from zip files
|
---|
873 | and Python Eggs. It is strongly recommended that, if you are using data files,
|
---|
874 | you should use the `Resource Management API`_ of ``pkg_resources`` to access
|
---|
875 | them. The ``pkg_resources`` module is distributed as part of setuptools, so if
|
---|
876 | you're using setuptools to distribute your package, there is no reason not to
|
---|
877 | use its resource management API. See also `Accessing Package Resources`_ for
|
---|
878 | a 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 |
|
---|
885 | Non-Package Data Files
|
---|
886 | ----------------------
|
---|
887 |
|
---|
888 | The ``distutils`` normally install general "data files" to a platform-specific
|
---|
889 | location (e.g. ``/usr/share``). This feature intended to be used for things
|
---|
890 | like documentation, example configuration files, and the like. ``setuptools``
|
---|
891 | does not install these data files in a separate location, however. They are
|
---|
892 | bundled inside the egg file or directory, alongside the Python modules and
|
---|
893 | packages. The data files can also be accessed using the `Resource Management
|
---|
894 | API`_, 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 |
|
---|
899 | The above code will obtain the filename of the "sample.conf" file in the data
|
---|
900 | root of the "MyProject" distribution.
|
---|
901 |
|
---|
902 | Note, by the way, that this encapsulation of data files means that you can't
|
---|
903 | actually install data files to some arbitrary location on a user's machine;
|
---|
904 | this is a feature, not a bug. You can always include a script in your
|
---|
905 | distribution that extracts and copies your the documentation or data files to
|
---|
906 | a user-specified location, at their discretion. If you put related data files
|
---|
907 | in a single directory, you can use ``resource_filename()`` with the directory
|
---|
908 | name to get a filesystem directory that then can be copied with the ``shutil``
|
---|
909 | module. (Even if your package is installed as a zipfile, calling
|
---|
910 | ``resource_filename()`` on a directory will return an actual filesystem
|
---|
911 | directory, 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
|
---|
914 | data files or directories inside one of your packages, rather than using the
|
---|
915 | distutils' approach. However, if you're updating an existing application, it
|
---|
916 | may be simpler not to change the way it currently specifies these data files.)
|
---|
917 |
|
---|
918 |
|
---|
919 | Automatic Resource Extraction
|
---|
920 | -----------------------------
|
---|
921 |
|
---|
922 | If you are using tools that expect your resources to be "real" files, or your
|
---|
923 | project includes non-extension native libraries or other files that your C
|
---|
924 | extensions expect to be able to access, you may need to list those files in
|
---|
925 | the ``eager_resources`` argument to ``setup()``, so that the files will be
|
---|
926 | extracted together, whenever a C extension in the project is imported.
|
---|
927 |
|
---|
928 | This is especially important if your project includes shared libraries *other*
|
---|
929 | than distutils-built C extensions, and those shared libraries use file
|
---|
930 | extensions other than ``.dll``, ``.so``, or ``.dylib``, which are the
|
---|
931 | extensions that setuptools 0.6a8 and higher automatically detects as shared
|
---|
932 | libraries and adds to the ``native_libs.txt`` file for you. Any shared
|
---|
933 | libraries whose names do not end with one of those extensions should be listed
|
---|
934 | as ``eager_resources``, because they need to be present in the filesystem when
|
---|
935 | he C extensions that link to them are used.
|
---|
936 |
|
---|
937 | The ``pkg_resources`` runtime for compressed packages will automatically
|
---|
938 | extract *all* C extensions and ``eager_resources`` at the same time, whenever
|
---|
939 | *any* C extension or eager resource is requested via the ``resource_filename()``
|
---|
940 | API. (C extensions are imported using ``resource_filename()`` internally.)
|
---|
941 | This ensures that C extensions will see all of the "real" files that they
|
---|
942 | expect to see.
|
---|
943 |
|
---|
944 | Note also that you can list directory resource names in ``eager_resources`` as
|
---|
945 | well, in which case the directory's contents (including subdirectories) will be
|
---|
946 | extracted whenever any C extension or eager resource is requested.
|
---|
947 |
|
---|
948 | Please note that if you're not sure whether you need to use this argument, you
|
---|
949 | don't! It's really intended to support projects with lots of non-Python
|
---|
950 | dependencies and as a last resort for crufty projects that can't otherwise
|
---|
951 | handle being compressed. If your package is pure Python, Python plus data
|
---|
952 | files, or Python plus C, you really don't need this. You've got to be using
|
---|
953 | either C or an external program that needs "real" files in your project before
|
---|
954 | there's any possibility of ``eager_resources`` being relevant to your project.
|
---|
955 |
|
---|
956 |
|
---|
957 | Extensible Applications and Frameworks
|
---|
958 | ======================================
|
---|
959 |
|
---|
960 |
|
---|
961 | .. _Entry Points:
|
---|
962 |
|
---|
963 | Dynamic Discovery of Services and Plugins
|
---|
964 | -----------------------------------------
|
---|
965 |
|
---|
966 | ``setuptools`` supports creating libraries that "plug in" to extensible
|
---|
967 | applications and frameworks, by letting you register "entry points" in your
|
---|
968 | project that can be imported by the application or framework.
|
---|
969 |
|
---|
970 | For example, suppose that a blogging tool wants to support plugins
|
---|
971 | that provide translation for various file types to the blog's output format.
|
---|
972 | The framework might define an "entry point group" called ``blogtool.parsers``,
|
---|
973 | and then allow plugins to register entry points for the file extensions they
|
---|
974 | support.
|
---|
975 |
|
---|
976 | This would allow people to create distributions that contain one or more
|
---|
977 | parsers for different file types, and then the blogging tool would be able to
|
---|
978 | find the parsers at runtime by looking up an entry point for the file
|
---|
979 | extension (or mime type, or however it wants to).
|
---|
980 |
|
---|
981 | Note that if the blogging tool includes parsers for certain file formats, it
|
---|
982 | can register these as entry points in its own setup script, which means it
|
---|
983 | doesn't have to special-case its built-in formats. They can just be treated
|
---|
984 | the same as any other plugin's entry points would be.
|
---|
985 |
|
---|
986 | If you're creating a project that plugs in to an existing application or
|
---|
987 | framework, you'll need to know what entry points or entry point groups are
|
---|
988 | defined by that application or framework. Then, you can register entry points
|
---|
989 | in 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,
|
---|
991 | for 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 |
|
---|
1012 | The ``entry_points`` argument to ``setup()`` accepts either a string with
|
---|
1013 | ``.ini``-style sections, or a dictionary mapping entry point group names to
|
---|
1014 | either strings or lists of strings containing entry point specifiers. An
|
---|
1015 | entry point specifier consists of a name and value, separated by an ``=``
|
---|
1016 | sign. 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
|
---|
1018 | also include a bracketed list of "extras" that are required for the entry
|
---|
1019 | point to be used. When the invoking application or framework requests loading
|
---|
1020 | of an entry point, any requirements implied by the associated extras will be
|
---|
1021 | passed to ``pkg_resources.require()``, so that an appropriate error message
|
---|
1022 | can be displayed if the needed package(s) are missing. (Of course, the
|
---|
1023 | invoking app or framework can ignore such errors if it wants to make an entry
|
---|
1024 | point optional if a requirement isn't installed.)
|
---|
1025 |
|
---|
1026 |
|
---|
1027 | Defining Additional Metadata
|
---|
1028 | ----------------------------
|
---|
1029 |
|
---|
1030 | Some extensible applications and frameworks may need to define their own kinds
|
---|
1031 | of metadata to include in eggs, which they can then access using the
|
---|
1032 | ``pkg_resources`` metadata APIs. Ordinarily, this is done by having plugin
|
---|
1033 | developers include additional files in their ``ProjectName.egg-info``
|
---|
1034 | directory. However, since it can be tedious to create such files by hand, you
|
---|
1035 | may want to create a distutils extension that will create the necessary files
|
---|
1036 | from arguments to ``setup()``, in much the same way that ``setuptools`` does
|
---|
1037 | for 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 |
|
---|
1045 | Under normal circumstances, the ``distutils`` assume that you are going to
|
---|
1046 | build a distribution of your project, not use it in its "raw" or "unbuilt"
|
---|
1047 | form. If you were to use the ``distutils`` that way, you would have to rebuild
|
---|
1048 | and reinstall your project every time you made a change to it during
|
---|
1049 | development.
|
---|
1050 |
|
---|
1051 | Another problem that sometimes comes up with the ``distutils`` is that you may
|
---|
1052 | need to do development on two related projects at the same time. You may need
|
---|
1053 | to put both projects' packages in the same directory to run them, but need to
|
---|
1054 | keep them separate for revision control purposes. How can you do this?
|
---|
1055 |
|
---|
1056 | Setuptools allows you to deploy your projects for use in a common directory or
|
---|
1057 | staging area, but without copying any files. Thus, you can edit each project's
|
---|
1058 | code in its checkout directory, and only need to run build commands when you
|
---|
1059 | change a project's C extensions or similarly compiled files. You can even
|
---|
1060 | deploy a project into another project's checkout directory, if that's your
|
---|
1061 | preferred way of working (as opposed to using a common independent staging area
|
---|
1062 | or the site-packages directory).
|
---|
1063 |
|
---|
1064 | To 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
|
---|
1066 | install anything. Instead, it creates a special ``.egg-link`` file in the
|
---|
1067 | deployment directory, that links to your project's source code. And, if your
|
---|
1068 | deployment directory is Python's ``site-packages`` directory, it will also
|
---|
1069 | update the ``easy-install.pth`` file to include your project's source code,
|
---|
1070 | thereby making it available on ``sys.path`` for all programs using that Python
|
---|
1071 | installation.
|
---|
1072 |
|
---|
1073 | In addition, the ``develop`` command creates wrapper scripts in the target
|
---|
1074 | script directory that will run your in-development scripts after ensuring that
|
---|
1075 | all your ``install_requires`` packages are available on ``sys.path``.
|
---|
1076 |
|
---|
1077 | You can deploy the same project to multiple staging areas, e.g. if you have
|
---|
1078 | multiple projects on the same machine that are sharing the same project you're
|
---|
1079 | doing development work.
|
---|
1080 |
|
---|
1081 | When you're done with a given development task, you can remove the project
|
---|
1082 | source from a staging area using ``setup.py develop --uninstall``, specifying
|
---|
1083 | the desired staging area if it's not the default.
|
---|
1084 |
|
---|
1085 | There are several options to control the precise behavior of the ``develop``
|
---|
1086 | command; see the section on the `develop`_ command below for more details.
|
---|
1087 |
|
---|
1088 | Note that you can also apply setuptools commands to non-setuptools projects,
|
---|
1089 | using commands like this::
|
---|
1090 |
|
---|
1091 | python -c "import setuptools; execfile('setup.py')" develop
|
---|
1092 |
|
---|
1093 | That is, you can simply list the normal setup commands and options following
|
---|
1094 | the quoted part.
|
---|
1095 |
|
---|
1096 |
|
---|
1097 | Distributing a ``setuptools``-based project
|
---|
1098 | ===========================================
|
---|
1099 |
|
---|
1100 | Using ``setuptools``... Without bundling it!
|
---|
1101 | ---------------------------------------------
|
---|
1102 |
|
---|
1103 | Your users might not have ``setuptools`` installed on their machines, or even
|
---|
1104 | if they do, it might not be the right version. Fixing this is easy; just
|
---|
1105 | download `ez_setup.py`_, and put it in the same directory as your ``setup.py``
|
---|
1106 | script. (Be sure to add it to your revision control system, too.) Then add
|
---|
1107 | these two lines to the very top of your setup script, before the script imports
|
---|
1108 | anything from setuptools::
|
---|
1109 |
|
---|
1110 | import ez_setup
|
---|
1111 | ez_setup.use_setuptools()
|
---|
1112 |
|
---|
1113 | That's it. The ``ez_setup`` module will automatically download a matching
|
---|
1114 | version of ``setuptools`` from PyPI, if it isn't present on the target system.
|
---|
1115 | Whenever you install an updated version of setuptools, you should also update
|
---|
1116 | your projects' ``ez_setup.py`` files, so that a matching version gets installed
|
---|
1117 | on the target machine(s).
|
---|
1118 |
|
---|
1119 | By 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
|
---|
1121 | source or egg distributions respectively. Your project's current version must
|
---|
1122 | be registered with PyPI first, of course; you can use ``setup.py register`` to
|
---|
1123 | do that. Or you can do it all in one step, e.g. ``setup.py register sdist
|
---|
1124 | bdist_egg upload`` will register the package, build source and egg
|
---|
1125 | distributions, and then upload them both to PyPI, where they'll be easily
|
---|
1126 | found by other projects that depend on them.
|
---|
1127 |
|
---|
1128 | (By the way, if you need to distribute a specific version of ``setuptools``,
|
---|
1129 | you 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 |
|
---|
1133 | What Your Users Should Know
|
---|
1134 | ---------------------------
|
---|
1135 |
|
---|
1136 | In general, a setuptools-based project looks just like any distutils-based
|
---|
1137 | project -- as long as your users have an internet connection and are installing
|
---|
1138 | to ``site-packages``, that is. But for some users, these conditions don't
|
---|
1139 | apply, and they may become frustrated if this is their first encounter with
|
---|
1140 | a setuptools-based project. To keep these users happy, you should review the
|
---|
1141 | following topics in your project's installation instructions, if they are
|
---|
1142 | relevant to your project and your target audience isn't already familiar with
|
---|
1143 | setuptools and ``easy_install``.
|
---|
1144 |
|
---|
1145 | Network 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 |
|
---|
1152 | Custom 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 |
|
---|
1158 | Your 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 |
|
---|
1180 | Subversion 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 |
|
---|
1197 | Creating 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 |
|
---|
1223 | Managing Multiple Projects
|
---|
1224 | --------------------------
|
---|
1225 |
|
---|
1226 | If you're managing several projects that need to use ``ez_setup``, and you are
|
---|
1227 | using Subversion as your revision control system, you can use the
|
---|
1228 | "svn:externals" property to share a single copy of ``ez_setup`` between
|
---|
1229 | projects, so that it will always be up-to-date whenever you check out or update
|
---|
1230 | an individual project, without having to manually update each project to use
|
---|
1231 | a new version.
|
---|
1232 |
|
---|
1233 | However, because Subversion only supports using directories as externals, you
|
---|
1234 | have to turn ``ez_setup.py`` into ``ez_setup/__init__.py`` in order to do this,
|
---|
1235 | then create "externals" definitions that map the ``ez_setup`` directory into
|
---|
1236 | each project. Also, if any of your projects use ``find_packages()`` on their
|
---|
1237 | setup directory, you will need to exclude the resulting ``ez_setup`` package,
|
---|
1238 | to keep it from being included in your distributions, e.g.::
|
---|
1239 |
|
---|
1240 | setup(
|
---|
1241 | ...
|
---|
1242 | packages = find_packages(exclude=['ez_setup']),
|
---|
1243 | )
|
---|
1244 |
|
---|
1245 | Of course, the ``ez_setup`` package will still be included in your packages'
|
---|
1246 | source distributions, as it needs to be.
|
---|
1247 |
|
---|
1248 | For your convenience, you may use the following external definition, which will
|
---|
1249 | track the latest version of setuptools::
|
---|
1250 |
|
---|
1251 | ez_setup svn://svn.eby-sarna.com/svnroot/ez_setup
|
---|
1252 |
|
---|
1253 | You can set this by executing this command in your project directory::
|
---|
1254 |
|
---|
1255 | svn propedit svn:externals .
|
---|
1256 |
|
---|
1257 | And then adding the line shown above to the file that comes up for editing.
|
---|
1258 |
|
---|
1259 |
|
---|
1260 | Setting the ``zip_safe`` flag
|
---|
1261 | -----------------------------
|
---|
1262 |
|
---|
1263 | For maximum performance, Python packages are best installed as zip files.
|
---|
1264 | Not all packages, however, are capable of running in compressed form, because
|
---|
1265 | they may expect to be able to access either source code or data files as
|
---|
1266 | normal operating system files. So, ``setuptools`` can install your project
|
---|
1267 | as a zipfile or a directory, and its default choice is determined by the
|
---|
1268 | project's ``zip_safe`` flag.
|
---|
1269 |
|
---|
1270 | You 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``
|
---|
1272 | command will analyze your project's contents to see if it can detect any
|
---|
1273 | conditions that would prevent it from working in a zipfile. It will output
|
---|
1274 | notices to the console about any such conditions that it finds.
|
---|
1275 |
|
---|
1276 | Currently, this analysis is extremely conservative: it will consider the
|
---|
1277 | project unsafe if it contains any C extensions or datafiles whatsoever. This
|
---|
1278 | does *not* mean that the project can't or won't work as a zipfile! It just
|
---|
1279 | means that the ``bdist_egg`` authors aren't yet comfortable asserting that
|
---|
1280 | the project *will* work. If the project contains no C or data files, and does
|
---|
1281 | no ``__file__`` or ``__path__`` introspection or source code manipulation, then
|
---|
1282 | there is an extremely solid chance the project will work when installed as a
|
---|
1283 | zipfile. (And if the project uses ``pkg_resources`` for all its data file
|
---|
1284 | access, then C extensions and other data files shouldn't be a problem at all.
|
---|
1285 | See the `Accessing Data Files at Runtime`_ section above for more information.)
|
---|
1286 |
|
---|
1287 | However, if ``bdist_egg`` can't be *sure* that your package will work, but
|
---|
1288 | you'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
|
---|
1291 | doesn'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 |
|
---|
1294 | Of course, the end-user can still override either decision, if they are using
|
---|
1295 | EasyInstall to install your package. And, if you want to override for testing
|
---|
1296 | purposes, you can just run ``setup.py easy_install --zip-ok .`` or ``setup.py
|
---|
1297 | easy_install --always-unzip .`` in your project directory. to install the
|
---|
1298 | package as a zipfile or directory, respectively.
|
---|
1299 |
|
---|
1300 | In the future, as we gain more experience with different packages and become
|
---|
1301 | more satisfied with the robustness of the ``pkg_resources`` runtime, the
|
---|
1302 | "zip safety" analysis may become less conservative. However, we strongly
|
---|
1303 | recommend that you determine for yourself whether your project functions
|
---|
1304 | correctly when installed as a zipfile, correct any problems if you can, and
|
---|
1305 | then make an explicit declaration of ``True`` or ``False`` for the ``zip_safe``
|
---|
1306 | flag, so that it will not be necessary for ``bdist_egg`` or ``EasyInstall`` to
|
---|
1307 | try to guess whether your project can work as a zipfile.
|
---|
1308 |
|
---|
1309 |
|
---|
1310 | Namespace Packages
|
---|
1311 | ------------------
|
---|
1312 |
|
---|
1313 | Sometimes, a large package is more useful if distributed as a collection of
|
---|
1314 | smaller eggs. However, Python does not normally allow the contents of a
|
---|
1315 | package to be retrieved from more than one location. "Namespace packages"
|
---|
1316 | are a solution for this problem. When you declare a package to be a namespace
|
---|
1317 | package, 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 |
|
---|
1320 | The ``pkg_resources`` runtime will then automatically ensure that the contents
|
---|
1321 | of namespace packages that are spread over multiple eggs or directories are
|
---|
1322 | combined into a single "virtual" package.
|
---|
1323 |
|
---|
1324 | The ``namespace_packages`` argument to ``setup()`` lets you declare your
|
---|
1325 | project's namespace packages, so that they will be included in your project's
|
---|
1326 | metadata. The argument should list the namespace packages that the egg
|
---|
1327 | participates in. For example, the ZopeInterface project might do this::
|
---|
1328 |
|
---|
1329 | setup(
|
---|
1330 | # ...
|
---|
1331 | namespace_packages = ['zope']
|
---|
1332 | )
|
---|
1333 |
|
---|
1334 | because it contains a ``zope.interface`` package that lives in the ``zope``
|
---|
1335 | namespace package. Similarly, a project for a standalone ``zope.publisher``
|
---|
1336 | would also declare the ``zope`` namespace package. When these projects are
|
---|
1337 | installed and used, Python will see them both as part of a "virtual" ``zope``
|
---|
1338 | package, even though they will be installed in different locations.
|
---|
1339 |
|
---|
1340 | Namespace 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 |
|
---|
1344 | Note, by the way, that your project's source tree must include the namespace
|
---|
1345 | packages' ``__init__.py`` files (and the ``__init__.py`` of any parent
|
---|
1346 | packages), in a normal Python package layout. These ``__init__.py`` files
|
---|
1347 | *must* contain the line::
|
---|
1348 |
|
---|
1349 | __import__('pkg_resources').declare_namespace(__name__)
|
---|
1350 |
|
---|
1351 | This code ensures that the namespace package machinery is operating and that
|
---|
1352 | the current package is registered as a namespace package.
|
---|
1353 |
|
---|
1354 | You 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
|
---|
1356 | projects are installed as ``.egg`` files, it will not work when the projects
|
---|
1357 | are installed using "system" packaging tools -- in such cases the
|
---|
1358 | ``__init__.py`` files will not be installed, let alone executed.
|
---|
1359 |
|
---|
1360 | You must include the ``declare_namespace()`` line in the ``__init__.py`` of
|
---|
1361 | *every* project that has contents for the namespace package in question, in
|
---|
1362 | order to ensure that the namespace will be declared regardless of which
|
---|
1363 | project'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
|
---|
1365 | other copies will ever be loaded!)
|
---|
1366 |
|
---|
1367 |
|
---|
1368 | TRANSITIONAL NOTE
|
---|
1369 | ~~~~~~~~~~~~~~~~~
|
---|
1370 |
|
---|
1371 | Setuptools 0.6a automatically calls ``declare_namespace()`` for you at runtime,
|
---|
1372 | but the 0.7a versions will *not*. This is because the automatic declaration
|
---|
1373 | feature has some negative side effects, such as needing to import all namespace
|
---|
1374 | packages during the initialization of the ``pkg_resources`` runtime, and also
|
---|
1375 | the need for ``pkg_resources`` to be explicitly imported before any namespace
|
---|
1376 | packages work at all. Beginning with the 0.7a releases, you'll be responsible
|
---|
1377 | for including your own declaration lines, and the automatic declaration feature
|
---|
1378 | will be dropped to get rid of the negative side effects.
|
---|
1379 |
|
---|
1380 | During the remainder of the 0.6 development cycle, therefore, setuptools will
|
---|
1381 | warn you about missing ``declare_namespace()`` calls in your ``__init__.py``
|
---|
1382 | files, and you should correct these as soon as possible before setuptools 0.7a1
|
---|
1383 | is released. Namespace packages without declaration lines will not work
|
---|
1384 | correctly once a user has upgraded to setuptools 0.7a1, so it's important that
|
---|
1385 | you make this change now in order to avoid having your code break in the field.
|
---|
1386 | Our apologies for the inconvenience, and thank you for your patience.
|
---|
1387 |
|
---|
1388 |
|
---|
1389 |
|
---|
1390 | Tagging and "Daily Build" or "Snapshot" Releases
|
---|
1391 | ------------------------------------------------
|
---|
1392 |
|
---|
1393 | When a set of related projects are under development, it may be important to
|
---|
1394 | track finer-grained version increments than you would normally use for e.g.
|
---|
1395 | "stable" releases. While stable releases might be measured in dotted numbers
|
---|
1396 | with alpha/beta/etc. status codes, development versions of a project often
|
---|
1397 | need to be tracked by revision or build number or even build date. This is
|
---|
1398 | especially true when projects in development need to refer to one another, and
|
---|
1399 | therefore may literally need an up-to-the-minute version of something!
|
---|
1400 |
|
---|
1401 | To support these scenarios, ``setuptools`` allows you to "tag" your source and
|
---|
1402 | egg 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 |
|
---|
1416 | You can add these tags by adding ``egg_info`` and the desired options to
|
---|
1417 | the command line ahead of the ``sdist`` or ``bdist`` commands that you want
|
---|
1418 | to 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
|
---|
1423 | post-release tags affect how setuptools and EasyInstall interpret version
|
---|
1424 | numbers. This is important in order to make sure that dependency processing
|
---|
1425 | tools will know which versions of your project are newer than others.)
|
---|
1426 |
|
---|
1427 | Finally, if you are creating builds frequently, and either building them in a
|
---|
1428 | downloadable location or are copying them to a distribution server, you should
|
---|
1429 | probably also check out the `rotate`_ command, which lets you automatically
|
---|
1430 | delete all but the N most-recently-modified distributions matching a glob
|
---|
1431 | pattern. So, you can use a command line like::
|
---|
1432 |
|
---|
1433 | setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
|
---|
1434 |
|
---|
1435 | to build an egg whose version info includes 'DEV-rNNNN' (where NNNN is the
|
---|
1436 | most recent Subversion revision that affected the source tree), and then
|
---|
1437 | delete any egg files from the distribution directory except for the three
|
---|
1438 | that were built most recently.
|
---|
1439 |
|
---|
1440 | If you have to manage automated builds for multiple packages, each with
|
---|
1441 | different 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``
|
---|
1443 | that would perform the necessary tag, build, and rotate commands. Then, a
|
---|
1444 | simpler script or cron job could just run ``setup.py daily`` in each project
|
---|
1445 | directory. (And, you could also define sitewide or per-user default versions
|
---|
1446 | of the ``daily`` alias, so that projects that didn't define their own would
|
---|
1447 | use the appropriate defaults.)
|
---|
1448 |
|
---|
1449 |
|
---|
1450 | Generating Source Distributions
|
---|
1451 | -------------------------------
|
---|
1452 |
|
---|
1453 | ``setuptools`` enhances the distutils' default algorithm for source file
|
---|
1454 | selection, so that all files managed by CVS or Subversion in your project tree
|
---|
1455 | are included in any source distribution you build. This is a big improvement
|
---|
1456 | over having to manually write a ``MANIFEST.in`` file and try to keep it in
|
---|
1457 | sync with your project. So, if you are using CVS or Subversion, and your
|
---|
1458 | source distributions only need to include files that you're tracking in
|
---|
1459 | revision 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
|
---|
1461 | you would otherwise have to change it.)
|
---|
1462 |
|
---|
1463 | (NOTE: other revision control systems besides CVS and Subversion can be
|
---|
1464 | supported using plugins; see the section below on `Adding Support for Other
|
---|
1465 | Revision Control Systems`_ for information on how to write such plugins.)
|
---|
1466 |
|
---|
1467 | If you need to include automatically generated files, or files that are kept in
|
---|
1468 | an unsupported revision control system, you'll need to create a ``MANIFEST.in``
|
---|
1469 | file to specify any files that the default file location algorithm doesn't
|
---|
1470 | catch. See the distutils documentation for more information on the format of
|
---|
1471 | the ``MANIFEST.in`` file.
|
---|
1472 |
|
---|
1473 | But, 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
|
---|
1475 | from these issues and doesn't work the same way in any case. Unlike the
|
---|
1476 | distutils, setuptools regenerates the source distribution manifest file
|
---|
1477 | every time you build a source distribution, and it builds it inside the
|
---|
1478 | project's ``.egg-info`` directory, out of the way of your main project
|
---|
1479 | directory. You therefore need not worry about whether it is up-to-date or not.
|
---|
1480 |
|
---|
1481 | Indeed, because setuptools' approach to determining the contents of a source
|
---|
1482 | distribution is so much simpler, its ``sdist`` command omits nearly all of
|
---|
1483 | the options that the distutils' more complex ``sdist`` process requires. For
|
---|
1484 | all practical purposes, you'll probably use only the ``--formats`` option, if
|
---|
1485 | you use any option at all.
|
---|
1486 |
|
---|
1487 | (By the way, if you're using some other revision control system, you might
|
---|
1488 | consider 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 |
|
---|
1494 | Making your package available for EasyInstall
|
---|
1495 | ---------------------------------------------
|
---|
1496 |
|
---|
1497 | If you use the ``register`` command (``setup.py register``) to register your
|
---|
1498 | package 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 |
|
---|
1503 | If you also use the `upload`_ command to upload actual distributions of your
|
---|
1504 | package, that's even better, because EasyInstall will be able to find and
|
---|
1505 | download them directly from your project's PyPI page.
|
---|
1506 |
|
---|
1507 | However, there may be reasons why you don't want to upload distributions to
|
---|
1508 | PyPI, and just want your existing distributions (or perhaps a Subversion
|
---|
1509 | checkout) to be used instead.
|
---|
1510 |
|
---|
1511 | So here's what you need to do before running the ``register`` command. There
|
---|
1512 | are 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 |
|
---|
1524 | A 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
|
---|
1527 | attempts to determine a project name and optional version number from the text
|
---|
1528 | of a primary link *without* downloading it. When it has found all the primary
|
---|
1529 | links, EasyInstall will select the best match based on requested version,
|
---|
1530 | platform compatibility, and other criteria.
|
---|
1531 |
|
---|
1532 | So, if your ``url`` or ``download_url`` point either directly to a downloadable
|
---|
1533 | source distribution, or to HTML page(s) that have direct links to such, then
|
---|
1534 | EasyInstall will be able to locate downloads automatically. If you want to
|
---|
1535 | make Subversion checkouts available, then you should create links with either
|
---|
1536 | ``#egg=project`` or ``#egg=project-version`` added to the URL. You should
|
---|
1537 | replace ``project`` and ``version`` with the values they would have in an egg
|
---|
1538 | filename. (Be sure to actually generate an egg and then use the initial part
|
---|
1539 | of the filename, rather than trying to guess what the escaped form of the
|
---|
1540 | project name and version number will be.)
|
---|
1541 |
|
---|
1542 | Note that Subversion checkout links are of lower precedence than other kinds
|
---|
1543 | of distributions, so EasyInstall will not select a Subversion checkout for
|
---|
1544 | downloading unless it has a version included in the ``#egg=`` suffix, and
|
---|
1545 | it's a higher version than EasyInstall has seen in any other links for your
|
---|
1546 | project.
|
---|
1547 |
|
---|
1548 | As 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
|
---|
1550 | this::
|
---|
1551 |
|
---|
1552 | easy_install --editable projectname==dev
|
---|
1553 |
|
---|
1554 | in order to check out the in-development version of ``projectname``.
|
---|
1555 |
|
---|
1556 |
|
---|
1557 | Managing "Continuous Releases" Using Subversion
|
---|
1558 | -----------------------------------------------
|
---|
1559 |
|
---|
1560 | If you expect your users to track in-development versions of your project via
|
---|
1561 | Subversion, there are a few additional steps you should take to ensure that
|
---|
1562 | things work smoothly with EasyInstall. First, you should add the following
|
---|
1563 | to your project's ``setup.cfg`` file::
|
---|
1564 |
|
---|
1565 | [egg_info]
|
---|
1566 | tag_build = .dev
|
---|
1567 | tag_svn_revision = 1
|
---|
1568 |
|
---|
1569 | This 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
|
---|
1572 | infrastructure (including ``setuptools``, ``pkg_resources`` and EasyInstall)
|
---|
1573 | will know that ``1.0a1`` supersedes any interim snapshots from Subversion, and
|
---|
1574 | handle upgrades accordingly.
|
---|
1575 |
|
---|
1576 | (Note: the project version number you specify in ``setup.py`` should always be
|
---|
1577 | the *next* version of your software, not the last released version.
|
---|
1578 | Alternately, 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,
|
---|
1581 | however, seem to prefer to think of their project as being a future version
|
---|
1582 | still under development, rather than a past version being patched. It is of
|
---|
1583 | course possible for a single project to have both situations, using
|
---|
1584 | post-release numbering on release branches, and pre-release numbering on the
|
---|
1585 | trunk. But you don't have to make things this complex if you don't want to.)
|
---|
1586 |
|
---|
1587 | Commonly, projects releasing code from Subversion will include a PyPI link to
|
---|
1588 | their checkout URL (as described in the previous section) with an
|
---|
1589 | ``#egg=projectname-dev`` suffix. This allows users to request EasyInstall
|
---|
1590 | to download ``projectname==dev`` in order to get the latest in-development
|
---|
1591 | code. Note that if your project depends on such in-progress code, you may wish
|
---|
1592 | to specify your ``install_requires`` (or other requirements) to include
|
---|
1593 | ``==dev``, e.g.::
|
---|
1594 |
|
---|
1595 | install_requires = ["OtherProject>=0.2a1.dev-r143,==dev"]
|
---|
1596 |
|
---|
1597 | The above example says, "I really want at least this particular development
|
---|
1598 | revision number, but feel free to follow and use an ``#egg=OtherProject-dev``
|
---|
1599 | link if you find one". This avoids the need to have actual source or binary
|
---|
1600 | distribution snapshots of in-development code available, just to be able to
|
---|
1601 | depend on the latest and greatest a project has to offer.
|
---|
1602 |
|
---|
1603 | A final note for Subversion development: if you are using SVN revision tags
|
---|
1604 | as described in this section, it's a good idea to run ``setup.py develop``
|
---|
1605 | after each Subversion checkin or update, because your project's version number
|
---|
1606 | will be changing, and your script wrappers need to be updated accordingly.
|
---|
1607 |
|
---|
1608 | Also, if the project's requirements have changed, the ``develop`` command will
|
---|
1609 | take care of fetching the updated dependencies, building changed extensions,
|
---|
1610 | etc. Be sure to also remind any of your users who check out your project
|
---|
1611 | from Subversion that they need to run ``setup.py develop`` after every update
|
---|
1612 | in order to keep their checkout completely in sync.
|
---|
1613 |
|
---|
1614 |
|
---|
1615 | Making "Official" (Non-Snapshot) Releases
|
---|
1616 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
---|
1617 |
|
---|
1618 | When you make an official release, creating source or binary distributions,
|
---|
1619 | you will need to override the tag settings from ``setup.cfg``, so that you
|
---|
1620 | don't end up registering versions like ``foobar-0.7a1.dev-r34832``. This is
|
---|
1621 | easy to do if you are developing on the trunk and using tags or branches for
|
---|
1622 | your releases - just make the change to ``setup.cfg`` after branching or
|
---|
1623 | tagging the release, so the trunk will still produce development snapshots.
|
---|
1624 |
|
---|
1625 | Alternately, if you are not branching for releases, you can override the
|
---|
1626 | default version options on the command line, using something like::
|
---|
1627 |
|
---|
1628 | python setup.py egg_info -RDb "" sdist bdist_egg register upload
|
---|
1629 |
|
---|
1630 | The first part of this command (``egg_info -RDb ""``) will override the
|
---|
1631 | configured tag information, before creating source and binary eggs, registering
|
---|
1632 | the project with PyPI, and uploading the files. Thus, these commands will use
|
---|
1633 | the plain version from your ``setup.py``, without adding the Subversion
|
---|
1634 | revision number or build designation string.
|
---|
1635 |
|
---|
1636 | Of course, if you will be doing this a lot, you may wish to create a personal
|
---|
1637 | alias for this operation, e.g.::
|
---|
1638 |
|
---|
1639 | python setup.py alias -u release egg_info -RDb ""
|
---|
1640 |
|
---|
1641 | You can then use it like this::
|
---|
1642 |
|
---|
1643 | python setup.py release sdist bdist_egg register upload
|
---|
1644 |
|
---|
1645 | Or of course you can create more elaborate aliases that do all of the above.
|
---|
1646 | See the sections below on the `egg_info`_ and `alias`_ commands for more ideas.
|
---|
1647 |
|
---|
1648 |
|
---|
1649 |
|
---|
1650 | Distributing Extensions compiled with Pyrex
|
---|
1651 | -------------------------------------------
|
---|
1652 |
|
---|
1653 | ``setuptools`` includes transparent support for building Pyrex extensions, as
|
---|
1654 | long as you define your extensions using ``setuptools.Extension``, *not*
|
---|
1655 | ``distutils.Extension``. You must also not import anything from Pyrex in
|
---|
1656 | your setup script.
|
---|
1657 |
|
---|
1658 | If you follow these rules, you can safely list ``.pyx`` files as the source
|
---|
1659 | of your ``Extension`` objects in the setup script. ``setuptools`` will detect
|
---|
1660 | at build time whether Pyrex is installed or not. If it is, then ``setuptools``
|
---|
1661 | will use it. If not, then ``setuptools`` will silently change the
|
---|
1662 | ``Extension`` objects to refer to the ``.c`` counterparts of the ``.pyx``
|
---|
1663 | files, so that the normal distutils C compilation process will occur.
|
---|
1664 |
|
---|
1665 | Of course, for this to work, your source distributions must include the C
|
---|
1666 | code generated by Pyrex, as well as your original ``.pyx`` files. This means
|
---|
1667 | that you will probably want to include current ``.c`` files in your revision
|
---|
1668 | control system, rebuilding them whenever you check changes in for the ``.pyx``
|
---|
1669 | source files. This will ensure that people tracking your project in CVS or
|
---|
1670 | Subversion will be able to build it even if they don't have Pyrex installed,
|
---|
1671 | and that your source releases will be similarly usable with or without Pyrex.
|
---|
1672 |
|
---|
1673 |
|
---|
1674 | -----------------
|
---|
1675 | Command Reference
|
---|
1676 | -----------------
|
---|
1677 |
|
---|
1678 | .. _alias:
|
---|
1679 |
|
---|
1680 | ``alias`` - Define shortcuts for commonly used commands
|
---|
1681 | =======================================================
|
---|
1682 |
|
---|
1683 | Sometimes, you need to use the same commands over and over, but you can't
|
---|
1684 | necessarily set them as defaults. For example, if you produce both development
|
---|
1685 | snapshot releases and "stable" releases of a project, you may want to put
|
---|
1686 | the distributions in different places, or use different ``egg_info`` tagging
|
---|
1687 | options, etc. In these cases, it doesn't make sense to set the options in
|
---|
1688 | a distutils configuration file, because the values of the options changed based
|
---|
1689 | on what you're trying to do.
|
---|
1690 |
|
---|
1691 | Setuptools therefore allows you to define "aliases" - shortcut names for
|
---|
1692 | an arbitrary string of commands and options, using ``setup.py alias aliasname
|
---|
1693 | expansion``, where aliasname is the name of the new alias, and the remainder of
|
---|
1694 | the command line supplies its expansion. For example, this command defines
|
---|
1695 | a sitewide alias called "daily", that sets various ``egg_info`` tagging
|
---|
1696 | options::
|
---|
1697 |
|
---|
1698 | setup.py alias --global-config daily egg_info --tag-svn-revision \
|
---|
1699 | --tag-build=development
|
---|
1700 |
|
---|
1701 | Once the alias is defined, it can then be used with other setup commands,
|
---|
1702 | e.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 |
|
---|
1708 | The above commands are interpreted as if the word ``daily`` were replaced with
|
---|
1709 | ``egg_info --tag-svn-revision --tag-build=development``.
|
---|
1710 |
|
---|
1711 | Note that setuptools will expand each alias *at most once* in a given command
|
---|
1712 | line. This serves two purposes. First, if you accidentally create an alias
|
---|
1713 | loop, it will have no effect; you'll instead get an error message about an
|
---|
1714 | unknown command. Second, it allows you to define an alias for a command, that
|
---|
1715 | uses that command. For example, this (project-local) alias::
|
---|
1716 |
|
---|
1717 | setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg
|
---|
1718 |
|
---|
1719 | redefines the ``bdist_egg`` command so that it always runs the ``rotate``
|
---|
1720 | command afterwards to delete all but the newest egg file. It doesn't loop
|
---|
1721 | indefinitely on ``bdist_egg`` because the alias is only expanded once when
|
---|
1722 | used.
|
---|
1723 |
|
---|
1724 | You can remove a defined alias with the ``--remove`` (or ``-r``) option, e.g.::
|
---|
1725 |
|
---|
1726 | setup.py alias --global-config --remove daily
|
---|
1727 |
|
---|
1728 | would delete the "daily" alias we defined above.
|
---|
1729 |
|
---|
1730 | Aliases can be defined on a project-specific, per-user, or sitewide basis. The
|
---|
1731 | default is to define or remove a project-specific alias, but you can use any of
|
---|
1732 | the `configuration file options`_ (listed under the `saveopts`_ command, below)
|
---|
1733 | to determine which distutils configuration file an aliases will be added to
|
---|
1734 | (or removed from).
|
---|
1735 |
|
---|
1736 | Note that if you omit the "expansion" argument to the ``alias`` command,
|
---|
1737 | you'll get output showing that alias' current definition (and what
|
---|
1738 | configuration file it's defined in). If you omit the alias name as well,
|
---|
1739 | you'll get a listing of all current aliases along with their configuration
|
---|
1740 | file locations.
|
---|
1741 |
|
---|
1742 |
|
---|
1743 | ``bdist_egg`` - Create a Python Egg for the project
|
---|
1744 | ===================================================
|
---|
1745 |
|
---|
1746 | This command generates a Python Egg (``.egg`` file) for the project. Python
|
---|
1747 | Eggs are the preferred binary distribution format for EasyInstall, because they
|
---|
1748 | are cross-platform (for "pure" packages), directly importable, and contain
|
---|
1749 | project metadata including scripts and information about the project's
|
---|
1750 | dependencies. They can be simply downloaded and added to ``sys.path``
|
---|
1751 | directly, or they can be placed in a directory on ``sys.path`` and then
|
---|
1752 | automatically discovered by the egg runtime system.
|
---|
1753 |
|
---|
1754 | This command runs the `egg_info`_ command (if it hasn't already run) to update
|
---|
1755 | the project's metadata (``.egg-info``) directory. If you have added any extra
|
---|
1756 | metadata files to the ``.egg-info`` directory, those files will be included in
|
---|
1757 | the new egg file's metadata directory, for use by the egg runtime system or by
|
---|
1758 | any applications or frameworks that use that metadata.
|
---|
1759 |
|
---|
1760 | You won't usually need to specify any special options for this command; just
|
---|
1761 | use ``bdist_egg`` and you're done. But there are a few options that may
|
---|
1762 | be 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 |
|
---|
1794 | There are also some options you will probably never need, but which are there
|
---|
1795 | because they were copied from similar ``bdist`` commands used as an example for
|
---|
1796 | creating this one. They may be useful for testing and debugging, however,
|
---|
1797 | which 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 |
|
---|
1819 | This 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
|
---|
1821 | done in such a way that changes to the project source are immediately available
|
---|
1822 | in the staging area(s), without needing to run a build or install step after
|
---|
1823 | each change.
|
---|
1824 |
|
---|
1825 | The ``develop`` command works by creating an ``.egg-link`` file (named for the
|
---|
1826 | project) 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
|
---|
1828 | that the project is on ``sys.path`` by default for all programs run using that
|
---|
1829 | Python installation.
|
---|
1830 |
|
---|
1831 | The ``develop`` command also installs wrapper scripts in the staging area (or
|
---|
1832 | a separate directory, as specified) that will ensure the project's dependencies
|
---|
1833 | are available on ``sys.path`` before running the project's source scripts.
|
---|
1834 | And, it ensures that any missing project dependencies are available in the
|
---|
1835 | staging area, by downloading and installing them if necessary.
|
---|
1836 |
|
---|
1837 | Last, but not least, the ``develop`` command invokes the ``build_ext -i``
|
---|
1838 | command to ensure any C extensions in the project have been built and are
|
---|
1839 | up-to-date, and the ``egg_info`` command to ensure the project's metadata is
|
---|
1840 | updated (so that the runtime and wrappers know what the project's dependencies
|
---|
1841 | are). If you make any changes to the project's setup script or C extensions,
|
---|
1842 | you should rerun the ``develop`` command against all relevant staging areas to
|
---|
1843 | keep the project's scripts, metadata and extensions up-to-date. Most other
|
---|
1844 | kinds of changes to your project should not require any build operations or
|
---|
1845 | rerunning ``develop``, but keep in mind that even minor changes to the setup
|
---|
1846 | script (e.g. changing an entry point definition) require you to re-run the
|
---|
1847 | ``develop`` or ``test`` commands to keep the distribution updated.
|
---|
1848 |
|
---|
1849 | Here are some of the options that the ``develop`` command accepts. Note that
|
---|
1850 | they affect the project's dependencies as well as the project itself, so if you
|
---|
1851 | have dependencies that need to be installed and you use ``--exclude-scripts``
|
---|
1852 | (for example), the dependencies' scripts will not be installed either! For
|
---|
1853 | this reason, you may want to use EasyInstall to install the project's
|
---|
1854 | dependencies before using the ``develop`` command, if you need finer control
|
---|
1855 | over 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 |
|
---|
1924 | In addition to the above options, the ``develop`` command also accepts all of
|
---|
1925 | the same options accepted by ``easy_install``. If you've configured any
|
---|
1926 | ``easy_install`` settings in your ``setup.cfg`` (or other distutils config
|
---|
1927 | files), the ``develop`` command will use them as defaults, unless you override
|
---|
1928 | them in a ``[develop]`` section or on the command line.
|
---|
1929 |
|
---|
1930 |
|
---|
1931 | ``easy_install`` - Find and install packages
|
---|
1932 | ============================================
|
---|
1933 |
|
---|
1934 | This command runs the `EasyInstall tool
|
---|
1935 | <http://peak.telecommunity.com/DevCenter/EasyInstall>`_ for you. It is exactly
|
---|
1936 | equivalent to running the ``easy_install`` command. All command line arguments
|
---|
1937 | following this command are consumed and not processed further by the distutils,
|
---|
1938 | so this must be the last command listed on the command line. Please see
|
---|
1939 | the EasyInstall documentation for the options reference and usage examples.
|
---|
1940 | Normally, there is no reason to use this command via the command line, as you
|
---|
1941 | can just use ``easy_install`` directly. It's only listed here so that you know
|
---|
1942 | it'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 |
|
---|
1955 | This command performs two operations: it updates a project's ``.egg-info``
|
---|
1956 | metadata directory (used by the ``bdist_egg``, ``develop``, and ``test``
|
---|
1957 | commands), and it allows you to temporarily change a project's version string,
|
---|
1958 | to support "daily builds" or "snapshot" releases. It is run automatically by
|
---|
1959 | the ``sdist``, ``bdist_egg``, ``develop``, ``register``, and ``test`` commands
|
---|
1960 | in order to update the project's metadata, but you can also specify it
|
---|
1961 | explicitly in order to temporarily change the project's version string while
|
---|
1962 | executing other commands. (It also generates the``.egg-info/SOURCES.txt``
|
---|
1963 | manifest file, which is used when you are building source distributions.)
|
---|
1964 |
|
---|
1965 | In addition to writing the core egg metadata defined by ``setuptools`` and
|
---|
1966 | required by ``pkg_resources``, this command can be extended to write other
|
---|
1967 | metadata files as well, by defining entry points in the ``egg_info.writers``
|
---|
1968 | group. See the section on `Adding new EGG-INFO Files`_ below for more details.
|
---|
1969 | Note that using additional metadata writers may require you to include a
|
---|
1970 | ``setup_requires`` argument to ``setup()`` in order to ensure that the desired
|
---|
1971 | writers are available on ``sys.path``.
|
---|
1972 |
|
---|
1973 |
|
---|
1974 | Release Tagging Options
|
---|
1975 | -----------------------
|
---|
1976 |
|
---|
1977 | The following options can be used to modify the project's version string for
|
---|
1978 | all remaining commands on the setup command line. The options are processed
|
---|
1979 | in the order shown, so if you use more than one, the requested tags will be
|
---|
1980 | added 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
|
---|
2027 | binary distributions of your project, you should first make sure that you know
|
---|
2028 | how the resulting version numbers will be interpreted by automated tools
|
---|
2029 | like EasyInstall. See the section above on `Specifying Your Project's
|
---|
2030 | Version`_ for an explanation of pre- and post-release tags, as well as tips on
|
---|
2031 | how to choose and verify a versioning scheme for your your project.)
|
---|
2032 |
|
---|
2033 | For advanced uses, there is one other option that can be set, to change the
|
---|
2034 | location of the project's ``.egg-info`` directory. Commands that need to find
|
---|
2035 | the project's source directory or metadata should get it from this setting:
|
---|
2036 |
|
---|
2037 |
|
---|
2038 | Other ``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 |
|
---|
2054 | Creating a dated "nightly build" snapshot egg::
|
---|
2055 |
|
---|
2056 | python setup.py egg_info --tag-date --tag-build=DEV bdist_egg
|
---|
2057 |
|
---|
2058 | Creating and uploading a release with no version tags, even if some default
|
---|
2059 | tags 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
|
---|
2064 | commands 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 |
|
---|
2072 | The setuptools ``install`` command is basically a shortcut to run the
|
---|
2073 | ``easy_install`` command on the current project. However, for convenience
|
---|
2074 | in creating "system packages" of setuptools-based projects, you can also
|
---|
2075 | use 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 |
|
---|
2085 | This option is automatically in effect when ``install`` is invoked by another
|
---|
2086 | distutils command, so that commands like ``bdist_wininst`` and ``bdist_rpm``
|
---|
2087 | will create system packages of eggs. It is also automatically in effect if
|
---|
2088 | you specify the ``--root`` option.
|
---|
2089 |
|
---|
2090 |
|
---|
2091 | ``install_egg_info`` - Install an ``.egg-info`` directory in ``site-packages``
|
---|
2092 | ==============================================================================
|
---|
2093 |
|
---|
2094 | Setuptools runs this command as part of ``install`` operations that use the
|
---|
2095 | ``--single-version-externally-managed`` options. You should not invoke it
|
---|
2096 | directly; it is documented here for completeness and so that distutils
|
---|
2097 | extensions such as system package builders can make use of it. This command
|
---|
2098 | has 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 |
|
---|
2106 | This command assumes that the ``egg_info`` command has been given valid options
|
---|
2107 | via the command line or ``setup.cfg``, as it will invoke the ``egg_info``
|
---|
2108 | command and use its options to locate the project's source ``.egg-info``
|
---|
2109 | directory.
|
---|
2110 |
|
---|
2111 |
|
---|
2112 | .. _rotate:
|
---|
2113 |
|
---|
2114 | ``rotate`` - Delete outdated distribution files
|
---|
2115 | ===============================================
|
---|
2116 |
|
---|
2117 | As you develop new versions of your project, your distribution (``dist``)
|
---|
2118 | directory will gradually fill up with older source and/or binary distribution
|
---|
2119 | files. The ``rotate`` command lets you automatically clean these up, keeping
|
---|
2120 | only 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
|
---|
2143 | for 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
|
---|
2148 | directory, 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 |
|
---|
2158 | Finding and editing ``distutils`` configuration files can be a pain, especially
|
---|
2159 | since you also have to translate the configuration options from command-line
|
---|
2160 | form to the proper configuration file format. You can avoid these hassles by
|
---|
2161 | using the ``saveopts`` command. Just add it to the command line to save the
|
---|
2162 | options you used. For example, this command builds the project using
|
---|
2163 | the ``mingw32`` C compiler, then saves the --compiler setting as the default
|
---|
2164 | for future builds (even those run implicitly by the ``install`` command)::
|
---|
2165 |
|
---|
2166 | setup.py build --compiler=mingw32 saveopts
|
---|
2167 |
|
---|
2168 | The ``saveopts`` command saves all options for every commmand specified on the
|
---|
2169 | command line to the project's local ``setup.cfg`` file, unless you use one of
|
---|
2170 | the `configuration file options`_ to change where the options are saved. For
|
---|
2171 | example, this command does the same as above, but saves the compiler setting
|
---|
2172 | to the site-wide (global) distutils configuration::
|
---|
2173 |
|
---|
2174 | setup.py build --compiler=mingw32 saveopts -g
|
---|
2175 |
|
---|
2176 | Note that it doesn't matter where you place the ``saveopts`` command on the
|
---|
2177 | command line; it will still save all the options specified for all commands.
|
---|
2178 | For example, this is another valid way to spell the last example::
|
---|
2179 |
|
---|
2180 | setup.py saveopts -g build --compiler=mingw32
|
---|
2181 |
|
---|
2182 | Note, however, that all of the commands specified are always run, regardless of
|
---|
2183 | where ``saveopts`` is placed on the command line.
|
---|
2184 |
|
---|
2185 |
|
---|
2186 | Configuration File Options
|
---|
2187 | --------------------------
|
---|
2188 |
|
---|
2189 | Normally, settings such as options and aliases are saved to the project's
|
---|
2190 | local ``setup.cfg`` file. But you can override this and save them to the
|
---|
2191 | global 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 |
|
---|
2210 | These options are used by other ``setuptools`` commands that modify
|
---|
2211 | configuration 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 |
|
---|
2219 | This command is mainly for use by scripts, but it can also be used as a quick
|
---|
2220 | and dirty way to change a distutils configuration option without having to
|
---|
2221 | remember 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
|
---|
2224 | names)::
|
---|
2225 |
|
---|
2226 | setup.py setopt --command=build --option=compiler --set-value=mingw32
|
---|
2227 |
|
---|
2228 | **Example 2**. Remove any setting for the distutils default package
|
---|
2229 | installation directory (short option names)::
|
---|
2230 |
|
---|
2231 | setup.py setopt -c install -o install_lib -r
|
---|
2232 |
|
---|
2233 |
|
---|
2234 | Options 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 |
|
---|
2249 | In addition to the above options, you may use any of the `configuration file
|
---|
2250 | options`_ (listed under the `saveopts`_ command, above) to determine which
|
---|
2251 | distutils 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 |
|
---|
2259 | When doing test-driven development, or running automated builds that need
|
---|
2260 | testing before they are deployed for downloading or use, it's often useful
|
---|
2261 | to be able to run a project's unit tests without actually deploying the project
|
---|
2262 | anywhere, even using the ``develop`` command. The ``test`` command runs a
|
---|
2263 | project's unit tests without actually deploying it, by temporarily putting the
|
---|
2264 | project'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
|
---|
2266 | up-to-date.
|
---|
2267 |
|
---|
2268 | To use this command, your project's tests must be wrapped in a ``unittest``
|
---|
2269 | test suite by either a function, a ``TestCase`` class or method, or a module
|
---|
2270 | or package containing ``TestCase`` classes. If the named suite is a module,
|
---|
2271 | and the module has an ``additional_tests()`` function, it is called and the
|
---|
2272 | result (which must be a ``unittest.TestSuite``) is added to the tests to be
|
---|
2273 | run. If the named suite is a package, any submodules and subpackages are
|
---|
2274 | recursively added to the overall test suite. (Note: if your project specifies
|
---|
2275 | a ``test_loader``, the rules for processing the chosen ``test_suite`` may
|
---|
2276 | differ; see the `test_loader`_ documentation for more details.)
|
---|
2277 |
|
---|
2278 | Note that many test systems including ``doctest`` support wrapping their
|
---|
2279 | non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test
|
---|
2280 | package that does not support this, we suggest you encourage its developers to
|
---|
2281 | implement test suite support, as this is a convenient and standard way to
|
---|
2282 | aggregate a collection of tests to be run under a common test harness.
|
---|
2283 |
|
---|
2284 | By default, tests will be run in the "verbose" mode of the ``unittest``
|
---|
2285 | package's text test runner, but you can get the "quiet" mode (just dots) if
|
---|
2286 | you supply the ``-q`` or ``--quiet`` option, either as a global option to
|
---|
2287 | the setup script (e.g. ``setup.py -q test``) or as an option for the ``test``
|
---|
2288 | command itself (e.g. ``setup.py test -q``). There is one other option
|
---|
2289 | available:
|
---|
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 |
|
---|
2310 | PyPI now supports uploading project files for redistribution; uploaded files
|
---|
2311 | are easily found by EasyInstall, even if you don't have download links on your
|
---|
2312 | project's home page.
|
---|
2313 |
|
---|
2314 | Although Python 2.5 will support uploading all types of distributions to PyPI,
|
---|
2315 | setuptools only supports source distributions and eggs. (This is partly
|
---|
2316 | because PyPI's upload support is currently broken for various other file
|
---|
2317 | types.) 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 |
|
---|
2324 | Note that to upload files for a project, the corresponding version must already
|
---|
2325 | be registered with PyPI, using the distutils ``register`` command. It's
|
---|
2326 | usually a good idea to include the ``register`` command at the start of the
|
---|
2327 | command line, so that any registration problems can be found and fixed before
|
---|
2328 | building and uploading the distributions, e.g.::
|
---|
2329 |
|
---|
2330 | setup.py register sdist bdist_egg upload
|
---|
2331 |
|
---|
2332 | This will update PyPI's listing for your project's current version.
|
---|
2333 |
|
---|
2334 | Note, by the way, that the metadata in your ``setup()`` call determines what
|
---|
2335 | will be listed in PyPI for your package. Try to fill out as much of it as
|
---|
2336 | possible, as it will save you a lot of trouble manually adding and updating
|
---|
2337 | your PyPI listings. Just put it in ``setup.py`` and use the ``register``
|
---|
2338 | comamnd to keep PyPI up to date.
|
---|
2339 |
|
---|
2340 | The ``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 | ------------------------------------
|
---|
2361 | Extending and Reusing ``setuptools``
|
---|
2362 | ------------------------------------
|
---|
2363 |
|
---|
2364 | Creating ``distutils`` Extensions
|
---|
2365 | =================================
|
---|
2366 |
|
---|
2367 | It can be hard to add new commands or setup arguments to the distutils. But
|
---|
2368 | the ``setuptools`` package makes it a bit easier, by allowing you to distribute
|
---|
2369 | a distutils extension as a separate project, and then have projects that need
|
---|
2370 | the extension just refer to it in their ``setup_requires`` argument.
|
---|
2371 |
|
---|
2372 | With ``setuptools``, your distutils extension projects can hook in new
|
---|
2373 | commands and ``setup()`` arguments just by defining "entry points". These
|
---|
2374 | are mappings from command or argument names to a specification of where to
|
---|
2375 | import a handler from. (See the section on `Dynamic Discovery of Services and
|
---|
2376 | Plugins`_ above for some more background on entry points.)
|
---|
2377 |
|
---|
2378 |
|
---|
2379 | Adding Commands
|
---|
2380 | ---------------
|
---|
2381 |
|
---|
2382 | You can add new ``setup`` commands by defining entry points in the
|
---|
2383 | ``distutils.commands`` group. For example, if you wanted to add a ``foo``
|
---|
2384 | command, you might add something like this to your distutils extension
|
---|
2385 | project'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
|
---|
2397 | a ``setuptools.Command`` subclass.)
|
---|
2398 |
|
---|
2399 | Once 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
|
---|
2401 | directory) the command(s) will be available to any ``setuptools``-based setup
|
---|
2402 | scripts. It is not necessary to use the ``--command-packages`` option or
|
---|
2403 | to monkeypatch the ``distutils.command`` package to install your commands;
|
---|
2404 | ``setuptools`` automatically adds a wrapper to the distutils to search for
|
---|
2405 | entry points in the active distributions on ``sys.path``. In fact, this is
|
---|
2406 | how setuptools' own commands are installed: the setuptools project's setup
|
---|
2407 | script defines entry points for them!
|
---|
2408 |
|
---|
2409 |
|
---|
2410 | Adding ``setup()`` Arguments
|
---|
2411 | ----------------------------
|
---|
2412 |
|
---|
2413 | Sometimes, your commands may need additional arguments to the ``setup()``
|
---|
2414 | call. You can enable this by defining entry points in the
|
---|
2415 | ``distutils.setup_keywords`` group. For example, if you wanted a ``setup()``
|
---|
2416 | argument called ``bar_baz``, you might add something like this to your
|
---|
2417 | distutils 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 |
|
---|
2431 | The idea here is that the entry point defines a function that will be called
|
---|
2432 | to validate the ``setup()`` argument, if it's supplied. The ``Distribution``
|
---|
2433 | object will have the initial value of the attribute set to ``None``, and the
|
---|
2434 | validation function will only be called if the ``setup()`` call sets it to
|
---|
2435 | a 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 |
|
---|
2444 | Your function should accept three arguments: the ``Distribution`` object,
|
---|
2445 | the attribute name, and the attribute value. It should raise a
|
---|
2446 | ``DistutilsSetupError`` (from the ``distutils.error`` module) if the argument
|
---|
2447 | is invalid. Remember, your function will only be called with non-None values,
|
---|
2448 | and the default value of arguments defined this way is always None. So, your
|
---|
2449 | commands should always be prepared for the possibility that the attribute will
|
---|
2450 | be ``None`` when they access it later.
|
---|
2451 |
|
---|
2452 | If more than one active distribution defines an entry point for the same
|
---|
2453 | ``setup()`` argument, *all* of them will be called. This allows multiple
|
---|
2454 | distutils extensions to define a common argument, as long as they agree on
|
---|
2455 | what values of that argument are valid.
|
---|
2456 |
|
---|
2457 | Also note that as with commands, it is not necessary to subclass or monkeypatch
|
---|
2458 | the distutils ``Distribution`` class in order to add your arguments; it is
|
---|
2459 | sufficient to define the entry points in your extension, as long as any setup
|
---|
2460 | script using your extension lists your project in its ``setup_requires``
|
---|
2461 | argument.
|
---|
2462 |
|
---|
2463 |
|
---|
2464 | Adding new EGG-INFO Files
|
---|
2465 | -------------------------
|
---|
2466 |
|
---|
2467 | Some extensible applications or frameworks may want to allow third parties to
|
---|
2468 | develop plugins with application or framework-specific metadata included in
|
---|
2469 | the plugins' EGG-INFO directory, for easy access via the ``pkg_resources``
|
---|
2470 | metadata API. The easiest way to allow this is to create a distutils extension
|
---|
2471 | to be used from the plugin projects' setup scripts (via ``setup_requires``)
|
---|
2472 | that defines a new setup keyword, and then uses that data to write an EGG-INFO
|
---|
2473 | file when the ``egg_info`` command is run.
|
---|
2474 |
|
---|
2475 | The ``egg_info`` command looks for extension points in an ``egg_info.writers``
|
---|
2476 | group, and calls them to write the files. Here's a simple example of a
|
---|
2477 | distutils extension defining a setup argument ``foo_bar``, which is a list of
|
---|
2478 | lines that will be written to ``foo_bar.txt`` in the EGG-INFO directory of any
|
---|
2479 | project 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 |
|
---|
2493 | This simple example makes use of two utility functions defined by setuptools
|
---|
2494 | for its own use: a routine to validate that a setup keyword is a sequence of
|
---|
2495 | strings, and another one that looks up a setup argument and writes it to
|
---|
2496 | a 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 |
|
---|
2505 | As you can see, ``egg_info.writers`` entry points must be a function taking
|
---|
2506 | three arguments: a ``egg_info`` command instance, the basename of the file to
|
---|
2507 | write (e.g. ``foo_bar.txt``), and the actual full filename that should be
|
---|
2508 | written to.
|
---|
2509 |
|
---|
2510 | In general, writer functions should honor the command object's ``dry_run``
|
---|
2511 | setting when writing files, and use the ``distutils.log`` object to do any
|
---|
2512 | console output. The easiest way to conform to this requirement is to use
|
---|
2513 | the ``cmd`` object's ``write_file()``, ``delete_file()``, and
|
---|
2514 | ``write_or_delete_file()`` methods exclusively for your file operations. See
|
---|
2515 | those methods' docstrings for more details.
|
---|
2516 |
|
---|
2517 |
|
---|
2518 | Adding Support for Other Revision Control Systems
|
---|
2519 | -------------------------------------------------
|
---|
2520 |
|
---|
2521 | If you would like to create a plugin for ``setuptools`` to find files in other
|
---|
2522 | source control systems besides CVS and Subversion, you can do so by adding an
|
---|
2523 | entry point to the ``setuptools.file_finders`` group. The entry point should
|
---|
2524 | be a function accepting a single directory name, and should yield
|
---|
2525 | all the filenames within that directory (and any subdirectories thereof) that
|
---|
2526 | are under revision control.
|
---|
2527 |
|
---|
2528 | For example, if you were going to create a plugin for a revision control system
|
---|
2529 | called "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 |
|
---|
2534 | And 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 |
|
---|
2542 | Then, anyone who wants to use your plugin can simply install it, and their
|
---|
2543 | local setuptools installation will be able to find the necessary files.
|
---|
2544 |
|
---|
2545 | It is not necessary to distribute source control plugins with projects that
|
---|
2546 | simply use the other source control system, or to specify the plugins in
|
---|
2547 | ``setup_requires``. When you create a source distribution with the ``sdist``
|
---|
2548 | command, setuptools automatically records what files were found in the
|
---|
2549 | ``SOURCES.txt`` file. That way, recipients of source distributions don't need
|
---|
2550 | to have revision control at all. However, if someone is working on a package
|
---|
2551 | by checking out with that system, they will need the same plugin(s) that the
|
---|
2552 | original author is using.
|
---|
2553 |
|
---|
2554 | A 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 |
|
---|
2572 | Subclassing ``Command``
|
---|
2573 | -----------------------
|
---|
2574 |
|
---|
2575 | Sorry, this section isn't written yet, and neither is a lot of what's below
|
---|
2576 | this point, except for the change log. You might want to `subscribe to changes
|
---|
2577 | in this page <setuptools?action=subscribe>`_ to see when new documentation is
|
---|
2578 | added or updated.
|
---|
2579 |
|
---|
2580 | XXX
|
---|
2581 |
|
---|
2582 |
|
---|
2583 | Reusing ``setuptools`` Code
|
---|
2584 | ===========================
|
---|
2585 |
|
---|
2586 | ``ez_setup``
|
---|
2587 | ------------
|
---|
2588 |
|
---|
2589 | XXX
|
---|
2590 |
|
---|
2591 |
|
---|
2592 | ``setuptools.archive_util``
|
---|
2593 | ---------------------------
|
---|
2594 |
|
---|
2595 | XXX
|
---|
2596 |
|
---|
2597 |
|
---|
2598 | ``setuptools.sandbox``
|
---|
2599 | ----------------------
|
---|
2600 |
|
---|
2601 | XXX
|
---|
2602 |
|
---|
2603 |
|
---|
2604 | ``setuptools.package_index``
|
---|
2605 | ----------------------------
|
---|
2606 |
|
---|
2607 | XXX
|
---|
2608 |
|
---|
2609 |
|
---|
2610 | ----------------------------
|
---|
2611 | Release Notes/Change History
|
---|
2612 | ----------------------------
|
---|
2613 |
|
---|
2614 | 0.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 |
|
---|
2652 | 0.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 |
|
---|
2660 | 0.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 |
|
---|
2681 | 0.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 |
|
---|
2688 | 0.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 |
|
---|
2715 | 0.6c3
|
---|
2716 | * Fixed breakages caused by Subversion 1.4's new "working copy" format
|
---|
2717 |
|
---|
2718 | 0.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 |
|
---|
2726 | 0.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 |
|
---|
2747 | 0.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 |
|
---|
2757 | 0.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 |
|
---|
2765 | 0.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 |
|
---|
2770 | 0.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 |
|
---|
2801 | 0.6a10
|
---|
2802 | * Fixed the ``develop`` command ignoring ``--find-links``.
|
---|
2803 |
|
---|
2804 | 0.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 |
|
---|
2853 | 0.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 |
|
---|
2878 | 0.6a5
|
---|
2879 | * Fixed missing gui/cli .exe files in distribution. Fixed bugs in tests.
|
---|
2880 |
|
---|
2881 | 0.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 |
|
---|
2886 | 0.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 |
|
---|
2892 | 0.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 |
|
---|
2934 | 0.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 |
|
---|
2939 | 0.5a11
|
---|
2940 | * Fix breakage of the "develop" command that was caused by the addition of
|
---|
2941 | ``--always-unzip`` to the ``easy_install`` command.
|
---|
2942 |
|
---|
2943 | 0.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 |
|
---|
2975 | 0.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 |
|
---|
3000 | 0.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 |
|
---|
3005 | 0.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 |
|
---|
3021 | 0.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 |
|
---|
3046 | 0.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 |
|
---|
3059 | 0.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 |
|
---|
3071 | 0.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 |
|
---|
3096 | 0.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 |
|
---|
3103 | 0.3a1
|
---|
3104 | * Initial release.
|
---|
3105 |
|
---|
3106 |
|
---|
3107 | Mailing List and Bug Tracker
|
---|
3108 | ============================
|
---|
3109 |
|
---|
3110 | Please use the `distutils-sig mailing list`_ for questions and discussion about
|
---|
3111 | setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
|
---|
3112 | confirmed via the list are actual bugs, and which you have reduced to a minimal
|
---|
3113 | set 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 |
|
---|