agglovar.dev.imports
====================

.. py:module:: agglovar.dev.imports

.. autoapi-nested-parse::

   General development utilities.



Classes
-------

.. autoapisummary::

   agglovar.dev.imports.GlobalImport


Functions
---------

.. autoapisummary::

   agglovar.dev.imports.alias_to_obj_dict
   agglovar.dev.imports.find_imports
   agglovar.dev.imports.get_defined_names
   agglovar.dev.imports.get_module_definitions
   agglovar.dev.imports.librl


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

.. py:class:: GlobalImport

   Mantains a stack of import frames.


   .. py:method:: __bool__() -> bool

      Determine if the stack is non-empty.



   .. py:method:: __len__() -> int

      Get the number of stack items.



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

      Clear all scopes.



   .. py:method:: pop() -> bool

      Pop the last scope from the stack and restore the global scope to the state before it was applied.

      :returns: True if a scope was popped, False if the global import stack is empty.



   .. py:method:: push(package_path: str, import_statements: Optional[str] = None, overwrite: bool = True, mod_imports: bool = True, mod_private: bool = True, mod_dunder: bool = False) -> None

      Push a new scope to the global import stack and update the global scope.

      :param package_path: Name of the module where this import statement is found (e.g. 'pav3.lgsv.interval' if
          the import statements are in 'pav3/lgsv/interval.py').
      :param import_statements: A string of newline-separated import statements.
      :param overwrite: Whether to overwrite existing global variables.
      :param mod_imports: Whether to import objects from modules.
      :param mod_private: Whether to import private objects from modules.
      :param mod_dunder: Whether to import dunder objects from modules.



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

      Undo and re-do all scopes.

      Run when objects might have changed.



   .. py:attribute:: caller_globals


   .. py:attribute:: import_stack
      :value: []



.. py:function:: alias_to_obj_dict(package_path: str, import_statements: Optional[str] = None, mod_imports: bool = True, mod_private: bool = True, mod_dunder: bool = False) -> dict[str, Any]

   Find objects for relative imports.

   :param package_path: Name of the module where this import statement is found (i.e. 'pav3.lgsv.interval' if the).
   :param import_statements: A string of newline-separated import statements.
   :param mod_imports: Whether to import objects from modules.
   :param mod_private: Whether to import private objects from modules.
   :param mod_dunder: Whether to import dunder objects from modules.

   :returns: A set of new global names that were imported.


.. py:function:: find_imports(module_name: str, public_only: bool = True, all_only: bool = False) -> set[str]

   Locate objects defined in a module.

   :param module_name: Name of the module to inspect.
   :param public_only: Whether to include only public objects (i.e. not starting with '_').
   :param all_only: Whether to include only objects defined in '__all__'. Overrides public_only if __all__ has values.

   :returns: Set of object names defined in the module.


.. py:function:: get_defined_names(mod: types.ModuleType)

   Get names defined in a module.

   :param mod: Module to inspect.

   :yields: Tuples of (name, type, level) where "type" is "func", "class", "def", or "import". "level" is defined for
       imports (None for others) and is the level of the import with 0 being the top-level and 1 or more being a
       relative import.


.. py:function:: get_module_definitions(module: types.ModuleType, include_dunder: bool = False) -> Generator[str, None, None]

   Get names defined in a module object ignoring imports.

   :param module: Module object to inspect.
   :param include_dunder: Whether to include dunder objects (starting with '__').


.. py:function:: librl(packages: collections.abc.Iterable[str] | str = 'agglovar') -> None

   Reload libraries.

   Reloads all modules in the given packages and their dependencies. Attempts to resolve import
   order by inspecting members of each package.

   :param packages: Names of packages to reload. Must be top-level package names (name
       before the first dot).