hio.help.doming

hio.help.doming module

Support for Dataclass Object Mapper Dom classes

Module Contents

hio.help.doming.dictify(val)

Returns a serializable dict represention of a dataclass. If the dataclass contains a _dictify method, use it instead of `asdict

Parameters:

dict. (val the dataclass instance to turn into a)

hio.help.doming.datify(cls, d)

Returns instance of dataclass cls converted from dict d. If the dataclass cls or any nested dataclasses contains a _datify method, the use it instead of default fieldtypes conversion.

Parameters: cls is dataclass class d is dict

hio.help.doming.registerify(cls)

Class Decorator to add cls as cls._registry entry for itself keyed by its own .__name__. Need class decorator so that class object is already created by registration time when decorator is applied

hio.help.doming.namify(cls)

Class decorator for dataclass to populate ClassVar ._names with names of all fields in dataclass

class hio.help.doming.IceMapDom

Base class for dataclasses (codexes) that support map syntax Adds support for dunder methods for map syntax dc[name]. Converts exceptions from attribute syntax to raise map syntax when using map syntax.

Enables dataclass instances to use Mapping item syntax except for __delattr__ because dataclasses to not allow __delattr__ to be overridden

A non-frozen dataclass may not be a subclass of a frozen dataclass neither may a frozen dataclass be a subclass of a frozen dataclass.

Frozen dataclass do not allow change or upate of either field or non-field attributes after __init__ this includes in the __post_init__ method.

Class Methods:

_fromdict(cls, d: dict): return dataclass converted from dict d

__iter__()

asdict(self)

__getitem__(self, name)  map like interface

_asdict()

return self converted to dict

_astuple()

return self converted to tuple

class hio.help.doming.IceRawDom

Bases: IceMapDom

IceRawDom is frozen version of RawDom which is a subclass of IceMapDom that adds methods for converting to/from raw format serializations in JSON, CBOR, and MGPK. IceRawDom is a base class for such frozen dataclasses. The serialization process is to transform dataclass into dict and then serialize into raw. The deserialization process is to deserialize into dict and then convert to dataclass. This allows dataclass to stored in databases or to be sent over the wire in messages in raw format.

Enables dataclass instances to use Mapping item syntax except for __delattr__ because dataclasses to not allow __delattr__ to be overridden

A non-frozen dataclass may not be a subclass of a frozen dataclass neither may a frozen dataclass be a subclass of a frozen dataclass.

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 Class Methods:

_fromdict(cls, d: dict): return dataclass converted from dict d

Class Methods:

_fromjson(cls, s: str or bytes): return dataclass converted from json s _fromcbor(cls, s: bytes): return dataclass converted from cbor s _frommgpk(cls, s: bytes): return dataclass converted from mgpk s

Inherited Methods:

__iter__(self): asdict(self) __getitem__(self, name) map like interface _asdict(self): return self converted to dict _astuple(): return self converted to tuple

_asjson(self)

return bytes self converted to json

_ascbor(self)

return bytes self converted to cbor

_asmgpk(self)

return bytes self converted to mgpk

class hio.help.doming.IceRegDom

Bases: IceRawDom

IceRegDom is frozen version of RegDom which is a base class for frozen Dom subclasses that have class registry as as non field ClassVar that holds mapping between class name and class object. Use the registerify decorator to populate the registry with a given dataclass.

This allows registry based creation of instances from the class name.

Enables dataclass instances to use Mapping item syntax except for __delattr__ because dataclasses to not allow __delattr__ to be overridden

A non-frozen dataclass may not be a subclass of a frozen dataclass neither may a frozen dataclass be a subclass of a frozen dataclass.

Frozen dataclass do not allow change or upate of either field or non-field attributes after __init__ this includes in the __post_init__ method.

Non-Field Class Attributes:

_registry (ClassVar[dict]): dict of subclasses keyed by class.__name__

Assigned by @registerify decorator

class hio.help.doming.IceTymeDom

Bases: IceRegDom

IceTymeDom is frozen version of TymeDom which is a base class for frozen Dom dataclasses that are registered and support the cycle tyme stamping of named fields using non-field attributes. Note the only tyme stamp that can happen is at init since the dataclass is frozen.

Use decorator registerify to populate ._registry Use deocrator namify to populate ._names which holds names of field attributes

Enables dataclass instances to use Mapping item syntax except for __delattr__ because dataclasses to not allow __delattr__ to be overridden

A non-frozen dataclass may not be a subclass of a frozen dataclass neither may a frozen dataclass be a subclass of a frozen dataclass.

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:

_registry (ClassVar[dict]): dict of subclasses keyed by class.__name__

Assigned by @registerify decorator

Non-Field Class Attributes:

_names (ClassVar[tuple[str] or None]): tuple of field names for class

Assigned by @namify decorator

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

class hio.help.doming.MapDom

MapDom is a subclass of IceMapDom and is a base class for dataclasses that support map syntax Adds support for dunder methods for map syntax dc[name]. Converts exceptions from attribute syntax to raise map syntax when using map syntax.

Enables dataclass instances to use Mapping item syntax except for __delattr__ because dataclasses to not allow __delattr__ to be overridden

A non-frozen dataclass may not be a subclass of a frozen dataclass neither may a frozen dataclass be a subclass of a frozen dataclass.

Class Methods:

_fromdict(cls, d: dict): return dataclass converted from dict d

__iter__()

asdict(self)

__getitem__(self, name)  map like interface

__setitem__(self, name, value)  map like interface

_update(\*pa, \*\*kwa)

update attributes using dict like update syntax

_asdict()

return self converted to dict

_astuple()

return self converted to tuple

hio.help.doming.modify(mods: MapDom | None = None, klas: Type[MapDom] = MapDom) → collections.abc.Callable[Ellipsis, Any]

Wrapper with argument(s) that injects mods dataclass instance that must be a subclass of MapDom. When mods is provided it is injected as the keyword arg ‘mods’ into the wrapped function. If mods is None then an instance of klas is created and injected instead. This creates a lexical closure of this injection. The value of klas must also be a a MapDom subclass.

Parameters:

• mods (WorkDom|None) – default None. Instance of dataclass to be injected

• klas (Type[WorkDom]) – defualt WorkDom. Class of dataclass to be injected as default when mods not provided.

If wrapped function call itself includes mods as an arg whose value is not None then does not inject. This allows override of a single call. Subsequent calls will resume using the lexical closure or the wrapped injected mods whichever was provided.

Assumes wrapped function defines mods argument as a keyword only parameter using ‘*’ such as:

def f(name='box', over=None, *, mods=None):

To use inline:

mods = WorkDom(box=None, over=None, bepre='box', beidx=0)
g = modify(mods)(f)

Later calling g as:

g(name="mid", over="top")

Actually has mods injected as if called as:

g(name="mid", over="top", mods=mods)

Also can be used on a method not just a function:

def m(self, name='box', over=None, *, mods=None):

To use inline:

mods = dict(box=None, over=None, bepre='box', beidx=0)
m = modify(mods)(self.m)

Later calling m as:

m(name="mid", over="top")

Actually has mods injected as if called as:

m(name="mid", over="top", mods=mods)  where self is also injected into method

Since mods is a mutable collection i.e. dataclass, not an immutable object using @decorator syntax on could be problematic as the injected mods would be a lexical closure defined in the defining scope not the calling scope. Depends on what the use case it for it.

Example:

mods = WorkDom(box=None, over=None, bepre='box', beidx=0)
@modify(mods=mods)
def f(name="box", over=None, *, mods=None)

Later calling f as:

f(name="mid", over="top")

Actually has mods injected as if called as:

f(name="mid", over="top", mods=mods)

But the mods in this case is from the defining scope, not the calling scope.

Likewise passing in mods=None would result in a lexical closure of mods with default values initially that would be shared everywhere f() is called.

When f() is called with an explicit mods such as f(mods=mods) then that call will use the passed in mods not the injected mods. This allows a per call override of the injected mods.

hio.help.doming.modize(mods: dict | None = None) → collections.abc.Callable[Ellipsis, Any]

Wrapper with argument(s) that injects dict or mods dataclass instance that must be a subclass of MapDom as lexical closure into the wrapped function as keyword parameter ‘mods’ .

If wrapped function call itself includes mods as an arg whose value is not None then does not inject. This allows override of a single call. Subsequent calls will resume using the lexical closure or the wrapped injected mods whichever was provided.

Assumes wrapped function defines mods argument as a keyword only parameter using ‘*’ such as:

def f(name='box', over=None, *, mods=None):

To use inline:

mods = dict(box=None, over=None, bepre='box', beidx=0)
g = modize(mods)(f)

Later calling g as:

g(name="mid", over="top")

Actually has mods injected as if called as:

g(name="mid", over="top", mods=mods)

If method then works as well:

def f(self, name='box', over=None, *, mods=None):

To use inline:

mods = dict(box=None, over=None, bepre='box', beidx=0)
f = modize(mods)(self.f)

Later calling f as:

f(name="mid", over="top")

Actually has mods injected as if called as:

f(name="mid", over="top", mods=mods)  the self is automatically supplied

Since mods is a mutable collection i.e. dict, not an immutable string then using it as decorator could be problematic as the mods would have lexical defining scope not calling scope. Which is ok if mods has lexical module scope intentionally.

Example:

mods = dict(box=None, over=None, bepre='box', beidx=0)

@modize(mods=mods)
def f(name="box", over=None, *, mods=None)

Later calling as:

f(name="mid", over="top")

Actually has mods injected as if called as:

f(name="mid", over="top", mods=mods)

But the mods in this case is from the defining scope not the calling scope.

Likewise passing in mods=None would result in a lexical closure of mods with default values initially that would be shared everywhere f() is called with whatever values each call changes in the lexical closure of mods.

class hio.help.doming.RawDom

Bases: MapDom

RawDom is subclass of MapDom that adds methods for converting to/from raw format serializations in JSON, CBOR, and MGPK. RawDom is a base class for such dataclasses. The serialization process is to transform dataclass into dict and then serialize into raw. The deserialization process is to deserialize into dict and then convert to dataclass. This allows dataclass to stored in databases or to be sent over the wire in messages in raw format.

Enables dataclass instances to use Mapping item syntax except for __delattr__ because dataclasses to not allow __delattr__ to be overridden

A non-frozen dataclass may not be a subclass of a frozen dataclass neither may a frozen dataclass be a subclass of a frozen dataclass.

Inherited Class Methods:

_fromdict(cls, d: dict): return dataclass converted from dict d

Class Methods:

_fromjson(cls, s: str|bytes): return dataclass converted from json s _fromcbor(cls, s: bytes): return dataclass converted from cbor s _frommgpk(cls, s: bytes): return dataclass converted from mgpk s

Inherited Methods:

__getitem__(self, name) map like interface __setitem__(self, name, value) map like interface __iter__(self): asdict(self) _asdict(self): return self converted to dict _astuple(): return self converted to tuple _update(*pa, **kwa): update attributes using dict like update syntax

_asjson(self)

return bytes self converted to json

_ascbor(self)

return bytes self converted to cbor

_asmgpk(self)

return bytes self converted to mgpk

class hio.help.doming.RegDom

Bases: RawDom

RegDom is base class for Dom subclasses that have class registry as as non field ClassVar that holds mapping between class name and class object. Use the registerify decorator to populate the registry with a given dataclass.

This allows registry based creation of instances from the class name.

Enables dataclass instances to use Mapping item syntax except for __delattr__ because dataclasses to not allow __delattr__ to be overridden

A non-frozen dataclass may not be a subclass of a frozen dataclass neither may a frozen dataclass be a subclass of a frozen dataclass.

Non-Field Class Attributes:

_registry (ClassVar[dict]): dict of subclasses keyed by class.__name__

Assigned by @registerify decorator

class hio.help.doming.TymeDom

Bases: RegDom

TymeDom is base class for Dom dataclasses that are registered and support the cycle tyme stamping of updates to named fields using non-field attributes. Use decorator registerify to populate ._registry Use deocrator namify to populate ._names which holds names of field attributes

Supports the cycle tyme stamping of updates to named fields using non-field attributes.

This allows registry based creation of instances from the class name.

Enables dataclass instances to use Mapping item syntax except for __delattr__ because dataclasses to not allow __delattr__ to be overridden

A non-frozen dataclass may not be a subclass of a frozen dataclass neither may a frozen dataclass be a subclass of a frozen dataclass.

Inherited Non-Field Class Attributes:

_registry (ClassVar[dict]): dict of subclasses keyed by class.__name__

Assigned by @registerify decorator

Non-Field Class Attributes:

_names (ClassVar[tuple[str]|None]): tuple of field names for class

Assigned by @namify decorator

Non-Field Attributes:

_tymth (None or 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. None means not assigned yet. Use ._wind method to assign ._tymth after init of bag.

_tyme (None or 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.

Properties:

_now (None or float): current tyme given by ._tymth if not None.