Griffe Loader

docforge.loaders.griffe_loader

Utilities for loading and introspecting Python modules using Griffe.

This module provides the GriffeLoader class and helper utilities used to discover Python modules, introspect their structure, and convert the results into doc-forge documentation models.

Classes

GriffeLoader

GriffeLoader()

Load Python modules using Griffe and convert them into doc-forge models.

This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge.

Initialize the Griffe-backed loader.

Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

Functions

load_module

load_module(path: str) -> Module

Load and convert a single Python module.

The module is introspected using Griffe and then transformed into a doc-forge Module model.

Parameters:

Name	Type	Description	Default
path	str	Dotted import path of the module.	required

Returns:

Type	Description
Module	A populated Module instance.

load_project

load_project(module_paths: List[str], project_name: Optional[str] = None, skip_import_errors: bool = None) -> Project

Load multiple modules and assemble them into a Project model.

Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

Parameters:

Name	Type	Description	Default
module_paths	List[str]	List of dotted module import paths to load.	required
project_name	Optional[str]	Optional override for the project name. Defaults to the top-level name of the first module.	None
skip_import_errors	bool	If True, modules that fail to load will be skipped instead of raising an error.	None

Returns:

Type	Description
Project	A populated Project instance containing the loaded modules.

Raises:

Type	Description
ValueError	If no module paths are provided.
ImportError	If a module fails to load and skip_import_errors is False.

Functions

discover_module_paths

discover_module_paths(module_name: str, project_root: Path | None = None) -> List[str]

Discover Python modules within a package directory.

The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

Discovery rules:

• Directories containing __init__.py are treated as packages.
• Each .py file is treated as a module.
• Results are returned as dotted import paths.

Parameters:

Name	Type	Description	Default
module_name	str	Top-level package name to discover modules from.	required
project_root	Path | None	Root directory used to resolve module paths. If not provided, the current working directory is used.	None

Returns:

Type	Description
List[str]	A sorted list of unique dotted module import paths.

Raises:

Type	Description
FileNotFoundError	If the specified package directory does not exist.