pythonnative 0.36.0__py3-none-any.whl → 0.38.0__py3-none-any.whl

pythonnative/bridge/android.py

@@ -0,0 +1,78 @@
+"""Android transport: the ``com.pythonnative.runtime.PNBridge`` class via Chaquopy.
+
+``PNBridge`` is the only Java class Python touches. Its static methods
+mirror the C entry points used on iOS (see ``docs/concepts/bridge.md``).
+The reverse direction (native -> Python) is installed by the template's
+``MainActivity``, which implements ``PythonHost`` by calling
+[`pythonnative.bridge.native_callback`][pythonnative.bridge.native_callback]
+through Chaquopy; this transport therefore has nothing to register.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Tuple
+
+__all__ = ["AndroidTransport"]
+
+BRIDGE_CLASS = "com.pythonnative.runtime.PNBridge"
+
+
+class AndroidTransport:
+    """Thin wrapper over the static ``PNBridge`` methods."""
+
+    name = "android"
+
+    def __init__(self, bridge_class: Any = None) -> None:
+        if bridge_class is None:
+            from java import jclass
+
+            try:
+                bridge_class = jclass(BRIDGE_CLASS)
+            except Exception as exc:
+                raise RuntimeError(
+                    f"{BRIDGE_CLASS} is not on the classpath. Rebuild the app with 'pn run android' or "
+                    "'pn build android' so the pythonnative Gradle module is included."
+                ) from exc
+        self._bridge = bridge_class
+
+    def protocol_version(self) -> int:
+        """Return the protocol version compiled into the native library."""
+        return int(self._bridge.protocolVersion())
+
+    def apply(self, transaction_json: str) -> None:
+        """Apply one serialized transaction (a JSON array of ops)."""
+        self._bridge.apply(transaction_json)
+
+    def measure(self, tag: int, max_width: float, max_height: float) -> Tuple[float, float]:
+        """Return the intrinsic ``(width, height)`` of the view ``tag`` under the constraints."""
+        packed = self._bridge.measure(int(tag), float(max_width), float(max_height))
+        if not packed:
+            return (0.0, 0.0)
+        text = str(packed)
+        w, _, h = text.partition(",")
+        try:
+            return (float(w), float(h))
+        except ValueError:
+            return (0.0, 0.0)
+
+    def command(self, tag: int, name: str, args_json: str) -> Optional[str]:
+        """Run an imperative command on one view; returns its JSON result or ``None``."""
+        return _opt_str(self._bridge.command(int(tag), name, args_json))
+
+    def animate(self, tag: int, request_json: str) -> Optional[str]:
+        """Handle an animation request (``set`` / ``start`` / ``cancel``) for one view."""
+        return _opt_str(self._bridge.animate(int(tag), request_json))
+
+    def call(self, module: str, method: str, args_json: str) -> Optional[str]:
+        """Call a native module method with a ``{"call_id", "args"}`` envelope."""
+        return _opt_str(self._bridge.call(module, method, args_json))
+
+    def set_callback(self, callback: Callable[[str, int, str, str], Optional[str]]) -> None:
+        """No-op: the Android template installs the host through ``PNBridge.setHost``."""
+        del callback
+
+
+def _opt_str(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    return str(value)

pythonnative/bridge/codec.py

@@ -0,0 +1,164 @@
+"""JSON encoding for the native bridge.
+
+The bridge speaks JSON in both directions (see ``docs/concepts/bridge.md``).
+Prop values coming out of the reconciler are almost, but not quite,
+JSON: they may contain ``frozenset`` event-name sets, tuples, floats
+that are infinite, and Python callables that native must never see.
+[`to_jsonable`][pythonnative.bridge.codec.to_jsonable] normalizes a
+value into something ``json.dumps`` accepts and reports the keys it had
+to drop so the backend can keep them Python-side.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any, Dict, List, Sequence, Tuple, Union
+
+from ..mutations import CreateOp, DestroyOp, InsertOp, Mutation, SetFrameOp, UpdateOp
+
+__all__ = [
+    "INF",
+    "NEG_INF",
+    "dumps",
+    "encode_transaction",
+    "loads",
+    "split_props",
+    "to_jsonable",
+]
+
+INF = "inf"
+"""Wire spelling of ``math.inf`` (JSON has no infinity literal)."""
+
+NEG_INF = "-inf"
+"""Wire spelling of ``-math.inf``."""
+
+_SCALARS = (str, int, bool, type(None))
+
+
+def to_jsonable(value: Any) -> Any:
+    """Return a JSON-serializable copy of ``value``.
+
+    - ``set`` / ``frozenset`` / ``tuple`` become lists (sets are sorted
+      when their members are strings so the output is deterministic).
+    - Infinite floats become the strings ``"inf"`` / ``"-inf"``; NaN
+      becomes ``None`` (native clamps missing geometry to zero).
+    - Dataclass-like objects with ``to_json()`` are converted through
+      it.
+
+    Raises:
+        TypeError: When ``value`` (or something nested in it) has no
+            JSON representation; callers decide whether to drop it.
+    """
+    if isinstance(value, _SCALARS):
+        return value
+    if isinstance(value, float):
+        if math.isfinite(value):
+            return value
+        if math.isnan(value):
+            return None
+        return INF if value > 0 else NEG_INF
+    if isinstance(value, dict):
+        return {str(k): to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [to_jsonable(v) for v in value]
+    if isinstance(value, (set, frozenset)):
+        items = list(value)
+        try:
+            items.sort()
+        except TypeError:
+            pass
+        return [to_jsonable(v) for v in items]
+    to_json = getattr(value, "to_json", None)
+    if callable(to_json):
+        return to_jsonable(to_json())
+    raise TypeError(f"value of type {type(value).__name__} is not bridge-serializable")
+
+
+def split_props(props: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Split ``props`` into ``(wire_props, python_props)``.
+
+    ``wire_props`` is JSON-ready; ``python_props`` holds every prop
+    that can't cross the bridge (callables such as ``render_row``,
+    arbitrary objects). The backend keeps the latter in a per-tag
+    sidecar so native-backed handlers that need them (virtualized
+    list rows) can still reach them.
+    """
+    wire: Dict[str, Any] = {}
+    python: Dict[str, Any] = {}
+    for key, value in props.items():
+        if callable(value) and not isinstance(value, type):
+            python[key] = value
+            continue
+        try:
+            wire[key] = to_jsonable(value)
+        except TypeError:
+            python[key] = value
+    return wire, python
+
+
+def encode_transaction(
+    ops: Sequence[Mutation], prop_filter: Any = None
+) -> Tuple[str, List[Tuple[int, Dict[str, Any]]]]:
+    """Encode a mutation batch as the bridge's transaction JSON.
+
+    Args:
+        ops: Ordered mutations from the reconciler.
+        prop_filter: Unused hook kept for symmetry with the desktop
+            registry; reserved for per-type prop rewriting.
+
+    Returns:
+        ``(json_text, python_props)`` where ``python_props`` lists
+        ``(tag, props)`` pairs for values that stayed Python-side (for
+        ``c`` and ``u`` ops). An update that *removes* a Python-side
+        prop reports it as ``None`` so the sidecar can drop it.
+    """
+    del prop_filter
+    encoded: List[Any] = []
+    sidecar: List[Tuple[int, Dict[str, Any]]] = []
+    for op in ops:
+        if isinstance(op, CreateOp):
+            wire, python = split_props(op.props)
+            encoded.append(["c", op.tag, op.type_name, wire])
+            if python:
+                sidecar.append((op.tag, python))
+        elif isinstance(op, UpdateOp):
+            wire, python = split_props(op.changed_props)
+            encoded.append(["u", op.tag, wire])
+            if python:
+                sidecar.append((op.tag, python))
+        elif isinstance(op, InsertOp):
+            encoded.append(["i", op.parent_tag, op.child_tag, op.index])
+        elif isinstance(op, DestroyOp):
+            encoded.append(["d", op.tag])
+        elif isinstance(op, SetFrameOp):
+            encoded.append(["f", op.tag, _num(op.x), _num(op.y), _num(op.width), _num(op.height)])
+        else:  # pragma: no cover - the reconciler only emits the five op kinds
+            raise TypeError(f"Unknown mutation op: {op!r}")
+    return dumps(encoded), sidecar
+
+
+def _num(value: float) -> float:
+    """Clamp a frame coordinate to a finite float (native treats NaN/inf as 0)."""
+    try:
+        f = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    return f if math.isfinite(f) else 0.0
+
+
+def dumps(value: Any) -> str:
+    """Compact ``json.dumps`` used for every bridge payload."""
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+
+
+def loads(text: Union[str, bytes, bytearray, None]) -> Any:
+    """Parse a bridge payload (``str`` or UTF-8 bytes); empty / ``None`` input yields ``None``."""
+    if text is None:
+        return None
+    if isinstance(text, (bytes, bytearray)):
+        text = text.decode("utf-8")
+    text = text.strip()
+    if not text:
+        return None
+    return json.loads(text)

pythonnative/bridge/fake.py

@@ -0,0 +1,236 @@
+"""An in-process stand-in for the native side of the bridge.
+
+[`FakeTransport`][pythonnative.bridge.fake.FakeTransport] decodes the
+same JSON the Swift and Kotlin runtimes receive and keeps a tiny view
+tree so tests can assert on what *would* have reached native: created
+types and props, insert order, frames, commands, animation requests,
+and module calls. It also lets tests play the native side, firing
+events and module results back through
+[`native_callback`][pythonnative.bridge.native_callback].
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from . import codec
+
+__all__ = ["FakeNativeView", "FakeTransport"]
+
+
+class FakeNativeView:
+    """One decoded native view: type, merged props, children, and frame."""
+
+    def __init__(self, tag: int, type_name: str, props: Dict[str, Any]) -> None:
+        self.tag = tag
+        self.type_name = type_name
+        self.props: Dict[str, Any] = dict(props)
+        self.children: List["FakeNativeView"] = []
+        self.parent: Optional["FakeNativeView"] = None
+        self.frame: Tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0)
+
+    def __repr__(self) -> str:
+        return f"<native {self.type_name} tag={self.tag}>"
+
+
+ModuleHandler = Callable[[str, Dict[str, Any]], Any]
+"""``handler(method, args) -> value`` for a fake native module."""
+
+DEFAULT_MEASURE: Dict[str, Tuple[float, float]] = {
+    "Text": (60.0, 16.0),
+    "Button": (80.0, 32.0),
+    "Image": (40.0, 40.0),
+    "TextInput": (120.0, 32.0),
+    "TabBar": (320.0, 49.0),
+}
+
+
+class FakeTransport:
+    """Decode bridge traffic into inspectable Python structures.
+
+    Attributes:
+        views: Live views by tag.
+        transactions: Every decoded transaction (list of op lists).
+        commands: ``(tag, name, args)`` tuples in call order.
+        animations: ``(tag, request)`` tuples in call order.
+        calls: ``(module, method, args)`` tuples in call order.
+    """
+
+    name = "fake"
+
+    def __init__(self, *, version: int = 1, measure: Optional[Dict[str, Tuple[float, float]]] = None) -> None:
+        self._version = version
+        self.measure_table = dict(DEFAULT_MEASURE if measure is None else measure)
+        self.views: Dict[int, FakeNativeView] = {}
+        self.transactions: List[List[Any]] = []
+        self.commands: List[Tuple[int, str, Dict[str, Any]]] = []
+        self.animations: List[Tuple[int, Dict[str, Any]]] = []
+        self.calls: List[Tuple[str, str, Dict[str, Any]]] = []
+        self.command_results: Dict[str, Any] = {}
+        self.animate_results: Dict[str, Any] = {"start": {"ok": True}}
+        self.module_handlers: Dict[str, ModuleHandler] = {}
+        self.pending_calls: List[Tuple[str, int, str, Dict[str, Any]]] = []
+        self.callback: Optional[Callable[[str, int, str, str], Optional[str]]] = None
+        self.posted = 0
+
+    # -- Transport protocol ----------------------------------------------
+
+    def protocol_version(self) -> int:
+        """Return the protocol version compiled into the native library."""
+        return self._version
+
+    def set_callback(self, callback: Callable[[str, int, str, str], Optional[str]]) -> None:
+        """Install ``callback`` as the native -> Python entry point."""
+        self.callback = callback
+
+    def apply(self, transaction_json: str) -> None:
+        """Apply one serialized transaction (a JSON array of ops)."""
+        ops = json.loads(transaction_json)
+        self.transactions.append(ops)
+        for op in ops:
+            self._apply_one(op)
+
+    def _apply_one(self, op: List[Any]) -> None:
+        code = op[0]
+        if code == "c":
+            _, tag, type_name, props = op
+            if tag in self.views:
+                raise AssertionError(f"create: tag {tag} already exists")
+            self.views[tag] = FakeNativeView(tag, type_name, props)
+        elif code == "u":
+            _, tag, changed = op
+            view = self._require(tag, "update")
+            for key, value in changed.items():
+                if value is None:
+                    view.props.pop(key, None)
+                else:
+                    view.props[key] = value
+        elif code == "i":
+            _, parent_tag, child_tag, index = op
+            parent = self._require(parent_tag, "insert")
+            child = self._require(child_tag, "insert")
+            if child.parent is not None:
+                child.parent.children.remove(child)
+            index = max(0, min(int(index), len(parent.children)))
+            parent.children.insert(index, child)
+            child.parent = parent
+        elif code == "d":
+            _, tag = op
+            view = self.views.pop(tag, None)
+            if view is None:
+                raise AssertionError(f"destroy: unknown tag {tag}")
+            if view.parent is not None:
+                view.parent.children.remove(view)
+                view.parent = None
+        elif code == "f":
+            _, tag, x, y, w, h = op
+            self._require(tag, "set_frame").frame = (float(x), float(y), float(w), float(h))
+        else:
+            raise AssertionError(f"unknown opcode {code!r}")
+
+    def _require(self, tag: int, what: str) -> FakeNativeView:
+        view = self.views.get(tag)
+        if view is None:
+            raise AssertionError(f"{what}: unknown tag {tag}")
+        return view
+
+    def measure(self, tag: int, max_width: float, max_height: float) -> Tuple[float, float]:
+        """Return the intrinsic ``(width, height)`` of the view ``tag`` under the constraints."""
+        view = self.views.get(tag)
+        if view is None:
+            return (0.0, 0.0)
+        return self.measure_table.get(view.type_name, (0.0, 0.0))
+
+    def command(self, tag: int, name: str, args_json: str) -> Optional[str]:
+        """Run an imperative command on one view; returns its JSON result or ``None``."""
+        args = codec.loads(args_json) or {}
+        self.commands.append((tag, name, args))
+        result = self.command_results.get(name)
+        return None if result is None else codec.dumps(result)
+
+    def animate(self, tag: int, request_json: str) -> Optional[str]:
+        """Handle an animation request (``set`` / ``start`` / ``cancel``) for one view."""
+        request = codec.loads(request_json) or {}
+        self.animations.append((tag, request))
+        result = self.animate_results.get(str(request.get("op")))
+        return None if result is None else codec.dumps(result)
+
+    def call(self, module: str, method: str, args_json: str) -> Optional[str]:
+        """Call a native module method with a ``{"call_id", "args"}`` envelope."""
+        envelope = codec.loads(args_json) or {}
+        args = envelope.get("args") or {}
+        call_id = int(envelope.get("call_id", 0) or 0)
+        self.calls.append((module, method, args))
+        if module == "Host" and method == "post":
+            self.posted += 1
+            return codec.dumps({"ok": True, "value": None})
+        handler = self.module_handlers.get(module)
+        if handler is None:
+            return codec.dumps({"ok": True, "value": None})
+        try:
+            value = handler(method, args)
+        except Exception as exc:
+            return codec.dumps({"ok": False, "error": str(exc)})
+        if value is _PENDING:
+            self.pending_calls.append((module, call_id, method, args))
+            return codec.dumps({"pending": True})
+        return codec.dumps({"ok": True, "value": codec.to_jsonable(value)})
+
+    # -- Playing the native side ------------------------------------------
+
+    def fire(self, tag: int, name: str, *args: Any) -> Any:
+        """Emit a view event as native would; returns the decoded handler result."""
+        return self._callback("event", tag, name, codec.dumps([codec.to_jsonable(a) for a in args]))
+
+    def emit_module_event(self, module: str, event: str, payload: Any = None) -> None:
+        """Push an unsolicited module event (``AppState`` ``change``, ...) into Python."""
+        self._callback("module", 0, module, codec.dumps({"event": event, "payload": codec.to_jsonable(payload)}))
+
+    def resolve_pending(self, call_id: int, value: Any = None, *, error: Optional[str] = None) -> None:
+        """Settle a call that returned ``pending``."""
+        module = next((m for m, cid, _, _ in self.pending_calls if cid == call_id), None)
+        if module is None:
+            raise AssertionError(f"no pending call with id {call_id}")
+        self.pending_calls = [p for p in self.pending_calls if p[1] != call_id]
+        body: Dict[str, Any] = {"call_id": call_id, "ok": error is None}
+        if error is None:
+            body["value"] = codec.to_jsonable(value)
+        else:
+            body["error"] = error
+        self._callback("module", 0, module, codec.dumps(body))
+
+    def host_event(self, screen: int, event: str, payload: Any = None) -> Any:
+        """Deliver a screen lifecycle event as the native host would; returns the decoded result."""
+        return self._callback("host", screen, event, codec.dumps(codec.to_jsonable(payload)))
+
+    def pump(self) -> None:
+        """Deliver the ``pump`` callback (what ``Host.post`` would trigger)."""
+        self._callback("pump", 0, "", "")
+
+    def complete_animation(self, anim_id: int, finished: bool = True) -> None:
+        """Report a native animation as finished (or interrupted) to Python."""
+        self._callback("animation", 0, "", codec.dumps({"id": anim_id, "finished": finished}))
+
+    def _callback(self, kind: str, tag: int, name: str, payload: str) -> Any:
+        if self.callback is None:
+            raise AssertionError("FakeTransport has no callback; install it with pythonnative.bridge.set_transport")
+        return codec.loads(self.callback(kind, tag, name, payload))
+
+    # -- Introspection -----------------------------------------------------
+
+    def find(self, type_name: str) -> List[FakeNativeView]:
+        """Every live view whose type is ``type_name``, in creation order."""
+        return [v for v in self.views.values() if v.type_name == type_name]
+
+    def roots(self) -> List[FakeNativeView]:
+        """Views with no parent (the attached screen roots and detached subtrees)."""
+        return [v for v in self.views.values() if v.parent is None]
+
+    @staticmethod
+    def pending() -> object:
+        """Sentinel a module handler returns to answer ``pending``."""
+        return _PENDING
+
+
+_PENDING = object()

pythonnative/bridge/ios.py

@@ -0,0 +1,138 @@
+"""iOS transport: C-ABI calls into ``PythonNativeKit`` through ``ctypes``.
+
+The Swift package exports ``@_cdecl`` symbols (see
+``docs/concepts/bridge.md``). They're resolved from the running process
+with ``ctypes.PyDLL(None)``: ``PyDLL`` keeps the GIL held across the
+call, so the main thread is never parked while native applies a
+transaction, and the Python callback registered with
+``pn_bridge_set_callback`` can re-enter Python safely.
+
+Strings returned by native are ``strdup``'d; this module copies them
+and hands the pointer back to ``pn_bridge_free``.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Any, Callable, Optional, Tuple
+
+__all__ = ["IOSTransport"]
+
+# const char *(*)(const char *kind, int64_t tag, const char *name, const char *payload_json)
+_CALLBACK_TYPE = ctypes.CFUNCTYPE(ctypes.c_void_p, ctypes.c_char_p, ctypes.c_int64, ctypes.c_char_p, ctypes.c_char_p)
+
+
+class IOSTransport:
+    """Bind the ``pn_bridge_*`` symbols and expose them as Python methods."""
+
+    name = "ios"
+
+    def __init__(self, lib: Any = None) -> None:
+        self._lib = lib if lib is not None else ctypes.PyDLL(None)
+        self._apply = self._sym("pn_bridge_apply", None, [ctypes.c_char_p])
+        self._measure = self._sym(
+            "pn_bridge_measure",
+            None,
+            [
+                ctypes.c_int64,
+                ctypes.c_double,
+                ctypes.c_double,
+                ctypes.POINTER(ctypes.c_double),
+                ctypes.POINTER(ctypes.c_double),
+            ],
+        )
+        self._command = self._sym(
+            "pn_bridge_command", ctypes.c_void_p, [ctypes.c_int64, ctypes.c_char_p, ctypes.c_char_p]
+        )
+        self._animate = self._sym("pn_bridge_animate", ctypes.c_void_p, [ctypes.c_int64, ctypes.c_char_p])
+        self._call = self._sym("pn_bridge_call", ctypes.c_void_p, [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p])
+        self._free = self._sym("pn_bridge_free", None, [ctypes.c_void_p])
+        self._set_callback = self._sym("pn_bridge_set_callback", None, [_CALLBACK_TYPE])
+        self._version = self._sym("pn_bridge_protocol_version", ctypes.c_int, [])
+        # Strong references so the C trampoline and its last return
+        # buffer outlive the calls native makes into them.
+        self._callback_c: Any = None
+        self._last_result: Any = None
+        self._out_w = ctypes.c_double(0.0)
+        self._out_h = ctypes.c_double(0.0)
+
+    def _sym(self, name: str, restype: Any, argtypes: Any) -> Any:
+        try:
+            fn = getattr(self._lib, name)
+        except AttributeError as exc:
+            raise RuntimeError(
+                f"PythonNativeKit symbol {name!r} is missing from the app binary. Rebuild the app with "
+                "'pn run ios' or 'pn build ios' so the Swift package is linked."
+            ) from exc
+        fn.restype = restype
+        fn.argtypes = argtypes
+        return fn
+
+    # -- protocol -------------------------------------------------------
+
+    def protocol_version(self) -> int:
+        """Return the protocol version compiled into the native library."""
+        return int(self._version())
+
+    def apply(self, transaction_json: str) -> None:
+        """Apply one serialized transaction (a JSON array of ops)."""
+        self._apply(transaction_json.encode("utf-8"))
+
+    def measure(self, tag: int, max_width: float, max_height: float) -> Tuple[float, float]:
+        """Return the intrinsic ``(width, height)`` of the view ``tag`` under the constraints."""
+        self._measure(
+            int(tag), float(max_width), float(max_height), ctypes.byref(self._out_w), ctypes.byref(self._out_h)
+        )
+        return (float(self._out_w.value), float(self._out_h.value))
+
+    def command(self, tag: int, name: str, args_json: str) -> Optional[str]:
+        """Run an imperative command on one view; returns its JSON result or ``None``."""
+        return self._take(self._command(int(tag), name.encode("utf-8"), args_json.encode("utf-8")))
+
+    def animate(self, tag: int, request_json: str) -> Optional[str]:
+        """Handle an animation request (``set`` / ``start`` / ``cancel``) for one view."""
+        return self._take(self._animate(int(tag), request_json.encode("utf-8")))
+
+    def call(self, module: str, method: str, args_json: str) -> Optional[str]:
+        """Call a native module method with a ``{"call_id", "args"}`` envelope."""
+        return self._take(self._call(module.encode("utf-8"), method.encode("utf-8"), args_json.encode("utf-8")))
+
+    def set_callback(self, callback: Callable[[str, int, str, str], Optional[str]]) -> None:
+        """Install ``callback`` as the native -> Python entry point."""
+
+        def trampoline(kind: bytes, tag: int, name: bytes, payload: bytes) -> Optional[int]:
+            try:
+                result = callback(
+                    _decode(kind),
+                    int(tag),
+                    _decode(name),
+                    _decode(payload),
+                )
+            except Exception as exc:  # pragma: no cover - last-resort guard
+                print(f"[pn.bridge] callback raised: {exc!r}")
+                return None
+            if result is None:
+                return None
+            buf = ctypes.create_string_buffer(result.encode("utf-8"))
+            self._last_result = buf
+            return ctypes.addressof(buf)
+
+        self._callback_c = _CALLBACK_TYPE(trampoline)
+        self._set_callback(self._callback_c)
+
+    # -- helpers --------------------------------------------------------
+
+    def _take(self, ptr: Optional[int]) -> Optional[str]:
+        """Copy a native ``char*`` result and free it."""
+        if not ptr:
+            return None
+        try:
+            return ctypes.string_at(ptr).decode("utf-8")
+        finally:
+            self._free(ptr)
+
+
+def _decode(value: Optional[bytes]) -> str:
+    if not value:
+        return ""
+    return value.decode("utf-8", "replace")