Merge lp:~mew/charm-helpers/document-core into lp:charm-helpers

[Matthew Wedgwood]

Add or clean up docstrings for all core functions.

[Nicola Larosa (teknico)]

Very much appreciated, thank you.

However, please be consistent in your choice of docstring delimiters. The convention is to always use triple double-quotes (""").

There's actually a whole guideline for docstrings alone <http://www.python.org/dev/peps/pep-0257/>.

Inconsistency in this has no use that I know of.

[lp:~mew/charm-helpers/document-core]

80. By Matthew Wedgwood on 2013-09-26

Standardize docstring quoting in core

[Matthew Wedgwood (mew)]

I've fixed the docstring quoting in the core modules.

[James Page (james-page)]

review: Approve

=== modified file 'charmhelpers/core/hookenv.py'
--- charmhelpers/core/hookenv.py	2013-07-18 16:13:49 +0000
+++ charmhelpers/core/hookenv.py	2013-09-26 14:36:53 +0000
@@ -21,7 +21,7 @@
 
 
 def cached(func):
-    ''' Cache return values for multiple executions of func + args
+    """Cache return values for multiple executions of func + args
 
     For example:
 
@@ -32,7 +32,7 @@
         unit_get('test')
 
     will cache the result of unit_get + 'test' for future calls.
-    '''
+    """
     def wrapper(*args, **kwargs):
         global cache
         key = str((func, args, kwargs))
@@ -46,8 +46,8 @@
 
 
 def flush(key):
-    ''' Flushes any entries from function cache where the
-    key is found in the function+args '''
+    """Flushes any entries from function cache where the
+    key is found in the function+args """
     flush_list = []
     for item in cache:
         if key in item:
@@ -57,7 +57,7 @@
 
 
 def log(message, level=None):
-    "Write a message to the juju log"
+    """Write a message to the juju log"""
     command = ['juju-log']
     if level:
         command += ['-l', level]
@@ -66,7 +66,7 @@
 
 
 class Serializable(UserDict.IterableUserDict):
-    "Wrapper, an object that can be serialized to yaml or json"
+    """Wrapper, an object that can be serialized to yaml or json"""
 
     def __init__(self, obj):
         # wrap the object
@@ -96,11 +96,11 @@
         self.data = state
 
     def json(self):
-        "Serialize the object to json"
+        """Serialize the object to json"""
         return json.dumps(self.data)
 
     def yaml(self):
-        "Serialize the object to yaml"
+        """Serialize the object to yaml"""
         return yaml.dump(self.data)
 
 
@@ -119,38 +119,38 @@
 
 
 def in_relation_hook():
-    "Determine whether we're running in a relation hook"
+    """Determine whether we're running in a relation hook"""
     return 'JUJU_RELATION' in os.environ
 
 
 def relation_type():
-    "The scope for the current relation hook"
+    """The scope for the current relation hook"""
     return os.environ.get('JUJU_RELATION', None)
 
 
 def relation_id():
-    "The relation ID for the current relation hook"
+    """The relation ID for the current relation hook"""
     return os.environ.get('JUJU_RELATION_ID', None)
 
 
 def local_unit():
-    "Local unit ID"
+    """Local unit ID"""
     return os.environ['JUJU_UNIT_NAME']
 
 
 def remote_unit():
-    "The remote unit for the current relation hook"
+    """The remote unit for the current relation hook"""
     return os.environ['JUJU_REMOTE_UNIT']
 
 
 def service_name():
-    "The name service group this unit belongs to"
+    """The name service group this unit belongs to"""
     return local_unit().split('/')[0]
 
 
 @cached
 def config(scope=None):
-    "Juju charm configuration"
+    """Juju charm configuration"""
     config_cmd_line = ['config-get']
     if scope is not None:
         config_cmd_line.append(scope)
@@ -163,6 +163,7 @@
 
 @cached
 def relation_get(attribute=None, unit=None, rid=None):
+    """Get relation information"""
     _args = ['relation-get', '--format=json']
     if rid:
         _args.append('-r')
@@ -177,6 +178,7 @@
 
 
 def relation_set(relation_id=None, relation_settings={}, **kwargs):
+    """Set relation information for the current unit"""
     relation_cmd_line = ['relation-set']
     if relation_id is not None:
         relation_cmd_line.extend(('-r', relation_id))
@@ -192,7 +194,7 @@
 
 @cached
 def relation_ids(reltype=None):
-    "A list of relation_ids"
+    """A list of relation_ids"""
     reltype = reltype or relation_type()
     relid_cmd_line = ['relation-ids', '--format=json']
     if reltype is not None:
@@ -203,7 +205,7 @@
 
 @cached
 def related_units(relid=None):
-    "A list of related units"
+    """A list of related units"""
     relid = relid or relation_id()
     units_cmd_line = ['relation-list', '--format=json']
     if relid is not None:
@@ -213,7 +215,7 @@
 
 @cached
 def relation_for_unit(unit=None, rid=None):
-    "Get the json represenation of a unit's relation"
+    """Get the json represenation of a unit's relation"""
     unit = unit or remote_unit()
     relation = relation_get(unit=unit, rid=rid)
     for key in relation:
@@ -225,7 +227,7 @@
 
 @cached
 def relations_for_id(relid=None):
-    "Get relations of a specific relation ID"
+    """Get relations of a specific relation ID"""
     relation_data = []
     relid = relid or relation_ids()
     for unit in related_units(relid):
@@ -237,7 +239,7 @@
 
 @cached
 def relations_of_type(reltype=None):
-    "Get relations of a specific type"
+    """Get relations of a specific type"""
     relation_data = []
     reltype = reltype or relation_type()
     for relid in relation_ids(reltype):
@@ -249,7 +251,7 @@
 
 @cached
 def relation_types():
-    "Get a list of relation types supported by this charm"
+    """Get a list of relation types supported by this charm"""
     charmdir = os.environ.get('CHARM_DIR', '')
     mdf = open(os.path.join(charmdir, 'metadata.yaml'))
     md = yaml.safe_load(mdf)
@@ -264,6 +266,7 @@
 
 @cached
 def relations():
+    """Get a nested dictionary of relation data for all related units"""
     rels = {}
     for reltype in relation_types():
         relids = {}
@@ -278,14 +281,14 @@
 
 
 def open_port(port, protocol="TCP"):
-    "Open a service network port"
+    """Open a service network port"""
     _args = ['open-port']
     _args.append('{}/{}'.format(port, protocol))
     subprocess.check_call(_args)
 
 
 def close_port(port, protocol="TCP"):
-    "Close a service network port"
+    """Close a service network port"""
     _args = ['close-port']
     _args.append('{}/{}'.format(port, protocol))
     subprocess.check_call(_args)
@@ -293,6 +296,7 @@
 
 @cached
 def unit_get(attribute):
+    """Get the unit ID for the remote unit"""
     _args = ['unit-get', '--format=json', attribute]
     try:
         return json.loads(subprocess.check_output(_args))
@@ -301,22 +305,46 @@
 
 
 def unit_private_ip():
+    """Get this unit's private IP address"""
     return unit_get('private-address')
 
 
 class UnregisteredHookError(Exception):
+    """Raised when an undefined hook is called"""
     pass
 
 
 class Hooks(object):
+    """A convenient handler for hook functions.
+
+    Example:
+        hooks = Hooks()
+
+        # register a hook, taking its name from the function name
+        @hooks.hook()
+        def install():
+            ...
+
+        # register a hook, providing a custom hook name
+        @hooks.hook("config-changed")
+        def config_changed():
+            ...
+
+        if __name__ == "__main__":
+            # execute a hook based on the name the program is called by
+            hooks.execute(sys.argv)
+    """
+
     def __init__(self):
         super(Hooks, self).__init__()
         self._hooks = {}
 
     def register(self, name, function):
+        """Register a hook"""
         self._hooks[name] = function
 
     def execute(self, args):
+        """Execute a registered hook based on args[0]"""
         hook_name = os.path.basename(args[0])
         if hook_name in self._hooks:
             self._hooks[hook_name]()
@@ -324,6 +352,7 @@
             raise UnregisteredHookError(hook_name)
 
     def hook(self, *hook_names):
+        """Decorator, registering them as hooks"""
         def wrapper(decorated):
             for hook_name in hook_names:
                 self.register(hook_name, decorated)
@@ -337,4 +366,5 @@
 
 
 def charm_dir():
+    """Return the root directory of the current charm"""
     return os.environ.get('CHARM_DIR')

=== modified file 'charmhelpers/core/host.py'
--- charmhelpers/core/host.py	2013-08-23 16:42:43 +0000
+++ charmhelpers/core/host.py	2013-09-26 14:36:53 +0000
@@ -19,18 +19,22 @@
 
 
 def service_start(service_name):
+    """Start a system service"""
     return service('start', service_name)
 
 
 def service_stop(service_name):
+    """Stop a system service"""
     return service('stop', service_name)
 
 
 def service_restart(service_name):
+    """Restart a system service"""
     return service('restart', service_name)
 
 
 def service_reload(service_name, restart_on_failure=False):
+    """Reload a system service, optionally falling back to restart if reload fails"""
     service_result = service('reload', service_name)
     if not service_result and restart_on_failure:
         service_result = service('restart', service_name)
@@ -38,11 +42,13 @@
 
 
 def service(action, service_name):
+    """Control a system service"""
     cmd = ['service', service_name, action]
     return subprocess.call(cmd) == 0
 
 
 def service_running(service):
+    """Determine whether a system service is running"""
     try:
         output = subprocess.check_output(['service', service, 'status'])
     except subprocess.CalledProcessError:
@@ -55,7 +61,7 @@
 
 
 def adduser(username, password=None, shell='/bin/bash', system_user=False):
-    """Add a user"""
+    """Add a user to the system"""
     try:
         user_info = pwd.getpwnam(username)
         log('user {0} already exists!'.format(username))
@@ -138,7 +144,7 @@
 
 
 def mount(device, mountpoint, options=None, persist=False):
-    '''Mount a filesystem'''
+    """Mount a filesystem at a particular mountpoint"""
     cmd_args = ['mount']
     if options is not None:
         cmd_args.extend(['-o', options])
@@ -155,7 +161,7 @@
 
 
 def umount(mountpoint, persist=False):
-    '''Unmount a filesystem'''
+    """Unmount a filesystem"""
     cmd_args = ['umount', mountpoint]
     try:
         subprocess.check_output(cmd_args)
@@ -169,7 +175,7 @@
 
 
 def mounts():
-    '''List of all mounted volumes as [[mountpoint,device],[...]]'''
+    """Get a list of all mounted volumes as [[mountpoint,device],[...]]"""
     with open('/proc/mounts') as f:
         # [['/mount/point','/dev/path'],[...]]
         system_mounts = [m[1::-1] for m in [l.strip().split()
@@ -178,7 +184,7 @@
 
 
 def file_hash(path):
-    ''' Generate a md5 hash of the contents of 'path' or None if not found '''
+    """Generate a md5 hash of the contents of 'path' or None if not found """
     if os.path.exists(path):
         h = hashlib.md5()
         with open(path, 'r') as source:
@@ -189,7 +195,7 @@
 
 
 def restart_on_change(restart_map):
-    ''' Restart services based on configuration files changing
+    """Restart services based on configuration files changing
 
     This function is used a decorator, for example
 
@@ -202,7 +208,7 @@
     In this example, the cinder-api and cinder-volume services
     would be restarted if /etc/ceph/ceph.conf is changed by the
     ceph_client_changed function.
-    '''
+    """
     def wrap(f):
         def wrapped_f(*args):
             checksums = {}
@@ -220,7 +226,7 @@
 
 
 def lsb_release():
-    '''Return /etc/lsb-release in a dict'''
+    """Return /etc/lsb-release in a dict"""
     d = {}
     with open('/etc/lsb-release', 'r') as lsb:
         for l in lsb:
@@ -230,7 +236,7 @@
 
 
 def pwgen(length=None):
-    '''Generate a random pasword.'''
+    """Generate a random pasword."""
     if length is None:
         length = random.choice(range(35, 45))
     alphanumeric_chars = [