.. _dootle.actions.postbox:
   
    
======================
dootle.actions.postbox
======================

   
.. py:module:: dootle.actions.postbox

.. autoapi-nested-parse::

   Postbox: Each Task Tree gets one, as a set[Any]
   Each Task can put something in its own postbox.
   And can read any other task tree's postbox, but not modify it.

       
 

   
 

 

 
   
        

           

 
 

           
   
             
  
 

Functions
---------

.. autoapisummary::

    dootle.actions.postbox._validate_key
           
 
  
 
 
  

   
Classes
-------


.. autoapisummary::

    dootle.actions.postbox._DootPostBox
    dootle.actions.postbox.PutPostAction
    dootle.actions.postbox.GetPostAction
    dootle.actions.postbox.ClearPostAction
    dootle.actions.postbox.SummarizePostAction
           
 
      
 
Module Contents
===============

 
.. py:function:: _validate_key(key: doot.workflow.TaskName) -> tuple[str, str]

   Validate and split a key into (box, subbox)


 
 

.. dootle.actions.postbox._DootPostBox:
   
.. py:class:: _DootPostBox
   
    
   Internal Postbox class.
   holds a static variable of `boxes`, which maps task roots -> unique postbox
   Postboxes are lists, values are appended to it

   Can 'put', 'get', 'clear_box', and 'clear'.

   Keys are task names, of {body}..{tail}
   eg: example::task..key
   which corresponds to body[example::task][key]

   
   .. py:attribute:: Subboxes
      :type:  TypeAlias
      :value: dict[str, list[Any]]


   .. py:attribute:: Boxes
      :type:  TypeAlias
      :value: dict[str, Subboxes]


   .. py:attribute:: boxes
      :type:  ClassVar[_DootPostBox.Boxes]

   .. py:attribute:: default_subbox
      :type:  Final[str]
      :value: '-'


   .. py:attribute:: whole_box_key
      :type:  Final[str]
      :value: '*'


   .. py:method:: put(key: doot.workflow.TaskName, val: None | list | set | Any) -> None
      :staticmethod:


   .. py:method:: get(key: doot.workflow.TaskName) -> list | dict
      :staticmethod:


   .. py:method:: clear_box(key: doot.workflow.TaskName) -> None
      :staticmethod:


   .. py:method:: clear() -> None
      :staticmethod:


 
 
 

.. _dootle.actions.postbox.PutPostAction:
   
.. py:class:: PutPostAction
   
    
   push data to the inter-task postbox of this task tree
   'args' are pushed to the postbox of the calling task root (ie: stripped of UUIDs)
   'kwargs' are pushed to the kwarg specific subbox. can be explicit tasks or a subbox of the calling task root

   Both key and value are expanded of kwargs.
   The Subbox is the last ..{name} of the full path

   eg: {do="post.put", args=["{key}", "{key}"], "group::task.sub..subbox"="{key}", "subbox"="{key2}"}

   
   .. py:method:: _add_to_task_box(spec, state, args, _basename) -> None

   .. py:method:: _add_to_target_box(spec, state, kwargs, _basename) -> None

 
 
 

.. _dootle.actions.postbox.GetPostAction:
   
.. py:class:: GetPostAction
   
    
   Read data from the inter-task postbox of a task tree.
   'args' pop a value from the calling tasks root (ie: no UUIDs) box into that key name
   'kwargs' are read literally

   stateKey="group::task.sub..{subbox}"
   eg: {do='post.get', args=["first", "second", "third"], data="bib::format..-"}

   
   .. py:method:: _get_from_task_box(spec, state, args) -> dict
      :abstractmethod:


   .. py:method:: _get_from_target_boxes(spec, state, kwargs) -> dict[doot.util.dkey.DKey, list | dict]

 
 
 

.. _dootle.actions.postbox.ClearPostAction:
   
.. py:class:: ClearPostAction
   
    
   Clear your postbox

   
 
 
 

.. _dootle.actions.postbox.SummarizePostAction:
   
.. py:class:: SummarizePostAction
   
    
   print a summary of this task tree's postbox
   The arguments of the action are held in self.spec