"""
This module defines the Module class, which represents a Python module or package
in the doc-forge documentation model. It acts as a container for top-level
documented objects.
"""

from typing import Dict, Iterable, Optional

from docforge.model.object import DocObject


class Module:
    """
    Represents a documented Python module or package.

    Attributes:
        path: Dotted import path of the module.
        docstring: Module-level docstring content.
        members: Dictionary mapping object names to their DocObject representations.
    """

    def __init__(
        self,
        path: str,
        docstring: Optional[str] = None,
    ) -> None:
        """
        Initialize a new Module.

        Args:
            path: The dotted path of the module.
            docstring: The module's docstring, if any.
        """
        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: The object to add.
        """
        self.members[obj.name] = obj

    def get_object(self, name: str) -> DocObject:
        """
        Retrieve a member object by name.

        Args:
            name: The name of the object.

        Returns:
            The requested DocObject.
        """
        return self.members[name]

    def get_all_objects(self) -> Iterable[DocObject]:
        """
        Get all top-level objects in the module.

        Returns:
            An iterable of DocObject instances.
        """
        return self.members.values()