Extensions¤

def generic_inspect(self, node: ObjectNode) -> None:
    """Extend the base generic inspection with extensions.

    Parameters:
        node: The node to inspect.
    """
    for child in node.children:
        if not child.alias_target_path:
            self.inspect(child)

def generic_visit(self, node: ast.AST) -> None:
    """Visit children nodes.

    Parameters:
        node: The node to visit the children of.
    """
    for child in ast_children(node):
        self.visit(child)

def inspect(self, node: ObjectNode) -> None:
    """Inspect a node.

    Parameters:
        node: The node to inspect.
    """
    getattr(self, f"inspect_{node.kind}", lambda _: None)(node)

def on_alias(self, *, alias: Alias, loader: GriffeLoader, **kwargs: Any) -> None:
    """Run on aliases once the object tree has been fully constructed.

    Note:
        This method runs once the object tree has been fully constructed:
        data is therefore complete and you can safely hook onto this event.

    Parameters:
        alias: The alias instance.
        loader: The loader currently in use.
        **kwargs: For forward-compatibility.
    """

def on_alias_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    alias: Alias,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when an Alias has been created.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        alias: The alias instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """
    if getattr(self, "__old_on_alias", False):
        self.on_alias(node=node, alias=alias, agent=agent, **kwargs)

def on_attribute(self, *, attr: Attribute, loader: GriffeLoader, **kwargs: Any) -> None:
    """Run on attributes once the object tree has been fully constructed.

    Note:
        This method runs once the object tree has been fully constructed:
        data is therefore complete and you can safely hook onto this event.

    Parameters:
        attr: The attribute instance.
        loader: The loader currently in use.
        **kwargs: For forward-compatibility.
    """

def on_attribute_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    attr: Attribute,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when an Attribute has been created.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        attr: The attribute instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_attribute_node(self, *, node: ast.AST | ObjectNode, agent: Visitor | Inspector, **kwargs: Any) -> None:
    """Run when visiting a new attribute node during static/dynamic analysis.

    Parameters:
        node: The currently visited node.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_class(self, *, cls: Class, loader: GriffeLoader, **kwargs: Any) -> None:
    """Run on classes once the object tree has been fully constructed.

    Note:
        This method runs once the object tree has been fully constructed:
        data is therefore complete and you can safely hook onto this event.

    Parameters:
        cls: The class instance.
        loader: The loader currently in use.
        **kwargs: For forward-compatibility.
    """

def on_class_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    cls: Class,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when a Class has been created.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        cls: The class instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_class_members(
    self,
    *,
    node: ast.AST | ObjectNode,
    cls: Class,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when members of a Class have been loaded.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        cls: The class instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_class_node(self, *, node: ast.AST | ObjectNode, agent: Visitor | Inspector, **kwargs: Any) -> None:
    """Run when visiting a new class node during static/dynamic analysis.

    Parameters:
        node: The currently visited node.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_function(self, *, func: Function, loader: GriffeLoader, **kwargs: Any) -> None:
    """Run on functions once the object tree has been fully constructed.

    Note:
        This method runs once the object tree has been fully constructed:
        data is therefore complete and you can safely hook onto this event.

    Parameters:
        func: The function instance.
        loader: The loader currently in use.
        **kwargs: For forward-compatibility.
    """

def on_function_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    func: Function,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when a Function has been created.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        func: The function instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_function_node(self, *, node: ast.AST | ObjectNode, agent: Visitor | Inspector, **kwargs: Any) -> None:
    """Run when visiting a new function node during static/dynamic analysis.

    Parameters:
        node: The currently visited node.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    obj: Object,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when an Object has been created.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        obj: The object instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_members(self, *, node: ast.AST | ObjectNode, obj: Object, agent: Visitor | Inspector, **kwargs: Any) -> None:
    """Run when members of an Object have been loaded.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        obj: The object instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_module(self, *, mod: Module, loader: GriffeLoader, **kwargs: Any) -> None:
    """Run on modules once the object tree has been fully constructed.

    Note:
        This method runs once the object tree has been fully constructed:
        data is therefore complete and you can safely hook onto this event.

    Parameters:
        mod: The module instance.
        loader: The loader currently in use.
        **kwargs: For forward-compatibility.
    """

def on_module_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    mod: Module,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when a Module has been created.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        mod: The module instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_module_members(
    self,
    *,
    node: ast.AST | ObjectNode,
    mod: Module,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when members of a Module have been loaded.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        mod: The module instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_module_node(self, *, node: ast.AST | ObjectNode, agent: Visitor | Inspector, **kwargs: Any) -> None:
    """Run when visiting a new module node during static/dynamic analysis.

    Parameters:
        node: The currently visited node.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_node(self, *, node: ast.AST | ObjectNode, agent: Visitor | Inspector, **kwargs: Any) -> None:
    """Run when visiting a new node during static/dynamic analysis.

    Parameters:
        node: The currently visited node.
    """

def on_object(self, *, obj: Object, loader: GriffeLoader, **kwargs: Any) -> None:
    """Run on objects (every kind) once the object tree has been fully constructed.

    Note:
        This method runs once the object tree has been fully constructed:
        data is therefore complete and you can safely hook onto this event.

    Parameters:
        obj: The object instance.
        loader: The loader currently in use.
        **kwargs: For forward-compatibility.
    """

def on_package(self, *, pkg: Module, loader: GriffeLoader, **kwargs: Any) -> None:
    """Run when a package has been completely loaded.

    Note:
        This method runs once the object tree has been fully constructed:
        data is therefore complete and you can safely hook onto this event.

    Parameters:
        pkg: The package (Module) instance.
        loader: The loader currently in use.
        **kwargs: For forward-compatibility.
    """
    # YORE: Bump 2: Remove block.
    if hasattr(self, "on_package_loaded"):
        self.on_package_loaded(pkg=pkg, loader=loader, **kwargs)

def on_type_alias(self, *, type_alias: TypeAlias, loader: GriffeLoader, **kwargs: Any) -> None:
    """Run on type aliases once the object tree has been fully constructed.

    Note:
        This method runs once the object tree has been fully constructed:
        data is therefore complete and you can safely hook onto this event.

    Parameters:
        type_alias: The type alias instance.
        loader: The loader currently in use.
        **kwargs: For forward-compatibility.
    """

def on_type_alias_instance(
    self,
    *,
    node: ast.AST | ObjectNode,
    type_alias: TypeAlias,
    agent: Visitor | Inspector,
    **kwargs: Any,
) -> None:
    """Run when a TypeAlias has been created.

    Warning:
        This method runs while the object tree is still being constructed:
        data might be incomplete (class inheritance, alias resolution, etc.).
        Only hook onto this event if you know what you're doing.

    Parameters:
        node: The currently visited node.
        type_alias: The type alias instance.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def on_type_alias_node(self, *, node: ast.AST | ObjectNode, agent: Visitor | Inspector, **kwargs: Any) -> None:
    """Run when visiting a new type alias node during static/dynamic analysis.

    Parameters:
        node: The currently visited node.
        agent: The analysis agent currently running.
        **kwargs: For forward-compatibility.
    """

def visit(self, node: ast.AST) -> None:
    """Visit a node.

    Parameters:
        node: The node to visit.
    """
    getattr(self, f"visit_{ast_kind(node)}", lambda _: None)(node)

def add(self, *extensions: Extension) -> None:
    """Add extensions to this container.

    Parameters:
        *extensions: The extensions to add.
    """
    for extension in extensions:
        self._extensions.append(extension)

def call(self, event: str, **kwargs: Any) -> None:
    """Call the extension hook for the given event.

    Parameters:
        event: The triggered event.
        **kwargs: Arguments passed to the hook.
    """
    for extension in self._extensions:
        # YORE: Bump 2: Replace block with line 5.
        if event == "on_alias" and getattr(extension, "__old_on_alias", False):
            with suppress(TypeError):
                getattr(extension, event)(**kwargs)
        else:
            getattr(extension, event, self._noop)(**kwargs)

def on_package(self, *, pkg: Module, **kwargs: Any) -> None:  # noqa: ARG002
    """Hook for loaded packages.

    Parameters:
        pkg: The loaded package.
    """
    _apply_recursively(pkg, set())

def on_class(self, *, cls: Class, **kwargs: Any) -> None:  # noqa: ARG002
    """Add an `__init__` method to `TypedDict` classes if missing."""
    for base in cls.bases:
        if isinstance(base, Expr) and base.canonical_path in {"typing.TypedDict", "typing_extensions.TypedDict"}:
            cls.labels.add("typed-dict")
            break
    else:
        return

    required, optional = _get_or_set_attrs(cls)

    if "__init__" not in cls.members:
        # Build the `__init__` method and add it to the class.
        parameters = Parameters(
            Parameter(name="self", kind=ParameterKind.positional_or_keyword),
            *_params_from_attrs(required, optional),
        )
        # TODO: Add `**kwargs` parameter if extra items are allowed.
        init = Function(name="__init__", parameters=parameters, returns="None")
        cls.set_member("__init__", init)
        # Update the `__init__` docstring.
        _update_docstring(init, required, optional)

    # Remove attributes from the class, as they are now in the `__init__` method.
    for attr in chain(required, optional):
        cls.del_member(attr["name"])

def on_function(self, *, func: Function, **kwargs: Any) -> None:  # noqa: ARG002
    """Expand `**kwargs: Unpack[TypedDict]` in function signatures."""
    # Find any `**kwargs: Unpack[TypedDict]` parameter.
    for parameter in func.parameters:
        if parameter.kind is ParameterKind.var_keyword:
            annotation = parameter.annotation
            if isinstance(annotation, ExprSubscript) and annotation.canonical_path in {
                "typing.Annotated",
                "typing_extensions.Annotated",
            }:
                annotation = annotation.slice.elements[0]  # type: ignore[union-attr]
            if isinstance(annotation, ExprSubscript) and annotation.canonical_path in {
                "typing.Unpack",
                "typing_extensions.Unpack",
            }:
                slice_path = annotation.slice.canonical_path  # type: ignore[union-attr]
                typed_dict = func.modules_collection[slice_path]
                break
    else:
        return

    required, optional = _get_or_set_attrs(typed_dict)

    # Update any parameter section in the docstring.
    # We do this before updating the signature so that
    # parsing the docstring doesn't emit warnings.
    _update_docstring(func, required, optional, parameter)

    # Update the function parameters.
    del func.parameters[parameter.name]
    for param in _params_from_attrs(required, optional):
        func.parameters[param.name] = Parameter(
            name=param.name,
            annotation=param.annotation,
            kind=ParameterKind.keyword_only,
            default=param.default,
            docstring=param.docstring,
        )