Construct proxies with positional flags (#193)

proxy() passed the readonly and shallow flags as keyword arguments to
proxy_db.get_proxy, the proxy classes and its own tuple recursion;
keyword calls are measurably slower than positional ones, and this is
the hottest code path in observ (it runs on the result of every read
from a proxied container).

The readonly proxy classes' __init__ shims now line up with
Proxy.__init__ ((target, readonly, shallow)) so that proxy() can
construct any proxy type positionally. The readonly argument is
accepted and ignored, so a directly constructed Readonly* proxy is
still always readonly (previously enforced with two dict merges per
construction, which are gone now).

New tests pin down that positional and keyword flags resolve to the
same cached proxies, and that direct Readonly* construction still
forces readonly and honors shallow.

Measured on bench/test_creation.py: proxy creation ~6-12% faster.


Claude-Session: https://claude.ai/code/session_01UyALuqgF1ZZ3Lj88FzwGVc

Co-authored-by: Claude <noreply@anthropic.com>

Author: Korijn

observ/dict_proxy.py

@@ -64,11 +64,12 @@ def _orphaned_keydeps(self) -> set[Any]:
 
 
 def readonly_dict_proxy_init(
-    self: DictProxyBase, target: dict, shallow: bool = False, **kwargs: Any
+    self: DictProxyBase, target: dict, readonly: bool = True, shallow: bool = False
 ) -> None:
-    super(ReadonlyDictProxy, self).__init__(
-        target, shallow=shallow, **{**kwargs, "readonly": True}
-    )
+    # The signature lines up with Proxy.__init__ so that proxy() can
+    # construct any proxy type positionally; the readonly argument is
+    # ignored, a ReadonlyDictProxy is always readonly
+    super(ReadonlyDictProxy, self).__init__(target, True, shallow)
 
 
 # The proxy classes are assembled dynamically from the trap functions,

observ/list_proxy.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, cast
+from typing import cast
 
 from .proxy import TYPE_LOOKUP, Proxy
 from .traps import construct_methods_traps_dict, trap_map, trap_map_readonly
@@ -53,11 +53,12 @@ class ListProxyBase(Proxy[list]):
 
 
 def readonly_list_proxy_init(
-    self: ListProxyBase, target: list, shallow: bool = False, **kwargs: Any
+    self: ListProxyBase, target: list, readonly: bool = True, shallow: bool = False
 ) -> None:
-    super(ReadonlyListProxy, self).__init__(
-        target, shallow=shallow, **{**kwargs, "readonly": True}
-    )
+    # The signature lines up with Proxy.__init__ so that proxy() can
+    # construct any proxy type positionally; the readonly argument is
+    # ignored, a ReadonlyListProxy is always readonly
+    super(ReadonlyListProxy, self).__init__(target, True, shallow)
 
 
 # The proxy classes are assembled dynamically from the trap functions,

observ/proxy.py

@@ -102,21 +102,21 @@ def proxy(target: T, readonly: bool = False, shallow: bool = False) -> T:
 
     # Note that at this point, target is always a non-proxy object
     # Check the proxy_db to see if there's already a proxy for the target object
-    existing_proxy: Any = proxy_db.get_proxy(target, readonly=readonly, shallow=shallow)
+    # NB: the calls below pass the flags positionally, since keyword
+    # arguments make a call measurably slower
+    existing_proxy: Any = proxy_db.get_proxy(target, readonly, shallow)
     if existing_proxy is not None:
         return existing_proxy
 
     # Create a new proxy
     proxy_types = TYPE_LOOKUP.get(type(target))
     if proxy_types is not None:
         proxy_type = proxy_types[1] if readonly else proxy_types[0]
-        new_proxy: Any = proxy_type(target, readonly=readonly, shallow=shallow)
+        new_proxy: Any = proxy_type(target, readonly, shallow)
         return new_proxy
 
     if isinstance(target, tuple):
-        return cast(
-            T, tuple(proxy(x, readonly=readonly, shallow=shallow) for x in target)
-        )
+        return cast(T, tuple(proxy(x, readonly, shallow) for x in target))
 
     # We can't proxy a plain value
     return target

observ/set_proxy.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, cast
+from typing import cast
 
 from .proxy import TYPE_LOOKUP, Proxy
 from .traps import construct_methods_traps_dict, trap_map, trap_map_readonly
@@ -62,11 +62,12 @@ class SetProxyBase(Proxy[set]):
 
 
 def readonly_set_proxy_init(
-    self: SetProxyBase, target: set, shallow: bool = False, **kwargs: Any
+    self: SetProxyBase, target: set, readonly: bool = True, shallow: bool = False
 ) -> None:
-    super(ReadonlySetProxy, self).__init__(
-        target, shallow=shallow, **{**kwargs, "readonly": True}
-    )
+    # The signature lines up with Proxy.__init__ so that proxy() can
+    # construct any proxy type positionally; the readonly argument is
+    # ignored, a ReadonlySetProxy is always readonly
+    super(ReadonlySetProxy, self).__init__(target, True, shallow)
 
 
 # The proxy classes are assembled dynamically from the trap functions,

tests/test_proxy.py

@@ -356,3 +356,59 @@ def test_proxy_types_registered_without_extra_imports():
         ],
         check=True,
     )
+
+
+def test_proxy_flag_call_conventions():
+    """
+    The readonly and shallow flags resolve identically whether they
+    are passed positionally or as keywords: every combination maps to
+    the same (cached) proxy for the same target.
+    """
+    data = {"foo": "bar"}
+    writable = proxy(data, readonly=False, shallow=False)
+    readonly_proxy = proxy(data, readonly=True)
+    shallow = proxy(data, shallow=True)
+    readonly_shallow = proxy(data, readonly=True, shallow=True)
+
+    # All four configurations are distinct proxies
+    configs = (writable, readonly_proxy, shallow, readonly_shallow)
+    assert len({id(p) for p in configs}) == 4
+
+    # Positional calls resolve to the same proxies as keyword calls
+    assert proxy(data, False, False) is writable
+    assert proxy(data, True) is readonly_proxy
+    assert proxy(data, False, True) is shallow
+    assert proxy(data, True, True) is readonly_shallow
+
+    assert writable.__readonly__ is False and writable.__shallow__ is False
+    assert readonly_proxy.__readonly__ is True
+    assert readonly_proxy.__shallow__ is False
+    assert shallow.__readonly__ is False and shallow.__shallow__ is True
+    assert readonly_shallow.__readonly__ is True
+    assert readonly_shallow.__shallow__ is True
+
+
+def test_readonly_proxy_construction_forces_readonly():
+    """
+    Constructing a Readonly* proxy class directly always yields a
+    readonly proxy, whatever flags are passed, and the shallow flag
+    still comes through.
+    """
+    for proxy_type, target in (
+        (ReadonlyDictProxy, {"foo": "bar"}),
+        (ReadonlyListProxy, ["foo"]),
+        (ReadonlySetProxy, {"foo"}),
+    ):
+        readonly_proxy = proxy_type(target)
+        assert readonly_proxy.__readonly__ is True
+        assert readonly_proxy.__shallow__ is False
+
+        # A passed readonly flag is ignored
+        del readonly_proxy
+        overridden = proxy_type(target, readonly=False)
+        assert overridden.__readonly__ is True
+
+        del overridden
+        shallow = proxy_type(target, shallow=True)
+        assert shallow.__readonly__ is True
+        assert shallow.__shallow__ is True