matrx-utils 2.0.0__tar.gz → 2.0.2__tar.gz

matrx_utils-2.0.2/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

{matrx_utils-2.0.0 → matrx_utils-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-utils
-Version: 2.0.0
+Version: 2.0.2
 Summary: Core shared utilities for the Matrx ecosystem (file handling now lives in matrx-files)
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current

{matrx_utils-2.0.0 → matrx_utils-2.0.2}/matrx_utils/__init__.py

@@ -51,6 +51,7 @@ from .fancy_prints import (
     vcprint,
 )
 from .utils import (
+    AsyncSingleFlight,
     async_test_wrapper,
     cleanup_async_resources,
     clear_terminal,
@@ -297,6 +298,7 @@ from .utils import (
 )
 
 __all__ = [
+    "AsyncSingleFlight",
     # rendezvous
     "Rendezvous",
     "RendezvousStats",

{matrx_utils-2.0.0 → matrx_utils-2.0.2}/matrx_utils/diagnostics/loop_watchdog.py

@@ -65,6 +65,16 @@ def _stall_signature(name: str, stack_text: str | None) -> str:
     if not stack_text:
         return f"{name}:no-stack"
     sites = [line.strip() for line in stack_text.split("\n") if line.lstrip().startswith("File ")]
+    relevant_sites = [
+        site
+        for site in sites
+        if "/site-packages/" not in site and "/lib/python" not in site
+    ]
+    # Transport implementation frames (SSL read/write/handshake) vary within
+    # one outage and previously defeated dedupe. Prefer application/package
+    # call sites while retaining the full stack in the report payload.
+    if relevant_sites:
+        sites = relevant_sites
     digest = hashlib.sha1(("\n".join(sites)).encode("utf-8")).hexdigest()[:16]
     return f"{name}:{digest}"
 

{matrx_utils-2.0.0 → matrx_utils-2.0.2}/matrx_utils/utils/__init__.py

@@ -2,6 +2,7 @@ from .get_dir_structure import generate_directory_structure, generate_and_save_d
 from .clear_terminal import clear_terminal
 from .testing import cleanup_async_resources, async_test_wrapper
 from .detached_task import detached_task
+from .singleflight import AsyncSingleFlight
 
 
 __all__ = [
@@ -11,4 +12,5 @@ __all__ = [
     "cleanup_async_resources",
     "async_test_wrapper",
     "detached_task",
-]
+    "AsyncSingleFlight",
+]

matrx_utils-2.0.2/matrx_utils/utils/singleflight.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Hashable
+from typing import Generic, TypeVar
+
+
+K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
+
+
+class AsyncSingleFlight(Generic[K, V]):
+    """Collapse concurrent work for the same key into one cancellation-safe task."""
+
+    def __init__(self) -> None:
+        self._tasks: dict[K, asyncio.Task[V]] = {}
+
+    @property
+    def pending(self) -> int:
+        return len(self._tasks)
+
+    async def do(self, key: K, factory: Callable[[], Awaitable[V]]) -> V:
+        task = self._tasks.get(key)
+        if task is None or task.done():
+            # Keys can be credentials or user identifiers. Never expose them in
+            # task names, trace dumps, or process introspection.
+            async def invoke() -> V:
+                return await factory()
+
+            task = asyncio.create_task(invoke(), name="singleflight")
+            self._tasks[key] = task
+            task.add_done_callback(lambda done, flight_key=key: self._finish(flight_key, done))
+
+        # A caller disconnect/cancellation must not cancel work shared by other
+        # callers. The task owns its own lifetime and is removed on completion.
+        return await asyncio.shield(task)
+
+    def _finish(self, key: K, task: asyncio.Task[V]) -> None:
+        if self._tasks.get(key) is task:
+            self._tasks.pop(key, None)
+        # Retrieve unexpected exceptions even when every waiter was cancelled,
+        # preventing "Task exception was never retrieved" during shutdown.
+        try:
+            task.exception()
+        except asyncio.CancelledError:
+            pass

{matrx_utils-2.0.0 → matrx_utils-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-utils"
-version = "2.0.0"
+version = "2.0.2"
 description = "Core shared utilities for the Matrx ecosystem (file handling now lives in matrx-files)"
 readme = "README.md"
 license = { text = "MIT" }

matrx_utils-2.0.2/tests/test_loop_watchdog_signature.py

@@ -0,0 +1,16 @@
+from matrx_utils.diagnostics.loop_watchdog import _stall_signature
+
+
+def test_transport_frames_do_not_fragment_stall_signature() -> None:
+    shared = '  File "/srv/aidream/aidream/api/app.py", line 500, in run\n'
+    ssl_read = (
+        shared
+        + '  File "/usr/lib/python3.13/asyncio/sslproto.py", line 700, in read\n'
+        + '  File "/venv/site-packages/asyncpg/pool.py", line 100, in acquire\n'
+    )
+    ssl_write = (
+        shared
+        + '  File "/usr/lib/python3.13/asyncio/sslproto.py", line 800, in write\n'
+        + '  File "/venv/site-packages/asyncpg/pool.py", line 200, in connect\n'
+    )
+    assert _stall_signature("api", ssl_read) == _stall_signature("api", ssl_write)

matrx_utils-2.0.2/tests/test_singleflight.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from matrx_utils import AsyncSingleFlight
+
+
+@pytest.mark.asyncio
+async def test_same_key_runs_factory_once() -> None:
+    flight: AsyncSingleFlight[str, int] = AsyncSingleFlight()
+    started = asyncio.Event()
+    release = asyncio.Event()
+    calls = 0
+
+    async def work() -> int:
+        nonlocal calls
+        calls += 1
+        started.set()
+        await release.wait()
+        return 42
+
+    waiters = [asyncio.create_task(flight.do("key", work)) for _ in range(20)]
+    await started.wait()
+    assert calls == 1
+    assert flight.pending == 1
+
+    release.set()
+    assert await asyncio.gather(*waiters) == [42] * 20
+    assert flight.pending == 0
+
+
+@pytest.mark.asyncio
+async def test_cancelled_waiter_does_not_cancel_shared_work() -> None:
+    flight: AsyncSingleFlight[str, str] = AsyncSingleFlight()
+    started = asyncio.Event()
+    release = asyncio.Event()
+
+    async def work() -> str:
+        started.set()
+        await release.wait()
+        return "done"
+
+    first = asyncio.create_task(flight.do("key", work))
+    await started.wait()
+    second = asyncio.create_task(flight.do("key", work))
+    first.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await first
+
+    release.set()
+    assert await second == "done"
+    assert flight.pending == 0
+
+
+@pytest.mark.asyncio
+async def test_different_keys_run_independently() -> None:
+    flight: AsyncSingleFlight[str, str] = AsyncSingleFlight()
+    calls: list[str] = []
+
+    async def work(key: str) -> str:
+        calls.append(key)
+        await asyncio.sleep(0)
+        return key
+
+    assert await asyncio.gather(
+        flight.do("a", lambda: work("a")),
+        flight.do("b", lambda: work("b")),
+    ) == ["a", "b"]
+    assert sorted(calls) == ["a", "b"]
+
+
+@pytest.mark.asyncio
+async def test_factory_may_return_any_awaitable() -> None:
+    flight: AsyncSingleFlight[str, int] = AsyncSingleFlight()
+    future = asyncio.get_running_loop().create_future()
+    future.set_result(7)
+    assert await flight.do("future", lambda: future) == 7