"""
# Summary

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 (str):
            Local name of the object.

        kind (str):
            Type of object (for example `class`, `function`, `method`, or `attribute`).

        path (str):
            Fully qualified dotted path to the object.

        signature (Optional[str]):
            Callable signature if the object represents a callable.

        docstring (Optional[str]):
            Raw docstring text extracted from the source code.

        members (Dict[str, DocObject]):
            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 (str):
                Local name of the object.

            kind (str):
                Object type identifier (for example `class` or `function`).

            path (str):
                Fully qualified dotted path of the object.

            signature (Optional[str]):
                Callable signature if applicable.

            docstring (Optional[str]):
                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 (str):
                Name of the member to retrieve.

        Returns:
            DocObject:
                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:
            Iterable[DocObject]:
                An iterable of `DocObject` instances representing nested members.
        """
        return self.members.values()