amsdal_utils 0.5.7__py3-none-any.whl → 0.6.0__py3-none-any.whl

amsdal_utils/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2023-present
 #
 # SPDX-License-Identifier: AMSDAL End User License Agreement
-__version__ = '0.5.7'
+__version__ = '0.6.0'

amsdal_utils/events/__init__.py

@@ -0,0 +1,21 @@
+from amsdal_utils.events.bus import EventBus
+from amsdal_utils.events.config import ErrorStrategy
+from amsdal_utils.events.context import ContextHistoryEntry
+from amsdal_utils.events.context import EventContext
+from amsdal_utils.events.decorators import listen_to
+from amsdal_utils.events.event import Event
+from amsdal_utils.events.listener import AsyncNextFn
+from amsdal_utils.events.listener import EventListener
+from amsdal_utils.events.listener import NextFn
+
+__all__ = [
+    'AsyncNextFn',
+    'ContextHistoryEntry',
+    'ErrorStrategy',
+    'Event',
+    'EventBus',
+    'EventContext',
+    'EventListener',
+    'NextFn',
+    'listen_to',
+]

amsdal_utils/events/bus.py

@@ -0,0 +1,417 @@
+import importlib
+import logging
+from collections.abc import Awaitable
+from collections.abc import Callable
+from typing import Any
+from typing import ClassVar
+from typing import TypeVar
+
+from amsdal_utils.events.config import ErrorStrategy
+from amsdal_utils.events.config import _ListenerRegistration
+from amsdal_utils.events.context import EventContext
+from amsdal_utils.events.event import Event
+from amsdal_utils.events.listener import EventListener
+
+logger = logging.getLogger(__name__)
+
+TContext = TypeVar('TContext', bound=EventContext)
+
+
+def _resolve_listener_id(listener: type[EventListener[Any]] | str) -> str:
+    """
+    Resolve listener to its listener_id string.
+
+    Args:
+        listener: Either a listener class or a fully-qualified module path string
+
+    Returns:
+        The listener_id string
+
+    Raises:
+        ValueError: If string path cannot be imported or is malformed
+        TypeError: If the resolved object is not a subclass of EventListener
+
+    Example:
+        _resolve_listener_id(MyListener)  # Returns "module.MyListener" (from listener.listener_id)
+        _resolve_listener_id("module.path.MyListener")  # Validates import and returns listener_id
+    """
+    if isinstance(listener, str):
+        # String path - strict validation by import
+        parts = listener.rsplit('.', 1)
+        expected_parts_count = 2
+        if len(parts) != expected_parts_count:
+            msg = f'Invalid listener path "{listener}". Expected format: "module.ClassName"'
+            raise ValueError(msg)
+
+        module_path, class_name = parts
+
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as e:
+            msg = f'Cannot import module "{module_path}" from listener path "{listener}". Check for typos: {e}'
+            raise ValueError(msg) from e
+
+        try:
+            listener_cls = getattr(module, class_name)
+        except AttributeError as e:
+            msg = f'Class "{class_name}" not found in module "{module_path}". Check for typos.'
+            raise ValueError(msg) from e
+
+        # Verify it's an EventListener subclass
+        if not isinstance(listener_cls, type) or not issubclass(listener_cls, EventListener):
+            msg = f'"{listener}" is not a subclass of EventListener'
+            raise TypeError(msg)
+
+        # Successfully validated - return its listener_id
+        return listener_cls.listener_id
+    else:
+        # Class type - return its listener_id
+        if not isinstance(listener, type) or not issubclass(listener, EventListener):
+            msg = f'Expected EventListener subclass or string path, got {type(listener)}'
+            raise TypeError(msg)
+        return listener.listener_id
+
+
+class EventBus:
+    """
+    Central event bus for middleware-style event handling.
+
+    Features:
+    - Type-safe event/context binding
+    - Middleware chain pattern
+    - Dependency-based ordering
+    - Context history tracking
+    - Caching of sorted listeners for performance
+
+    Example:
+        # Register listener
+        EventBus.subscribe(MyEvent, MyListener, priority=100)
+
+        # Emit event
+        context = MyContext(value=10)
+        result = EventBus.emit(MyEvent, context)
+
+        # Or async
+        result = await EventBus.aemit(MyEvent, context)
+    """
+
+    _listeners: ClassVar[dict[type[Event[Any]], list[_ListenerRegistration]]] = {}
+    _sorted_cache: ClassVar[dict[type[Event[Any]], list[_ListenerRegistration]]] = {}
+
+    @classmethod
+    def subscribe(
+        cls,
+        event: type[Event[TContext]],
+        listener: type[EventListener[TContext]],
+        after: list[type[EventListener[Any]] | str] | None = None,
+        before: list[type[EventListener[Any]] | str] | None = None,
+        priority: int = 500,
+        error_strategy: ErrorStrategy | None = None,
+    ) -> None:
+        """
+        Subscribe listener to event.
+
+        Args:
+            event: Event class to listen to
+            listener: Listener class (will be instantiated per execution)
+            after: List of listeners or listener_id strings this should run after.
+                   Strings must be fully-qualified paths (e.g., "module.ClassName")
+            before: List of listeners or listener_id strings this should run before.
+                    Strings must be fully-qualified paths (e.g., "module.ClassName")
+            priority: Numeric priority (0-999, lower = earlier)
+            error_strategy: How to handle errors (None = use event's default)
+
+        Raises:
+            ValueError: If string path cannot be imported (typo in listener reference)
+            TypeError: If listener reference is not an EventListener subclass
+
+        Example:
+            # Using class references (type-safe)
+            EventBus.subscribe(MyEvent, ListenerA, after=[ListenerB])
+
+            # Using string paths (for cross-module references)
+            EventBus.subscribe(MyEvent, ListenerA, after=["other.module.ListenerB"])
+
+            # Mixed approach
+            EventBus.subscribe(MyEvent, ListenerC, after=[ListenerA, "other.module.ListenerB"])
+        """
+        # Use event's default error strategy if not specified
+        if error_strategy is None:
+            error_strategy = event.default_error_strategy
+
+        # Resolve listener references to IDs
+        after_ids = [_resolve_listener_id(dep) for dep in (after or [])]
+        before_ids = [_resolve_listener_id(dep) for dep in (before or [])]
+
+        # Check for duplicate registration
+        existing_listeners = cls._listeners.get(event, [])
+        if any(reg.listener_id == listener.listener_id for reg in existing_listeners):
+            return  # Already registered, skip
+
+        registration = _ListenerRegistration(
+            listener=listener,
+            after=after_ids,
+            before=before_ids,
+            priority=priority,
+            error_strategy=error_strategy,
+        )
+
+        cls._listeners.setdefault(event, []).append(registration)
+        # Invalidate cache
+        cls._sorted_cache.pop(event, None)
+
+    @classmethod
+    def unsubscribe(cls, event: type[Event[Any]], listener_id: str) -> bool:
+        """
+        Unsubscribe listener from event.
+
+        Args:
+            event: Event type
+            listener_id: Listener ID to remove
+
+        Returns:
+            True if listener was found and removed
+        """
+        if event not in cls._listeners:
+            return False
+
+        initial_count = len(cls._listeners[event])
+        cls._listeners[event] = [reg for reg in cls._listeners[event] if reg.listener_id != listener_id]
+
+        if len(cls._listeners[event]) < initial_count:
+            cls._sorted_cache.pop(event, None)
+            return True
+        return False
+
+    @classmethod
+    def emit(
+        cls,
+        event: type[Event[TContext]],
+        context: TContext,
+    ) -> TContext:
+        """
+        Emit event synchronously and execute middleware chain.
+
+        Args:
+            event: Event type to emit
+            context: Initial context
+
+        Returns:
+            Final context after all listeners
+
+        Raises:
+            Any exception raised by listeners (depends on error_strategy)
+        """
+        listeners = cls._get_sorted_listeners(event)
+
+        if not listeners:
+            return context
+
+        chain = cls._build_sync_chain(listeners)
+        return chain(context)
+
+    @classmethod
+    async def aemit(
+        cls,
+        event: type[Event[TContext]],
+        context: TContext,
+    ) -> TContext:
+        """
+        Emit event asynchronously and execute middleware chain.
+
+        Args:
+            event: Event type to emit
+            context: Initial context
+
+        Returns:
+            Final context after all listeners
+
+        Raises:
+            Any exception raised by listeners (depends on error_strategy)
+        """
+        listeners = cls._get_sorted_listeners(event)
+
+        if not listeners:
+            return context
+
+        chain = cls._build_async_chain(listeners)
+        return await chain(context)
+
+    @classmethod
+    def _get_sorted_listeners(cls, event: type[Event[Any]]) -> list[_ListenerRegistration]:
+        """
+        Get listeners sorted by dependencies and priority.
+        Uses cache to avoid re-sorting on every emit.
+        """
+        if event in cls._sorted_cache:
+            return cls._sorted_cache[event]
+
+        listeners = cls._listeners.get(event, [])
+        sorted_listeners = cls._sort_listeners(listeners)
+
+        cls._sorted_cache[event] = sorted_listeners
+        return sorted_listeners
+
+    @classmethod
+    def _sort_listeners(cls, registrations: list[_ListenerRegistration]) -> list[_ListenerRegistration]:
+        """
+        Sort listeners by priority and dependencies (after/before).
+
+        Uses topological sort with cycle detection.
+        Priority is used as tiebreaker when no dependencies exist.
+
+        Raises:
+            ValueError: If circular dependencies detected
+        """
+        if not registrations:
+            return []
+
+        # Build adjacency graph and in-degree map
+        graph: dict[str, list[str]] = {}  # listener_id -> [dependencies]
+        in_degree: dict[str, int] = {}
+        listener_map: dict[str, _ListenerRegistration] = {}
+
+        # Initialize
+        for reg in registrations:
+            listener_id = reg.listener_id
+            listener_map[listener_id] = reg
+            graph[listener_id] = []
+            in_degree[listener_id] = 0
+
+        # Build dependency graph
+        for reg in registrations:
+            listener_id = reg.listener_id
+
+            # "after" means this listener depends on others (they must run first)
+            for dependency in reg.after:
+                if dependency in listener_map:
+                    graph[dependency].append(listener_id)
+                    in_degree[listener_id] += 1
+
+            # "before" means others depend on this listener (this must run first)
+            for dependent in reg.before:
+                if dependent in listener_map:
+                    graph[listener_id].append(dependent)
+                    in_degree[dependent] += 1
+
+        # Kahn's algorithm for topological sort
+        queue: list[str] = []
+        for listener_id, degree in in_degree.items():
+            if degree == 0:
+                queue.append(listener_id)
+
+        # Sort queue by priority for deterministic ordering
+        queue.sort(key=lambda lid: listener_map[lid].priority)
+
+        result: list[_ListenerRegistration] = []
+
+        while queue:
+            # Pop listener with lowest priority
+            queue.sort(key=lambda lid: listener_map[lid].priority)
+            current = queue.pop(0)
+            result.append(listener_map[current])
+
+            # Reduce in-degree for neighbors
+            for neighbor in graph[current]:
+                in_degree[neighbor] -= 1
+                if in_degree[neighbor] == 0:
+                    queue.append(neighbor)
+
+        # Check for cycles
+        if len(result) != len(registrations):
+            # Find which listeners are in the cycle
+            remaining = [lid for lid, deg in in_degree.items() if deg > 0]
+            msg = f'Circular dependency detected among listeners: {remaining}'
+            raise ValueError(msg)
+
+        return result
+
+    @classmethod
+    def _build_sync_chain(
+        cls,
+        registrations: list[_ListenerRegistration],
+    ) -> Callable[[TContext], TContext]:
+        """Build synchronous middleware chain"""
+
+        def create_next(index: int) -> Callable[[TContext], TContext]:
+            if index >= len(registrations):
+                # End of chain - return context as-is
+                return lambda ctx: ctx
+
+            registration = registrations[index]
+            next_fn = create_next(index + 1)
+
+            def middleware(ctx: TContext) -> TContext:
+                listener_instance = registration.listener()
+
+                try:
+                    return listener_instance.handle(ctx, next_fn)
+
+                except Exception as e:
+                    if registration.error_strategy == ErrorStrategy.PROPAGATE:
+                        raise
+                    if registration.error_strategy == ErrorStrategy.LOG_AND_CONTINUE:
+                        logger.exception(f'Error in listener {registration.listener_id}: {e}')
+                        return next_fn(ctx)
+                    # SILENT
+                    return next_fn(ctx)
+
+            return middleware
+
+        return create_next(0)
+
+    @classmethod
+    def _build_async_chain(
+        cls,
+        registrations: list[_ListenerRegistration],
+    ) -> Callable[[TContext], Awaitable[TContext]]:
+        """Build asynchronous middleware chain"""
+
+        def create_next(index: int) -> Callable[[TContext], Awaitable[TContext]]:
+            if index >= len(registrations):
+                # End of chain - return context as-is
+                async def final(ctx: TContext) -> TContext:
+                    return ctx
+
+                return final
+
+            registration = registrations[index]
+            next_fn = create_next(index + 1)
+
+            async def middleware(ctx: TContext) -> TContext:
+                listener_instance = registration.listener()
+
+                try:
+                    return await listener_instance.ahandle(ctx, next_fn)
+                except Exception as e:
+                    if registration.error_strategy == ErrorStrategy.PROPAGATE:
+                        raise
+                    if registration.error_strategy == ErrorStrategy.LOG_AND_CONTINUE:
+                        logger.exception(f'Error in listener {registration.listener_id}: {e}')
+                        return await next_fn(ctx)
+                    # SILENT
+                    return await next_fn(ctx)
+
+            return middleware
+
+        return create_next(0)
+
+    @classmethod
+    def reset(cls) -> None:
+        """Clear all listeners and cache (useful for testing)"""
+        cls._listeners.clear()
+        cls._sorted_cache.clear()
+
+    @classmethod
+    def get_listeners(cls, event: type[Event[Any]]) -> list[str]:
+        """
+        Get list of listener IDs for event (for introspection).
+
+        Args:
+            event: Event type
+
+        Returns:
+            List of listener IDs in execution order
+        """
+        configs = cls._get_sorted_listeners(event)
+        return [cfg.listener_id for cfg in configs]

amsdal_utils/events/config.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+from dataclasses import field
+from enum import Enum
+from typing import Any
+
+
+class ErrorStrategy(Enum):
+    """Strategy for handling errors in listeners"""
+
+    PROPAGATE = 'propagate'  # raise exception, stop chain
+    LOG_AND_CONTINUE = 'log_and_continue'  # log error but continue chain
+    SILENT = 'silent'  # ignore errors completely
+
+
+@dataclass
+class _ListenerRegistration:
+    """Internal: stores listener with metadata"""
+
+    listener: type[Any]  # type[EventListener] but can't import here
+    after: list[str] = field(default_factory=list)
+    before: list[str] = field(default_factory=list)
+    priority: int = 500
+    error_strategy: ErrorStrategy = ErrorStrategy.PROPAGATE
+
+    @property
+    def listener_id(self) -> str:
+        return self.listener.listener_id  # type: ignore[attr-defined,unused-ignore]

amsdal_utils/events/context.py

@@ -0,0 +1,150 @@
+from abc import ABC
+from time import time
+from typing import Any
+from typing import TypeVar
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+
+def _safe_deep_copy(value: Any) -> Any:
+    """
+    Safely deep copy a value.
+
+    - Primitives (None, bool, int, float, str, bytes): returned as-is (immutable)
+    - Pydantic BaseModel: uses model_copy(deep=True)
+    - dict: recursively copies each key-value pair
+    - list: recursively copies each item
+    - tuple: recursively copies each item and returns tuple
+    - set/frozenset: recursively copies each item
+    - Other objects (Request, Response, etc.): returned as-is (reference)
+    """
+    if value is None or isinstance(value, bool | int | float | str | bytes):
+        return value
+
+    if isinstance(value, BaseModel):
+        # For Pydantic models, use safe copy on each field
+        data = {}
+        for field_name in value.__class__.model_fields:
+            field_value = getattr(value, field_name)
+            data[field_name] = _safe_deep_copy(field_value)
+        return value.__class__.model_construct(**data)
+
+    if isinstance(value, dict):
+        return {_safe_deep_copy(k): _safe_deep_copy(v) for k, v in value.items()}
+
+    if isinstance(value, list):
+        return [_safe_deep_copy(item) for item in value]
+
+    if isinstance(value, tuple):
+        return tuple(_safe_deep_copy(item) for item in value)
+
+    if isinstance(value, set):
+        return {_safe_deep_copy(item) for item in value}
+
+    if isinstance(value, frozenset):
+        return frozenset(_safe_deep_copy(item) for item in value)
+
+    # For anything else (Request, Response, file handles, etc.), keep reference
+    return value
+
+
+class ContextHistoryEntry(BaseModel):
+    """Single entry in context history"""
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    context_snapshot: Any  # snapshot of context at this point
+    listener_id: str  # which listener created this version
+    timestamp: float  # when created
+
+
+TContext = TypeVar('TContext', bound='EventContext')
+
+
+class EventContext(BaseModel, ABC):
+    """
+    Base class for all event contexts.
+
+    Each listener creates new immutable version, history is preserved.
+    Uses Pydantic with frozen=True to enforce immutability.
+
+    Example:
+        class MyContext(EventContext):
+            value: int
+            processed: bool = False
+
+        # In listener - ✅ correct way
+        new_context = context.create_next(
+            listener_id=self.listener_id,
+            value=context.value * 2,
+        )
+
+        # ❌ This will raise ValidationError
+        context.value = 42  # pydantic prevents mutation
+    """
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    history_: list[ContextHistoryEntry] = Field(default_factory=list, repr=False)
+    current_listener_: str | None = Field(default=None, repr=False)
+
+    def create_next(self: TContext, listener_id: str, **changes: Any) -> TContext:
+        """
+        Create new context version with changes.
+        Preserves history.
+
+        Args:
+            listener_id: ID of listener creating new version
+            **changes: Fields to update in new context
+
+        Returns:
+            New context instance with updated fields
+
+        Example:
+            new_ctx = context.create_next(
+                listener_id="my.Listener",
+                value=42,
+                processed=True,
+            )
+        """
+        # Add snapshot to history
+        # Using _safe_deep_copy to avoid issues with non-copyable objects like Request
+        new_history = [
+            *self.history_,
+            ContextHistoryEntry(
+                context_snapshot=_safe_deep_copy(self),
+                listener_id=listener_id,
+                timestamp=time(),
+            ),
+        ]
+
+        # Use model_copy to avoid serialization issues with Reference fields
+        return self.model_copy(
+            update={
+                **changes,
+                'history_': new_history,
+                'current_listener_': listener_id,
+            }
+        )
+
+    @property
+    def history(self) -> list[ContextHistoryEntry]:
+        """Get full history of context mutations"""
+        return self.history_
+
+    def get_by_listener(self, listener_id: str) -> 'EventContext | None':
+        """
+        Get context version created by specific listener.
+
+        Args:
+            listener_id: Listener ID to search for
+
+        Returns:
+            Context snapshot or None if not found
+        """
+        for entry in self.history_:
+            if entry.listener_id == listener_id:
+                return entry.context_snapshot
+        return None

amsdal_utils/events/decorators.py

@@ -0,0 +1,71 @@
+from collections.abc import Callable
+from typing import Any
+from typing import TypeVar
+
+from amsdal_utils.events.bus import EventBus
+from amsdal_utils.events.config import ErrorStrategy
+from amsdal_utils.events.context import EventContext
+from amsdal_utils.events.event import Event
+from amsdal_utils.events.listener import EventListener
+
+TContext = TypeVar('TContext', bound=EventContext)
+
+
+def listen_to(
+    event: type[Event[TContext]],
+    after: list[type[EventListener[Any]] | str] | None = None,
+    before: list[type[EventListener[Any]] | str] | None = None,
+    priority: int = 500,
+    error_strategy: ErrorStrategy | None = None,
+) -> Callable[[type[EventListener[TContext]]], type[EventListener[TContext]]]:
+    """
+    Decorator to auto-register listener to event.
+
+    Args:
+        event: Event class to listen to
+        after: List of listeners or listener_id strings this should run after.
+               Strings must be fully-qualified paths (e.g., "module.ClassName")
+        before: List of listeners or listener_id strings this should run before.
+                Strings must be fully-qualified paths (e.g., "module.ClassName")
+        priority: Numeric priority (0-999, lower = earlier)
+        error_strategy: How to handle errors (None = use event's default)
+
+    Returns:
+        Decorated listener class (unchanged)
+
+    Raises:
+        ValueError: If string path cannot be imported (typo in listener reference)
+        TypeError: If listener reference is not an EventListener subclass
+
+    Example:
+        # Using class references (type-safe)
+        @listen_to(MyEvent, after=[OtherListener], priority=100)
+        class MyListener(EventListener[MyContext]):
+            def handle(self, context, next_fn):
+                return next_fn(context)
+
+        # Using string paths (for cross-module references)
+        @listen_to(MyEvent, after=["other.module.OtherListener"], priority=100)
+        class MyListener(EventListener[MyContext]):
+            def handle(self, context, next_fn):
+                return next_fn(context)
+
+        # Mixed approach
+        @listen_to(MyEvent, after=[LocalListener, "other.module.RemoteListener"])
+        class MyListener(EventListener[MyContext]):
+            def handle(self, context, next_fn):
+                return next_fn(context)
+    """
+
+    def decorator(listener_cls: type[EventListener[TContext]]) -> type[EventListener[TContext]]:
+        EventBus.subscribe(
+            event=event,
+            listener=listener_cls,
+            after=after,
+            before=before,
+            priority=priority,
+            error_strategy=error_strategy,
+        )
+        return listener_cls
+
+    return decorator

amsdal_utils/events/event.py

@@ -0,0 +1,43 @@
+from typing import Generic
+from typing import TypeVar
+from typing import get_args
+
+from amsdal_utils.events.config import ErrorStrategy
+from amsdal_utils.events.context import EventContext
+
+TContext = TypeVar('TContext', bound=EventContext)
+
+
+class Event(Generic[TContext]):
+    """
+    Base event class with typed context.
+
+    Each event type automatically extracts its context type from the generic parameter.
+    Optionally define default error strategy for all listeners of this event.
+
+    Usage:
+        class MyEvent(Event[MyContext]):
+            pass
+
+        # With custom error strategy
+        class NonCriticalEvent(Event[MyContext]):
+            default_error_strategy = ErrorStrategy.LOG_AND_CONTINUE
+
+    Attributes:
+        context_type: Type of context this event uses (auto-detected)
+        default_error_strategy: Default error handling strategy for listeners
+    """
+
+    context_type: type[TContext]
+    default_error_strategy: ErrorStrategy = ErrorStrategy.PROPAGATE
+
+    def __init_subclass__(cls, **kwargs) -> None:  # type: ignore[no-untyped-def]
+        super().__init_subclass__(**kwargs)
+        # Auto-detect context type from generic parameter
+        if hasattr(cls, '__orig_bases__'):
+            for base in cls.__orig_bases__:
+                if hasattr(base, '__args__'):
+                    args = get_args(base)
+                    if args:
+                        cls.context_type = args[0]
+                        break

amsdal_utils/events/listener.py

@@ -0,0 +1,87 @@
+from abc import ABC
+from abc import abstractmethod
+from collections.abc import Awaitable
+from collections.abc import Callable
+from typing import Generic
+from typing import TypeVar
+
+from amsdal_utils.events.context import EventContext
+
+TContext = TypeVar('TContext', bound=EventContext)
+
+# Type aliases for next function
+NextFn = Callable[[TContext], TContext]
+AsyncNextFn = Callable[[TContext], Awaitable[TContext]]
+
+
+class EventListener(ABC, Generic[TContext]):
+    """
+    Base event listener acting as middleware.
+
+    Each listener receives context and next() function.
+    Must call next(context) to continue chain or raise exception to stop.
+
+    The listener_id is auto-generated from module and class name.
+
+    Example:
+        class MyListener(EventListener[MyContext]):
+            def handle(self, context: MyContext, next: NextFn) -> MyContext:
+                # Your logic
+                if not self.is_valid(context):
+                    raise ValueError("Invalid context")
+
+                # Modify context
+                new_ctx = context.create_next(
+                    listener_id=self.listener_id,
+                    some_field="new_value",
+                )
+
+                # Continue chain
+                return next(new_ctx)
+    """
+
+    listener_id: str
+
+    def __init_subclass__(cls, **kwargs) -> None:  # type: ignore[no-untyped-def]
+        super().__init_subclass__(**kwargs)
+        # Auto-generate listener_id from module + class name
+        if not hasattr(cls, 'listener_id') or cls.listener_id == EventListener.listener_id:
+            cls.listener_id = f'{cls.__module__}.{cls.__name__}'
+
+    @abstractmethod
+    def handle(self, context: TContext, next_fn: NextFn[TContext]) -> TContext:
+        """
+        Sync handler (default).
+
+        Args:
+            context: Event context (immutable - create new with context.create_next())
+            next_fn: Function to call next listener
+
+        Returns:
+            Context (original or modified)
+
+        Raises:
+            Any exception to stop chain execution
+            NotImplementedError: If only async is supported
+        """
+        msg = f'{self.__class__.__name__} does not implement sync handling'
+        raise NotImplementedError(msg)
+
+    @abstractmethod
+    async def ahandle(self, context: TContext, next_fn: AsyncNextFn[TContext]) -> TContext:
+        """
+        Async handler.
+
+        Args:
+            context: Event context (immutable - create new with context.create_next())
+            next_fn: Async function to call next listener
+
+        Returns:
+            Context (original or modified)
+
+        Raises:
+            Any exception to stop chain execution
+            NotImplementedError: If only sync is supported
+        """
+        msg = f'{self.__class__.__name__} does not implement async handling'
+        raise NotImplementedError(msg)

amsdal_utils/models/data_models/address.py

@@ -26,7 +26,7 @@ class JSONExtendedEncoder(json.JSONEncoder):
     """Custom JSON encoder to handle additional types."""
 
     def default(self, obj: Any) -> Any:
-        if isinstance(obj, (Decimal, datetime, date, time, bytes)):
+        if isinstance(obj, Decimal | datetime | date | time | bytes):
             return {
                 '__type__': type(obj).__name__,
                 'value': base64.b64encode(obj).decode('utf-8') if isinstance(obj, bytes) else str(obj),

{amsdal_utils-0.5.7.dist-info → amsdal_utils-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amsdal_utils
-Version: 0.5.7
+Version: 0.6.0
 Summary: Utils for AMSDAL data framework
 Project-URL: Documentation, https://pypi.org/project/amsdal_utils/#readme
 Project-URL: Issues, https://pypi.org/project/amsdal_utils/#issues
@@ -118,9 +118,10 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: >=3.11
+Requires-Python: <3.14,>=3.11
 Requires-Dist: pydantic~=2.12
 Requires-Dist: pyyaml~=6.0
 Description-Content-Type: text/markdown

{amsdal_utils-0.5.7.dist-info → amsdal_utils-0.6.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 amsdal_utils/Third-Party Materials - AMSDAL Dependencies - License Notices.md,sha256=blZRsT9Qg4u4LzZuxlWQOzlWGpLAg7DugWS6nz7s_yw,62595
-amsdal_utils/__about__.py,sha256=6iW8h6OIk_sNDiVyp7NxCzL_PEkI5J0OHZQ6VEA84jQ,124
+amsdal_utils/__about__.py,sha256=L9I3u2z3UsLTmwP99KJ8u9WMvIGgp6dH1-e7eZsHvlE,124
 amsdal_utils/__init__.py,sha256=EQCJ5OevmkkIpIULumPNIbWk3UI7afDfRzIsZN5mfwg,73
 amsdal_utils/errors.py,sha256=P90oGdKczHZzHukWnzJfbsSxMC-Sc8dUXvHzP7b1IIA,129
 amsdal_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -16,6 +16,13 @@ amsdal_utils/config/data_models/connection_config.py,sha256=bUb0dvWVVOXsLV-A37Wv
 amsdal_utils/config/data_models/integration_config.py,sha256=UhFUhEchDY5PPrGiFfmisLkslVtKfiac3BMiU77FoT4,387
 amsdal_utils/config/data_models/repository_config.py,sha256=Mrqzki0cYMNJI2mywD4BTNSl438B-Jlmy7LqyNZ6I_o,383
 amsdal_utils/config/data_models/resources_config.py,sha256=RrCCThE7hj8Tr5Nn_ItsRAAnkMBuest2kNWnRL84exk,844
+amsdal_utils/events/__init__.py,sha256=5NRRBtQAaAeKAehX4uwgP3hT_VT7rG9Clsejcffo9u4,647
+amsdal_utils/events/bus.py,sha256=AfTxWqKhbemYHkWAt9xRPv9hUv43qCC0HFrS667QEis,14406
+amsdal_utils/events/config.py,sha256=INNXKprSmGWz0oGDAm1cxKbR-YT4zKhf67-lMyMiWOE,857
+amsdal_utils/events/context.py,sha256=4_xjK5TubDy6cOD2hXoQQO619ailzhF6tr7q1PU31S0,4710
+amsdal_utils/events/decorators.py,sha256=Py7UnxUkAIZtjzFYEA1nXa412aZfUzPzyajmUPF4ggU,2686
+amsdal_utils/events/event.py,sha256=fNZqNRAeAiqwsoWnJD8CK20P14EZhvR_6OL11O_FmYk,1462
+amsdal_utils/events/listener.py,sha256=bc1_a8kSB1bs0xicQ66e7DEVJPEGi7oTtE0CBlVEFQY,2866
 amsdal_utils/lifecycle/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 amsdal_utils/lifecycle/consumer.py,sha256=IzA4peJwAQ5knaU11TwkHsLX7KIq9EOdPF2kEzu8DJI,739
 amsdal_utils/lifecycle/enum.py,sha256=0bmmU1XmyJaxztxVnYIzwzT9Iyzc-s3jUvmk5JcuaYw,500
@@ -24,7 +31,7 @@ amsdal_utils/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 amsdal_utils/models/base.py,sha256=jcY7ZE6n0lANGjg87sEwlz6val_8ZRHWaCmNZo9Oxnc,1642
 amsdal_utils/models/enums.py,sha256=1iuixjmfHMIMDM3rEQ1YUjOPF3aV_OEoPq61I61KvGI,745
 amsdal_utils/models/data_models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-amsdal_utils/models/data_models/address.py,sha256=zKAGlXjw8oGJrADyhwE8BhYzCEUTSChMSApMYOL7Bjk,6585
+amsdal_utils/models/data_models/address.py,sha256=Sjdny-5XcpSJEv_kQ6lDq7dBIvftIzPRoIkhiFizxLc,6587
 amsdal_utils/models/data_models/core.py,sha256=GdOkd-WU5Grifl3f4tyr1Kpv56NQjec2lud1iKo2hAI,8686
 amsdal_utils/models/data_models/enums.py,sha256=qDJDPU5oxPlSNENFNf3PPgxiFJYbTM8OOE8stMmYYHc,4130
 amsdal_utils/models/data_models/metadata.py,sha256=z0u7kJzzNj8FxFXozVCcFfwyJFdto6_CgwXnW5TicB4,2996
@@ -57,7 +64,7 @@ amsdal_utils/utils/identifier.py,sha256=oP3CHd2i8EBHMVUC8DWLr9pFZBt1IdH7Falaa3M2
 amsdal_utils/utils/lazy_object.py,sha256=eIVHBDNCSHKQopzYjviPCuh0svbRJQOCZ8KzqFLiS-s,2115
 amsdal_utils/utils/singleton.py,sha256=O42jKH0jOdfcPGz-OHqfm7kShEZQwUanu3rMHQJSsb0,722
 amsdal_utils/utils/text.py,sha256=4L5aICJGbmFZwNUhMrACb5thqmcIaWb3aVD24lW24a0,1962
-amsdal_utils-0.5.7.dist-info/METADATA,sha256=fUhjsCqBtctVDepD3eLZYUDRojKP62UM1cVNhIz0jvM,57432
-amsdal_utils-0.5.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-amsdal_utils-0.5.7.dist-info/licenses/LICENSE.txt,sha256=hG-541PFYfNJi9WRZi_hno91UyqNg7YLK8LR3vLblZA,27355
-amsdal_utils-0.5.7.dist-info/RECORD,,
+amsdal_utils-0.6.0.dist-info/METADATA,sha256=iowOWyYBT0qEzIeylBs-ONvvVele-7bJT72RkRU0pH8,57489
+amsdal_utils-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+amsdal_utils-0.6.0.dist-info/licenses/LICENSE.txt,sha256=hG-541PFYfNJi9WRZi_hno91UyqNg7YLK8LR3vLblZA,27355
+amsdal_utils-0.6.0.dist-info/RECORD,,