From: Christian Herdtweck <christian.herdtweck@intra2net.com>
Date: Mon, 11 Feb 2019 10:51:54 +0000 (+0100)
Subject: Add and fix and few CNF_VAR-related doc strings
X-Git-Tag: v1.4~3^2~2
X-Git-Url: http://developer.intra2net.com/git/?a=commitdiff_plain;h=02fe61790eef7989db0c0fefa8023834d3407fd0;p=pyi2ncommon

Add and fix and few CNF_VAR-related doc strings
---

diff --git a/src/arnied_wrapper.py b/src/arnied_wrapper.py
index 463ee4e..d59891a 100644
--- a/src/arnied_wrapper.py
+++ b/src/arnied_wrapper.py
@@ -666,6 +666,7 @@ def set_cnf_dynamic(cnf, config_file=None, kind="cnf", timeout=30, vm=None):
              "generated" if generated else "user-supplied",
              config_file, " on %s" % vm.name if vm is not None else "")
 
+    # Important to write bytes here to ensure text is encoded with latin-1
     fd = open(config_path, "wb")
     try:
         SET_CNF_METHODS = {
diff --git a/src/cnfvar.py b/src/cnfvar.py
index cb143f9..44af29f 100644
--- a/src/cnfvar.py
+++ b/src/cnfvar.py
@@ -115,12 +115,12 @@ import io
 
 
 def to_latin1(s):
-    """ take given unicode value and convert it to a latin1-encoded string """
+    """Take given unicode str and convert it to a latin1-encoded `bytes`."""
     return s.encode("latin-1")
 
 
 def from_latin1(s):
-    """ take given latin1-encoded string value and convert it to unicode """
+    """Take given latin1-encoded `bytes` value and convert it to `str`."""
     return s.decode("latin-1")
 
 #
@@ -568,10 +568,12 @@ def read_cnf(data):
 
 def renumber_vars(root, parent=None, toplevel=False):
     """
-    renumber_vars -- Number cnfvars linearly. If *parent* is specified,
-    numbering will start at this offset. Also, the VAR *root* will be assigned
-    this number as a parent lineno unless *toplevel* is set (the root var in
-    a CNF tree obviously can’t have a parent).
+    Number cnfvars linearly.
+
+    If *parent* is specified, numbering will start at this offset. Also, the
+    VAR *root* will be assigned this number as a parent lineno unless
+    *toplevel* is set (the root var in a CNF tree obviously can’t have a
+    parent).
 
     The *toplevel* parameter is useful when renumbering an existing variable
     starting at a given offset without at the same time having that offset
@@ -703,11 +705,13 @@ def normalize_cnf (cnf):
 
 
 def print_cnf_raw(root, out=None):
+    """`if root is not None: out.write(root)`."""
     if root is not None:
         out.write(root)
 
 
 def write_cnf_raw(*argv, **kw_argv):
+    """Alias for :py:func:`print_cnf_raw`."""
     print_cnf_raw(*argv, **kw_argv)
 
 
@@ -738,8 +742,7 @@ def output_cnf(root, out, renumber=False):
 
 def dump_cnf_bytes (root, renumber=False):
     """
-    dump_cnf_bytes -- Serialize CNF var structure, returning the result as a
-    byte sequence.
+    Serialize CNF var structure, returning the result as a byte sequence.
     """
     cnf = cnf_root(root)
     out = io.BytesIO()
@@ -751,8 +754,9 @@ def dump_cnf_bytes (root, renumber=False):
 
 def dump_cnf_string(root, renumber=False):
     """
-    dump_cnf_string -- Serialize CNF var structure, returning the result as a
-    string.
+    Serialize CNF var structure, returning a latin1-encode byte string.
+
+    .. todo::this is identical to :py:func:`dump_cnf_bytes`!
     """
     cnf = cnf_root(root)
     out = io.BytesIO()
@@ -761,16 +765,36 @@ def dump_cnf_string(root, renumber=False):
     out.close()
     return res
 
+
 def print_cnf(root, out=None, renumber=False):
+    """
+    Print given CNF_VAR structure to stdout (or other file-like object).
+
+    Note that per default the config is printed to sys.stdout using the shell's
+    preferred encoding. If the shell cannot handle unicode this might raise
+    `UnicodeError`.
+
+    All params forwarded to :py:func:`output_cnf`. See args there.
+    """
     if root is not None:
         output_cnf(root, out or sys.stdout, renumber=renumber)
 
 
 def write_cnf(*argv, **kw_argv):
+    """Alias for :py:func:`print_cnf`."""
     print_cnf(*argv, **kw_argv)
 
 
 def output_json(root, out, renumber=False):
+    """
+    Dump CNF_VAR structure to file-like object in json format.
+
+    :param root: CNF_VAR structure
+    :type root: dict or list or anything that :py:func:`cnf_root` accepts
+    :param out: file-like object, used as argument to :py:func:`json.dumps` so
+                probably has to accept `str` (as opposed to `bytes`).
+    :param bool renumber: whether to renumber variables before dupming.
+    """
     # Sanity check incompatible with Autotest. Who needs a seatbelt anyways?
     # if not isinstance(out, file):
         #raise TypeError("%s (%s) is not a stream." % (out, type(out)))
@@ -781,12 +805,12 @@ def output_json(root, out, renumber=False):
         data = json.dumps(root)
         out.write(data)
         out.write("\n")
+    # TODO: else raise value error?
 
 
 def dump_json_string(root, renumber=False):
     """
-    dump_json_string -- Serialize CNF var structure as JSON, returning the
-    result as a string.
+    Serialize CNF var structure as JSON, returning the result as a string.
     """
     out = io.StringIO()
     output_json(root, out, renumber=renumber)
@@ -796,11 +820,18 @@ def dump_json_string(root, renumber=False):
 
 
 def print_cnf_json(root, out=None, renumber=False):
+    """
+    Print CNF_VAR structure in json format to stdout.
+
+    Calls :py:func:`output_json` with `sys.stdout` if `out` is not given or
+    `None`.
+    """
     if root is not None:
         output_json(root, out or sys.stdout, renumber=renumber)
 
 
 def write_cnf_json(*argv, **kw_argv):
+    """Alias for :py:func:`print_cnf_json`."""
     print_cnf_json(*argv, **kw_argv)
 
 #