hooke/__init__.py

   1 # Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
   2 #
   3 # This file is part of Hooke.
   4 #
   5 # Hooke is free software: you can redistribute it and/or
   6 # modify it under the terms of the GNU Lesser General Public
   7 # License as published by the Free Software Foundation, either
   8 # version 3 of the License, or (at your option) any later version.
   9 #
  10 # Hooke is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU Lesser General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with Hooke.  If not, see
  17 # <http://www.gnu.org/licenses/>.
  18
  19 """The hooke module does all the legwork for Hooke_.
  20
  21 .. _hooke: http://code.google.com/p/hooke/
  22
  23 To facilitate faster loading, submodules are not imported by default.
  24 The available submodules are:
  25
  26 * :mod:`hooke.config`
  27 * :mod:`hooke.compat`
  28 """
  29
  30 __version__ = (0, 9, 0, 'devel', None, 'Kenzo')
  31 """Version tuple::
  32
  33     (major, minor, release, type, patch, name)
  34
  35 Where
  36
  37   * type: Python uses alpha, beta, candidate, and final.  Whatever
  38     so long as the alphabetic sort gets them in the right order.
  39   * patch: either manually incremented for each release, the packaging
  40     date string, YYYYMMDD, date of last commit, whatever.
  41
  42 See `Greg Noel's post on scons-devel`_ for a good explaination of why this
  43 versioning scheme is a good idea.
  44
  45 .. _Greg Noel's post on scons-devel
  46   http://thread.gmane.org/gmane.comp.programming.tools.scons.devel/8740
  47 """
  48
  49 def version(depth=-1, version_tuple=None):
  50     """Return a nicely formatted version string.::
  51
  52         major.minor.release.type[.patch] (name)
  53
  54     Examples
  55     --------
  56
  57     Since I seem to be unable to override __version__ in a Doctest,
  58     we'll pass the version tuple in as an argument.  You can ignore
  59     `version_tuple`.
  60
  61     >>> v = (1, 2, 3, 'devel', '20100501', 'Kenzo')
  62
  63     If depth -1, a full version string is returned
  64
  65     >>> version(depth=-1, version_tuple=v)
  66     '1.2.3.devel.20100501 (Kenzo)'
  67
  68     Otherwise, only the first depth fields are used.
  69
  70     >>> version(depth=3, version_tuple=v)
  71     '1.2.3'
  72     >>> version(depth=4, version_tuple=v)
  73     '1.2.3.devel'
  74
  75     Here's an example dropping the patch.
  76
  77     >>> v = (1, 2, 3, 'devel', None, 'Kenzo')
  78     >>> version(depth=-1, version_tuple=v)
  79     '1.2.3.devel (Kenzo)'
  80     """
  81     if version_tuple == None:
  82         version_tuple = __version__
  83     patch_index = 4
  84     if version_tuple[patch_index] == None: # No patch field, drop that entry
  85         version_tuple = version_tuple[0:patch_index] \
  86             + version_tuple[patch_index+1:]
  87         if depth >= patch_index:
  88             depth -= 1
  89     fields = version_tuple[0:depth]
  90     string = '.'.join([str(x) for x in fields])
  91     if depth == -1 or depth == len(version_tuple):
  92         string += ' (%s)' % version_tuple[-1]
  93     return string