129 lines
4.2 KiB
Python
129 lines
4.2 KiB
Python
"""Module representation in the doc-forge documentation model.
|
|
|
|
Module represents a Python module that can be documented. It serves as
|
|
a container for all the documentation objects within that module,
|
|
including classes, functions, attributes, and constants.
|
|
|
|
Each Module corresponds to a Python import path and contains the
|
|
module-level docstring along with all documented members.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import Dict, List, Optional
|
|
|
|
from .object import DocObject
|
|
|
|
|
|
class Module:
|
|
"""Represents a Python module in the documentation model.
|
|
|
|
A Module is the primary organizational unit in doc-forge. It corresponds
|
|
to a Python module (identified by its import path) and contains all
|
|
the documentation objects within that module.
|
|
|
|
Attributes:
|
|
path: The import path of the module (e.g., "package.submodule")
|
|
docstring: Optional module-level docstring
|
|
members: Dictionary of all documented objects in the module
|
|
"""
|
|
|
|
def __init__(self, path: str, docstring: Optional[str] = None) -> None:
|
|
"""Initialize a Module.
|
|
|
|
Args:
|
|
path: The import path of the module
|
|
docstring: Optional module-level docstring
|
|
|
|
Raises:
|
|
ValueError: If path is empty
|
|
"""
|
|
if not path:
|
|
raise ValueError("Module path cannot be empty")
|
|
|
|
self.path: str = path
|
|
self.docstring: Optional[str] = docstring
|
|
self.members: Dict[str, DocObject] = {}
|
|
|
|
def add_object(self, obj: DocObject) -> None:
|
|
"""Add a documentation object to this module.
|
|
|
|
Args:
|
|
obj: The documentation object to add
|
|
|
|
Raises:
|
|
ValueError: If object name conflicts with existing object
|
|
"""
|
|
if obj.name in self.members:
|
|
raise ValueError(f"Object '{obj.name}' already exists in module '{self.path}'")
|
|
self.members[obj.name] = obj
|
|
|
|
def get_object(self, name: str) -> Optional[DocObject]:
|
|
"""Get a documentation object by name.
|
|
|
|
Args:
|
|
name: The name of the object to retrieve
|
|
|
|
Returns:
|
|
The DocObject if found, None otherwise
|
|
"""
|
|
return self.members.get(name)
|
|
|
|
def get_public_objects(self) -> List[DocObject]:
|
|
"""Get all public (non-private) documentation objects.
|
|
|
|
Returns:
|
|
List of DocObjects that are not private
|
|
"""
|
|
return [obj for obj in self.members.values() if not obj.is_private()]
|
|
|
|
def get_objects_by_kind(self, kind: str) -> List[DocObject]:
|
|
"""Get all documentation objects of a specific kind.
|
|
|
|
Args:
|
|
kind: The kind of objects to retrieve (e.g., "class", "function")
|
|
|
|
Returns:
|
|
List of DocObjects matching the specified kind
|
|
"""
|
|
return [obj for obj in self.members.values() if obj.kind == kind]
|
|
|
|
def get_classes(self) -> List[DocObject]:
|
|
"""Get all class objects in this module.
|
|
|
|
Returns:
|
|
List of DocObjects with kind "class"
|
|
"""
|
|
return self.get_objects_by_kind("class")
|
|
|
|
def get_functions(self) -> List[DocObject]:
|
|
"""Get all function objects in this module.
|
|
|
|
Returns:
|
|
List of DocObjects with kind "function"
|
|
"""
|
|
return self.get_objects_by_kind("function")
|
|
|
|
def has_docstring(self) -> bool:
|
|
"""Check if this module has a docstring.
|
|
|
|
Returns:
|
|
True if docstring is not None and not empty, False otherwise
|
|
"""
|
|
return bool(self.docstring and self.docstring.strip())
|
|
|
|
def is_empty(self) -> bool:
|
|
"""Check if this module contains any documented objects.
|
|
|
|
Returns:
|
|
True if the module has no members, False otherwise
|
|
"""
|
|
return len(self.members) == 0
|
|
|
|
def __repr__(self) -> str:
|
|
"""Return a string representation of the Module.
|
|
|
|
Returns:
|
|
String representation showing path and member count
|
|
"""
|
|
return f"Module(path='{self.path}', members={len(self.members)})" |