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