Run update-copyright.py.
[hooke.git] / hooke / __init__.py
1 # Copyright (C) 2010-2012 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 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 try:
29     from .license import LICENSE as __license__
30 except ImportError, e:
31     import logging
32     logging.warn('could not load LICENSE from hooke.license')
33     __license__ = 'All rights reserved.' 
34
35 from .util import yaml  # extend YAML to parse Hooke-specific items.
36
37 __version__ = (1, 0, 0, 'alpha', None, 'Ninken')
38 """Version tuple::
39
40     (major, minor, release, type, patch, name)
41
42 Where 
43
44   * type: Python uses alpha, beta, candidate, and final.  Whatever
45     so long as the alphabetic sort gets them in the right order.
46   * patch: either manually incremented for each release, the packaging
47     date string, YYYYMMDD, date of last commit, whatever.
48
49 See `Greg Noel's post on scons-devel`_ for a good explaination of why this
50 versioning scheme is a good idea.
51
52 .. _Greg Noel's post on scons-devel
53   http://thread.gmane.org/gmane.comp.programming.tools.scons.devel/8740
54 """
55
56 def version(depth=-1, version_tuple=None):
57     """Return a nicely formatted version string.::
58
59         major.minor.release.type[.patch] (name)
60
61     Examples
62     --------
63
64     Since I seem to be unable to override __version__ in a Doctest,
65     we'll pass the version tuple in as an argument.  You can ignore
66     `version_tuple`.
67
68     >>> v = (1, 2, 3, 'devel', '20100501', 'Kenzo')
69
70     If depth -1, a full version string is returned
71
72     >>> version(depth=-1, version_tuple=v)
73     '1.2.3.devel.20100501 (Kenzo)'
74
75     Otherwise, only the first depth fields are used.
76
77     >>> version(depth=3, version_tuple=v)
78     '1.2.3'
79     >>> version(depth=4, version_tuple=v)
80     '1.2.3.devel'
81
82     Here's an example dropping the patch.
83
84     >>> v = (1, 2, 3, 'devel', None, 'Kenzo')
85     >>> version(depth=-1, version_tuple=v)
86     '1.2.3.devel (Kenzo)'
87     """
88     if version_tuple == None:
89         version_tuple = __version__
90     patch_index = 4
91     if version_tuple[patch_index] == None: # No patch field, drop that entry
92         version_tuple = version_tuple[0:patch_index] \
93             + version_tuple[patch_index+1:]
94         if depth >= patch_index:
95             depth -= 1
96     fields = version_tuple[0:depth]
97     string = '.'.join([str(x) for x in fields])
98     if depth == -1 or depth == len(version_tuple):
99         string += ' (%s)' % version_tuple[-1]
100     return string