distutils/packaging-related utilities used by some of STScI's packages

## Introduction

This package contains utilities used to package some of STScI’s Python projects; specifically those projects that comprise stsci_python and Astrolib.

It currently consists mostly of some setup_hook scripts meant for use with distutils2/packaging and/or d2to1, and a customized easy_install command meant for use with distribute.

This package is not meant for general consumption, though it might be worth looking at for examples of how to do certain things with your own packages, but YMMV.

## Features

### Hook Scripts

Currently the main features of this package are a couple of setup_hook scripts. In distutils2, a setup_hook is a script that runs at the beginning of any pysetup command, and can modify the package configuration read from setup.cfg. There are also pre- and post-command hooks that only run before/after a specific setup command (eg. build_ext, install) is run.

#### stsci.distutils.hooks.use_packages_root

If using the packages_root option under the [files] section of setup.cfg, this hook will add that path to sys.path so that modules in your package can be imported and used in setup. This can be used even if packages_root is not specified–in this case it adds '' to sys.path.

#### stsci.distutils.hooks.version_setup_hook

Creates a Python module called version.py which currently contains four variables:

• __version__ (the release version)

• __svn_revision__ (the SVN revision info as returned by the svnversion command)

• __svn_full_info__ (as returned by the svn info command)

• __setup_datetime__ (the date and time that setup.py was last run).

These variables can be imported in the package’s __init__.py for degugging purposes. The version.py module will only be created in a package that imports from the version module in its __init__.py. It should be noted that this is generally preferable to writing these variables directly into __init__.py, since this provides more control and is less likely to unexpectedly break things in __init__.py.

#### stsci.distutils.hooks.version_pre_command_hook

Identical to version_setup_hook, but designed to be used as a pre-command hook.

#### stsci.distutils.hooks.version_post_command_hook

The complement to version_pre_command_hook. This will delete any version.py files created during a build in order to prevent them from cluttering an SVN working copy (note, however, that version.py is not deleted from the build/ directory, so a copy of it is still preserved). It will also not be deleted if the current directory is not an SVN working copy. For example, if source code extracted from a source tarball it will be preserved.

#### stsci.distutils.hooks.tag_svn_revision

A setup_hook to add the SVN revision of the current working copy path to the package version string, but only if the version ends in .dev.

For example, mypackage-1.0.dev becomes mypackage-1.0.dev1234. This is in accordance with the version string format standardized by PEP 386.

This should be used as a replacement for the tag_svn_revision option to the egg_info command. This hook is more compatible with packaging/distutils2, which does not include any VCS support. This hook is also more flexible in that it turns the revision number on/off depending on the presence of .dev in the version string, so that it’s not automatically added to the version in final releases.

This hook does require the svnversion command to be available in order to work. It does not examine the working copy metadata directly.

#### stsci.distutils.hooks.numpy_extension_hook

This is a pre-command hook for the build_ext command. To use it, add a [build_ext] section to your setup.cfg, and add to it:

pre-hook.numpy-extension-hook = stsci.distutils.hooks.numpy_extension_hook

This hook must be used to build extension modules that use Numpy. The primary side-effect of this hook is to add the correct numpy include directories to include_dirs. To use it, add ‘numpy’ to the ‘include-dirs’ option of each extension module that requires numpy to build. The value ‘numpy’ will be replaced with the actual path to the numpy includes.

#### stsci.distutils.hooks.is_display_option

This is not actually a hook, but is a useful utility function that can be used in writing other hooks. Basically, it returns True if setup.py was run with a “display option” such as –version or –help. This can be used to prevent your hook from running in such cases.

#### stsci.distutils.hooks.glob_data_files

A pre-command hook for the install_data command. Allows filename wildcards as understood by glob.glob() to be used in the data_files option. This hook must be used in order to have this functionality since it does not normally exist in distutils.

This hook also ensures that data files are installed relative to the package path. data_files shouldn’t normally be installed this way, but the functionality is required for a few special cases.

### Commands

build_optional_ext

This serves as an optional replacement for the default built_ext command, which compiles C extension modules. Its purpose is to allow extension modules to be optional, so that if their build fails the rest of the package is still allowed to be built and installed. This can be used when an extension module is not definitely required to use the package.

To use this custom command, add:

commands = stsci.distutils.command.build_optional_ext.build_optional_ext

under the [global] section of your package’s setup.cfg. Then, to mark an individual extension module as optional, under the setup.cfg section for that extension add:

optional = True

Optionally, you may also add a custom failure message by adding:

fail_message = The foobar extension module failed to compile.
This could be because you lack such and such headers.
This package will still work, but such and such features
will be disabled.

## Changelog

### 0.3.6 (2013-11-21)

• Fixed a syntax error in Python 3 that was introduced in 0.3.5. This could occur very early in the setup such that it bailed before even 2to3 could run on the rest of the package.

### 0.3.5 (2013-11-18)

• Fixed an obscure issue that could occur when trying to install with easy_install on Python 2 systems that have lib2to3 installed but have never used it.

### 0.3.4 (2013-07-31)

• Updated the check for __loader__ added in v0.3.3 to only perform that check on Python >= 3.3, since the issue doesn’t apply to older Python versions.

### 0.3.3 (2013-07-25)

• Updated the import-time SVN revision update mechanism in the version.py module generated by the version_setup_hook to avoid running when not in a dev version of the package. This saves time on importing released packages when installed on users’ systems.

• Added a workaround to a bug on Python 3.3 that could cause stsci.distutils to crash during installation.

### 0.3.2 (2013-03-27)

• Fixed a bug in the version hook that could occur if the svnversion command fails.

• Updated the template for the version.py module generated by the version hook so that from .version import * will work for applications.

• Added a __vdate__ variable in version.py which may contain a release date string by specifying a vdate option in the [metadata] section of setup.cfg.

• Added a stsci_distutils_version variable in version.py containing the version of stsci.distutils used to generate the file–useful primarily for debugging purposes.

• Version 0.3.1 added a new zest.releaser hooks to ensure that source distributes are created as tar.gz files instead of zip files–this was left out of the changelog for 0.3.1.

• The tar.gz zest.releaser hook is updated in 0.3.2 to only run on stsci packages.

### 0.3.1 (2012-06-28)

• Fixed a bug where console output from svn-related programs was assumed to be ascii, leading to possible crashes on non-English systems.

### 0.3 (2012-02-20)

• The glob_data_files hook became a pre-command hook for the install_data command instead of being a setup-hook. This is to support the additional functionality of requiring data_files with relative destination paths to be install relative to the package’s install path (i.e. site-packages).

• Dropped support for and deprecated the easier_install custom command. Although it should still work, it probably won’t be used anymore for stsci_python packages.

• Added support for the build_optional_ext command, which replaces/extends the default build_ext command. See the README for more details.

• Added the tag_svn_revision setup_hook as a replacement for the setuptools-specific tag_svn_revision option to the egg_info command. This new hook is easier to use than the old tag_svn_revision option: It’s automatically enabled by the presence of .dev in the version string, and disabled otherwise.

• The svn_info_pre_hook and svn_info_post_hook have been replaced with version_pre_command_hook and version_post_command_hook respectively. However, a new version_setup_hook, which has the same purpose, has been added. It is generally easier to use and will give more consistent results in that it will run every time setup.py is run, regardless of which command is used. stsci.distutils itself uses this hook–see the setup.cfg file and stsci/distutils/__init__.py for example usage.

• Instead of creating an svninfo.py module, the new version_ hooks create a file called version.py. In addition to the SVN info that was included in svninfo.py, it includes a __version__ variable to be used by the package’s __init__.py. This allows there to be a hard-coded __version__ variable included in the source code, rather than using pkg_resources to get the version.

• In version.py, the variables previously named __svn_version__ and __full_svn_info__ are now named __svn_revision__ and __svn_full_info__.

• Fixed a bug when using stsci.distutils in the installation of other packages in the stsci.* namespace package. If stsci.distutils was not already installed, and was downloaded automatically by distribute through the setup_requires option, then stsci.distutils would fail to import. This is because the way the namespace package (nspkg) mechanism currently works, all packages belonging to the nspkg must be on the import path at initial import time.

So when installing stsci.tools, for example, if stsci.tools is imported from within the source code at install time, but before stsci.distutils is downloaded and added to the path, the stsci package is already imported and can’t be extended to include the path of stsci.distutils after the fact. The easiest way of dealing with this, it seems, is to delete stsci from sys.modules, which forces it to be reimported, now the its __path__ extended to include stsci.distutil’s path.

• Added zest.releaser hooks for tweaking the development version string template, and for uploading new releases to STScI’s local package index.

### 0.2.2 (2011-11-09)

• Fixed check for the issue205 bug on actual setuptools installs; before it only worked on distribute. setuptools has the issue205 bug prior to version 0.6c10.

• Improved the fix for the issue205 bug, especially on setuptools. setuptools, prior to 0.6c10, did not back of sys.modules either before sandboxing, which causes serious problems. In fact, it’s so bad that it’s not enough to add a sys.modules backup to the current sandbox: It’s in fact necessary to monkeypatch setuptools.sandbox.run_setup so that any subsequent calls to it also back up sys.modules.

### 0.2.1 (2011-09-02)

• Fixed the dependencies so that setuptools is requirement but ‘distribute’ specifically. Previously installation could fail if users had plain setuptools installed and not distribute

### 0.2 (2011-08-23)

• Initial public release

## Release history Release notifications | RSS feed

Uploaded source