"""
Documentation model representing individual Python objects.

This module defines the ``DocObject`` class, the fundamental recursive unit of
the doc-forge documentation model. Each ``DocObject`` represents a Python
entity such as a class, function, method, or attribute, and may contain nested
members that form a hierarchical documentation structure.
"""

from typing import Dict, Iterable, Optional


class DocObject:
    """
    Representation of a documented Python object.

    A ``DocObject`` models a single Python entity discovered during
    introspection. Objects may contain nested members, allowing the structure
    of modules, classes, and other containers to be represented recursively.

    Attributes:
        name: Local name of the object.
        kind: Type of object (for example ``class``, ``function``,
            ``method``, or ``attribute``).
        path: Fully qualified dotted path to the object.
        signature: Callable signature if the object represents a callable.
        docstring: Raw docstring text extracted from the source code.
        members: Mapping of member names to child ``DocObject`` instances.
    """

    def __init__(
        self,
        name: str,
        kind: str,
        path: str,
        signature: Optional[str] = None,
        docstring: Optional[str] = None,
    ) -> None:
        """
        Initialize a DocObject instance.

        Args:
            name: Local name of the object.
            kind: Object type identifier (for example ``class`` or ``function``).
            path: Fully qualified dotted path of the object.
            signature: Callable signature if applicable.
            docstring: Documentation string associated with the object.
        """
        self.name = name
        self.kind = kind
        self.path = path
        self.signature = signature
        self.docstring = docstring
        self.members: Dict[str, "DocObject"] = {}

    def add_member(self, obj: "DocObject") -> None:
        """
        Add a child documentation object.

        This is typically used when attaching methods to classes or
        nested objects to their parent containers.

        Args:
            obj: Documentation object to add as a member.
        """
        self.members[obj.name] = obj

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

        Args:
            name: Name of the member to retrieve.

        Returns:
            The corresponding ``DocObject`` instance.

        Raises:
            KeyError: If the member does not exist.
        """
        return self.members[name]

    def get_all_members(self) -> Iterable["DocObject"]:
        """
        Return all child members of the object.

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