loader ¤

This module contains the code allowing to load modules data.

This is the entrypoint to use griffe programatically:

from griffe.loader import GriffeLoader

griffe = GriffeLoader()
fastapi = griffe.load("fastapi")

Classes:

GriffeLoader –

The Griffe loader, allowing to load data from modules.

Functions:

load –

Load and return a module.
load_git –

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

Load and return a module from a specific package version downloaded using pip.

GriffeLoader ¤

GriffeLoader(
    *,
    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
)

The Griffe loader, allowing to load data from modules.

Parameters:

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.

Methods:

expand_exports –

Expand exports: try to recursively expand all module exports (__all__ values).
expand_wildcards –

Expand wildcards: try to recursively expand all found wildcards.
load –

Load an object as a Griffe object, given its Python or file path.
load_module –

Renamed load. Load an object as a Griffe object, given its dotted path.
resolve_aliases –

Resolve aliases.
resolve_module_aliases –

Follow aliases: try to recursively resolve all found aliases.
stats –

Compute some statistics.

Attributes:

allow_inspection (bool) –

Whether to allow inspecting (importing) modules for which we can't find sources.
docstring_options (dict[str, Any]) –

Configured parsing options.
docstring_parser (Parser | None) –

Selected docstring parser.
extensions (Extensions) –

Loaded Griffe extensions.
finder (ModuleFinder) –

The module source finder.
lines_collection (LinesCollection) –

Collection of source code lines.
modules_collection (ModulesCollection) –

Collection of modules.
store_source (bool) –

Whether to store source code in the lines collection.

allow_inspection `instance-attribute` ¤

allow_inspection: bool = allow_inspection

Whether to allow inspecting (importing) modules for which we can't find sources.

docstring_options `instance-attribute` ¤

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

Configured parsing options.

docstring_parser `instance-attribute` ¤

docstring_parser: Parser | None = docstring_parser

Selected docstring parser.

extensions `instance-attribute` ¤

extensions: Extensions = extensions or load_extensions()

Loaded Griffe extensions.

finder `instance-attribute` ¤

finder: ModuleFinder = ModuleFinder(search_paths)

The module source finder.

lines_collection `instance-attribute` ¤

lines_collection: LinesCollection = (
    lines_collection or LinesCollection()
)

Collection of source code lines.

modules_collection `instance-attribute` ¤

modules_collection: ModulesCollection = (
    modules_collection or ModulesCollection()
)

Collection of modules.

store_source `instance-attribute` ¤

store_source: bool = store_source

Whether to store source code in the lines collection.

expand_exports ¤

expand_exports(
    module: Module, seen: set | None = None
) -> None

Expand exports: try to recursively expand all module exports (__all__ values).

Parameters:

module (Module) –

The module to recurse on.
seen (set | None, default: None ) –

Used to avoid infinite recursion.

expand_wildcards ¤

expand_wildcards(
    obj: Object,
    *,
    external: bool = False,
    seen: set | None = None
) -> None

Expand wildcards: try to recursively expand all found wildcards.

Parameters:

obj (Object) –

The object and its members to recurse on.
external (bool, default: False ) –

When true, try to load unspecified modules to expand wildcards.
seen (set | None, default: None ) –

Used to avoid infinite recursion.

load ¤

load(
    objspec: str | Path | None = None,
    /,
    *,
    submodules: bool = True,
    try_relative_path: bool = True,
    find_stubs_package: bool = False,
    module: str | Path | None = None,
) -> Object

Load an object as a Griffe object, given its Python or file path.

Note that this will load the whole object's package, and return only the specified object. The rest of the package can be accessed from the returned object with regular methods and properties (parent, members, etc.).

Examples:

>>> loader.load("griffe.dataclasses.Module")
Class("Module")
>>> loader.load("src/griffe/dataclasses.py")
Module("dataclasses")

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

Raises:

LoadingError –

When loading a module failed for various reasons.
ModuleNotFoundError –

When a module was not found and inspection is disallowed.

Returns:

Object –

A Griffe object.

load_module ¤

load_module(
    module: str | Path,
    *,
    submodules: bool = True,
    try_relative_path: bool = True,
    find_stubs_package: bool = False
) -> Object

Renamed load. Load an object as a Griffe object, given its dotted path.

This method was renamed load.

resolve_aliases ¤

resolve_aliases(
    *,
    implicit: bool = False,
    external: bool = False,
    max_iterations: int | None = None
) -> tuple[set[str], int]

Resolve aliases.

Parameters:

implicit (bool, default: False ) –

When false, only try to resolve an alias if it is explicitely exported.
external (bool, default: False ) –

When false, don't try to load unspecified modules to resolve aliases.
max_iterations (int | None, default: None ) –

Maximum number of iterations on the loader modules collection.

Returns:

tuple[set[str], int] –

The unresolved aliases and the number of iterations done.

resolve_module_aliases ¤

resolve_module_aliases(
    obj: Object | Alias,
    *,
    implicit: bool = False,
    external: bool = False,
    seen: set[str] | None = None,
    load_failures: set[str] | None = None
) -> tuple[set[str], set[str]]

Follow aliases: try to recursively resolve all found aliases.

Parameters:

obj (Object | Alias) –

The object and its members to recurse on.
implicit (bool, default: False ) –

When false, only try to resolve an alias if it is explicitely exported.
external (bool, default: False ) –

When false, don't try to load unspecified modules to resolve aliases.
seen (set[str] | None, default: None ) –

Used to avoid infinite recursion.
load_failures (set[str] | None, default: None ) –

Set of external packages we failed to load (to prevent retries).

Returns:

tuple[set[str], set[str]] –

Both sets of resolved and unresolved aliases.

stats ¤

stats() -> dict

Compute some statistics.

Returns:

dict –

Some statistics.

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

load_pypi ¤

load_pypi(
    package: str,
    distribution: str,
    version_spec: str,
    *,
    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
) -> Object

Load and return a module from a specific package version downloaded using pip.

Parameters:

package (str) –

The package import name.
distribution (str) –

The distribution name.
version_spec (str) –

The version specifier to use when installing with pip.
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.

loader ¤

GriffeLoader ¤

allow_inspection instance-attribute ¤

docstring_options instance-attribute ¤

docstring_parser instance-attribute ¤

extensions instance-attribute ¤

finder instance-attribute ¤

lines_collection instance-attribute ¤

modules_collection instance-attribute ¤

store_source instance-attribute ¤

expand_exports ¤

expand_wildcards ¤

load ¤

load_module ¤

resolve_aliases ¤

resolve_module_aliases ¤

stats ¤

load ¤

load_git ¤

load_pypi ¤

allow_inspection `instance-attribute` ¤

docstring_options `instance-attribute` ¤

docstring_parser `instance-attribute` ¤

extensions `instance-attribute` ¤

finder `instance-attribute` ¤

lines_collection `instance-attribute` ¤

modules_collection `instance-attribute` ¤

store_source `instance-attribute` ¤