92 lines
2.4 KiB
Python
92 lines
2.4 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.
|
|
"""
|
|
|
|
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 (str):
|
|
Dotted import path of the module.
|
|
|
|
docstring (Optional[str]):
|
|
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: Optional[str] = None,
|
|
) -> None:
|
|
"""
|
|
Initialize a Module instance.
|
|
|
|
Args:
|
|
path (str):
|
|
Dotted import path identifying the module.
|
|
|
|
docstring (Optional[str]):
|
|
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()
|