Skip to content

# Griffe Loader

## `` docforge.loaders.griffe_loader

### Summary

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

    1

    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

    1

    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:

Name | Type | Description
--- | --- | ---
`Module` | `Module` | A populated `Module` instance.

###### `` load_project

    1

    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` | `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:

Name | Type | Description
--- | --- | ---
`Project` | `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

    1

    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` | Root directory used to resolve module paths. If not provided, the current working directory is used. | `None`

Returns:

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

Raises:

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