1Metadata-Version: 1.1 2Name: stsci.distutils 3Version: 0.3.7 4Summary: distutils/packaging-related utilities used by some of STScI's packages 5Home-page: http://www.stsci.edu/resources/software_hardware/stsci_python 6Author: Erik M. Bray 7Author-email: embray@stsci.edu 8License: UNKNOWN 9Description: Introduction 10 ============ 11 This package contains utilities used to package some of STScI's Python 12 projects; specifically those projects that comprise stsci_python_ and 13 Astrolib_. 14 15 It currently consists mostly of some setup_hook scripts meant for use with 16 `distutils2/packaging`_ and/or d2to1_, and a customized easy_install command 17 meant for use with distribute_. 18 19 This package is not meant for general consumption, though it might be worth 20 looking at for examples of how to do certain things with your own packages, but 21 YMMV. 22 23 Features 24 ======== 25 26 Hook Scripts 27 ------------ 28 Currently the main features of this package are a couple of setup_hook scripts. 29 In distutils2, a setup_hook is a script that runs at the beginning of any 30 pysetup command, and can modify the package configuration read from setup.cfg. 31 There are also pre- and post-command hooks that only run before/after a 32 specific setup command (eg. build_ext, install) is run. 33 34 stsci.distutils.hooks.use_packages_root 35 ''''''''''''''''''''''''''''''''''''''' 36 If using the ``packages_root`` option under the ``[files]`` section of 37 setup.cfg, this hook will add that path to ``sys.path`` so that modules in your 38 package can be imported and used in setup. This can be used even if 39 ``packages_root`` is not specified--in this case it adds ``''`` to 40 ``sys.path``. 41 42 stsci.distutils.hooks.version_setup_hook 43 '''''''''''''''''''''''''''''''''''''''' 44 Creates a Python module called version.py which currently contains four 45 variables: 46 47 * ``__version__`` (the release version) 48 * ``__svn_revision__`` (the SVN revision info as returned by the ``svnversion`` 49 command) 50 * ``__svn_full_info__`` (as returned by the ``svn info`` command) 51 * ``__setup_datetime__`` (the date and time that setup.py was last run). 52 53 These variables can be imported in the package's ``__init__.py`` for degugging 54 purposes. The version.py module will *only* be created in a package that 55 imports from the version module in its ``__init__.py``. It should be noted 56 that this is generally preferable to writing these variables directly into 57 ``__init__.py``, since this provides more control and is less likely to 58 unexpectedly break things in ``__init__.py``. 59 60 stsci.distutils.hooks.version_pre_command_hook 61 '''''''''''''''''''''''''''''''''''''''''''''' 62 Identical to version_setup_hook, but designed to be used as a pre-command 63 hook. 64 65 stsci.distutils.hooks.version_post_command_hook 66 ''''''''''''''''''''''''''''''''''''''''''''''' 67 The complement to version_pre_command_hook. This will delete any version.py 68 files created during a build in order to prevent them from cluttering an SVN 69 working copy (note, however, that version.py is *not* deleted from the build/ 70 directory, so a copy of it is still preserved). It will also not be deleted 71 if the current directory is not an SVN working copy. For example, if source 72 code extracted from a source tarball it will be preserved. 73 74 stsci.distutils.hooks.tag_svn_revision 75 '''''''''''''''''''''''''''''''''''''' 76 A setup_hook to add the SVN revision of the current working copy path to the 77 package version string, but only if the version ends in .dev. 78 79 For example, ``mypackage-1.0.dev`` becomes ``mypackage-1.0.dev1234``. This is 80 in accordance with the version string format standardized by PEP 386. 81 82 This should be used as a replacement for the ``tag_svn_revision`` option to 83 the egg_info command. This hook is more compatible with packaging/distutils2, 84 which does not include any VCS support. This hook is also more flexible in 85 that it turns the revision number on/off depending on the presence of ``.dev`` 86 in the version string, so that it's not automatically added to the version in 87 final releases. 88 89 This hook does require the ``svnversion`` command to be available in order to 90 work. It does not examine the working copy metadata directly. 91 92 stsci.distutils.hooks.numpy_extension_hook 93 '''''''''''''''''''''''''''''''''''''''''' 94 This is a pre-command hook for the build_ext command. To use it, add a 95 ``[build_ext]`` section to your setup.cfg, and add to it:: 96 97 pre-hook.numpy-extension-hook = stsci.distutils.hooks.numpy_extension_hook 98 99 This hook must be used to build extension modules that use Numpy. The primary 100 side-effect of this hook is to add the correct numpy include directories to 101 `include_dirs`. To use it, add 'numpy' to the 'include-dirs' option of each 102 extension module that requires numpy to build. The value 'numpy' will be 103 replaced with the actual path to the numpy includes. 104 105 stsci.distutils.hooks.is_display_option 106 ''''''''''''''''''''''''''''''''''''''' 107 This is not actually a hook, but is a useful utility function that can be used 108 in writing other hooks. Basically, it returns ``True`` if setup.py was run 109 with a "display option" such as --version or --help. This can be used to 110 prevent your hook from running in such cases. 111 112 stsci.distutils.hooks.glob_data_files 113 ''''''''''''''''''''''''''''''''''''' 114 A pre-command hook for the install_data command. Allows filename wildcards as 115 understood by ``glob.glob()`` to be used in the data_files option. This hook 116 must be used in order to have this functionality since it does not normally 117 exist in distutils. 118 119 This hook also ensures that data files are installed relative to the package 120 path. data_files shouldn't normally be installed this way, but the 121 functionality is required for a few special cases. 122 123 124 Commands 125 -------- 126 build_optional_ext 127 '''''''''''''''''' 128 This serves as an optional replacement for the default built_ext command, 129 which compiles C extension modules. Its purpose is to allow extension modules 130 to be *optional*, so that if their build fails the rest of the package is 131 still allowed to be built and installed. This can be used when an extension 132 module is not definitely required to use the package. 133 134 To use this custom command, add:: 135 136 commands = stsci.distutils.command.build_optional_ext.build_optional_ext 137 138 under the ``[global]`` section of your package's setup.cfg. Then, to mark 139 an individual extension module as optional, under the setup.cfg section for 140 that extension add:: 141 142 optional = True 143 144 Optionally, you may also add a custom failure message by adding:: 145 146 fail_message = The foobar extension module failed to compile. 147 This could be because you lack such and such headers. 148 This package will still work, but such and such features 149 will be disabled. 150 151 152 .. _stsci_python: http://www.stsci.edu/resources/software_hardware/pyraf/stsci_python 153 .. _Astrolib: http://www.scipy.org/AstroLib/ 154 .. _distutils2/packaging: http://distutils2.notmyidea.org/ 155 .. _d2to1: http://pypi.python.org/pypi/d2to1 156 .. _distribute: http://pypi.python.org/pypi/distribute 157 158 Changelog 159 =========== 160 161 0.3.7 (2013-12-23) 162 ------------------ 163 164 - Avoid using ``Popen.stdout`` directly in the version.py SVN revision 165 auto-update script to avoid possible ResourceWarnings on Python >= 3.2. 166 See https://github.com/spacetelescope/PyFITS/issues/45 167 168 169 0.3.6 (2013-11-21) 170 ------------------ 171 172 - Fixed a syntax error in Python 3 that was introduced in 0.3.5. This 173 could occur very early in the setup such that it bailed before even 2to3 174 could run on the rest of the package. 175 176 177 0.3.5 (2013-11-18) 178 ------------------ 179 180 - Fixed an obscure issue that could occur when trying to install with 181 easy_install on Python 2 systems that have lib2to3 installed but have never 182 used it. 183 184 185 0.3.4 (2013-07-31) 186 ------------------ 187 188 - Updated the check for ``__loader__`` added in v0.3.3 to only perform 189 that check on Python >= 3.3, since the issue doesn't apply to older 190 Python versions. 191 192 193 0.3.3 (2013-07-25) 194 ------------------ 195 196 - Updated the import-time SVN revision update mechanism in the ``version.py`` 197 module generated by the ``version_setup_hook`` to avoid running when not in 198 a dev version of the package. This saves time on importing released 199 packages when installed on users' systems. 200 201 - Added a workaround to a bug on Python 3.3 that could cause stsci.distutils 202 to crash during installation. 203 204 205 0.3.2 (2013-03-27) 206 ------------------ 207 208 - Fixed a bug in the version hook that could occur if the svnversion command 209 fails. 210 211 - Updated the template for the version.py module generated by the version hook 212 so that ``from .version import *`` will work for applications. 213 214 - Added a ``__vdate__`` variable in version.py which may contain a release 215 date string by specifying a ``vdate`` option in the ``[metadata]`` section 216 of setup.cfg. 217 218 - Added a ``stsci_distutils_version`` variable in version.py containing the 219 version of stsci.distutils used to generate the file--useful primarily for 220 debugging purposes. 221 222 - Version 0.3.1 added a new zest.releaser hooks to ensure that source 223 distributes are created as tar.gz files instead of zip files--this was left 224 out of the changelog for 0.3.1. 225 226 - The tar.gz zest.releaser hook is updated in 0.3.2 to only run on stsci 227 packages. 228 229 230 0.3.1 (2012-06-28) 231 ------------------ 232 233 - Fixed a bug where console output from svn-related programs was assumed to be 234 ascii, leading to possible crashes on non-English systems. 235 236 237 0.3 (2012-02-20) 238 ---------------- 239 240 - The ``glob_data_files`` hook became a pre-command hook for the install_data 241 command instead of being a setup-hook. This is to support the additional 242 functionality of requiring data_files with relative destination paths to be 243 install relative to the package's install path (i.e. site-packages). 244 245 - Dropped support for and deprecated the easier_install custom command. 246 Although it should still work, it probably won't be used anymore for 247 stsci_python packages. 248 249 - Added support for the ``build_optional_ext`` command, which replaces/extends 250 the default ``build_ext`` command. See the README for more details. 251 252 - Added the ``tag_svn_revision`` setup_hook as a replacement for the 253 setuptools-specific tag_svn_revision option to the egg_info command. This 254 new hook is easier to use than the old tag_svn_revision option: It's 255 automatically enabled by the presence of ``.dev`` in the version string, and 256 disabled otherwise. 257 258 - The ``svn_info_pre_hook`` and ``svn_info_post_hook`` have been replaced with 259 ``version_pre_command_hook`` and ``version_post_command_hook`` respectively. 260 However, a new ``version_setup_hook``, which has the same purpose, has been 261 added. It is generally easier to use and will give more consistent results 262 in that it will run every time setup.py is run, regardless of which command 263 is used. ``stsci.distutils`` itself uses this hook--see the `setup.cfg` file 264 and `stsci/distutils/__init__.py` for example usage. 265 266 - Instead of creating an `svninfo.py` module, the new ``version_`` hooks create 267 a file called `version.py`. In addition to the SVN info that was included 268 in `svninfo.py`, it includes a ``__version__`` variable to be used by the 269 package's `__init__.py`. This allows there to be a hard-coded 270 ``__version__`` variable included in the source code, rather than using 271 pkg_resources to get the version. 272 273 - In `version.py`, the variables previously named ``__svn_version__`` and 274 ``__full_svn_info__`` are now named ``__svn_revision__`` and 275 ``__svn_full_info__``. 276 277 - Fixed a bug when using stsci.distutils in the installation of other packages 278 in the ``stsci.*`` namespace package. If stsci.distutils was not already 279 installed, and was downloaded automatically by distribute through the 280 setup_requires option, then ``stsci.distutils`` would fail to import. This 281 is because the way the namespace package (nspkg) mechanism currently works, 282 all packages belonging to the nspkg *must* be on the import path at initial 283 import time. 284 285 So when installing stsci.tools, for example, if ``stsci.tools`` is imported 286 from within the source code at install time, but before ``stsci.distutils`` 287 is downloaded and added to the path, the ``stsci`` package is already 288 imported and can't be extended to include the path of ``stsci.distutils`` 289 after the fact. The easiest way of dealing with this, it seems, is to 290 delete ``stsci`` from ``sys.modules``, which forces it to be reimported, now 291 the its ``__path__`` extended to include ``stsci.distutil``'s path. 292 293 - Added zest.releaser hooks for tweaking the development version string 294 template, and for uploading new releases to STScI's local package index. 295 296 297 0.2.2 (2011-11-09) 298 ------------------ 299 300 - Fixed check for the issue205 bug on actual setuptools installs; before it 301 only worked on distribute. setuptools has the issue205 bug prior to version 302 0.6c10. 303 304 - Improved the fix for the issue205 bug, especially on setuptools. 305 setuptools, prior to 0.6c10, did not back of sys.modules either before 306 sandboxing, which causes serious problems. In fact, it's so bad that it's 307 not enough to add a sys.modules backup to the current sandbox: It's in fact 308 necessary to monkeypatch setuptools.sandbox.run_setup so that any subsequent 309 calls to it also back up sys.modules. 310 311 312 0.2.1 (2011-09-02) 313 ------------------ 314 315 - Fixed the dependencies so that setuptools is requirement but 'distribute' 316 specifically. Previously installation could fail if users had plain 317 setuptools installed and not distribute 318 319 0.2 (2011-08-23) 320 ------------------ 321 322 - Initial public release 323 324 325Platform: UNKNOWN 326Classifier: Development Status :: 3 - Alpha 327Classifier: Intended Audience :: Developers 328Classifier: License :: OSI Approved :: BSD License 329Classifier: Programming Language :: Python 330Classifier: Topic :: Scientific/Engineering 331Classifier: Topic :: Software Development :: Build Tools 332Classifier: Topic :: Software Development :: Libraries :: Python Modules 333Classifier: Topic :: System :: Archiving :: Packaging 334