init docforge lib

docforge/model/module.py

@@ -0,0 +1,129 @@
+"""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)})"