krons 0.1.0__py3-none-any.whl

kronos/utils/concurrency/_priority_queue.py

@@ -0,0 +1,135 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Async priority queue with condition-based synchronization.
+
+Provides asyncio.PriorityQueue-like interface using anyio primitives.
+Uses heapq internally with sequence numbers for stable ordering.
+"""
+
+from __future__ import annotations
+
+import heapq
+from typing import Any, Generic, TypeVar
+
+from ._primitives import Condition
+
+T = TypeVar("T")
+
+__all__ = ("PriorityQueue", "QueueEmpty", "QueueFull")
+
+
+class QueueEmpty(Exception):  # noqa: N818
+    """Exception raised when queue.get_nowait() is called on empty queue."""
+
+
+class QueueFull(Exception):  # noqa: N818
+    """Exception raised when queue.put_nowait() is called on full queue."""
+
+
+class PriorityQueue(Generic[T]):
+    """Async priority queue using heapq + anyio.Condition.
+
+    Unlike asyncio.PriorityQueue, nowait methods are async (require lock).
+    Items stored as (priority, seq, item) for stable ordering when priorities equal.
+
+    Attributes:
+        maxsize: Maximum queue size. 0 means unlimited.
+    """
+
+    def __init__(self, maxsize: int = 0):
+        """Initialize priority queue.
+
+        Args:
+            maxsize: Max items allowed. 0 = unlimited.
+
+        Raises:
+            ValueError: If maxsize < 0.
+        """
+        if maxsize < 0:
+            raise ValueError("maxsize must be >= 0")
+        self.maxsize = maxsize
+        self._queue: list[Any] = []
+        self._seq = 0
+        self._condition = Condition()
+
+    @staticmethod
+    def _get_priority(item: Any) -> Any:
+        """Extract priority: first element if tuple/list, else item itself."""
+        if isinstance(item, (tuple, list)) and item:
+            return item[0]
+        return item
+
+    async def put(self, item: T) -> None:
+        """Put item into queue, blocking if full.
+
+        Args:
+            item: Item to enqueue. If tuple/list, first element is priority.
+        """
+        async with self._condition:
+            while self.maxsize > 0 and len(self._queue) >= self.maxsize:
+                await self._condition.wait()
+            priority = self._get_priority(item)
+            entry = (priority, self._seq, item)
+            self._seq += 1
+            heapq.heappush(self._queue, entry)
+            self._condition.notify()
+
+    async def put_nowait(self, item: T) -> None:
+        """Put item, raising QueueFull if at capacity. Async (requires lock).
+
+        Args:
+            item: Item to enqueue. If tuple/list, first element is priority.
+
+        Raises:
+            QueueFull: If queue is at maxsize.
+        """
+        async with self._condition:
+            if self.maxsize > 0 and len(self._queue) >= self.maxsize:
+                raise QueueFull("Queue is full")
+            priority = self._get_priority(item)
+            entry = (priority, self._seq, item)
+            self._seq += 1
+            heapq.heappush(self._queue, entry)
+            self._condition.notify()
+
+    async def get(self) -> T:
+        """Get highest priority item (lowest value), blocking if empty.
+
+        Returns:
+            Item with lowest priority value.
+        """
+        async with self._condition:
+            while not self._queue:
+                await self._condition.wait()
+            _priority, _seq, item = heapq.heappop(self._queue)
+            self._condition.notify()
+            return item
+
+    async def get_nowait(self) -> T:
+        """Get item, raising QueueEmpty if none available. Async (requires lock).
+
+        Returns:
+            Item with lowest priority value.
+
+        Raises:
+            QueueEmpty: If queue is empty.
+        """
+        async with self._condition:
+            if not self._queue:
+                raise QueueEmpty("Queue is empty")
+            _priority, _seq, item = heapq.heappop(self._queue)
+            self._condition.notify()
+            return item
+
+    def qsize(self) -> int:
+        """Approximate queue size. Unlocked, may be stale. Use for monitoring."""
+        return len(self._queue)
+
+    def empty(self) -> bool:
+        """Check if empty. Unlocked, may be stale. Use for monitoring."""
+        return len(self._queue) == 0
+
+    def full(self) -> bool:
+        """Check if full. Unlocked, may be stale. Use for monitoring."""
+        return self.maxsize > 0 and len(self._queue) >= self.maxsize

kronos/utils/concurrency/_resource_tracker.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Resource leak detection via weakref-based tracking.
+
+Tracks object lifetimes to detect resources that outlive their expected scope.
+Uses weakref finalizers for automatic cleanup when objects are garbage collected.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import weakref
+from dataclasses import dataclass
+
+__all__ = (
+    "LeakInfo",
+    "LeakTracker",
+    "track_resource",
+    "untrack_resource",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class LeakInfo:
+    """Metadata for a tracked resource.
+
+    Attributes:
+        name: Identifier for the resource (auto-generated if not provided).
+        kind: Optional category/type label for grouping.
+        created_at: Unix timestamp when tracking began.
+    """
+
+    name: str
+    kind: str | None
+    created_at: float
+
+
+class LeakTracker:
+    """Thread-safe tracker for detecting resource leaks.
+
+    Uses weakref finalizers to automatically remove entries when objects
+    are garbage collected. Call `live()` to inspect currently tracked objects.
+
+    Example:
+        >>> tracker = LeakTracker()
+        >>> tracker.track(my_connection, name="db_conn", kind="database")
+        >>> # ... later, check for leaks ...
+        >>> leaks = tracker.live()
+        >>> if leaks:
+        ...     print(f"Potential leaks: {leaks}")
+    """
+
+    def __init__(self) -> None:
+        self._live: dict[int, LeakInfo] = {}
+        self._lock = threading.Lock()
+
+    def track(self, obj: object, *, name: str | None, kind: str | None) -> None:
+        """Begin tracking an object for leak detection.
+
+        Args:
+            obj: Object to track (must be weak-referenceable).
+            name: Identifier (defaults to "obj-{id}").
+            kind: Optional category label.
+        """
+        info = LeakInfo(name=name or f"obj-{id(obj)}", kind=kind, created_at=time.time())
+        key = id(obj)
+
+        def _finalizer(_key: int = key) -> None:
+            with self._lock:
+                self._live.pop(_key, None)
+
+        with self._lock:
+            self._live[key] = info
+        weakref.finalize(obj, _finalizer)
+
+    def untrack(self, obj: object) -> None:
+        """Manually stop tracking an object."""
+        with self._lock:
+            self._live.pop(id(obj), None)
+
+    def live(self) -> list[LeakInfo]:
+        """Return list of currently tracked (potentially leaked) resources."""
+        with self._lock:
+            return list(self._live.values())
+
+    def clear(self) -> None:
+        """Remove all tracked entries."""
+        with self._lock:
+            self._live.clear()
+
+
+_TRACKER = LeakTracker()
+
+
+def track_resource(obj: object, name: str | None = None, kind: str | None = None) -> None:
+    """Track an object using the global leak tracker.
+
+    Args:
+        obj: Object to track.
+        name: Optional identifier.
+        kind: Optional category label.
+    """
+    _TRACKER.track(obj, name=name, kind=kind)
+
+
+def untrack_resource(obj: object) -> None:
+    """Stop tracking an object in the global tracker."""
+    _TRACKER.untrack(obj)

kronos/utils/concurrency/_run_async.py

@@ -0,0 +1,67 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Sync-to-async bridge for running coroutines from synchronous contexts."""
+
+import threading
+from collections.abc import Awaitable
+from typing import Any, TypeVar
+
+import anyio
+
+T = TypeVar("T")
+
+__all__ = ("run_async",)
+
+
+def run_async(coro: Awaitable[T]) -> T:
+    """Execute an async coroutine from a synchronous context.
+
+    Creates an isolated thread with its own event loop to run the coroutine,
+    avoiding conflicts with any existing event loop in the current thread.
+    Thread-safe and blocks until completion.
+
+    Args:
+        coro: Awaitable to execute (coroutine, Task, or Future).
+
+    Returns:
+        The result of the awaited coroutine.
+
+    Raises:
+        BaseException: Any exception raised by the coroutine is re-raised.
+        RuntimeError: If the coroutine completes without producing a result.
+
+    Example:
+        >>> async def fetch_data():
+        ...     return {"status": "ok"}
+        >>> result = run_async(fetch_data())
+        >>> result
+        {'status': 'ok'}
+
+    Note:
+        Use sparingly. Prefer native async patterns when possible.
+        Each call creates a new thread and event loop.
+    """
+    result_container: list[Any] = []
+    exception_container: list[BaseException] = []
+
+    def run_in_thread() -> None:
+        try:
+
+            async def _runner() -> T:
+                return await coro
+
+            result = anyio.run(_runner)
+            result_container.append(result)
+        except BaseException as e:
+            exception_container.append(e)
+
+    thread = threading.Thread(target=run_in_thread, daemon=False)
+    thread.start()
+    thread.join()
+
+    if exception_container:
+        raise exception_container[0]
+    if not result_container:  # pragma: no cover
+        raise RuntimeError("Coroutine did not produce a result")
+    return result_container[0]

kronos/utils/concurrency/_task.py

@@ -0,0 +1,95 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Task group wrapper for structured concurrency.
+
+Thin wrapper around anyio.TaskGroup to provide a consistent internal API.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Any, TypeVar
+
+import anyio
+import anyio.abc
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+__all__ = (
+    "TaskGroup",
+    "create_task_group",
+)
+
+
+class TaskGroup:
+    """Wrapper around anyio.TaskGroup for structured concurrency.
+
+    All spawned tasks complete (or are cancelled) before the group exits.
+    Exceptions propagate and cancel sibling tasks.
+    """
+
+    __slots__ = ("_tg",)
+
+    def __init__(self, tg: anyio.abc.TaskGroup) -> None:
+        """Initialize with underlying anyio task group.
+
+        Args:
+            tg: The anyio TaskGroup to wrap.
+        """
+        self._tg = tg
+
+    @property
+    def cancel_scope(self) -> anyio.CancelScope:
+        """Cancel scope controlling the task group lifetime."""
+        return self._tg.cancel_scope
+
+    def start_soon(
+        self,
+        func: Callable[..., Awaitable[Any]],
+        *args: Any,
+        name: str | None = None,
+    ) -> None:
+        """Spawn task immediately without waiting for it to initialize.
+
+        Args:
+            func: Async callable to run.
+            *args: Positional arguments for func.
+            name: Optional task name for debugging.
+        """
+        self._tg.start_soon(func, *args, name=name)
+
+    async def start(
+        self,
+        func: Callable[..., Awaitable[R]],
+        *args: Any,
+        name: str | None = None,
+    ) -> R:
+        """Spawn task and wait for it to signal readiness via task_status.started().
+
+        Args:
+            func: Async callable that calls task_status.started(value).
+            *args: Positional arguments for func.
+            name: Optional task name for debugging.
+
+        Returns:
+            Value passed to task_status.started().
+        """
+        return await self._tg.start(func, *args, name=name)
+
+
+@asynccontextmanager
+async def create_task_group() -> AsyncIterator[TaskGroup]:
+    """Create a task group context for structured concurrency.
+
+    Usage:
+        async with create_task_group() as tg:
+            tg.start_soon(some_async_func)
+
+    Yields:
+        TaskGroup instance.
+    """
+    async with anyio.create_task_group() as tg:
+        yield TaskGroup(tg)

kronos/utils/concurrency/_utils.py

@@ -0,0 +1,79 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Concurrency utility functions.
+
+Thin wrappers around anyio for time, sleep, thread offloading, and coroutine detection.
+"""
+
+import inspect
+from collections.abc import Callable
+from functools import cache, partial
+from typing import Any, ParamSpec, TypeVar
+
+import anyio
+import anyio.to_thread
+
+P = ParamSpec("P")
+R = TypeVar("R")
+T = TypeVar("T")
+
+__all__ = ("current_time", "is_coro_func", "run_sync", "sleep")
+
+
+@cache
+def _is_coro_func_cached(func: Callable[..., Any]) -> bool:
+    """Cached coroutine check. Internal: expects already-unwrapped func."""
+    return inspect.iscoroutinefunction(func)
+
+
+def is_coro_func(func: Callable[..., Any]) -> bool:
+    """Check if func is a coroutine function, unwrapping partials first.
+
+    Unwraps partials before caching to prevent unbounded cache growth
+    (each partial instance would otherwise be a separate cache key).
+
+    Args:
+        func: Callable to check (may be wrapped in partial).
+
+    Returns:
+        True if underlying function is async def.
+    """
+    while isinstance(func, partial):
+        func = func.func
+    return _is_coro_func_cached(func)
+
+
+def current_time() -> float:
+    """Get current monotonic time in seconds.
+
+    Returns:
+        Monotonic clock value from anyio.
+    """
+    return anyio.current_time()
+
+
+async def run_sync(func: Callable[P, R], *args: P.args, **kwargs: P.kwargs) -> R:
+    """Run synchronous function in thread pool without blocking event loop.
+
+    Args:
+        func: Synchronous callable.
+        *args: Positional arguments for func.
+        **kwargs: Keyword arguments for func.
+
+    Returns:
+        Result of func(*args, **kwargs).
+    """
+    if kwargs:
+        func_with_kwargs = partial(func, **kwargs)
+        return await anyio.to_thread.run_sync(func_with_kwargs, *args)
+    return await anyio.to_thread.run_sync(func, *args)
+
+
+async def sleep(seconds: float) -> None:
+    """Async sleep without blocking the event loop.
+
+    Args:
+        seconds: Duration to sleep.
+    """
+    await anyio.sleep(seconds)

kronos/utils/fuzzy/__init__.py

@@ -0,0 +1,14 @@
+from ._extract_json import extract_json
+from ._fuzzy_json import fuzzy_json
+from ._fuzzy_match import fuzzy_match_keys
+from ._string_similarity import SimilarityAlgo, string_similarity
+from ._to_dict import to_dict
+
+__all__ = (
+    "extract_json",
+    "fuzzy_json",
+    "fuzzy_match_keys",
+    "string_similarity",
+    "SimilarityAlgo",
+    "to_dict",
+)

kronos/utils/fuzzy/_extract_json.py

@@ -0,0 +1,90 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""JSON extraction utilities for parsing JSON from strings and markdown blocks."""
+
+import re
+from typing import Any
+
+import orjson
+
+from ._fuzzy_json import MAX_JSON_INPUT_SIZE, fuzzy_json
+
+__all__ = ("extract_json",)
+
+_JSON_BLOCK_PATTERN = re.compile(r"```json\s*(.*?)\s*```", re.DOTALL)
+"""Regex for extracting content from ```json ... ``` code blocks."""
+
+_JSON_PARSE_ERRORS = (orjson.JSONDecodeError, ValueError, TypeError)
+"""Exceptions indicating parse failure (not system errors like MemoryError)."""
+
+
+def extract_json(
+    input_data: str | list[str],
+    /,
+    *,
+    fuzzy_parse: bool = False,
+    return_one_if_single: bool = True,
+    max_size: int = MAX_JSON_INPUT_SIZE,
+) -> Any | list[Any]:
+    """Extract and parse JSON from string or markdown code blocks.
+
+    Parsing strategy:
+        1. Try direct JSON parsing of entire input
+        2. On failure, extract ```json ... ``` blocks and parse each
+        3. Return [] if no valid JSON found
+
+    Args:
+        input_data: String or list of strings (joined with newlines).
+        fuzzy_parse: Use fuzzy_json() for malformed JSON.
+        return_one_if_single: Return single result directly (not wrapped in list).
+        max_size: Max input size in bytes (default: 10MB). DoS protection.
+
+    Returns:
+        - Single parsed object if return_one_if_single and exactly one result
+        - List of parsed objects otherwise
+        - [] if no valid JSON found
+
+    Raises:
+        ValueError: Input exceeds max_size.
+
+    Edge Cases:
+        - Multiple ```json blocks: returns list of all successfully parsed
+        - Invalid JSON in some blocks: skipped silently
+        - Empty input: returns []
+    """
+    input_str = "\n".join(input_data) if isinstance(input_data, list) else input_data
+
+    if len(input_str) > max_size:
+        msg = (
+            f"Input size ({len(input_str)} bytes) exceeds maximum "
+            f"({max_size} bytes). This limit prevents memory exhaustion."
+        )
+        raise ValueError(msg)
+
+    # Try direct parsing first
+    try:
+        parsed = fuzzy_json(input_str) if fuzzy_parse else orjson.loads(input_str)
+        return parsed if return_one_if_single else [parsed]
+    except _JSON_PARSE_ERRORS:
+        pass
+
+    # Extract from markdown code blocks
+    matches = _JSON_BLOCK_PATTERN.findall(input_str)
+    if not matches:
+        return []
+
+    if return_one_if_single and len(matches) == 1:
+        try:
+            return fuzzy_json(matches[0]) if fuzzy_parse else orjson.loads(matches[0])
+        except _JSON_PARSE_ERRORS:
+            return []
+
+    results: list[Any] = []
+    for m in matches:
+        try:
+            parsed = fuzzy_json(m) if fuzzy_parse else orjson.loads(m)
+            results.append(parsed)
+        except _JSON_PARSE_ERRORS:
+            continue
+    return results