Loaders¤

def expand_exports(self, module: Module, seen: set | None = None) -> None:
    """Expand exports: try to recursively expand all module exports (`__all__` values).

    See also: [`Module.exports`][griffe.Module.exports].

    Parameters:
        module: The module to recurse on.
        seen: Used to avoid infinite recursion.
    """
    seen = seen or set()
    seen.add(module.path)
    if module.exports is None:
        return

    expanded = []
    for export in module.exports:
        # It's a name: we resolve it, get the module it comes from,
        # recurse into it, and add its exports to the current ones.
        if isinstance(export, ExprName):
            module_path = export.canonical_path.rsplit(".", 1)[0]  # Remove trailing `.__all__`.
            try:
                next_module = self.modules_collection.get_member(module_path)
            except KeyError:
                logger.debug("Cannot expand '%s', try pre-loading corresponding package", export.canonical_path)
                continue
            if next_module.path not in seen:
                self.expand_exports(next_module, seen)
            try:
                expanded += [export for export in next_module.exports if export not in expanded]
            except TypeError:
                logger.warning("Unsupported item in %s.__all__: %s (use strings only)", module.path, export)
        # It's a string, simply add it to the current exports.
        else:
            expanded.append(export)
    module.exports = expanded

    # Make sure to expand exports in all modules.
    for submodule in module.modules.values():
        if not submodule.is_alias and submodule.path not in seen:
            self.expand_exports(submodule, seen)

def expand_wildcards(
    self,
    obj: Object,
    *,
    external: bool | None = None,
    seen: set | None = None,
) -> None:
    """Expand wildcards: try to recursively expand all found wildcards.

    See also: [`Alias.wildcard`][griffe.Alias.wildcard].

    Parameters:
        obj: The object and its members to recurse on.
        external: When true, try to load unspecified modules to expand wildcards.
        seen: Used to avoid infinite recursion.
    """
    expanded = []
    to_remove = []
    seen = seen or set()
    seen.add(obj.path)

    # First we expand wildcard imports and store the objects in a temporary `expanded` variable,
    # while also keeping track of the members representing wildcard import, to remove them later.
    for member in obj.members.values():
        # Handle a wildcard.
        if member.is_alias and member.wildcard:  # type: ignore[union-attr]
            package = member.wildcard.split(".", 1)[0]  # type: ignore[union-attr]
            not_loaded = obj.package.path != package and package not in self.modules_collection

            # Try loading the (unknown) package containing the wildcard importe module (if allowed to).
            if not_loaded:
                if external is False or (external is None and package != f"_{obj.package.name}"):
                    continue
                try:
                    self.load(package, try_relative_path=False)
                except (ImportError, LoadingError) as error:
                    logger.debug("Could not expand wildcard import %s in %s: %s", member.name, obj.path, error)
                    continue

            # Try getting the module from which every public object is imported.
            try:
                target = self.modules_collection.get_member(member.target_path)  # type: ignore[union-attr]
            except KeyError:
                logger.debug(
                    "Could not expand wildcard import %s in %s: %s not found in modules collection",
                    member.name,
                    obj.path,
                    cast("Alias", member).target_path,
                )
                continue

            # Recurse into this module, expanding wildcards there before collecting everything.
            if target.path not in seen:
                try:
                    self.expand_wildcards(target, external=external, seen=seen)
                except (AliasResolutionError, CyclicAliasError) as error:
                    logger.debug("Could not expand wildcard import %s in %s: %s", member.name, obj.path, error)
                    continue

            # Collect every imported object.
            expanded.extend(self._expand_wildcard(member))  # type: ignore[arg-type]
            to_remove.append(member.name)

        # Recurse in unseen submodules.
        elif not member.is_alias and member.is_module and member.path not in seen:
            self.expand_wildcards(member, external=external, seen=seen)  # type: ignore[arg-type]

    # Then we remove the members representing wildcard imports.
    for name in to_remove:
        obj.del_member(name)

    # Finally we process the collected objects.
    for new_member, alias_lineno, alias_endlineno in expanded:
        overwrite = False
        already_present = new_member.name in obj.members
        self_alias = (
            new_member.is_alias and cast("Alias", new_member).target_path == f"{obj.path}.{new_member.name}"
        )

        # If a member with the same name is already present in the current object,
        # we only overwrite it if the alias is imported lower in the module
        # (meaning that the alias takes precedence at runtime).
        if already_present:
            old_member = obj.get_member(new_member.name)
            old_lineno = old_member.alias_lineno if old_member.is_alias else old_member.lineno
            overwrite = alias_lineno > (old_lineno or 0)  # type: ignore[operator]

        # 1. If the expanded member is an alias with a target path equal to its own path, we stop.
        #    This situation can arise because of Griffe's mishandling of (abusive) wildcard imports.
        #    We have yet to check how Python handles this itself, or if there's an algorithm
        #    that we could follow to untangle back-and-forth wildcard imports.
        # 2. If the expanded member was already present and we decided not to overwrite it, we stop.
        # 3. Otherwise we proceed further.
        if not self_alias and (not already_present or overwrite):
            alias = Alias(
                new_member.name,
                new_member,
                lineno=alias_lineno,
                endlineno=alias_endlineno,
                parent=obj,  # type: ignore[arg-type]
                wildcard_imported=True,
            )
            # Special case: we avoid overwriting a submodule with an alias.
            # Griffe suffers from this limitation where an object cannot store both
            # a submodule and a member of the same name, while this poses (almost) no issue in Python.
            # We always give precedence to the submodule.
            # See the "avoid member-submodule name shadowing" section in the "Python code" docs page.
            if already_present:
                prev_member = obj.get_member(new_member.name)
                with suppress(AliasResolutionError, CyclicAliasError):
                    if prev_member.is_module:
                        continue

            # Everything went right (supposedly), we add the alias as a member of the current object.
            obj.set_member(new_member.name, alias)
            # YORE: Bump 2: Remove line.
            self.extensions.call("on_wildcard_expansion", alias=alias, loader=self)

def load(
    self,
    objspec: str | Path | None = None,
    /,
    *,
    submodules: bool = True,
    try_relative_path: bool = True,
    find_stubs_package: bool = False,
) -> Object | Alias:
    """Load an object as a Griffe object, given its Python or file path.

    Note that this will load the whole object's package,
    and return only the specified object.
    The rest of the package can be accessed from the returned object
    with regular methods and properties (`parent`, `members`, etc.).

    Examples:
        >>> loader.load("griffe.Module")
        Alias("Module", "griffe._internal.models.Module")

    Parameters:
        objspec: The Python path of an object, or file path to a module.
        submodules: Whether to recurse on the submodules.
            This parameter only makes sense when loading a package (top-level module).
        try_relative_path: Whether to try finding the module as a relative path.
        find_stubs_package: Whether to search for stubs-only package.
            If both the package and its stubs are found, they'll be merged together.
            If only the stubs are found, they'll be used as the package itself.

    Raises:
        LoadingError: When loading a module failed for various reasons.
        ModuleNotFoundError: When a module was not found and inspection is disallowed.

    Returns:
        A Griffe object.
    """
    obj_path: str
    package = None
    top_module = None

    # We always start by searching paths on the disk,
    # even if inspection is forced.
    logger.debug("Searching path(s) for %s", objspec)
    try:
        obj_path, package = self.finder.find_spec(
            objspec,  # type: ignore[arg-type]
            try_relative_path=try_relative_path,
            find_stubs_package=find_stubs_package,
        )
    except ModuleNotFoundError:
        # If we couldn't find paths on disk and inspection is disabled,
        # re-raise ModuleNotFoundError.
        logger.debug("Could not find path for %s on disk", objspec)
        if not (self.allow_inspection or self.force_inspection):
            raise

        # Otherwise we try to dynamically import the top-level module.
        obj_path = str(objspec)
        top_module_name = obj_path.split(".", 1)[0]
        logger.debug("Trying to dynamically import %s", top_module_name)
        top_module_object = dynamic_import(top_module_name, self.finder.search_paths)

        try:
            top_module_path = top_module_object.__path__
            if not top_module_path:
                raise ValueError(f"Module {top_module_name} has no paths set")  # noqa: TRY301
        except (AttributeError, ValueError):
            # If the top-level module has no `__path__`, we inspect it as-is,
            # and do not try to recurse into submodules (there shouldn't be any in builtin/compiled modules).
            logger.debug("Module %s has no paths set (built-in module?). Inspecting it as-is.", top_module_name)
            top_module = self._inspect_module(top_module_name)
            self.modules_collection.set_member(top_module.path, top_module)
            return self._post_load(top_module, obj_path)

        # We found paths, and use them to build our intermediate Package or NamespacePackage struct.
        logger.debug("Module %s has paths set: %s", top_module_name, top_module_path)
        top_module_path = [Path(path) for path in top_module_path]
        if len(top_module_path) > 1:
            package = NamespacePackage(top_module_name, top_module_path)
        else:
            package = Package(top_module_name, top_module_path[0])

    # We have an intermediate package, and an object path: we're ready to load.
    logger.debug("Found %s: loading", objspec)
    try:
        top_module = self._load_package(package, submodules=submodules)
    except LoadingError:
        logger.exception("Could not load package %s", package)
        raise

    return self._post_load(top_module, obj_path)

def resolve_aliases(
    self,
    *,
    implicit: bool = False,
    external: bool | None = None,
    max_iterations: int | None = None,
) -> tuple[set[str], int]:
    """Resolve aliases.

    Parameters:
        implicit: When false, only try to resolve an alias if it is explicitly exported.
        external: When false, don't try to load unspecified modules to resolve aliases.
        max_iterations: Maximum number of iterations on the loader modules collection.

    Returns:
        The unresolved aliases and the number of iterations done.
    """
    if max_iterations is None:
        max_iterations = float("inf")  # type: ignore[assignment]
    prev_unresolved: set[str] = set()
    unresolved: set[str] = set("0")  # Init to enter loop.
    iteration = 0
    collection = self.modules_collection.members

    # Before resolving aliases, we try to expand wildcard imports again
    # (this was already done in `_post_load()`),
    # this time with the user-configured `external` setting,
    # and with potentially more packages loaded in the collection,
    # allowing to resolve more aliases.
    for wildcards_module in list(collection.values()):
        self.expand_wildcards(wildcards_module, external=external)

    load_failures: set[str] = set()
    while unresolved and unresolved != prev_unresolved and iteration < max_iterations:  # type: ignore[operator]
        prev_unresolved = unresolved - {"0"}
        unresolved = set()
        resolved: set[str] = set()
        iteration += 1
        for module_name in list(collection.keys()):
            module = collection[module_name]
            next_resolved, next_unresolved = self.resolve_module_aliases(
                module,
                implicit=implicit,
                external=external,
                load_failures=load_failures,
            )
            resolved |= next_resolved
            unresolved |= next_unresolved
        logger.debug(
            "Iteration %s finished, %s aliases resolved, still %s to go",
            iteration,
            len(resolved),
            len(unresolved),
        )
    return unresolved, iteration

def resolve_module_aliases(
    self,
    obj: Object | Alias,
    *,
    implicit: bool = False,
    external: bool | None = None,
    seen: set[str] | None = None,
    load_failures: set[str] | None = None,
) -> tuple[set[str], set[str]]:
    """Follow aliases: try to recursively resolve all found aliases.

    Parameters:
        obj: The object and its members to recurse on.
        implicit: When false, only try to resolve an alias if it is explicitly exported.
        external: When false, don't try to load unspecified modules to resolve aliases.
        seen: Used to avoid infinite recursion.
        load_failures: Set of external packages we failed to load (to prevent retries).

    Returns:
        Both sets of resolved and unresolved aliases.
    """
    resolved = set()
    unresolved = set()
    if load_failures is None:
        load_failures = set()
    seen = seen or set()
    seen.add(obj.path)

    for member in obj.members.values():
        # Handle aliases.
        if member.is_alias:
            if member.wildcard or member.resolved:  # type: ignore[union-attr]
                continue
            if not implicit and not member.is_exported:
                continue

            # Try resolving the alias. If it fails, check if it is because it comes
            # from an external package, and decide if we should load that package
            # to allow the alias to be resolved at the next iteration (maybe).
            try:
                member.resolve_target()  # type: ignore[union-attr]
            except AliasResolutionError as error:
                target = error.alias.target_path
                unresolved.add(member.path)
                package = target.split(".", 1)[0]
                load_module = (
                    (external is True or (external is None and package == f"_{obj.package.name}"))
                    and package not in load_failures
                    and obj.package.path != package
                    and package not in self.modules_collection
                )
                if load_module:
                    logger.debug("Failed to resolve alias %s -> %s", member.path, target)
                    try:
                        self.load(package, try_relative_path=False)
                    except (ImportError, LoadingError) as error:
                        logger.debug("Could not follow alias %s: %s", member.path, error)
                        load_failures.add(package)
            except CyclicAliasError as error:
                logger.debug(str(error))
            else:
                logger.debug("Alias %s was resolved to %s", member.path, member.final_target.path)  # type: ignore[union-attr]
                resolved.add(member.path)

        # Recurse into unseen modules and classes.
        elif member.kind in {Kind.MODULE, Kind.CLASS} and member.path not in seen:
            sub_resolved, sub_unresolved = self.resolve_module_aliases(
                member,
                implicit=implicit,
                external=external,
                seen=seen,
                load_failures=load_failures,
            )
            resolved |= sub_resolved
            unresolved |= sub_unresolved

    return resolved, unresolved

def stats(self) -> Stats:
    """Compute some statistics.

    Returns:
        Some statistics.
    """
    stats = Stats(self)
    stats.time_spent_visiting = self._time_stats["time_spent_visiting"]
    stats.time_spent_inspecting = self._time_stats["time_spent_inspecting"]
    return stats

def __bool__(self) -> bool:
    """A modules collection is always true-ish."""
    return True

def __contains__(self, item: Any) -> bool:
    """Check if a module is in the collection."""
    return item in self.members

def __delitem__(self, key: str | Sequence[str]) -> None:
    """Delete a member with its name or path.

    This method is part of the consumer API:
    do not use when producing Griffe trees!

    Members will be looked up in both declared members and inherited ones,
    triggering computation of the latter.

    Parameters:
        key: The name or path of the member.

    Examples:
        >>> del griffe_object["foo"]
        >>> del griffe_object["path.to.bar"]
        >>> del griffe_object[("path", "to", "qux")]
    """
    parts = _get_parts(key)
    if len(parts) == 1:
        name = parts[0]
        try:
            del self.members[name]  # type: ignore[attr-defined]
        except KeyError:
            del self.inherited_members[name]  # type: ignore[attr-defined]
    else:
        del self.all_members[parts[0]][parts[1:]]  # type: ignore[attr-defined]

def __getitem__(self, key: str | Sequence[str]) -> Any:
    """Get a member with its name or path.

    This method is part of the consumer API:
    do not use when producing Griffe trees!

    Members will be looked up in both declared members and inherited ones,
    triggering computation of the latter.

    Parameters:
        key: The name or path of the member.

    Examples:
        >>> foo = griffe_object["foo"]
        >>> bar = griffe_object["path.to.bar"]
        >>> qux = griffe_object[("path", "to", "qux")]
    """
    parts = _get_parts(key)
    if len(parts) == 1:
        return self.all_members[parts[0]]  # type: ignore[attr-defined]
    return self.all_members[parts[0]][parts[1:]]  # type: ignore[attr-defined]

def __setitem__(self, key: str | Sequence[str], value: Object | Alias) -> None:
    """Set a member with its name or path.

    This method is part of the consumer API:
    do not use when producing Griffe trees!

    Parameters:
        key: The name or path of the member.
        value: The member.

    Examples:
        >>> griffe_object["foo"] = foo
        >>> griffe_object["path.to.bar"] = bar
        >>> griffe_object[("path", "to", "qux")] = qux
    """
    parts = _get_parts(key)
    if len(parts) == 1:
        name = parts[0]
        self.members[name] = value  # type: ignore[attr-defined]
        if self.is_collection:  # type: ignore[attr-defined]
            value._modules_collection = self  # type: ignore[union-attr]
        else:
            value.parent = self  # type: ignore[assignment]
    else:
        self.members[parts[0]][parts[1:]] = value  # type: ignore[attr-defined]