"""
This module defines the Project class, the top-level container for a documented
project. It aggregates multiple Module instances into a single named entity.
"""

from typing import Dict, Iterable

from docforge.model.module import Module


class Project:
    """
    Represents a documentation project, serving as a container for modules.

    Attributes:
        name: Name of the project.
        modules: Dictionary mapping module paths to Module instances.
    """

    def __init__(self, name: str) -> None:
        """
        Initialize a new Project.

        Args:
            name: The name of the project.
        """
        self.name = name
        self.modules: Dict[str, Module] = {}

    def add_module(self, module: Module) -> None:
        """
        Add a module to the project.

        Args:
            module: The module to add.
        """
        self.modules[module.path] = module

    def get_module(self, path: str) -> Module:
        """
        Retrieve a module by its dotted path.

        Args:
            path: The dotted path of the module (e.g., 'pkg.mod').

        Returns:
            The requested Module.
        """
        return self.modules[path]

    def get_all_modules(self) -> Iterable[Module]:
        """
        Get all modules in the project.

        Returns:
            An iterable of Module objects.
        """
        return self.modules.values()

    def get_module_list(self) -> list[str]:
        """
        Get the list of all module dotted paths.

        Returns:
            A list of module paths.
        """
        return list(self.modules.keys())