ryu/.eggs/pbr-5.3.1-py2.7.egg/pbr/tests/testpackage/README.txt

   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