hooke/__init__.py

   1 # Copyright
   2
   3 """The hooke module does all the legwork for Hooke_.
   4
   5 .. _hooke: http://code.google.com/p/hooke/
   6
   7 To facilitate faster loading, submodules are not imported by default.
   8 The available submodules are:
   9
  10 * :mod:`hooke.config`
  11 * :mod:`hooke.compat`
  12 """
  13
  14 __version__ = (0, 9, 0, 'devel', None, 'Kenzo')
  15 """Version tuple::
  16
  17     (major, minor, release, type, patch, name)
  18
  19 Where
  20
  21   * type: Python uses alpha, beta, candidate, and final.  Whatever
  22     so long as the alphabetic sort gets them in the right order.
  23   * patch: either manually incremented for each release, the packaging
  24     date string, YYYYMMDD, date of last commit, whatever.
  25
  26 See `Greg Noel's post on scons-devel`_ for a good explaination of why this
  27 versioning scheme is a good idea.
  28
  29 .. _Greg Noel's post on scons-devel
  30   http://thread.gmane.org/gmane.comp.programming.tools.scons.devel/8740
  31 """
  32
  33 def version(depth=-1, version_tuple=None):
  34     """Return a nicely formatted version string.::
  35
  36         major.minor.release.type[.patch] (name)
  37
  38     Examples
  39     --------
  40
  41     Since I seem to be unable to override __version__ in a Doctest,
  42     we'll pass the version tuple in as an argument.  You can ignore
  43     `version_tuple`.
  44
  45     >>> v = (1, 2, 3, 'devel', '20100501', 'Kenzo')
  46
  47     If depth -1, a full version string is returned
  48
  49     >>> version(depth=-1, version_tuple=v)
  50     '1.2.3.devel.20100501 (Kenzo)'
  51
  52     Otherwise, only the first depth fields are used.
  53
  54     >>> version(depth=3, version_tuple=v)
  55     '1.2.3'
  56     >>> version(depth=4, version_tuple=v)
  57     '1.2.3.devel'
  58
  59     Here's an example dropping the patch.
  60
  61     >>> v = (1, 2, 3, 'devel', None, 'Kenzo')
  62     >>> version(depth=-1, version_tuple=v)
  63     '1.2.3.devel (Kenzo)'
  64     """
  65     if version_tuple == None:
  66         version_tuple = __version__
  67     patch_index = 4
  68     if version_tuple[patch_index] == None: # No patch field, drop that entry
  69         version_tuple = version_tuple[0:patch_index] \
  70             + version_tuple[patch_index+1:]
  71         if depth >= patch_index:
  72             depth -= 1
  73     fields = version_tuple[0:depth]
  74     string = '.'.join([str(x) for x in fields])
  75     if depth == -1 or depth == len(version_tuple):
  76         string += ' (%s)' % version_tuple[-1]
  77     return string