# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
# See LICENSE for details.
"""Generic descriptor for plugin catalog entries.

Defines the base Descriptor class which contains metadata and an instance
for any pluggable component.
"""

from typing import Any


class Descriptor[T]:
    """Generic descriptor for a plugin catalog entry.

    A descriptor contains both metadata (id, name, description, attributes)
    and an instance of the plugin component it describes.

    Type Parameters:
        T: The type of instance this descriptor holds (e.g., Evaluator, Loader).

    Attributes:
        id: Unique identifier for this plugin.
        name: Human-readable name.
        description: Optional description.
        attributes: Additional plugin-specific metadata as key-value pairs.
        instance: The plugin instance (e.g., evaluator, loader).

    Example:
        >>> descriptor = Descriptor(
        ...     id="csv-parser",
        ...     name="CSV Parser",
        ...     instance=my_parser,
        ...     attributes={"file_type": "text", "extensions": [".csv"]},
        ... )
        >>> descriptor.instance.parse(data)
    """

    def __init__(
        self,
        id: str,
        name: str,
        instance: T,
        description: str | None = None,
        attributes: dict[str, Any] | None = None,
    ):
        """Initialize a Descriptor.

        Args:
            id: Unique identifier for the plugin.
            name: Human-readable name.
            instance: The plugin instance.
            description: Optional description.
            attributes: Optional additional plugin-specific attributes.
        """
        self.id = id
        self.name = name
        self.description = description
        self.instance = instance
        self.attributes = attributes if attributes is not None else {}

    def __repr__(self) -> str:
        instance_type = type(self.instance).__name__
        return f"<Descriptor id={self.id!r} name={self.name!r} instance={instance_type}>"
