Skip to content

Fix docstrings in hier small modules #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SmithSamuelM merged 1 commit into from
Mar 18, 2026
Merged

Fix docstrings in hier small modules #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions src/hio/base/hier/bagging.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,22 +35,25 @@ 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
Returns None
_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

Expand All @@ -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.
Expand All @@ -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

Expand All @@ -103,4 +110,3 @@ def __hash__(self):
in every subclass
"""
return hash((self.__class__.__name__,) + self._astuple()) # almost same as __eq__

34 changes: 22 additions & 12 deletions src/hio/base/hier/canning.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
"""
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -220,4 +231,3 @@ def __hash__(self):
in every subclass
"""
return hash((self.__class__.__name__,) + self._astuple()) # almost same as __eq__

26 changes: 16 additions & 10 deletions src/hio/base/hier/durqing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,17 @@ 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
.sdb.db.opened are not None
False otherwise


Hidden:
Hidden::

_deq (deque): in-memory cache as deque
_sdb (DomIoSuber): instance of durable store
_key (str): into .sdb
Expand All @@ -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()
Expand Down Expand Up @@ -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
"""
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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
"""
Expand All @@ -256,4 +263,3 @@ def sync(self, force=False):
return self.pin()

return None

31 changes: 20 additions & 11 deletions src/hio/base/hier/dusqing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,17 @@ 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
.sdb.db.opened are not None
False otherwise


Hidden:
Hidden::

_oset (oset): in-memory cache as ordered set
_sdb (DomIoSuber): instance of durable store
_key (str): into .sdb
Expand All @@ -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()
Expand Down Expand Up @@ -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
"""
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
"""
Expand Down
11 changes: 6 additions & 5 deletions src/hio/base/hier/hiering.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 .

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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)


Loading
Loading