mini_arcade.utils.module_loader
===============================

.. py:module:: mini_arcade.utils.module_loader

.. autoapi-nested-parse::

   Module for discovering and loading packages from a specified directory and namespace.
   This module defines the OneLevelPackageLoader class, which can be used to discover and
   load packages from a specified directory and namespace. It also defines the
   DiscoveredPackage dataclass, which represents a discovered package,
   and the load_command_packages function, which is a convenience function for loading
   command packages.



Exceptions
----------

.. autoapisummary::

   mini_arcade.utils.module_loader.ModuleDiscoveryError
   mini_arcade.utils.module_loader.ModuleImportError


Classes
-------

.. autoapisummary::

   mini_arcade.utils.module_loader.DiscoveredPackage
   mini_arcade.utils.module_loader.OneLevelPackageLoader


Functions
---------

.. autoapisummary::

   mini_arcade.utils.module_loader.load_command_packages


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

.. py:class:: DiscoveredPackage

   Represents a discovered package.

   :ivar import_name: The import name of the package
       (e.g. "mini_arcade.modules.game_runner")."
   :ivar path: The filesystem path to the package.


   .. py:attribute:: import_name
      :type:  str


   .. py:attribute:: path
      :type:  pathlib.Path


.. py:exception:: ModuleDiscoveryError

   Bases: :py:obj:`RuntimeError`


   Raised when there is an error discovering modules.


.. py:exception:: ModuleImportError

   Bases: :py:obj:`RuntimeError`


   Raised when there is an error importing modules.


.. py:class:: OneLevelPackageLoader(*, base_namespace: str, base_dir: str | pathlib.Path, require_init: bool = True, strict: bool = True, import_commands_fallback: bool = False)

   Loads packages from a specified directory and namespace.

   :param base_namespace: The base namespace for the packages (e.g. "mini_arcade.modules").
   :type base_namespace: str
   :param base_dir: The base directory to search for packages.
   :type base_dir: str | Path
   :param require_init: Whether to require an __init__.py file in each package (default: True).
   :type require_init: bool
   :param strict: Whether to raise an error if a package fails to import (default: True).
   :type strict: bool
   :param import_commands_fallback: Whether to attempt importing <package>.commands as a
       fallback (default: False).
   :type import_commands_fallback: bool


   .. py:attribute:: base_namespace


   .. py:attribute:: base_dir


   .. py:attribute:: require_init
      :value: True



   .. py:attribute:: strict
      :value: True



   .. py:attribute:: import_commands_fallback
      :value: False



   .. py:method:: discover() -> list[DiscoveredPackage]

      Discover packages in the base directory.

      :return: A list of DiscoveredPackage instances.
      :rtype: list[DiscoveredPackage]



   .. py:method:: load_all() -> list[DiscoveredPackage]

      Load all discovered packages.

      :return: A list of successfully loaded DiscoveredPackage instances.
      :rtype: list[DiscoveredPackage]
      :raises ModuleImportError: If strict is True and a package fails to import.



.. py:function:: load_command_packages(*, base_namespace: str, base_dir: str | pathlib.Path, strict: bool = True) -> list[DiscoveredPackage]

   Load command packages from the specified directory and namespace.

   :param base_namespace: The base namespace for the command packages (e.g. "mini_arcade.modules").
   :type base_namespace: str
   :param base_dir: The base directory to search for command packages.
   :type base_dir: str | Path
   :param strict: Whether to raise an error if a package fails to import (default: True).
   :type strict: bool
   :return: A list of successfully loaded DiscoveredPackage instances.
   :rtype: list[DiscoveredPackage]