From: Scott Gasch 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)