python-roborock 3.17.0__tar.gz → 3.19.0__tar.gz

{python_roborock-3.17.0 → python_roborock-3.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 3.17.0
+Version: 3.19.0
 Summary: A package to control Roborock vacuums.
 Project-URL: Repository, https://github.com/humbertogontijo/python-roborock
 Project-URL: Documentation, https://python-roborock.readthedocs.io/
@@ -49,11 +49,13 @@ Install this via pip (or your favourite package manager):
 
 `pip install python-roborock`
 
-## Functionality
+## Example Usage
 
-You can see all of the commands supported [here](https://python-roborock.readthedocs.io/en/latest/api_commands.html)
+See [examples/example.py](examples/example.py) for a more full featured example,
+or the [API documentation](https://python-roborock.github.io/python-roborock/)
+for more details.
 
-## Example Usage
+Here is a basic example:
 
 ```python
 import asyncio
@@ -63,28 +65,28 @@ from roborock.devices.device_manager import create_device_manager, UserParams
 
 
 async def main():
-    web_api = RoborockApiClient(username="youremailhere")
-    # Login via your password
-    user_data = await web_api.pass_login(password="pass_here")
-    # Or login via a code
+    email_address = "youremailhere@example.com"
+    web_api = RoborockApiClient(username=email_address)
+    # Send a login code to the above email address
     await web_api.request_code()
+    # Prompt the user to enter the code
     code = input("What is the code?")
     user_data = await web_api.code_login(code)
 
     # Create a device manager that can discover devices.
-    user_params = UserParams(
-        username="youremailhere",
-        user_data=user_data,
-    )
+    user_params = UserParams(username=email_address, user_data=user_data)
     device_manager = await create_device_manager(user_params)
     devices = await device_manager.get_devices()
 
-    # Get all vacuum devices that support the v1 PropertiesApi
+    # Get all vacuum devices. Each device generation has different capabilities
+    # and APIs available so to find vacuums we filter by the v1 PropertiesApi.
     for device in devices:
         if not device.v1_properties:
             continue
 
-        # Refresh the current device status
+        # The PropertiesAPI has traits different device commands such as getting
+        # status, sending clean commands, etc. For this example we send a
+        # command to refresh the current device status.
         status_trait = device.v1_properties.status
         await status_trait.refresh()
         print(status_trait)
@@ -92,9 +94,16 @@ async def main():
 asyncio.run(main())
 ```
 
-See [examples/example.py](examples/example.py) for a more full featured example
-that has performance improvements to cache cloud information to prefer
-connections over the local network.
+
+## Functionality
+
+The library interacts with devices through specific API properties based on the device protocol:
+
+*   **Standard Vacuums (V1 Protocol)**: Most robot vacuums use this. Interaction is done through `device.v1_properties`, which contains traits like `status`, `consumables`, and `maps`. Use the `command` trait for actions like starting or stopping cleaning.
+*   **Wet/Dry Vacuums & Washing Machines (A01 Protocol)**: Devices like the Dyad and Zeo use this. Interaction is done through `device.a01_properties` using `query_values()` and `set_value()`.
+
+You can find detailed documentation for [Devices](https://python-roborock.github.io/python-roborock/roborock/devices/device.html) and [Traits](https://python-roborock.github.io/python-roborock/roborock/devices/traits.html).
+
 
 ## Supported devices
 
@@ -103,6 +112,7 @@ You can find what devices are supported
 Please note this may not immediately contain the latest devices.
 
 
-## Credits
+## Acknowledgements
 
-Thanks @rovo89 for https://gist.github.com/rovo89/dff47ed19fca0dfdda77503e66c2b7c7 And thanks @PiotrMachowski for https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor
+* Thanks to [@rovo89](https://github.com/rovo89) for [Login APIs gist](https://gist.github.com/rovo89/dff47ed19fca0dfdda77503e66c2b7c7).
+* Thanks to [@PiotrMachowski](https://github.com/PiotrMachowski) for [Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor](https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor).

python_roborock-3.19.0/README.md

@@ -0,0 +1,89 @@
+# Roborock
+
+<p align="center">
+  <a href="https://pypi.org/project/python-roborock/">
+    <img src="https://img.shields.io/pypi/v/python-roborock.svg?logo=python&logoColor=fff&style=flat-square" alt="PyPI Version">
+  </a>
+  <img src="https://img.shields.io/pypi/pyversions/python-roborock.svg?style=flat-square&logo=python&amp;logoColor=fff" alt="Supported Python versions">
+  <img src="https://img.shields.io/pypi/l/python-roborock.svg?style=flat-square" alt="License">
+    <a href="https://codecov.io/github/Python-roborock/python-roborock" >
+  <img src="https://codecov.io/github/Python-roborock/python-roborock/graph/badge.svg?token=KEK4S3FPSZ" alt="Code Coverage"/>
+ </a>
+</p>
+
+
+Roborock library for online and offline control of your vacuums.
+
+## Installation
+
+Install this via pip (or your favourite package manager):
+
+`pip install python-roborock`
+
+## Example Usage
+
+See [examples/example.py](examples/example.py) for a more full featured example,
+or the [API documentation](https://python-roborock.github.io/python-roborock/)
+for more details.
+
+Here is a basic example:
+
+```python
+import asyncio
+
+from roborock.web_api import RoborockApiClient
+from roborock.devices.device_manager import create_device_manager, UserParams
+
+
+async def main():
+    email_address = "youremailhere@example.com"
+    web_api = RoborockApiClient(username=email_address)
+    # Send a login code to the above email address
+    await web_api.request_code()
+    # Prompt the user to enter the code
+    code = input("What is the code?")
+    user_data = await web_api.code_login(code)
+
+    # Create a device manager that can discover devices.
+    user_params = UserParams(username=email_address, user_data=user_data)
+    device_manager = await create_device_manager(user_params)
+    devices = await device_manager.get_devices()
+
+    # Get all vacuum devices. Each device generation has different capabilities
+    # and APIs available so to find vacuums we filter by the v1 PropertiesApi.
+    for device in devices:
+        if not device.v1_properties:
+            continue
+
+        # The PropertiesAPI has traits different device commands such as getting
+        # status, sending clean commands, etc. For this example we send a
+        # command to refresh the current device status.
+        status_trait = device.v1_properties.status
+        await status_trait.refresh()
+        print(status_trait)
+
+asyncio.run(main())
+```
+
+
+## Functionality
+
+The library interacts with devices through specific API properties based on the device protocol:
+
+*   **Standard Vacuums (V1 Protocol)**: Most robot vacuums use this. Interaction is done through `device.v1_properties`, which contains traits like `status`, `consumables`, and `maps`. Use the `command` trait for actions like starting or stopping cleaning.
+*   **Wet/Dry Vacuums & Washing Machines (A01 Protocol)**: Devices like the Dyad and Zeo use this. Interaction is done through `device.a01_properties` using `query_values()` and `set_value()`.
+
+You can find detailed documentation for [Devices](https://python-roborock.github.io/python-roborock/roborock/devices/device.html) and [Traits](https://python-roborock.github.io/python-roborock/roborock/devices/traits.html).
+
+
+## Supported devices
+
+You can find what devices are supported
+[here](https://python-roborock.readthedocs.io/en/latest/supported_devices.html).
+Please note this may not immediately contain the latest devices.
+
+
+## Acknowledgements
+
+* Thanks to [@rovo89](https://github.com/rovo89) for [Login APIs gist](https://gist.github.com/rovo89/dff47ed19fca0dfdda77503e66c2b7c7).
+* Thanks to [@PiotrMachowski](https://github.com/PiotrMachowski) for [Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor](https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor).

{python_roborock-3.17.0 → python_roborock-3.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "3.17.0"
+version = "3.19.0"
 description = "A package to control Roborock vacuums."
 authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
 requires-python = ">=3.11, <4"

{python_roborock-3.17.0 → python_roborock-3.19.0}/roborock/data/b01_q7/b01_q7_containers.py

@@ -187,19 +187,19 @@ class B01Props(RoborockBase):
     @property
     def status_name(self) -> str | None:
         """Returns the name of the current status."""
-        return self.status.name if self.status is not None else None
+        return self.status.value if self.status is not None else None
 
     @property
     def fault_name(self) -> str | None:
         """Returns the name of the current fault."""
-        return self.fault.name if self.fault is not None else None
+        return self.fault.value if self.fault is not None else None
 
     @property
     def wind_name(self) -> str | None:
         """Returns the name of the current fan speed (wind)."""
-        return self.wind.name if self.wind is not None else None
+        return self.wind.value if self.wind is not None else None
 
     @property
     def work_mode_name(self) -> str | None:
         """Returns the name of the current work mode."""
-        return self.work_mode.name if self.work_mode is not None else None
+        return self.work_mode.value if self.work_mode is not None else None

{python_roborock-3.17.0 → python_roborock-3.19.0}/roborock/data/code_mappings.py

@@ -72,8 +72,8 @@ class RoborockModeEnum(StrEnum):
 
     @classmethod
     def keys(cls) -> list[str]:
-        """Returns a list of all member names."""
-        return [member.name for member in cls]
+        """Returns a list of all member values."""
+        return [member.value for member in cls]
 
 
 ProductInfo = namedtuple("ProductInfo", ["nickname", "short_models"])

{python_roborock-3.17.0 → python_roborock-3.19.0}/roborock/data/v1/v1_containers.py

@@ -585,7 +585,7 @@ class AppInitStatus(RoborockBase):
     local_info: AppInitStatusLocalInfo
     feature_info: list[int]
     new_feature_info: int
-    new_feature_info_str: str
+    new_feature_info_str: str = ""
     new_feature_info_2: int | None = None
     carriage_type: int | None = None
     dsp_version: str | None = None

{python_roborock-3.17.0 → python_roborock-3.19.0}/roborock/devices/README.md

@@ -4,7 +4,19 @@ The devices module provides functionality to discover Roborock devices on the
 network. This section documents the full lifecycle of device discovery across
 Cloud and Network.
 
-## Quick Start: Understanding Device Protocols
+## Usage TL;DR
+
+*   **Discovery**: Use `roborock.devices.device_manager.DeviceManager` to get device instances.
+    *   Call `create_device_manager(user_params)` then `await device_manager.get_devices()`.
+*   **Control**:
+    *   **Vacuums (V1)**: Use `device.v1_properties` to access traits like `status` or `consumables`.
+        *   Call `await trait.refresh()` to update state.
+        *   Use `device.v1_properties.command.send()` for raw commands (start/stop).
+    *   **Washers (A01)**: Use `device.a01_properties` for Dyad/Zeo devices.
+        *   Use `await device.a01_properties.query_values([...])` to get state.
+        *   Use `await device.a01_properties.set_value(protocol, value)` to control.
+
+## Background: Understanding Device Protocols
 
 **The library supports three device protocol versions, each with different capabilities:**
 
@@ -18,7 +30,7 @@ Cloud and Network.
 
 **Key Point:** The `DeviceManager` automatically detects the protocol version and creates the appropriate channel type. You don't need to handle this manually.
 
-## Architecture Overview
+## Internal Architecture
 
 The library is organized into distinct layers, each with a specific responsibility. **Different device protocols use different channel implementations:**
 
@@ -138,7 +150,7 @@ graph TB
 | **A01** (`pv=A01`) | `MqttChannel` + helpers | ❌ No | Direct MQTT | Dyad, Zeo washers |
 | **B01** (`pv=B01`) | `MqttChannel` + helpers | ❌ No | Direct MQTT | Some newer models |
 
-## Init account setup
+## Account Setup Internals
 
 ### Login
 
@@ -151,7 +163,7 @@ graph TB
   - This contains information used to connect to MQTT
   - You get an `-eu` suffix in the API URLs if you are in the eu and `-us` if you are in the us
 
-## Home Data
+## Home Data Internals
 
 The `HomeData` includes information about the various devices in the home. We use `v3`
 and it is notable that if devices don't show up in the `home_data` response it is likely
@@ -174,7 +186,7 @@ that a newer version of the API should be used.
   - There is another REST request `get_rooms` that will do the same thing.
   - Note: If we cache home_data, we likely need to use `get_rooms` to get rooms fresh
 
-## Device Connections
+## Connection Implementation
 
 ### Connection Flow by Protocol
 
@@ -343,7 +355,7 @@ graph LR
 3. **Timeout Handling**: Commands timeout after 10 seconds if no response is received
 4. **Multiple Strategies**: `V1Channel` tries local first, then falls back to MQTT if local fails
 
-## Design
+## Class Design & Components
 
 ### Current Architecture
 

{python_roborock-3.17.0 → python_roborock-3.19.0}/roborock/devices/device_manager.py

@@ -3,8 +3,9 @@
 import asyncio
 import enum
 import logging
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass
+from typing import Any
 
 import aiohttp
 
@@ -15,6 +16,8 @@ from roborock.data import (
     UserData,
 )
 from roborock.devices.device import DeviceReadyCallback, RoborockDevice
+from roborock.diagnostics import Diagnostics
+from roborock.exceptions import RoborockException
 from roborock.map.map_parser import MapParserConfig
 from roborock.mqtt.roborock_session import create_lazy_mqtt_session
 from roborock.mqtt.session import MqttSession
@@ -57,6 +60,7 @@ class DeviceManager:
         device_creator: DeviceCreator,
         mqtt_session: MqttSession,
         cache: Cache,
+        diagnostics: Diagnostics,
     ) -> None:
         """Initialize the DeviceManager with user data and optional cache storage.
 
@@ -67,13 +71,21 @@ class DeviceManager:
         self._device_creator = device_creator
         self._devices: dict[str, RoborockDevice] = {}
         self._mqtt_session = mqtt_session
+        self._diagnostics = diagnostics
 
-    async def discover_devices(self) -> list[RoborockDevice]:
+    async def discover_devices(self, prefer_cache: bool = True) -> list[RoborockDevice]:
         """Discover all devices for the logged-in user."""
+        self._diagnostics.increment("discover_devices")
         cache_data = await self._cache.get()
-        if not cache_data.home_data:
-            _LOGGER.debug("No cached home data found, fetching from API")
-            cache_data.home_data = await self._web_api.get_home_data()
+        if not cache_data.home_data or not prefer_cache:
+            _LOGGER.debug("Fetching home data (prefer_cache=%s)", prefer_cache)
+            self._diagnostics.increment("fetch_home_data")
+            try:
+                cache_data.home_data = await self._web_api.get_home_data()
+            except RoborockException as ex:
+                if not cache_data.home_data:
+                    raise
+                _LOGGER.debug("Failed to fetch home data, using cached data: %s", ex)
             await self._cache.set(cache_data)
         home_data = cache_data.home_data
 
@@ -110,6 +122,10 @@ class DeviceManager:
         tasks.append(self._mqtt_session.close())
         await asyncio.gather(*tasks)
 
+    def diagnostic_data(self) -> Mapping[str, Any]:
+        """Return diagnostics information about the device manager."""
+        return self._diagnostics.as_dict()
+
 
 @dataclass
 class UserParams:
@@ -176,7 +192,10 @@ async def create_device_manager(
     web_api = create_web_api_wrapper(user_params, session=session, cache=cache)
     user_data = user_params.user_data
 
+    diagnostics = Diagnostics()
+
     mqtt_params = create_mqtt_params(user_data.rriot)
+    mqtt_params.diagnostics = diagnostics.subkey("mqtt_session")
     mqtt_session = await create_lazy_mqtt_session(mqtt_params)
 
     def device_creator(home_data: HomeData, device: HomeDataDevice, product: HomeDataProduct) -> RoborockDevice:
@@ -220,6 +239,6 @@ async def create_device_manager(
             dev.add_ready_callback(ready_callback)
         return dev
 
-    manager = DeviceManager(web_api, device_creator, mqtt_session=mqtt_session, cache=cache)
+    manager = DeviceManager(web_api, device_creator, mqtt_session=mqtt_session, cache=cache, diagnostics=diagnostics)
     await manager.discover_devices()
     return manager

python_roborock-3.19.0/roborock/devices/traits/__init__.py

@@ -0,0 +1,28 @@
+"""Module for device traits.
+
+This package contains the trait definitions for different device protocols supported
+by Roborock devices.
+
+Submodules
+----------
+*   `v1`: Contains traits for standard Roborock vacuums (e.g., S-series, Q-series).
+    These devices use the V1 protocol and have rich feature sets split into
+    granular traits (e.g., `StatusTrait`, `ConsumableTrait`).
+*   `a01`: Contains APIs for A01 protocol devices, such as the Dyad (wet/dry vacuum)
+    and Zeo (washing machine). These devices use a different communication structure.
+*   `b01`: Contains APIs for B01 protocol devices.
+"""
+
+from abc import ABC
+
+__all__ = [
+    "Trait",
+    "traits_mixin",
+    "v1",
+    "a01",
+    "b01",
+]
+
+
+class Trait(ABC):
+    """Base class for all traits."""

{python_roborock-3.17.0 → python_roborock-3.19.0}/roborock/devices/traits/a01/__init__.py

@@ -1,3 +1,24 @@
+"""Create traits for A01 devices.
+
+This module provides the API implementations for A01 protocol devices, which include
+Dyad (Wet/Dry Vacuums) and Zeo (Washing Machines).
+
+Using A01 APIs
+--------------
+A01 devices expose a single API object that handles all device interactions. This API is
+available on the device instance (typically via `device.a01_properties`).
+
+The API provides two main methods:
+1.  **query_values(protocols)**: Fetches current state for specific data points.
+    You must pass a list of protocol enums (e.g. `RoborockDyadDataProtocol` or
+    `RoborockZeoProtocol`) to request specific data.
+2.  **set_value(protocol, value)**: Sends a command to the device to change a setting
+    or perform an action.
+
+Note that these APIs fetch data directly from the device upon request and do not
+cache state internally.
+"""
+
 import json
 from collections.abc import Callable
 from datetime import time

{python_roborock-3.17.0 → python_roborock-3.19.0}/roborock/devices/traits/v1/__init__.py

@@ -2,17 +2,33 @@
 
 Traits are modular components that encapsulate specific features of a Roborock
 device. This module provides a factory function to create and initialize the
-appropriate traits for V1 devices based on their capabilities. They can also
-be considered groups of commands and parsing logic for that command.
-
-Traits have a `refresh()` method that can be called to update their state
-from the device. Some traits may also provide additional methods for modifying
-the device state.
-
-The most common pattern for a trait is to subclass `V1TraitMixin` and a `RoborockBase`
-dataclass, and define a `command` class variable that specifies the `RoborockCommand`
-used to fetch the trait data from the device. See `common.py` for more details
-on common patterns used across traits.
+appropriate traits for V1 devices based on their capabilities.
+
+Using Traits
+------------
+Traits are accessed via the `v1_properties` attribute on a device. Each trait
+represents a specific capability, such as `status`, `consumables`, or `rooms`.
+
+Traits serve two main purposes:
+1.  **State**: Traits are dataclasses that hold the current state of the device
+    feature. You can access attributes directly (e.g., `device.v1_properties.status.battery`).
+2.  **Commands**: Traits provide methods to control the device. For example,
+    `device.v1_properties.volume.set_volume()`.
+
+Additionally, the `command` trait provides a generic way to send any command to the
+device (e.g. `device.v1_properties.command.send("app_start")`). This is often used
+for basic cleaning operations like starting, stopping, or docking the vacuum.
+
+Most traits have a `refresh()` method that must be called to update their state
+from the device. The state is not updated automatically in real-time unless
+specifically implemented by the trait or via polling.
+
+Adding New Traits
+-----------------
+When adding a new trait, the most common pattern is to subclass `V1TraitMixin`
+and a `RoborockBase` dataclass. You must define a `command` class variable that
+specifies the `RoborockCommand` used to fetch the trait data from the device.
+See `common.py` for more details on common patterns used across traits.
 
 There are some additional decorators in `common.py` that can be used to specify which
 RPC channel to use for the trait (standard, MQTT/cloud, or map-specific).
@@ -43,6 +59,29 @@ from roborock.map.map_parser import MapParserConfig
 from roborock.protocols.v1_protocol import V1RpcChannel
 from roborock.web_api import UserWebApiClient
 
+from . import (
+    child_lock,
+    clean_summary,
+    command,
+    common,
+    consumeable,
+    device_features,
+    do_not_disturb,
+    dust_collection_mode,
+    flow_led_status,
+    home,
+    led_status,
+    map_content,
+    maps,
+    network_info,
+    rooms,
+    routines,
+    smart_wash_params,
+    status,
+    valley_electricity_timer,
+    volume,
+    wash_towel_mode,
+)
 from .child_lock import ChildLockTrait
 from .clean_summary import CleanSummaryTrait
 from .command import CommandTrait
@@ -71,6 +110,7 @@ __all__ = [
     "PropertiesApi",
     "child_lock",
     "clean_summary",
+    "command",
     "common",
     "consumeable",
     "device_features",

{python_roborock-3.17.0 → python_roborock-3.19.0}/roborock/devices/traits/v1/command.py

@@ -5,7 +5,17 @@ from roborock.protocols.v1_protocol import ParamsType
 
 
 class CommandTrait:
-    """Trait for sending commands to Roborock devices."""
+    """Trait for sending commands to Roborock devices.
+
+    This trait allows sending raw commands directly to the device. It is particularly
+    useful for:
+    1.  **Cleaning Control**: Sending commands like `app_start`, `app_stop`, `app_pause`,
+        or `app_charge` which don't belong to a specific state trait.
+    2.  **Unsupported Features**: Accessing device functionality that hasn't been
+        mapped to a specific trait yet.
+
+    See `roborock.roborock_typing.RoborockCommand` for a list of available commands.
+    """
 
     def __post_init__(self) -> None:
         """Post-initialization to set up the RPC channel.

python_roborock-3.19.0/roborock/diagnostics.py

@@ -0,0 +1,84 @@
+"""Diagnostics for debugging.
+
+A Diagnostics object can be used to track counts and latencies of various
+operations within a module. This can be useful for debugging performance issues
+or understanding usage patterns.
+
+This is an internal facing module and is not intended for public use. Diagnostics
+data is collected and exposed to clients via higher level APIs like the
+DeviceManager.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import Counter
+from collections.abc import Generator, Mapping
+from contextlib import contextmanager
+from typing import Any
+
+
+class Diagnostics:
+    """A class that holds diagnostics information for a module.
+
+    You can use this class to hold counter or for recording timing information
+    that can be exported as a dictionary for debugging purposes.
+    """
+
+    def __init__(self) -> None:
+        """Initialize Diagnostics."""
+        self._counter: Counter = Counter()
+        self._subkeys: dict[str, Diagnostics] = {}
+
+    def increment(self, key: str, count: int = 1) -> None:
+        """Increment a counter for the specified key/event."""
+        self._counter.update(Counter({key: count}))
+
+    def elapsed(self, key_prefix: str, elapsed_ms: int = 1) -> None:
+        """Track a latency event for the specified key/event prefix."""
+        self.increment(f"{key_prefix}_count", 1)
+        self.increment(f"{key_prefix}_sum", elapsed_ms)
+
+    def as_dict(self) -> Mapping[str, Any]:
+        """Return diagnostics as a debug dictionary."""
+        data: dict[str, Any] = {k: self._counter[k] for k in self._counter}
+        for k, d in self._subkeys.items():
+            v = d.as_dict()
+            if not v:
+                continue
+            data[k] = v
+        return data
+
+    def subkey(self, key: str) -> Diagnostics:
+        """Return sub-Diagnostics object with the specified subkey.
+
+        This will create a new Diagnostics object if one does not already exist
+        for the specified subkey. Stats from the sub-Diagnostics will be included
+        in the parent Diagnostics when exported as a dictionary.
+
+        Args:
+            key: The subkey for the diagnostics.
+
+        Returns:
+            The Diagnostics object for the specified subkey.
+        """
+        if key not in self._subkeys:
+            self._subkeys[key] = Diagnostics()
+        return self._subkeys[key]
+
+    @contextmanager
+    def timer(self, key_prefix: str) -> Generator[None, None, None]:
+        """A context manager that records the timing of operations as a diagnostic."""
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            end = time.perf_counter()
+            ms = int((end - start) * 1000)
+            self.elapsed(key_prefix, ms)
+
+    def reset(self) -> None:
+        """Clear all diagnostics, for testing."""
+        self._counter = Counter()
+        for d in self._subkeys.values():
+            d.reset()