From 672eea1b70132d5838508367fca618063b048b9f Mon Sep 17 00:00:00 2001 From: Jay-Alexander Elliot Date: Fri, 13 Mar 2026 14:53:43 -0600 Subject: [PATCH] Fix docstrings in hier small modules --- src/hio/base/hier/bagging.py | 26 ++++++++----- src/hio/base/hier/canning.py | 34 ++++++++++------ src/hio/base/hier/durqing.py | 26 ++++++++----- src/hio/base/hier/dusqing.py | 31 +++++++++------ src/hio/base/hier/hiering.py | 11 +++--- src/hio/base/hier/hogging.py | 75 ++++++++++++++++++++++-------------- src/hio/base/hier/holding.py | 27 ++++++------- src/hio/base/hier/needing.py | 31 +++++++++------ 8 files changed, 161 insertions(+), 100 deletions(-) diff --git a/src/hio/base/hier/bagging.py b/src/hio/base/hier/bagging.py index 835a6739..e9d643a0 100644 --- a/src/hio/base/hier/bagging.py +++ b/src/hio/base/hier/bagging.py @@ -35,13 +35,15 @@ class IceBag(IceTymeDom): Frozen dataclass do not allow change or upate of either field or non-field attributes after __init__ this includes in the __post_init__ method. - Inherited Non-Field Class Attributes: + Inherited Non-Field Class Attributes:: + _registry (ClassVar[dict]): dict of subclasses keyed by class.__name__ Assigned by @registerify decorator _names (ClassVar[tuple[str]|None]): tuple of field names for class Assigned by @namify decorator - Inherited Properties: + Inherited Properties:: + _tymth (None|Callable): Emulates interface for non-frozen TymeDom Returns None _tyme (None|Float): Emulates interface for non-frozen TymeDom @@ -49,8 +51,9 @@ class IceBag(IceTymeDom): _now (None|float): Emulates interface for non-frozen TymeDom Returns None - Field Attributes: - value (Any): generic value field + Field Attributes:: + + value (Any): generic value field """ value: Any = None # generic value @@ -72,13 +75,15 @@ class Bag(TymeDom): may a frozen dataclass be a subclass of a frozen dataclass. - Inherited Non-Field Class Attributes: + Inherited Non-Field Class Attributes:: + _registry (ClassVar[dict]): dict of subclasses keyed by class.__name__ Assigned by @registerify decorator _names (ClassVar[tuple[str]|None]): tuple of field names for class Assigned by @namify decorator - Inherited Non-Field Attributes: + Inherited Non-Field Attributes:: + _tymth (None|Callable): function wrapper closure returned by Tymist.tymen() method. When .tymth is called it returns associated Tymist.tyme. Provides injected dependency on Tymist cycle tyme base. @@ -88,11 +93,13 @@ class Bag(TymeDom): None means either ._tymth as not yet been assigned or this bag's fields have not yet been updated. - Inherited Properties: + Inherited Properties:: + _now (None|float): current tyme given by ._tymth if not None. - Field Attributes: - value (Any): generic value field + Field Attributes:: + + value (Any): generic value field """ value: Any = None # generic value @@ -103,4 +110,3 @@ def __hash__(self): in every subclass """ return hash((self.__class__.__name__,) + self._astuple()) # almost same as __eq__ - diff --git a/src/hio/base/hier/canning.py b/src/hio/base/hier/canning.py index f8219e67..27794d7f 100644 --- a/src/hio/base/hier/canning.py +++ b/src/hio/base/hier/canning.py @@ -25,13 +25,15 @@ class CanDom(TymeDom): only. Assignment to Hold instance at key, injects ._sdb and ._key. This makes the in-memory key in Hold and the durable key the same. - Inherited Non-Field Class Attributes: + Inherited Non-Field Class Attributes:: + _registry (ClassVar[dict]): dict of subclasses keyed by class.__name__ Assigned by @registerify decorator _names (ClassVar[tuple[str]|None]): tuple of field names for class Assigned by @namify decorator - Inherited Non-Field Attributes: + Inherited Non-Field Attributes:: + _tymth (None|Callable): function wrapper closure returned by Tymist.tymen() method. When .tymth is called it returns associated Tymist.tyme. Provides injected dependency on Tymist cycle tyme base. @@ -41,15 +43,18 @@ class CanDom(TymeDom): None means either ._tymth as not yet been assigned or this bag's fields have not yet been updated. - Inherited Properties: + Inherited Properties:: + _now (None|float): current tyme given by ._tymth if not None. - Properties: + Properties:: + _durable (bool): True means ._sdb and ._key and ._sdb.db and .sdb.db.opened are not None False otherwise - Non-Field Attributes: + 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 @@ -131,7 +136,8 @@ def _update(self, *pa, **kwa): def _durable(self): """Property durable True when durable subdb injected and opened. - Returns: + Returns:: + durable (bool): True means ._sdb and ._key and ._sdb.db and .sdb.db.opened are not None False otherwise @@ -158,7 +164,8 @@ def _sync(self, force=False): Toggles ._fresh during read so can update own fields from read without triggering a write. - Parameters: + Parameters:: + force (bool): True means force read even if not ._stale Flase means do not force read """ @@ -185,13 +192,15 @@ class Can(CanDom): """CanDom is base class that adds support for durable storage via its ._cans non-field attribute - Inherited Non-Field Class Attributes: + Inherited Non-Field Class Attributes:: + _registry (ClassVar[dict]): dict of subclasses keyed by class.__name__ Assigned by @registerify decorator _names (ClassVar[tuple[str]|None]): tuple of field names for class Assigned by @namify decorator - Inherited Non-Field Attributes: + Inherited Non-Field Attributes:: + _tymth (None|Callable): function wrapper closure returned by Tymist.tymen() method. When .tymth is called it returns associated Tymist.tyme. Provides injected dependency on Tymist cycle tyme base. @@ -203,12 +212,14 @@ class Can(CanDom): _sdb (DomSuber|None): SuberBase subclass instance of durable subdb of Duror _key (str|None): database key used to store serialized field in ._cans - Inherited Properties: + 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 - Field Attributes: + Field Attributes:: + value (Any): generic value field """ value: Any = None # generic value @@ -220,4 +231,3 @@ def __hash__(self): in every subclass """ return hash((self.__class__.__name__,) + self._astuple()) # almost same as __eq__ - diff --git a/src/hio/base/hier/durqing.py b/src/hio/base/hier/durqing.py index bfd2333e..380c4486 100644 --- a/src/hio/base/hier/durqing.py +++ b/src/hio/base/hier/durqing.py @@ -17,7 +17,8 @@ class Durq(): .sdb and .key will store its ordered list durably and allow access as a FIFO queue - Properties + 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 @@ -25,7 +26,8 @@ class Durq(): False otherwise - Hidden: + Hidden:: + _deq (deque): in-memory cache as deque _sdb (DomIoSuber): instance of durable store _key (str): into .sdb @@ -37,8 +39,9 @@ class Durq(): def __init__(self, *pa): """Initialize instance - Parameters: - pa[0] (NonStringeIteralble[RegDom]): instances to preload self._deq + Parameters:: + + pa[0] (NonStringeIteralble[RegDom]): instances to preload self._deq """ self._deq = deque() @@ -78,7 +81,8 @@ def __len__(self): def stale(self): """Getter for ._stale - Returns: + Returns:: + stale (bool): True means in-memory and durable on disk not synced False means in-memory and durable on disk synced """ @@ -88,7 +92,8 @@ def stale(self): def durable(self): """Property durable True when durable subdb injected and opened. - Returns: + Returns:: + durable (bool): True means ._sdb and ._key and ._sdb.db and .sdb.db.opened are not None False otherwise @@ -120,7 +125,8 @@ 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: + Parameters:: + val (RegDom): element to be appended to deck (deque) """ if val is not None: @@ -141,7 +147,8 @@ def pull(self, emptive=True): Peforms equivalent operation on durable .sdb at .key if any - Parameters: + Parameters:: + emptive (bool): True means return None instead of raise IndexError when attempt to pull False means normal behavior of deque @@ -241,7 +248,7 @@ def sync(self, force=False): and ._stale or force then reads own data from ._sdb at ._key if any. If not attempts to write to ._sdb at ._key - Parameters: + Parameters:: force (bool): True means force read even if not ._stale Flase means do not force read """ @@ -256,4 +263,3 @@ def sync(self, force=False): return self.pin() return None - diff --git a/src/hio/base/hier/dusqing.py b/src/hio/base/hier/dusqing.py index 991ebdf8..82bda13c 100644 --- a/src/hio/base/hier/dusqing.py +++ b/src/hio/base/hier/dusqing.py @@ -17,7 +17,8 @@ class Dusq(): .sdb and .key will store its ordered set durably and allow access as a deduped FIFO queue. A set is deduped. - Properties + 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 @@ -25,7 +26,8 @@ class Dusq(): False otherwise - Hidden: + Hidden:: + _oset (oset): in-memory cache as ordered set _sdb (DomIoSuber): instance of durable store _key (str): into .sdb @@ -38,8 +40,9 @@ class Dusq(): def __init__(self, *pa): """Initialize instance - Parameters: - pa[0] (NonStringeIteralble[RegDom]): instances to preload self._oset + Parameters:: + + pa[0] (NonStringeIteralble[RegDom]): instances to preload self._oset """ self._oset = oset() @@ -81,7 +84,8 @@ def __len__(self): def stale(self): """Getter for ._stale - Returns: + Returns:: + stale (bool): True means in-memory and durable on disk not synced False means in-memory and durable on disk synced """ @@ -91,7 +95,8 @@ def stale(self): def durable(self): """Property durable True when durable subdb injected and opened. - Returns: + Returns:: + durable (bool): True means ._sdb and ._key and ._sdb.db and .sdb.db.opened are not None False otherwise @@ -104,7 +109,8 @@ def update(self, vals: NonStringIterable[RegDom|IceRegDom], *, deep=True): """Update ._deq with vals Peforms equivalent operation on durable .sdb at .key if any - Parameters: + Parameters:: + vals (NonStringIterable[RegDom]): to add to dusq deep (bool): True means deepcopy to ensure can't mutate outside False means do not deepcopy @@ -130,7 +136,8 @@ 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: + Parameters:: + val (RegDom): element to be appended to deck (deque) """ if val is not None: @@ -155,7 +162,8 @@ def pull(self, emptive=True): Peforms equivalent operation on durable .sdb at .key if any - Parameters: + Parameters:: + emptive (bool): True means return None instead of raise IndexError when attempt to pull False means normal behavior of deque @@ -197,7 +205,8 @@ def clear(self): def remove(self, value: RegDom|IceRegDom): """Remove value if contained - Returns: + Returns:: + result (bool): True value was removed Raises KeyError if value not found @@ -272,7 +281,7 @@ def sync(self, force=False): and ._stale or force then reads own data from ._sdb at ._key if any. If not attempts to write to ._sdb at ._key - Parameters: + Parameters:: force (bool): True means force read even if not ._stale Flase means do not force read """ diff --git a/src/hio/base/hier/hiering.py b/src/hio/base/hier/hiering.py index 9f395ee3..bad3044e 100644 --- a/src/hio/base/hier/hiering.py +++ b/src/hio/base/hier/hiering.py @@ -5,7 +5,8 @@ Provides hierarchical action support -Syntax notes for Mine and Dock use in boxwork: +Syntax notes for Mine and Dock use in boxwork:: + H hold (Hold) boxwork shared data attribute syntax with locally scoped variable H ref for hold . @@ -47,7 +48,8 @@ """Nabage (namedtuple): Action nabes (contexts mileu neighborhood) for Acts -Fields: +Fields:: + native (str): native nabe predo (str): predo nabe remark (str): remark sub-nabe of rendo @@ -75,7 +77,8 @@ class WorkDom(MapDom): make methods of Boxer by workify wrapper. - Attributes: + Attributes:: + box (Box | None): current box in box work. None if not yet a box over (Box | None): current over Box in box work. None if top level bxpre (str): default box name prefix used to generate unique box name @@ -91,5 +94,3 @@ class WorkDom(MapDom): bxidx: int = 0 # default box name index when name not provided acts: dict = field(default_factory=dict) # registry of Acts by name & aliases nabe: str = Nabes.native # current action nabe (context) - - diff --git a/src/hio/base/hier/hogging.py b/src/hio/base/hier/hogging.py index ca45bad4..a8771c2b 100644 --- a/src/hio/base/hier/hogging.py +++ b/src/hio/base/hier/hogging.py @@ -35,7 +35,8 @@ class Hog(ActBase, Filer): Act comes before Filer in .__mro__ so Act.name property is used not Filer.name - Inherited Class Attributes: + Inherited Class Attributes:: + Registry (dict): subclass registry whose items are (name, cls) where: name is unique name for subclass cls is reference to class object @@ -60,14 +61,16 @@ class Hog(ActBase, Filer): Mode (str): open mode such as "r+" Fext (str): default file extension such as "text" for "fname.text" - Class Attributes: + 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 tags when using ``**kwa`` to provide hold log leys. Uses dict since inclusion test is faster than with list - Inherited Attributes see Act, File + Inherited Attributes see Act, File:: + hold (Hold): data shared by boxwork name (str): overriden by .name property from Act (see name property) @@ -88,7 +91,8 @@ class Hog(ActBase, Filer): is opened. False otherwise - Inherited Properties see Act, File + 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 @@ -96,7 +100,8 @@ class Hog(ActBase, Filer): nabe (str): action nabe (context) for .act - Attributes: + Attributes:: + started (bool): True means logging has begun with header False means logging has not yet begun needs header first (float|None): tyme when began logging, None means not yet running @@ -135,7 +140,8 @@ class Hog(ActBase, Filer): None otherwise - Hidden: + Hidden:: + _name (str): unique name of instance for .name property _iopts (dict): input-output-paramters for .act for .iops property _nabe (str): action nabe (context) for .act for .nabe property @@ -173,7 +179,8 @@ class Hog(ActBase, Filer): def _genRid(cls): """Generates random universally unique hog run ID rid, not iteration - Returns: + Returns:: + rid (str): run id in 24 bit aligned Base64 """ ps = 2 # pad size, use unit test to ensure .Proem is at least length 2 @@ -190,7 +197,8 @@ def __init__(self, iops=None, nabe=Nabes.afdo, base="", filed=True, hits=None, **kwa): """Initialize instance. - Inherited Parameters: + Inherited Parameters:: + name (str|None): unique name of this instance. When None then generate name from .Index. Used for .name property which is used for registering Act instance in Act registry as well @@ -228,7 +236,8 @@ def __init__(self, iops=None, nabe=Nabes.afdo, base="", filed=True, mode (str): File open mode when filed fext (str): File extension when filed or extensioned - Parameters: + Parameters:: + rid (str|None): universally unique run ID for given run of hog None means create one using uuid lib rule (str|None): condition for log to fire, one of Rules default every @@ -245,11 +254,11 @@ def __init__(self, iops=None, nabe=Nabes.afdo, base="", filed=True, 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`` wrt .ReservedTags When made (created and inited) by boxer.do then have "_boxer" and - "_box" keys in self.iops = dict(_boxer=self.name, _box=m.box.name, **iops) + "_box" keys in self.iops = ``dict(_boxer=self.name, _box=m.box.name, **iops)`` """ if not base: @@ -326,12 +335,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 + Parameters:: + iops (dict): input/output parms, same as self.iops. Puts ``**iops`` in local scope in case act compliles 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: @@ -433,7 +442,8 @@ def act(self, **iops): def log(self, record, tyme, force=False): """Write one record to file and flush when indicated - Parameters: + Parameters:: + record (str): one line of tab delimited newline ended values tyme (float): tyme of log record force (bool): True means force flush even when not flushSpan elapsed @@ -471,8 +481,9 @@ def log(self, record, tyme, force=False): def record(self): """Generate on record line .hits values from .hold - Returns: - record (str): one newline delimited line of tab delimited values + Returns:: + + record (str): one newline delimited line of tab delimited values from .hits. Each hit time value is key into hold vector holds each get entry in record per field @@ -490,7 +501,8 @@ def record(self): def cycle(self, tyme): """Cycle log files - Parameters: + Parameters:: + tyme (float): current tyme of cycle """ self.flush @@ -530,7 +542,8 @@ def openHog(cls=None, name=None, temp=True, reopen=True, clear=False, **kwa): Defaults to using temporary directory path. Context 'with' statements call .close on exit of 'with' block - Parameters: + Parameters:: + cls is Class instance of subclass instance name is str name of Filer instance path part so can have multiple Filers at different paths that each use different dirs or files @@ -540,13 +553,15 @@ def openHog(cls=None, name=None, temp=True, reopen=True, clear=False, **kwa): False not (re)open with this init but later (default) clear (bool): True means remove directory upon close when reopening False means do not remove directory upon close when reopening + See hogging.Hog for other keyword parameter passthroughs - Usage: + Usage:: + + with openHog(name="bob") as hog: - with openHog(name="bob") as hog: + with openHog(name="eve", cls=HogSubClass) as hog: - with openHog(name="eve", cls=HogSubClass) as hog: """ hog = None @@ -566,13 +581,15 @@ class HogDoer(Doer): """ Basic Hog Doer - Attributes: + Attributes:: + done (bool): completion state: True means completed Otherwise incomplete. Incompletion maybe due to close or abort. hog (Hog): instance - Properties: + Properties:: + tyme (float): relative cycle time of associated Tymist .tyme obtained via injected .tymth function wrapper closure. tymth (func): closure returned by Tymist .tymeth() method. @@ -585,8 +602,9 @@ class HogDoer(Doer): def __init__(self, hog, **kwa): """ - Parameters: - tymist (Tymist): instance + Parameters:: + + tymist (Tymist): instance tock (float): initial value of .tock in seconds hog (Hog): instance """ @@ -598,7 +616,8 @@ def enter(self, *, temp=None): """Do 'enter' context actions. Override in subclass. Not a generator method. Set up resources. Comparable to context manager enter. - Parameters: + Parameters:: + temp (bool | None): True means use temporary file resources if any None means ignore parameter value. Use self.temp diff --git a/src/hio/base/hier/holding.py b/src/hio/base/hier/holding.py index 12bcdd35..869464d5 100644 --- a/src/hio/base/hier/holding.py +++ b/src/hio/base/hier/holding.py @@ -46,10 +46,12 @@ class Hold(Mine): of the Can when Can or Durq when Durq - Properties: + Properties:: + subery (None|Subery): gets instance from item at '_hold_subery' or None - Methods: + Methods:: + inject(self, key, val): injects .cans into val._sdb and key into val._key @@ -59,9 +61,9 @@ def __init__(self, *pa, **kwa): Mapping to '.' joined strings dict __init__ signature options are: - dict(**kwa) - dict(mapping, **kwa) - dict(iterable, **kwa) + ``dict(**kwa)`` + ``dict(mapping, **kwa)`` + ``dict(iterable, **kwa)`` dict.update has same call signature d.update({"a": 5, "b": 2,}, c=3 , d=4) """ @@ -81,9 +83,9 @@ def update(self, *pa, **kwa): Mapping to '.' joined strings dict __init__ signature options are: - dict(**kwa) - dict(mapping, **kwa) - dict(iterable, **kwa) + ``dict(**kwa)`` + ``dict(mapping, **kwa)`` + ``dict(iterable, **kwa)`` dict.update has same call signature d.update({"a": 5, "b": 2,}, c=3 , d=4) @@ -125,7 +127,8 @@ def inject(self, key, val): """When val is instance of CanDom, injects .tokey(key) into val._key and .subery.cans into val._sdb - Parameters: + Parameters:: + key (str): for item val (Any|CanDom): for item. When instance subclass of CanDom then inject to ._key and ._sdb @@ -148,10 +151,8 @@ def inject(self, key, val): def subery(self): """Gets value of special item '_hold_subery' - Returns: + Returns:: + subery (None|Subery): instance or None """ return self["_hold_subery"] - - - diff --git a/src/hio/base/hier/needing.py b/src/hio/base/hier/needing.py index b83abb81..3428cc0e 100644 --- a/src/hio/base/hier/needing.py +++ b/src/hio/base/hier/needing.py @@ -21,23 +21,27 @@ class Need(Mixin): The calling it evaluates a need expression. May be used as the transition condition of a Gact. - Attributes: + Attributes:: + hold (Hold): data shared by boxwork - Properties: + Properties:: + expr (str): evalable boolean expression. compiled (bool): True means ._code holds compiled ._expr False means not yet compiled - Hidden: + Hidden:: + _expr (str): evalable boolean expression. _code (None|CodeType): compiled evalable boolean expression .expr None means not yet compiled from .expr - Compilation Notes: + Compilation Notes:: + c = compile("True", '', 'eval') c at 0x1042f2250, file "", line 1> @@ -60,7 +64,8 @@ class Need(Mixin): Also having the string rep around can be helpful in debugging if define __repr__ and __str__ for need objects. - Expr syntax notes: + 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 @@ -83,7 +88,8 @@ class Need(Mixin): def __init__(self, *, expr='True', hold=None, **kwa): """Initialization method for instance. - Parameters: + Parameters:: + expr (str): evalable boolean expression. if empty or None then use default = 'True' hold (None|Hold): data shared by boxwork @@ -97,7 +103,8 @@ def __init__(self, *, expr='True', hold=None, **kwa): def __call__(self, **iops): """Make Need instance a callable object. - Parameters: + Parameters:: + iops (dict): run time input output parms for need. Usually provided when need is Act deed. @@ -112,7 +119,8 @@ def __call__(self, **iops): def expr(self): """Property getter for ._expr - Returns: + Returns:: + expr (str): evalable boolean expression. """ return self._expr @@ -122,7 +130,8 @@ def expr(self): def expr(self, expr): """Property setter for ._expr - Parameters: + Parameters:: + expr (str): evalable boolean expression. """ self._expr = expr if expr else 'True' @@ -133,7 +142,8 @@ def expr(self, expr): def compiled(self): """Property compiled - Returns: + Returns:: + compiled (bool): True means ._code holds compiled ._expr False means not yet compiled """ @@ -147,4 +157,3 @@ def compile(self): at prep (enter) time not init time. """ self._code = compile(self.expr, '', 'eval') -