Docfmt: help module docstring formatting bundle

src/hio/help/decking.py

@@ -35,26 +35,26 @@ class Deck(deque):
 
     Local methods::
 
-        .push(x) = add x if x is not None to the right side of deque (like append)
-        .pull(x) = remove and return element from left side of deque (like popleft)
+        .push(x): add x if x is not None to the right side of deque (like append)
+        .pull(x): remove and return element from left side of deque (like popleft)
 
 
     Inherited methods from deque::
 
-        .append(x)             = add x to right side of deque
-        .appendleft(x)         = add x to left side of deque
-        .clear()               = clear all items from deque leaving it a length 0
-        .count(x)              = count the number of deque elements equal to x.
-        .extend(iterable)      = append elements of iterable to right side
-        .extendleft(iterable)  = append elemets of iterable to left side
+        .append(x): add x to right side of deque
+        .appendleft(x): add x to left side of deque
+        .clear(): clear all items from deque leaving it a length 0
+        .count(x): count the number of deque elements equal to x.
+        .extend(iterable): append elements of iterable to right side
+        .extendleft(iterable): append elemets of iterable to left side
                                  (this reverses iterable)
-        .pop()                 = remove and return element from right side
+        .pop(): remove and return element from right side
                                   if empty then raise IndexError
-        .popleft()             = remove and return element from left side
+        .popleft(): remove and return element from left side
                                   if empty then raise IndexError
-        .remove(x)             = remove first occurence of x left to right
+        .remove(x): remove first occurence of x left to right
                                   if not found raise ValueError
-        .rotate(n)             = rotate n steps to right if neg rotate to left
+        .rotate(n): rotate n steps to right if neg rotate to left
 
     Built in methods supported::
 
@@ -66,7 +66,7 @@ class Deck(deque):
 
     Attributes::
 
-        .maxlen  = maximum size of Deck or None if unbounded
+        .maxlen: maximum size of Deck or None if unbounded
 
     """
     def __repr__(self):

src/hio/help/doming.py

@@ -361,7 +361,7 @@ class MapDom():
         __iter__():  asdict(self)
         __getitem__(self, name)  map like interface
         __setitem__(self, name, value)  map like interface
-        _update(*pa,**kwa): update attributes using dict like update syntax
+        _update(\*pa, \*\*kwa): update attributes using dict like update syntax
         _asdict(): return self converted to dict
         _astuple(): return self converted to tuple
     """
@@ -631,7 +631,7 @@ class RawDom(MapDom):
         __iter__(self): asdict(self)
         _asdict(self): return self converted to dict
         _astuple(): return self converted to tuple
-        _update(*pa,**kwa): update attributes using dict like update syntax
+        _update(\*pa, \*\*kwa): update attributes using dict like update syntax
 
     Methods:
         _asjson(self): return bytes self converted to json

src/hio/help/helping.py

@@ -489,7 +489,7 @@ def intToB64b(i, l=1):
     """Converts int i to at least l Base64 chars as bytes.
 
     Returns:
-        b64 (bytes): Base64 converstion of i of length minimum l. If more than
+        b64 (bytes): Base64 conversion of i of length minimum l. If more than
                      l bytes are needed to represent i in Base64 then returned
                      bytes is extended appropriately. When less then l bytes
                      is needed then returned bytes is prepadded with b'A' bytes.
@@ -498,7 +498,7 @@ def intToB64b(i, l=1):
         i (int): to be converted
         l (int): min number of b64 digits. When empty these are left padded with
                  Base64 0 == b'A' digits.
-                 The length of return bytes is extended to accomodate full
+                 The length of return bytes is extended to accommodate full
                  Base64 encoding of i regardless of l.
     """
     return (intToB64(i=i, l=l).encode())

src/hio/help/hicting.py

@@ -17,22 +17,21 @@ class Hict(CIMultiDict):
 
     https://multidict.readthedocs.io/en/stable/
     CIMultiDict keys must be subclass of str no ints allowed
-    In CIMultiDict:
-        .add(key,value)  appends value to the valuelist at key
+    In CIMultiDict::
 
+        .add(key, value) appends value to the valuelist at key
         m["key"] = value replaces the valuelist at key with [value]
-
         m["key"] returns the first added element of the valuelist at key
 
     MultiDict methods access values in FIFO order
     Hict adds method to access values in LIFO order
 
-    Extended methods in Hict but not in CIMultiDict are:
-       nabone(key [,default])  get last value at key else default or KeyError
-       nab(key [,default])  get last value at key else default or None
-       naball(key [,default]) get all values inverse order else default or KeyError
-       firsts() get all items where item value is first inserted value at key
-       lasts() get all items where item value is last insterted value at key
+    Extended methods in Hict but not in CIMultiDict:
+        - nabone(key [,default]): get last value at key else default or KeyError
+        - nab(key [,default]): get last value at key else default or None
+        - naball(key [,default]): get all values inverse order else default or KeyError
+        - firsts(): get all items where item value is first inserted value at key
+        - lasts(): get all items where item value is last inserted value at key
     """
 
     def __repr__(self):
@@ -122,20 +121,19 @@ class Mict(MultiDict):
 
     https://multidict.readthedocs.io/en/stable/
     MultiDict keys must be subclass of str no ints allowed
-    In MultiDict:
-        .add(key,value)  appends value to the valuelist at key
+    In MultiDict::
 
+        .add(key, value) appends value to the valuelist at key
         m["key"] = value replaces the valuelist at key with [value]
-
         m["key"] returns the first added element of the valuelist at key
 
     MultiDict methods access values in FIFO order
     Mict adds methods to access values in LIFO order
 
-    Extended methods in Mict but not in MultiDict are:
-       nabone(key [,default])  get last value at key else default or KeyError
-       nab(key [,default])  get last value at key else default or None
-       naball(key [,default]) get all values inverse order else default or KeyError
+    Extended methods in Mict but not in MultiDict:
+        - nabone(key [,default]): get last value at key else default or KeyError
+        - nab(key [,default]): get last value at key else default or None
+        - naball(key [,default]): get all values inverse order else default or KeyError
 
     """
 
@@ -213,4 +211,3 @@ def lasts(self):
         """
         keys = oset(self.keys())  # get rid of duplicates provided by .keys()
         return [(k, self.nabone(k)) for k in keys]
-

src/hio/help/mining.py

@@ -8,7 +8,7 @@
 
 import re
 from collections.abc import Iterable, Mapping
-from ..help import isNonStringIterable, NonStringIterable
+from .helping import isNonStringIterable, NonStringIterable
 
 
 
@@ -25,24 +25,24 @@ class Mine(dict):
     will only allow actual keys as str. Iterables passed in as key are converted
     to a "_' joined str. Uses "_" so can use dict constuctor if need be with str
     path. Assumes items in Iterable do not contain '_'.
-    Supports attribute syntax to access items:
-        mine.a = 5
-        mine.a_b = 4
+    Supports attribute syntax to access items, e.g. mine.a = 5 and mine.a_b = 4.
 
-    Special staticmethods:
-        tokeys(k) returns split of k at separator '_' as tuple.
+    Special static methods: tokeys(k) returns split of k at separator '_' as tuple.
     """
 
     def __init__(self, *pa, **kwa):
         """Convert keys that are tuples when positional argument is Iterable or
         Mapping to '.' joined strings
 
-        dict __init__ signature options are:
+        dict __init__ signature options are::
+
             dict(**kwa)
             dict(mapping, **kwa)
             dict(iterable, **kwa)
-        dict.update has same call signature
-            d.update({"a": 5, "b": 2,}, c=3 , d=4)
+
+        dict.update has same call signature::
+
+            d.update({"a": 5, "b": 2}, c=3, d=4)
         """
         self.update(*pa, **kwa)
 
@@ -93,12 +93,15 @@ def update(self, *pa, **kwa):
         """Convert keys that are tuples when positional argument is Iterable or
         Mapping to '.' joined strings
 
-        dict __init__ signature options are:
+        dict __init__ signature options are::
+
             dict(**kwa)
             dict(mapping, **kwa)
             dict(iterable, **kwa)
-        dict.update has same call signature
-            d.update({"a": 5, "b": 2,}, c=3 , d=4)
+
+        dict.update has same call signature::
+
+            d.update({"a": 5, "b": 2}, c=3, d=4)
 
         """
         if len(pa) > 1:
@@ -165,5 +168,3 @@ def tokeys(key):
             keys (tuple[str]): split of key on '_' into path key components
         """
         return tuple(key.split('_'))
-
-

src/hio/help/naming.py

@@ -134,10 +134,8 @@ def addNameAddr(self, name, addr):
         All mappings must be one-to-one
 
         Returns:
-            result (bool):  True if successfully added new entry.
-                            False If matching entry already exists.
-                            Otherwise raises NamerError if partial matching
-                                entry with either name or addr
+            bool: True if a new entry was added; False if matching entry already
+            exists. Raises NamerError for conflicting partial matches.
 
         Parameters:
             name (str): name of entry
@@ -175,14 +173,15 @@ def remNameAddr(self, name=None, addr=None):
            All mappings must be one-to-one
 
         Returns:
-            result (bool):  True if matching entry successfully deleted
-                            False if no matching entry, nothing deleted
+            bool: True if matching entry was deleted; False when no matching
+            entry exists.
 
         Parameters:
             name (str | None): name of remote to delete or None if delete by addr
             addr (str | None): addr of remote to delete or None if delete by name
 
-            When both name and addr provided deletes by name
+        Notes:
+            When both name and addr are provided, delete by name.
 
         Raise error when at least one of name or addr is not None and no mappings
         exist.
@@ -226,9 +225,8 @@ def changeAddrAtName(self, *, name=None, addr=None):
         All mappings must be one-to-one
 
         Returns:
-            result (bool):  True If successfully updated existing entries.
-                            False If matching entry already exists, no change.
-                            Otherwise raises NamerError
+            bool: True if existing entries were updated; False if no change.
+            Raises NamerError for conflicts.
 
         Parameters:
             name (str): name of entry
@@ -263,9 +261,8 @@ def changeNameAtAddr(self, *, addr=None, name=None):
         All mappings must be one-to-one
 
         Returns:
-            result (bool):  True If successfully updated existing entries.
-                            False If matching entry already exists, no change.
-                            Otherwise raises NamerError
+            bool: True if existing entries were updated; False if no change.
+            Raises NamerError for conflicts.
 
         Parameters:
             addr (str): address of entry
@@ -292,4 +289,3 @@ def changeNameAtAddr(self, *, addr=None, name=None):
         self._addrByName[name] = addr
 
         return True  # updated entries
-

src/hio/help/packing.py

@@ -18,17 +18,16 @@ def packify(fmt=u'8', fields=[0x00], size=None, reverse=False):
 
     Assumes unsigned fields values.
     Assumes network big endian so first fields element is high order bits.
-    Each field in format string is number of bits for the associated bit field
-    Fields with length of 1 are treated as has having boolean truthy field values
-       that is,   nonzero is True and packs as a 1
-    for 2+ length bit fields the field element is truncated to the number of
-       low order bits in the bit field
-    if sum of number of bits in fmt less than size bytes then the last byte in
-       the bytearray is right zero padded
-    if sum of number of bits in fmt greater than size bytes returns exception
-    to pad just use 0 value in source field.
-    example
-    packify("1 3 2 2", (True, 4, 0, 3)). returns bytearry([0xc3])
+    Each field in format string is number of bits for the associated bit field.
+    Fields with length of 1 are treated as having boolean truthy field values;
+    nonzero is True and packs as a 1.
+    For 2+ length bit fields the field element is truncated to the number of
+    low order bits in the bit field.
+    If sum of number of bits in fmt is less than size bytes then the last byte
+    in the bytearray is right zero padded.
+    If sum of number of bits in fmt is greater than size bytes, returns
+    exception. To pad just use 0 value in source field.
+    Example: ``packify("1 3 2 2", (True, 4, 0, 3))`` returns ``bytearray([0xc3])``.
     """
     tbfl = sum((int(x) for x in fmt.split()))
     if size is None:
@@ -66,25 +65,24 @@ def packifyInto(b, fmt=u'8', fields=[0x00], size=None, offset=0, reverse=False):
     starting at offset and packing into size bytes
     Each white space separated field of fmt is the length of the associated bit field
     If not provided size is the least integer number of bytes that hold the fmt.
-    Extends the length of b to accomodate size after offset if not enough.
+    Extends the length of b to accommodate size after offset if not enough.
     Returns actual size of portion packed into.
     The default assumes big endian.
     If reverse is True then reverses the byte order before extending. Useful for
     little endian.
 
     Assumes unsigned fields values.
     Assumes network big endian so first fields element is high order bits.
-    Each field in format string is number of bits for the associated bit field
-    Fields with length of 1 are treated as has having boolean truthy field values
-       that is,   nonzero is True and packs as a 1
-    for 2+ length bit fields the field element is truncated
-    to the number of low order bits in the bit field
-    if sum of number of bits in fmt less than size bytes then the last byte in
-       the bytearray is right zero padded
-    if sum of number of bits in fmt greater than size bytes returns exception
-    to pad just use 0 value in source field.
-    example
-    packify("1 3 2 2", (True, 4, 0, 3)). returns bytearry([0xc3])
+    Each field in format string is number of bits for the associated bit field.
+    Fields with length of 1 are treated as having boolean truthy field values;
+    nonzero is True and packs as a 1.
+    For 2+ length bit fields the field element is truncated to the number of
+    low order bits in the bit field.
+    If sum of number of bits in fmt is less than size bytes then the last byte
+    in the bytearray is right zero padded.
+    If sum of number of bits in fmt is greater than size bytes, returns
+    exception. To pad just use 0 value in source field.
+    Example: ``packify("1 3 2 2", (True, 4, 0, 3))`` returns ``bytearray([0xc3])``.
     """
     tbfl = sum((int(x) for x in fmt.split()))
     if size is None:
@@ -140,17 +138,17 @@ def unpackify(fmt=u'1 1 1 1 1 1 1 1',
 
     Assumes network big endian so first fmt is high order bits.
     Format string is number of bits per bit field
-    If boolean parameter is True then return boolean values for
-       bit fields of length 1
+    If boolean parameter is True then return boolean values for bit fields of
+    length 1.
 
-    if sum of number of bits in fmt less than 8 * size) then remaining
-    bits are returned as additional field in result.
+    If sum of number of bits in fmt is less than 8 * size then remaining bits
+    are returned as additional field in result.
 
     if sum of number of bits in fmt greater 8 * len(b) returns exception
 
-    example:
-    unpackify(u"1 3 2 2", bytearray([0xc3]), False) returns (1, 4, 0, 3)
-    unpackify(u"1 3 2 2", 0xc3, True) returns (True, 4, 0, 3)
+    Examples: ``unpackify(u"1 3 2 2", bytearray([0xc3]), False)`` returns
+    ``(1, 4, 0, 3)`` and ``unpackify(u"1 3 2 2", 0xc3, True)`` returns
+    ``(True, 4, 0, 3)``.
     """
     b = bytearray(b)
     if reverse:
@@ -191,4 +189,3 @@ def unpackify(fmt=u'1 1 1 1 1 1 1 1',
 
         fields.append(bits) #assign to fields list
     return tuple(fields) #convert to tuple
-