| 1 |
Introduction |
| 2 |
============ |
| 3 |
This package contains utilities used to package some of STScI's Python |
| 4 |
projects; specifically those projects that comprise stsci_python_ and |
| 5 |
Astrolib_. |
| 6 |
|
| 7 |
It currently consists mostly of some setup_hook scripts meant for use with |
| 8 |
`distutils2/packaging`_ and/or pbr_, and a customized easy_install command |
| 9 |
meant for use with distribute_. |
| 10 |
|
| 11 |
This package is not meant for general consumption, though it might be worth |
| 12 |
looking at for examples of how to do certain things with your own packages, but |
| 13 |
YMMV. |
| 14 |
|
| 15 |
Features |
| 16 |
======== |
| 17 |
|
| 18 |
Hook Scripts |
| 19 |
------------ |
| 20 |
Currently the main features of this package are a couple of setup_hook scripts. |
| 21 |
In distutils2, a setup_hook is a script that runs at the beginning of any |
| 22 |
pysetup command, and can modify the package configuration read from setup.cfg. |
| 23 |
There are also pre- and post-command hooks that only run before/after a |
| 24 |
specific setup command (eg. build_ext, install) is run. |
| 25 |
|
| 26 |
stsci.distutils.hooks.use_packages_root |
| 27 |
''''''''''''''''''''''''''''''''''''''' |
| 28 |
If using the ``packages_root`` option under the ``[files]`` section of |
| 29 |
setup.cfg, this hook will add that path to ``sys.path`` so that modules in your |
| 30 |
package can be imported and used in setup. This can be used even if |
| 31 |
``packages_root`` is not specified--in this case it adds ``''`` to |
| 32 |
``sys.path``. |
| 33 |
|
| 34 |
stsci.distutils.hooks.version_setup_hook |
| 35 |
'''''''''''''''''''''''''''''''''''''''' |
| 36 |
Creates a Python module called version.py which currently contains four |
| 37 |
variables: |
| 38 |
|
| 39 |
* ``__version__`` (the release version) |
| 40 |
* ``__svn_revision__`` (the SVN revision info as returned by the ``svnversion`` |
| 41 |
command) |
| 42 |
* ``__svn_full_info__`` (as returned by the ``svn info`` command) |
| 43 |
* ``__setup_datetime__`` (the date and time that setup.py was last run). |
| 44 |
|
| 45 |
These variables can be imported in the package's `__init__.py` for degugging |
| 46 |
purposes. The version.py module will *only* be created in a package that |
| 47 |
imports from the version module in its `__init__.py`. It should be noted that |
| 48 |
this is generally preferable to writing these variables directly into |
| 49 |
`__init__.py`, since this provides more control and is less likely to |
| 50 |
unexpectedly break things in `__init__.py`. |
| 51 |
|
| 52 |
stsci.distutils.hooks.version_pre_command_hook |
| 53 |
'''''''''''''''''''''''''''''''''''''''''''''' |
| 54 |
Identical to version_setup_hook, but designed to be used as a pre-command |
| 55 |
hook. |
| 56 |
|
| 57 |
stsci.distutils.hooks.version_post_command_hook |
| 58 |
''''''''''''''''''''''''''''''''''''''''''''''' |
| 59 |
The complement to version_pre_command_hook. This will delete any version.py |
| 60 |
files created during a build in order to prevent them from cluttering an SVN |
| 61 |
working copy (note, however, that version.py is *not* deleted from the build/ |
| 62 |
directory, so a copy of it is still preserved). It will also not be deleted |
| 63 |
if the current directory is not an SVN working copy. For example, if source |
| 64 |
code extracted from a source tarball it will be preserved. |
| 65 |
|
| 66 |
stsci.distutils.hooks.tag_svn_revision |
| 67 |
'''''''''''''''''''''''''''''''''''''' |
| 68 |
A setup_hook to add the SVN revision of the current working copy path to the |
| 69 |
package version string, but only if the version ends in .dev. |
| 70 |
|
| 71 |
For example, ``mypackage-1.0.dev`` becomes ``mypackage-1.0.dev1234``. This is |
| 72 |
in accordance with the version string format standardized by PEP 386. |
| 73 |
|
| 74 |
This should be used as a replacement for the ``tag_svn_revision`` option to |
| 75 |
the egg_info command. This hook is more compatible with packaging/distutils2, |
| 76 |
which does not include any VCS support. This hook is also more flexible in |
| 77 |
that it turns the revision number on/off depending on the presence of ``.dev`` |
| 78 |
in the version string, so that it's not automatically added to the version in |
| 79 |
final releases. |
| 80 |
|
| 81 |
This hook does require the ``svnversion`` command to be available in order to |
| 82 |
work. It does not examine the working copy metadata directly. |
| 83 |
|
| 84 |
stsci.distutils.hooks.numpy_extension_hook |
| 85 |
'''''''''''''''''''''''''''''''''''''''''' |
| 86 |
This is a pre-command hook for the build_ext command. To use it, add a |
| 87 |
``[build_ext]`` section to your setup.cfg, and add to it:: |
| 88 |
|
| 89 |
pre-hook.numpy-extension-hook = stsci.distutils.hooks.numpy_extension_hook |
| 90 |
|
| 91 |
This hook must be used to build extension modules that use Numpy. The primary |
| 92 |
side-effect of this hook is to add the correct numpy include directories to |
| 93 |
`include_dirs`. To use it, add 'numpy' to the 'include-dirs' option of each |
| 94 |
extension module that requires numpy to build. The value 'numpy' will be |
| 95 |
replaced with the actual path to the numpy includes. |
| 96 |
|
| 97 |
stsci.distutils.hooks.is_display_option |
| 98 |
''''''''''''''''''''''''''''''''''''''' |
| 99 |
This is not actually a hook, but is a useful utility function that can be used |
| 100 |
in writing other hooks. Basically, it returns ``True`` if setup.py was run |
| 101 |
with a "display option" such as --version or --help. This can be used to |
| 102 |
prevent your hook from running in such cases. |
| 103 |
|
| 104 |
stsci.distutils.hooks.glob_data_files |
| 105 |
''''''''''''''''''''''''''''''''''''' |
| 106 |
A pre-command hook for the install_data command. Allows filename wildcards as |
| 107 |
understood by ``glob.glob()`` to be used in the data_files option. This hook |
| 108 |
must be used in order to have this functionality since it does not normally |
| 109 |
exist in distutils. |
| 110 |
|
| 111 |
This hook also ensures that data files are installed relative to the package |
| 112 |
path. data_files shouldn't normally be installed this way, but the |
| 113 |
functionality is required for a few special cases. |
| 114 |
|
| 115 |
|
| 116 |
Commands |
| 117 |
-------- |
| 118 |
build_optional_ext |
| 119 |
'''''''''''''''''' |
| 120 |
This serves as an optional replacement for the default built_ext command, |
| 121 |
which compiles C extension modules. Its purpose is to allow extension modules |
| 122 |
to be *optional*, so that if their build fails the rest of the package is |
| 123 |
still allowed to be built and installed. This can be used when an extension |
| 124 |
module is not definitely required to use the package. |
| 125 |
|
| 126 |
To use this custom command, add:: |
| 127 |
|
| 128 |
commands = stsci.distutils.command.build_optional_ext.build_optional_ext |
| 129 |
|
| 130 |
under the ``[global]`` section of your package's setup.cfg. Then, to mark |
| 131 |
an individual extension module as optional, under the setup.cfg section for |
| 132 |
that extension add:: |
| 133 |
|
| 134 |
optional = True |
| 135 |
|
| 136 |
Optionally, you may also add a custom failure message by adding:: |
| 137 |
|
| 138 |
fail_message = The foobar extension module failed to compile. |
| 139 |
This could be because you lack such and such headers. |
| 140 |
This package will still work, but such and such features |
| 141 |
will be disabled. |
| 142 |
|
| 143 |
|
| 144 |
.. _stsci_python: http://www.stsci.edu/resources/software_hardware/pyraf/stsci_python |
| 145 |
.. _Astrolib: http://www.scipy.org/AstroLib/ |
| 146 |
.. _distutils2/packaging: http://distutils2.notmyidea.org/ |
| 147 |
.. _d2to1: http://pypi.python.org/pypi/d2to1 |
| 148 |
.. _distribute: http://pypi.python.org/pypi/distribute |