add docstrings

tiramisu/autolib.py

@@ -31,6 +31,7 @@ from tiramisu.i18n import _
 
 
 def carry_out_calculation(name, config, callback, callback_params):
+    "a function that carries out a calculation for an option's value"
     #callback, callback_params = option.getcallback()
     #if callback_params is None:
     #    callback_params = {}
@@ -110,12 +111,11 @@ def carry_out_calculation(name, config, callback, callback_params):
 
 
 def calculate(name, callback, params, tcparams):
-    """wrapper that launches the callback, that is a function
+    """wrapper that launches the 'callback'
-    that carries out a calculation for an option's value
 
     :param callback: callback name
     :param params: in the callback's arity, the unnamed parameters
     :param tcparams: in the callback's arity, the named parameters
-    
+
     """
     return callback(*params, **tcparams)

tiramisu/config.py

@@ -352,7 +352,9 @@ class SubConfig(BaseInformation):
     def make_dict(self, flatten=False, _currpath=None, withoption=None,
                   withvalue=None):
         """export the whole config into a `dict`
-        :returns: dict of Option's name (or path) and values"""
+        
+        :returns: dict of Option's name (or path) and values
+        """
         pathsvalues = []
         if _currpath is None:
             _currpath = []

tiramisu/error.py

@@ -19,7 +19,7 @@
 # the rough pypy's guys: http://codespeak.net/svn/pypy/dist/pypy/config/
 # the whole pypy projet is under MIT licence
 # ____________________________________________________________
-
+"user defined exceptions"
 # Exceptions for an Option
 class PropertiesOptionError(AttributeError):
     "attempt to access to an option with a property that is not allowed"

tiramisu/i18n.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 # -*- coding: UTF-8 -*-
-
+"internationalisation utilities"
 import gettext
 import os
 import sys

tiramisu/option.py

@@ -37,6 +37,7 @@ forbidden_names = ('iter_all', 'iter_group', 'find', 'find_first',
 
 
 def valid_name(name):
+    "an option's name is a str and does not start with 'impl' or 'cfgimpl'"
     try:
         name = str(name)
     except:
@@ -53,6 +54,7 @@ def valid_name(name):
 
 
 class BaseInformation(object):
+    "interface for an option's information attribute"
     __slots__ = ('_impl_informations',)
 
     def impl_set_information(self, key, value):
@@ -349,7 +351,7 @@ class Option(BaseInformation):
 
 
 class ChoiceOption(Option):
-    """Represents a choice out of several objects.
+    """represents a choice out of several objects.
 
     The option can also have the value ``None``
     """
@@ -395,7 +397,7 @@ class ChoiceOption(Option):
 
 
 class BoolOption(Option):
-    "Represents a choice between ``True`` and ``False``"
+    "represents a choice between ``True`` and ``False``"
     __slots__ = ('_opt_type',)
     _opt_type = 'bool'
 
@@ -404,7 +406,7 @@ class BoolOption(Option):
 
 
 class IntOption(Option):
-    "Represents a choice of an integer"
+    "represents a choice of an integer"
     __slots__ = ('_opt_type',)
     _opt_type = 'int'
 
@@ -413,7 +415,7 @@ class IntOption(Option):
 
 
 class FloatOption(Option):
-    "Represents a choice of a floating point number"
+    "represents a choice of a floating point number"
     __slots__ = ('_opt_type',)
     _opt_type = 'float'
 
@@ -422,7 +424,7 @@ class FloatOption(Option):
 
 
 class StrOption(Option):
-    "Represents the choice of a string"
+    "represents the choice of a string"
     __slots__ = ('_opt_type',)
     _opt_type = 'string'
 
@@ -431,7 +433,7 @@ class StrOption(Option):
 
 
 class UnicodeOption(Option):
-    "Represents the choice of a unicode string"
+    "represents the choice of a unicode string"
     __slots__ = ('_opt_type',)
     _opt_type = 'unicode'
     _empty = u''
@@ -460,7 +462,7 @@ class SymLinkOption(object):
 
 
 class IPOption(Option):
-    "Represents the choice of an ip"
+    "represents the choice of an ip"
     __slots__ = ('_opt_type', '_only_private')
     _opt_type = 'ip'
 
@@ -490,7 +492,7 @@ class IPOption(Option):
 
 
 class NetworkOption(Option):
-    "Represents the choice of a network"
+    "represents the choice of a network"
     __slots__ = ('_opt_type',)
     _opt_type = 'network'
 
@@ -503,7 +505,7 @@ class NetworkOption(Option):
 
 
 class NetmaskOption(Option):
-    "Represents the choice of a netmask"
+    "represents the choice of a netmask"
     __slots__ = ('_opt_type',)
     _opt_type = 'netmask'
 
@@ -553,6 +555,7 @@ class NetmaskOption(Option):
 
 
 class DomainnameOption(Option):
+    "represents the choice of a domain name"
     __slots__ = ('_opt_type', '_type', '_allow_ip')
     _opt_type = 'domainname'
 

tiramisu/setting.py

@@ -121,6 +121,7 @@ populate_owners()
 
 
 class MultiTypeModule(_const):
+    "namespace for the master/slaves"
     class MultiType(str):
         pass
 
@@ -137,6 +138,7 @@ multitypes = MultiTypeModule()
 
 
 def populate_multitypes():
+    "populates the master/slave namespace"
     setattr(multitypes, 'default', multitypes.DefaultMultiType('default'))
     setattr(multitypes, 'master', multitypes.MasterMultiType('master'))
     setattr(multitypes, 'slave', multitypes.SlaveMultiType('slave'))

tiramisu/value.py

@@ -25,6 +25,10 @@ from tiramisu.i18n import _
 
 
 class Values(object):
+    """`Config`'s root indeed is in charge of the `Option()`'s values,
+    and the values are physicaly located here. `Values` is also
+    responsible for a caching utility.
+    """
     __slots__ = ('context', '_values', '_cache')
 
     def __init__(self, context):
@@ -32,8 +36,9 @@ class Values(object):
         Initializes the values's dict.
 
         :param context: the context is the home config's values
+
         """
-        "Config's root indeed is in charge of the `Option()`'s values"
+
         self.context = context
         self._values = {}
         self._cache = {}