Vishesh 'ironeagle' Bangotra
582b6809a0
- fix GSDFC spec contradictions in __init__ docstring (parenthesized types, fenced-block rule) and sync generated README - rewrite docstrings across loaders, models, nav, servers, renderers, cli; sync .pyi stubs - add pydoclint (google style) gate to dev extras and pyproject config - fix mcp nav resources doc:// -> docs:// - refresh docs/lib and docs/mcp, drop stale docforge/ duplicate group - update wiki pages and add GSDFC + MCP guides under 05_development
99 lines
2.5 KiB
Python
99 lines
2.5 KiB
Python
"""
|
|
# Summary
|
|
|
|
Documentation model representing a Python module or package.
|
|
|
|
This module defines the `Module` class used in the doc-forge documentation
|
|
model. A `Module` acts as a container for top-level documented objects
|
|
(classes, functions, variables, and other members) discovered during
|
|
introspection.
|
|
|
|
---
|
|
|
|
Notes:
|
|
- Only public members are stored; private names are filtered by the loader.
|
|
|
|
---
|
|
"""
|
|
|
|
from collections.abc import Iterable
|
|
|
|
from docforge.models.object import DocObject
|
|
|
|
|
|
class Module:
|
|
"""
|
|
Representation of a documented Python module or package.
|
|
|
|
A `Module` stores metadata about the module itself and maintains a
|
|
collection of top-level documentation objects discovered during
|
|
introspection.
|
|
|
|
Attributes:
|
|
path (str):
|
|
Dotted import path of the module.
|
|
|
|
docstring (str | None):
|
|
Module-level documentation string, if present.
|
|
|
|
members (dict[str, DocObject]):
|
|
Mapping of object names to their corresponding `DocObject` representations.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
path: str,
|
|
docstring: str | None = None,
|
|
) -> None:
|
|
"""
|
|
Initialize a Module instance.
|
|
|
|
Args:
|
|
path (str):
|
|
Dotted import path identifying the module.
|
|
|
|
docstring (str | None):
|
|
Module-level documentation text, if available.
|
|
"""
|
|
self.path = path
|
|
self.docstring = docstring
|
|
self.members: dict[str, DocObject] = {}
|
|
|
|
def add_object(self, obj: DocObject) -> None:
|
|
"""
|
|
Add a documented object to the module.
|
|
|
|
Args:
|
|
obj (DocObject):
|
|
Documentation object to register as a top-level member of the module.
|
|
"""
|
|
self.members[obj.name] = obj
|
|
|
|
def get_object(self, name: str) -> DocObject:
|
|
"""
|
|
Retrieve a documented object by name.
|
|
|
|
Args:
|
|
name (str):
|
|
Name of the object to retrieve.
|
|
|
|
Returns:
|
|
DocObject:
|
|
The corresponding `DocObject` instance.
|
|
|
|
Raises:
|
|
KeyError:
|
|
If no object with the given name exists.
|
|
"""
|
|
return self.members[name]
|
|
|
|
def get_all_objects(self) -> Iterable[DocObject]:
|
|
"""
|
|
Return all top-level documentation objects in the module.
|
|
|
|
Returns:
|
|
Iterable[DocObject]:
|
|
An iterable of `DocObject` instances representing the module's public members.
|
|
"""
|
|
return self.members.values()
|