Function ¤

Bases: Object

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

                              griffe._internal.models.Object --> griffe.Function
                                griffe._internal.mixins.ObjectAliasMixin --> griffe._internal.models.Object
                                griffe._internal.mixins.GetMembersMixin --> griffe._internal.mixins.ObjectAliasMixin
                
                griffe._internal.mixins.SetMembersMixin --> griffe._internal.mixins.ObjectAliasMixin
                
                griffe._internal.mixins.DelMembersMixin --> griffe._internal.mixins.ObjectAliasMixin
                
                griffe._internal.mixins.SerializationMixin --> griffe._internal.mixins.ObjectAliasMixin
                




              click griffe.Function href "" "griffe.Function"
              click griffe._internal.models.Object href "" "griffe._internal.models.Object"
              click griffe._internal.mixins.ObjectAliasMixin href "" "griffe._internal.mixins.ObjectAliasMixin"
              click griffe._internal.mixins.GetMembersMixin href "" "griffe._internal.mixins.GetMembersMixin"
              click griffe._internal.mixins.SetMembersMixin href "" "griffe._internal.mixins.SetMembersMixin"
              click griffe._internal.mixins.DelMembersMixin href "" "griffe._internal.mixins.DelMembersMixin"
              click griffe._internal.mixins.SerializationMixin href "" "griffe._internal.mixins.SerializationMixin"
            

The class representing a Python function.

Parameters:

• *args ¤

  (Any, default: () ) –

  See griffe.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.Object.

Methods:

• __bool__ –

  An object is always true-ish.

• __delitem__ –

  Delete a member with its name or path.

• __getitem__ –

  Get a member with its name or path.

• __len__ –

  The number of members in this object, recursively.

• __setitem__ –

  Set a member with its name or path.

• as_dict –

  Return this function's data as a dictionary.

• as_json –

  Return this object's data as a JSON string.

• del_member –

  Delete a member with its name or path.

• filter_members –

  Filter and return members based on predicates.

• from_json –

  Create an instance of this class from a JSON string.

• get_member –

  Get a member with its name or path.

• has_labels –

  Tell if this object has all the given labels.

• is_kind –

  Tell if this object is of the given kind.

• resolve –

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

• set_member –

  Set a member with its name or path.

• signature –

  Construct the function signature.

Attributes:

• aliases (dict[str, Alias]) –

  The aliases pointing to this object.

• all_members (dict[str, Object | Alias]) –

  All members (declared and inherited).

• analysis (Literal['static', 'dynamic'] | None) –

  The type of analysis used to load this object.

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

• deprecated (bool | str | None) –

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

• docstring (Docstring | None) –

  The object docstring.

• endlineno (int | None) –

  The ending line number of the object.

• exports (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.

• git_info (GitInfo | None) –

  Git information for this object, if available.

• 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) –

  Always false for objects.

• inherited_members (dict[str, Alias]) –

  Members that are inherited from base classes.

• is_alias (bool) –

  Always false for objects.

• is_attribute (bool) –

  Whether this object is an attribute.

• is_class (bool) –

  Whether this object is a class.

• is_class_private (bool) –

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

• is_collection (bool) –

  Always false for objects.

• is_deprecated (bool) –

  Whether this object is deprecated.

• is_exported (bool) –

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

• is_function (bool) –

  Whether this object is a function.

• is_generic (bool) –

  Whether this object is generic.

• is_imported (bool) –

  Whether this object/alias was imported from another module.

• is_init_method (bool) –

  Whether this function is an __init__ method.

• 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_private (bool) –

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

• is_public (bool) –

  Whether this object is considered public.

• is_special (bool) –

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

• is_subpackage (bool) –

  Whether this object is a subpackage.

• is_type_alias (bool) –

  Whether this object is a type alias.

• is_wildcard_exposed (bool) –

  Whether this object/alias is exposed to wildcard imports.

• 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, type aliases).

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

• source (str) –

  The source code of this object.

• source_link (str | None) –

  Source link for this object, if available.

• type_aliases (dict[str, TypeAlias]) –

  The type alias members.

• type_parameters (TypeParameters) –

  The object type parameters.

2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516

def __init__(
    self,
    *args: Any,
    parameters: Parameters | None = None,
    returns: str | Expr | None = None,
    decorators: list[Decorator] | None = None,
    **kwargs: Any,
) -> None:
    """Initialize the function.

    Parameters:
        *args: See [`griffe.Object`][].
        parameters: The function parameters.
        returns: The function return annotation.
        decorators: The function decorators, if any.
        **kwargs: See [`griffe.Object`][].
    """
    super().__init__(*args, **kwargs)
    self.parameters: Parameters = parameters or Parameters()
    """The function parameters."""
    self.returns: str | Expr | None = returns
    """The function return type annotation."""
    self.decorators: list[Decorator] = decorators or []
    """The function decorators."""
    self.overloads: list[Function] | None = None
    """The overloaded signatures of this function."""

    for parameter in self.parameters:
        parameter.function = self

aliases: dict[str, Alias] = {}

all_members: dict[str, Object | Alias]

analysis: Literal['static', 'dynamic'] | None = analysis

annotation: str | Expr | None

attributes: dict[str, Attribute]

canonical_path: str

classes: dict[str, Class]

decorators: list[Decorator] = decorators or []

deprecated: bool | str | None = None

docstring: Docstring | None = docstring

endlineno: int | None = endlineno

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

from .submodule import __all__ as submodule_all

__all__ = ["hello", *submodule_all]

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

filepath: Path | list[Path]

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

functions: dict[str, Function]

git_info: GitInfo | None

has_docstring: bool

has_docstrings: bool

imports: dict[str, str] = {}

inherited: bool = False

inherited_members: dict[str, Alias]

is_alias: bool = False

is_attribute: bool

is_class: bool

is_class_private: bool

is_collection: bool = False

is_deprecated: bool

is_exported: bool

is_function: bool

is_generic: bool

is_imported: bool

is_init_method: bool

is_init_module: bool

is_module: bool

is_namespace_package: bool

is_namespace_subpackage: bool

is_package: bool

is_private: bool

is_public: bool

is_special: bool

is_subpackage: bool

is_type_alias: bool

is_wildcard_exposed: bool

kind = FUNCTION

labels: set[str] = set()

lineno: int | None = lineno

lines: list[str]

lines_collection: LinesCollection

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

module: Module

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

modules: dict[str, Module]

modules_collection: ModulesCollection

name: str = name

overloads: list[Function] | None = None

package: Module

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

parameters: Parameters = parameters or Parameters()

parent: Module | Class | None = parent

path: str

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

public: bool | None = None

relative_filepath: Path

relative_package_filepath: Path

returns: str | Expr | None = returns

runtime: bool = runtime

source: str

source_link: str | None

type_aliases: dict[str, TypeAlias]

type_parameters: TypeParameters = (
    type_parameters or TypeParameters()
)

__bool__() -> bool

717
718
719

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

__delitem__(key: str | Sequence[str]) -> None

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

 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112

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

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

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

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

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

__getitem__(key: str | Sequence[str]) -> Any

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

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

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

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

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

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

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

__len__() -> int

721
722
723

def __len__(self) -> int:
    """The number of members in this object, recursively."""
    return len(self.members) + sum(len(member) for member in self.members.values())

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

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

142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

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

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

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

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

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

2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576

def as_dict(self, **kwargs: Any) -> dict[str, Any]:
    """Return this function's data as a dictionary.

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

    Parameters:
        **kwargs: Additional serialization options.

    Returns:
        A dictionary.
    """
    base = super().as_dict(**kwargs)
    base["decorators"] = [dec.as_dict(**kwargs) for dec in self.decorators]
    base["parameters"] = [param.as_dict(**kwargs) for param in self.parameters]
    base["returns"] = self.returns
    return base

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

215
216
217
218
219
220
221
222
223
224
225
226
227

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

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

    Returns:
        A JSON string.
    """
    from griffe._internal.encoders import JSONEncoder  # Avoid circular import.  # noqa: PLC0415

    return json.dumps(self, cls=JSONEncoder, full=full, **kwargs)

del_member(key: str | Sequence[str]) -> None

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

114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

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

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

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

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

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

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