hio.base.hier.acting ==================== .. py:module:: hio.base.hier.acting .. autoapi-nested-parse:: hio.base.hier.acting Module Provides hierarchical action support Module Contents --------------- .. py:function:: actify(name, *, base=None, attrs=None) Parametrized decorator that converts the decorated function func into .act method of new subclass of class base with .__name__ name. If not provided then uses Act as base. When provided base must be subclass of ActBase. Registers new subclass in ActBase.Registry. Then instantiates cls and returns instance. Returns:: instance (cls): instance of new subclass Updates the class attributes of new subclass with attrs if any. Any callable usually function that is not already a subclass of ActBase can be converted to a subclass of ActBase and then registered in the Registry by its given name. Usually when defining a class simply make is a subclass of ActBase. But when given a function one can decorate it with actify so that a new subclass of ActBase is created and registered. Usage:: @actify(name="Tact") def test(self, **kwa): # signature for .act with ``**iops`` as ``**kwa`` assert kwa == self.iops return self.iops t = test(iops=dict(what=1), hello="hello", nabe=Nabes.redo) Notes: In Python, when a function is assigned as the value of a class attribute, the value of that attribute is automatically converted to a bound method of that class with injected self as first argument. class A(): def a(self): print(self) a = A() a.a() <__main__.A object at 0x1059ffc50> def b(self): print(self) A.b = b a.b() <__main__.A object at 0x1059ffc50> .. py:function:: registerone(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 .. py:function:: register(names=None) Parametrized class Decorator to add cls as cls.Registry entry for itself keyed by its own .__name__ as well as being keyed by aliases in names. A class decorator is necessary so that the class object is already created when decorator is applied. Parameters:: names (None|str|Iterator): iterator of names as aliases besides class name to register class in Act registry and assigned to cls.Names .. py:class:: ActBase(*, name=None, iops=None, nabe=Nabes.endo, hold=None, **kwa) Bases: :py:obj:`hio.hioing.Mixin` Act Base Class. Callable with Registry of itself and its subclasses. Class Attributes:: Registry (dict): subclass registry whose items are (name, cls) where: name is unique name for subclass cls is reference to class object Instances (dict): instance registry whose items are (name, instance) where: name is unique instance name and instance is instance reference Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Attributes:: hold (Hold): data shared by boxwork Properties:: name (str): unique name string of instance iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act Hidden:: _name (str): unique name of instance for .name property _iopts (dict): input-output-parameters for .act for .iops property _nabe (str): action nabe (context) for .act for .nabe property .. py:method:: registerbyname(name=None) :classmethod: Adds cls to cls.Registry entry by name. Raises HierError if already registered. Parameters:: cls (Type[Act]): class to be registered name (None|str): key to register cls under. When None then use cls.__name__ .. py:property:: name Property getter for ._name Returns:: name (str): unique identifier of instance .. py:method:: act(**iops) Act called by Actor. Should override in subclass. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:property:: iops Property getter for ._iopts. Makes ._iopts read only Returns:: iops (dict): input-output-parameters for .act .. py:property:: nabe Property getter for ._nabe. Makes ._nabe read only Returns:: nabe (str): action nabe (context) for .act .. py:class:: Act(deed=None, **kwa) Bases: :py:obj:`ActBase` Act for do verb deeds as executable statements or callables. At make (compile) time any callable that is available in the scope of the do verb in the boxer.make method can be passed in as the deed parameter and will be executed with iops as its parameters. do(deed) 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 Instances (dict): instance registry whose items are (name, instance) where: name is unique instance name and instance is instance reference Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Names (tuple[str]): tuple of aliases (names) under which this subclass appears in .Registry. Created by @register Overridden Class Attributes:: Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Inherited Properties:: name (str): unique name string of instance iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act Inherited Attributes:: hold (Hold): data shared by boxwork Attributes:: None. Properties:: deed (Callable|str): action to be called with .iops as parameters else executable set of statements with H as local compiled (bool): True means ._code holds compiled .deed False means not yet compiled Hidden:: _name (str|None): unique name of instance _iopts (dict): input-output-parameters for .act _nabe (str): action nabe (context) for .act _deed (Callable|str): action to be called with .iops as parameters else executable set of statements with H as local _code (None|CodeType): compiled executable boolean statements from .deed None means not yet compiled from .deed .. py:property:: deed Property getter for ._deed Returns:: deed (str|Callable): compilable exec statement str or callable. .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:property:: compiled Property compiled Returns:: compiled (bool): True means ._code holds compiled ._expr False means not yet compiled or Callable .. py:method:: compile() Compile executable statements in .deed to ._code ._code to be executed (exec) at run time. Because code objects are not pickleable the instantiation compilation must happen after any unpickling of any instances if any. .. py:class:: Goact(dest=None, need=None, **kwa) Bases: :py:obj:`ActBase` Goact (go act) is subclass of ActBase whose .act evaluates conditional need expression to determine if a transition condition is satisfied for transition to its destination box. 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 Instances (dict): instance registry whose items are (name, instance) where: name is unique instance name and instance is instance reference Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Names (tuple[str]): tuple of aliases (names) under which this subclass appears in .Registry. Created by @register Overridden Class Attributes:: Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Inherited Properties:: name (str): unique name string of instance iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act Inherited Attributes:: hold (Hold): data shared by boxwork Attributes:: dest (Box): destination Box for this transition. need (Need): transition condition to be evaluated Hidden:: _name (str|None): unique name of instance _iops (dict): input-output-parameters for .act _context (str): action context for .act .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: EndAct(nabe=Nabes.endo, **kwa) Bases: :py:obj:`ActBase` EndAct is subclass of ActBase whose .act indicates a desire to end the boxer by setting bag at .iops "end" .value to True. Where "end" is at key "_boxer_boxername_end". 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 Instances (dict): instance registry whose items are (name, instance) where: name is unique instance name and instance is instance reference Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Names (tuple[str]): tuple of aliases (names) under which this subclass appears in .Registry. Created by @register Overridden Class Attributes:: Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Inherited Properties:: name (str): unique name string of instance iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act Inherited Attributes:: hold (Hold): data shared by boxwork Attributes:: None. Used iops:: _boxer (str): boxer name Hidden:: _name (str|None): unique name of instance _iops (dict): input-output-parameters for .act _nabe (str): action nabe (context) for .act .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: Beact(lhs: str | tuple([str]), rhs: None | str | collections.abc.Callable = None, **kwa) Bases: :py:obj:`ActBase` Beact for be verb deeds be(lhs, rhs) left_hand_side = right_hand_side 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 Instances (dict): instance registry whose items are (name, instance) where: name is unique instance name and instance is instance reference Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Names (tuple[str]): tuple of aliases (names) under which this subclass appears in .Registry. Created by @register Overridden Class Attributes:: Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Inherited Properties:: name (str): unique name string of instance iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act Inherited Attributes:: hold (Hold): data shared by boxwork Properties:: lhs (tuple[str]): left hand side of assignment of form (key,field) to be assigned as .mine[key][field] rhs (None|str|Callable): When None assign directly When str compiles to evaluable expression When Callable then call directly with iops compiled (bool): True means ._code holds compiled rhs False means not yet compiled Hidden:: _name (str|None): unique name of instance _iopts (dict): input-output-parameters for .act _nabe (str): action nabe (context) for .act _lhs (tuple[str]): of form (key, field) _rhs (None|str|Callable): When None assign directly When str compiles to evaluable expression When Callable then call directly with iops _code (None|CodeType): compiled evaluable boolean expression .rhs None means not yet compiled from .rhs .. py:property:: lhs Property getter for ._lhs Returns:: lhs (tuple[str]): of form (key, field) .. py:property:: rhs Property getter for ._rhs Returns:: rhs (None|str|Callable): right hand side of assignment When None assign directly When str compiles to evaluable expression When Callable then call directly with iops .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:property:: compiled Property compiled Returns:: compiled (bool): True means ._code holds compiled ._expr False means not yet compiled .. py:method:: compile() 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. .. py:class:: Mark(nabe=Nabes.enmark, **kwa) Bases: :py:obj:`ActBase` Mark is base class that is subclass of ActBase whose .act marks a box for a special need condition. 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 Instances (dict): instance registry whose items are (name, instance) where: name is unique instance name and instance is instance reference Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Names (tuple[str]): tuple of aliases (names) under which this subclass appears in .Registry. Created by @register Overridden Class Attributes:: Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Inherited Properties:: name (str): unique name string of instance iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act Inherited Attributes:: hold (Hold): data shared by boxwork Attributes:: bag (Bag): marked bag in Mine Used iops:: _boxer (str): boxer name _box (str): box name in boxer Hidden:: _name (str|None): unique name of instance _iopts (dict): input-output-parameters for .act _nabe (str): action nabe (context) for .act .. py:method:: act(**iops) Act called by ActBase. Override in subclass Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: LapseMark(nabe=Nabes.enmark, **kwa) Bases: :py:obj:`Mark` LapseMark marks box in mine for tyme lapse special need. Enables condition to transit based on elapsed time in a box. .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: RelapseMark(nabe=Nabes.remark, **kwa) Bases: :py:obj:`Mark` RelapseMark marks box in mine for tyme relapse special need. Enables condition to transit based on elapsed time in a box. .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: Count(nabe=Nabes.redo, **kwa) Bases: :py:obj:`Mark` Count tracks count of box in mine for count special need in the nabe where this act is actioned. .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: Discount(nabe=Nabes.exdo, **kwa) Bases: :py:obj:`Mark` Discount resets count to None of box in mine for count special need in the nabe where this act is actioned, usually Nabes.exdo. .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: BagMark(nabe=Nabes.enmark, **kwa) Bases: :py:obj:`Mark` BagMark (Mine Mark) is a base subclass of ActBase whose .act marks a bag value when in a box for a special need condition. 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 Instances (dict): instance registry whose items are (name, instance) where: name is unique instance name and instance is instance reference Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Names (tuple[str]): tuple of aliases (names) under which this subclass appears in .Registry. Created by @register Overridden Class Attributes:: Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Inherited Properties:: name (str): unique name string of instance iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act Inherited Attributes:: hold (Hold): data shared by boxwork Attributes:: bag (Bag): marked bag in Mine Used iops:: _boxer (str): boxer name _box (str): box name in boxer _key (str): marked bag key. Injected by on verb Hidden:: _name (str|None): unique name of instance _iopts (dict): input-output-parameters for .act _nabe (str): action nabe (context) for .act .. py:method:: act(**iops) Act called by ActBase. Override in subclass Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: UpdateMark(nabe=Nabes.enmark, **kwa) Bases: :py:obj:`BagMark` UpdateMark marks bag in mine for tyme update special need .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: ReupdateMark(nabe=Nabes.remark, **kwa) Bases: :py:obj:`BagMark` ReupdateMark marks bag in mine for tyme reupdate special need .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: ChangeMark(nabe=Nabes.enmark, **kwa) Bases: :py:obj:`BagMark` ChangeMark marks bag in mine for value change special need Creates tuple of non-hidden fields in associated bag. .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: RechangeMark(nabe=Nabes.remark, **kwa) Bases: :py:obj:`BagMark` RechangeMark marks bag in mine for value rechange special need Creates tuple of non-hidden fields in associated bag. .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str .. py:class:: CloseAct(nabe=Nabes.exdo, **kwa) Bases: :py:obj:`ActBase` CloseAct is subclass of ActBase whose .act calls .close method of target instance provided by iops item "it", if iops item "clear" provided then passes that value as clear parameter to it.close 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 Instances (dict): instance registry whose items are (name, instance) where: name is unique instance name and instance is instance reference Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Names (tuple[str]): tuple of aliases (names) under which this subclass appears in .Registry. Created by @register Overridden Class Attributes:: Index (int): default naming index for subclass instances. Each subclass overrides with a subclass specific Index value to track subclass specific instance default names. Inherited Properties:: name (str): unique name string of instance iops (dict): input-output-parameters for .act nabe (str): action nabe (context) for .act Inherited Attributes:: hold (Hold): data shared by boxwork Attributes:: it (Any): instance with Callable attribute .close clear (bool|None): clear parameter for .close method Used iops:: it (Any): instance with .close method clear (bool|None): when not None passes value to .close method Hidden:: _name (str|None): unique name of instance _iops (dict): input-output-parameters for .act _nabe (str): action nabe (context) for .act .. py:method:: act(**iops) Act called by ActBase. Parameters:: iops (dict): input/output parameters, same as self.iops. Puts ``**iops`` in local scope in case act compiles exec/eval str