80 lines
2.2 KiB
Python
80 lines
2.2 KiB
Python
"""
|
|
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.
|
|
"""
|
|
|
|
from typing import Dict, Iterable, Optional
|
|
|
|
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: Dotted import path of the module.
|
|
docstring: Module-level documentation string, if present.
|
|
members: Mapping of object names to their corresponding
|
|
``DocObject`` representations.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
path: str,
|
|
docstring: Optional[str] = None,
|
|
) -> None:
|
|
"""
|
|
Initialize a Module instance.
|
|
|
|
Args:
|
|
path: Dotted import path identifying the module.
|
|
docstring: 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: 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: Name of the object to retrieve.
|
|
|
|
Returns:
|
|
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:
|
|
An iterable of ``DocObject`` instances representing the
|
|
module's public members.
|
|
"""
|
|
return self.members.values()
|