haywire-core 0.0.2__py3-none-any.whl

haywire/core/adapter/base.py

@@ -0,0 +1,307 @@
+"""
+Base adapter classes for type conversion
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, List, Optional, Type, TypeVar
+from dataclasses import dataclass
+
+from haywire.core.library.identity import LibraryIdentity
+from haywire.core.registry.identity import BaseIdentity
+from haywire.core.library.utils import ADAPTER, derive_library_identity, reg_key
+
+if TYPE_CHECKING:
+    from haywire.core.types.interface import IType
+
+# ============================================================================
+#    Decorator
+# ============================================================================
+
+T = TypeVar("T")
+
+
+def adapter(**kwargs: Any) -> Callable[[Type[T]], Type[T]]:
+    """
+    Decorator to register a class as a type adapter.
+
+    Always invoked with parentheses — `@adapter(...)`. The bare `@adapter`
+    form (no parens) is not supported; `converts_from` and `converts_to`
+    are required.
+
+    Accepts any AdapterIdentity field as a keyword argument.
+
+    Args:
+        label (str, optional): Human-readable display name.
+            Defaults to class name if not provided.
+        description (str, optional): Human-readable description.
+            Defaults to empty string.
+        converts_from (type[IType], required): Source IType class.
+        converts_to (type[IType], required): Target IType class.
+        priority (int, optional): Priority (higher = preferred).
+            Defaults to 0.
+        deprecation_warning (str, optional): Deprecation warning message.
+            Defaults to empty string.
+        registry_id (str, optional): Unique identifier for the adapter.
+            Defaults to class name if not provided.
+
+    Any other keyword arguments will be passed through to AdapterIdentity.
+    See the AdapterIdentity dataclass for complete list of fields.
+
+    Usage:
+        # Common customization
+        @adapter(
+            description="Temperature to float conversion",
+            converts_from=Temperature,
+            converts_to=FLOAT,
+        )
+        class MyAdapter(BaseAdapter): ...
+
+        # Full customization with IType classes
+        @adapter(
+            description="Convert Temperature (Celsius) to FLOAT",
+            converts_from=Temperature,
+            converts_to=FLOAT,
+            priority=5
+        )
+        class TempToFloatAdapter(BaseAdapter): ...
+
+        # Multi-hop chain example
+        @adapter(
+            converts_from=Temperature,
+            converts_to=Kelvin,
+            priority=10,
+            description="Celsius to Kelvin"
+        )
+        class TempToKelvinAdapter(BaseAdapter): ...
+    """
+
+    def decorator(inner_cls: Type[T]) -> Type[T]:
+        if not issubclass(inner_cls, BaseAdapter):
+            raise TypeError(f"@adapter can only be applied to BaseAdapter subclasses, got {inner_cls}")
+
+        # Set defaults from class name if not provided
+        kwargs.setdefault("registry_id", inner_cls.__name__)
+        kwargs.setdefault("label", inner_cls.__name__)
+
+        # Get library identity (survives hot-reload)
+        library_identity = derive_library_identity(inner_cls)
+
+        # Auto-derive registry_key
+        kwargs["registry_key"] = reg_key(library_identity.id, ADAPTER, kwargs["registry_id"])
+
+        # Set source info from the class itself
+        kwargs["class_name"] = inner_cls.__name__
+        kwargs["module"] = inner_cls.__module__
+
+        # Create and attach identity and library
+        inner_cls.class_identity = AdapterIdentity(**kwargs)
+        inner_cls.class_library = library_identity
+        return inner_cls
+
+    return decorator
+
+
+@dataclass(kw_only=True)
+class AdapterIdentity(BaseIdentity):
+    """
+    Core identifying attributes of an adapter.
+
+    IType-based: converts_from and converts_to are IType classes.
+    """
+
+    converts_from: type["IType"]  # Source IType (FLOAT, Temperature, etc.)
+    converts_to: type["IType"]  # Target IType (INT, MeshData, etc.)
+    priority: int = 0  # Priority (higher = preferred)
+
+
+# ============================================================================
+#    Adapter Interface
+# ============================================================================
+
+
+class IAdapter(ABC):
+    """
+    Interface for all adapters.
+
+    All adapters must implement:
+    - convert(): Transform a value
+    - execute(): Execute this adapter, then chain to next
+    - get_registry_keys(): Get all registry keys in chain
+    """
+
+    # IDENTITY ATTRIBUTES (set by @type decorator)
+    class_identity: ClassVar[AdapterIdentity]
+    class_library: ClassVar[LibraryIdentity]
+
+    @abstractmethod
+    def convert(self, value: Any) -> Any:
+        """
+        Method to convert value.
+        This method ONLY performs conversion.
+        Use execute() to run the full adapter chain.
+        Args:
+            value: Input value to convert
+        Returns:
+            Converted value by this adapter only
+        """
+        pass
+
+    @abstractmethod
+    def execute(self, value: Any) -> Any:
+        """
+        Main method to execute adapter-chain
+        Args:
+            value: Input value to convert
+        Returns:
+            Converted value after executing entire chain
+        """
+        pass
+
+    @abstractmethod
+    def _get_registry_keys(self) -> List[str]:
+        """Get all registry keys in chain"""
+        pass
+
+    @abstractmethod
+    def get_test_value(self) -> Any:
+        """
+        method returns a sample value of the type this adapter
+        is converting from for testing this adapter
+
+        Returns: sample value of the expected input type
+        """
+        return True
+
+    def get_test_repetitions(self) -> int:
+        """method returns the number of repetitions the test needs to run"""
+        return 1
+
+    @abstractmethod
+    def test(self, value: Any) -> Any:
+        """
+        Tests this adapter with sample data
+
+        Args:
+            value: Sample input value of the type this adapter expects
+        """
+        return True
+
+
+# ============================================================================
+#    Base Adapter Class
+# ============================================================================
+
+
+class ReturnAdapter(IAdapter):
+    """
+    Terminal adapter that returns values unchanged.
+
+    Used as the default terminal adapter in chains.
+    Does not have a registry key (not registered).
+    """
+
+    def convert(self, value: Any) -> Any:
+        """Pass through unchanged"""
+        return value
+
+    def execute(self, value: Any) -> Any:
+        """Terminal - just return value"""
+        return value
+
+    def get_test_value(self) -> Any:
+        """Terminal - always succeeds"""
+        return True
+
+    def test(self, value: int) -> Any:
+        return self.execute(value)
+
+    def _get_registry_keys(self) -> List[str]:
+        """Terminal - no registry keys"""
+        return []
+
+
+class BaseAdapter(IAdapter):
+    """
+    Base class for type adapters.
+
+    Key design:
+    - Type-level operations use IType classes (for registration, matching)
+    - Value-level operations use unwrapped primitives/instances (for conversion)
+    - Chaining via _chain attribute for recursive execution
+
+    This creates clean separation between type system and runtime values.
+
+    Example:
+        # Register with type classes
+        registry.register_adapter(
+            source=Temperature,  # IType class
+            target=FLOAT,        # IType class
+            adapter=TemperatureToFloatAdapter
+        )
+
+        # Convert with unwrapped values
+        adapter = TemperatureToFloatAdapter()
+        result = adapter.convert(25.0)  # float -> float (not FLOAT -> FLOAT)
+    """
+
+    def __init__(self, child: Optional[IAdapter] = None):
+        """Initialize adapter with child in chain"""
+        self._chain: IAdapter = child if child is not None else ReturnAdapter()
+
+    @abstractmethod
+    def convert(self, value: Any) -> Any:
+        """
+        Value-level conversion: Convert UNWRAPPED value.
+        DO NOT USE THIS METHOD FOR CONVERSION. USE execute() INSTEAD.
+
+        This is where actual data transformation happens.
+        Operates on unwrapped primitives or instances, not IType wrappers.
+
+        Args:
+            value: Unwrapped value from source field
+                   - For primitives: 25.0 (not FLOAT(25.0))
+                   - For complex: MeshData(...) instance
+
+        Returns:
+            Unwrapped value for target field
+            - For primitives: 77.0 (not FLOAT(77.0))
+            - For complex: PointCloud(...) instance
+        """
+        pass
+
+    def execute(self, value: Any) -> Any:
+        """
+        Execute this adapter, then delegate to chain.
+
+        Args:
+            value: Input value (unwrapped)
+
+        Returns:
+            Transformed value after executing entire chain
+        """
+        converted = self.convert(value)
+        return self._chain.execute(converted)
+
+    def test(self, value: int) -> Any:
+        return self.execute(value)
+
+    def _get_registry_keys(self) -> List[str]:
+        """
+        Get all registry keys for this adapter and any nested adapters.
+
+        Base implementation returns this adapter's key plus chained keys.
+        Compound adapters (ArrayArrayAdapter, StructuralAdapter) should
+        override to include nested adapter keys.
+
+        Returns:
+            List of registry keys for hot-reload dependency tracking
+        """
+        keys = [self.class_identity.registry_key]
+        keys.extend(self._chain._get_registry_keys())
+        return keys
+
+
+class ConversionError(Exception):
+    """Raised when a type conversion fails"""
+
+    pass