From: Scott Gasch <scott@gasch.org>
Date: Wed, 1 Jun 2022 05:12:19 +0000 (-0700)
Subject: More doc updates.
X-Git-Url: https://wannabe.guru.org/gitweb/?a=commitdiff_plain;h=2a6d7810f85b88fb89d11d3e6be64f974ab77f97;p=python_utils.git

More doc updates.
---

diff --git a/NOTICE b/NOTICE
index f5937ca..59d5c11 100644
--- a/NOTICE
+++ b/NOTICE
@@ -28,6 +28,7 @@ contains URLs pointing at the source of the forked code.
       replace_nth.
     + Added type annotations everywhere,
     + Wrote doctests everywhere,
+    + Added sphinx style pydocs,
     + Wrote a supplimental unittest (tests/string_utils_test.py),
     + Added logging.
 
@@ -41,6 +42,7 @@ contains URLs pointing at the source of the forked code.
   Scott's modifications include:
     + Adding a unittest (tests/shared_dict_test.py),
     + Minor cleanup and style tweaks,
+    + Added sphinx style pydocs,
     + Added type hints.
 
   3. The timeout decortator in decorator_utils.py is based on original
@@ -65,6 +67,7 @@ contains URLs pointing at the source of the forked code.
     + Ported the code to python3,
     + Added type hints,
     + Added timeouts / retries,
+    + Added sphinx style pydocs,
     + Added logging.
 
 Thank you to everyone who makes their code available for reuse by
diff --git a/unscrambler.py b/unscrambler.py
index a40213e..3ccddbb 100644
--- a/unscrambler.py
+++ b/unscrambler.py
@@ -102,10 +102,16 @@ class Unscrambler(object):
     lookup methods support a "fuzzy match" argument that can be set to
     request similar words that do not match exactly in addition to any
     exact matches.
-
     """
 
     def __init__(self, indexfile: Optional[str] = None):
+        """
+        Constructs an unscrambler.
+
+        Args:
+            indexfile: overrides the default indexfile location if provided
+        """
+
         # Cached index per instance.
         self.sigs = []
         self.words = []
@@ -122,6 +128,7 @@ class Unscrambler(object):
 
     @staticmethod
     def get_indexfile(indexfile: Optional[str]) -> str:
+        """Returns the current indexfile location."""
         if indexfile is None:
             if 'unscrambler_default_indexfile' in config.config:
                 indexfile = config.config['unscramble_indexfile']
@@ -177,6 +184,12 @@ class Unscrambler(object):
         the word and their frequencies.  We try to cluster "similar"
         words close to each other in the signature space.
 
+        Args:
+            word: the word to compute a signature for
+
+        Returns:
+            The word's signature.
+
         >>> train = Unscrambler.compute_word_sig('train')
         >>> train
         23178969883741
@@ -201,9 +214,14 @@ class Unscrambler(object):
         dictfile: str = '/usr/share/dict/words',
         indexfile: str = '/usr/share/dict/sparse_index',
     ) -> None:
-        """Before calling this method, change letter_sigs from the default above
-        unless you want to populate the same exact files.
+        """
+        Repopulates the indexfile.
 
+        .. warning::
+
+            Before calling this method, change letter_sigs from the
+            default above unless you want to populate the same exact
+            files.
         """
         words_by_sigs: Dict[int, str] = {}
         seen = set()
@@ -229,10 +247,20 @@ class Unscrambler(object):
         """Looks up a potentially scrambled word optionally including near
         "fuzzy" matches.
 
+        Args:
+            word: the word to lookup
+            window_size: the number of nearby fuzzy matches to return
+
+        Returns:
+            A dict of word -> bool containing unscrambled words with (close
+            to or precisely) the same letters as the input word.  The bool
+            values in this dict indicate whether the key word is an exact
+            or near match.  The count of entries in this dict is controlled
+            by the window_size param.
+
         >>> u = Unscrambler()
         >>> u.lookup('eanycleocipd', window_size=0)
         {'encyclopedia': True}
-
         """
         sig = Unscrambler.compute_word_sig(word)
         return self.lookup_by_sig(sig, window_size=window_size)
@@ -242,6 +270,18 @@ class Unscrambler(object):
         a previous call to Unscrambler.compute_word_sig.  Optionally returns
         near "fuzzy" matches.
 
+        Args:
+            sig: the signature of the word to lookup (see :meth:`compute_word_sig`
+                to generate these signatures).
+            window_size: the number of nearby fuzzy matches to return
+
+        Returns:
+            A dict of word -> bool containing unscrambled words with (close
+            to or precisely) the same letters as the input word.  The bool
+            values in this dict indicate whether the key word is an exact
+            or near match.  The count of entries in this dict is controlled
+            by the window_size param.
+
         >>> sig = Unscrambler.compute_word_sig('sunepsapetuargiarin')
         >>> sig
         18491949645300288339
@@ -249,7 +289,6 @@ class Unscrambler(object):
         >>> u = Unscrambler()
         >>> u.lookup_by_sig(sig)
         {'pupigerous': False, 'pupigenous': False, 'unpurposing': False, 'superpurgation': False, 'unsupporting': False, 'superseptuaginarian': True, 'purpurogallin': False, 'scuppaug': False, 'purpurigenous': False, 'purpurogenous': False, 'proppage': False}
-
         """
         ret = {}
         (_, location) = list_utils.binary_search(self.sigs, sig)