From 6131b2e4054dbdff0be7fdeec13b868b1a915783 Mon Sep 17 00:00:00 2001
From: Jay Faulkner <jay@jvf.cc>
Date: Thu, 3 Sep 2015 14:02:28 -0700
Subject: [PATCH] Ensure all methods in utils.py have docstrings

Previous some of these methods were not well documented. Hopefully they
now are.

Change-Id: If73987a2dd234b71a1c2af9b764becc34aee4496
Partial-bug: 1367915
---
 ironic_python_agent/utils.py | 36 +++++++++++++++++++++++++++++++-----
 1 file changed, 31 insertions(+), 5 deletions(-)

diff --git a/ironic_python_agent/utils.py b/ironic_python_agent/utils.py
index 53305f113..3ef5ec23e 100644
--- a/ironic_python_agent/utils.py
+++ b/ironic_python_agent/utils.py
@@ -46,7 +46,18 @@ AGENT_PARAMS_CACHED = dict()
 
 
 def execute(*cmd, **kwargs):
-    """Convenience wrapper around oslo's execute() method."""
+    """Convenience wrapper around oslo's execute() method.
+
+    Executes and logs results from a system command. See docs for
+    oslo_concurrency.processutils.execute for usage.
+
+    :param *cmd: positional arguments to pass to processutils.execute()
+    :param **kwargs: keyword arguments to pass to processutils.execute()
+    :raises: UnknownArgumentError on receiving unknown arguments
+    :raises: ProcessExecutionError
+    :raises: OSError
+    :returns: tuple of (stdout, stderr)
+    """
     result = processutils.execute(*cmd, **kwargs)
     LOG.debug('Execution completed, command line is "%s"', ' '.join(cmd))
     LOG.debug('Command stdout is: "%s"', result[0])
@@ -55,7 +66,19 @@ def execute(*cmd, **kwargs):
 
 
 def try_execute(*cmd, **kwargs):
-    """The same as execute but returns None on error."""
+    """The same as execute but returns None on error.
+
+    Executes and logs results from a system command. See docs for
+    oslo_concurrency.processutils.execute for usage.
+
+    Instead of raising an exception on failure, this method simply
+    returns None in case of failure.
+
+    :param *cmd: positional arguments to pass to processutils.execute()
+    :param **kwargs: keyword arguments to pass to processutils.execute()
+    :raises: UnknownArgumentError on receiving unknown arguments
+    :returns: tuple of (stdout, stderr) or None in some error cases
+    """
     try:
         return execute(*cmd, **kwargs)
     except (processutils.ProcessExecutionError, OSError) as e:
@@ -190,9 +213,12 @@ def get_agent_params():
 
 
 def normalize(string):
-    """Return a normalized string."""
-    # Since we can't use space on the kernel cmdline, Ironic will
-    # urlencode the values.
+    """Return a normalized string.
+
+    Take a urlencoded value from Ironic and urldecode it.
+
+    :returns: a normalized version of passed in string
+    """
     return parse.unquote(string).lower().strip()