Alias ¤

def __bool__(self) -> bool:
    """An alias is always true-ish."""
    return True

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 __len__(self) -> int:
    """The length of an alias is always 1."""
    return 1

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]

def as_dict(self, *, full: bool = False, **kwargs: Any) -> dict[str, Any]:  # noqa: ARG002
    """Return this alias' data as a dictionary.

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

    Parameters:
        full: Whether to return full info, or just base info.
        **kwargs: Additional serialization options.

    Returns:
        A dictionary.
    """
    base: dict[str, Any] = {
        "kind": Kind.ALIAS,
        "name": self.name,
        "target_path": self.target_path,
        "runtime": self.runtime,
        "inherited": self.inherited,
    }

    if self.public is not None:
        base["public"] = self.public
    if self.deprecated is not None:
        base["deprecated"] = self.deprecated
    if self.alias_lineno:
        base["lineno"] = self.alias_lineno
    if self.alias_endlineno:
        base["endlineno"] = self.alias_endlineno
    if self.analysis:
        base["analysis"] = self.analysis

    if full:
        base.update(
            {
                "path": self.path,
                "is_public": self.is_public,
                "is_deprecated": self.is_deprecated,
                "is_private": self.is_private,
                "is_class_private": self.is_class_private,
                "is_special": self.is_special,
                "is_imported": self.is_imported,
                "is_exported": self.is_exported,
                "is_wildcard_exposed": self.is_wildcard_exposed,
            },
        )

    return base

def as_json(self, *, full: bool = False, **kwargs: Any) -> str:
    """Return this target's data as a JSON string.

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

    Parameters:
        full: Whether to return full info, or just base info.
        **kwargs: Additional serialization options passed to encoder.

    Returns:
        A JSON string.
    """
    try:
        return self.final_target.as_json(full=full, **kwargs)
    except (AliasResolutionError, CyclicAliasError):
        return super().as_json(full=full, **kwargs)

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

    This method is part of the producer API:
    you can use it safely while building Griffe trees
    (for example in Griffe extensions).

    Members will be looked up in declared members only, not inherited ones.

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

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

def filter_members(self, *predicates: Callable[[Object | Alias], bool]) -> dict[str, Object | Alias]:
    """Filter and return members based on predicates.

    See also: [`members`][griffe.Alias.members],
    [`get_member`][griffe.Alias.get_member],
    [`set_member`][griffe.Alias.set_member].

    Parameters:
        *predicates: A list of predicates, i.e. callables accepting a member as argument and returning a boolean.

    Returns:
        A dictionary of members.
    """
    return self.final_target.filter_members(*predicates)

@classmethod
def from_json(cls: type[_ObjType], json_string: str, **kwargs: Any) -> _ObjType:  # noqa: PYI019
    """Create an instance of this class from a JSON string.

    Parameters:
        json_string: JSON to decode into Object.
        **kwargs: Additional options passed to decoder.

    Returns:
        An Object instance.

    Raises:
        TypeError: When the json_string does not represent and object
            of the class from which this classmethod has been called.
    """
    from griffe._internal.encoders import json_decoder  # Avoid circular import.  # noqa: PLC0415

    kwargs.setdefault("object_hook", json_decoder)
    obj = json.loads(json_string, **kwargs)
    if not isinstance(obj, cls):
        raise TypeError(f"provided JSON object is not of type {cls}")
    return obj

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

    This method is part of the producer API:
    you can use it safely while building Griffe trees
    (for example in Griffe extensions).

    Members will be looked up in declared members only, not inherited ones.

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

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

def has_labels(self, *labels: str) -> bool:
    """Tell if this object has all the given labels.

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

    Parameters:
        *labels: Labels that must be present.

    Returns:
        True or False.
    """
    return self.final_target.has_labels(*labels)

def is_kind(self, kind: str | Kind | set[str | Kind]) -> bool:
    """Tell if this object is of the given kind.

    See also: [`is_module`][griffe.Alias.is_module],
    [`is_class`][griffe.Alias.is_class],
    [`is_function`][griffe.Alias.is_function],
    [`is_attribute`][griffe.Alias.is_attribute],
    [`is_type_alias`][griffe.Alias.is_type_alias],
    [`is_alias`][griffe.Alias.is_alias].

    Parameters:
        kind: An instance or set of kinds (strings or enumerations).

    Raises:
        ValueError: When an empty set is given as argument.

    Returns:
        True or False.
    """
    return self.final_target.is_kind(kind)

def mro(self) -> list[Class]:
    """Return a list of classes in order corresponding to Python's MRO."""
    return cast("Class", self.final_target).mro()

def resolve(self, name: str) -> str:
    """Resolve a name within this object's and parents' scope.

    Parameters:
        name: The name to resolve.

    Raises:
        NameResolutionError: When the name could not be resolved.

    Returns:
        The resolved name.
    """
    return self.final_target.resolve(name)

def resolve_target(self) -> None:
    """Resolve the target.

    See also: [`target`][griffe.Alias.target],
    [`final_target`][griffe.Alias.final_target],
    [`resolved`][griffe.Alias.resolved].

    Raises:
        AliasResolutionError: When the target cannot be resolved.
            It happens when the target does not exist,
            or could not be loaded (unhandled dynamic object?),
            or when the target is from a module that was not loaded
            and added to the collection.
        CyclicAliasError: When the resolved target is the alias itself.
    """
    # Here we try to resolve the whole alias chain recursively.
    # We detect cycles by setting a "passed through" state variable
    # on each alias as we pass through it. Passing a second time
    # through an alias will raise a CyclicAliasError.

    # If a single link of the chain cannot be resolved,
    # the whole chain stays unresolved. This prevents
    # bad surprises later, in code that checks if
    # an alias is resolved by checking only
    # the first link of the chain.
    if self._passed_through:
        raise CyclicAliasError([self.target_path])
    self._passed_through = True
    try:
        self._resolve_target()
    finally:
        self._passed_through = False