.. _doot.control.overlord:
  
=====================
doot.control.overlord
=====================
  


.. py:module:: doot.control.overlord

 






Type Aliases
------------

.. autoapisummary::

   doot.control.overlord.Logger







Classes
-------
  


.. autoapisummary::

    doot.control.overlord.StartupController
    doot.control.overlord.PluginsController
    doot.control.overlord.DootOverlord
    doot.control.overlord.OverlordFacade

Module Contents
===============

.. py:data:: Logger
   :type:  TypeAlias
   :value: logmod.Logger



.. _doot.control.overlord.StartupController:
  


.. py:class:: StartupController

 

   .. py:attribute:: DO
      :type:  TypeAlias
      :value: DootOverlord


   
   .. py:method:: null_setup(obj: DO) -> None


      Doesn't load anything but constants,
      Used for initialising Doot when testing.
      Doesn't set the is_setup flag.



   
   .. py:method:: setup(obj: DO, *, targets: jgdv.Maybe[list[Loadable]] = None, prefix: jgdv.Maybe[str] = None) -> None


      The core requirement to call before any other doot code is run.
      loads the config files, so everything else can retrieve values when imported.

      `prefix` removes a prefix from the loaded data.
      eg: 'tool.doot' for if putting doot settings in a pyproject.toml

      targets=False is for loading nothing, for testing



   
   .. py:method:: _load_config(obj: DO, *, targets: jgdv.Maybe[list[Loadable]], prefix: jgdv.Maybe[str]) -> None


      Load a specified config, or one of the defaults if it exists



   
   .. py:method:: _load_constants(obj: DO, *, target: jgdv.Maybe[Loadable] = None) -> None


      Load the override constants if the loaded base config specifies one
      Modifies the global `doot.constants`



   
   .. py:method:: _load_aliases(obj: DO, *, target: jgdv.Maybe[Loadable] = None, force: bool = False) -> None


      Load plugin aliases from a toml file

      if forced, will append additional aliases on top of existing



   
   .. py:method:: _load_locations(obj: DO) -> None


      Load and update the JGDVLocator db




 

.. _doot.control.overlord.PluginsController:
  


.. py:class:: PluginsController

 

   .. py:attribute:: DO
      :type:  TypeAlias
      :value: DootOverlord


   
   .. py:method:: load(obj: DO) -> None



   
   .. py:method:: _load_plugins(obj: DootOverlord) -> None


      Use the plugin loader to find all applicable `importlib.EntryPoint`s



   
   .. py:method:: _load_commands(obj: DootOverlord, *, loader: str = 'default') -> None


      Select Commands from the discovered loaded_plugins,
      using the preferred cmd loader or the default



   
   .. py:method:: _load_tasks(obj: DootOverlord, *, loader: str = 'default') -> None


      Load task entry points, using the preferred task loader,
      or the default



 

.. _doot.control.overlord.DootOverlord:
  


.. py:class:: DootOverlord(*args: Any, **kwargs: Any)

 
   The main control point of Doot
   The setup logic of doot.

   As Doot uses loaded config data throughout, using the doot.config.on_fail... pattern,
   the top-level package 'doot', uses a module getattr to offload attribute access to this class.

   Adapted from https://stackoverflow.com/questions/880530


   .. py:attribute:: _startup
      :type:  ClassVar[StartupController]

   .. py:attribute:: _plugin
      :type:  ClassVar[PluginsController]

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

   .. py:attribute:: path_ext
      :type:  list[str]

   .. py:attribute:: configs_loaded_from
      :type:  list[str | pathlib.Path]

   .. py:attribute:: is_setup
      :type:  bool

   .. py:attribute:: config

   .. py:attribute:: constants

   .. py:attribute:: aliases

   .. py:attribute:: loaded_plugins

   .. py:attribute:: loaded_cmds

   .. py:attribute:: loaded_tasks

   .. py:attribute:: cmd_aliases

   .. py:attribute:: args

   .. py:attribute:: locs

   .. py:property:: report
      :type: doot.reporters._interface.Reporter_p


   
   .. py:method:: _set_reporter(rep: Any) -> None



   
   .. py:method:: setup(*, targets: jgdv.Maybe[list[Loadable]] = None, prefix: jgdv.Maybe[str] = None) -> None



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



   
   .. py:method:: load_reporter(target: str = 'default') -> None



   
   .. py:method:: verify_config_version(ver: jgdv.Maybe[str], source: jgdv.Maybe[str | pathlib.Path], *, override: jgdv.Maybe[str] = None) -> None


      Ensure the config file is compatible with doot

      Compatibility is based on MAJOR.MINOR and discards PATCH

      Raises a VersionMismatchError otherwise if they aren't compatible



   
   .. py:method:: update_aliases(*, data: dict | jgdv.structs.chainguard.ChainGuard) -> None


      Update aliases with a dict-like of loaded mappings



   
   .. py:method:: update_global_task_state(data: jgdv.structs.chainguard.ChainGuard, *, source: jgdv.Maybe[str] = None) -> None


      Try to Update the shared global state.
      Will try to get data[doot._interface.GLOBAL_STATE_KEY] data and add it to the global task state

      toml in [[state]] segments is merged here



   
   .. py:method:: update_import_path(*paths: pathlib.Path) -> None


      Add locations to the python path for task local code importing
      Modifies the global `sys.path`



   
   .. py:method:: update_cmd_args(data: jgdv.cli._interface.ParseReport_d | dict, *, override: bool = False) -> None


      update global args that cmd's use for control flow



 

.. _doot.control.overlord.OverlordFacade:
  


.. py:class:: OverlordFacade(*args, **kwargs)

   Bases: :py:obj:`types.ModuleType` 
  
   A Facade for the overlord, to be used as the module class
   of the root package 'doot'.



   .. py:attribute:: _overlord
      :type:  doot.control._interface.Overlord_i