Module ¤

Bases: Object

              flowchart TD
              griffe.Module[Module]
              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.Module
                                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.Module href "" "griffe.Module"
              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 module.

Parameters:

• *args ¤

  (Any, default: () ) –

  See griffe.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.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 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_kind –

  Tell if this object is of the given kind.

• resolve –

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

• set_member –

  Set a member with its name or path.

Attributes:

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

• attributes (dict[str, Attribute]) –

  The attribute members.

• canonical_path (str) –

  The full dotted path of this object.

• classes (dict[str, Class]) –

  The class members.

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

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

• imports_future_annotations (bool) –

  Whether this module import future annotations.

• 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 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_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 module 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 (dict[str, list[Function]]) –

  The overloaded signatures 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.

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

2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331

def __init__(self, *args: Any, filepath: Path | list[Path] | None = None, **kwargs: Any) -> None:
    """Initialize the module.

    Parameters:
        *args: See [`griffe.Object`][].
        filepath: The module file path (directory for namespace [sub]packages, none for builtin modules).
        **kwargs: See [`griffe.Object`][].
    """
    super().__init__(*args, **kwargs)
    self._filepath: Path | list[Path] | None = filepath
    self.overloads: dict[str, list[Function]] = defaultdict(list)
    """The overloaded signatures declared in this module."""

aliases: dict[str, Alias] = {}

all_members: dict[str, Object | Alias]

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

attributes: dict[str, Attribute]

canonical_path: str

classes: dict[str, Class]

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]

functions: dict[str, Function]

git_info: GitInfo | None

has_docstring: bool

has_docstrings: bool

imports: dict[str, str] = {}

imports_future_annotations: bool

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 = Kind.MODULE

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: dict[str, list[Function]] = defaultdict(list)

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

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

runtime: bool = runtime

source: str

source_link: str | None

type_aliases: dict[str, TypeAlias]

type_parameters: TypeParameters = (
    type_parameters or TypeParameters()
)

__bool__() -> bool

773
774
775

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

103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

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]  # ty:ignore[unresolved-attribute]
        except KeyError:
            del self.inherited_members[name]  # ty:ignore[unresolved-attribute]
    else:
        del self.all_members[parts[0]][parts[1:]]  # ty:ignore[unresolved-attribute]

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

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

53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

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]]  # ty:ignore[unresolved-attribute]
    return self.all_members[parts[0]][parts[1:]]  # ty:ignore[unresolved-attribute]

__len__() -> int

777
778
779

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

158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182

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  # ty:ignore[unresolved-attribute]
        if self.is_collection:  # ty:ignore[unresolved-attribute]
            value._modules_collection = self  # ty:ignore[invalid-assignment]
        else:
            value.parent = self  # ty:ignore[invalid-assignment]
    else:
        self.members[parts[0]][parts[1:]] = value  # ty:ignore[unresolved-attribute]

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

2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435

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

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

    Parameters:
        **kwargs: Additional serialization options.

    Returns:
        A dictionary.
    """
    base = super().as_dict(**kwargs)
    if isinstance(self._filepath, list):
        base["filepath"] = [str(path) for path in self._filepath]
    elif self._filepath:
        base["filepath"] = str(self._filepath)
    else:
        base["filepath"] = None
    return base

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

232
233
234
235
236
237
238
239
240
241
242
243
244

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

130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

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]  # ty:ignore[unresolved-attribute]
    else:
        self.members[parts[0]].del_member(parts[1:])  # ty:ignore[unresolved-attribute]

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

1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051

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

    See also: [`members`][griffe.Object.members].

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

    Returns:
        A dictionary of members.
    """
    if not predicates:
        return self.members
    members: dict[str, Object | Alias] = {
        name: member for name, member in self.members.items() if all(predicate(member) for predicate in predicates)
    }
    return members

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

246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267

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

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

    Returns:
        An Object instance.

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

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