polymerist.genutils.importutils.pkgiter ======================================= .. py:module:: polymerist.genutils.importutils.pkgiter .. autoapi-nested-parse:: Tools for iterating over and extracting information from Python package hierarchies Attributes ---------- .. autoapisummary:: polymerist.genutils.importutils.pkgiter.LOGGER polymerist.genutils.importutils.pkgiter.module_tree Classes ------- .. autoapisummary:: polymerist.genutils.importutils.pkgiter.ModuleToNodeCorrespondence Functions --------- .. autoapisummary:: polymerist.genutils.importutils.pkgiter.module_tree_direct polymerist.genutils.importutils.pkgiter.iter_submodules polymerist.genutils.importutils.pkgiter.iter_submodule_info polymerist.genutils.importutils.pkgiter.register_submodules polymerist.genutils.importutils.pkgiter.module_hierarchy Module Contents --------------- .. py:data:: LOGGER .. py:class:: ModuleToNodeCorrespondence Bases: :py:obj:`polymerist.genutils.trees.treebase.NodeCorrespondence` Concrete implementation of Python modules and packages as nodes in a tree .. py:method:: name(module: types.ModuleType) -> str Define how to obtain a string name .. py:method:: has_children(module: types.ModuleType) -> bool Define how to check if an object can produce children in the first place before attempting to do so .. py:method:: children(module: types.ModuleType) -> Iterable[types.ModuleType] Define how to obtain node children from an instance Should return NoneType if the instance is "leaf-like" .. py:data:: module_tree .. py:function:: module_tree_direct(module: types.ModuleType, recursive: bool = True, blacklist: Optional[Container[str]] = None) -> anytree.node.Node Produce a tree from the Python package hierarchy starting with a given module :Parameters: * **module** (*ModuleType*) -- The "root" module to begin importing from Represented in the Node object returned by this function * **recursive** (*bool, default=True*) -- Whether or not to recursively import modules from subpackages and add them to the tree * **blacklist** (*Container[str] (optional)*) -- List of module names to exclude from tree building If provided, will exclude any modules whose names occur in this list :returns: **modtree** -- The root node of the module tree, corresponding to the module object passed to "module" :rtype: Node .. py:function:: iter_submodules(module: types.ModuleType, recursive: bool = True, blacklist: Optional[Container[str]] = None) -> Generator[types.ModuleType, None, None] Generates all modules which can be imported from the given toplevel module :Parameters: * **module** (*ModuleType*) -- The "root" module to begin importing from Represented in the Node object returned by this function * **recursive** (*bool, default=True*) -- Whether or not to recursively import modules from subpackages and add them to the tree * **blacklist** (*Container[str] (optional)*) -- List of module names to exclude from tree building If provided, will exclude any modules whose names occur in this list :returns: **submodules** -- A generator which yields modules in traversal pre-order as they appear wihin the package hierarchy :rtype: Generator[ModuleType] .. py:function:: iter_submodule_info(module: types.ModuleType, recursive: bool = True, blacklist: Optional[Container[str]] = None) -> Generator[tuple[types.ModuleType, str, bool], None, None] Generates information about all modules which can be imported from the given toplevel module Namely, yields the module object, module name, and whether or not the module is a package :Parameters: * **module** (*ModuleType*) -- The "root" module to begin importing from Represented in the Node object returned by this function * **recursive** (*bool, default=True*) -- Whether or not to recursively import modules from subpackages and add them to the tree * **blacklist** (*Container[str] (optional)*) -- List of module names to exclude from tree building If provided, will exclude any modules whose names occur in this list :returns: **submodule_info** -- A generator which yields modules info in traversal pre-order as they appear wihin the package hierarchy yields 3-tuples containing ModuleType objects, module names, and whether the current module is also a subpackage :rtype: Generator[ModuleType, str, bool] .. py:function:: register_submodules(module: types.ModuleType, recursive: bool = True, blacklist: Optional[Container[str]] = None) -> None Registers all submodules of a given module into it's own namespace (i.e. autoimports submodules) :Parameters: * **module** (*ModuleType*) -- The "root" module to begin importing from Represented in the Node object returned by this function * **recursive** (*bool, default=True*) -- Whether or not to recursively import modules from subpackages and add them to the tree * **blacklist** (*Container[str] (optional)*) -- List of module names to exclude from tree building If provided, will exclude any modules whose names occur in this list :rtype: None .. py:function:: module_hierarchy(module: types.ModuleType, recursive: bool = True, blacklist: Optional[Container[str]] = None, style: Union[str, anytree.render.AbstractStyle] = ContStyle()) -> str Generates a printable string which summarizes a Python packages hierarchy. Reminiscent of GNU tree output :Parameters: * **module** (*ModuleType*) -- The "root" module to begin importing from Represented in the Node object returned by this function * **recursive** (*bool, default=True*) -- Whether or not to recursively import modules from subpackages and add them to the tree * **blacklist** (*Container[str] (optional)*) -- List of module names to exclude from tree building If provided, will exclude any modules whose names occur in this list * **style** (*str or AbstractStyle*) -- An element drawing style for the final tree structure printout :returns: **module_summary** -- Printable string which displays the package structure :rtype: str