find_mod_objs

plasmapy_sphinx.utils.find_mod_objs(modname: str, app: Optional[sphinx.application.Sphinx] = None) Dict[str, Dict[str, Any]]

Inspect the module modname for all the contained objects, sort for the object type (module, function, class, etc.), and return a dictionary containing object names, fully qualified names, and instances.

Parameters
  • modname (str) – Name of the module (e.g. "plasmapy_sphinx.utils') to be inspect.

  • app (Sphinx) – Instance of the Sphinx application.

Returns

mod_objs – A dictionary containing names, qualified names, and objects instances of all the objects in modname sorted by their respective group (module, class, function, etc.)

The first key of the dictionary represents the object type (modules, classes, functions, etc.). The second key is either "names" (list of all object short names), "qualnames" (list of all object qualified names), and "objs" (list of object instances).

Return type

Dict[str, Dict[str, List[Any]]]

Examples

>>> find_mod_objs("plasmapy_sphinx.utils")
{
    'functions': {
        'names': ['find_mod_objs', 'get_custom_grouping_info'],
        'qualnames': [
            'plasmapy_sphinx.utils.find_mod_objs',
            'plasmapy_sphinx.utils.get_custom_grouping_info',
        ],
        'objs': [
            <function plasmapy_sphinx.utils.find_mod_objs>,
            <function plasmapy_sphinx.utils.get_custom_grouping_info>,
        ]
    },
    'variables': {
        'names': ['default_grouping_info', 'package_dir', 'templates_dir'],
        'qualnames': [
            'plasmapy_sphinx.utils.default_grouping_info',
            'plasmapy_sphinx.utils.package_dir',
            'plasmapy_sphinx.utils.templates_dir',
        ],
        'objs': [
            OrderedDict(...),
            "/.../plasmapy_sphinx",
            "/.../plasmapy_sphinx/templates",
        ]
    }
}

Notes

If the module contains the __all__ dunder, then the routine groups the objects specified in the dunder; otherwise, it will search the module’s globals, minus any private or special members. The routing will then group the module objects in the following order…

  1. Group any imported modules or packages.

    • Regardless of if __all__ is defined, the routine will first search the module’s globals for any imported modules or packages.

    • Any 3rd party modules are excluded unless specified in __all__.

    • Any non-direct sub-modules are excluded unless specified in __all__.

  2. Custom groups defined by automodapi_custom_groups are then collected.

  3. The remaining objects are grouped into the default groupds defined by default_grouping_info.