lionherd-core 1.0.0a3__py3-none-any.whl

lionherd_core/base/progression.py

@@ -0,0 +1,261 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any, overload
+from uuid import UUID
+
+from pydantic import Field, field_validator
+
+from ..protocols import Containable, implements
+from .element import Element
+
+__all__ = ("Progression",)
+
+
+@implements(Containable)
+class Progression(Element):
+    """Ordered sequence of UUIDs with Element identity.
+
+    Attributes:
+        name: Optional progression name
+        order: Ordered UUIDs (allows duplicates)
+
+    Supports list-like operations (append/insert/remove/pop/extend), reordering (move/swap/reverse),
+    and idempotent set-like operations (include/exclude).
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="Optional name for this progression (e.g., 'execution_order')",
+    )
+    order: list[UUID] = Field(
+        default_factory=list,
+        description="Ordered sequence of UUIDs",
+    )
+
+    def __init__(
+        self, order: list[UUID] | list[Element] | None = None, name: str | None = None, **data
+    ):
+        """Initialize Progression.
+
+        Args:
+            order: Initial items (UUIDs or Elements)
+            name: Optional name for this progression
+            **data: Additional Element fields
+        """
+        # Convert Elements to UUIDs
+        if order:
+            from ._utils import to_uuid
+
+            order = [to_uuid(item) for item in order]
+
+        # Pass all field values through **kwargs to satisfy mypy
+        super().__init__(**{"name": name, "order": order or [], **data})
+
+    @field_validator("order", mode="before")
+    @classmethod
+    def _validate_order(cls, value: Any) -> list[UUID]:
+        """Validate and coerce order field."""
+        if value is None:
+            return []
+
+        from ._utils import to_uuid
+
+        if not isinstance(value, list):
+            value = [value]
+
+        result = []
+        for item in value:
+            with contextlib.suppress(Exception):
+                result.append(to_uuid(item))
+        return result
+
+    # ==================== Core Operations ====================
+
+    def append(self, item_id: UUID | Element) -> None:
+        """Add item to end of progression."""
+        from ._utils import to_uuid
+
+        uid = to_uuid(item_id)
+        self.order.append(uid)
+
+    def insert(self, index: int, item_id: UUID | Element) -> None:
+        """Insert item at specific position."""
+        from ._utils import to_uuid
+
+        uid = to_uuid(item_id)
+        self.order.insert(index, uid)
+
+    def remove(self, item_id: UUID | Element) -> None:
+        """Remove first occurrence of item from progression."""
+        from ._utils import to_uuid
+
+        uid = to_uuid(item_id)
+        self.order.remove(uid)
+
+    def pop(self, index: int = -1) -> UUID:
+        """Remove and return item at index."""
+        return self.order.pop(index)
+
+    def popleft(self) -> UUID:
+        """Remove and return first item (queue behavior)."""
+        if not self.order:
+            raise IndexError("Progression is empty")
+        return self.order.pop(0)
+
+    def clear(self) -> None:
+        """Remove all items from progression."""
+        self.order.clear()
+
+    def extend(self, items: list[UUID | Element]) -> None:
+        """Extend progression with multiple items."""
+        from ._utils import to_uuid
+
+        for item in items:
+            uid = to_uuid(item)
+            self.order.append(uid)
+
+    # ==================== Query Operations ====================
+
+    def __contains__(self, item: UUID | Element) -> bool:
+        """Check if item is in progression."""
+        from ._utils import to_uuid
+
+        with contextlib.suppress(Exception):
+            uid = to_uuid(item)
+            return uid in self.order
+        return False
+
+    def __len__(self) -> int:
+        """Return number of items."""
+        return len(self.order)
+
+    def __iter__(self):
+        """Iterate over UUIDs in order."""
+        return iter(self.order)
+
+    @overload
+    def __getitem__(self, index: int) -> UUID:
+        """Get single item by index."""
+        ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[UUID]:
+        """Get multiple items by slice."""
+        ...
+
+    def __getitem__(self, index: int | slice) -> UUID | list[UUID]:
+        """Get item(s) by index."""
+        return self.order[index]
+
+    def __setitem__(self, index: int | slice, value: UUID | Element | list) -> None:
+        """Set item(s) at index."""
+        from ._utils import to_uuid
+
+        if isinstance(index, slice):
+            # Type guard: ensure value is a list when using slice
+            if not isinstance(value, list):
+                raise TypeError(f"Cannot assign {type(value).__name__} to slice, expected list")
+            self.order[index] = [to_uuid(v) for v in value]
+        else:
+            self.order[index] = to_uuid(value)
+
+    def index(self, item_id: UUID | Element) -> int:
+        """Get index of item in progression."""
+        from ._utils import to_uuid
+
+        uid = to_uuid(item_id)
+        return self.order.index(uid)
+
+    def __reversed__(self):
+        """Iterate over UUIDs in reverse order."""
+        return reversed(self.order)
+
+    def _validate_index(self, index: int, allow_end: bool = False) -> int:
+        """Validate and normalize index (supports negative). Raises IndexError if out of bounds."""
+        length = len(self.order)
+        if length == 0 and not allow_end:
+            raise IndexError("Progression is empty")
+
+        # Normalize negative indices
+        if index < 0:
+            index = length + index
+
+        # Check bounds
+        max_index = length if allow_end else length - 1
+        if index < 0 or index > max_index:
+            raise IndexError(f"Index {index} out of range for progression of length {length}")
+
+        return index
+
+    # ==================== Workflow Operations ====================
+
+    def move(self, from_index: int, to_index: int) -> None:
+        """Move item from one position to another.
+
+        Args:
+            from_index: Current position (supports negative indexing)
+            to_index: Target position (supports negative indexing)
+        """
+        from_index = self._validate_index(from_index)
+        # For to_index, allow insertion at end
+        to_index = self._validate_index(to_index, allow_end=True)
+
+        item = self.order.pop(from_index)
+        # Adjust to_index if we removed item before it
+        if from_index < to_index:
+            to_index -= 1
+        self.order.insert(to_index, item)
+
+    def swap(self, index1: int, index2: int) -> None:
+        """Swap two items by index.
+
+        Args:
+            index1: First position (supports negative indexing)
+            index2: Second position (supports negative indexing)
+        """
+        index1 = self._validate_index(index1)
+        index2 = self._validate_index(index2)
+
+        self.order[index1], self.order[index2] = self.order[index2], self.order[index1]
+
+    def reverse(self) -> None:
+        """Reverse the progression in-place."""
+        self.order.reverse()
+
+    # ==================== Set-like Operations ====================
+
+    def include(self, item: UUID | Element) -> bool:
+        """Include item in progression (idempotent).
+
+        Returns:
+            bool: True if item was added, False if already present
+        """
+        from ._utils import to_uuid
+
+        uid = to_uuid(item)
+        if uid not in self.order:
+            self.order.append(uid)
+            return True
+        return False
+
+    def exclude(self, item: UUID | Element) -> bool:
+        """Exclude item from progression (idempotent).
+
+        Returns:
+            bool: True if item was removed, False if not present
+        """
+        from ._utils import to_uuid
+
+        uid = to_uuid(item)
+        if uid in self.order:
+            self.order.remove(uid)
+            return True
+        return False
+
+    def __repr__(self) -> str:
+        name_str = f" name='{self.name}'" if self.name else ""
+        return f"Progression(len={len(self)}{name_str})"

lionherd_core/errors.py

@@ -0,0 +1,104 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+from .protocols import Serializable, implements
+
+__all__ = (
+    "ConfigurationError",
+    "ConnectionError",
+    "ExecutionError",
+    "LionherdError",
+    "TimeoutError",
+    "ValidationError",
+)
+
+
+@implements(Serializable)
+class LionherdError(Exception):
+    """Base exception for all lionherd errors.
+
+    Attributes:
+        message: Human-readable error message
+        details: Additional structured context
+        retryable: Whether this error can be retried
+    """
+
+    default_message: str = "Lionherd error"
+    default_retryable: bool = True
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        details: dict[str, Any] | None = None,
+        retryable: bool | None = None,
+        cause: Exception | None = None,
+    ):
+        """Initialize error.
+
+        Args:
+            message: Error message (uses default_message if None)
+            details: Additional context dict
+            retryable: Whether error can be retried (uses default_retryable if None)
+            cause: Original exception that caused this error
+        """
+        self.message = message or self.default_message
+        self.details = details or {}
+        self.retryable = retryable if retryable is not None else self.default_retryable
+
+        if cause:
+            self.__cause__ = cause  # Preserve traceback
+
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize error to dict for logging/debugging.
+
+        Returns:
+            Dict with error type, message, details, retryable flag
+        """
+        return {
+            "error": self.__class__.__name__,
+            "message": self.message,
+            "retryable": self.retryable,
+            **({"details": self.details} if self.details else {}),
+        }
+
+
+class ValidationError(LionherdError):
+    """Validation failure. Not retryable."""
+
+    default_message = "Validation failed"
+    default_retryable = False  # Validation errors won't fix themselves
+
+
+class ConfigurationError(LionherdError):
+    """Configuration error. Not retryable."""
+
+    default_message = "Configuration error"
+    default_retryable = False  # Config errors need manual fixes
+
+
+class ExecutionError(LionherdError):
+    """Event/Calling execution failure. Retryable by default."""
+
+    default_message = "Execution failed"
+    default_retryable = True  # Most execution failures are transient
+
+
+class ConnectionError(LionherdError):
+    """Connection/network failure. Retryable by default."""
+
+    default_message = "Connection error"
+    default_retryable = True  # Network issues are often transient
+
+
+class TimeoutError(LionherdError):
+    """Operation timeout. Retryable by default."""
+
+    default_message = "Operation timed out"
+    default_retryable = True  # Timeouts might succeed with more time

lionherd_core/libs/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0

lionherd_core/libs/concurrency/__init__.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from ._cancel import (
+    CancelScope,
+    effective_deadline,
+    fail_after,
+    fail_at,
+    move_on_after,
+    move_on_at,
+)
+from ._errors import get_cancelled_exc_class, is_cancelled, non_cancel_subgroup, shield
+from ._patterns import CompletionStream, bounded_map, gather, race, retry
+from ._primitives import CapacityLimiter, Condition, Event, Lock, Queue, Semaphore
+from ._priority_queue import PriorityQueue, QueueEmpty, QueueFull
+from ._resource_tracker import LeakInfo, LeakTracker, track_resource, untrack_resource
+from ._task import TaskGroup, create_task_group
+from ._utils import current_time, is_coro_func, run_sync, sleep
+
+ExceptionGroup = ExceptionGroup  # Re-export built-in
+ConcurrencyEvent = Event
+
+__all__ = (
+    "CancelScope",
+    "CapacityLimiter",
+    "CompletionStream",
+    "ConcurrencyEvent",
+    "Condition",
+    "Event",
+    "ExceptionGroup",
+    "LeakInfo",
+    "LeakTracker",
+    "Lock",
+    "PriorityQueue",
+    "Queue",
+    "QueueEmpty",
+    "QueueFull",
+    "Semaphore",
+    "TaskGroup",
+    "bounded_map",
+    "create_task_group",
+    "current_time",
+    "effective_deadline",
+    "fail_after",
+    "fail_at",
+    "gather",
+    "get_cancelled_exc_class",
+    "is_cancelled",
+    "is_coro_func",
+    "move_on_after",
+    "move_on_at",
+    "non_cancel_subgroup",
+    "race",
+    "retry",
+    "run_sync",
+    "shield",
+    "sleep",
+    "track_resource",
+    "untrack_resource",
+)

lionherd_core/libs/concurrency/_cancel.py

@@ -0,0 +1,85 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from math import isinf
+
+import anyio
+
+from ._utils import current_time
+
+CancelScope = anyio.CancelScope
+
+
+__all__ = (
+    "CancelScope",
+    "effective_deadline",
+    "fail_after",
+    "fail_at",
+    "move_on_after",
+    "move_on_at",
+)
+
+
+@contextmanager
+def fail_after(seconds: float | None) -> Iterator[CancelScope]:
+    """Create context with timeout that raises TimeoutError."""
+    if seconds is None:
+        # No timeout, but still cancellable by outer scopes
+        with CancelScope() as scope:
+            yield scope
+        return
+    with anyio.fail_after(seconds) as scope:
+        yield scope
+
+
+@contextmanager
+def move_on_after(seconds: float | None) -> Iterator[CancelScope]:
+    """Create context with timeout that silently cancels."""
+    if seconds is None:
+        # No timeout, but still cancellable by outer scopes
+        with CancelScope() as scope:
+            yield scope
+        return
+    with anyio.move_on_after(seconds) as scope:
+        yield scope
+
+
+@contextmanager
+def fail_at(deadline: float | None) -> Iterator[CancelScope]:
+    """Create context that raises TimeoutError at absolute deadline."""
+    if deadline is None:
+        # No timeout, but still cancellable by outer scopes
+        with CancelScope() as scope:
+            yield scope
+        return
+    now = current_time()
+    seconds = max(0.0, deadline - now)
+    with fail_after(seconds) as scope:
+        yield scope
+
+
+@contextmanager
+def move_on_at(deadline: float | None) -> Iterator[CancelScope]:
+    """Create context that silently cancels at absolute deadline."""
+    if deadline is None:
+        # No timeout, but still cancellable by outer scopes
+        with CancelScope() as scope:
+            yield scope
+        return
+    now = current_time()
+    seconds = max(0.0, deadline - now)
+    with anyio.move_on_after(seconds) as scope:
+        yield scope
+
+
+def effective_deadline() -> float | None:
+    """Return the ambient effective deadline, or None if unlimited.
+
+    AnyIO uses +inf to indicate "no deadline".
+    """
+    d = anyio.current_effective_deadline()
+    return None if isinf(d) else d

lionherd_core/libs/concurrency/_errors.py

@@ -0,0 +1,80 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import ParamSpec, TypeVar
+
+import anyio
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+
+__all__ = (
+    "get_cancelled_exc_class",
+    "is_cancelled",
+    "non_cancel_subgroup",
+    "shield",
+    "split_cancellation",
+)
+
+
+def get_cancelled_exc_class() -> type[BaseException]:
+    """Return the backend-native cancellation exception class."""
+    return anyio.get_cancelled_exc_class()
+
+
+def is_cancelled(exc: BaseException) -> bool:
+    """True if this is the backend-native cancellation exception."""
+    return isinstance(exc, anyio.get_cancelled_exc_class())
+
+
+async def shield(func: Callable[P, Awaitable[T]], *args: P.args, **kwargs: P.kwargs) -> T:
+    """Run ``func`` immune to outer cancellation.
+
+    Args:
+        func: Async function to shield from cancellation
+        *args: Positional arguments for func
+        **kwargs: Keyword arguments for func
+
+    Returns:
+        Result of func
+    """
+    with anyio.CancelScope(shield=True):
+        return await func(*args, **kwargs)  # type: ignore[return-value]
+
+
+# -------- ExceptionGroup helpers (Python 3.11+) --------
+
+
+def split_cancellation(
+    eg: BaseExceptionGroup,
+) -> tuple[BaseExceptionGroup | None, BaseExceptionGroup | None]:
+    """Split an exception group into (cancel_subgroup, non_cancel_subgroup).
+
+    Uses Python 3.11+ ExceptionGroup.split() to preserve structure, tracebacks,
+    __cause__/__context__/__notes__.
+
+    Args:
+        eg: Exception group to split
+
+    Returns:
+        Tuple of (cancellation exceptions, non-cancellation exceptions).
+        Either element may be None if that category is empty.
+    """
+    return eg.split(anyio.get_cancelled_exc_class())
+
+
+def non_cancel_subgroup(eg: BaseExceptionGroup) -> BaseExceptionGroup | None:
+    """Return subgroup without cancellations, or None if empty.
+
+    Args:
+        eg: Exception group to filter
+
+    Returns:
+        Subgroup containing only non-cancellation exceptions, or None.
+    """
+    _, rest = eg.split(anyio.get_cancelled_exc_class())
+    return rest