"""
This module defines the DocObject class, the fundamental recursive unit of the
doc-forge documentation models. A DocObject represents a single Python entity
(class, function, method, or attribute) and its nested members.
"""

from typing import Dict, Iterable, Optional


class DocObject:
    """
    Represents a documented Python object (class, function, method, etc.).

    Attributes:
        name: Local name of the object.
        kind: Type of object (e.g., 'class', 'function', 'attribute').
        path: Full dotted import path to the object.
        signature: Callable signature, if applicable.
        docstring: Raw docstring content extracted from the source.
        members: Dictionary mapping member names to their DocObject representations.
    """

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

        Args:
            name: The local name of the object.
            kind: The kind of object (e.g., 'class', 'function').
            path: The full dotted path to the object.
            signature: The object's signature (for callable objects).
            docstring: The object's docstring, if any.
        """
        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 member to this object (e.g., a method to a class).

        Args:
            obj: The child DocObject to add.
        """
        self.members[obj.name] = obj

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

        Args:
            name: The name of the member.

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

    def get_all_members(self) -> Iterable['DocObject']:
        """
        Get all members of this object.

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