More work to improve the quality of sphinx autodocs.

[pyutils.git] / docs / pyutils.collectionz.rst

diff --git a/docs/pyutils.collectionz.rst b/docs/pyutils.collectionz.rst
index c3424503628c6c817a46203a42aefa903851ae4d..60518dcc9812e8b95e2a513839bc5c002ac0d984 100644 (file)
--- a/docs/pyutils.collectionz.rst
+++ b/docs/pyutils.collectionz.rst
@@ -7,6 +7,35 @@ Submodules
 pyutils.collectionz.bidict module
 ---------------------------------
 
+The bidict.BiDict class is a subclass of :py:class:`dict` that
+implements a bidirectional dictionary.  That is, it maps each key to a
+value in constant time and each value back to the one or more keys it
+is associated with in constant time.  It does this by simply storing
+the data twice.
+
+Sample usage::
+
+    # Initialize with a normal dict...
+    third_party_wierdos = BiDict({
+        'prometheus-fastapi-instrumentator': 'prometheus_fastapi_instrumentator',
+        'scikit-learn': 'sklearn',
+        'antlr4-python3-runtime' : 'antlr4',
+        'python-dateutil': 'dateutil',
+        'speechrecognition': 'speech_recognition',
+        'beautifulsoup4': 'bs4',
+        'python-dateutil': 'dateutil',
+        'homeassistant-api': 'homeassistant_api',
+    })
+
+    # Use in one direction:
+    x = third_party_wierdos['scikit-learn']
+
+    # Use in opposite direction:
+    y = third_party_wierdos.inverse['python_dateutil']
+
+    # Note: type(y) is List since one value may map back to multiple keys.
+
+
 .. automodule:: pyutils.collectionz.bidict
    :members:
    :undoc-members:
@@ -15,6 +44,8 @@ pyutils.collectionz.bidict module
 pyutils.collectionz.bst module
 ------------------------------
 
+The bst.BinarySearchTree class is a binary search tree container.
+
 .. automodule:: pyutils.collectionz.bst
    :members:
    :undoc-members:
@@ -23,6 +54,14 @@ pyutils.collectionz.bst module
 pyutils.collectionz.shared\_dict module
 ---------------------------------------
 
+The shared\_dict.SharedDict class is a normal python dictionary that
+can be accessed safely in parallel from multiple threads or processes
+without (external) locking by using Multiprocessing.SharedMemory.  It
+uses internal locking and rewrites the shared memory region as it is
+changed so it is slower than a normal dict.  It also does not grow
+dynamically; the creator of the shared\_dict must declare a maximum
+size.
+
 .. automodule:: pyutils.collectionz.shared_dict
    :members:
    :undoc-members:
@@ -31,6 +70,13 @@ pyutils.collectionz.shared\_dict module
 pyutils.collectionz.trie module
 -------------------------------
 
+The trie.Trie class is a Trie or prefix tree.  It can be used with
+arbitrary sequences as keys and stores its values in a tree with paths
+determined by the sequence determined by each key.  Thus, it can
+determine whether a value is contained in the tree via a simple
+traversal in linear time and can also check whether a key-prefix is
+present in the tree in linear time.
+
 .. automodule:: pyutils.collectionz.trie
    :members:
    :undoc-members: