Vishesh 'ironeagle' Bangotra
4ec67c86c6
- Stringify Object.signature() instead of str()-ing the bound method, which produced "<bound method Class.signature of ...>" reprs - Skip alias members that cannot resolve (stdlib/third-party imports) while preserving resolvable package re-exports; return None for empty signatures (classes without __init__ args) - Add MCP renderer regression tests for signature cleanliness, alias filtering, and package re-export preservation
259 lines
19 KiB
JSON
259 lines
19 KiB
JSON
{
|
||
"module": "docforge.loaders",
|
||
"content": {
|
||
"path": "docforge.loaders",
|
||
"docstring": "# Summary\n\nLoader layer for doc-forge.\n\nThe `docforge.loaders` package is responsible for discovering Python modules\nand extracting documentation data using static analysis.\n\n---\n\n# Overview\n\nThis layer converts Python source code into an intermediate documentation\nmodel used by doc-forge. It performs module discovery, introspection, and\ninitial filtering before the data is passed to the core documentation models.\n\nCore capabilities include:\n\n- **Module discovery** – Locate Python modules and packages within a project.\n- **Static introspection** – Parse docstrings, signatures, and object\n hierarchies using the `griffe` library without executing the code.\n- **Public API filtering** – Exclude private members (names prefixed with\n `_`) to produce clean public documentation structures.\n\n---",
|
||
"objects": {
|
||
"GriffeLoader": {
|
||
"name": "GriffeLoader",
|
||
"kind": "class",
|
||
"path": "docforge.loaders.GriffeLoader",
|
||
"signature": "GriffeLoader()",
|
||
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
|
||
"members": {
|
||
"load_project": {
|
||
"name": "load_project",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.GriffeLoader.load_project",
|
||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None)",
|
||
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
|
||
},
|
||
"load_module": {
|
||
"name": "load_module",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.GriffeLoader.load_module",
|
||
"signature": "load_module(path: str)",
|
||
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```"
|
||
}
|
||
}
|
||
},
|
||
"discover_module_paths": {
|
||
"name": "discover_module_paths",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.discover_module_paths",
|
||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None)",
|
||
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
|
||
},
|
||
"griffe_loader": {
|
||
"name": "griffe_loader",
|
||
"kind": "module",
|
||
"path": "docforge.loaders.griffe_loader",
|
||
"signature": null,
|
||
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.\n\n---\n\nNotes:\n - All analysis is static; analyzed modules are never executed.\n - Private members (names starting with `_`) are skipped during conversion.\n - Imported aliases that cannot be resolved (stdlib/third-party names) are\n skipped; aliases that resolve within the documented project are kept.\n\n---",
|
||
"members": {
|
||
"DocObject": {
|
||
"name": "DocObject",
|
||
"kind": "class",
|
||
"path": "docforge.loaders.griffe_loader.DocObject",
|
||
"signature": "DocObject(name: str, kind: str, path: str, signature: str | None = None, docstring: str | None = None)",
|
||
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (str | None):\n Callable signature if the object represents a callable.\n\n docstring (str | None):\n Raw docstring text extracted from the source code.\n\n members (dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.",
|
||
"members": {
|
||
"name": {
|
||
"name": "name",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.name",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"kind": {
|
||
"name": "kind",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.kind",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"path": {
|
||
"name": "path",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.path",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"signature": {
|
||
"name": "signature",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.signature",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"docstring": {
|
||
"name": "docstring",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.docstring",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"members": {
|
||
"name": "members",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.members",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"add_member": {
|
||
"name": "add_member",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.add_member",
|
||
"signature": "add_member(obj: DocObject)",
|
||
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj (DocObject):\n Documentation object to add as a member."
|
||
},
|
||
"get_member": {
|
||
"name": "get_member",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.get_member",
|
||
"signature": "get_member(name: str)",
|
||
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist."
|
||
},
|
||
"get_all_members": {
|
||
"name": "get_all_members",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.DocObject.get_all_members",
|
||
"signature": "get_all_members()",
|
||
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members."
|
||
}
|
||
}
|
||
},
|
||
"Module": {
|
||
"name": "Module",
|
||
"kind": "class",
|
||
"path": "docforge.loaders.griffe_loader.Module",
|
||
"signature": "Module(path: str, docstring: str | None = None)",
|
||
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (str | None):\n Module-level documentation string, if present.\n\n members (dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.",
|
||
"members": {
|
||
"path": {
|
||
"name": "path",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.Module.path",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"docstring": {
|
||
"name": "docstring",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.Module.docstring",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"members": {
|
||
"name": "members",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.Module.members",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"add_object": {
|
||
"name": "add_object",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.Module.add_object",
|
||
"signature": "add_object(obj: DocObject)",
|
||
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module."
|
||
},
|
||
"get_object": {
|
||
"name": "get_object",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.Module.get_object",
|
||
"signature": "get_object(name: str)",
|
||
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists."
|
||
},
|
||
"get_all_objects": {
|
||
"name": "get_all_objects",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.Module.get_all_objects",
|
||
"signature": "get_all_objects()",
|
||
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members."
|
||
}
|
||
}
|
||
},
|
||
"Project": {
|
||
"name": "Project",
|
||
"kind": "class",
|
||
"path": "docforge.loaders.griffe_loader.Project",
|
||
"signature": "Project(name: str)",
|
||
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (dict[str, Module]):\n Mapping of module paths to `Module` instances.",
|
||
"members": {
|
||
"name": {
|
||
"name": "name",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.Project.name",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"modules": {
|
||
"name": "modules",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.Project.modules",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"add_module": {
|
||
"name": "add_module",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.Project.add_module",
|
||
"signature": "add_module(module: Module)",
|
||
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project."
|
||
},
|
||
"get_module": {
|
||
"name": "get_module",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.Project.get_module",
|
||
"signature": "get_module(path: str)",
|
||
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project."
|
||
},
|
||
"get_all_modules": {
|
||
"name": "get_all_modules",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.Project.get_all_modules",
|
||
"signature": "get_all_modules()",
|
||
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances."
|
||
},
|
||
"get_module_list": {
|
||
"name": "get_module_list",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.Project.get_module_list",
|
||
"signature": "get_module_list()",
|
||
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project."
|
||
}
|
||
}
|
||
},
|
||
"logger": {
|
||
"name": "logger",
|
||
"kind": "attribute",
|
||
"path": "docforge.loaders.griffe_loader.logger",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"discover_module_paths": {
|
||
"name": "discover_module_paths",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.discover_module_paths",
|
||
"signature": "discover_module_paths(module_name: str, project_root: Path | None = None) -> list[str]",
|
||
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
|
||
},
|
||
"GriffeLoader": {
|
||
"name": "GriffeLoader",
|
||
"kind": "class",
|
||
"path": "docforge.loaders.griffe_loader.GriffeLoader",
|
||
"signature": "GriffeLoader()",
|
||
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
|
||
"members": {
|
||
"load_project": {
|
||
"name": "load_project",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
|
||
"signature": "load_project(module_paths: list[str], project_name: str | None = None, skip_import_errors: bool | None = None) -> Project",
|
||
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
|
||
},
|
||
"load_module": {
|
||
"name": "load_module",
|
||
"kind": "function",
|
||
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_module",
|
||
"signature": "load_module(path: str) -> Module",
|
||
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
} |