:py:mod:`electrolyt.plan`
=========================

.. py:module:: electrolyt.plan

.. autoapi-nested-parse::

   Electrolyt plan parsing and execution.



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

Classes
~~~~~~~

.. autoapisummary::

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




.. py:exception:: PlanError(message: str | list[str], origin: str | None = None)


   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: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]
      :return: a toggleable boolean with the given name


   .. 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 to load
      :param filename: filename associated with the Python code



.. py:class:: PlanActionEnv(build: e3.platform.Platform | None = None, host: e3.platform.Platform | None = None, target: e3.platform.Platform | None = None)


   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 | collections.abc.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: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:: 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:method:: execute(plan: Plan, entry_point_name: str, verify: bool = False, entry_point_parameters: dict | None = None, symbols: dict[str, Any] | 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
      :param symbols: any additional symbols (global variable, types, object,
          function, and so on) that should be made available to the plan module.
      :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

      Enter context manager for plan context.


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

      Exit context manager for plan context.