From 186b12624634b87e37ea861f7028f7e2f1e90088 Mon Sep 17 00:00:00 2001 From: Jay-Alexander Elliot Date: Fri, 13 Mar 2026 22:01:16 -0600 Subject: [PATCH] Normalize help module docstring formatting --- src/hio/help/decking.py | 26 +++++++++--------- src/hio/help/doming.py | 4 +-- src/hio/help/helping.py | 4 +-- src/hio/help/hicting.py | 31 ++++++++++------------ src/hio/help/mining.py | 29 ++++++++++---------- src/hio/help/naming.py | 24 +++++++---------- src/hio/help/packing.py | 59 +++++++++++++++++++---------------------- src/hio/help/timing.py | 35 ++++++++++++------------ 8 files changed, 102 insertions(+), 110 deletions(-) diff --git a/src/hio/help/decking.py b/src/hio/help/decking.py index eabebadf..28869206 100644 --- a/src/hio/help/decking.py +++ b/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): diff --git a/src/hio/help/doming.py b/src/hio/help/doming.py index 20487855..faf7f40c 100644 --- a/src/hio/help/doming.py +++ b/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 diff --git a/src/hio/help/helping.py b/src/hio/help/helping.py index 8e2c7db6..c563baf0 100644 --- a/src/hio/help/helping.py +++ b/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()) diff --git a/src/hio/help/hicting.py b/src/hio/help/hicting.py index 170d7c24..62a1b09d 100644 --- a/src/hio/help/hicting.py +++ b/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] - diff --git a/src/hio/help/mining.py b/src/hio/help/mining.py index af6e3f0e..500cfe5f 100644 --- a/src/hio/help/mining.py +++ b/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('_')) - - diff --git a/src/hio/help/naming.py b/src/hio/help/naming.py index 1340d738..ac432ea5 100644 --- a/src/hio/help/naming.py +++ b/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 - diff --git a/src/hio/help/packing.py b/src/hio/help/packing.py index 27ca147f..ded13bdd 100644 --- a/src/hio/help/packing.py +++ b/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,7 +65,7 @@ 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 @@ -74,17 +73,16 @@ def packifyInto(b, fmt=u'8', fields=[0x00], size=None, offset=0, 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: @@ -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 - diff --git a/src/hio/help/timing.py b/src/hio/help/timing.py index 1752affb..ca6f4e0e 100644 --- a/src/hio/help/timing.py +++ b/src/hio/help/timing.py @@ -20,19 +20,20 @@ class RetroTimerError(TimerError): class Timer(hioing.Mixin): """Class to manage real elaspsed time using time module. - Attributes: - ._start is start tyme in seconds - ._stop is stop tyme in seconds - Properties: - .duration is float time duration in seconds of timer from ._start to ._stop - .elaspsed is float time elasped in seconds since ._start - .remaining is float time remaining in seconds until ._stop - .expired is boolean, True if expired, False otherwise, i.e. time >= ._stop + Attribute notes: + - ._start is start tyme in seconds + - ._stop is stop tyme in seconds + + Property notes: + - .duration is float time duration in seconds of timer from ._start to ._stop + - .elaspsed is float time elasped in seconds since ._start + - .remaining is float time remaining in seconds until ._stop + - .expired is boolean, True if expired, False otherwise, i.e. time >= ._stop - methods: - .start() start timer at current time - .restart() = restart timer at last ._stop so no time lost + Method notes: + - start() starts timer at current time + - restart() restarts timer at last ._stop so no time lost """ def __init__(self, duration=0.0, start=None, **kwa): @@ -126,9 +127,9 @@ class MonoTimer(Timer): .expired is boolean True if expired, False otherwise, i.e. time >= ._stop .latest is float latest measured time in seconds with retrograte handling - methods: - .start() = start timer at current time returns start time - .restart() = restart timer at last ._stop so no time lost, returns start time + Methods: + - start: start timer at current time and return start time + - restart: restart timer at last ._stop with no time lost, returns start time """ def __init__(self, duration=0.0, start=None, retro=True): @@ -201,9 +202,9 @@ class AsyncTimer(Timer): .remaining is float time remaining in seconds until ._stop .expired is boolean, True if expired, False otherwise, i.e. time >= ._stop - methods: - .start() start timer at current time - .restart() = restart timer at last ._stop so no time lost + Methods: + - start: start timer at current time + - restart: restart timer at last ._stop so no time lost """ def __init__(self, duration=0.0, start=None, **kwa):