"""
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()