Skip to content

Attribute¤

Attribute ¤

Attribute(
    *args: Any,
    value: str | Expr | None = None,
    annotation: str | Expr | None = None,
    **kwargs: Any,
)


              flowchart TD
              griffe.Attribute[Attribute]
              _griffe.models.Object[Object]
              _griffe.mixins.ObjectAliasMixin[ObjectAliasMixin]
              _griffe.mixins.GetMembersMixin[GetMembersMixin]
              _griffe.mixins.SetMembersMixin[SetMembersMixin]
              _griffe.mixins.DelMembersMixin[DelMembersMixin]
              _griffe.mixins.SerializationMixin[SerializationMixin]

                              _griffe.models.Object --> griffe.Attribute
                                _griffe.mixins.ObjectAliasMixin --> _griffe.models.Object
                                _griffe.mixins.GetMembersMixin --> _griffe.mixins.ObjectAliasMixin
                
                _griffe.mixins.SetMembersMixin --> _griffe.mixins.ObjectAliasMixin
                
                _griffe.mixins.DelMembersMixin --> _griffe.mixins.ObjectAliasMixin
                
                _griffe.mixins.SerializationMixin --> _griffe.mixins.ObjectAliasMixin
                




              click griffe.Attribute href "" "griffe.Attribute"
              click _griffe.models.Object href "" "_griffe.models.Object"
              click _griffe.mixins.ObjectAliasMixin href "" "_griffe.mixins.ObjectAliasMixin"
              click _griffe.mixins.GetMembersMixin href "" "_griffe.mixins.GetMembersMixin"
              click _griffe.mixins.SetMembersMixin href "" "_griffe.mixins.SetMembersMixin"
              click _griffe.mixins.DelMembersMixin href "" "_griffe.mixins.DelMembersMixin"
              click _griffe.mixins.SerializationMixin href "" "_griffe.mixins.SerializationMixin"

The class representing a Python module/class/instance attribute.

Parameters:

  • *args ¤

    (Any, default: () ) –

    See griffe.Object.

  • value ¤

    (str | Expr | None, default: None ) –

    The attribute value, if any.

  • annotation ¤

    (str | Expr | None, default: None ) –

    The attribute annotation, if any.

  • **kwargs ¤

    (Any, default: {} ) –

    See griffe.Object.

Methods:

  • __bool__ –

    An object is always true-ish.

  • __delitem__ –

    Delete a member with its name or path.

  • __getitem__ –

    Get a member with its name or path.

  • __len__ –

    The number of members in this object, recursively.

  • __setitem__ –

    Set a member with its name or path.

  • as_dict –

    Return this function's data as a dictionary.

  • as_json –

    Return this object's data as a JSON string.

  • del_member –

    Delete a member with its name or path.

  • filter_members –

    Filter and return members based on predicates.

  • from_json –

    Create an instance of this class from a JSON string.

  • get_member –

    Get a member with its name or path.

  • has_labels –

    Tell if this object has all the given labels.

  • is_kind –

    Tell if this object is of the given kind.

  • resolve –

    Resolve a name within this object's and parents' scope.

  • set_member –

    Set a member with its name or path.

Attributes:

aliases instance-attribute ¤

aliases: dict[str, Alias] = {}

The aliases pointing to this object.

all_members property ¤

all_members: dict[str, Object | Alias]

All members (declared and inherited).

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

annotation instance-attribute ¤

annotation: str | Expr | None = annotation

The attribute type annotation.

attributes property ¤

attributes: dict[str, Attribute]

The attribute members.

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

canonical_path property ¤

canonical_path: str

The full dotted path of this object.

The canonical path is the path where the object was defined (not imported).

classes property ¤

classes: dict[str, Class]

The class members.

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

deleter instance-attribute ¤

deleter: Function | None = None

The deleter linked to this property.

deprecated instance-attribute ¤

deprecated: bool | str | None = None

Whether this object is deprecated (boolean or deprecation message).

docstring instance-attribute ¤

docstring: Docstring | None = docstring

The object docstring.

endlineno instance-attribute ¤

endlineno: int | None = endlineno

The ending line number of the object.

exports instance-attribute ¤

exports: set[str] | list[str | ExprName] | None = None

The names of the objects exported by this (module) object through the __all__ variable.

Exports can contain string (object names) or resolvable names, like other lists of exports coming from submodules:

from .submodule import __all__ as submodule_all

__all__ = ["hello", *submodule_all]

Exports get expanded by the loader before it expands wildcards and resolves aliases.

extra instance-attribute ¤

extra: dict[str, dict[str, Any]] = defaultdict(dict)

Namespaced dictionaries storing extra metadata for this object, used by extensions.

filepath property ¤

filepath: Path | list[Path]

The file path (or directory list for namespace packages) where this object was defined.

Examples:

>>> import griffe
>>> markdown = griffe.load("markdown")
>>> markdown.filepath
PosixPath('~/project/.venv/lib/python3.11/site-packages/markdown/__init__.py')

functions property ¤

functions: dict[str, Function]

The function members.

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

has_docstring property ¤

has_docstring: bool

Whether this object has a docstring (empty or not).

has_docstrings property ¤

has_docstrings: bool

Whether this object or any of its members has a docstring (empty or not).

Inherited members are not considered. Imported members are not considered, unless they are also public.

imports instance-attribute ¤

imports: dict[str, str] = {}

The other objects imported by this object.

Keys are the names within the object (from ... import ... as AS_NAME), while the values are the actual names of the objects (from ... import REAL_NAME as ...).

inherited class-attribute instance-attribute ¤

inherited: bool = False

Always false for objects.

Only aliases can be marked as inherited.

inherited_members cached property ¤

inherited_members: dict[str, Alias]

Members that are inherited from base classes.

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

is_alias class-attribute instance-attribute ¤

is_alias: bool = False

Always false for objects.

is_attribute property ¤

is_attribute: bool

Whether this object is an attribute.

is_class property ¤

is_class: bool

Whether this object is a class.

is_class_private property ¤

is_class_private: bool

Whether this object/alias is class-private (starts with __ and is a class member).

is_collection class-attribute instance-attribute ¤

is_collection: bool = False

Always false for objects.

is_deprecated property ¤

is_deprecated: bool

Whether this object is deprecated.

is_exported property ¤

is_exported: bool

Whether this object/alias is exported (listed in __all__).

is_function property ¤

is_function: bool

Whether this object is a function.

is_imported property ¤

is_imported: bool

Whether this object/alias was imported from another module.

is_init_module property ¤

is_init_module: bool

Whether this object is an __init__.py module.

is_module property ¤

is_module: bool

Whether this object is a module.

is_namespace_package property ¤

is_namespace_package: bool

Whether this object is a namespace package (top folder, no __init__.py).

is_namespace_subpackage property ¤

is_namespace_subpackage: bool

Whether this object is a namespace subpackage.

is_package property ¤

is_package: bool

Whether this object is a package (top module).

is_private property ¤

is_private: bool

Whether this object/alias is private (starts with _) but not special.

is_public property ¤

is_public: bool

Whether this object is considered public.

In modules, developers can mark objects as public thanks to the __all__ variable. In classes however, there is no convention or standard to do so.

Therefore, to decide whether an object is public, we follow this algorithm:

  • If the object's public attribute is set (boolean), return its value.
  • If the object is listed in its parent's (a module) __all__ attribute, it is public.
  • If the parent (module) defines __all__ and the object is not listed in, it is private.
  • If the object has a private name, it is private.
  • If the object was imported from another module, it is private.
  • Otherwise, the object is public.

is_special property ¤

is_special: bool

Whether this object/alias is special ("dunder" attribute/method, starts and end with __).

is_subpackage property ¤

is_subpackage: bool

Whether this object is a subpackage.

is_wildcard_exposed property ¤

is_wildcard_exposed: bool

Whether this object/alias is exposed to wildcard imports.

To be exposed to wildcard imports, an object/alias must:

  • be available at runtime
  • have a module as parent
  • be listed in __all__ if __all__ is defined
  • or not be private (having a name starting with an underscore)

Special case for Griffe trees: a submodule is only exposed if its parent imports it.

Returns:

  • bool –

    True or False.

kind class-attribute instance-attribute ¤

kind = ATTRIBUTE

The object kind.

labels instance-attribute ¤

labels: set[str] = set()

The object labels (property, dataclass, etc.).

lineno instance-attribute ¤

lineno: int | None = lineno

The starting line number of the object.

lines property ¤

lines: list[str]

The lines containing the source of this object.

lines_collection property ¤

lines_collection: LinesCollection

The lines collection attached to this object or its parents.

Raises:

  • ValueError –

    When no modules collection can be found in the object or its parents.

members instance-attribute ¤

members: dict[str, Object | Alias] = {}

The object members (modules, classes, functions, attributes).

module property ¤

module: Module

The parent module of this object.

Examples:

>>> import griffe
>>> markdown = griffe.load("markdown")
>>> markdown["core.Markdown.references"].module
Module(PosixPath('~/project/.venv/lib/python3.11/site-packages/markdown/core.py'))
>>> # The `module` of a module is itself.
>>> markdown["core"].module
Module(PosixPath('~/project/.venv/lib/python3.11/site-packages/markdown/core.py'))

Raises:

  • ValueError –

    When the object is not a module and does not have a parent.

modules property ¤

modules: dict[str, Module]

The module members.

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

modules_collection property ¤

modules_collection: ModulesCollection

The modules collection attached to this object or its parents.

Raises:

  • ValueError –

    When no modules collection can be found in the object or its parents.

name instance-attribute ¤

name: str = name

The object name.

package property ¤

package: Module

The absolute top module (the package) of this object.

Examples:

>>> import griffe
>>> markdown = griffe.load("markdown")
>>> markdown["core.Markdown.references"].package
Module(PosixPath('~/project/.venv/lib/python3.11/site-packages/markdown/__init__.py'))

parent instance-attribute ¤

parent: Module | Class | None = parent

The parent of the object (none if top module).

path property ¤

path: str

The dotted path of this object.

On regular objects (not aliases), the path is the canonical path.

Examples:

>>> import griffe
>>> markdown = griffe.load("markdown")
>>> markdown["core.Markdown.references"].path
'markdown.core.Markdown.references'

public instance-attribute ¤

public: bool | None = None

Whether this object is public.

relative_filepath property ¤

relative_filepath: Path

The file path where this object was defined, relative to the current working directory.

If this object's file path is not relative to the current working directory, return its absolute path.

Raises:

  • ValueError –

    When the relative path could not be computed.

relative_package_filepath property ¤

relative_package_filepath: Path

The file path where this object was defined, relative to the top module path.

Raises:

  • ValueError –

    When the relative path could not be computed.

runtime instance-attribute ¤

runtime: bool = runtime

Whether this object is available at runtime.

Typically, type-guarded objects (under an if TYPE_CHECKING condition) are not available at runtime.

setter instance-attribute ¤

setter: Function | None = None

The setter linked to this property.

source property ¤

source: str

The source code of this object.

value instance-attribute ¤

value: str | Expr | None = value

The attribute value.

__bool__ ¤

__bool__() -> bool

An object is always true-ish.

__delitem__ ¤

__delitem__(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:

Examples:

>>> del griffe_object["foo"]
>>> del griffe_object["path.to.bar"]
>>> del griffe_object[("path", "to", "qux")]

__getitem__ ¤

__getitem__(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:

Examples:

>>> foo = griffe_object["foo"]
>>> bar = griffe_object["path.to.bar"]
>>> qux = griffe_object[("path", "to", "qux")]

__len__ ¤

__len__() -> int

The number of members in this object, recursively.

__setitem__ ¤

__setitem__(
    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:

Examples:

>>> griffe_object["foo"] = foo
>>> griffe_object["path.to.bar"] = bar
>>> griffe_object[("path", "to", "qux")] = qux

as_dict ¤

as_dict(**kwargs: Any) -> dict[str, Any]

Return this function's data as a dictionary.

Parameters:

  • **kwargs ¤

    (Any, default: {} ) –

    Additional serialization options.

Returns:

as_json ¤

as_json(*, full: bool = False, **kwargs: Any) -> str

Return this object's data as a JSON string.

Parameters:

  • full ¤

    (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs ¤

    (Any, default: {} ) –

    Additional serialization options passed to encoder.

Returns:

  • str –

    A JSON string.

del_member ¤

del_member(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:

Examples:

>>> griffe_object.del_member("foo")
>>> griffe_object.del_member("path.to.bar")
>>> griffe_object.del_member(("path", "to", "qux"))

filter_members ¤

filter_members(
    *predicates: Callable[[Object | Alias], bool]
) -> dict[str, Object | Alias]

Filter and return members based on predicates.

Parameters:

  • *predicates ¤

    (Callable[[Object | Alias], bool], default: () ) –

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

Returns:

from_json classmethod ¤

from_json(json_string: str, **kwargs: Any) -> _ObjType

Create an instance of this class from a JSON string.

Parameters:

  • json_string ¤

    (str) –

    JSON to decode into Object.

  • **kwargs ¤

    (Any, default: {} ) –

    Additional options passed to decoder.

Returns:

  • _ObjType –

    An Object instance.

Raises:

  • TypeError –

    When the json_string does not represent and object of the class from which this classmethod has been called.

get_member ¤

get_member(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:

Examples:

>>> foo = griffe_object["foo"]
>>> bar = griffe_object["path.to.bar"]
>>> bar = griffe_object[("path", "to", "bar")]

has_labels ¤

has_labels(*labels: str) -> bool

Tell if this object has all the given labels.

Parameters:

  • *labels ¤

    (str, default: () ) –

    Labels that must be present.

Returns:

  • bool –

    True or False.

is_kind ¤

is_kind(kind: str | Kind | set[str | Kind]) -> bool

Tell if this object is of the given kind.

Parameters:

  • kind ¤

    (str | Kind | set[str | Kind]) –

    An instance or set of kinds (strings or enumerations).

Raises:

  • ValueError –

    When an empty set is given as argument.

Returns:

  • bool –

    True or False.

resolve ¤

resolve(name: str) -> str

Resolve a name within this object's and parents' scope.

Parameters:

  • name ¤

    (str) –

    The name to resolve.

Raises:

Returns:

  • str –

    The resolved name.

set_member ¤

set_member(
    key: str | Sequence[str], value: Object | Alias
) -> None

Set 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).

Parameters:

Examples:

>>> griffe_object.set_member("foo", foo)
>>> griffe_object.set_member("path.to.bar", bar)
>>> griffe_object.set_member(("path", "to", "qux"), qux)