From c5f9af1662ad7bb063625c2d6473a3c6c92248ac Mon Sep 17 00:00:00 2001 From: Jay-Alexander Elliot Date: Sat, 14 Mar 2026 16:53:28 -0600 Subject: [PATCH] docs: fix docstring RST formatting across all modules for Sphinx/docutils compliance - Fix unexpected indentation errors in 30+ source modules by converting free-form text blocks to proper RST list items and literal blocks - Add :no-index: directives to manual .rst pages to resolve duplicate-object warnings when autoapi covers the same symbols - Fix conf.py: expand autoapi_dirs from base/ to full hio package, remove undoc-members, guard sphinx.ext.viewcode against Python 3.14 crash - Add test.md to exclude_patterns - Minor README.md line-wrap cleanup and typo fixes in docstrings Build result: 0 warnings, 0 errors (clean from 303+ errors on upstream main) --- src/hio/base/during.py | 51 +++++++------------- src/hio/base/filing.py | 14 +++--- src/hio/base/hier/boxing.py | 52 ++++++++++---------- src/hio/base/hier/canning.py | 34 +++++-------- src/hio/base/hier/durqing.py | 51 ++++++++------------ src/hio/base/hier/dusqing.py | 66 +++++++++++--------------- src/hio/base/hier/hogging.py | 91 +++++++++++++++-------------------- src/hio/base/hier/holding.py | 5 +- src/hio/base/hier/needing.py | 92 ++++++++++++------------------------ src/hio/base/multidoing.py | 49 ++++++++++--------- src/hio/base/tyming.py | 14 +++--- 11 files changed, 214 insertions(+), 305 deletions(-) diff --git a/src/hio/base/during.py b/src/hio/base/during.py index 6e31e4a8..643ade42 100644 --- a/src/hio/base/during.py +++ b/src/hio/base/during.py @@ -104,7 +104,7 @@ def __init__(self, readonly=False, **kwa): When system employs more than one keri installation, name allows differentiating each instance by name base (str): optional directory path segment inserted before name - that allows further differentation with a hierarchy. "" means + that allows further differentiation with a hierarchy. "" means optional. temp (bool): assign to .temp True then open in temporary directory, clear on close @@ -122,7 +122,7 @@ def __init__(self, readonly=False, **kwa): clean (bool): True means path uses clean tail variant False means path uses normal tail variant filed (bool): True means .path is file path not directory path - False means .path is directiory path not file path + False means .path is directory path not file path extensioned (bool): When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext @@ -147,25 +147,17 @@ def reopen(self, readonly=False, **kwa): Open lmdb and assign to .env Inherited Parameters: (see Filer) - temp (bool): assign to .temp - True means open in temporary directory, clear on close - False means open persistent directory, do not clear on close - headDirPath (str): optional head directory pathname for main database - Default .HeadDirpath - perm (int): optional numeric os dir permissions for database - directory and database files. Default .Perm - clear (bool): True means remove directory upon close - False means do not remove directory upon close - reuse (bool): True means reuse self.path if already exists - False means do not reuse but remake self.path - clean (bool): True means path uses clean tail variant - False means path uses normal tail variant + temp (bool): assign to .temp; temporary means clear on close, persistent means do not clear. + headDirPath (str): optional head directory pathname for main database. Default .HeadDirPath. + perm (int): optional numeric os dir permissions for database directory and files. Default .Perm. + clear (bool): True means remove directory upon close; False means keep directory. + reuse (bool): True means reuse self.path if already exists; False means remake self.path. + clean (bool): True means path uses clean tail variant; False means normal tail variant. mode (str): file open mode when .filed fext (str): File extension when .filed Parameters: - readonly (bool): True means open database in readonly mode - False means open database in read/write mode + readonly (bool): True means open database in readonly mode; False means read/write mode. """ exists = self.exists(name=self.name, base=self.base) opened = super(Duror, self).reopen(**kwa) @@ -271,8 +263,7 @@ def putVal(self, sdb, key, val): """Write serialized bytes val to location key in db (subdb) Does not overwrite. Returns: - result (bool): True if val successfully written - False if val at key already exitss + result (bool): True if val successfully written; False if val at key already exists Parameters: db (lmdb._Database): opened named subdb with dupsort=False @@ -291,8 +282,7 @@ def pinVal(self, sdb, key, val): """Write serialized bytes val to location key in db Overwrites existing val if any Returns: - result (bool): True If val successfully written - False otherwise + result (bool): True if val successfully written; False otherwise Parameters: db (lmdb._Database): opened named subdb with dupsort=False @@ -545,10 +535,8 @@ def getIoVals(self, sdb, key, *, ion=0, sep=b'.'): """Gets list of all the insertion ordered set of values at key Returns: - vals (list[bytes]): the insertion ordered set of values at same apparent - effective key. - Uses hidden ordinal key suffix for insertion ordering. - The suffix is appended and stripped transparently. + vals (list[bytes]): insertion-ordered values at same apparent effective key; + hidden ordinal key suffix is used for insertion ordering and stripped transparently. Parameters: db (lmdb._Database): instance of named sub db with dupsort==False @@ -1149,7 +1137,7 @@ def trim(self, keys: str|bytes|memoryview|Iterable=b"", *, topive=False): 'a.1'and 'a.2' but not 'ab' Parameters: - keys (Iteratabke[str | bytes | memoryview]): of key parts that may be + keys (Iterable[str | bytes | memoryview]): of key parts that may be a truncation of a full keys tuple in in order to address all the items from multiple branches of the key space. If keys is empty then trims all items in database. @@ -1185,7 +1173,7 @@ def getFullItemIter(self, keys: str|bytes|memoryview|Iterable[str|bytes]="", valuespace which may be useful in debugging or testing. Parameters: - keys (str|bytes|memoryview|Iteratable[str | bytes | memoryview]): + keys (str|bytes|memoryview|Iterable[str | bytes | memoryview]): of key parts that may be a truncation of a full keys tuple in in order to address all the items from multiple branches of the key space. @@ -1806,12 +1794,9 @@ def rem(self, keys: str | bytes | memoryview | Iterable, if val is empty then remove all values at key Returns: - When val: - result (bool): True if effective key with val exists so rem successful. - False otherwise - Otherwise: - result (bool): True if effective key with val exists so rem successful. - False otherwise + result (bool): True if deletion succeeds; False otherwise. + If val is provided, remove matching value at effective key. + If val is empty, remove all values at effective key. """ if val: diff --git a/src/hio/base/filing.py b/src/hio/base/filing.py index 2175ef3e..5e4f8116 100644 --- a/src/hio/base/filing.py +++ b/src/hio/base/filing.py @@ -99,7 +99,7 @@ def __init__(self, *, name='main', base="", temp=False, headDirPath=None, When system employs more than one keri installation, name allows differentiating each instance by name base (str): optional directory path segment inserted before name - that allows further differentation with a hierarchy. "" means + that allows further differentiation with a hierarchy. "" means optional. temp (bool): assign to .temp True then open in temporary directory, clear on close @@ -117,7 +117,7 @@ def __init__(self, *, name='main', base="", temp=False, headDirPath=None, clean (bool): True means path uses clean tail variant False means path uses normal tail variant filed (bool): True means .path is file path not directory path - False means .path is directiory path not file path + False means .path is directory path not file path extensioned (bool): When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext @@ -255,7 +255,7 @@ def remake(self, *, name="", base="", temp=None, headDirPath=None, perm=None, False means make path normally (not clean) filed (bool): True means .path is file path not directory path - False means .path is directiory path not file path + False means .path is directory path not file path extensioned (bool): When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext @@ -418,7 +418,7 @@ def exists(self, name="", base="", headDirPath=None, clean=False, False means make path normally (not clean) filed (bool): True means .path is file path not directory path - False means .path is directiory path not file path + False means .path is directory path not file path extensioned (bool): When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext @@ -548,9 +548,11 @@ def openFiler(cls=None, name="test", temp=True, reopen=True, clear=False, **kwa) Usage:: - with openFiler(name="bob") as filer: + with openFiler(name="bob") as filer: + pass - with openFiler(name="eve", cls=FilerSubClass) as filer: + with openFiler(name="eve", cls=FilerSubClass) as filer: + pass """ filer = None diff --git a/src/hio/base/hier/boxing.py b/src/hio/base/hier/boxing.py index 5da23240..58ea24ea 100644 --- a/src/hio/base/hier/boxing.py +++ b/src/hio/base/hier/boxing.py @@ -860,7 +860,7 @@ def go(self, dest: None|str=None, expr: None|str|Need=None, expr (None|str|Need): need for transition to dest. When None then conditional always True. Always godo. - When str then evalable python boolean expression to be + When str then evaluable python boolean expression to be resolved into a Need instance for eval at run time When Need instance then use as is @@ -894,7 +894,7 @@ def go(self, dest: None|str=None, expr: None|str|Need=None, if isinstance(expr, Need): need = expr - else: # assumes evalable expr str + else: # assumes evaluable expr str need = Need(expr=expr, hold=self.hold) goact = Goact(dest=dest, need=need) @@ -912,7 +912,7 @@ def do(self, deed: None|str|Type[ActBase]|Callable=None, nabe=None, *, deed (None|str|Type[ActBase]|Callable): When None use Act with default lambda and iops as parameters When str name of class in ActBase registry. - When issubclass of ActBase then create instance + When subclass of ActBase then create instance When Callable use Act with iops as parameters. name (None|str): name of act instance created by do. When None use default indexed name created by Act. @@ -922,7 +922,7 @@ def do(self, deed: None|str|Type[ActBase]|Callable=None, nabe=None, *, None is just to allow definition as keyword arg. Assumes in actual usage that mods is always provided as WorkDom instance. - iops (dict): input-output-parms for Act + iops (dict): input-output-parameters for Act """ m = mods # alias more compact @@ -971,9 +971,9 @@ def on(self, cond: None|str=None, key: None|str=None, expr: None|str=None, Parameters:: cond (None|str): special need condition to be satisfied. This is - resolved in evalable boolean expression. + resolved in evaluable boolean expression. When None then ignore - When str then special need condition to be resolved into evalable + When str then special need condition to be resolved into evaluable boolean expression key (None|str): key to mine item ref for special need cond when @@ -983,10 +983,10 @@ def on(self, cond: None|str=None, key: None|str=None, expr: None|str=None, When str then resolve key to mine at key - expr (None|str): evalable boolean expression as additional constraint(s) + expr (None|str): evaluable boolean expression as additional constraint(s) ANDed with result of cond. When None or empty then ignore - When str then evalable python boolean expression to be ANDed with + When str then evaluable python boolean expression to be ANDed with the result of cond resolution. mods (None | WorkDom): state variables used to construct box work @@ -1002,7 +1002,7 @@ def on(self, cond: None|str=None, key: None|str=None, expr: None|str=None, acts (dict): registry of ActBase subclasses by name (including aliases) nabe (str): action nabe (context) for act - iops (dict): input-output-parms for Act + iops (dict): input-output-parameters for Act """ m = mods # alias more compact @@ -1155,7 +1155,7 @@ def at(self, nabe: str=Nabes.native, *, mods: WorkDom|None=None)->str: Parameters:: - nabe (str): action nabe (context) for mods. Defualt is native + nabe (str): action nabe (context) for mods. Default is native mods (None | WorkDom): state variables used to construct box work None is just to allow definition as keyword arg. Assumes in @@ -1174,11 +1174,11 @@ def be(self, lhs: str|tuple[str], rhs: None|str|Callable=None, nabe=None, *, name: str|None=None, mods: WorkDom|None=None, **iops)->str: """Make Beact instance that assigns mine bag at lhs to value from rhs. lhs is of form "key.field" - rhs may be either a Callable or an evalable expression or None. + rhs may be either a Callable or an evaluable expression or None. Resulting act performs one of:: H.key.field = None when rhs is None - H.key.field = eval(rhs) when rhs is evalable str + H.key.field = eval(rhs) when rhs is evaluable str H.key.field = rhs(``**parms``) when rhs is callable Usage:: @@ -1191,7 +1191,7 @@ def be(self, lhs: str|tuple[str], rhs: None|str|Callable=None, nabe=None, *, Resolves lhs to (key, field) rhs (None|str|Callable): When None assign directly - When str compile to evable expression + When str compiles to evaluable expression When Callable then call directly with iops nabe (None|str): action nabe (context) for act instance created by do. None means use nabe from mods. @@ -1200,7 +1200,7 @@ def be(self, lhs: str|tuple[str], rhs: None|str|Callable=None, nabe=None, *, mods (None | WorkDom): state variables used to construct box work None is just to allow definition as keyword arg. Assumes in actual usage that mods is always provided as WorkDom instance. - iops (dict): input-output-parms for Beact + iops (dict): input-output-parameters for Beact """ m = mods # alias more compact @@ -1251,7 +1251,7 @@ def exen(near, far): rendos is list of common boxes in both nears and fars to be re-entered These are boxes retained in pile. The sets of boxes in rexdos and rendos are the same set but rexdos - is reversed to bottum up order. These are boxes retained in the + is reversed to bottom up order. These are boxes retained in the pile before and after the transition. This is where common exdo/endo actions for the non-common boxes can be actioned non-redundantly. @@ -1418,23 +1418,23 @@ class BoxerDoer(Doer): Inherited Methods:: - .wind injects ._tymth dependency from associated Tymist to get its .tyme - .__call__ makes instance callable - Appears as generator function that returns generator - .do is generator method that returns generator - .enter is enter context action method - .recur is recur context action method or generator method - .exit is exit context method - .close is close context method - .abort is abort context method + - wind: injects ._tymth dependency from associated Tymist to get its .tyme + - __call__: makes instance callable. Appears as generator function + that returns generator + - do: is generator method that returns generator + - enter: is enter context action method + - recur: is recur context action method or generator method + - exit: is exit context method + - close: is close context method + - abort: is abort context method Attributes:: boxer (Boxer): boxwork instance this doer runs - Overidden Methods:: + Overridden Methods:: - .recur + - recur Hidden:: diff --git a/src/hio/base/hier/canning.py b/src/hio/base/hier/canning.py index 27794d7f..97d6ea5c 100644 --- a/src/hio/base/hier/canning.py +++ b/src/hio/base/hier/canning.py @@ -39,9 +39,8 @@ class CanDom(TymeDom): Tymist.tyme. Provides injected dependency on Tymist cycle tyme base. None means not assigned yet. Use ._wind method to assign ._tymth after init of bag. - _tyme (None|Float): cycle tyme of last update of a bag field. - None means either ._tymth as not yet been assigned or this bag's - fields have not yet been updated. + _tyme (None|Float): cycle tyme of last update of a bag field; + None means either ._tymth has not yet been assigned or this bag fields have not yet been updated. Inherited Properties:: @@ -50,19 +49,16 @@ class CanDom(TymeDom): Properties:: _durable (bool): True means ._sdb and ._key and ._sdb.db and - .sdb.db.opened are not None - False otherwise + ._sdb.db.opened are not None + False otherwise Non-Field Attributes:: _sdb (DomSuber|None): SuberBase subclass instance of durable subdb of Duror _key (str|None): database key used to store serialized field in ._cans - _stale (bool): True means fields not yet been synced by write/read with durable - False means fields have been synced by write/read with durable - _fresh (bool): True means fields being synced by read from durable - False means fields not being synced by read from durable - _bulk (bool): True means do not write individual fields wait for bulk update - False means write individual fields as updated + _stale (bool): True means fields not yet been synced by write/read with durable; False means fields have been synced by write/read with durable + _fresh (bool): True means fields being synced by read from durable; False means fields not being synced by read from durable + _bulk (bool): True means do not write individual fields and wait for bulk update; False means write individual fields as updated """ _sdb: InitVar[None|DomSuber] = None # durable storage of serialized fields @@ -139,8 +135,8 @@ def _durable(self): Returns:: durable (bool): True means ._sdb and ._key and ._sdb.db and - .sdb.db.opened are not None - False otherwise + ._sdb.db.opened are not None + False otherwise """ return (self._sdb is not None and self._key is not None and self._sdb.db and self._sdb.db.opened) @@ -167,7 +163,7 @@ def _sync(self, force=False): Parameters:: force (bool): True means force read even if not ._stale - Flase means do not force read + False means do not force read """ if self._durable and (self._stale or force): if can := self._sdb.get(self._key): # not empty @@ -206,17 +202,13 @@ class Can(CanDom): Tymist.tyme. Provides injected dependency on Tymist cycle tyme base. None means not assigned yet. Use ._wind method to assign ._tymth after init of bag. - _tyme (None|Float): cycle tyme of last update of a bag field. - None means either ._tymth as not yet been assigned or this bag's - fields have not yet been updated. - _sdb (DomSuber|None): SuberBase subclass instance of durable subdb of Duror - _key (str|None): database key used to store serialized field in ._cans + + Additional inherited non-field attributes include _tyme (last field-update tyme), _sdb (durable subdb instance), and _key (storage key in ._cans). Inherited Properties:: _now (None|float): current tyme given by ._tymth if not None. - _durable (bool): True means ._sdb and ._key are not None - False otherwise + _durable (bool): True means ._sdb and ._key are not None; False otherwise Field Attributes:: diff --git a/src/hio/base/hier/durqing.py b/src/hio/base/hier/durqing.py index 380c4486..7b7e0a54 100644 --- a/src/hio/base/hier/durqing.py +++ b/src/hio/base/hier/durqing.py @@ -17,31 +17,25 @@ class Durq(): .sdb and .key will store its ordered list durably and allow access as a FIFO queue - Properties:: - - stale (bool): True means in-memory and durable on disk not synced - False means in-memory and durable on disk synced + Properties: + stale (bool): True means in-memory and durable on disk not synced. + False means in-memory and durable on disk synced. durable (bool): True means ._sdb and ._key and ._sdb.db and - .sdb.db.opened are not None - False otherwise - + ._sdb.db.opened are not None. + False otherwise. - Hidden:: - - _deq (deque): in-memory cache as deque + Hidden: + _deq (deque): in-memory cache as deque _sdb (DomIoSuber): instance of durable store _key (str): into .sdb - _stale (bool): for .stale property: - True means in-memory and durable on disk not synced - False means in-memory and durable on disk synced + _stale (bool): stale-status cache for .stale property. """ def __init__(self, *pa): """Initialize instance - Parameters:: - - pa[0] (NonStringeIteralble[RegDom]): instances to preload self._deq + Parameters: + pa[0] (NonStringIterable[hio.help.doming.RegDom]): instances to preload self._deq """ self._deq = deque() @@ -81,10 +75,8 @@ def __len__(self): def stale(self): """Getter for ._stale - Returns:: - - stale (bool): True means in-memory and durable on disk not synced - False means in-memory and durable on disk synced + Returns: + stale (bool): True means in-memory and durable on disk not synced; False means in-memory and durable on disk synced """ return self._stale @@ -95,8 +87,8 @@ def durable(self): Returns:: durable (bool): True means ._sdb and ._key and ._sdb.db and - .sdb.db.opened are not None - False otherwise + ._sdb.db.opened are not None + False otherwise """ return (self._sdb is not None and self._key is not None and self._sdb.db and self._sdb.db.opened) @@ -104,7 +96,7 @@ def durable(self): def extend(self, vals: NonStringIterable[RegDom|IceRegDom]): """Extend ._deq with vals - Peforms equivalent operation on durable .sdb at .key if any + Performs equivalent operation on durable .sdb at .key if any """ if not vals: @@ -123,11 +115,10 @@ def extend(self, vals: NonStringIterable[RegDom|IceRegDom]): def push(self, val: RegDom|IceRegDom): """If not None, add val to last in. Otherwise ignore - Peforms equivalent operation on durable .sdb at .key if any - - Parameters:: + Performs equivalent operation on durable .sdb at .key if any - val (RegDom): element to be appended to deck (deque) + Parameters: + val (hio.help.doming.RegDom): element to be appended to deck (deque) """ if val is not None: if not isinstance(val, (RegDom, IceRegDom)): @@ -145,7 +136,7 @@ def pull(self, emptive=True): """Remove and return first in value If empty and emptive return None else raise IndexError - Peforms equivalent operation on durable .sdb at .key if any + Performs equivalent operation on durable .sdb at .key if any Parameters:: @@ -172,7 +163,7 @@ def pull(self, emptive=True): def clear(self): """Clear all values from deque - Peforms equivalent operation on durable .sdb at .key if any + Performs equivalent operation on durable .sdb at .key if any """ prior = len(self._deq) @@ -250,7 +241,7 @@ def sync(self, force=False): Parameters:: force (bool): True means force read even if not ._stale - Flase means do not force read + False means do not force read """ if self.durable and (self.stale or force): if self._sdb.cnt(self._key): # not empty diff --git a/src/hio/base/hier/dusqing.py b/src/hio/base/hier/dusqing.py index 82bda13c..4bc7cb02 100644 --- a/src/hio/base/hier/dusqing.py +++ b/src/hio/base/hier/dusqing.py @@ -17,32 +17,26 @@ class Dusq(): .sdb and .key will store its ordered set durably and allow access as a deduped FIFO queue. A set is deduped. - Properties:: - - stale (bool): True means in-memory and durable on disk not synced - False means in-memory and durable on disk synced + Properties: + stale (bool): True means in-memory and durable on disk not synced. + False means in-memory and durable on disk synced. durable (bool): True means ._sdb and ._key and ._sdb.db and - .sdb.db.opened are not None - False otherwise - - - Hidden:: + ._sdb.db.opened are not None. + False otherwise. - _oset (oset): in-memory cache as ordered set + Hidden: + _oset (oset): in-memory cache as ordered set _sdb (DomIoSuber): instance of durable store _key (str): into .sdb - _stale (bool): for .stale property: - True means in-memory and durable on disk not synced - False means in-memory and durable on disk synced + _stale (bool): stale-status cache for .stale property. """ def __init__(self, *pa): """Initialize instance - Parameters:: - - pa[0] (NonStringeIteralble[RegDom]): instances to preload self._oset + Parameters: + pa[0] (NonStringIterable[hio.help.doming.RegDom]): instances to preload self._oset """ self._oset = oset() @@ -70,7 +64,7 @@ def __repr__(self): def __iter__(self): - """Makes iterator out of self by returning iterable ._deq""" + """Makes iterator out of self by returning iterable ._oset""" return iter(tuple(val if val.__dataclass_params__.frozen else deepcopy(val) for val in self._oset)) # ensure not mutable outside #return iter(self._oset) @@ -84,10 +78,8 @@ def __len__(self): def stale(self): """Getter for ._stale - Returns:: - - stale (bool): True means in-memory and durable on disk not synced - False means in-memory and durable on disk synced + Returns: + stale (bool): True means in-memory and durable on disk not synced; False means in-memory and durable on disk synced """ return self._stale @@ -98,20 +90,19 @@ def durable(self): Returns:: durable (bool): True means ._sdb and ._key and ._sdb.db and - .sdb.db.opened are not None - False otherwise + ._sdb.db.opened are not None + False otherwise """ return (self._sdb is not None and self._key is not None and self._sdb.db and self._sdb.db.opened) def update(self, vals: NonStringIterable[RegDom|IceRegDom], *, deep=True): - """Update ._deq with vals - Peforms equivalent operation on durable .sdb at .key if any - - Parameters:: + """Update ._oset with vals + Performs equivalent operation on durable .sdb at .key if any - vals (NonStringIterable[RegDom]): to add to dusq + Parameters: + vals (NonStringIterable[hio.help.doming.RegDom]): to add to dusq deep (bool): True means deepcopy to ensure can't mutate outside False means do not deepcopy @@ -134,11 +125,10 @@ def update(self, vals: NonStringIterable[RegDom|IceRegDom], *, deep=True): def push(self, val: RegDom|IceRegDom): """If not None, add val add val to last in if unique. Otherwise ignore - Peforms equivalent operation on durable .sdb at .key if any - - Parameters:: + Performs equivalent operation on durable .sdb at .key if any - val (RegDom): element to be appended to deck (deque) + Parameters: + val (hio.help.doming.RegDom): element to be appended to deck (deque) """ if val is not None: if not isinstance(val, (RegDom, IceRegDom)): @@ -160,7 +150,7 @@ def pull(self, emptive=True): """Remove and return first in val If empty and emptive return None else raise IndexError - Peforms equivalent operation on durable .sdb at .key if any + Performs equivalent operation on durable .sdb at .key if any Parameters:: @@ -188,7 +178,7 @@ def pull(self, emptive=True): def clear(self): """Clear all values - Peforms equivalent operation on durable .sdb at .key if any + Performs equivalent operation on durable .sdb at .key if any """ prior = len(self._oset) self._oset.clear() @@ -210,7 +200,7 @@ def remove(self, value: RegDom|IceRegDom): result (bool): True value was removed Raises KeyError if value not found - Peforms equivalent operation on durable .sdb at .key if any + Performs equivalent operation on durable .sdb at .key if any """ if not isinstance(val, (RegDom, IceRegDom)): raise HierError(f"Expected RegDom instance got {val}") @@ -265,12 +255,12 @@ def cnt(self): def pin(self): - """Pins all of ._deq to ._sdb at ._key if any. + """Pins all of ._oset to ._sdb at ._key if any. Sets ._stale to False on success """ if self.durable: vals = [val for val in self._oset] - self._sdb.pin(self._key, vals) # pin sdb._ser to ._deq vals + self._sdb.pin(self._key, vals) # pin sdb._ser to ._oset vals self._stale = False return True return None @@ -283,7 +273,7 @@ def sync(self, force=False): Parameters:: force (bool): True means force read even if not ._stale - Flase means do not force read + False means do not force read """ if self.durable and (self.stale or force): if self._sdb.cnt(self._key): # not empty diff --git a/src/hio/base/hier/hogging.py b/src/hio/base/hier/hogging.py index a8771c2b..d8398ae5 100644 --- a/src/hio/base/hier/hogging.py +++ b/src/hio/base/hier/hogging.py @@ -49,10 +49,8 @@ class Hog(ActBase, Filer): HeadDirPath (str): default abs dir path head such as "/usr/local/var" TailDirPath (str): default rel dir path tail when using head CleanTailDirPath (str): default rel dir path tail when creating clean - AltHeadDirPath (str): default alt dir path head such as "~" - as fallback when desired head not permitted. - AltTailDirPath (str): default alt rel dir path tail as fallback - when using alt head. + AltHeadDirPath (str): default alt dir path head such as "~"; fallback when desired head not permitted. + AltTailDirPath (str): default alt rel dir path tail as fallback when using alt head. AltCleanTailDirPath (str): default alt rel path tail when creating clean TempHeadDir (str): default temp abs dir path head such as "/tmp" TempPrefix (str): default rel dir path prefix when using temp head @@ -61,41 +59,27 @@ class Hog(ActBase, Filer): Mode (str): open mode such as "r+" Fext (str): default file extension such as "text" for "fname.text" - Class Attributes:: - - ReservedTags (dict[str]): of reserved tags to protect from collision with - defined parameter names that may not be used for - log tags when using ``**kwa`` to provide hold - log leys. Uses dict since inclusion test is - faster than with list - - Inherited Attributes see Act, File:: + Class Attributes: + ReservedTags (dict[str]): reserved tags that prevent collisions with defined parameter names; these may not be used for log tags when using ``**kwa`` to provide hold log keys. Uses dict because inclusion test is faster than list. + Inherited Attributes (see Act, File): hold (Hold): data shared by boxwork - name (str): overriden by .name property from Act (see name property) + name (str): overridden by .name property from Act (see name property) base (str): another unique path component inserted before name temp (bool): True means use TempHeadDir in /tmp directory headDirPath (str): head directory path path (str | None): full directory or file path once created else None perm (int): octal OS permissions for path directory and/or file - filed (bool): True means .path ends in file. - False means .path ends in directory - extensioned (bool): When not filed: - True means ensure .path ends with fext - False means do not ensure .path ends with fext + filed (bool): True means .path ends in file; False means .path ends in directory + extensioned (bool): When not filed, True means ensure .path ends with fext; False means do not ensure .path ends with fext mode (str): file open mode if filed fext (str): file extension if filed file (File | None): File instance when filed and created. - opened (bool): True means directory created and if filed then file - is opened. False otherwise - + opened (bool): True means directory is created and, if filed, file is opened; False otherwise - Inherited Properties see Act, File:: - - name (str): unique name string of instance used for registering Act - instance in Act registry as well providing a unique path - component used in file path name + Inherited Properties (see Act, File): + name (str): unique instance name used for registering Act instance in Act registry and providing a unique path component in file path name iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act @@ -106,44 +90,43 @@ class Hog(ActBase, Filer): False means logging has not yet begun needs header first (float|None): tyme when began logging, None means not yet running last (float|None): tyme when last logged, None means not yet running - realtime equiv of last = began + (last - first) + realtime equiv of last = began + (last - first) rule (str): condition for log to fire one of Rules (once, every, span, update, change) - span (float): tyme span seconds for periodic logging 0.0 means everytyme + span (float): tyme span seconds for periodic logging 0.0 means every tyme onced (bool): True means logged at least one (first) record False means not yet logged one (first) record header (str): header for log file(s) rid (str): universally unique run ID for given run of hog flushSpan (float): tyme span seconds between flushes (flush) - 0.0 means everytyme + 0.0 means every tyme flushForce (bool): True means force flush on every log - False means only flush at appropriate times + False means only flush at appropriate times flushLast (float|None): tyme last flushed, None means not yet running cycleCount (int): number of cycled logs, 0 means do not cycle (count) cyclePeriod (float): min tyme span for cycling logs (cycle). 0.0 means - cycle based on cycleHigh not tyme span. One of - cycleSpan or cycleHigh must be non zero + cycle based on cycleHigh not tyme span. One of cycleSpan or + cycleHigh must be non zero cycleSize (int): maximum size in bytes allowed for each cycled log - 0 means no maximum. One of cycleSpan or cycleHigh must - be non zero + 0 means no maximum. One of cycleSpan or cycleHigh must be non zero cyclePaths (list[str]): paths for cycled logs cycleLast (float|None): tyme last cycled. None means not yet running hits (dict): hold items to log. Item label is log header tag - Item value is hold key that provides value to log + Item value is hold key that provides value to log marks (dict): tyme or value tuples marks of hold items logged with - updated or changed rule. Label is hold key. + updated or changed rule. Label is hold key. activeKey (str|None): hold key to active box name of boxer given by iops - None otherwise + None otherwise tockKey (str|None): hold key to tock value of boxer given by iops - None otherwise - tockKey (str|None): hold key to tyme value of boxer given by iops - None otherwise + None otherwise + tymeKey (str|None): hold key to tyme value of boxer given by iops + None otherwise Hidden:: _name (str): unique name of instance for .name property - _iopts (dict): input-output-paramters for .act for .iops property + _iopts (dict): input-output-parameters for .act for .iops property _nabe (str): action nabe (context) for .act for .nabe property @@ -152,15 +135,15 @@ class Hog(ActBase, Filer): So opening file during init is compatible as its in the enter context of the its Doer even though its not in the endo context of its box. It still needs to be closed. Unlike the hold subery the Boxer doesn't know - about any Hogs runing as acts inside its boxes so can't close in its BoxerDoer - exit context. So much be closed inside with a close do act + about any Hogs running as acts inside its boxes so can't close in its BoxerDoer + exit context. So must be closed inside with a close do act Since filed it should reopen without truncating so does not overwrite existing log file of same name so uses mode = 'a+'. Need to test reopen logic Always rewrites header on first log after restart which may have changed log behavior so header demarcation enables recognition of log parameters. - Log header includes rid (unique run id) and datatime stamp so can always + Log header includes rid (unique run id) and datetime stamp so can always uniquely match a given run data to header even when reusing same log file. This is most important when rotating logs. Because each individual log record after header always starts with tyme as @@ -211,7 +194,7 @@ def __init__(self, iops=None, nabe=Nabes.afdo, base="", filed=True, hold (None|Hold): data shared across boxwork base (str): optional directory path segment inserted before name - that allows further differentation with a hierarchy. "" means + that allows further differentiation with a hierarchy. "" means optional. temp (bool): assign to .temp True then open in temporary directory, clear on close @@ -229,7 +212,7 @@ def __init__(self, iops=None, nabe=Nabes.afdo, base="", filed=True, clean (bool): True means path uses clean tail variant False means path uses normal tail variant filed (bool): True means .path is file path not directory path - False means .path is directiory path not file path + False means .path is directory path not file path extensioned (bool): When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext @@ -249,12 +232,12 @@ def __init__(self, iops=None, nabe=Nabes.afdo, base="", filed=True, flushForce (bool): True means force flush on every log False means only flush at appropriate times cycleCount (int): number of cycled logs, 0 means do not cycle - cycleSapn (float): cycle tyme span, tyme between log cycles + cycleSpan (float): cycle tyme span, tyme between log cycles cycleSize (int): maximum size in bytes allowed for each cycled log 0 means no maximum hits (None|dict): hold items to log. Item label is log header tag Item value is hold key that provides value to log - None means use unreserved items in ``**kwa`` wrt .ReservedTags + None means use unreserved items in ``**kwa`` with respect to .ReservedTags When made (created and inited) by boxer.do then have "_boxer" and @@ -335,12 +318,12 @@ def __init__(self, iops=None, nabe=Nabes.afdo, base="", filed=True, def act(self, **iops): """Act called by ActBase. - Parameters:: - iops (dict): input/output parms, same as self.iops. Puts ``**iops`` in - local scope in case act compliles exec/eval str + Parameters: + iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in + local scope in case act compiles exec/eval str When made by boxer.do then have "_boxer" and "_box" keys in self.iops - iops = ``dict(_boxer=self.name, _box=m.box.name, **iops)`` + iops = ``dict(_boxer=self.name, _box=m.box.name, **iops)`` """ if not self.started: @@ -479,7 +462,7 @@ def log(self, record, tyme, force=False): def record(self): - """Generate on record line .hits values from .hold + """Generate one record line from .hits values from .hold Returns:: diff --git a/src/hio/base/hier/holding.py b/src/hio/base/hier/holding.py index 869464d5..3eb6eb08 100644 --- a/src/hio/base/hier/holding.py +++ b/src/hio/base/hier/holding.py @@ -50,9 +50,8 @@ class Hold(Mine): subery (None|Subery): gets instance from item at '_hold_subery' or None - Methods:: - - inject(self, key, val): injects .cans into val._sdb and key into val._key + Methods: + - inject: injects .cans into val._sdb and key into val._key """ diff --git a/src/hio/base/hier/needing.py b/src/hio/base/hier/needing.py index 3428cc0e..9b609b41 100644 --- a/src/hio/base/hier/needing.py +++ b/src/hio/base/hier/needing.py @@ -25,62 +25,34 @@ class Need(Mixin): hold (Hold): data shared by boxwork - Properties:: + Properties: + expr (str): evaluable boolean expression. + compiled (bool): True means ._code holds compiled ._expr; False means not yet compiled - expr (str): evalable boolean expression. - compiled (bool): True means ._code holds compiled ._expr - False means not yet compiled + Hidden: + _expr (str): evaluable boolean expression. + _code (None|CodeType): compiled evaluable boolean expression .expr; None means not yet compiled from .expr - Hidden:: - _expr (str): evalable boolean expression. - _code (None|CodeType): compiled evalable boolean expression .expr - None means not yet compiled from .expr + Compilation Notes: + The need returned by an ``on()`` call keeps the string expression because + compiled code objects are not pickleable. In multiprocessing, the child + process recompiles the expression from the string form. Keeping the string + representation also helps debugging and introspection. + Expression Syntax Notes: + ``H`` is a local reference to ``self.hold`` during evaluation. Need + expressions can use dotted hold paths directly, for example, + ``H.root_dog.value``. This is equivalent to either + ``self.hold["root_dog"].value`` or ``self.hold[("root", "dog")].value``. - Compilation Notes:: - - c = compile("True", '', 'eval') - c - at 0x1042f2250, file "", line 1> - type(c) - - import types - isinstance(c, types.CodeType) - True - - import pickle - s = pickle.dumps(c) - builtins.TypeError: cannot pickle code objects - - eval(c) - True - - So the need returned by an on() call must keep around the string - representation for multiprocessing because the code object itself is not - pickleable and must be recompiled inside the child process. - Also having the string rep around can be helpful in debugging if define - __repr__ and __str__ for need objects. - - Expr syntax notes:: - - H (Hold) shared data syntax with locally scope variables H ref for .hold - - so need syntax does not heed to "quote" paths keys into the bags - containers Hold dict subclass with attribute and durable support. - - H.root_dog.value is equivalent to self.hold["root_dog"].value or - self.hold[("root", "dog")].value - - So need term "H.root_dog.value > 5" should compile directly and eval - as long as H is in the locals() and H is a Hold instance. - - So no need to do substitutions or shorthand - The hierarchy in the .hold is indicated by '_' separated keys - The Box Boxer Actor names are forbidden from having '_" as an element - with Renam regex test. + The expression ``H.root_dog.value > 5`` compiles and evaluates directly + as long as ``H`` is present in locals and references a ``Hold`` instance. + No substitution shorthand is required. Hierarchy in ``.hold`` uses + underscore-separated keys, so Box/Boxer/Actor names may not contain + ``_`` (enforced by the ``Renam`` regex). """ @@ -88,9 +60,8 @@ class Need(Mixin): def __init__(self, *, expr='True', hold=None, **kwa): """Initialization method for instance. - Parameters:: - - expr (str): evalable boolean expression. + Parameters: + expr (str): evaluable boolean expression. if empty or None then use default = 'True' hold (None|Hold): data shared by boxwork """ @@ -103,9 +74,8 @@ def __init__(self, *, expr='True', hold=None, **kwa): def __call__(self, **iops): """Make Need instance a callable object. - Parameters:: - - iops (dict): run time input output parms for need. + Parameters: + iops (dict): run time input output parameters for need. Usually provided when need is Act deed. """ @@ -119,9 +89,8 @@ def __call__(self, **iops): def expr(self): """Property getter for ._expr - Returns:: - - expr (str): evalable boolean expression. + Returns: + expr (str): evaluable boolean expression. """ return self._expr @@ -130,9 +99,8 @@ def expr(self): def expr(self, expr): """Property setter for ._expr - Parameters:: - - expr (str): evalable boolean expression. + Parameters: + expr (str): evaluable boolean expression. """ self._expr = expr if expr else 'True' self._code = None # force lazy recompilation @@ -151,7 +119,7 @@ def compiled(self): def compile(self): - """Compile evable boolean expression str ._expr into compiled code + """Compile evaluable boolean expression str ._expr into compiled code object ._code to be evaluated at run time. Because code objects are not pickleable the compilation must happen at prep (enter) time not init time. diff --git a/src/hio/base/multidoing.py b/src/hio/base/multidoing.py index ec4453cb..3af3c1bf 100644 --- a/src/hio/base/multidoing.py +++ b/src/hio/base/multidoing.py @@ -24,10 +24,9 @@ from . import tyming from .doing import Doist, Doer from .. import hioing -from .. import help from ..help import ogling, timing, helping, Namer, RawDom, IceMapDom -from ..core.uxd import PeerMemoer +from ..core.uxd.peermemoing import PeerMemoer ogler = ogling.initOgler(prefix='hio_mp', name="Boss", level=logging.ERROR) @@ -44,7 +43,7 @@ # Loadage (namedtuple): # Bosser info to be injected into Crewer .start() containing both crew doist -# parms for Process target kwargs and and Crewer parms. +# parameters for Process target kwargs and Crewer parameters. # # Fields: # name (str): child doist identifier for resources @@ -307,22 +306,22 @@ class MultiDoerBase(Namer, PeerMemoer, Doer): Inherited Methods:: - __call__() makes instance callable as generator function returning generator - do() generator method that returns generator - enter() is enter context action method - recur() recur context action method or generator method - clean() clean context action method - exit() exit context method - close() close context method - abort() abort context method - wind() injects ._tymth dependency from associated Tymist to get its .tyme - clearAllNameAddr() - getAddr(name) - getName(addr) - addNameAddr(name, addr) - remNameAddr(name=None, addr=None) - changeAddrAtName(name=None, addr=None) - changeNameAtAddr(addr=None, name=None) + - __call__(): makes instance callable as generator function returning generator + - do(): generator method that returns generator + - enter(): is enter context action method + - recur(): recur context action method or generator method + - clean(): clean context action method + - exit(): exit context method + - close(): close context method + - abort(): abort context method + - wind(): injects ._tymth dependency from associated Tymist to get its .tyme + - clearAllNameAddr() + - getAddr(name) + - getName(addr) + - addNameAddr(name, addr) + - remNameAddr(name=None, addr=None) + - changeAddrAtName(name=None, addr=None) + - changeNameAtAddr(addr=None, name=None) """ Tagex = TagDex @@ -352,7 +351,7 @@ def __init__(self, *, name='base', temp=False, reopen=False, bc=4, **kwa): **kwa) self.logger = None # assign later from ogler in enter time/scope - self.graceful = False # indiction by .force signal handler to exit on next recur + self.graceful = False # indication by .force signal handler to exit on next recur @@ -377,13 +376,13 @@ def enter(self, *, temp=None): """ self.logger = ogler.getLogger() # uses ogler in enter scope - signal.signal(signal.SIGINT, self.force) # register signal handers - signal.signal(signal.SIGTERM, self.force) # register signal handers + signal.signal(signal.SIGINT, self.force) # register signal handlers + signal.signal(signal.SIGTERM, self.force) # register signal handlers def recur(self, tyme): """Do 'recur' context. - Must be overidden in subclass + Must be overridden in subclass """ if self.graceful: # signal handler.force caught signal so exit here sys.exit() @@ -440,8 +439,8 @@ class Bosser(MultiDoerBase): Attributes:: loads (list[dict]): Bosser info to be injected into Crewer .start() - containing both crew doist parmss for Process target - kwargs and and Crewer parms + containing both crew doist parameters for Process target + kwargs and Crewer parameters (see Loadage._asdict() or CrewDom._asdict()) ctx (mp.context.SpawnContext or None): context under which to spawn processes crew (dict): values HandDom instances keyed by name diff --git a/src/hio/base/tyming.py b/src/hio/base/tyming.py index 1929355e..e25d19ab 100644 --- a/src/hio/base/tyming.py +++ b/src/hio/base/tyming.py @@ -22,16 +22,16 @@ class Tymist(hioing.Mixin): .tyme may be synchronized with real time by a .tyme manager Class Attributes: - .Tock is default .tock + Tock: default .tock Attributes: Properties: - .tyme is float relative cycle time, .tyme is artificial time - .tock is float tyme increment of .tick() + tyme: float relative cycle time, .tyme is artificial time + tock: float tyme increment of .tick() Methods: - .tick increments .tyme by one .tock or provided tock + tick method increments .tyme by one .tock or provided tock """ Tock = 0.03125 # 1/32 @@ -119,7 +119,7 @@ class Tymee(hioing.Mixin): None means not assigned yet. Methods: - .wind injects ._tymth dependency from associated Tymist to get its .tyme + - wind: injects ._tymth dependency from associated Tymist to get its .tyme Hidden: _tymth is injected function wrapper closure returned by .tymen() of @@ -183,13 +183,13 @@ class Tymer(Tymee): Inherited attributes and properties are documented on Tymee. - Properties: + Properties: - duration (float): tyme duration in seconds from ._start to ._stop. - elapsed (float): tyme elapsed in seconds since ._start. - remaining (float): tyme remaining in seconds until ._stop. - expired (bool): True if expired (.tyme >= ._stop). - Hidden attributes: _tymth, _start, _stop. + Hidden attributes: _tymth, _start, _stop. """ Duration = 0.0 # default duration when not provided