pythonnative 0.24.0__tar.gz → 0.26.0__tar.gz

{pythonnative-0.24.0/src/pythonnative.egg-info → pythonnative-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.24.0
+Version: 0.26.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -105,6 +105,7 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Rich component library:** 25+ built-in components backed by real native widgets: `TextInput`, `Image` / `ImageBackground`, `ScrollView`, `FlatList` / `SectionList`, `Modal`, `Pressable` / `TouchableOpacity`, `Switch` / `Checkbox`, `Slider`, `SegmentedControl`, `Picker`, `DatePicker`, `ProgressBar` / `ActivityIndicator`, `WebView`, and more.
 - **Device APIs:** Cross-platform modules for `Camera`, `Location`, `FileSystem`, `Notifications`, `Clipboard`, `Share`, `Linking`, `Permissions`, `AppState`, `NetInfo`, `SecureStore`, `Battery`, `Haptics` / `Vibration`, and `Biometrics`, plus reactive `use_app_state` and `use_net_info` hooks.
 - **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect` / `use_layout_effect`, refs and imperative handles with `use_ref` / `use_imperative_handle`, and navigation with `use_navigation`, all through one consistent pattern. Components can return a single element, a list of siblings, or `None`, and `Fragment`, `Portal`, and reactive `Provider` context work the way they do in React.
+- **Async-first rendering:** One `asyncio` event loop runs the whole framework on the platform's main thread. Components can be `async def` and `await` data directly in the body; `Suspense` boundaries show declarative loading states while they wait. `use_resource` fetches during render, `use_effect` accepts coroutine callbacks (cancelled automatically on unmount), `lazy` code-splits components, and `use_transition` / `use_deferred_value` keep the UI responsive during expensive updates.
 - **Developer feedback that finds your bugs:** In dev mode (`pn preview`, hot reload, or `PN_DEV=1`), uncaught errors from renders, effects, and event handlers show a full-screen RedBox with the traceback; unknown style keys and duplicate list keys print "did you mean" warnings; and conditional hooks raise a `HookOrderError` at the source instead of silently cross-wiring state.
 - **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.
 - **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.

{pythonnative-0.24.0 → pythonnative-0.26.0}/README.md

@@ -34,6 +34,7 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Rich component library:** 25+ built-in components backed by real native widgets: `TextInput`, `Image` / `ImageBackground`, `ScrollView`, `FlatList` / `SectionList`, `Modal`, `Pressable` / `TouchableOpacity`, `Switch` / `Checkbox`, `Slider`, `SegmentedControl`, `Picker`, `DatePicker`, `ProgressBar` / `ActivityIndicator`, `WebView`, and more.
 - **Device APIs:** Cross-platform modules for `Camera`, `Location`, `FileSystem`, `Notifications`, `Clipboard`, `Share`, `Linking`, `Permissions`, `AppState`, `NetInfo`, `SecureStore`, `Battery`, `Haptics` / `Vibration`, and `Biometrics`, plus reactive `use_app_state` and `use_net_info` hooks.
 - **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect` / `use_layout_effect`, refs and imperative handles with `use_ref` / `use_imperative_handle`, and navigation with `use_navigation`, all through one consistent pattern. Components can return a single element, a list of siblings, or `None`, and `Fragment`, `Portal`, and reactive `Provider` context work the way they do in React.
+- **Async-first rendering:** One `asyncio` event loop runs the whole framework on the platform's main thread. Components can be `async def` and `await` data directly in the body; `Suspense` boundaries show declarative loading states while they wait. `use_resource` fetches during render, `use_effect` accepts coroutine callbacks (cancelled automatically on unmount), `lazy` code-splits components, and `use_transition` / `use_deferred_value` keep the UI responsive during expensive updates.
 - **Developer feedback that finds your bugs:** In dev mode (`pn preview`, hot reload, or `PN_DEV=1`), uncaught errors from renders, effects, and event handlers show a full-screen RedBox with the traceback; unknown style keys and duplicate list keys print "did you mean" warnings; and conditional hooks raise a `HookOrderError` at the source instead of silently cross-wiring state.
 - **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.
 - **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.

{pythonnative-0.24.0 → pythonnative-0.26.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.24.0"
+version = "0.26.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }

{pythonnative-0.24.0 → pythonnative-0.26.0}/src/pythonnative/__init__.py

@@ -60,7 +60,7 @@ Example:
     ```
 """
 
-__version__ = "0.24.0"
+__version__ = "0.26.0"
 
 from . import appearance, diagnostics, gestures, images, runtime, sdk
 from .alerts import Alert
@@ -92,6 +92,7 @@ from .components import (
     Slider,
     Spacer,
     StatusBar,
+    Suspense,
     Switch,
     Text,
     TextInput,
@@ -111,11 +112,11 @@ from .hooks import (
     component,
     create_context,
     memo,
-    use_async_effect,
     use_back_handler,
     use_callback,
     use_color_scheme,
     use_context,
+    use_deferred_value,
     use_effect,
     use_imperative_handle,
     use_keyboard_height,
@@ -126,8 +127,10 @@ from .hooks import (
     use_query,
     use_reducer,
     use_ref,
+    use_resource,
     use_safe_area_insets,
     use_state,
+    use_transition,
     use_window_dimensions,
 )
 from .native_modules import (
@@ -160,7 +163,7 @@ from .navigation import (
 )
 from .net import HTTPError, Response, fetch
 from .platform import Platform
-from .runtime import run_async
+from .runtime import run_async, run_blocking
 from .screen import create_screen
 from .sdk import (
     Props,
@@ -204,6 +207,7 @@ from .style import (
     style,
     use_theme,
 )
+from .suspense import Resource, lazy, start_resource
 
 __all__ = [
     # Components
@@ -233,6 +237,7 @@ __all__ = [
     "Slider",
     "Spacer",
     "StatusBar",
+    "Suspense",
     "Switch",
     "Text",
     "TextInput",
@@ -251,11 +256,11 @@ __all__ = [
     "MutationState",
     "QueryResult",
     "Ref",
-    "use_async_effect",
     "use_back_handler",
     "use_callback",
     "use_color_scheme",
     "use_context",
+    "use_deferred_value",
     "use_effect",
     "use_focus_effect",
     "use_imperative_handle",
@@ -268,11 +273,17 @@ __all__ = [
     "use_query",
     "use_reducer",
     "use_ref",
+    "use_resource",
     "use_route",
     "use_safe_area_insets",
     "use_state",
+    "use_transition",
     "use_window_dimensions",
     "Provider",
+    # Suspense and async rendering
+    "Resource",
+    "lazy",
+    "start_resource",
     # Navigation
     "NavigationContainer",
     "ScreenOptions",
@@ -349,6 +360,7 @@ __all__ = [
     "Response",
     # Runtime
     "run_async",
+    "run_blocking",
     "runtime",
     # Diagnostics
     "HookOrderError",

{pythonnative-0.24.0 → pythonnative-0.26.0}/src/pythonnative/animated.py

@@ -47,7 +47,7 @@ Example:
             await pn.Animated.timing(opacity, to=1.0, duration=400)
             await pn.Animated.timing(opacity, to=0.5, duration=200)
 
-        pn.use_async_effect(fade_in, [])
+        pn.use_effect(fade_in, [])
 
         return pn.Animated.View(
             pn.Text("Hello!"),
@@ -1014,7 +1014,7 @@ def use_animated_value(initial: float = 0.0) -> AnimatedValue:
             async def fade_in():
                 await pn.Animated.timing(opacity, to=1.0, duration=300)
 
-            pn.use_async_effect(fade_in, [])
+            pn.use_effect(fade_in, [])
             return pn.Animated.View(
                 pn.Text("Hello"),
                 style=pn.style(opacity=opacity),

{pythonnative-0.24.0 → pythonnative-0.26.0}/src/pythonnative/cli/pn.py

@@ -6,10 +6,14 @@ The console script `pn` (declared in `pyproject.toml`) dispatches to:
 - `pn doctor [platform]`: diagnose the local toolchain and config.
 - `pn preview [component]`: render the app in a desktop (Tkinter) window
   with Fast Refresh, the fast inner dev loop, no device required.
-- `pn run android|ios`: stage + build + install + launch on a device or
-  simulator, with optional on-device hot reload.
+- `pn devices [platform]`: list connected devices, emulators, and
+  simulators.
+- `pn run android|ios [--device D]`: stage + build + install + launch on
+  a device, emulator, or simulator, with optional on-device hot reload.
+- `pn logs android|ios`: stream logs from the running app without
+  rebuilding.
 - `pn build android|ios`: produce standalone artifacts (signed APK/AAB,
-  or an iOS archive/IPA).
+  or an iOS archive/IPA, optionally uploaded to App Store Connect).
 - `pn app-id android|ios`: print the resolved application/bundle id
   (handy for scripts and CI).
 - `pn clean`: remove the local `build/` directory.
@@ -34,6 +38,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from ..project import builder as builder_mod
+from ..project import devices as devices_mod
 from ..project import doctor as doctor_mod
 from ..project.android import collect_logcat_filters
 from ..project.config import CONFIG_FILENAME, AppConfig, ConfigError, render_default_toml
@@ -241,6 +246,41 @@ def _preview_entry(project_dir: Path) -> str:
         return "app.main"
 
 
+# ======================================================================
+# devices
+# ======================================================================
+
+
+def devices_command(args: argparse.Namespace) -> None:
+    """List connected devices, emulators, and simulators.
+
+    Args:
+        args: Parsed namespace with optional ``platform``.
+    """
+    platform: Optional[str] = getattr(args, "platform", None)
+    devices = devices_mod.list_devices(platform)
+    if not devices:
+        print("No devices found.")
+        print("Android: start an emulator or connect a device with USB debugging enabled.")
+        print("iOS: open Xcode once to install Simulators, or plug in a device.")
+        sys.exit(1)
+    print(f"  {'IDENTIFIER':<40} {'KIND':<10} {'STATE':<10} NAME")
+    for device in devices:
+        print(device.format())
+    print("\nTarget one with: pn run <platform> --device <identifier or name>")
+
+
+def _resolve_device(platform: str, query: Optional[str]) -> Optional[devices_mod.Device]:
+    """Resolve ``--device`` to a concrete target, exiting on a bad query."""
+    if not query:
+        return None
+    device = devices_mod.find_device(devices_mod.list_devices(platform), query)
+    if device is None:
+        print(f"Error: no {platform} device matches {query!r}. Run 'pn devices {platform}' to list targets.")
+        sys.exit(1)
+    return device
+
+
 # ======================================================================
 # run
 # ======================================================================
@@ -250,13 +290,14 @@ def run_project(args: argparse.Namespace) -> None:
     """Stage, build, install, and launch the app on a device/simulator.
 
     Args:
-        args: Parsed namespace (``platform``, ``prepare_only``,
-            ``hot_reload``, ``no_logs``).
+        args: Parsed namespace (``platform``, ``device``,
+            ``prepare_only``, ``hot_reload``, ``no_logs``).
     """
     platform: str = args.platform
     prepare_only: bool = getattr(args, "prepare_only", False)
     hot_reload: bool = getattr(args, "hot_reload", False)
     show_logs: bool = not getattr(args, "no_logs", False)
+    device = _resolve_device(platform, getattr(args, "device", None))
 
     config = _load_config_or_exit()
     builder = builder_mod.Builder(config, log=print)
@@ -273,9 +314,14 @@ def run_project(args: argparse.Namespace) -> None:
 
     try:
         if platform == "android":
-            _run_android(builder, prepared, hot_reload=hot_reload, show_logs=show_logs)
+            _run_android(builder, prepared, device=device, hot_reload=hot_reload, show_logs=show_logs)
+        elif device is not None and device.kind == "device":
+            _run_ios_device(builder, prepared, device=device)
+            if hot_reload:
+                print("Note: hot reload targets the iOS Simulator; skipping it for a physical device.")
+            return
         else:
-            _run_ios(builder, prepared, hot_reload=hot_reload, show_logs=show_logs)
+            _run_ios(builder, prepared, device=device, hot_reload=hot_reload, show_logs=show_logs)
     except builder_mod.BuildError as exc:
         print(f"Error: {exc}")
         sys.exit(1)
@@ -295,9 +341,14 @@ def _run_android(
     builder: builder_mod.Builder,
     prepared: builder_mod.PreparedProject,
     *,
+    device: Optional[devices_mod.Device],
     hot_reload: bool,
     show_logs: bool,
 ) -> None:
+    if device is not None:
+        # Both Gradle's install task and every adb call below honor
+        # ANDROID_SERIAL, so exporting it targets the whole run.
+        os.environ["ANDROID_SERIAL"] = device.identifier
     builder.install_android_debug(prepared)
     _clear_android_hot_reload_overlay(prepared.app_id)
     subprocess.run(
@@ -319,11 +370,12 @@ def _run_ios(
     builder: builder_mod.Builder,
     prepared: builder_mod.PreparedProject,
     *,
+    device: Optional[devices_mod.Device],
     hot_reload: bool,
     show_logs: bool,
 ) -> None:
     app_path = builder.build_ios_simulator(prepared)
-    udid = _select_ios_simulator()
+    udid = device.identifier if device is not None else _select_ios_simulator()
     if udid is None:
         print("No available iOS Simulators found; open the project in Xcode to run.")
         return
@@ -352,6 +404,45 @@ def _run_ios(
         print("Launched iOS app on Simulator.")
 
 
+def _run_ios_device(
+    builder: builder_mod.Builder,
+    prepared: builder_mod.PreparedProject,
+    *,
+    device: devices_mod.Device,
+) -> None:
+    """Build, install, and launch on a physical iOS device via devicectl."""
+    app_path = builder.build_ios_device(prepared)
+    print(f"Installing on {device.name}...")
+    install = subprocess.run(
+        ["xcrun", "devicectl", "device", "install", "app", "--device", device.identifier, str(app_path)],
+        check=False,
+    )
+    if install.returncode != 0:
+        print(
+            "Error: install failed. Make sure the device is unlocked, paired with this Mac, "
+            "and has Developer Mode enabled (Settings > Privacy & Security > Developer Mode)."
+        )
+        sys.exit(1)
+    launch = subprocess.run(
+        [
+            "xcrun",
+            "devicectl",
+            "device",
+            "process",
+            "launch",
+            "--terminate-existing",
+            "--device",
+            device.identifier,
+            prepared.app_id,
+        ],
+        check=False,
+    )
+    if launch.returncode != 0:
+        print("Error: launch failed. Launch the app from the home screen to see details.")
+        sys.exit(1)
+    print(f"Launched on {device.name}. Use Console.app (or Xcode > Devices) for device logs.")
+
+
 # ======================================================================
 # build
 # ======================================================================
@@ -361,16 +452,24 @@ def build_project(args: argparse.Namespace) -> None:
     """Build standalone, distributable artifacts for ``platform``.
 
     Args:
-        args: Parsed namespace (``platform``, ``debug``).
+        args: Parsed namespace (``platform``, ``debug``, ``upload``).
     """
     platform: str = args.platform
     debug: bool = getattr(args, "debug", False)
+    upload: bool = getattr(args, "upload", False)
 
     config = _load_config_or_exit()
     builder = builder_mod.Builder(config, log=print)
 
+    if upload and (platform != "ios" or debug):
+        print("Error: --upload applies to 'pn build ios' release builds only.")
+        sys.exit(1)
+    if upload and config.ios.signing.export_method != "app-store":
+        print('Error: --upload requires [ios.signing] export_method = "app-store" in pythonnative.toml.')
+        sys.exit(1)
+
     try:
-        prepared = builder.prepare(platform)
+        prepared = builder.prepare(platform, release=not debug)
         if platform == "android":
             artifacts = builder.build_android(prepared, debug=debug)
         else:
@@ -378,19 +477,61 @@ def build_project(args: argparse.Namespace) -> None:
                 app_path = builder.build_ios_simulator(prepared)
                 artifacts = builder_mod.BuildArtifacts(paths=[app_path])
             else:
-                artifacts = builder.build_ios_archive(prepared)
+                artifacts = builder.build_ios_archive(prepared, upload=upload)
     except builder_mod.BuildError as exc:
         print(f"Error: {exc}")
         sys.exit(1)
 
+    if upload:
+        print("\nUploaded to App Store Connect. Check the build's status at appstoreconnect.apple.com.")
     if not artifacts.paths:
-        print("Build completed, but no artifacts were found. Check the build output above.")
+        if not upload:
+            print("Build completed, but no artifacts were found. Check the build output above.")
         return
     print("\nBuilt artifacts:")
     for path in artifacts.paths:
         print(f"  {path}")
 
 
+# ======================================================================
+# logs
+# ======================================================================
+
+
+def logs_command(args: argparse.Namespace) -> None:
+    """Stream logs from the running app without rebuilding.
+
+    Args:
+        args: Parsed namespace (``platform``).
+    """
+    platform: str = args.platform
+    if platform == "android":
+        proc = _start_android_log_stream()
+        if proc is None:
+            sys.exit(1)
+        try:
+            proc.wait()
+        except KeyboardInterrupt:
+            print()
+            _terminate_subprocess(proc)
+            print("Stopped log streaming.")
+        return
+
+    # iOS: relaunch the app on the booted simulator with a console PTY so
+    # Python's stdout/stderr stream to this terminal.
+    config = _load_config_or_exit()
+    proc = _start_ios_log_stream(config.bundle_id)
+    if proc is None:
+        print("For a physical device, use Console.app or Xcode > Devices and Simulators.")
+        sys.exit(1)
+    try:
+        proc.wait()
+    except KeyboardInterrupt:
+        print()
+        _terminate_subprocess(proc)
+        print("Stopped log streaming.")
+
+
 # ======================================================================
 # clean
 # ======================================================================
@@ -747,16 +888,35 @@ def _build_parser() -> argparse.ArgumentParser:
     parser_preview.add_argument("--no-hot-reload", action="store_true", help="Disable file watching / Fast Refresh")
     parser_preview.set_defaults(func=preview_project)
 
+    parser_devices = subparsers.add_parser("devices", help="List devices, emulators, and simulators")
+    parser_devices.add_argument("platform", nargs="?", choices=["android", "ios"], help="Restrict to a platform")
+    parser_devices.set_defaults(func=devices_command)
+
     parser_run = subparsers.add_parser("run", help="Build, install, and launch on a device/simulator")
     parser_run.add_argument("platform", choices=["android", "ios"])
+    parser_run.add_argument(
+        "--device",
+        "-d",
+        help="Target device: an identifier or name from 'pn devices' "
+        "(physical iOS devices need [ios].development_team)",
+    )
     parser_run.add_argument("--prepare-only", action="store_true", help="Stage + configure without building")
     parser_run.add_argument("--hot-reload", action="store_true", help="Watch app/ and push updates to the running app")
     parser_run.add_argument("--no-logs", action="store_true", help="Don't stream device logs after launch")
     parser_run.set_defaults(func=run_project)
 
+    parser_logs = subparsers.add_parser("logs", help="Stream logs from the running app")
+    parser_logs.add_argument("platform", choices=["android", "ios"])
+    parser_logs.set_defaults(func=logs_command)
+
     parser_build = subparsers.add_parser("build", help="Build distributable artifacts")
     parser_build.add_argument("platform", choices=["android", "ios"])
     parser_build.add_argument("--debug", action="store_true", help="Build the debug variant instead of release")
+    parser_build.add_argument(
+        "--upload",
+        action="store_true",
+        help='Upload the iOS release build to App Store Connect (needs export_method = "app-store")',
+    )
     parser_build.set_defaults(func=build_project)
 
     parser_app_id = subparsers.add_parser("app-id", help="Print the resolved application/bundle id")

{pythonnative-0.24.0 → pythonnative-0.26.0}/src/pythonnative/components.py

@@ -1732,6 +1732,65 @@ def ErrorBoundary(
     return Element("__ErrorBoundary__", props, list(children), key=key)
 
 
+def Suspense(
+    *children: Element,
+    fallback: Optional[Any] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Show ``fallback`` while descendants wait on async work, then swap in the content.
+
+    A Suspense boundary catches **suspensions** from the subtree it
+    wraps: an ``async def`` component body blocking on a pending
+    await, or a regular component calling
+    [`Resource.read`][pythonnative.suspense.Resource.read] on data that hasn't
+    arrived (see [`use_resource`][pythonnative.use_resource] and
+    [`lazy`][pythonnative.lazy]). While anything is pending the
+    boundary renders ``fallback``; when the awaited work completes it
+    retries the content and swaps it in. Suspended components keep
+    their hook state across retries, so cached resources aren't
+    refetched.
+
+    Two timing behaviors, matching React:
+
+    - **Initial mount**: the fallback shows until the content is ready.
+    - **Updates**: a component that's already on screen and suspends
+      again (its dependencies changed) keeps its previous content
+      visible and re-renders when ready; there's no fallback flash.
+
+    Args:
+        *children: Subtree to wrap (the async content).
+        fallback: Content shown while suspended: an
+            [`Element`][pythonnative.Element] or a zero-arg callable
+            returning one. Without it, suspensions propagate to the
+            next Suspense boundary up.
+        key: Stable identity for keyed reconciliation.
+
+    Returns:
+        An [`Element`][pythonnative.Element] of type ``"__Suspense__"``.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        async def Profile(user_id: str):
+            user = await api.fetch_user(user_id)
+            return pn.Text(user.name)
+
+        @pn.component
+        def Screen():
+            return pn.Suspense(
+                Profile(user_id="42"),
+                fallback=pn.ActivityIndicator(),
+            )
+        ```
+    """
+    props: Dict[str, Any] = {}
+    if fallback is not None:
+        props["__fallback__"] = fallback
+    return Element("__Suspense__", props, list(children), key=key)
+
+
 # ======================================================================
 # Lists (native virtualization with a Python-windowed fallback)
 # ======================================================================

{pythonnative-0.24.0 → pythonnative-0.26.0}/src/pythonnative/diagnostics.py

@@ -37,6 +37,7 @@ __all__ = [
     "is_dev",
     "warn",
     "warn_once",
+    "swallowed",
     "get_warnings",
     "clear_warnings",
     "set_error_reporter",
@@ -143,6 +144,32 @@ def warn_once(message: str, key: Optional[str] = None) -> None:
     warn(message)
 
 
+def swallowed(context: str) -> None:
+    """Surface a suppressed native-backend exception (dev mode only).
+
+    The native view/module backends intentionally degrade gracefully in
+    production: a failed style application or a missing OS API must not
+    crash the app. Call this from the ``except`` block instead of
+    ``pass`` so that, in dev mode, each suppression is reported once per
+    call site instead of disappearing.
+
+    Args:
+        context: Where the suppression happened, e.g.
+            ``"ios.TextHandler._apply"``.
+    """
+    if not is_dev():
+        return
+    exc = sys.exc_info()[1]
+    if exc is None:
+        return
+    frame = sys._getframe(1)
+    location = f"{os.path.basename(frame.f_code.co_filename)}:{frame.f_lineno}"
+    warn_once(
+        f"{context} suppressed {type(exc).__name__}: {exc} ({location})",
+        key=f"swallowed:{context}:{location}",
+    )
+
+
 def get_warnings() -> List[str]:
     """Return a snapshot of the recorded warnings (oldest first)."""
     with _warn_lock: