hooke/__init__.py

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