Skip to content

docs: fix all remaining docstring RST formatting for Sphinx/docutils compliance #154

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

docs: fix all remaining docstring RST formatting for Sphinx/docutils compliance #154

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
51 changes: 18 additions & 33 deletions src/hio/base/during.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down
14 changes: 8 additions & 6 deletions src/hio/base/filing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
52 changes: 26 additions & 26 deletions src/hio/base/hier/boxing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

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

Expand Down
Loading
Loading