Comment and doc cleanups (walk-through-inspection)

- Many spelling/clarity comment fixes
- Doc quoting fixes
- Drop use of backports.shutil_which (not needed after Python 3.3)
- Remove some 'NamedTuple' abandoned work-in-progress code (commented out)

docs/source/dyn/cli.rst

@@ -212,7 +212,7 @@ ksconf diff
       --format {diff,json}, -f {diff,json}
                             Output file format to produce. 'diff' the the classic
                             format used by default. 'json' is helpful when trying
-                            to review changes programatically .
+                            to review changes programmatically.
 
 
 

ksconf/builder/cache.py

@@ -14,9 +14,9 @@ class FileSet:
 
     Currently the fingerprint is only a SHA256 hash.
 
-    Two constructore are provided for building an instance from either file that
+    Two constructors are provided for building an instance from either file that
     live on the filesystem, via :py:meth:`from_filesystem` or from a persisted
-    cached record aviable from the :py:meth:`from_cache`.
+    cached record available from the :py:meth:`from_cache`.
     The filesystem version actively reads all inputs files at object creation
     time, so this can be costly, especially if repeated.
     """

ksconf/builder/core.py

@@ -4,11 +4,11 @@
 
 Cache build requirements:
 
-    * Caching mechanism should inspet 'inputs' (collect file hashes) to determine if any content has
+    * Caching mechanism should inspect 'inputs' (collect file hashes) to determine if any content has
       changed.  If input varies, then command should be re-run.
     * Command (decorated function) should be generally unaware of all other details of build process,
       and it should *ONLY* be able to see files listed in "inputs"
-    * Allow caching to be fully disabled (run in-place with no dir proxying) for CI/CD
+    * Allow caching to be fully disabled (run in-place with no dir proxy) for CI/CD
     * Cache should have allow a timeout parameter
 
 

ksconf/combine.py

@@ -27,7 +27,7 @@ class LayerCombinerException(Exception):
 
 class LayerCombiner:
     """
-    Class to rescursively combine layers (directories) into a single rendered output target directory.
+    Class to recursively combine layers (directories) into a single rendered output target directory.
     This is heavily used by the ``ksconf combine`` command as well as by the ``package`` command.
 
 
@@ -45,7 +45,7 @@ class LayerCombiner:
         lc.combine()                    Entry point
             -> prepare()                Directory, layer prep
                 -> prepare_target_dir() Make dir; subclass handles marker here (combine CLI)
-            -> pre_combine_inventory()  Hook for pre-processing (or alterting) the set of files to combine
+            -> pre_combine_inventory()  Hook for pre-processing (or alerting) the set of files to combine
             -> combine_files()          Main worker function
             -> post_combine()           Optional, cleanup leftover files
     """
@@ -72,7 +72,7 @@ def __init__(self,
         self.layer_names_all = set()
         self.layer_names_used = set()
 
-        # Not a great long-term design, but good enough for initial converstion from command-based desgin
+        # Not a great long-term design, but good enough for initial conversion from command-based design
         self.stdout = sys.stdout
         self.stderr = sys.stderr
 

ksconf/commands/diff.py

@@ -50,7 +50,7 @@ def register_args(self, parser):
         parser.add_argument("--format", "-f",
                             choices=["diff", "json"], default="diff",
                             help="Output file format to produce.  'diff' the the classic format used by default. "
-                            "'json' is helpful when trying to review changes programatically .")
+                            "'json' is helpful when trying to review changes programmatically.")
 
     def run(self, args):
         ''' Compare two configuration files. '''

ksconf/conf/delta.py

@@ -38,15 +38,6 @@ def __lt__(self, other):
 DIFF_OP_EQUAL = DiffVerb.EQUAL
 
 
-'''
-from typing import NamedTuple
-DiffOp = NamedTuple("DiffOp", (["tag", DiffVerb], ["location", Union[DiffGlobal, DiffStanza, DiffStzKey]], ["a", Union[ConfType, StanzaType, str]], ["b", Union[ConfType, StanzaType, str]]))
-DiffGlobal = NamedTuple("DiffGlobal", (["type", str],))
-DiffStanza = NamedTuple("DiffStanza", (["type", str], ["stanza", str]))
-DiffStzKey = NamedTuple("DiffStzKey", (["type", str], ["stanza", str], ["key", str]))
-'''
-
-
 class DiffLevel(Enum):
     GLOBAL = "global"
     STANZA = "stanza"
@@ -174,7 +165,7 @@ def compare_cfgs(a: ConfType, b: ConfType,
               in the standard Python module.
 
     This function returns a sequence of 5 element tuples describing the
-    transformation based on the detail level specified in `replace_level`.
+    transformation based on the detail level specified in ``replace_level``.
 
     Each :py:class:`DiffOp` (named tuple) takes the form:
 
@@ -202,7 +193,7 @@ def compare_cfgs(a: ConfType, b: ConfType,
     ====================== ========== ==============================================================
 
     .. versionchanged:: v0.8.8
-        The ``preserve_empty`` argument was origionally introduced to preserve backwards
+        The ``preserve_empty`` argument was originally introduced to preserve backwards
         compatibility, but it ended up introducing new bugs.
         Additionally, no use cases were found where better to automatically discarding empty stanzas.
 
@@ -252,7 +243,7 @@ def compare_cfgs(a: ConfType, b: ConfType,
 
 
 def summarize_cfg_diffs(delta: List[DiffOp], stream: TextIO):
-    """ Summarize a delta into a human-readable format.   The input `delta` is in the format
+    """ Summarize a delta into a human-readable format.   The input ``delta`` is in the format
     produced by the compare_cfgs() function.
     """
     stanza_stats = defaultdict(set)

ksconf/package.py

@@ -77,7 +77,7 @@ def expand_var(self, value):
     def expand_new_only(self, value):
         """ Expand a variable but return False if no substitution occurred
 
-        :param str value:  String that main contain ``{{variable}}`` substitution.
+        :param str value:  String that may contain ``{{variable}}`` substitution.
         :return:  Expanded value if variables were expanded, else False
         :rtype: str
         """
@@ -231,7 +231,7 @@ def make_archive(self, filename):
     def __enter__(self):
         self.build_dir = tempfile.mkdtemp("-ksconf-package-build")
         if self.app_name == "." or "{{" in self.app_name:
-            # Use a placehold app name, specifically as "." causes build_dir == app_dir
+            # Use a placeholder app name, otherwise build_dir == app_dir
             self.app_dir = os.path.join(self.build_dir, "app")
         else:
             self.app_dir = os.path.join(self.build_dir, self.app_name)

ksconf/vc/git.py

@@ -1,16 +1,11 @@
 from __future__ import absolute_import, unicode_literals
 
 from collections import Counter, namedtuple
+from shutil import which
 from subprocess import PIPE, Popen, call, list2cmdline
 
 from ksconf.util import _xargs, memoize
 
-try:
-    from shutil import which
-except ImportError:
-    from backports.shutil_which import which
-
-
 GIT_BIN = "git"
 GitCmdOutput = namedtuple("GitCmdOutput", ["cmd", "returncode", "stdout", "stderr", "lines"])
 
@@ -45,7 +40,7 @@ def git_cmd_iterable(args, iterable, cwd=None, cmd_len=1024):
                 p.returncode, list2cmdline(args + chunk)))
 
 
-# Shave time off of unit testing; or anyting that does CLI calls from the API
+# Shave time off of unit testing; or anything that does CLI calls from the API
 @memoize
 def git_version():
     git_path = which(GIT_BIN)

ksconf/xmlformat.py

@@ -23,7 +23,7 @@ def _import_etree():
 
 
 class FileReadlinesCache:
-    """ Silly class as a hacky workaround for CDATA detection... """
+    """ Silly workaround for CDATA detection... """
 
     def __init__(self):
         self.cache = {}