inspector ¤

This module defines introspection mechanisms.

Sometimes we cannot get the source code of a module or an object, typically built-in modules like itertools. The only way to know what they are made of is to actually import them and inspect their contents.

Sometimes, even if the source code is available, loading the object is desired because it was created or modified dynamically, and our node visitor is not powerful enough to infer all these dynamic modifications. In this case, we always try to visit the code first, and only then we load the object to update the data with introspection.

This module exposes a public function, inspect(), which inspects the module using inspect.getmembers(), and returns a new Module instance, populating its members recursively, by using a NodeVisitor-like class.

The inspection agent works similarly to the regular "node visitor" agent, in that it maintains a state with the current object being handled, and recursively handle its members.

Classes:

Inspector –

This class is used to instantiate an inspector.

Functions:

inspect –

Inspect a module.

Inspector ¤

Inspector(
    module_name: str,
    filepath: Path | None,
    extensions: Extensions,
    parent: Module | None = None,
    docstring_parser: Parser | None = None,
    docstring_options: dict[str, Any] | None = None,
    lines_collection: LinesCollection | None = None,
    modules_collection: ModulesCollection | None = None,
)

This class is used to instantiate an inspector.

Inspectors iterate on objects members to extract data from them.

Parameters:

module_name (str) –

The module name.
filepath (Path | None) –

The optional filepath.
extensions (Extensions) –

Extensions to use when inspecting.
parent (Module | None, default: None ) –

The module parent.
docstring_parser (Parser | None, default: None ) –

The docstring parser to use.
docstring_options (dict[str, Any] | None, default: None ) –

The docstring parsing options.
lines_collection (LinesCollection | None, default: None ) –

A collection of source code lines.
modules_collection (ModulesCollection | None, default: None ) –

A collection of modules.

Methods:

generic_inspect –

Extend the base generic inspection with extensions.
get_module –

Build and return the object representing the module attached to this inspector.
handle_attribute –

Handle an attribute.
handle_function –

Handle a function.
inspect –

Extend the base inspection with extensions.
inspect_attribute –

Inspect an attribute.
inspect_builtin_function –

Inspect a builtin function.
inspect_builtin_method –

Inspect a builtin method.
inspect_cached_property –

Inspect a cached property.
inspect_class –

Inspect a class.
inspect_classmethod –

Inspect a class method.
inspect_coroutine –

Inspect a coroutine.
inspect_function –

Inspect a function.
inspect_method –

Inspect a method.
inspect_method_descriptor –

Inspect a method descriptor.
inspect_module –

Inspect a module.
inspect_property –

Inspect a property.
inspect_staticmethod –

Inspect a static method.

generic_inspect ¤

generic_inspect(node: ObjectNode) -> None

Extend the base generic inspection with extensions.

Parameters:

node (ObjectNode) –

The node to inspect.

get_module ¤

get_module(
    import_paths: Sequence[str | Path] | None = None,
) -> Module

Build and return the object representing the module attached to this inspector.

This method triggers a complete inspection of the module members.

Parameters:

import_paths (Sequence[str | Path] | None, default: None ) –

Paths replacing sys.path to import the module.

Returns:

Module –

A module instance.

handle_attribute ¤

handle_attribute(
    node: ObjectNode, annotation: str | Expr | None = None
) -> None

Handle an attribute.

Parameters:

node (ObjectNode) –

The node to inspect.
annotation (str | Expr | None, default: None ) –

A potentiel annotation.

handle_function ¤

handle_function(
    node: ObjectNode, labels: set | None = None
) -> None

Handle a function.

Parameters:

node (ObjectNode) –

The node to inspect.
labels (set | None, default: None ) –

Labels to add to the data object.

inspect ¤

inspect(node: ObjectNode) -> None

Extend the base inspection with extensions.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_attribute ¤

inspect_attribute(node: ObjectNode) -> None

Inspect an attribute.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_builtin_function ¤

inspect_builtin_function(node: ObjectNode) -> None

Inspect a builtin function.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_builtin_method ¤

inspect_builtin_method(node: ObjectNode) -> None

Inspect a builtin method.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_cached_property ¤

inspect_cached_property(node: ObjectNode) -> None

Inspect a cached property.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_class ¤

inspect_class(node: ObjectNode) -> None

Inspect a class.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_classmethod ¤

inspect_classmethod(node: ObjectNode) -> None

Inspect a class method.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_coroutine ¤

inspect_coroutine(node: ObjectNode) -> None

Inspect a coroutine.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_function ¤

inspect_function(node: ObjectNode) -> None

Inspect a function.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_method ¤

inspect_method(node: ObjectNode) -> None

Inspect a method.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_method_descriptor ¤

inspect_method_descriptor(node: ObjectNode) -> None

Inspect a method descriptor.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_module ¤

inspect_module(node: ObjectNode) -> None

Inspect a module.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_property ¤

inspect_property(node: ObjectNode) -> None

Inspect a property.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect_staticmethod ¤

inspect_staticmethod(node: ObjectNode) -> None

Inspect a static method.

Parameters:

node (ObjectNode) –

The node to inspect.

inspect ¤

inspect(
    module_name: str,
    *,
    filepath: Path | None = None,
    import_paths: Sequence[str | Path] | None = None,
    extensions: Extensions | None = None,
    parent: Module | None = None,
    docstring_parser: Parser | None = None,
    docstring_options: dict[str, Any] | None = None,
    lines_collection: LinesCollection | None = None,
    modules_collection: ModulesCollection | None = None
) -> Module

Inspect a module.

Parameters:

module_name (str) –

The module name (as when importing [from] it).
filepath (Path | None, default: None ) –

The module file path.
import_paths (Sequence[str | Path] | None, default: None ) –

Paths to import the module from.
extensions (Extensions | None, default: None ) –

The extensions to use when inspecting the module.
parent (Module | None, default: None ) –

The optional parent of this module.
docstring_parser (Parser | None, default: None ) –

The docstring parser to use. By default, no parsing is done.
docstring_options (dict[str, Any] | None, default: None ) –

Additional docstring parsing options.
lines_collection (LinesCollection | None, default: None ) –

A collection of source code lines.
modules_collection (ModulesCollection | None, default: None ) –

A collection of modules.

Returns:

Module –

The module, with its members populated.