Skip to content

nodes ¤

This module contains utilities for extracting information from nodes.

Classes:

  • ObjectKind –

    Enumeration of the different runtime object kinds.

  • ObjectNode –

    Helper class to represent an object tree.

Functions:

ObjectKind ¤


          flowchart TD
          griffe.agents.nodes.ObjectKind[ObjectKind]

          

          click griffe.agents.nodes.ObjectKind href "" "griffe.agents.nodes.ObjectKind"

Enumeration of the different runtime object kinds.

Attributes:

ATTRIBUTE class-attribute instance-attribute ¤

ATTRIBUTE: str = 'attribute'

Attributes.

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.

CLASS class-attribute instance-attribute ¤

CLASS: str = 'class'

Classes.

CLASSMETHOD class-attribute instance-attribute ¤

CLASSMETHOD: str = 'classmethod'

Class methods.

COROUTINE class-attribute instance-attribute ¤

COROUTINE: str = 'coroutine'

Coroutines

FUNCTION class-attribute instance-attribute ¤

FUNCTION: str = 'function'

Functions.

METHOD class-attribute instance-attribute ¤

METHOD: str = 'method'

Methods.

METHOD_DESCRIPTOR class-attribute instance-attribute ¤

METHOD_DESCRIPTOR: str = 'method_descriptor'

Method descriptors.

MODULE class-attribute instance-attribute ¤

MODULE: str = 'module'

Modules.

PROPERTY class-attribute instance-attribute ¤

PROPERTY: str = 'property'

Properties.

STATICMETHOD class-attribute instance-attribute ¤

STATICMETHOD: str = 'staticmethod'

Static methods.

ObjectNode ¤

ObjectNode(
    obj: Any, name: str, parent: ObjectNode | None = None
)

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 cached property ¤

alias_target_path: str | None

Alias target path of this node, if the node should be an alias.

children cached property ¤

children: Sequence[ObjectNode]

The children of this node.

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 cached property ¤

is_cached_property: bool

Whether this node's object is a cached property.

is_class cached property ¤

is_class: bool

Whether this node's object is a class.

is_classmethod cached property ¤

is_classmethod: bool

Whether this node's object is a classmethod.

is_coroutine cached property ¤

is_coroutine: bool

Whether this node's object is a coroutine.

is_function cached property ¤

is_function: bool

Whether this node's object is a function.

is_method cached property ¤

is_method: bool

Whether this node's object is a method.

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_module cached property ¤

is_module: bool

Whether this node's object is a module.

is_property cached property ¤

is_property: bool

Whether this node's object is a property.

is_staticmethod cached property ¤

is_staticmethod: bool

Whether this node's object is a staticmethod.

kind property ¤

kind: ObjectKind

The kind of this node.

module property ¤

module: ObjectNode

The object's module.

name instance-attribute ¤

name: str = name

The Python object's name.

obj instance-attribute ¤

obj: Any = obj

The actual Python object.

parent instance-attribute ¤

parent: ObjectNode | None = parent

The parent node.

parent_is_class cached property ¤

parent_is_class: bool

Whether the object of this node's parent is a class.

path property ¤

path: str

The object's (Python) path.

ast_children ¤

ast_children(node: AST) -> Iterator[AST]

Return the children of an AST node.

Parameters:

  • node (AST) –

    The AST node.

Yields:

  • AST –

    The node children.

ast_first_child ¤

ast_first_child(node: AST) -> AST

Return the first child of this node.

Parameters:

  • node (AST) –

    The AST node.

Raises:

Returns:

  • AST –

    The child.

ast_kind ¤

ast_kind(node: AST) -> str

Return the kind of an AST node.

Parameters:

  • node (AST) –

    The AST node.

Returns:

  • str –

    The node kind.

ast_last_child ¤

ast_last_child(node: AST) -> AST

Return the lasts child of this node.

Parameters:

  • node (AST) –

    The AST node.

Raises:

Returns:

  • AST –

    The child.

ast_next ¤

ast_next(node: AST) -> AST

Return the next sibling of this node.

Parameters:

  • node (AST) –

    The AST node.

Raises:

Returns:

  • AST –

    The sibling.

ast_next_siblings ¤

ast_next_siblings(node: AST) -> Iterator[AST]

Return the next siblings of this node, starting from the closest.

Parameters:

  • node (AST) –

    The AST node.

Yields:

  • AST –

    The next siblings.

ast_previous ¤

ast_previous(node: AST) -> AST

Return the previous sibling of this node.

Parameters:

  • node (AST) –

    The AST node.

Raises:

  • LastNodeError –

    When the node does not have previous siblings.

Returns:

  • AST –

    The sibling.

ast_previous_siblings ¤

ast_previous_siblings(node: AST) -> Iterator[AST]

Return the previous siblings of this node, starting from the closest.

Parameters:

  • node (AST) –

    The AST node.

Yields:

  • AST –

    The previous siblings.

ast_siblings ¤

ast_siblings(node: AST) -> Iterator[AST]

Return the siblings of this node.

Parameters:

  • node (AST) –

    The AST node.

Yields:

  • AST –

    The siblings.

get__all__ ¤

get__all__(
    node: Assign | AnnAssign | AugAssign, parent: Module
) -> list[str | Name]

Get the values declared in __all__.

Parameters:

Returns:

  • list[str | Name] –

    A set of names.

get_docstring ¤

get_docstring(
    node: AST, *, strict: bool = False
) -> tuple[str | None, int | None, int | None]

Extract a docstring.

Parameters:

  • node (AST) –

    The node to extract the docstring from.

  • strict (bool, default: False ) –

    Whether to skip searching the body (functions).

Returns:

  • tuple[str | None, int | None, int | None] –

    A tuple with the value and line numbers of the docstring.

get_instance_names ¤

get_instance_names(node: AST) -> list[str]

Extract names from an assignment node, only for instance attributes.

Parameters:

  • node (AST) –

    The node to extract names from.

Returns:

get_name ¤

get_name(node: AST) -> str

Extract name from an assignment node.

Parameters:

  • node (AST) –

    The node to extract names from.

Returns:

  • str –

    A list of names.

get_names ¤

get_names(node: AST) -> list[str]

Extract names from an assignment node.

Parameters:

  • node (AST) –

    The node to extract names from.

Returns:

get_value ¤

get_value(node: AST | None) -> str | None

Get the string representation of a node.

Parameters:

  • node (AST | None) –

    The node to represent.

Returns:

  • str | None –

    The representing code for the node.

relative_to_absolute ¤

relative_to_absolute(
    node: ImportFrom, name: alias, current_module: Module
) -> str

Convert a relative import path to an absolute one.

Parameters:

  • node (ImportFrom) –

    The "from ... import ..." AST node.

  • name (alias) –

    The imported name.

  • current_module (Module) –

    The module in which the import happens.

Returns:

  • str –

    The absolute import path.

safe_get__all__ ¤

safe_get__all__(
    node: Assign | AnnAssign | AugAssign,
    parent: Module,
    log_level: LogLevel = debug,
) -> list[str | Name]

Safely (no exception) extract values in __all__.

Parameters:

  • node (Assign | AnnAssign | AugAssign) –

    The __all__ assignment node.

  • parent (Module) –

    The parent used to resolve the names.

  • log_level (LogLevel, default: debug ) –

    Log level to use to log a message.

Returns:

  • list[str | Name] –

    A list of strings or resovable names.

safe_get_value ¤

safe_get_value(
    node: AST | None, filepath: str | Path | None = None
) -> str | None

Safely (no exception) get the string representation of a node.

Parameters:

  • node (AST | None) –

    The node to represent.

  • filepath (str | Path | None, default: None ) –

    An optional filepath from where the node comes.

Returns:

  • str | None –

    The representing code for the node.