click-async-plugins 0.8.0__tar.gz → 0.9.0__tar.gz

{click_async_plugins-0.8.0 → click_async_plugins-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: click-async-plugins
-Version: 0.8.0
+Version: 0.9.0
 Summary: An architecture to easily run asyncio tasks from Click
 Author-email: "martin f. krafft" <click-async-plugins@pobox.madduck.net>
 License-File: LICENSE

{click_async_plugins-0.8.0 → click_async_plugins-0.9.0}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.8.0'
-__version_tuple__ = version_tuple = (0, 8, 0)
+__version__ = version = '0.9.0'
+__version_tuple__ = version_tuple = (0, 9, 0)
 
 __commit_id__ = commit_id = None

{click_async_plugins-0.8.0 → click_async_plugins-0.9.0}/click_async_plugins/debug.py

@@ -10,7 +10,7 @@ from collections.abc import AsyncGenerator, Callable
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from functools import partial
-from typing import Any, Coroutine, cast
+from typing import Any, Coroutine, Never, cast
 
 from click_async_plugins.util import CliContext
 
@@ -44,6 +44,10 @@ def _name_for_coro(coro: Coroutine[Any, Any, Any] | None) -> str:
     return "(unknown)"
 
 
+def interrupt(clictx: CliContext) -> Never:
+    raise KeyboardInterrupt
+
+
 def debug_info(clictx: CliContext) -> str:
     """Prints debugging information on tasks and CliContext"""
     ret = "*** BEGIN DEBUG INFO: ***\n"
@@ -58,7 +62,7 @@ def debug_info(clictx: CliContext) -> str:
     ret += "CliContext:\n"
     maxlen = max([len(k) for k in clictx.__dict__.keys()])
     for attr, value in clictx.__dict__.items():
-        ret += f"  {attr:>{maxlen}s} = {value!r}\n"
+        ret += f"  {attr:>{maxlen}s} = {value!r} (id:{id(value)})\n"
     return ret + "*** END DEBUG INFO: ***"
 
 
@@ -188,6 +192,7 @@ async def monitor_stdin_for_debug_commands[ContextT: CliContext](
     decrease_loglevel.__doc__ = "Decrease the logging level"
 
     map = {
+        0x3: KeyAndFunc(r"^C", interrupt),
         0xA: KeyAndFunc(r"\n", echo_newline),
         0xD: KeyAndFunc(r"\n", echo_newline),
         0x1B: KeyAndFunc("<Esc>", terminal_block),

{click_async_plugins-0.8.0 → click_async_plugins-0.9.0}/click_async_plugins/itc.py

@@ -1,4 +1,5 @@
 import asyncio
+import inspect
 import logging
 import time
 from collections import defaultdict
@@ -8,6 +9,31 @@ from typing import Any
 logger = logging.getLogger(__name__)
 
 
+def _caller(depth: int = 1) -> str:
+    """Return a description of a calling frame, ``depth`` frames up.
+
+    ``depth`` counts frames starting at this helper, so ``depth=1`` (the
+    default) reports the direct caller of this helper, ``depth=2`` the frame
+    above that, and so on. Returns a ``file:lineno in function`` string, or
+    a fallback marker if the frame cannot be determined.
+
+    Raises:
+        ValueError: If ``depth`` is less than 1.
+    """
+    if depth < 1:
+        raise ValueError(f"depth must be >= 1, got {depth}")
+
+    frame = inspect.currentframe()
+    try:
+        for _ in range(depth):
+            frame = frame.f_back if frame is not None else None
+        if frame is None:
+            return "<unknown>"
+        return f"{frame.f_code.co_filename}:{frame.f_lineno} in {frame.f_code.co_name}"
+    finally:
+        del frame
+
+
 class ITC:
     def __init__(self) -> None:
         self._events: dict[str, list[asyncio.Event]] = defaultdict(list[asyncio.Event])
@@ -25,13 +51,20 @@ class ITC:
         return f"{ret}{'    ' if i > 0 else ''})"
 
     def set(self, key: str, obj: Any) -> None:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"set('{key}', {obj!r}) called from {_caller(2)}")
         self._objects[key] = obj
         self.fire(key)
 
     def get(self, key: str, default: Any = None) -> Any:
-        return self._objects.get(key, default)
+        value = self._objects.get(key, default)
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"get('{key}') -> {value!r} called from {_caller(2)}")
+        return value
 
     def fire(self, key: str) -> None:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"fire('{key}') called from {_caller(2)}")
         logger.debug(f"Notifying subscribers of update to '{key}'…")
         for event in self._events.get(key) or []:
             event.set()
@@ -47,6 +80,9 @@ class ITC:
     ) -> AsyncGenerator[Any | None]:
         at_most_every = 0 if at_most_every is None else at_most_every
 
+        caller = _caller(2) if logger.isEnabledFor(logging.DEBUG) else ""
+        logger.debug(f"updates('{key}') subscribing from {caller}")
+
         if timeout is not None and timeout <= 0:
             logger.warning("Updates timeout <= 0, disabling timeout…")
             timeout = None
@@ -60,7 +96,12 @@ class ITC:
 
         try:
             if yield_immediately:
-                yield self._objects.get(key, yield_for_no_value)
+                value = self._objects.get(key, yield_for_no_value)
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.debug(
+                        f"updates('{key}') yielding initial {value!r} to {caller}"
+                    )
+                yield value
 
             timestamp = 0.0
             while True:
@@ -81,6 +122,8 @@ class ITC:
                 # instead of being wiped out.
                 event.clear()
                 value = self._objects.get(key, yield_for_no_value)
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.debug(f"updates('{key}') yielding {value!r} to {caller}")
                 yield value
                 timestamp = time.monotonic()
 

{click_async_plugins-0.8.0 → click_async_plugins-0.9.0}/tests/test_debug.py

@@ -4,8 +4,8 @@ import os
 import pty
 import sys
 import types
-from collections.abc import AsyncGenerator, Iterator
-from typing import Any
+from collections.abc import AsyncGenerator, Coroutine, Iterator
+from typing import Any, cast
 
 import pytest
 from click.testing import CliRunner
@@ -21,6 +21,7 @@ from click_async_plugins.debug import (
     debug_info,
     echo_newline,
     getch,
+    interrupt,
     monitor_stdin_for_debug_commands,
     print_help,
     puts,
@@ -52,6 +53,11 @@ def test_echo_newline(clictx: CliContext) -> None:
     assert echo_newline(clictx) == ""
 
 
+def test_interrupt(clictx: CliContext) -> None:
+    with pytest.raises(KeyboardInterrupt):
+        interrupt(clictx)
+
+
 def test_terminal_block(clictx: CliContext) -> None:
     block = terminal_block(clictx)
     assert block.startswith("\n" * 8 + "The time is now: ")
@@ -79,7 +85,7 @@ def test_name_for_coro_unknown() -> None:
 
 def test_name_for_coro_falls_back_to_name() -> None:
     # an object with __name__ but no __qualname__
-    obj = types.SimpleNamespace(__name__="named")
+    obj = cast(Coroutine[Any, Any, Any], types.SimpleNamespace(__name__="named"))
     assert _name_for_coro(obj) == "named"
 
 

{click_async_plugins-0.8.0 → click_async_plugins-0.9.0}/tests/test_itc.py

@@ -207,3 +207,117 @@ async def test_updates_does_not_lose_update_during_consumer_work(itc: ITC) -> No
 
     assert await asyncio.wait_for(anext(gen), 1) == 2
     await gen.aclose()
+
+
+def test_set_logs_caller_and_value(itc: ITC, caplog: pytest.LogCaptureFixture) -> None:
+    caplog.set_level(logging.DEBUG)
+    itc.set("key", 7)
+    record = next(r for r in caplog.records if r.message.startswith("set("))
+    assert "set('key', 7) called from" in record.message
+    assert "test_itc.py" in record.message
+    assert "test_set_logs_caller_and_value" in record.message
+
+
+def test_get_logs_caller_and_value(itc: ITC, caplog: pytest.LogCaptureFixture) -> None:
+    caplog.set_level(logging.DEBUG)
+    itc.set("key", 7)
+    caplog.clear()
+    assert itc.get("key") == 7
+    record = next(r for r in caplog.records if r.message.startswith("get("))
+    assert "get('key') -> 7 called from" in record.message
+    assert "test_get_logs_caller_and_value" in record.message
+
+
+def test_fire_logs_caller(itc: ITC, caplog: pytest.LogCaptureFixture) -> None:
+    caplog.set_level(logging.DEBUG)
+    itc.fire("key")
+    record = next(r for r in caplog.records if r.message.startswith("fire("))
+    assert "fire('key') called from" in record.message
+    assert "test_fire_logs_caller" in record.message
+
+
+@pytest.mark.asyncio
+async def test_updates_logs_caller_and_values(
+    itc: ITC, caplog: pytest.LogCaptureFixture
+) -> None:
+    caplog.set_level(logging.DEBUG)
+    itc.set("key", 1)
+    caplog.clear()
+
+    gen = itc.updates("key")
+    assert await anext(gen) == 1
+    await gen.aclose()
+
+    assert any(
+        "updates('key') subscribing from" in r.message
+        and "test_updates_logs_caller_and_values" in r.message
+        for r in caplog.records
+    )
+    assert any(
+        "updates('key') yielding initial 1 to" in r.message for r in caplog.records
+    )
+
+
+@pytest.mark.asyncio
+async def test_updates_logs_subsequent_values(
+    itc: ITC, caplog: pytest.LogCaptureFixture
+) -> None:
+    caplog.set_level(logging.DEBUG)
+    gen = itc.updates("key", yield_immediately=False)
+    pending = asyncio.ensure_future(anext(gen))
+    await asyncio.sleep(0)
+    itc.set("key", 42)
+    assert await asyncio.wait_for(pending, 1) == 42
+    await gen.aclose()
+
+    assert any("updates('key') yielding 42 to" in r.message for r in caplog.records)
+
+
+def test_caller_defaults_to_direct_caller() -> None:
+    from click_async_plugins.itc import _caller
+
+    def helper() -> str:
+        return _caller()
+
+    assert helper().endswith(" in helper")
+    assert "test_itc.py" in helper()
+
+
+def test_caller_depth_walks_up_stack() -> None:
+    from click_async_plugins.itc import _caller
+
+    def inner() -> str:
+        return _caller(2)
+
+    def outer() -> str:
+        return inner()
+
+    assert outer().endswith(" in outer")
+
+
+def test_caller_zero_depth_raises() -> None:
+    from click_async_plugins.itc import _caller
+
+    with pytest.raises(ValueError, match="depth must be >= 1"):
+        _caller(0)
+
+
+def test_caller_negative_depth_raises() -> None:
+    from click_async_plugins.itc import _caller
+
+    with pytest.raises(ValueError, match="depth must be >= 1"):
+        _caller(-1)
+
+
+def test_caller_depth_beyond_stack_returns_unknown() -> None:
+    from click_async_plugins.itc import _caller
+
+    assert _caller(10_000) == "<unknown>"
+
+
+def test_get_does_not_log_when_debug_disabled(
+    itc: ITC, caplog: pytest.LogCaptureFixture
+) -> None:
+    caplog.set_level(logging.INFO)
+    itc.get("key")
+    assert not any(r.message.startswith("get(") for r in caplog.records)