shorthand-client 0.1.0__tar.gz

shorthand_client-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: shorthand-client
+Version: 0.1.0
+Summary: Async client for the Shorthand server, used by the Home Assistant integration
+License-Expression: MIT
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Dist: aiohttp>=3.14
+Requires-Python: >=3.14.2
+Project-URL: Source, https://github.com/JoshuaLoran/ha-shorthand
+Description-Content-Type: text/markdown
+
+# shorthand-client
+
+The async Python client for the [Shorthand](https://github.com/JoshuaLoran/ha-shorthand) server. The Home Assistant integration uses it to talk to the server. You don't need to install it yourself.

shorthand_client-0.1.0/README.md

@@ -0,0 +1,3 @@
+# shorthand-client
+
+The async Python client for the [Shorthand](https://github.com/JoshuaLoran/ha-shorthand) server. The Home Assistant integration uses it to talk to the server. You don't need to install it yourself.

shorthand_client-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "shorthand-client"
+version = "0.1.0"
+description = "Async client for the Shorthand server, used by the Home Assistant integration"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14.2"
+dependencies = ["aiohttp>=3.14"]
+classifiers = [
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Source = "https://github.com/JoshuaLoran/ha-shorthand"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"

shorthand_client-0.1.0/pyproject.toml.orig

@@ -0,0 +1,16 @@
+[project]
+name = "shorthand-client"
+version = "0.1.0"
+description = "Async client for the Shorthand server, used by the Home Assistant integration"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14.2"
+dependencies = ["aiohttp>=3.14"]
+classifiers = ["Framework :: AsyncIO", "Typing :: Typed"]
+
+[project.urls]
+Source = "https://github.com/JoshuaLoran/ha-shorthand"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"

shorthand_client-0.1.0/src/shorthand_client/__init__.py

@@ -0,0 +1,7 @@
+"""Async client for the Shorthand server (01 §9, D19)."""
+
+from . import models
+from .client import ShorthandClient
+from .models import VERSION as PROTOCOL_VERSION
+
+__all__ = ["PROTOCOL_VERSION", "ShorthandClient", "models"]

shorthand_client-0.1.0/src/shorthand_client/client.py

@@ -0,0 +1,216 @@
+"""The client (01 §9, D19): one WebSocket to the server.
+
+The integration opens it. Requests are matched to replies by id; anything
+the server starts (`learn_request`, `sync_request`) goes to `on_message`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import itertools
+import logging
+from collections.abc import Awaitable, Callable
+
+import aiohttp
+
+from . import models
+from .errors import (
+    AuthenticationError,
+    CannotConnectError,
+    ProtocolError,
+    RequestTimeoutError,
+    ServerError,
+    ShorthandError,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+type MessageHandler = Callable[[models.Envelope], Awaitable[None]]
+type ConnectHandler = Callable[[models.Welcome], Awaitable[None]]
+
+
+class ShorthandClient:
+    """A connection to one Shorthand server.
+
+    The aiohttp session is the caller's (Home Assistant's) and is never
+    closed here.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        session: aiohttp.ClientSession,
+        *,
+        client_name: str,
+        ha_version: str,
+        on_message: MessageHandler | None = None,
+        request_timeout: float = 10.0,
+        backoff: tuple[float, float] = (1.0, 30.0),
+    ) -> None:
+        """Set up a client for the server at `url` (its `/ws` endpoint)."""
+        self._url = url
+        self._session = session
+        self._client_name = client_name
+        self._ha_version = ha_version
+        self._on_message = on_message
+        self._timeout = request_timeout
+        self._backoff = backoff
+        self._ws: aiohttp.ClientWebSocketResponse | None = None
+        self._reader: asyncio.Task[None] | None = None
+        self._pending: dict[str, asyncio.Future[models.Envelope]] = {}
+        self._ids = itertools.count(1)
+        self._closing = False
+
+    @property
+    def connected(self) -> bool:
+        """Whether the connection is open and welcomed."""
+        return self._ws is not None and not self._ws.closed
+
+    async def connect(self, auth: models.Auth) -> models.Welcome:
+        """Open the connection and say hello; the welcome says who answered."""
+        try:
+            ws = await self._session.ws_connect(self._url, heartbeat=30)
+        except (aiohttp.ClientError, OSError) as err:
+            raise CannotConnectError(str(err)) from err
+        hello = models.Envelope(
+            id=self._next_id(),
+            body=models.Hello(
+                client=self._client_name, ha_version=self._ha_version, auth=auth
+            ),
+        )
+        try:
+            await ws.send_str(hello.to_json())
+            msg = await asyncio.wait_for(ws.receive(), self._timeout)
+        except TimeoutError as err:
+            await ws.close()
+            raise RequestTimeoutError("no answer to hello") from err
+        if msg.type is not aiohttp.WSMsgType.TEXT:
+            await ws.close()
+            raise CannotConnectError("the server closed the connection")
+        reply = models.parse(msg.data)
+        if isinstance(reply.body, models.ErrorReply):
+            await ws.close()
+            raise AuthenticationError(reply.body.message)
+        if not isinstance(reply.body, models.Welcome):
+            await ws.close()
+            raise CannotConnectError(f"expected welcome, got {reply.body.TYPE}")
+        self._ws = ws
+        self._reader = asyncio.create_task(self._read(ws))
+        return reply.body
+
+    async def request(self, body: models.Message) -> models.Message:
+        """Send a request and wait for the reply with its id."""
+        ws = self._require()
+        env = models.Envelope(id=self._next_id(), body=body)
+        future: asyncio.Future[models.Envelope] = (
+            asyncio.get_running_loop().create_future()
+        )
+        self._pending[env.id] = future
+        try:
+            await ws.send_str(env.to_json())
+            reply = await asyncio.wait_for(future, self._timeout)
+        except TimeoutError as err:
+            raise RequestTimeoutError(f"no answer to {body.TYPE}") from err
+        finally:
+            self._pending.pop(env.id, None)
+        if isinstance(reply.body, models.ErrorReply):
+            raise ServerError(reply.body.code, reply.body.message)
+        return reply.body
+
+    async def send(self, body: models.Message, *, reply_to: str | None = None) -> None:
+        """Send a message that needs no reply (a push, or an answer)."""
+        ws = self._require()
+        env = models.Envelope(id=reply_to or self._next_id(), body=body)
+        await ws.send_str(env.to_json())
+
+    async def ping(self) -> None:
+        """Check the server answers."""
+        reply = await self.request(models.Ping())
+        if not isinstance(reply, models.Pong):
+            raise CannotConnectError(f"expected pong, got {reply.TYPE}")
+
+    async def decide(self, decide: models.Decide) -> models.Decision:
+        """Ask what to do with these words."""
+        reply = await self.request(decide)
+        if not isinstance(reply, models.Decision):
+            raise CannotConnectError(f"expected decision, got {reply.TYPE}")
+        return reply
+
+    async def run_forever(
+        self,
+        auth: models.Auth,
+        *,
+        on_connect: ConnectHandler | None = None,
+        on_disconnect: Callable[[], Awaitable[None]] | None = None,
+    ) -> None:
+        """Stay connected until `close()`, reconnecting with backoff."""
+        first, most = self._backoff
+        delay = first
+        while not self._stopping():
+            try:
+                welcome = await self.connect(auth)
+            except AuthenticationError:
+                raise
+            except ShorthandError as err:
+                _LOGGER.debug("Can't reach the Shorthand server: %s", err)
+            else:
+                delay = first
+                if on_connect is not None:
+                    await on_connect(welcome)
+                if self._reader is not None:
+                    with contextlib.suppress(asyncio.CancelledError):
+                        await self._reader
+                if on_disconnect is not None and not self._stopping():
+                    await on_disconnect()
+            if self._stopping():
+                break
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, most)
+
+    async def close(self) -> None:
+        """Close the connection; `run_forever` returns."""
+        self._closing = True
+        if self._ws is not None:
+            await self._ws.close()
+        if self._reader is not None:
+            self._reader.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._reader
+
+    async def _read(self, ws: aiohttp.ClientWebSocketResponse) -> None:
+        try:
+            async for msg in ws:
+                if msg.type is not aiohttp.WSMsgType.TEXT:
+                    continue
+                try:
+                    env = models.parse(msg.data)
+                except ProtocolError as err:
+                    _LOGGER.warning("Ignoring a message from the server: %s", err)
+                    continue
+                future = self._pending.get(env.id)
+                if future is not None and not future.done():
+                    future.set_result(env)
+                elif self._on_message is not None:
+                    await self._on_message(env)
+        finally:
+            self._ws = None
+            lost = CannotConnectError("the connection to the server was lost")
+            for future in self._pending.values():
+                if not future.done():
+                    future.set_exception(lost)
+
+    def _stopping(self) -> bool:
+        # A method, so type checkers don't assume it can't change across an await.
+        return self._closing
+
+    def _require(self) -> aiohttp.ClientWebSocketResponse:
+        if self._ws is None or self._ws.closed:
+            raise CannotConnectError("not connected")
+        return self._ws
+
+    def _next_id(self) -> str:
+        return str(next(self._ids))
+
+
+__all__ = ["ShorthandClient"]

shorthand_client-0.1.0/src/shorthand_client/errors.py

@@ -0,0 +1,55 @@
+"""What can go wrong talking to the Shorthand server."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import ErrorCode
+
+
+class ShorthandError(Exception):
+    """Anything this library raises."""
+
+
+class ProtocolError(ShorthandError):
+    """Text that isn't a message this version can use."""
+
+
+class VersionMismatchError(ProtocolError):
+    """The peer speaks another protocol version."""
+
+    def __init__(self, got: int) -> None:
+        """Record the version the peer spoke."""
+        super().__init__(f"protocol version {got} isn't supported")
+        self.got = got
+
+
+class UnknownMessageTypeError(ProtocolError):
+    """A message type this version doesn't know."""
+
+
+class MalformedMessageError(ProtocolError):
+    """Not JSON, not an object, or a field that's missing or wrong."""
+
+
+class CannotConnectError(ShorthandError):
+    """The server couldn't be reached, or the connection was lost."""
+
+
+class AuthenticationError(ShorthandError):
+    """The server refused the pairing code or key."""
+
+
+class RequestTimeoutError(ShorthandError):
+    """The server didn't answer a request in time."""
+
+
+class ServerError(ShorthandError):
+    """The server answered a request with an error."""
+
+    def __init__(self, code: ErrorCode, message: str) -> None:
+        """Record the server's error code and message."""
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message

shorthand_client-0.1.0/src/shorthand_client/models.py

@@ -0,0 +1,454 @@
+"""The protocol's messages (07 §2), mirroring `shorthand-protocol` in Rust.
+
+The Rust crate's fixtures are the contract: every one must parse into these
+types and serialize back to the same JSON (`tests/test_contract.py`).
+"""
+
+from __future__ import annotations
+
+import enum
+import json
+import types
+from dataclasses import MISSING, dataclass, field, fields, is_dataclass
+from typing import Any, ClassVar, Union, get_args, get_origin, get_type_hints
+
+from .errors import (
+    MalformedMessageError,
+    UnknownMessageTypeError,
+    VersionMismatchError,
+)
+
+VERSION = 1
+"""The protocol version this library speaks."""
+
+
+class CheckResult(enum.StrEnum):
+    """Whether the house showed what a call should have done (03 §5)."""
+
+    VERIFIED = "verified"
+    MISMATCH = "mismatch"
+    UNCONFIRMED = "unconfirmed"
+    DEVICE_TROUBLE = "device_trouble"
+
+
+class ErrorCode(enum.StrEnum):
+    """Why a request couldn't be done."""
+
+    UNAUTHORIZED = "unauthorized"
+    BAD_MESSAGE = "bad_message"
+    INTERNAL = "internal"
+
+
+# Tagged variants: `TAG_KEY` names the field that says which one.
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Pair:
+    """The first time: the code the server shows."""
+
+    TAG_KEY: ClassVar[str] = "method"
+    TAG: ClassVar[str] = "pair"
+    code: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Key:
+    """Every time after: the key the server gave back."""
+
+    TAG_KEY: ClassVar[str] = "method"
+    TAG: ClassVar[str] = "key"
+    key: str
+
+
+type Auth = Pair | Key
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ServiceCall:
+    """One service call, as captured or to run (01 §5)."""
+
+    service: str
+    entity_ids: list[str] = field(default_factory=list)
+    data: Any = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Run:
+    """Run a learned command."""
+
+    TAG_KEY: ClassVar[str] = "decision"
+    TAG: ClassVar[str] = "run"
+    command: int
+    calls: list[ServiceCall]
+    why: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Pass:
+    """Pass the words to the brain."""
+
+    TAG_KEY: ClassVar[str] = "decision"
+    TAG: ClassVar[str] = "pass"
+    why: str
+
+
+type Verdict = Run | Pass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Floor:
+    """A floor, with its aliases."""
+
+    id: str
+    name: str
+    aliases: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Area:
+    """An area, with its aliases and floor."""
+
+    id: str
+    name: str
+    aliases: list[str] = field(default_factory=list)
+    floor: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Entity:
+    """An entity exposed to Assist."""
+
+    id: str
+    name: str
+    aliases: list[str] = field(default_factory=list)
+    domain: str
+    device_class: str | None = None
+    area: str | None = None
+    sensitive: bool = False
+    state: str
+    attributes: Any = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Media:
+    """Something to play, from Music Assistant's library."""
+
+    uri: str
+    name: str
+    kind: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Home:
+    """The house as Shorthand sees it (04 §1)."""
+
+    floors: list[Floor] = field(default_factory=list)
+    areas: list[Area] = field(default_factory=list)
+    entities: list[Entity] = field(default_factory=list)
+    media: list[Media] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class State:
+    """One entity's state, as it is now or was then."""
+
+    entity_id: str
+    state: str
+    attributes: Any = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Check:
+    """One call's check (03 §5)."""
+
+    call: int
+    result: CheckResult
+    detail: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TurnRecord:
+    """What the brain did in one turn (03 §2)."""
+
+    words: str
+    conversation_id: str | None = None
+    here: str | None = None
+    focus_before: list[str] = field(default_factory=list)
+    calls: list[ServiceCall] = field(default_factory=list)
+    before: list[State] = field(default_factory=list)
+    checks: list[Check] = field(default_factory=list)
+    tools: Any = None
+    reply: str
+
+
+# Messages: `TYPE` is the envelope's "type".
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Hello:
+    """Integration → server: who's connecting, and how it proves it."""
+
+    TYPE: ClassVar[str] = "hello"
+    client: str
+    ha_version: str
+    auth: Auth
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Welcome:
+    """Server → integration: accepted; the key only when pairing."""
+
+    TYPE: ClassVar[str] = "welcome"
+    server: str
+    server_id: str
+    key: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Ping:
+    """Are you there?"""
+
+    TYPE: ClassVar[str] = "ping"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Pong:
+    """Yes."""
+
+    TYPE: ClassVar[str] = "pong"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Snapshot:
+    """The whole house, on connecting and when asked."""
+
+    TYPE: ClassVar[str] = "snapshot"
+    home: Home
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class States:
+    """State changes of exposed entities."""
+
+    TYPE: ClassVar[str] = "states"
+    changes: list[State]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Decide:
+    """What to do with these words."""
+
+    TYPE: ClassVar[str] = "decide"
+    words: str
+    conversation_id: str | None = None
+    here: str | None = None
+    focus: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Decision:
+    """The answer to a decide."""
+
+    TYPE: ClassVar[str] = "decision"
+    verdict: Verdict
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Turn:
+    """What the brain did in a turn."""
+
+    TYPE: ClassVar[str] = "turn"
+    record: TurnRecord
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Outcome:
+    """How a learned command's run went."""
+
+    TYPE: ClassVar[str] = "outcome"
+    command: int
+    checks: list[Check] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LearnRequest:
+    """Server → integration: run this AI Task."""
+
+    TYPE: ClassVar[str] = "learn_request"
+    task: str
+    instructions: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LearnResult:
+    """Integration → server: the AI Task's result."""
+
+    TYPE: ClassVar[str] = "learn_result"
+    data: Any = None
+    error: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SyncRequest:
+    """Server → integration: send a full snapshot."""
+
+    TYPE: ClassVar[str] = "sync_request"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ErrorReply:
+    """A request couldn't be done."""
+
+    TYPE: ClassVar[str] = "error"
+    code: ErrorCode
+    message: str
+
+
+type Message = (
+    Hello
+    | Welcome
+    | Ping
+    | Pong
+    | Snapshot
+    | States
+    | Decide
+    | Decision
+    | Turn
+    | Outcome
+    | LearnRequest
+    | LearnResult
+    | SyncRequest
+    | ErrorReply
+)
+
+MESSAGE_TYPES: dict[str, type[Any]] = {
+    cls.TYPE: cls
+    for cls in (
+        Hello,
+        Welcome,
+        Ping,
+        Pong,
+        Snapshot,
+        States,
+        Decide,
+        Decision,
+        Turn,
+        Outcome,
+        LearnRequest,
+        LearnResult,
+        SyncRequest,
+        ErrorReply,
+    )
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Envelope:
+    """A message with its version and id."""
+
+    id: str
+    body: Message
+    v: int = VERSION
+
+    def to_json(self) -> str:
+        """The message as one JSON object, as the server expects it."""
+        return json.dumps(
+            {"v": self.v, "id": self.id, "type": self.body.TYPE, **_to_dict(self.body)}
+        )
+
+
+def parse(text: str) -> Envelope:
+    """Read a message: the version first, then the type, then its fields."""
+    try:
+        raw = json.loads(text)
+    except ValueError as err:
+        raise MalformedMessageError(str(err)) from err
+    if not isinstance(raw, dict):
+        raise MalformedMessageError("not an object")
+    v = raw.pop("v", None)
+    if not isinstance(v, int) or isinstance(v, bool):
+        raise MalformedMessageError("no version")
+    if v != VERSION:
+        raise VersionMismatchError(v)
+    msg_id = raw.pop("id", None)
+    if not isinstance(msg_id, str):
+        raise MalformedMessageError("no id")
+    kind = raw.pop("type", None)
+    if not isinstance(kind, str):
+        raise MalformedMessageError("no type")
+    cls = MESSAGE_TYPES.get(kind)
+    if cls is None:
+        raise UnknownMessageTypeError(f"unknown message type {kind!r}")
+    return Envelope(id=msg_id, body=_from_dict(cls, raw, kind))
+
+
+# A small typed converter between these dataclasses and JSON values.
+
+
+def _to_dict(obj: Any) -> dict[str, Any]:
+    out = {f.name: _to_json(getattr(obj, f.name)) for f in fields(obj)}
+    if tag_key := getattr(type(obj), "TAG_KEY", None):
+        out[tag_key] = type(obj).TAG
+    return out
+
+
+def _to_json(value: Any) -> Any:
+    if is_dataclass(value) and not isinstance(value, type):
+        return _to_dict(value)
+    if isinstance(value, list):
+        return [_to_json(v) for v in value]
+    if isinstance(value, enum.Enum):
+        return value.value
+    return value
+
+
+def _from_dict(cls: type[Any], raw: Any, where: str) -> Any:
+    if not isinstance(raw, dict):
+        raise MalformedMessageError(f"{where}: expected an object")
+    hints = get_type_hints(cls)
+    kwargs: dict[str, Any] = {}
+    for f in fields(cls):
+        if f.name in raw:
+            kwargs[f.name] = _convert(hints[f.name], raw[f.name], f"{where}.{f.name}")
+        elif f.default is MISSING and f.default_factory is MISSING:
+            raise MalformedMessageError(f"{where}: missing {f.name}")
+    return cls(**kwargs)
+
+
+def _convert(tp: Any, value: Any, where: str) -> Any:  # noqa: PLR0911, PLR0912
+    # One branch per kind of type; splitting it would hide the whole picture.
+    tp = getattr(tp, "__value__", tp)  # a `type X = …` alias
+    origin = get_origin(tp)
+    if tp is Any:
+        return value
+    if origin in (Union, types.UnionType):
+        options = [a for a in get_args(tp) if a is not type(None)]
+        if value is None and len(options) < len(get_args(tp)):
+            return None
+        tagged = [o for o in options if hasattr(o, "TAG_KEY")]
+        if tagged:
+            tag = value.get(tagged[0].TAG_KEY) if isinstance(value, dict) else None
+            for o in tagged:
+                if tag == o.TAG:
+                    return _from_dict(o, value, where)
+            raise MalformedMessageError(f"{where}: unknown variant {tag!r}")
+        return _convert(options[0], value, where)
+    if origin is list:
+        if not isinstance(value, list):
+            raise MalformedMessageError(f"{where}: expected a list")
+        (item,) = get_args(tp)
+        return [_convert(item, v, f"{where}[{i}]") for i, v in enumerate(value)]
+    if isinstance(tp, type) and is_dataclass(tp):
+        return _from_dict(tp, value, where)
+    if isinstance(tp, type) and issubclass(tp, enum.Enum):
+        try:
+            return tp(value)
+        except ValueError as err:
+            raise MalformedMessageError(
+                f"{where}: {value!r} isn't a {tp.__name__}"
+            ) from err
+    if tp is int and (not isinstance(value, int) or isinstance(value, bool)):
+        raise MalformedMessageError(f"{where}: expected an integer")
+    if tp in (str, bool) and not isinstance(value, tp):
+        raise MalformedMessageError(f"{where}: expected {tp.__name__}")
+    return value