.. _doot.control.main:
  
=================
doot.control.main
=================
  


.. py:module:: doot.control.main

 






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

.. autoapisummary::

   doot.control.main.DataSource







Classes
-------
  


.. autoapisummary::

    doot.control.main.LoadingController
    doot.control.main.CLIController
    doot.control.main.CmdController
    doot.control.main.ShutdownController
    doot.control.main.ErrorHandlers
    doot.control.main.DootMain

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

.. py:data:: DataSource
   :type:  TypeAlias
   :value: dict | ChainGuard



.. _doot.control.main.LoadingController:
  


.. py:class:: LoadingController

 
   mixin for triggering full loading


   .. py:attribute:: DM
      :type:  TypeAlias
      :value: Main_p


   .. py:attribute:: _version_template
      :type:  str

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



   
   .. py:method:: update_command_aliases(obj: DM) -> None


      Read settings.commands.* and register aliases

      commands use doot.config.settings.commands.NAME,
      and within that, 'aliases' gives a dict of {alias=[args]}

      eg: commands.list.aliases.acts = ['--actions']
      ..  aliases 'doot acts'
      ..  to equiv of 'doot list --actions'




 

.. _doot.control.main.CLIController:
  


.. py:class:: CLIController

 
   mixin for cli arg processing


   .. py:attribute:: DM
      :type:  TypeAlias
      :value: DootMain


   
   .. py:method:: parse_args(obj: DM, *, override: jgdv.Maybe[list] = None) -> None


      use loaded cmd and tasks to parse sys.argv



   
   .. py:method:: _load_cli_parser(obj: DM, *, target: str = 'default') -> jgdv.cli.ParseMachine



   
   .. py:method:: _unalias_raw_args(obj: DM) -> list[str]


      replaces aliases with their full command args.

      Just a simple, literal, find and replace



   
   .. py:method:: _construct_implicits() -> dict[str, list[str]]



   
   .. py:method:: _map_subcmd_constraints() -> list[tuple[tuple[str, Ellipsis], jgdv.cli.ParamSource_p]]



 

.. _doot.control.main.CmdController:
  


.. py:class:: CmdController

 
   mixin for actually running a command


   .. py:attribute:: DM
      :type:  TypeAlias
      :value: DootMain


   
   .. py:method:: prepare(obj: DM) -> None



   
   .. py:method:: run_cmds(obj: DM) -> None



   
   .. py:method:: get_cmd_instance(obj: DM, *, cmd: str) -> doot.cmds._interface.Command_p


      Uses the full command name to get the instance of the command



   
   .. py:method:: run_cmd(*, idx: int, cmd: doot.cmds._interface.Command_p) -> int


      The method run to trigger a doot workflow




 

.. _doot.control.main.ShutdownController:
  


.. py:class:: ShutdownController

 
   mixin for cleaning up on and shutting down doot


   .. py:attribute:: DM
      :type:  TypeAlias
      :value: DootMain


   
   .. py:method:: prepare(obj: DM) -> None



   
   .. py:method:: shutdown(obj: DM) -> None


      Doot has finished, report on what was done and how doot finished



   
   .. py:method:: install_handler(obj: DM) -> None


      Install an exit handler



   
   .. py:method:: announce_exit(message: str) -> None


      triggers speech synthesis on exiting doot



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



 

.. _doot.control.main.ErrorHandlers:
  


.. py:class:: ErrorHandlers

 
   Mixin for handling different errors of doot


   .. py:attribute:: DM
      :type:  TypeAlias
      :value: DootMain


   
   .. py:method:: discriminate_exit(obj: DootMain, err: Exception) -> int



   
   .. py:method:: _early_exit(err: doot.errors.EarlyExit | doot.errors.Interrupt | bdb.BdbQuit) -> int



   
   .. py:method:: _missing_config_exit(obj: DootMain, err: doot.errors.MissingConfigError) -> int



   
   .. py:method:: _config_error_exit(err: doot.errors.ConfigError) -> int



   
   .. py:method:: _task_failed_exit(err: doot.errors.TaskError) -> int



   
   .. py:method:: _bad_state_exit(err: doot.errors.StateError) -> int



   
   .. py:method:: _bad_struct_exit(err: doot.errors.StructLoadError) -> int



   
   .. py:method:: _tracking_exit(err: doot.errors.TrackingError) -> int



   
   .. py:method:: _backend_exit(err: doot.errors.BackendError) -> int



   
   .. py:method:: _frontend_exit(err: doot.errors.FrontendError) -> int



   
   .. py:method:: _misc_doot_exit(err: doot.errors.DootError) -> int



   
   .. py:method:: _not_implemented_exit(err: NotImplementedError) -> int



   
   .. py:method:: python_exit(err: Exception) -> int



 

.. _doot.control.main.DootMain:
  


.. py:class:: DootMain(*, cli_args: jgdv.Maybe[list] = None)

   Bases: :py:obj:`jgdv.cli.ParamSpecMaker_m` 
  
   doot.main and the associated exit handlers

   Error's if doot hasn't got an overlord (aliased as the doot package)

   loads values from the overlord config,
   sets up runtime plugin system



   .. py:attribute:: _loading
      :type:  ClassVar[LoadingController]

   .. py:attribute:: _cli
      :type:  ClassVar[CLIController]

   .. py:attribute:: _cmd
      :type:  ClassVar[CmdController]

   .. py:attribute:: _shutdown
      :type:  ClassVar[ShutdownController]

   .. py:attribute:: _err
      :type:  ClassVar[ErrorHandlers]

   .. py:attribute:: result_code
      :type:  int

   .. py:attribute:: bin_name
      :type:  str

   .. py:attribute:: prog_name
      :type:  str

   .. py:attribute:: current_cmd
      :type:  jgdv.Maybe[doot.cmds._interface.Command_p]

   .. py:attribute:: _errored
      :type:  jgdv.Maybe[Exception]

   .. py:attribute:: _help_txt
      :value: ('A Toml Specified Task Runner',)


   .. py:attribute:: parser
      :value: None


   .. py:attribute:: log_config

   .. py:property:: name
      :type: str


   
   .. py:method:: param_specs() -> list[jgdv.cli.param_spec.ParamSpec]


      The cli parameters of the main doot program.



   
   .. py:method:: help() -> str



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



   
   .. py:method:: handle_cli_args() -> jgdv.Maybe[int]


      Overlord specific cli arg responses.
      Modifies:
      - verbosity,
      - print version
      - header suppression
      - help printing
      - debugger entry

        return an int to give an override result code