refactor(python): use cached_property and MappingProxyType for read-only collections (#284) (#286)

weinbe58 · claude · web-flow · commit bf288573a90c · 2026-03-20T15:21:38.000-04:00
* refactor(python): use MappingProxyType and tuple for read-only property access Convert PlotParameters dict-returning properties in artist.py to @cached_property with MappingProxyType for immutable, cached access. Wrap DetectorResult.detectors and .observables in tuple() to prevent mutation of internal lists. Add comment to ArchSpec.paths explaining why it remains mutable (populated incrementally after construction). Closes #284 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(python): address PR review feedback on MappingProxyType changes (#284) - Add from __future__ import annotations to artist.py for Python 3.10 compatibility with MappingProxyType[str, Any] annotations - Make PlotParameters frozen=True to keep cached_property coherent - Deep-copy inner lists in DetectorResult: return tuple(tuple(shot)) instead of tuple(self._list) to prevent mutation of inner lists - Make ArchSpec.paths read-only with MappingProxyType — refactor impls.py to merge path dicts before construction instead of mutating after - Add caching identity check to test_plot_parameters_properties Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/python/bloqade/lanes/arch/gemini/impls.py b/python/bloqade/lanes/arch/gemini/impls.py
@@ -230,7 +230,7 @@ def generate_arch_hypercube(hypercube_dims: int = 4, word_size_y: int = 5) -> Ar
     num_words_x = 2**hypercube_dims
     base_arch = _generate_base_arch(num_words_x, word_size_y)
     word_buses = _hypercube_busses(hypercube_dims)
-    base_arch.paths.update(_calc_hypercube_word_path_dict(base_arch.words))
+    paths = {**base_arch.paths, **_calc_hypercube_word_path_dict(base_arch.words)}
     return ArchSpec.from_components(
         words=base_arch.words,
         zones=base_arch.zones,
@@ -240,14 +240,14 @@ def generate_arch_hypercube(hypercube_dims: int = 4, word_size_y: int = 5) -> Ar
         has_word_buses=base_arch.has_word_buses,
         site_buses=base_arch.site_buses,
         word_buses=word_buses,
-        paths=base_arch.paths,
+        paths=paths,
     )
 
 
 def generate_arch_linear(num_words: int = 16, word_size_y: int = 5) -> ArchSpec:
     base_arch = _generate_base_arch(num_words, word_size_y)
     word_buses = _generate_linear_busses(num_words)
-    base_arch.paths.update(_calc_linear_word_path_dict(base_arch.words))
+    paths = {**base_arch.paths, **_calc_linear_word_path_dict(base_arch.words)}
     return ArchSpec.from_components(
         words=base_arch.words,
         zones=base_arch.zones,
@@ -257,7 +257,7 @@ def generate_arch_linear(num_words: int = 16, word_size_y: int = 5) -> ArchSpec:
         has_word_buses=base_arch.has_word_buses,
         site_buses=base_arch.site_buses,
         word_buses=word_buses,
-        paths=base_arch.paths,
+        paths=paths,
     )
 
 
diff --git a/python/bloqade/lanes/device.py b/python/bloqade/lanes/device.py
@@ -62,24 +62,24 @@ def detector_error_model(self) -> DetectorErrorModel:
         return self._detector_error_model
 
     @property
-    def detectors(self) -> list[list[bool]]:
+    def detectors(self) -> tuple[tuple[bool, ...], ...]:
         """The detector outcomes from the simulation.
 
         Returns:
-            list[list[bool]]: The detector outcomes, one list per shot.
+            tuple[tuple[bool, ...], ...]: The detector outcomes, one tuple per shot.
 
         """
-        return self._detectors
+        return tuple(tuple(shot) for shot in self._detectors)
 
     @property
-    def observables(self) -> list[list[bool]]:
+    def observables(self) -> tuple[tuple[bool, ...], ...]:
         """The observable outcomes from the simulation.
 
         Returns:
-            list[list[bool]]: The observable outcomes, one list per shot.
+            tuple[tuple[bool, ...], ...]: The observable outcomes, one tuple per shot.
 
         """
-        return self._observables
+        return tuple(tuple(shot) for shot in self._observables)
 
 
 @dataclass(frozen=True)
diff --git a/python/bloqade/lanes/layout/arch.py b/python/bloqade/lanes/layout/arch.py
@@ -2,6 +2,7 @@
 
 from collections import defaultdict
 from functools import cached_property
+from types import MappingProxyType
 from typing import TYPE_CHECKING, Sequence
 
 from bloqade.lanes.bytecode._native import (
@@ -34,7 +35,7 @@ class ArchSpec:
 
     _inner: _RustArchSpec
     words: tuple[Word, ...]
-    paths: dict[LaneAddress, tuple[tuple[float, float], ...]]
+    paths: MappingProxyType[LaneAddress, tuple[tuple[float, float], ...]]
 
     def __init__(
         self,
@@ -44,7 +45,7 @@ def __init__(
     ):
         self._inner = inner
         self.words = words
-        self.paths = paths if paths is not None else {}
+        self.paths = MappingProxyType(paths if paths is not None else {})
 
         self._inner.validate()
 
diff --git a/python/bloqade/lanes/visualize/artist.py b/python/bloqade/lanes/visualize/artist.py
@@ -1,7 +1,11 @@
+from __future__ import annotations
+
 from abc import ABC
 from dataclasses import dataclass
 from enum import Enum
-from typing import Callable, Sequence
+from functools import cached_property
+from types import MappingProxyType
+from typing import Any, Callable, Sequence
 
 import numpy as np
 from kirin import ir
@@ -22,7 +26,7 @@ class QuEraColorCode(str, Enum):
     AodLineColor = "#FFE8E9"
 
 
-@dataclass
+@dataclass(frozen=True)
 class PlotParameters:
     scale: float
 
@@ -38,64 +42,76 @@ class PlotParameters:
     atom_color: str = QuEraColorCode.Purple
     aod_line_style: str = "dashed"
 
-    @property
-    def atom_plot_args(self) -> dict:
-        return {
-            "color": self.atom_color,
-            "marker": self.atom_marker,
-            "linestyle": "",
-            "s": self.scale * 65,
-        }
+    @cached_property
+    def atom_plot_args(self) -> MappingProxyType[str, Any]:
+        return MappingProxyType(
+            {
+                "color": self.atom_color,
+                "marker": self.atom_marker,
+                "linestyle": "",
+                "s": self.scale * 65,
+            }
+        )
 
-    @property
-    def gate_spot_args(self) -> dict:
-        return {
-            "marker": self.atom_marker,
-            "s": self.scale * 160,
-            "alpha": 0.3,
-        }
+    @cached_property
+    def gate_spot_args(self) -> MappingProxyType[str, Any]:
+        return MappingProxyType(
+            {
+                "marker": self.atom_marker,
+                "s": self.scale * 160,
+                "alpha": 0.3,
+            }
+        )
 
-    @property
-    def slm_plot_args(self) -> dict:
-        return {
-            "facecolors": "none",
-            "edgecolors": "k",
-            "linestyle": "-",
-            "s": self.scale * 80,
-            "alpha": 1.0,
-            "linewidth": 0.5 * np.sqrt(self.scale),
-            "marker": self.atom_marker,
-        }
+    @cached_property
+    def slm_plot_args(self) -> MappingProxyType[str, Any]:
+        return MappingProxyType(
+            {
+                "facecolors": "none",
+                "edgecolors": "k",
+                "linestyle": "-",
+                "s": self.scale * 80,
+                "alpha": 1.0,
+                "linewidth": 0.5 * np.sqrt(self.scale),
+                "marker": self.atom_marker,
+            }
+        )
 
-    @property
-    def aod_line_args(self) -> dict:
-        return {
-            "alpha": 1.0,
-            "colors": self.aod_line_color,
-            "linestyles": self.aod_line_style,
-            "zorder": -101,
-        }
+    @cached_property
+    def aod_line_args(self) -> MappingProxyType[str, Any]:
+        return MappingProxyType(
+            {
+                "alpha": 1.0,
+                "colors": self.aod_line_color,
+                "linestyles": self.aod_line_style,
+                "zorder": -101,
+            }
+        )
 
-    @property
-    def aod_marker_args(self) -> dict:
-        return {
-            "color": QuEraColorCode.Red,
-            "marker": self.aod_marker,
-            "s": self.scale * 260,
-            "linewidth": np.sqrt(self.scale),
-            "alpha": 0.7,
-            "zorder": -100,
-        }
+    @cached_property
+    def aod_marker_args(self) -> MappingProxyType[str, Any]:
+        return MappingProxyType(
+            {
+                "color": QuEraColorCode.Red,
+                "marker": self.aod_marker,
+                "s": self.scale * 260,
+                "linewidth": np.sqrt(self.scale),
+                "alpha": 0.7,
+                "zorder": -100,
+            }
+        )
 
-    @property
-    def atom_label_args(self) -> dict:
-        return {
-            "color": "white",
-            "fontsize": max(4.0, self.scale * 6.0),
-            "ha": "center",
-            "va": "center",
-            "zorder": 200,
-        }
+    @cached_property
+    def atom_label_args(self) -> MappingProxyType[str, Any]:
+        return MappingProxyType(
+            {
+                "color": "white",
+                "fontsize": max(4.0, self.scale * 6.0),
+                "ha": "center",
+                "va": "center",
+                "zorder": 200,
+            }
+        )
 
 
 def init_aod_x_lines(ax: Axes, aod_x: Sequence[float], plot_params: PlotParameters):
diff --git a/python/tests/visualize/test_artist.py b/python/tests/visualize/test_artist.py
@@ -1,3 +1,5 @@
+from types import MappingProxyType
+
 from matplotlib import pyplot as plt
 from scipy.interpolate import interp1d
 
@@ -14,12 +16,16 @@
 
 def test_plot_parameters_properties():
     params = PlotParameters(scale=1.0)
-    assert isinstance(params.atom_plot_args, dict)
-    assert isinstance(params.atom_label_args, dict)
-    assert isinstance(params.gate_spot_args, dict)
-    assert isinstance(params.slm_plot_args, dict)
-    assert isinstance(params.aod_line_args, dict)
-    assert isinstance(params.aod_marker_args, dict)
+    # All properties return read-only MappingProxyType
+    assert isinstance(params.atom_plot_args, MappingProxyType)
+    assert isinstance(params.atom_label_args, MappingProxyType)
+    assert isinstance(params.gate_spot_args, MappingProxyType)
+    assert isinstance(params.slm_plot_args, MappingProxyType)
+    assert isinstance(params.aod_line_args, MappingProxyType)
+    assert isinstance(params.aod_marker_args, MappingProxyType)
+    # Cached: repeated access returns the same object
+    assert params.atom_plot_args is params.atom_plot_args
+    assert params.aod_line_args is params.aod_line_args
 
 
 def test_aod_x_lines():
