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