Agents¤
Griffe is able to analyze code both statically and dynamically.
Main API¤
visit ¤
visit(
module_name: str,
filepath: Path,
code: str,
*,
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
Parse and visit a module file.
We provide this function for static analysis. It uses a NodeVisitor
-like class, the Visitor
, to compile and parse code (using compile
) then visit the resulting AST (Abstract Syntax Tree).
Important
This function is generally not used directly. In most cases, users can rely on the GriffeLoader
and its accompanying load
shortcut and their respective options to load modules using static analysis.
Parameters:
-
module_name
¤str
) –The module name (as when importing [from] it).
-
filepath
¤Path
) –The module file path.
-
code
¤str
) –The module contents.
-
extensions
¤Extensions | None
, default:None
) –The extensions to use when visiting the AST.
-
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.
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.
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 static agent is not powerful enough to infer all these dynamic modifications. In this case, we load the module using introspection.
Griffe therefore provides this function for dynamic analysis. It uses a NodeVisitor
-like class, the Inspector
, to inspect the module with inspect.getmembers()
.
The inspection agent works similarly to the regular Visitor
agent, in that it maintains a state with the current object being handled, and recursively handle its members.
Important
This function is generally not used directly. In most cases, users can rely on the GriffeLoader
and its accompanying load
shortcut and their respective options to load modules using dynamic analysis.
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.
Advanced API¤
Visitor ¤
Visitor(
module_name: str,
filepath: Path,
code: str,
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 a visitor.
Visitors iterate on AST nodes to extract data from them.
Parameters:
-
module_name
¤str
) –The module name.
-
filepath
¤Path
) –The module filepath.
-
code
¤str
) –The module source code.
-
extensions
¤Extensions
) –The extensions to use when visiting.
-
parent
¤Module | None
, default:None
) –An optional parent for the final module object.
-
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:
-
decorators_to_labels
–Build and return a set of labels based on decorators.
-
generic_visit
–Extend the base generic visit with extensions.
-
get_base_property
–Check decorators to return the base property in case of setters and deleters.
-
get_module
–Build and return the object representing the module attached to this visitor.
-
handle_attribute
–Handle an attribute (assignment) node.
-
handle_function
–Handle a function definition node.
-
visit
–Extend the base visit with extensions.
-
visit_annassign
–Visit an annotated assignment node.
-
visit_assign
–Visit an assignment node.
-
visit_asyncfunctiondef
–Visit an async function definition node.
-
visit_augassign
–Visit an augmented assignment node.
-
visit_classdef
–Visit a class definition node.
-
visit_functiondef
–Visit a function definition node.
-
visit_if
–Visit an "if" node.
-
visit_import
–Visit an import node.
-
visit_importfrom
–Visit an "import from" node.
-
visit_module
–Visit a module node.
Attributes:
-
code
(str
) –The module source code.
-
current
(Module | Class
) –The current object being visited.
-
docstring_options
(dict[str, Any]
) –The docstring parsing options.
-
docstring_parser
(Parser | None
) –The docstring parser to use.
-
extensions
(Extensions
) –The extensions to use when visiting the AST.
-
filepath
(Path
) –The module filepath.
-
lines_collection
(LinesCollection
) –A collection of source code lines.
-
module_name
(str
) –The module name.
-
modules_collection
(ModulesCollection
) –A collection of modules.
-
parent
(Module | None
) –An optional parent for the final module object.
-
type_guarded
(bool
) –Whether the current code branch is type-guarded.
docstring_options instance-attribute
¤
docstring_options: dict[str, Any] = docstring_options or {}
The docstring parsing options.
docstring_parser instance-attribute
¤
docstring_parser: Parser | None = docstring_parser
The docstring parser to use.
extensions instance-attribute
¤
extensions: Extensions = extensions
The extensions to use when visiting the AST.
lines_collection instance-attribute
¤
lines_collection: LinesCollection = (
lines_collection or LinesCollection()
)
A collection of source code lines.
modules_collection instance-attribute
¤
modules_collection: ModulesCollection = (
modules_collection or ModulesCollection()
)
A collection of modules.
parent instance-attribute
¤
An optional parent for the final module object.
type_guarded instance-attribute
¤
type_guarded: bool = False
Whether the current code branch is type-guarded.
generic_visit ¤
get_base_property ¤
get_base_property(
decorators: list[Decorator], function: Function
) -> str | None
Check decorators to return the base property in case of setters and deleters.
Parameters:
Returns:
get_module ¤
get_module() -> Module
Build and return the object representing the module attached to this visitor.
This method triggers a complete visit of the module nodes.
Returns:
-
Module
–A module instance.
handle_attribute ¤
handle_function ¤
handle_function(
node: AsyncFunctionDef | FunctionDef,
labels: set | None = None,
) -> None
Handle a function definition node.
Parameters:
-
node
¤AsyncFunctionDef | FunctionDef
) –The node to visit.
-
labels
¤set | None
, default:None
) –Labels to add to the data object.
visit ¤
visit_annassign ¤
visit_assign ¤
visit_asyncfunctiondef ¤
visit_asyncfunctiondef(node: AsyncFunctionDef) -> None
visit_augassign ¤
visit_classdef ¤
visit_functiondef ¤
visit_functiondef(node: FunctionDef) -> None
visit_if ¤
visit_import ¤
visit_importfrom ¤
visit_importfrom(node: ImportFrom) -> None
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.
Attributes:
-
current
(Module | Class
) –The current object being inspected.
-
docstring_options
(dict[str, Any]
) –The docstring parsing options.
-
docstring_parser
(Parser | None
) –The docstring parser to use.
-
extensions
(Extensions
) –The extensions to use when inspecting.
-
filepath
(Path | None
) –The module file path.
-
lines_collection
(LinesCollection
) –A collection of source code lines.
-
module_name
(str
) –The module name.
-
modules_collection
(ModulesCollection
) –A collection of modules.
-
parent
(Module | None
) –An optional parent for the final module object.
docstring_options instance-attribute
¤
docstring_options: dict[str, Any] = docstring_options or {}
The docstring parsing options.
docstring_parser instance-attribute
¤
docstring_parser: Parser | None = docstring_parser
The docstring parser to use.
extensions instance-attribute
¤
extensions: Extensions = extensions
The extensions to use when inspecting.
lines_collection instance-attribute
¤
lines_collection: LinesCollection = (
lines_collection or LinesCollection()
)
A collection of source code lines.
modules_collection instance-attribute
¤
modules_collection: ModulesCollection = (
modules_collection or ModulesCollection()
)
A collection of modules.
parent instance-attribute
¤
An optional parent for the final module object.
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 potential 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
inspect_attribute ¤
inspect_attribute(node: ObjectNode) -> None
inspect_builtin_function ¤
inspect_builtin_function(node: ObjectNode) -> None
inspect_builtin_method ¤
inspect_builtin_method(node: ObjectNode) -> None
inspect_cached_property ¤
inspect_cached_property(node: ObjectNode) -> None
inspect_class ¤
inspect_class(node: ObjectNode) -> None
inspect_classmethod ¤
inspect_classmethod(node: ObjectNode) -> None
inspect_coroutine ¤
inspect_coroutine(node: ObjectNode) -> None
inspect_function ¤
inspect_function(node: ObjectNode) -> None
inspect_method ¤
inspect_method(node: ObjectNode) -> None
inspect_method_descriptor ¤
inspect_method_descriptor(node: ObjectNode) -> None
inspect_module ¤
inspect_module(node: ObjectNode) -> None
inspect_property ¤
inspect_property(node: ObjectNode) -> None
inspect_staticmethod ¤
inspect_staticmethod(node: ObjectNode) -> None
Dynamic analysis helpers¤
sys_path ¤
dynamic_import ¤
dynamic_import(
import_path: str,
import_paths: Sequence[str | Path] | None = None,
) -> Any
Dynamically import the specified object.
It can be a module, class, method, function, attribute, nested arbitrarily.
It works like this:
- for a given object path
a.b.x.y
- it tries to import
a.b.x.y
as a module (withimportlib.import_module
) - if it fails, it tries again with
a.b.x
, storingy
- then
a.b
, storingx.y
- then
a
, storingb.x.y
- if nothing worked, it raises an error
- if one of the iteration worked, it moves on, and...
- it tries to get the remaining (stored) parts with
getattr
- for example it gets
b
froma
, thenx
fromb
, etc. - if a single attribute access fails, it raises an error
- if everything worked, it returns the last obtained attribute
Since the function potentially tries multiple things before succeeding, all errors happening along the way are recorded, and re-emitted with an ImportError
when it fails, to let users know what was tried.
Important
The paths given through the import_paths
parameter are used to temporarily patch sys.path
: this function is therefore not thread-safe.
Important
The paths given as import_paths
must be correct. The contents of sys.path
must be consistent to what a user of the imported code would expect. Given a set of paths, if the import fails for a user, it will fail here too, with potentially unintuitive errors. If we wanted to make this function more robust, we could add a loop to "roll the window" of given paths, shifting them to the left (for example: ("/a/a", "/a/b", "/a/c/")
, then ("/a/b", "/a/c", "/a/a/")
, then ("/a/c", "/a/a", "/a/b/")
), to make sure each entry is given highest priority at least once, maintaining relative order, but we deem this unnecessary for now.
Parameters:
-
import_path
¤str
) –The path of the object to import.
-
import_paths
¤Sequence[str | Path] | None
, default:None
) –The (sys) paths to import the object from.
Raises:
-
ModuleNotFoundError
–When the object's module could not be found.
-
ImportError
–When there was an import error or when couldn't get the attribute.
Returns:
-
Any
–The imported object.
ObjectNode ¤
Helper class to represent an object tree.
It's not really a tree but more a backward-linked list: each node has a reference to its parent, but not to its child (for simplicity purposes and to avoid bugs).
Each node stores an object, its name, and a reference to its parent node.
Parameters:
-
obj
¤Any
) –A Python object.
-
name
¤str
) –The object's name.
-
parent
¤ObjectNode | None
, default:None
) –The object's parent node.
Attributes:
-
alias_target_path
(str | None
) –Alias target path of this node, if the node should be an alias.
-
children
(Sequence[ObjectNode]
) –The children of this node.
-
exclude_specials
(set[str]
) –Low level attributes known to cause issues when resolving aliases.
-
is_builtin_function
(bool
) –Whether this node's object is a builtin function.
-
is_builtin_method
(bool
) –Whether this node's object is a builtin method.
-
is_cached_property
(bool
) –Whether this node's object is a cached property.
-
is_class
(bool
) –Whether this node's object is a class.
-
is_classmethod
(bool
) –Whether this node's object is a classmethod.
-
is_coroutine
(bool
) –Whether this node's object is a coroutine.
-
is_function
(bool
) –Whether this node's object is a function.
-
is_method
(bool
) –Whether this node's object is a method.
-
is_method_descriptor
(bool
) –Whether this node's object is a method descriptor.
-
is_module
(bool
) –Whether this node's object is a module.
-
is_property
(bool
) –Whether this node's object is a property.
-
is_staticmethod
(bool
) –Whether this node's object is a staticmethod.
-
kind
(ObjectKind
) –The kind of this node.
-
module
(ObjectNode
) –The object's module, fetched from the node tree.
-
module_path
(str | None
) –The object's module path.
-
name
(str
) –The Python object's name.
-
obj
(Any
) –The actual Python object.
-
parent
(ObjectNode | None
) –The parent node.
-
parent_is_class
(bool
) –Whether the object of this node's parent is a class.
-
path
(str
) –The object's (Python) path.
alias_target_path cached
property
¤
alias_target_path: str | None
Alias target path of this node, if the node should be an alias.
exclude_specials class-attribute
¤
Low level attributes known to cause issues when resolving aliases.
is_builtin_function cached
property
¤
is_builtin_function: bool
Whether this node's object is a builtin function.
is_builtin_method cached
property
¤
is_builtin_method: bool
Whether this node's object is a builtin method.
is_cached_property instance-attribute
¤
is_cached_property: bool = is_cached_property
Whether this node's object is a cached property.
is_method_descriptor cached
property
¤
is_method_descriptor: bool
Whether this node's object is a method descriptor.
Built-in methods (e.g. those implemented in C/Rust) are often method descriptors, rather than normal methods.
is_staticmethod cached
property
¤
is_staticmethod: bool
Whether this node's object is a staticmethod.
ObjectKind ¤
flowchart TD
griffe.ObjectKind[ObjectKind]
click griffe.ObjectKind href "" "griffe.ObjectKind"
Enumeration of the different runtime object kinds.
Attributes:
-
ATTRIBUTE
(str
) –Attributes.
-
BUILTIN_FUNCTION
(str
) –Built-in functions.
-
BUILTIN_METHOD
(str
) –Built-in ethods.
-
CACHED_PROPERTY
(str
) –Cached properties.
-
CLASS
(str
) –Classes.
-
CLASSMETHOD
(str
) –Class methods.
-
COROUTINE
(str
) –Coroutines
-
FUNCTION
(str
) –Functions.
-
METHOD
(str
) –Methods.
-
METHOD_DESCRIPTOR
(str
) –Method descriptors.
-
MODULE
(str
) –Modules.
-
PROPERTY
(str
) –Properties.
-
STATICMETHOD
(str
) –Static methods.
BUILTIN_FUNCTION class-attribute
instance-attribute
¤
BUILTIN_FUNCTION: str = 'builtin_function'
Built-in functions.
BUILTIN_METHOD class-attribute
instance-attribute
¤
BUILTIN_METHOD: str = 'builtin_method'
Built-in ethods.
CACHED_PROPERTY class-attribute
instance-attribute
¤
CACHED_PROPERTY: str = 'cached_property'
Cached properties.
Static analysis helpers¤
builtin_decorators module-attribute
¤
builtin_decorators = {
"property": "property",
"staticmethod": "staticmethod",
"classmethod": "classmethod",
}
Mapping of builtin decorators to labels.
stdlib_decorators module-attribute
¤
stdlib_decorators = {
"abc.abstractmethod": {"abstractmethod"},
"functools.cache": {"cached"},
"functools.cached_property": {"cached", "property"},
"cached_property.cached_property": {
"cached",
"property",
},
"functools.lru_cache": {"cached"},
"dataclasses.dataclass": {"dataclass"},
}
Mapping of standard library decorators to labels.
typing_overload module-attribute
¤
typing_overload = {
"typing.overload",
"typing_extensions.overload",
}
Set of recognized typing overload decorators.
When such a decorator is found, the decorated function becomes an overload.
ast_kind ¤
ast_children ¤
ast_previous_siblings ¤
ast_next_siblings ¤
ast_siblings ¤
ast_previous ¤
Return the previous sibling of this node.
Parameters:
Raises:
-
LastNodeError
–When the node does not have previous siblings.
Returns:
-
AST
–The sibling.
ast_next ¤
Return the next sibling of this node.
Parameters:
Raises:
-
LastNodeError
–When the node does not have next siblings.
Returns:
-
AST
–The sibling.
ast_first_child ¤
Return the first child of this node.
Parameters:
Raises:
-
LastNodeError
–When the node does not have children.
Returns:
-
AST
–The child.
ast_last_child ¤
Return the lasts child of this node.
Parameters:
Raises:
-
LastNodeError
–When the node does not have children.
Returns:
-
AST
–The child.
get_docstring ¤
get_name ¤
get_names ¤
get_instance_names ¤
get__all__ ¤
safe_get__all__ ¤
safe_get__all__(
node: Assign | AnnAssign | AugAssign,
parent: Module,
log_level: LogLevel = debug,
) -> list[str | ExprName]
relative_to_absolute ¤
relative_to_absolute(
node: ImportFrom, name: alias, current_module: Module
) -> str
get_value ¤
safe_get_value ¤
Deprecated API¤
ExportedName dataclass
¤
Deprecated. An intermediate class to store names.
The get__all__
function now returns instances of ExprName
instead.
Attributes: