[oe-commits] Chris Larson : oe.types: add/update docstrings

[git version control]

Module: openembedded.git
Branch: shr/testing2011.1
Commit: f12ce2877e1f8dc436286f5258ccd5ac850c81bc
URL:    http://gitweb.openembedded.net/?p=openembedded.git&a=commit;h=f12ce2877e1f8dc436286f5258ccd5ac850c81bc

Author: Chris Larson <chris_larson at mentor.com>
Date:   Thu Jan 13 08:38:46 2011 -0700

oe.types: add/update docstrings

Signed-off-by: Chris Larson <chris_larson at mentor.com>

---

 lib/oe/_types.py |   28 ++++++++++++++++++++++++++++
 lib/oe/types.py  |   30 ++++++++++++++++++++----------
 2 files changed, 48 insertions(+), 10 deletions(-)

diff --git a/lib/oe/_types.py b/lib/oe/_types.py
index 91afb8a..b36060f 100644
--- a/lib/oe/_types.py
+++ b/lib/oe/_types.py
@@ -1,6 +1,13 @@
 import re
 
 class OEList(list):
+    """OpenEmbedded 'list' type
+
+    Acts as an ordinary list, but is constructed from a string value and a
+    separator (optional), and re-joins itself when converted to a string with
+    str().  Set the variable type flag to 'list' to use this type, and the
+    'separator' flag may be specified (defaulting to whitespace)."""
+
     name = "list"
 
     def __init__(self, value, separator = None):
@@ -18,6 +25,11 @@ class OEList(list):
         return self.separator.join(self)
 
 def choice(value, choices):
+    """OpenEmbedded 'choice' type
+
+    Acts as a multiple choice for the user.  To use this, set the variable
+    type flag to 'choice', and set the 'choices' flag to a space separated
+    list of valid values."""
     if not isinstance(value, basestring):
         raise TypeError("choice accepts a string, not '%s'" % type(value))
 
@@ -29,6 +41,15 @@ def choice(value, choices):
     return value
 
 def regex(value, regexflags=None):
+    """OpenEmbedded 'regex' type
+
+    Acts as a regular expression, returning the pre-compiled regular
+    expression pattern object.  To use this type, set the variable type flag
+    to 'regex', and optionally, set the 'regexflags' type to a space separated
+    list of the flags to control the regular expression matching (e.g.
+    FOO[regexflags] += 'ignorecase').  See the python documentation on the
+    're' module for a list of valid flags."""
+
     flagval = 0
     if regexflags:
         for flag in regexflags.split():
@@ -45,6 +66,12 @@ def regex(value, regexflags=None):
                          (value, exc.args[0]))
 
 def boolean(value):
+    """OpenEmbedded 'boolean' type
+
+    Valid values for true: 'yes', 'y', 'true', 't', '1'
+    Valid values for false: 'no', 'n', 'false', 'f', '0'
+    """
+
     if not isinstance(value, basestring):
         raise TypeError("boolean accepts a string, not '%s'" % type(value))
 
@@ -56,4 +83,5 @@ def boolean(value):
     raise ValueError("Invalid boolean value '%s'" % value)
 
 def integer(value):
+    """OpenEmbedded 'integer' type"""
     return int(value)
diff --git a/lib/oe/types.py b/lib/oe/types.py
index 963e964..0fb91db 100644
--- a/lib/oe/types.py
+++ b/lib/oe/types.py
@@ -1,9 +1,9 @@
-# Constructs objects of the specified type for a given variable in the
-# metadata.  The 'type' flag of the variable defines which of the factory
-# functions in this module will be called.
-#
-# If no type is defined, the value() function will simply return the expanded
-# string value as is.
+"""OpenEmbedded variable typing support
+
+Types are defined in the metadata by name, using the 'type' flag on a
+variable.  Other flags may be utilized in the construction of the types.  See
+the arguments of the type's factory for details.
+"""
 
 import bb
 import inspect
@@ -12,6 +12,8 @@ import _types
 types = {}
 
 class MissingFlag(TypeError):
+    """A particular flag is required to construct the type, but has not been
+    provided."""
     def __init__(self, flag, type):
         self.flag = flag
         self.type = type
@@ -21,12 +23,15 @@ class MissingFlag(TypeError):
         return "Type '%s' requires flag '%s'" % (self.type, self.flag)
 
 def factory(var_type):
+    """Return the factory for a specified type."""
     try:
         return types[var_type]
     except KeyError:
         raise TypeError("Invalid type '%s'" % var_type)
 
 def create(value, var_type, **flags):
+    """Create an object of the specified type, given the specified flags and
+    string value."""
     obj = factory(var_type)
     objflags = {}
     for flag in obj.flags:
@@ -39,8 +44,8 @@ def create(value, var_type, **flags):
     return obj(value, **objflags)
 
 def value(key, d):
-    """Construct a value for a metadata variable, based upon its flags"""
-
+    """Construct a value for the specified metadata variable, using its flags
+    to determine the type and parameters for construction."""
     var_type = d.getVarFlag(key, 'type')
     flags = d.getVarFlags(key)
 
@@ -69,7 +74,7 @@ def get_callable_args(obj):
     return flaglist, optional
 
 def factory_setup(name, obj):
-    """Prepare a factory for use by oe.types"""
+    """Prepare a factory for use."""
     args, optional = get_callable_args(obj)
     extra_args = args[1:]
     if extra_args:
@@ -82,10 +87,15 @@ def factory_setup(name, obj):
         obj.name = name
 
 def register(name, factory):
+    """Register a type, given its name and a factory callable.
+
+    Determines the required and optional flags from the factory's
+    arguments."""
     factory_setup(name, factory)
     types[factory.name] = factory
 
-# Set the 'flags' and 'optflags' attributes of all our types
+
+# Register all our included types
 for name in dir(_types):
     if name.startswith('_'):
         continue