electrolyt.plan
===============

.. py:module:: electrolyt.plan


Classes
-------

.. autoapisummary::

   electrolyt.plan.PlanError
   electrolyt.plan.Plan
   electrolyt.plan.PlanActionEnv
   electrolyt.plan.PlanContext


Module Contents
---------------

.. py:class:: PlanError

   Bases: :py:obj:`e3.error.E3Error`


   Error when parsing or executing the plan.


.. py:class:: Plan(data: dict[str, Any], entry_point_cls: dict[str, collections.abc.Callable[Ellipsis, e3.electrolyt.entry_point.EntryPoint]] | None = None, plan_ext: str = '.plan')

   Electrolyt Plan.

   :ivar entry_points: list of entry points found in the plans
   :vartype entry_points: dict


   .. py:attribute:: mod


   .. py:attribute:: entry_points
      :type:  dict[str, e3.electrolyt.entry_point.EntryPoint]


   .. py:attribute:: plan_ext
      :value: '.plan'



   .. py:attribute:: plan_date


   .. py:attribute:: toggleable_bool_group


   .. py:method:: cond(name: str, date: collections.abc.Callable[[datetime.datetime], bool]) -> e3.collection.toggleable_bool.ToggleableBoolean

      Generate a new conditional boolean.

      :param name: variable name
      :param date: function that takes the plan date and return a boolean.
          This can be used to set a value depending on the day of the week,
          e.g. by setting the constant to True on weekend:
          lambda d: d.isoweekday() in [6, 7]



   .. py:method:: load(filename: str) -> None

      Load python code from file.

      :param filename: path to the python code



   .. py:method:: check(code_ast: ast.AST) -> None

      Check plan coding style.



   .. py:method:: load_chunk(source_code: bytes, filename: str = '<unknown>') -> None

      Load a chunk of Python code.

      :param source_code: python source code
      :param filename: filename associated with the Python code



.. py:class:: PlanActionEnv

   Bases: :py:obj:`e3.env.BaseEnv`


   Store the action environment.

   This includes the build/host/target as well as additional parameters
   coming from the plan.


   .. py:attribute:: action
      :type:  str


   .. py:attribute:: plan_line
      :type:  str


   .. py:attribute:: plan_args
      :type:  dict[str, Any]


   .. py:attribute:: plan_call_args
      :type:  dict[str, Any]


   .. py:attribute:: push_to_store
      :type:  bool


   .. py:attribute:: default_build
      :type:  bool


   .. py:attribute:: module
      :type:  str | None


   .. py:attribute:: source_packages
      :type:  list[str] | None


   .. py:attribute:: qualifier
      :type:  str | dict[str, str | bool | Iterable[str]] | None


.. py:class:: PlanContext(stack: list[PlanActionEnv] | None = None, plan: Plan | None = None, ignore_disabled: bool = True, server: e3.env.BaseEnv | None = None, build: str | None = None, host: str | None = None, target: str | None = None, enabled: bool = True, default_push_to_store: bool = False, **kwargs: Any)

   Context in which a Plan is executed.


   .. py:attribute:: ignore_disabled
      :value: True



   .. py:attribute:: actions
      :type:  dict[str, collections.abc.Callable]


   .. py:attribute:: action_list
      :type:  list[PlanActionEnv]
      :value: []



   .. py:method:: register_action(name: str, fun: collections.abc.Callable) -> None

      Register a function that correspond to an action.

      :param name: name used in the plans
      :param fun: python function. The function itself does
          not require an implementation. Only signature is
          is used



   .. py:property:: env
      :type: PlanActionEnv


      Get environment for current scope.

      :return: the current scope environment



   .. py:property:: default_env
      :type: e3.env.BaseEnv


      Get initial environment.

      :return: the environment set during creation of the
          initial context



   .. py:method:: execute(plan: Plan, entry_point_name: str, verify: bool = False, entry_point_parameters: dict | None = None) -> list[PlanActionEnv]

      Execute a plan.

      :param plan: the plan to execute
      :param entry_point_name: entry point to call in the plan. It can be
          either a function name in the plan or an entry_point function
      :param verify: verify whether the entry point name is a
          electrolyt entry point
      :param entry_point_parameters: parameters passed as keyword arguments
          to the entry point
      :raise: PlanError
      :return: a list of plan actions



   .. py:method:: _add_action(name: str, *args: Any, **kwargs: Any) -> None

      Process action calls in plans.

      :param name: action name
      :param args: positional arguments of the action call
      :param kwargs: keyword arguments of the action call



   .. py:method:: __enter__() -> None


   .. py:method:: __exit__(_type: type[BaseException] | None, _value: BaseException | None, _tb: types.TracebackType | None) -> None


