griffe ¤

Griffe package.

Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API.

Modules:

__main__ –

Entry-point module, in case you use python -m griffe.
agents –

These modules contain the different agents that are able to extract data.
c3linear –

Compute method resolution order. Implements Class.mro attribute.
cli –

Module that contains the command line application.
collections –

This module stores collections of data, useful during parsing.
dataclasses –

This module contains the data classes that represent Python objects.
debug –

Debugging utilities.
diff –

This module exports "breaking changes" related utilities.
docstrings –

This module exposes objects related to docstrings.
encoders –

This module contains data encoders/serializers and decoders/deserializers.
enumerations –

This module contains all the enumerations of the package.
exceptions –

This module contains all the exceptions specific to Griffe.
expressions –

This module contains the data classes that represent resolvable names and expressions.
extensions –

This module is the public interface to import elements from the base.
finder –

This module contains the code allowing to find modules.
git –

This module contains Git utilities.
importer –

This module contains utilities to dynamically import objects.
loader –

This module contains the code allowing to load modules data.
logger –

This module contains logging utilities.
merger –

This module contains utilities to merge data together.
mixins –

This module contains some mixins classes about accessing and setting members.
stats –

This module contains utilities to compute loading statistics.
tests –

Test helpers and pytest fixtures.

Classes:

Attribute –

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

The class representing a Python class.
Docstring –

This class represents docstrings.
Extension –

Base class for Griffe extensions.
Function –

The class representing a Python function.
Module –

The class representing a Python module.
Object –

An abstract class representing a Python object.
ObjectNode –

Helper class to represent an object tree.
Parser –

Enumeration of the different docstring parsers.

Functions:

dynamic_import –

Dynamically import the specified object.
find_breaking_changes –

Find breaking changes between two versions of the same API.
get_logger –

Create and return a new logger instance.
load –

Load and return a module.
load_extensions –

Load configured extensions.
load_git –

Load and return a module from a specific Git reference.
parse_google –

Parse a Google-style docstring.
parse_numpy –

Parse a Numpydoc-style docstring.
parse_sphinx –

Parse a Sphinx-style docstring.

Attribute ¤

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


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

                        griffe.dataclasses.Object --> griffe.Attribute
                            griffe.mixins.ObjectAliasMixin --> griffe.dataclasses.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.dataclasses.Object href "" "griffe.dataclasses.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.dataclasses.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.dataclasses.Object.

Methods:

__delitem__ –

Delete a member with its name or path.
__getitem__ –

Get a member with its name or path.
__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_exported –

Tell if this object/alias is implicitely exported by its parent.
is_kind –

Tell if this object is of the given kind.
is_public –

Whether this object is considered public.
member_is_exported –

Whether a member of this object is "exported".
resolve –

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

Set a member with its name or path.

Attributes:

aliases (dict[str, Alias]) –

The aliases pointing to this object.
all_members (dict[str, Object | Alias]) –

All members (declared and inherited).
annotation (str | Expr | None) –

The attribute type annotation.
attributes (dict[str, Attribute]) –

The attribute members.
canonical_path (str) –

The full dotted path of this object.
classes (dict[str, Class]) –

The class members.
docstring (Docstring | None) –

The object docstring.
endlineno (int | None) –

The ending line number of the object.
exports (set[str] | list[str | ExprName] | None) –

The names of the objects exported by this (module) object through the __all__ variable.
extra (dict[str, dict[str, Any]]) –

Namespaced dictionaries storing extra metadata for this object, used by extensions.
filepath (Path | list[Path]) –

The file path (or directory list for namespace packages) where this object was defined.
functions (dict[str, Function]) –

The function members.
has_docstring (bool) –

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

Whether this object or any of its members has a docstring (empty or not).
imports (dict[str, str]) –

The other objects imported by this object.
inherited (bool) –

Whether this object (alias) is inherited.
inherited_members (dict[str, Alias]) –

Members that are inherited from base classes.
is_alias (bool) –

Whether this object is an alias.
is_attribute (bool) –

Whether this object is an attribute.
is_class (bool) –

Whether this object is a class.
is_collection (bool) –

Whether this object is a (modules) collection.
is_explicitely_exported (bool) –

Whether this object/alias is explicitely exported by its parent.
is_function (bool) –

Whether this object is a function.
is_implicitely_exported (bool) –

Whether this object/alias is implicitely exported by its parent.
is_init_module (bool) –

Whether this object is an __init__.py module.
is_module (bool) –

Whether this object is a module.
is_namespace_package (bool) –

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

Whether this object is a namespace subpackage.
is_package (bool) –

Whether this object is a package (top module).
is_subpackage (bool) –

Whether this object is a subpackage.
kind –

The object kind.
labels (set[str]) –

The object labels (property, dataclass, etc.).
lineno (int | None) –

The starting line number of the object.
lines (list[str]) –

The lines containing the source of this object.
lines_collection (LinesCollection) –

The lines collection attached to this object or its parents.
members (dict[str, Object | Alias]) –

The object members (modules, classes, functions, attributes).
module (Module) –

The parent module of this object.
modules (dict[str, Module]) –

The module members.
modules_collection (ModulesCollection) –

The modules collection attached to this object or its parents.
name (str) –

The object name.
package (Module) –

The absolute top module (the package) of this object.
parent (Module | Class | None) –

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

The dotted path of this object.
public (bool | None) –

Whether this object is public.
relative_filepath (Path) –

The file path where this object was defined, relative to the current working directory.
relative_package_filepath (Path) –

The file path where this object was defined, relative to the top module path.
runtime (bool) –

Whether this object is available at runtime.
source (str) –

The source code of this object.
value (str | Expr | None) –

The attribute value.

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!

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.

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

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

Whether this object (alias) is inherited.

Objects can never be inherited, only aliases can.

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

Whether this object is an alias.

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_collection `class-attribute` `instance-attribute` ¤

is_collection: bool = False

Whether this object is a (modules) collection.

is_explicitely_exported `property` ¤

is_explicitely_exported: bool

Whether this object/alias is explicitely exported by its parent.

is_function `property` ¤

is_function: bool

Whether this object is a function.

is_implicitely_exported `property` ¤

is_implicitely_exported: bool

Whether this object/alias is implicitely exported by its parent.

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_subpackage `property` ¤

is_subpackage: bool

Whether this object is a subpackage.

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.

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.

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.

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.

source `property` ¤

source: str

The source code of this object.

value `instance-attribute` ¤

value: str | Expr | None = value

The attribute value.

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:

key (str | Sequence[str]) –

The name or path of the member.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

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:

dict[str, Any] –

A dictionary.

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:

key (str | Sequence[str]) –

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"))

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:

dict[str, Object | Alias] –

A dictionary of members.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

has_labels ¤

has_labels(labels: set[str]) -> bool

Tell if this object has all the given labels.

Parameters:

labels (set[str]) –

A set of labels.

Returns:

bool –

True or False.

is_exported ¤

is_exported(*, explicitely: bool = True) -> bool

Tell if this object/alias is implicitely exported by its parent.

Parameters:

explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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.

is_public ¤

is_public(
    *, strict: bool = False, check_name: bool = True
) -> 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.
In strict mode, the object is public only if it is explicitely exported (listed in __all__). Strict mode should only be used for module members.
Otherwise, if name checks are enabled, the object is private if its name starts with an underscore.
Otherwise, if the object is an alias, and is neither inherited from a base class, nor a member of a parent alias, it is not public.
Otherwise, the object is public.

member_is_exported ¤

member_is_exported(
    member: Object | Alias, *, explicitely: bool = True
) -> bool

Whether a member of this object is "exported".

By exported, we mean that the object is included in the __all__ attribute of its parent module or class. When __all__ is not defined, we consider the member to be implicitely exported, unless it's a module and it was not imported, and unless it's not defined at runtime.

Parameters:

member (Object | Alias) –

The member to verify.
explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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:

NameResolutionError –

When the name could not be resolved.

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

Examples:

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

Class ¤

Class(
    *args: Any,
    bases: Sequence[Expr | str] | None = None,
    decorators: list[Decorator] | None = None,
    **kwargs: Any
)


          flowchart TD
          griffe.Class[Class]
          griffe.dataclasses.Object[Object]
          griffe.mixins.ObjectAliasMixin[ObjectAliasMixin]
          griffe.mixins.GetMembersMixin[GetMembersMixin]
          griffe.mixins.SetMembersMixin[SetMembersMixin]
          griffe.mixins.DelMembersMixin[DelMembersMixin]
          griffe.mixins.SerializationMixin[SerializationMixin]

                        griffe.dataclasses.Object --> griffe.Class
                            griffe.mixins.ObjectAliasMixin --> griffe.dataclasses.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.Class href "" "griffe.Class"
          click griffe.dataclasses.Object href "" "griffe.dataclasses.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 class.

Parameters:

*args (Any, default: () ) –

See griffe.dataclasses.Object.
bases (Sequence[Expr | str] | None, default: None ) –

The list of base classes, if any.
decorators (list[Decorator] | None, default: None ) –

The class decorators, if any.
**kwargs (Any, default: {} ) –

See griffe.dataclasses.Object.

Methods:

__delitem__ –

Delete a member with its name or path.
__getitem__ –

Get a member with its name or path.
__setitem__ –

Set a member with its name or path.
as_dict –

Return this class' 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_exported –

Tell if this object/alias is implicitely exported by its parent.
is_kind –

Tell if this object is of the given kind.
is_public –

Whether this object is considered public.
member_is_exported –

Whether a member of this object is "exported".
mro –

Return a list of classes in order corresponding to Python's MRO.
resolve –

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

Set a member with its name or path.

Attributes:

aliases (dict[str, Alias]) –

The aliases pointing to this object.
all_members (dict[str, Object | Alias]) –

All members (declared and inherited).
attributes (dict[str, Attribute]) –

The attribute members.
bases (list[Expr | str]) –

The class bases.
canonical_path (str) –

The full dotted path of this object.
classes (dict[str, Class]) –

The class members.
decorators (list[Decorator]) –

The class decorators.
docstring (Docstring | None) –

The object docstring.
endlineno (int | None) –

The ending line number of the object.
exports (set[str] | list[str | ExprName] | None) –

The names of the objects exported by this (module) object through the __all__ variable.
extra (dict[str, dict[str, Any]]) –

Namespaced dictionaries storing extra metadata for this object, used by extensions.
filepath (Path | list[Path]) –

The file path (or directory list for namespace packages) where this object was defined.
functions (dict[str, Function]) –

The function members.
has_docstring (bool) –

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

Whether this object or any of its members has a docstring (empty or not).
imports (dict[str, str]) –

The other objects imported by this object.
inherited (bool) –

Whether this object (alias) is inherited.
inherited_members (dict[str, Alias]) –

Members that are inherited from base classes.
is_alias (bool) –

Whether this object is an alias.
is_attribute (bool) –

Whether this object is an attribute.
is_class (bool) –

Whether this object is a class.
is_collection (bool) –

Whether this object is a (modules) collection.
is_explicitely_exported (bool) –

Whether this object/alias is explicitely exported by its parent.
is_function (bool) –

Whether this object is a function.
is_implicitely_exported (bool) –

Whether this object/alias is implicitely exported by its parent.
is_init_module (bool) –

Whether this object is an __init__.py module.
is_module (bool) –

Whether this object is a module.
is_namespace_package (bool) –

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

Whether this object is a namespace subpackage.
is_package (bool) –

Whether this object is a package (top module).
is_subpackage (bool) –

Whether this object is a subpackage.
kind –

The object kind.
labels (set[str]) –

The object labels (property, dataclass, etc.).
lineno (int | None) –

The starting line number of the object.
lines (list[str]) –

The lines containing the source of this object.
lines_collection (LinesCollection) –

The lines collection attached to this object or its parents.
members (dict[str, Object | Alias]) –

The object members (modules, classes, functions, attributes).
module (Module) –

The parent module of this object.
modules (dict[str, Module]) –

The module members.
modules_collection (ModulesCollection) –

The modules collection attached to this object or its parents.
name (str) –

The object name.
overloads (dict[str, list[Function]]) –

The overloaded signatures declared in this class.
package (Module) –

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

The parameters of this class' __init__ method, if any.
parent (Module | Class | None) –

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

The dotted path of this object.
public (bool | None) –

Whether this object is public.
relative_filepath (Path) –

The file path where this object was defined, relative to the current working directory.
relative_package_filepath (Path) –

The file path where this object was defined, relative to the top module path.
resolved_bases (list[Object]) –

Resolved class bases.
runtime (bool) –

Whether this object is available at runtime.
source (str) –

The source code of this object.

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!

attributes `property` ¤

attributes: dict[str, Attribute]

The attribute members.

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

bases `instance-attribute` ¤

bases: list[Expr | str] = list(bases) if bases else []

The class bases.

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!

decorators `instance-attribute` ¤

decorators: list[Decorator] = decorators or []

The class decorators.

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.

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

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

Whether this object (alias) is inherited.

Objects can never be inherited, only aliases can.

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

Whether this object is an alias.

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_collection `class-attribute` `instance-attribute` ¤

is_collection: bool = False

Whether this object is a (modules) collection.

is_explicitely_exported `property` ¤

is_explicitely_exported: bool

Whether this object/alias is explicitely exported by its parent.

is_function `property` ¤

is_function: bool

Whether this object is a function.

is_implicitely_exported `property` ¤

is_implicitely_exported: bool

Whether this object/alias is implicitely exported by its parent.

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_subpackage `property` ¤

is_subpackage: bool

Whether this object is a subpackage.

kind `class-attribute` `instance-attribute` ¤

kind = CLASS

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.

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.

overloads `instance-attribute` ¤

overloads: dict[str, list[Function]] = defaultdict(list)

The overloaded signatures declared in this class.

package `property` ¤

package: Module

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

parameters `property` ¤

parameters: Parameters

The parameters of this class' __init__ method, if any.

This property fetches inherited members, and therefore is part of the consumer API: do not use when producing Griffe trees!

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.

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.

resolved_bases `cached` `property` ¤

resolved_bases: list[Object]

Resolved class bases.

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

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.

source `property` ¤

source: str

The source code of this object.

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:

key (str | Sequence[str]) –

The name or path of the member.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

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 class' data as a dictionary.

Parameters:

**kwargs (Any, default: {} ) –

Additional serialization options.

Returns:

dict[str, Any] –

A dictionary.

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:

key (str | Sequence[str]) –

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"))

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:

dict[str, Object | Alias] –

A dictionary of members.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

has_labels ¤

has_labels(labels: set[str]) -> bool

Tell if this object has all the given labels.

Parameters:

labels (set[str]) –

A set of labels.

Returns:

bool –

True or False.

is_exported ¤

is_exported(*, explicitely: bool = True) -> bool

Tell if this object/alias is implicitely exported by its parent.

Parameters:

explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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.

is_public ¤

is_public(
    *, strict: bool = False, check_name: bool = True
) -> 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.
In strict mode, the object is public only if it is explicitely exported (listed in __all__). Strict mode should only be used for module members.
Otherwise, if name checks are enabled, the object is private if its name starts with an underscore.
Otherwise, if the object is an alias, and is neither inherited from a base class, nor a member of a parent alias, it is not public.
Otherwise, the object is public.

member_is_exported ¤

member_is_exported(
    member: Object | Alias, *, explicitely: bool = True
) -> bool

Whether a member of this object is "exported".

By exported, we mean that the object is included in the __all__ attribute of its parent module or class. When __all__ is not defined, we consider the member to be implicitely exported, unless it's a module and it was not imported, and unless it's not defined at runtime.

Parameters:

member (Object | Alias) –

The member to verify.
explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

Returns:

bool –

True or False.

mro ¤

mro() -> list[Class]

Return a list of classes in order corresponding to Python's MRO.

resolve ¤

resolve(name: str) -> str

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

Parameters:

name (str) –

The name to resolve.

Raises:

NameResolutionError –

When the name could not be resolved.

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

Examples:

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

Docstring ¤

Docstring(
    value: str,
    *,
    lineno: int | None = None,
    endlineno: int | None = None,
    parent: Object | None = None,
    parser: (
        Literal["google", "numpy", "sphinx"] | Parser | None
    ) = None,
    parser_options: dict[str, Any] | None = None
)

This class represents docstrings.

Parameters:

value (str) –

The docstring value.
lineno (int | None, default: None ) –

The starting line number.
endlineno (int | None, default: None ) –

The ending line number.
parent (Object | None, default: None ) –

The parent object on which this docstring is attached.
parser (Literal['google', 'numpy', 'sphinx'] | Parser | None, default: None ) –

The docstring parser to use. By default, no parsing is done.
parser_options (dict[str, Any] | None, default: None ) –

Additional docstring parsing options.

Methods:

as_dict –

Return this docstring's data as a dictionary.
parse –

Parse the docstring into structured data.

Attributes:

endlineno (int | None) –

The ending line number of the docstring.
lineno (int | None) –

The starting line number of the docstring.
lines (list[str]) –

The lines of the docstring.
parent (Object | None) –

The object this docstring is attached to.
parsed (list[DocstringSection]) –

The docstring sections, parsed into structured data.
parser (Literal['google', 'numpy', 'sphinx'] | Parser | None) –

The selected docstring parser.
parser_options (dict[str, Any]) –

The configured parsing options.
value (str) –

The original value of the docstring, cleaned by inspect.cleandoc.

endlineno `instance-attribute` ¤

endlineno: int | None = endlineno

The ending line number of the docstring.

lineno `instance-attribute` ¤

lineno: int | None = lineno

The starting line number of the docstring.

lines `property` ¤

lines: list[str]

The lines of the docstring.

parent `instance-attribute` ¤

parent: Object | None = parent

The object this docstring is attached to.

parsed `cached` `property` ¤

parsed: list[DocstringSection]

The docstring sections, parsed into structured data.

parser `instance-attribute` ¤

parser: (
    Literal["google", "numpy", "sphinx"] | Parser | None
) = parser

The selected docstring parser.

parser_options `instance-attribute` ¤

parser_options: dict[str, Any] = parser_options or {}

The configured parsing options.

value `instance-attribute` ¤

value: str = cleandoc(rstrip())

The original value of the docstring, cleaned by inspect.cleandoc.

as_dict ¤

as_dict(
    *,
    full: bool = False,
    docstring_parser: Parser | None = None,
    **kwargs: Any
) -> dict[str, Any]

Return this docstring's data as a dictionary.

Parameters:

full (bool, default: False ) –

Whether to return full info, or just base info.
docstring_parser (Parser | None, default: None ) –

Deprecated. The docstring parser to parse the docstring with. By default, no parsing is done.
**kwargs (Any, default: {} ) –

Additional serialization options.

Returns:

dict[str, Any] –

A dictionary.

parse ¤

parse(
    parser: (
        Literal["google", "numpy", "sphinx"] | Parser | None
    ) = None,
    **options: Any
) -> list[DocstringSection]

Parse the docstring into structured data.

Parameters:

parser (Literal['google', 'numpy', 'sphinx'] | Parser | None, default: None ) –

The docstring parser to use. In order: use the given parser, or the self parser, or no parser (return a single text section).
**options (Any, default: {} ) –

Additional docstring parsing options.

Returns:

list[DocstringSection] –

The parsed docstring as a list of sections.

Extension ¤

Base class for Griffe extensions.

Methods:

generic_inspect –

Extend the base generic inspection with extensions.
generic_visit –

Visit children nodes.
inspect –

Inspect a node.
on_attribute_instance –

Run when an Attribute has been created.
on_attribute_node –

Run when visiting a new attribute node during static/dynamic analysis.
on_class_instance –

Run when a Class has been created.
on_class_members –

Run when members of a Class have been loaded.
on_class_node –

Run when visiting a new class node during static/dynamic analysis.
on_function_instance –

Run when a Function has been created.
on_function_node –

Run when visiting a new function node during static/dynamic analysis.
on_instance –

Run when an Object has been created.
on_members –

Run when members of an Object have been loaded.
on_module_instance –

Run when a Module has been created.
on_module_members –

Run when members of a Module have been loaded.
on_module_node –

Run when visiting a new module node during static/dynamic analysis.
on_node –

Run when visiting a new node during static/dynamic analysis.
on_package_loaded –

Run when a package has been completely loaded.
visit –

Visit a node.

generic_inspect ¤

generic_inspect(node: ObjectNode) -> None

Extend the base generic inspection with extensions.

Parameters:

node (ObjectNode) –

The node to inspect.

generic_visit ¤

generic_visit(node: AST) -> None

Visit children nodes.

Parameters:

node (AST) –

The node to visit the children of.

inspect ¤

inspect(node: ObjectNode) -> None

Inspect a node.

Parameters:

node (ObjectNode) –

The node to inspect.

on_attribute_instance ¤

on_attribute_instance(
    *, node: AST | ObjectNode, attr: Attribute
) -> None

Run when an Attribute has been created.

Parameters:

node (AST | ObjectNode) –

The currently visited node.
attr (Attribute) –

The attribute instance.

on_attribute_node ¤

on_attribute_node(*, node: AST | ObjectNode) -> None

Run when visiting a new attribute node during static/dynamic analysis.

Parameters:

node (AST | ObjectNode) –

The currently visited node.

on_class_instance ¤

on_class_instance(
    *, node: AST | ObjectNode, cls: Class
) -> None

Run when a Class has been created.

Parameters:

node (AST | ObjectNode) –

The currently visited node.
cls (Class) –

The class instance.

on_class_members ¤

on_class_members(
    *, node: AST | ObjectNode, cls: Class
) -> None

Run when members of a Class have been loaded.

Parameters:

node (AST | ObjectNode) –

The currently visited node.
cls (Class) –

The class instance.

on_class_node ¤

on_class_node(*, node: AST | ObjectNode) -> None

Run when visiting a new class node during static/dynamic analysis.

Parameters:

node (AST | ObjectNode) –

The currently visited node.

on_function_instance ¤

on_function_instance(
    *, node: AST | ObjectNode, func: Function
) -> None

Run when a Function has been created.

Parameters:

node (AST | ObjectNode) –

The currently visited node.
func (Function) –

The function instance.

on_function_node ¤

on_function_node(*, node: AST | ObjectNode) -> None

Run when visiting a new function node during static/dynamic analysis.

Parameters:

node (AST | ObjectNode) –

The currently visited node.

on_instance ¤

on_instance(*, node: AST | ObjectNode, obj: Object) -> None

Run when an Object has been created.

Parameters:

node (AST | ObjectNode) –

The currently visited node.
obj (Object) –

The object instance.

on_members ¤

on_members(*, node: AST | ObjectNode, obj: Object) -> None

Run when members of an Object have been loaded.

Parameters:

node (AST | ObjectNode) –

The currently visited node.
obj (Object) –

The object instance.

on_module_instance ¤

on_module_instance(
    *, node: AST | ObjectNode, mod: Module
) -> None

Run when a Module has been created.

Parameters:

node (AST | ObjectNode) –

The currently visited node.
mod (Module) –

The module instance.

on_module_members ¤

on_module_members(
    *, node: AST | ObjectNode, mod: Module
) -> None

Run when members of a Module have been loaded.

Parameters:

node (AST | ObjectNode) –

The currently visited node.
mod (Module) –

The module instance.

on_module_node ¤

on_module_node(*, node: AST | ObjectNode) -> None

Run when visiting a new module node during static/dynamic analysis.

Parameters:

node (AST | ObjectNode) –

The currently visited node.

on_node ¤

on_node(*, node: AST | ObjectNode) -> None

Run when visiting a new node during static/dynamic analysis.

Parameters:

node (AST | ObjectNode) –

The currently visited node.

on_package_loaded ¤

on_package_loaded(*, pkg: Module) -> None

Run when a package has been completely loaded.

Parameters:

pkg (Module) –

The package (Module) instance.

visit ¤

visit(node: AST) -> None

Visit a node.

Parameters:

node (AST) –

The node to visit.

Function ¤

Function(
    *args: Any,
    parameters: Parameters | None = None,
    returns: str | Expr | None = None,
    decorators: list[Decorator] | None = None,
    **kwargs: Any
)


          flowchart TD
          griffe.Function[Function]
          griffe.dataclasses.Object[Object]
          griffe.mixins.ObjectAliasMixin[ObjectAliasMixin]
          griffe.mixins.GetMembersMixin[GetMembersMixin]
          griffe.mixins.SetMembersMixin[SetMembersMixin]
          griffe.mixins.DelMembersMixin[DelMembersMixin]
          griffe.mixins.SerializationMixin[SerializationMixin]

                        griffe.dataclasses.Object --> griffe.Function
                            griffe.mixins.ObjectAliasMixin --> griffe.dataclasses.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.Function href "" "griffe.Function"
          click griffe.dataclasses.Object href "" "griffe.dataclasses.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 function.

Parameters:

*args (Any, default: () ) –

See griffe.dataclasses.Object.
parameters (Parameters | None, default: None ) –

The function parameters.
returns (str | Expr | None, default: None ) –

The function return annotation.
decorators (list[Decorator] | None, default: None ) –

The function decorators, if any.
**kwargs (Any, default: {} ) –

See griffe.dataclasses.Object.

Methods:

__delitem__ –

Delete a member with its name or path.
__getitem__ –

Get a member with its name or path.
__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_exported –

Tell if this object/alias is implicitely exported by its parent.
is_kind –

Tell if this object is of the given kind.
is_public –

Whether this object is considered public.
member_is_exported –

Whether a member of this object is "exported".
resolve –

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

Set a member with its name or path.

Attributes:

aliases (dict[str, Alias]) –

The aliases pointing to this object.
all_members (dict[str, Object | Alias]) –

All members (declared and inherited).
annotation (str | Expr | None) –

The type annotation of the returned value.
attributes (dict[str, Attribute]) –

The attribute members.
canonical_path (str) –

The full dotted path of this object.
classes (dict[str, Class]) –

The class members.
decorators (list[Decorator]) –

The function decorators.
deleter (Function | None) –

The deleter linked to this function (property).
docstring (Docstring | None) –

The object docstring.
endlineno (int | None) –

The ending line number of the object.
exports (set[str] | list[str | ExprName] | None) –

The names of the objects exported by this (module) object through the __all__ variable.
extra (dict[str, dict[str, Any]]) –

Namespaced dictionaries storing extra metadata for this object, used by extensions.
filepath (Path | list[Path]) –

The file path (or directory list for namespace packages) where this object was defined.
functions (dict[str, Function]) –

The function members.
has_docstring (bool) –

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

Whether this object or any of its members has a docstring (empty or not).
imports (dict[str, str]) –

The other objects imported by this object.
inherited (bool) –

Whether this object (alias) is inherited.
inherited_members (dict[str, Alias]) –

Members that are inherited from base classes.
is_alias (bool) –

Whether this object is an alias.
is_attribute (bool) –

Whether this object is an attribute.
is_class (bool) –

Whether this object is a class.
is_collection (bool) –

Whether this object is a (modules) collection.
is_explicitely_exported (bool) –

Whether this object/alias is explicitely exported by its parent.
is_function (bool) –

Whether this object is a function.
is_implicitely_exported (bool) –

Whether this object/alias is implicitely exported by its parent.
is_init_module (bool) –

Whether this object is an __init__.py module.
is_module (bool) –

Whether this object is a module.
is_namespace_package (bool) –

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

Whether this object is a namespace subpackage.
is_package (bool) –

Whether this object is a package (top module).
is_subpackage (bool) –

Whether this object is a subpackage.
kind –

The object kind.
labels (set[str]) –

The object labels (property, dataclass, etc.).
lineno (int | None) –

The starting line number of the object.
lines (list[str]) –

The lines containing the source of this object.
lines_collection (LinesCollection) –

The lines collection attached to this object or its parents.
members (dict[str, Object | Alias]) –

The object members (modules, classes, functions, attributes).
module (Module) –

The parent module of this object.
modules (dict[str, Module]) –

The module members.
modules_collection (ModulesCollection) –

The modules collection attached to this object or its parents.
name (str) –

The object name.
overloads (list[Function] | None) –

The overloaded signatures of this function.
package (Module) –

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

The function parameters.
parent (Module | Class | None) –

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

The dotted path of this object.
public (bool | None) –

Whether this object is public.
relative_filepath (Path) –

The file path where this object was defined, relative to the current working directory.
relative_package_filepath (Path) –

The file path where this object was defined, relative to the top module path.
returns (str | Expr | None) –

The function return type annotation.
runtime (bool) –

Whether this object is available at runtime.
setter (Function | None) –

The setter linked to this function (property).
source (str) –

The source code of this object.

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 `property` ¤

annotation: str | Expr | None

The type annotation of the returned value.

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!

decorators `instance-attribute` ¤

decorators: list[Decorator] = decorators or []

The function decorators.

deleter `instance-attribute` ¤

deleter: Function | None = None

The deleter linked to this function (property).

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.

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

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

Whether this object (alias) is inherited.

Objects can never be inherited, only aliases can.

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

Whether this object is an alias.

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_collection `class-attribute` `instance-attribute` ¤

is_collection: bool = False

Whether this object is a (modules) collection.

is_explicitely_exported `property` ¤

is_explicitely_exported: bool

Whether this object/alias is explicitely exported by its parent.

is_function `property` ¤

is_function: bool

Whether this object is a function.

is_implicitely_exported `property` ¤

is_implicitely_exported: bool

Whether this object/alias is implicitely exported by its parent.

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_subpackage `property` ¤

is_subpackage: bool

Whether this object is a subpackage.

kind `class-attribute` `instance-attribute` ¤

kind = FUNCTION

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.

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.

overloads `instance-attribute` ¤

overloads: list[Function] | None = None

The overloaded signatures of this function.

package `property` ¤

package: Module

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

parameters `instance-attribute` ¤

parameters: Parameters = parameters or Parameters()

The function parameters.

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.

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.

returns `instance-attribute` ¤

returns: str | Expr | None = returns

The function return type annotation.

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 function (property).

source `property` ¤

source: str

The source code of this object.

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:

key (str | Sequence[str]) –

The name or path of the member.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

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:

dict[str, Any] –

A dictionary.

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:

key (str | Sequence[str]) –

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"))

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:

dict[str, Object | Alias] –

A dictionary of members.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

has_labels ¤

has_labels(labels: set[str]) -> bool

Tell if this object has all the given labels.

Parameters:

labels (set[str]) –

A set of labels.

Returns:

bool –

True or False.

is_exported ¤

is_exported(*, explicitely: bool = True) -> bool

Tell if this object/alias is implicitely exported by its parent.

Parameters:

explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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.

is_public ¤

is_public(
    *, strict: bool = False, check_name: bool = True
) -> 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.
In strict mode, the object is public only if it is explicitely exported (listed in __all__). Strict mode should only be used for module members.
Otherwise, if name checks are enabled, the object is private if its name starts with an underscore.
Otherwise, if the object is an alias, and is neither inherited from a base class, nor a member of a parent alias, it is not public.
Otherwise, the object is public.

member_is_exported ¤

member_is_exported(
    member: Object | Alias, *, explicitely: bool = True
) -> bool

Whether a member of this object is "exported".

By exported, we mean that the object is included in the __all__ attribute of its parent module or class. When __all__ is not defined, we consider the member to be implicitely exported, unless it's a module and it was not imported, and unless it's not defined at runtime.

Parameters:

member (Object | Alias) –

The member to verify.
explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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:

NameResolutionError –

When the name could not be resolved.

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

Examples:

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

Module ¤

Module(
    *args: Any,
    filepath: Path | list[Path] | None = None,
    **kwargs: Any
)


          flowchart TD
          griffe.Module[Module]
          griffe.dataclasses.Object[Object]
          griffe.mixins.ObjectAliasMixin[ObjectAliasMixin]
          griffe.mixins.GetMembersMixin[GetMembersMixin]
          griffe.mixins.SetMembersMixin[SetMembersMixin]
          griffe.mixins.DelMembersMixin[DelMembersMixin]
          griffe.mixins.SerializationMixin[SerializationMixin]

                        griffe.dataclasses.Object --> griffe.Module
                            griffe.mixins.ObjectAliasMixin --> griffe.dataclasses.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.Module href "" "griffe.Module"
          click griffe.dataclasses.Object href "" "griffe.dataclasses.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.

Parameters:

*args (Any, default: () ) –

See griffe.dataclasses.Object.
filepath (Path | list[Path] | None, default: None ) –

The module file path (directory for namespace [sub]packages, none for builtin modules).
**kwargs (Any, default: {} ) –

See griffe.dataclasses.Object.

Methods:

__delitem__ –

Delete a member with its name or path.
__getitem__ –

Get a member with its name or path.
__setitem__ –

Set a member with its name or path.
as_dict –

Return this module'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_exported –

Tell if this object/alias is implicitely exported by its parent.
is_kind –

Tell if this object is of the given kind.
is_public –

Whether this object is considered public.
member_is_exported –

Whether a member of this object is "exported".
resolve –

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

Set a member with its name or path.

Attributes:

aliases (dict[str, Alias]) –

The aliases pointing to this object.
all_members (dict[str, Object | Alias]) –

All members (declared and inherited).
attributes (dict[str, Attribute]) –

The attribute members.
canonical_path (str) –

The full dotted path of this object.
classes (dict[str, Class]) –

The class members.
docstring (Docstring | None) –

The object docstring.
endlineno (int | None) –

The ending line number of the object.
exports (set[str] | list[str | ExprName] | None) –

The names of the objects exported by this (module) object through the __all__ variable.
extra (dict[str, dict[str, Any]]) –

Namespaced dictionaries storing extra metadata for this object, used by extensions.
filepath (Path | list[Path]) –

The file path of this module.
functions (dict[str, Function]) –

The function members.
has_docstring (bool) –

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

Whether this object or any of its members has a docstring (empty or not).
imports (dict[str, str]) –

The other objects imported by this object.
imports_future_annotations (bool) –

Whether this module import future annotations.
inherited (bool) –

Whether this object (alias) is inherited.
inherited_members (dict[str, Alias]) –

Members that are inherited from base classes.
is_alias (bool) –

Whether this object is an alias.
is_attribute (bool) –

Whether this object is an attribute.
is_class (bool) –

Whether this object is a class.
is_collection (bool) –

Whether this object is a (modules) collection.
is_explicitely_exported (bool) –

Whether this object/alias is explicitely exported by its parent.
is_function (bool) –

Whether this object is a function.
is_implicitely_exported (bool) –

Whether this object/alias is implicitely exported by its parent.
is_init_module (bool) –

Whether this module is an __init__.py module.
is_module (bool) –

Whether this object is a module.
is_namespace_package (bool) –

Whether this module is a namespace package (top folder, no __init__.py).
is_namespace_subpackage (bool) –

Whether this module is a namespace subpackage.
is_package (bool) –

Whether this module is a package (top module).
is_subpackage (bool) –

Whether this module is a subpackage.
kind –

The object kind.
labels (set[str]) –

The object labels (property, dataclass, etc.).
lineno (int | None) –

The starting line number of the object.
lines (list[str]) –

The lines containing the source of this object.
lines_collection (LinesCollection) –

The lines collection attached to this object or its parents.
members (dict[str, Object | Alias]) –

The object members (modules, classes, functions, attributes).
module (Module) –

The parent module of this object.
modules (dict[str, Module]) –

The module members.
modules_collection (ModulesCollection) –

The modules collection attached to this object or its parents.
name (str) –

The object name.
overloads (dict[str, list[Function]]) –

The overloaded signature declared in this module.
package (Module) –

The absolute top module (the package) of this object.
parent (Module | Class | None) –

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

The dotted path of this object.
public (bool | None) –

Whether this object is public.
relative_filepath (Path) –

The file path where this object was defined, relative to the current working directory.
relative_package_filepath (Path) –

The file path where this object was defined, relative to the top module path.
runtime (bool) –

Whether this object is available at runtime.
source (str) –

The source code of this object.

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!

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!

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 of this module.

Raises:

BuiltinModuleError –

When the instance filepath is None.

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

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

imports_future_annotations `property` ¤

imports_future_annotations: bool

Whether this module import future annotations.

inherited `class-attribute` `instance-attribute` ¤

inherited: bool = False

Whether this object (alias) is inherited.

Objects can never be inherited, only aliases can.

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

Whether this object is an alias.

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_collection `class-attribute` `instance-attribute` ¤

is_collection: bool = False

Whether this object is a (modules) collection.

is_explicitely_exported `property` ¤

is_explicitely_exported: bool

Whether this object/alias is explicitely exported by its parent.

is_function `property` ¤

is_function: bool

Whether this object is a function.

is_implicitely_exported `property` ¤

is_implicitely_exported: bool

Whether this object/alias is implicitely exported by its parent.

is_init_module `property` ¤

is_init_module: bool

Whether this module 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 module is a namespace package (top folder, no __init__.py).

is_namespace_subpackage `property` ¤

is_namespace_subpackage: bool

Whether this module is a namespace subpackage.

is_package `property` ¤

is_package: bool

Whether this module is a package (top module).

is_subpackage `property` ¤

is_subpackage: bool

Whether this module is a subpackage.

kind `class-attribute` `instance-attribute` ¤

kind = MODULE

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.

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.

overloads `instance-attribute` ¤

overloads: dict[str, list[Function]] = defaultdict(list)

The overloaded signature declared in this module.

package `property` ¤

package: Module

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

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.

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.

source `property` ¤

source: str

The source code of this object.

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:

key (str | Sequence[str]) –

The name or path of the member.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

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 module's data as a dictionary.

Parameters:

**kwargs (Any, default: {} ) –

Additional serialization options.

Returns:

dict[str, Any] –

A dictionary.

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:

key (str | Sequence[str]) –

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"))

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:

dict[str, Object | Alias] –

A dictionary of members.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

has_labels ¤

has_labels(labels: set[str]) -> bool

Tell if this object has all the given labels.

Parameters:

labels (set[str]) –

A set of labels.

Returns:

bool –

True or False.

is_exported ¤

is_exported(*, explicitely: bool = True) -> bool

Tell if this object/alias is implicitely exported by its parent.

Parameters:

explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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.

is_public ¤

is_public(
    *, strict: bool = False, check_name: bool = True
) -> 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.
In strict mode, the object is public only if it is explicitely exported (listed in __all__). Strict mode should only be used for module members.
Otherwise, if name checks are enabled, the object is private if its name starts with an underscore.
Otherwise, if the object is an alias, and is neither inherited from a base class, nor a member of a parent alias, it is not public.
Otherwise, the object is public.

member_is_exported ¤

member_is_exported(
    member: Object | Alias, *, explicitely: bool = True
) -> bool

Whether a member of this object is "exported".

By exported, we mean that the object is included in the __all__ attribute of its parent module or class. When __all__ is not defined, we consider the member to be implicitely exported, unless it's a module and it was not imported, and unless it's not defined at runtime.

Parameters:

member (Object | Alias) –

The member to verify.
explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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:

NameResolutionError –

When the name could not be resolved.

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

Examples:

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

Object ¤

Object(
    name: str,
    *,
    lineno: int | None = None,
    endlineno: int | None = None,
    runtime: bool = True,
    docstring: Docstring | None = None,
    parent: Module | Class | None = None,
    lines_collection: LinesCollection | None = None,
    modules_collection: ModulesCollection | None = None
)


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

                        griffe.mixins.ObjectAliasMixin --> griffe.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.Object href "" "griffe.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"

An abstract class representing a Python object.

Parameters:

name (str) –

The object name, as declared in the code.
lineno (int | None, default: None ) –

The object starting line, or None for modules. Lines start at 1.
endlineno (int | None, default: None ) –

The object ending line (inclusive), or None for modules.
runtime (bool, default: True ) –

Whether this object is present at runtime or not.
docstring (Docstring | None, default: None ) –

The object docstring.
parent (Module | Class | None, default: None ) –

The object parent.
lines_collection (LinesCollection | None, default: None ) –

A collection of source code lines.
modules_collection (ModulesCollection | None, default: None ) –

A collection of modules.

Methods:

__delitem__ –

Delete a member with its name or path.
__getitem__ –

Get a member with its name or path.
__setitem__ –

Set a member with its name or path.
as_dict –

Return this object'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_exported –

Tell if this object/alias is implicitely exported by its parent.
is_kind –

Tell if this object is of the given kind.
is_public –

Whether this object is considered public.
member_is_exported –

Whether a member of this object is "exported".
resolve –

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

Set a member with its name or path.

Attributes:

aliases (dict[str, Alias]) –

The aliases pointing to this object.
all_members (dict[str, Object | Alias]) –

All members (declared and inherited).
attributes (dict[str, Attribute]) –

The attribute members.
canonical_path (str) –

The full dotted path of this object.
classes (dict[str, Class]) –

The class members.
docstring (Docstring | None) –

The object docstring.
endlineno (int | None) –

The ending line number of the object.
exports (set[str] | list[str | ExprName] | None) –

The names of the objects exported by this (module) object through the __all__ variable.
extra (dict[str, dict[str, Any]]) –

Namespaced dictionaries storing extra metadata for this object, used by extensions.
filepath (Path | list[Path]) –

The file path (or directory list for namespace packages) where this object was defined.
functions (dict[str, Function]) –

The function members.
has_docstring (bool) –

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

Whether this object or any of its members has a docstring (empty or not).
imports (dict[str, str]) –

The other objects imported by this object.
inherited (bool) –

Whether this object (alias) is inherited.
inherited_members (dict[str, Alias]) –

Members that are inherited from base classes.
is_alias (bool) –

Whether this object is an alias.
is_attribute (bool) –

Whether this object is an attribute.
is_class (bool) –

Whether this object is a class.
is_collection (bool) –

Whether this object is a (modules) collection.
is_explicitely_exported (bool) –

Whether this object/alias is explicitely exported by its parent.
is_function (bool) –

Whether this object is a function.
is_implicitely_exported (bool) –

Whether this object/alias is implicitely exported by its parent.
is_init_module (bool) –

Whether this object is an __init__.py module.
is_module (bool) –

Whether this object is a module.
is_namespace_package (bool) –

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

Whether this object is a namespace subpackage.
is_package (bool) –

Whether this object is a package (top module).
is_subpackage (bool) –

Whether this object is a subpackage.
kind (Kind) –

The object kind.
labels (set[str]) –

The object labels (property, dataclass, etc.).
lineno (int | None) –

The starting line number of the object.
lines (list[str]) –

The lines containing the source of this object.
lines_collection (LinesCollection) –

The lines collection attached to this object or its parents.
members (dict[str, Object | Alias]) –

The object members (modules, classes, functions, attributes).
module (Module) –

The parent module of this object.
modules (dict[str, Module]) –

The module members.
modules_collection (ModulesCollection) –

The modules collection attached to this object or its parents.
name (str) –

The object name.
package (Module) –

The absolute top module (the package) of this object.
parent (Module | Class | None) –

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

The dotted path of this object.
public (bool | None) –

Whether this object is public.
relative_filepath (Path) –

The file path where this object was defined, relative to the current working directory.
relative_package_filepath (Path) –

The file path where this object was defined, relative to the top module path.
runtime (bool) –

Whether this object is available at runtime.
source (str) –

The source code of this object.

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!

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!

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.

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

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

Whether this object (alias) is inherited.

Objects can never be inherited, only aliases can.

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

Whether this object is an alias.

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_collection `class-attribute` `instance-attribute` ¤

is_collection: bool = False

Whether this object is a (modules) collection.

is_explicitely_exported `property` ¤

is_explicitely_exported: bool

Whether this object/alias is explicitely exported by its parent.

is_function `property` ¤

is_function: bool

Whether this object is a function.

is_implicitely_exported `property` ¤

is_implicitely_exported: bool

Whether this object/alias is implicitely exported by its parent.

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_subpackage `property` ¤

is_subpackage: bool

Whether this object is a subpackage.

kind `instance-attribute` ¤

kind: Kind

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.

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.

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.

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.

source `property` ¤

source: str

The source code of this object.

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:

key (str | Sequence[str]) –

The name or path of the member.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

Examples:

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

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

full (bool, default: False ) –

Whether to return full info, or just base info.
**kwargs (Any, default: {} ) –

Additional serialization options.

Returns:

dict[str, Any] –

A dictionary.

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:

key (str | Sequence[str]) –

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"))

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:

dict[str, Object | Alias] –

A dictionary of members.

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:

key (str | Sequence[str]) –

The name or path of the member.

Examples:

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

has_labels ¤

has_labels(labels: set[str]) -> bool

Tell if this object has all the given labels.

Parameters:

labels (set[str]) –

A set of labels.

Returns:

bool –

True or False.

is_exported ¤

is_exported(*, explicitely: bool = True) -> bool

Tell if this object/alias is implicitely exported by its parent.

Parameters:

explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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.

is_public ¤

is_public(
    *, strict: bool = False, check_name: bool = True
) -> 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.
In strict mode, the object is public only if it is explicitely exported (listed in __all__). Strict mode should only be used for module members.
Otherwise, if name checks are enabled, the object is private if its name starts with an underscore.
Otherwise, if the object is an alias, and is neither inherited from a base class, nor a member of a parent alias, it is not public.
Otherwise, the object is public.

member_is_exported ¤

member_is_exported(
    member: Object | Alias, *, explicitely: bool = True
) -> bool

Whether a member of this object is "exported".

By exported, we mean that the object is included in the __all__ attribute of its parent module or class. When __all__ is not defined, we consider the member to be implicitely exported, unless it's a module and it was not imported, and unless it's not defined at runtime.

Parameters:

member (Object | Alias) –

The member to verify.
explicitely (bool, default: True ) –

Whether to only return True when __all__ is defined.

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:

NameResolutionError –

When the name could not be resolved.

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:

key (str | Sequence[str]) –

The name or path of the member.
value (Object | Alias) –

The member.

Examples:

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

ObjectNode ¤

ObjectNode(
    obj: Any, name: str, parent: ObjectNode | None = None
)

Helper class to represent an object tree.

It's not really a tree but more a backward-linked list: each node has a reference to its parent, but not to its child (for simplicity purposes and to avoid bugs).

Each node stores an object, its name, and a reference to its parent node.

Parameters:

obj (Any) –

A Python object.
name (str) –

The object's name.
parent (ObjectNode | None, default: None ) –

The object's parent node.

Attributes:

alias_target_path (str | None) –

Alias target path of this node, if the node should be an alias.
children (Sequence[ObjectNode]) –

The children of this node.
is_builtin_function (bool) –

Whether this node's object is a builtin function.
is_builtin_method (bool) –

Whether this node's object is a builtin method.
is_cached_property (bool) –

Whether this node's object is a cached property.
is_class (bool) –

Whether this node's object is a class.
is_classmethod (bool) –

Whether this node's object is a classmethod.
is_coroutine (bool) –

Whether this node's object is a coroutine.
is_function (bool) –

Whether this node's object is a function.
is_method (bool) –

Whether this node's object is a method.
is_method_descriptor (bool) –

Whether this node's object is a method descriptor.
is_module (bool) –

Whether this node's object is a module.
is_property (bool) –

Whether this node's object is a property.
is_staticmethod (bool) –

Whether this node's object is a staticmethod.
kind (ObjectKind) –

The kind of this node.
module (ObjectNode) –

The object's module.
name (str) –

The Python object's name.
obj (Any) –

The actual Python object.
parent (ObjectNode | None) –

The parent node.
parent_is_class (bool) –

Whether the object of this node's parent is a class.
path (str) –

The object's (Python) path.

alias_target_path `cached` `property` ¤

alias_target_path: str | None

Alias target path of this node, if the node should be an alias.

children `cached` `property` ¤

children: Sequence[ObjectNode]

The children of this node.

is_builtin_function `cached` `property` ¤

is_builtin_function: bool

Whether this node's object is a builtin function.

is_builtin_method `cached` `property` ¤

is_builtin_method: bool

Whether this node's object is a builtin method.

is_cached_property `cached` `property` ¤

is_cached_property: bool

Whether this node's object is a cached property.

is_class `cached` `property` ¤

is_class: bool

Whether this node's object is a class.

is_classmethod `cached` `property` ¤

is_classmethod: bool

Whether this node's object is a classmethod.

is_coroutine `cached` `property` ¤

is_coroutine: bool

Whether this node's object is a coroutine.

is_function `cached` `property` ¤

is_function: bool

Whether this node's object is a function.

is_method `cached` `property` ¤

is_method: bool

Whether this node's object is a method.

is_method_descriptor `cached` `property` ¤

is_method_descriptor: bool

Whether this node's object is a method descriptor.

Built-in methods (e.g. those implemented in C/Rust) are often method descriptors, rather than normal methods.

is_module `cached` `property` ¤

is_module: bool

Whether this node's object is a module.

is_property `cached` `property` ¤

is_property: bool

Whether this node's object is a property.

is_staticmethod `cached` `property` ¤

is_staticmethod: bool

Whether this node's object is a staticmethod.

kind `property` ¤

kind: ObjectKind

The kind of this node.

module `property` ¤

module: ObjectNode

The object's module.

name `instance-attribute` ¤

name: str = name

The Python object's name.

obj `instance-attribute` ¤

obj: Any = obj

The actual Python object.

parent `instance-attribute` ¤

parent: ObjectNode | None = parent

The parent node.

parent_is_class `cached` `property` ¤

parent_is_class: bool

Whether the object of this node's parent is a class.

path `property` ¤

path: str

The object's (Python) path.

Parser ¤


          flowchart TD
          griffe.Parser[Parser]

          

          click griffe.Parser href "" "griffe.Parser"

Enumeration of the different docstring parsers.

Attributes:

google –

Google-style docstrings parser.
numpy –

Numpydoc-style docstrings parser.
sphinx –

Sphinx-style docstrings parser.

google `class-attribute` `instance-attribute` ¤

google = 'google'

Google-style docstrings parser.

numpy `class-attribute` `instance-attribute` ¤

numpy = 'numpy'

Numpydoc-style docstrings parser.

sphinx `class-attribute` `instance-attribute` ¤

sphinx = 'sphinx'

Sphinx-style docstrings parser.

dynamic_import ¤

dynamic_import(
    import_path: str,
    import_paths: Sequence[str | Path] | None = None,
) -> Any

Dynamically import the specified object.

It can be a module, class, method, function, attribute, nested arbitrarily.

It works like this:

for a given object path a.b.x.y
it tries to import a.b.x.y as a module (with importlib.import_module)
if it fails, it tries again with a.b.x, storing y
then a.b, storing x.y
then a, storing b.x.y
if nothing worked, it raises an error
if one of the iteration worked, it moves on, and...
it tries to get the remaining (stored) parts with getattr
for example it gets b from a, then x from b, etc.
if a single attribute access fails, it raises an error
if everything worked, it returns the last obtained attribute

Since the function potentially tries multiple things before succeeding, all errors happening along the way are recorded, and re-emitted with an ImportError when it fails, to let users know what was tried.

Important

The paths given through the import_paths parameter are used to temporarily patch sys.path: this function is therefore not thread-safe.

Important

The paths given as import_paths must be correct. The contents of sys.path must be consistent to what a user of the imported code would expect. Given a set of paths, if the import fails for a user, it will fail here too, with potentially unintuitive errors. If we wanted to make this function more robust, we could add a loop to "roll the window" of given paths, shifting them to the left (for example: ("/a/a", "/a/b", "/a/c/"), then ("/a/b", "/a/c", "/a/a/"), then ("/a/c", "/a/a", "/a/b/")), to make sure each entry is given highest priority at least once, maintaining relative order, but we deem this unncessary for now.

Parameters:

import_path (str) –

The path of the object to import.
import_paths (Sequence[str | Path] | None, default: None ) –

The (sys) paths to import the object from.

Raises:

ModuleNotFoundError –

When the object's module could not be found.
ImportError –

When there was an import error or when couldn't get the attribute.

Returns:

Any –

The imported object.

find_breaking_changes ¤

find_breaking_changes(
    old_obj: Object | Alias,
    new_obj: Object | Alias,
    *,
    ignore_private: bool = True
) -> Iterator[Breakage]

Find breaking changes between two versions of the same API.

The function will iterate recursively on all objects and yield breaking changes with detailed information.

Parameters:

old_obj (Object | Alias) –

The old version of an object.
new_obj (Object | Alias) –

The new version of an object.

Yields:

Breakage –

Breaking changes.

Examples:

>>> import sys, griffe
>>> new = griffe.load("pkg")
>>> old = griffe.load_git("pkg", "1.2.3")
>>> for breakage in griffe.find_breaking_changes(old, new)
...     print(breakage.explain(style=style), file=sys.stderr)

get_logger ¤

get_logger(name: str) -> _Logger

Create and return a new logger instance.

Parameters:

name (str) –

The logger name.

Returns:

_Logger –

The logger.

load ¤

load(
    objspec: str | Path | None = None,
    /,
    *,
    submodules: bool = True,
    try_relative_path: bool = True,
    extensions: Extensions | None = None,
    search_paths: Sequence[str | Path] | None = None,
    docstring_parser: Parser | None = None,
    docstring_options: dict[str, Any] | None = None,
    lines_collection: LinesCollection | None = None,
    modules_collection: ModulesCollection | None = None,
    allow_inspection: bool = True,
    store_source: bool = True,
    find_stubs_package: bool = False,
    module: str | Path | None = None,
) -> Object

Load and return a module.

Example:

import griffe

module = griffe.load(...)

This is a shortcut for:

from griffe.loader import GriffeLoader

loader = GriffeLoader(...)
module = loader.load(...)

See the documentation for the loader: GriffeLoader.

Parameters:

objspec (str | Path | None, default: None ) –

The Python path of an object, or file path to a module.
submodules (bool, default: True ) –

Whether to recurse on the submodules. This parameter only makes sense when loading a package (top-level module).
try_relative_path (bool, default: True ) –

Whether to try finding the module as a relative path.
extensions (Extensions | None, default: None ) –

The extensions to use.
search_paths (Sequence[str | Path] | None, default: None ) –

The paths to search into.
docstring_parser (Parser | None, default: None ) –

The docstring parser to use. By default, no parsing is done.
docstring_options (dict[str, Any] | None, default: None ) –

Additional docstring parsing options.
lines_collection (LinesCollection | None, default: None ) –

A collection of source code lines.
modules_collection (ModulesCollection | None, default: None ) –

A collection of modules.
allow_inspection (bool, default: True ) –

Whether to allow inspecting modules when visiting them is not possible.
store_source (bool, default: True ) –

Whether to store code source in the lines collection.
find_stubs_package (bool, default: False ) –

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.
module (str | Path | None, default: None ) –

Deprecated. Use objspec positional-only parameter instead.

Returns:

Object –

A Griffe object.

load_extensions ¤

load_extensions(
    exts: (
        Sequence[
            str
            | dict[str, Any]
            | ExtensionType
            | type[ExtensionType]
        ]
        | None
    ) = None
) -> Extensions

Load configured extensions.

Parameters:

exts (Sequence[str | dict[str, Any] | ExtensionType | type[ExtensionType]] | None, default: None ) –

A sequence of extension, with potential configuration options.

Returns:

Extensions –

An extensions container.

load_git ¤

load_git(
    objspec: str | Path | None = None,
    /,
    *,
    ref: str = "HEAD",
    repo: str | Path = ".",
    submodules: bool = True,
    extensions: Extensions | None = None,
    search_paths: Sequence[str | Path] | None = None,
    docstring_parser: Parser | None = None,
    docstring_options: dict[str, Any] | None = None,
    lines_collection: LinesCollection | None = None,
    modules_collection: ModulesCollection | None = None,
    allow_inspection: bool = True,
    find_stubs_package: bool = False,
    module: str | Path | None = None,
) -> Object

Load and return a module from a specific Git reference.

This function will create a temporary git worktree at the requested reference before loading module with griffe.load.

This function requires that the git executable is installed.

Examples:

from griffe.loader import load_git

old_api = load_git("my_module", ref="v0.1.0", repo="path/to/repo")

Parameters:

objspec (str | Path | None, default: None ) –

The Python path of an object, or file path to a module.
ref (str, default: 'HEAD' ) –

A Git reference such as a commit, tag or branch.
repo (str | Path, default: '.' ) –

Path to the repository (i.e. the directory containing the .git directory)
submodules (bool, default: True ) –

Whether to recurse on the submodules. This parameter only makes sense when loading a package (top-level module).
extensions (Extensions | None, default: None ) –

The extensions to use.
search_paths (Sequence[str | Path] | None, default: None ) –

The paths to search into (relative to the repository root).
docstring_parser (Parser | None, default: None ) –

The docstring parser to use. By default, no parsing is done.
docstring_options (dict[str, Any] | None, default: None ) –

Additional docstring parsing options.
lines_collection (LinesCollection | None, default: None ) –

A collection of source code lines.
modules_collection (ModulesCollection | None, default: None ) –

A collection of modules.
allow_inspection (bool, default: True ) –

Whether to allow inspecting modules when visiting them is not possible.
find_stubs_package (bool, default: False ) –

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.
module (str | Path | None, default: None ) –

Deprecated. Use objspec positional-only parameter instead.

Returns:

Object –

A Griffe object.

parse_google ¤

parse_google(
    docstring: Docstring,
    *,
    ignore_init_summary: bool = False,
    trim_doctest_flags: bool = True,
    returns_multiple_items: bool = True,
    warn_unknown_params: bool = True,
    returns_named_value: bool = True,
    returns_type_in_property_summary: bool = False,
    **options: Any
) -> list[DocstringSection]

Parse a Google-style docstring.

This function iterates on lines of a docstring to build sections. It then returns this list of sections.

Parameters:

docstring (Docstring) –

The docstring to parse.
ignore_init_summary (bool, default: False ) –

Whether to ignore the summary in __init__ methods' docstrings.
trim_doctest_flags (bool, default: True ) –

Whether to remove doctest flags from Python example blocks.
returns_multiple_items (bool, default: True ) –

Whether the Returns section has multiple items.
warn_unknown_params (bool, default: True ) –

Warn about documented parameters not appearing in the signature.
returns_named_value (bool, default: True ) –

Whether to parse thing: Description in returns sections as a name and description, rather than a type and description. When true, type must be wrapped in parentheses: (int): Description.. When false, parentheses are optional but the items cannot be named: int: Description.
returns_type_in_property_summary (bool, default: False ) –

Whether to parse the return type of properties at the beginning of their summary: str: Summary of the property.
**options (Any, default: {} ) –

Additional parsing options.

Returns:

list[DocstringSection] –

A list of docstring sections.

parse_numpy ¤

parse_numpy(
    docstring: Docstring,
    *,
    ignore_init_summary: bool = False,
    trim_doctest_flags: bool = True,
    warn_unknown_params: bool = True,
    **options: Any
) -> list[DocstringSection]

Parse a Numpydoc-style docstring.

This function iterates on lines of a docstring to build sections. It then returns this list of sections.

Parameters:

docstring (Docstring) –

The docstring to parse.
ignore_init_summary (bool, default: False ) –

Whether to ignore the summary in __init__ methods' docstrings.
trim_doctest_flags (bool, default: True ) –

Whether to remove doctest flags from Python example blocks.
warn_unknown_params (bool, default: True ) –

Warn about documented parameters not appearing in the signature.
**options (Any, default: {} ) –

Additional parsing options.

Returns:

list[DocstringSection] –

A list of docstring sections.

parse_sphinx ¤

parse_sphinx(
    docstring: Docstring,
    *,
    warn_unknown_params: bool = True,
    **options: Any
) -> list[DocstringSection]

Parse a Sphinx-style docstring.

Parameters:

docstring (Docstring) –

The docstring to parse.
warn_unknown_params (bool, default: True ) –

Warn about documented parameters not appearing in the signature.
**options (Any, default: {} ) –

Additional parsing options.

Returns:

list[DocstringSection] –

A list of docstring sections.

griffe ¤

Attribute ¤

aliases instance-attribute ¤

all_members property ¤

annotation instance-attribute ¤

attributes property ¤

canonical_path property ¤

classes property ¤

docstring instance-attribute ¤

endlineno instance-attribute ¤

exports instance-attribute ¤

extra instance-attribute ¤

filepath property ¤

functions property ¤

has_docstring property ¤

has_docstrings property ¤

imports instance-attribute ¤

inherited class-attribute instance-attribute ¤

inherited_members cached property ¤

is_alias class-attribute instance-attribute ¤

is_attribute property ¤

is_class property ¤

is_collection class-attribute instance-attribute ¤

is_explicitely_exported property ¤

is_function property ¤

is_implicitely_exported property ¤

is_init_module property ¤

is_module property ¤

is_namespace_package property ¤

is_namespace_subpackage property ¤

is_package property ¤

is_subpackage property ¤

kind class-attribute instance-attribute ¤

labels instance-attribute ¤

lineno instance-attribute ¤

lines property ¤

lines_collection property ¤

members instance-attribute ¤

module property ¤

modules property ¤

modules_collection property ¤

name instance-attribute ¤

package property ¤

parent instance-attribute ¤

path property ¤

public instance-attribute ¤

relative_filepath property ¤

relative_package_filepath property ¤

runtime instance-attribute ¤

source property ¤

value instance-attribute ¤

__delitem__ ¤

__getitem__ ¤

__setitem__ ¤

as_dict ¤

as_json ¤

del_member ¤

filter_members ¤

from_json classmethod ¤

get_member ¤

has_labels ¤

is_exported ¤

is_kind ¤

is_public ¤

member_is_exported ¤

resolve ¤

set_member ¤

Class ¤

aliases instance-attribute ¤

all_members property ¤

attributes property ¤

bases instance-attribute ¤

canonical_path property ¤

classes property ¤

decorators instance-attribute ¤

docstring instance-attribute ¤

endlineno instance-attribute ¤

exports instance-attribute ¤

extra instance-attribute ¤

filepath property ¤

aliases `instance-attribute` ¤

all_members `property` ¤

annotation `instance-attribute` ¤

attributes `property` ¤

canonical_path `property` ¤

classes `property` ¤

docstring `instance-attribute` ¤

endlineno `instance-attribute` ¤

exports `instance-attribute` ¤

extra `instance-attribute` ¤

filepath `property` ¤

functions `property` ¤

has_docstring `property` ¤

has_docstrings `property` ¤

imports `instance-attribute` ¤

inherited `class-attribute` `instance-attribute` ¤

inherited_members `cached` `property` ¤

is_alias `class-attribute` `instance-attribute` ¤

is_attribute `property` ¤

is_class `property` ¤

is_collection `class-attribute` `instance-attribute` ¤

is_explicitely_exported `property` ¤

is_function `property` ¤

is_implicitely_exported `property` ¤

is_init_module `property` ¤

is_module `property` ¤

is_namespace_package `property` ¤

is_namespace_subpackage `property` ¤

is_package `property` ¤

is_subpackage `property` ¤

kind `class-attribute` `instance-attribute` ¤

labels `instance-attribute` ¤

lineno `instance-attribute` ¤

lines `property` ¤

lines_collection `property` ¤

members `instance-attribute` ¤

module `property` ¤

modules `property` ¤

modules_collection `property` ¤

name `instance-attribute` ¤

package `property` ¤

parent `instance-attribute` ¤

path `property` ¤

public `instance-attribute` ¤

relative_filepath `property` ¤

relative_package_filepath `property` ¤

runtime `instance-attribute` ¤

source `property` ¤

value `instance-attribute` ¤

delitem ¤

getitem ¤

setitem ¤

from_json `classmethod` ¤

aliases `instance-attribute` ¤

all_members `property` ¤

attributes `property` ¤

bases `instance-attribute` ¤

canonical_path `property` ¤

classes `property` ¤

decorators `instance-attribute` ¤

docstring `instance-attribute` ¤

endlineno `instance-attribute` ¤

exports `instance-attribute` ¤

extra `instance-attribute` ¤

filepath `property` ¤

functions `property` ¤

has_docstring `property` ¤

has_docstrings `property` ¤

imports `instance-attribute` ¤

inherited `class-attribute` `instance-attribute` ¤

inherited_members `cached` `property` ¤

is_alias `class-attribute` `instance-attribute` ¤

is_attribute `property` ¤

is_class `property` ¤

is_collection `class-attribute` `instance-attribute` ¤

is_explicitely_exported `property` ¤

is_function `property` ¤

is_implicitely_exported `property` ¤

is_init_module `property` ¤

is_module `property` ¤