Agents¤

def decorators_to_labels(self, decorators: list[Decorator]) -> set[str]:
    """Build and return a set of labels based on decorators.

    Parameters:
        decorators: The decorators to check.

    Returns:
        A set of labels.
    """
    labels = set()
    for decorator in decorators:
        callable_path = decorator.callable_path
        if callable_path in builtin_decorators:
            labels.add(builtin_decorators[callable_path])
        elif callable_path in stdlib_decorators:
            labels |= stdlib_decorators[callable_path]
    return labels

def generic_visit(self, node: ast.AST) -> None:
    """Extend the base generic visit with extensions.

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

def get_base_property(self, decorators: list[Decorator], function: Function) -> str | None:
    """Check decorators to return the base property in case of setters and deleters.

    Parameters:
        decorators: The decorators to check.

    Returns:
        base_property: The property for which the setter/deleted is set.
        property_function: Either `"setter"` or `"deleter"`.
    """
    for decorator in decorators:
        try:
            path, prop_function = decorator.callable_path.rsplit(".", 1)
        except ValueError:
            continue
        property_setter_or_deleter = (
            prop_function in {"setter", "deleter"}
            and path == function.path
            and self.current.get_member(function.name).has_labels("property")
        )
        if property_setter_or_deleter:
            return prop_function
    return None

def get_module(self) -> Module:
    """Build and return the object representing the module attached to this visitor.

    This method triggers a complete visit of the module nodes.

    Returns:
        A module instance.
    """
    # Optimization: equivalent to `ast.parse`, but with `optimize=1` to remove assert statements.
    # TODO: With options, could use `optimize=2` to remove docstrings.
    top_node = compile(self.code, mode="exec", filename=str(self.filepath), flags=ast.PyCF_ONLY_AST, optimize=1)
    self.visit(top_node)
    return self.current.module

def handle_attribute(
    self,
    node: ast.Assign | ast.AnnAssign,
    annotation: str | Expr | None = None,
) -> None:
    """Handle an attribute (assignment) node.

    Parameters:
        node: The node to visit.
        annotation: A potential annotation.
    """
    self.extensions.call("on_node", node=node, agent=self)
    self.extensions.call("on_attribute_node", node=node, agent=self)
    parent = self.current
    labels = set()
    names = None

    if parent.kind is Kind.MODULE:
        try:
            names = get_names(node)
        except KeyError:  # Unsupported nodes, like subscript.
            return
        labels.add("module-attribute")
    elif parent.kind is Kind.CLASS:
        try:
            names = get_names(node)
        except KeyError:  # Unsupported nodes, like subscript.
            return

        if isinstance(annotation, Expr) and annotation.is_classvar:
            # Explicit `ClassVar`: class attribute only.
            annotation = annotation.slice  # type: ignore[attr-defined]
            labels.add("class-attribute")
        elif node.value:
            # Attribute assigned at class-level: available in instances as well.
            labels.add("class-attribute")
            labels.add("instance-attribute")
        else:
            # Annotated attribute only: not available at class-level.
            labels.add("instance-attribute")

    elif parent.kind is Kind.FUNCTION:
        if parent.name != "__init__":
            return
        try:
            names = get_instance_names(node)
        except KeyError:  # Unsupported nodes, like subscript.
            return
        parent = parent.parent  # type: ignore[assignment]
        if parent is None:
            return
        labels.add("instance-attribute")

    if not names:
        return

    value = safe_get_expression(node.value, parent=self.current, parse_strings=False)

    try:
        docstring = self._get_docstring(ast_next(node), strict=True)
    except (LastNodeError, AttributeError):
        docstring = None

    for name in names:
        # TODO: Handle assigns like `x.y = z`.
        # We need to resolve `x.y` and add `z` in its members.
        if "." in name:
            continue

        if name in parent.members:
            # Assigning multiple times.
            # TODO: Might be better to inspect.
            if isinstance(node.parent, (ast.If, ast.ExceptHandler)):  # type: ignore[union-attr]
                continue  # Prefer "no-exception" case.

            existing_member = parent.members[name]
            with suppress(AliasResolutionError, CyclicAliasError):
                labels |= existing_member.labels
                # Forward previous docstring and annotation instead of erasing them.
                if existing_member.docstring and not docstring:
                    docstring = existing_member.docstring
                with suppress(AttributeError):
                    if existing_member.annotation and not annotation:  # type: ignore[union-attr]
                        annotation = existing_member.annotation  # type: ignore[union-attr]

        attribute = Attribute(
            name=name,
            value=value,
            annotation=annotation,
            lineno=node.lineno,
            endlineno=node.end_lineno,
            docstring=docstring,
            runtime=not self.type_guarded,
            analysis="static",
        )
        attribute.labels |= labels
        parent.set_member(name, attribute)

        if name == "__all__":
            with suppress(AttributeError):
                parent.exports = [
                    name if isinstance(name, str) else ExprName(name.name, parent=name.parent)
                    for name in safe_get__all__(node, self.current)  # type: ignore[arg-type]
                ]
        self.extensions.call("on_instance", node=node, obj=attribute, agent=self)
        self.extensions.call("on_attribute_instance", node=node, attr=attribute, agent=self)

def handle_function(self, node: ast.AsyncFunctionDef | ast.FunctionDef, labels: set | None = None) -> None:
    """Handle a function definition node.

    Parameters:
        node: The node to visit.
        labels: Labels to add to the data object.
    """
    self.extensions.call("on_node", node=node, agent=self)
    self.extensions.call("on_function_node", node=node, agent=self)

    labels = labels or set()

    # Handle decorators.
    decorators = []
    overload = False
    if node.decorator_list:
        lineno = node.decorator_list[0].lineno
        for decorator_node in node.decorator_list:
            decorator_value = safe_get_expression(decorator_node, parent=self.current, parse_strings=False)
            if decorator_value is None:
                continue
            decorator = Decorator(
                decorator_value,
                lineno=decorator_node.lineno,
                endlineno=decorator_node.end_lineno,
            )
            decorators.append(decorator)
            overload |= decorator.callable_path in typing_overload
    else:
        lineno = node.lineno

    labels |= self.decorators_to_labels(decorators)

    if "property" in labels:
        attribute = Attribute(
            name=node.name,
            value=None,
            annotation=safe_get_annotation(node.returns, parent=self.current, member=node.name),
            lineno=node.lineno,
            endlineno=node.end_lineno,
            docstring=self._get_docstring(node),
            runtime=not self.type_guarded,
            analysis="static",
        )
        attribute.labels |= labels
        self.current.set_member(node.name, attribute)
        self.extensions.call("on_instance", node=node, obj=attribute, agent=self)
        self.extensions.call("on_attribute_instance", node=node, attr=attribute, agent=self)
        return

    # Handle parameters.
    parameters = Parameters(
        *[
            Parameter(
                name,
                kind=kind,
                annotation=safe_get_annotation(annotation, parent=self.current, member=node.name),
                default=default
                if isinstance(default, str)
                else safe_get_expression(default, parent=self.current, parse_strings=False),
            )
            for name, annotation, kind, default in get_parameters(node.args)
        ],
    )

    function = Function(
        name=node.name,
        lineno=lineno,
        endlineno=node.end_lineno,
        parameters=parameters,
        returns=safe_get_annotation(node.returns, parent=self.current, member=node.name),
        decorators=decorators,
        type_parameters=TypeParameters(*self._get_type_parameters(node, scope=node.name)),
        docstring=self._get_docstring(node),
        runtime=not self.type_guarded,
        parent=self.current,
        analysis="static",
    )

    property_function = self.get_base_property(decorators, function)

    if overload:
        self.current.overloads[function.name].append(function)
    elif property_function:
        base_property: Attribute = self.current.members[node.name]  # type: ignore[assignment]
        if property_function == "setter":
            base_property.setter = function
            base_property.labels.add("writable")
        elif property_function == "deleter":
            base_property.deleter = function
            base_property.labels.add("deletable")
    else:
        self.current.set_member(node.name, function)
        if self.current.kind in {Kind.MODULE, Kind.CLASS} and self.current.overloads[function.name]:
            function.overloads = self.current.overloads[function.name]
            del self.current.overloads[function.name]

    function.labels |= labels

    self.extensions.call("on_instance", node=node, obj=function, agent=self)
    self.extensions.call("on_function_instance", node=node, func=function, agent=self)
    if self.current.kind is Kind.CLASS and function.name == "__init__":
        self.current = function  # type: ignore[assignment]
        self.generic_visit(node)
        self.current = self.current.parent  # type: ignore[assignment]

def visit(self, node: ast.AST) -> None:
    """Extend the base visit with extensions.

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

def visit_annassign(self, node: ast.AnnAssign) -> None:
    """Visit an annotated assignment node.

    Parameters:
        node: The node to visit.
    """
    self.handle_attribute(node, safe_get_annotation(node.annotation, parent=self.current))

def visit_assign(self, node: ast.Assign) -> None:
    """Visit an assignment node.

    Parameters:
        node: The node to visit.
    """
    self.handle_attribute(node)

def visit_asyncfunctiondef(self, node: ast.AsyncFunctionDef) -> None:
    """Visit an async function definition node.

    Parameters:
        node: The node to visit.
    """
    self.handle_function(node, labels={"async"})

def visit_augassign(self, node: ast.AugAssign) -> None:
    """Visit an augmented assignment node.

    Parameters:
        node: The node to visit.
    """
    with suppress(AttributeError):
        all_augment = (
            node.target.id == "__all__"  # type: ignore[union-attr]
            and self.current.is_module
            and isinstance(node.op, ast.Add)
        )
        if all_augment:
            # We assume `exports` is not `None` at this point.
            self.current.exports.extend(  # type: ignore[union-attr]
                [
                    name if isinstance(name, str) else ExprName(name.name, parent=name.parent)
                    for name in safe_get__all__(node, self.current)  # type: ignore[arg-type]
                ],
            )

def visit_classdef(self, node: ast.ClassDef) -> None:
    """Visit a class definition node.

    Parameters:
        node: The node to visit.
    """
    self.extensions.call("on_node", node=node, agent=self)
    self.extensions.call("on_class_node", node=node, agent=self)

    # Handle decorators.
    decorators: list[Decorator] = []
    if node.decorator_list:
        lineno = node.decorator_list[0].lineno
        decorators.extend(
            Decorator(
                safe_get_expression(decorator_node, parent=self.current, parse_strings=False),  # type: ignore[arg-type]
                lineno=decorator_node.lineno,
                endlineno=decorator_node.end_lineno,
            )
            for decorator_node in node.decorator_list
        )
    else:
        lineno = node.lineno

    # Handle base classes and keywords.
    bases = [safe_get_base_class(base, parent=self.current, member=node.name) for base in node.bases]
    keywords = {
        kw.arg: safe_get_class_keyword(kw.value, parent=self.current) for kw in node.keywords if kw.arg is not None
    }

    class_ = Class(
        name=node.name,
        lineno=lineno,
        endlineno=node.end_lineno,
        docstring=self._get_docstring(node),
        decorators=decorators,
        type_parameters=TypeParameters(*self._get_type_parameters(node, scope=node.name)),
        bases=bases,  # type: ignore[arg-type]
        keywords=keywords,
        runtime=not self.type_guarded,
        analysis="static",
    )
    class_.labels |= self.decorators_to_labels(decorators)

    self.current.set_member(node.name, class_)
    self.current = class_
    self.extensions.call("on_instance", node=node, obj=class_, agent=self)
    self.extensions.call("on_class_instance", node=node, cls=class_, agent=self)
    self.generic_visit(node)
    self.extensions.call("on_members", node=node, obj=class_, agent=self)
    self.extensions.call("on_class_members", node=node, cls=class_, agent=self)
    self.current = self.current.parent  # type: ignore[assignment]

def visit_functiondef(self, node: ast.FunctionDef) -> None:
    """Visit a function definition node.

    Parameters:
        node: The node to visit.
    """
    self.handle_function(node)

def visit_if(self, node: ast.If) -> None:
    """Visit an "if" node.

    Parameters:
        node: The node to visit.
    """
    if isinstance(node.parent, (ast.Module, ast.ClassDef)):  # type: ignore[attr-defined]
        condition = safe_get_condition(node.test, parent=self.current, log_level=None)
        if str(condition) in {"typing.TYPE_CHECKING", "TYPE_CHECKING"}:
            self.type_guarded = True
    self.generic_visit(node)
    self.type_guarded = False

def visit_import(self, node: ast.Import) -> None:
    """Visit an import node.

    Parameters:
        node: The node to visit.
    """
    for name in node.names:
        alias_path = name.name if name.asname else name.name.split(".", 1)[0]
        alias_name = name.asname or alias_path.split(".", 1)[0]
        self.current.imports[alias_name] = alias_path
        alias = Alias(
            alias_name,
            alias_path,
            lineno=node.lineno,
            endlineno=node.end_lineno,
            runtime=not self.type_guarded,
            analysis="static",
        )
        self.current.set_member(alias_name, alias)
        self.extensions.call("on_alias_instance", alias=alias, node=node, agent=self)

def visit_importfrom(self, node: ast.ImportFrom) -> None:
    """Visit an "import from" node.

    Parameters:
        node: The node to visit.
    """
    for name in node.names:
        if not node.module and node.level == 1 and not name.asname and self.current.module.is_init_module:
            # Special case: when being in `a/__init__.py` and doing `from . import b`,
            # we are effectively creating a member `b` in `a` that is pointing to `a.b`
            # -> cyclic alias! In that case, we just skip it, as both the member and module
            # have the same name and can be accessed the same way.
            continue

        alias_path = relative_to_absolute(node, name, self.current.module)
        if name.name == "*":
            alias_name = alias_path.replace(".", "/")
            alias_path = alias_path.replace(".*", "")
        else:
            alias_name = name.asname or name.name
            self.current.imports[alias_name] = alias_path
        # Do not create aliases pointing to themselves (it happens with
        # `from package.current_module import Thing as Thing` or
        # `from . import thing as thing`).
        if alias_path != f"{self.current.path}.{alias_name}":
            alias = Alias(
                alias_name,
                alias_path,
                lineno=node.lineno,
                endlineno=node.end_lineno,
                runtime=not self.type_guarded,
                analysis="static",
            )
            self.current.set_member(alias_name, alias)
            self.extensions.call("on_alias_instance", alias=alias, node=node, agent=self)

def visit_module(self, node: ast.Module) -> None:
    """Visit a module node.

    Parameters:
        node: The node to visit.
    """
    self.extensions.call("on_node", node=node, agent=self)
    self.extensions.call("on_module_node", node=node, agent=self)
    self.current = module = Module(
        name=self.module_name,
        filepath=self.filepath,
        parent=self.parent,
        docstring=self._get_docstring(node),
        lines_collection=self.lines_collection,
        modules_collection=self.modules_collection,
        analysis="static",
    )
    self.extensions.call("on_instance", node=node, obj=module, agent=self)
    self.extensions.call("on_module_instance", node=node, mod=module, agent=self)
    self.generic_visit(node)
    self.extensions.call("on_members", node=node, obj=module, agent=self)
    self.extensions.call("on_module_members", node=node, mod=module, agent=self)

def visit_typealias(self, node: ast.TypeAlias) -> None:
    """Visit a type alias node.

    Parameters:
        node: The node to visit.
    """
    self.extensions.call("on_node", node=node, agent=self)
    self.extensions.call("on_type_alias_node", node=node, agent=self)

    # A type alias's name attribute is syntactically a single NAME,
    # but represented as an expression in the AST.
    # https://jellezijlstra.github.io/pep695#ast

    name = node.name.id

    value = safe_get_expression(node.value, parent=self.current, member=name)

    try:
        docstring = self._get_docstring(ast_next(node), strict=True)
    except (LastNodeError, AttributeError):
        docstring = None

    type_alias = TypeAlias(
        name=name,
        value=value,
        lineno=node.lineno,
        endlineno=node.end_lineno,
        type_parameters=TypeParameters(*self._get_type_parameters(node, scope=name)),
        docstring=docstring,
        parent=self.current,
        analysis="static",
    )
    self.current.set_member(name, type_alias)
    self.extensions.call("on_instance", node=node, obj=type_alias, agent=self)
    self.extensions.call("on_type_alias_instance", node=node, type_alias=type_alias, agent=self)

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 target_path := child.alias_target_path:
            # If the child is an actual submodule of the current module,
            # and has no `__file__` set, we won't find it on the disk so we must inspect it now.
            # For that we instantiate a new inspector and use it to inspect the submodule,
            # then assign the submodule as member of the current module.
            # If the submodule has a `__file__` set, the loader should find it on the disk,
            # so we skip it here (no member, no alias, just skip it).
            if child.is_module and target_path == f"{self.current.path}.{child.name}":
                if not hasattr(child.obj, "__file__"):
                    logger.debug("Module %s is not discoverable on disk, inspecting right now", target_path)
                    inspector = Inspector(
                        child.name,
                        filepath=None,
                        parent=self.current.module,
                        extensions=self.extensions,
                        docstring_parser=self.docstring_parser,
                        docstring_options=self.docstring_options,
                        lines_collection=self.lines_collection,
                        modules_collection=self.modules_collection,
                    )
                    inspector.inspect_module(child)
                    self.current.set_member(child.name, inspector.current.module)
            # Otherwise, alias the object.
            else:
                alias = Alias(child.name, target_path, analysis="dynamic")
                self.current.set_member(child.name, alias)
                self.extensions.call("on_alias_instance", alias=alias, node=node, agent=self)
        else:
            self.inspect(child)

def get_module(self, 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: Paths replacing `sys.path` to import the module.

    Returns:
        A module instance.
    """
    import_path = self.module_name
    if self.parent is not None:
        import_path = f"{self.parent.path}.{import_path}"

    # Make sure `import_paths` is a list, in case we want to `insert` into it.
    import_paths = list(import_paths or ())

    # If the thing we want to import has a filepath,
    # we make sure to insert the right parent directory
    # at the front of our list of import paths.
    # We do this by counting the number of dots `.` in the import path,
    # corresponding to slashes `/` in the filesystem,
    # and go up in the file tree the same number of times.
    if self.filepath:
        parent_path = self.filepath.parent
        for _ in range(import_path.count(".")):
            parent_path = parent_path.parent
        # Climb up one more time for `__init__` modules.
        if self.filepath.stem == "__init__":
            parent_path = parent_path.parent
        if parent_path not in import_paths:
            import_paths.insert(0, parent_path)

    value = dynamic_import(import_path, import_paths)

    # We successfully imported the given object,
    # and we now create the object tree with all the necessary nodes,
    # from the root of the package to this leaf object.
    parent_node = None
    if self.parent is not None:
        for part in self.parent.path.split("."):
            parent_node = ObjectNode(None, name=part, parent=parent_node)
    module_node = ObjectNode(value, self.module_name, parent=parent_node)

    self.inspect(module_node)
    return self.current.module