simplecadapi 2.2.6__tar.gz → 2.2.6.post1__tar.gz

{simplecadapi-2.2.6 → simplecadapi-2.2.6.post1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplecadapi
-Version: 2.2.6
+Version: 2.2.6.post1
 Summary: A simplified OCP-native CAD modeling Python API
 Project-URL: Homepage, https://github.com/PhySpace/SimpleCADAPI
 Project-URL: Repository, https://github.com/PhySpace/SimpleCADAPI
@@ -413,20 +413,20 @@ the full crank cycle sweeps clean in the same sim ·
 
 ---
 
-## Update Notes (2.2.6)
+## Update Notes (2.2.6.post1)
 
 > Validate generated definitions, assembly constraints, and manufacturing
 > geometry before production use.
 
-- **Switch notebooks without leaving the CLI.** `sca cell open NOTEBOOK` moves the editor
-  and waits for its kernel; the write commands take `--open` to switch and write in one
-  step, and a refused write names the way out.
-- **`sca viewport` answers what the person sees.** The image's path, age and size, copied
-  out with `--out`, instead of reading `.sca-editor/viewport.png` by hand.
-- **Cache entries are signed and verified again.** `cryptography` ships as a dependency,
-  so marimo's cache verification no longer silently degrades to off.
+- **Keyword `scad.var` is a parameter again.** `scad.var(name="j1", default=0.0)` is read
+  by the editor's parameter panel like the positional form; before, it was skipped.
+- **A cached run costs much less.** On the desktop arm: cold 80 s to 35 s, nothing changed
+  24 s to 4 s, one joint edited 18 s to 3 s, cache 1.7 GB to 96 MB. Restored shapes are built
+  on first use, parameters and imported names are keyed by value, and the `use` calls of a
+  cell run in worker processes (`SCA_JOBS`, 1 turns it off).
+- **Slider drags are sent when they settle**, not step by step.
 
-Full notes for this version: [`docs/updates/2.2.6.md`](docs/updates/2.2.6.md).
+Full notes for this version: [`docs/updates/2.2.6.post1.md`](docs/updates/2.2.6.post1.md).
 Earlier versions: the [changelog](CHANGELOG.md) and [`docs/updates/`](docs/updates/).
 
 ---
@@ -447,7 +447,7 @@ in a compact public API for creating solids, applying features, tagging semantic
 intent, querying topology, exporting manufacturing files, and translating recorded
 models into FreeCAD workflows.
 
-Current release: `simplecadapi==2.2.6`.
+Current release: `simplecadapi==2.2.6.post1`.
 
 ## What It Provides
 
@@ -962,6 +962,7 @@ and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reco
 
 ## Documentation
 
+- 2.2.6.post1 update notes: [`docs/updates/2.2.6.post1.md`](docs/updates/2.2.6.post1.md)
 - 2.2.6 update notes: [`docs/updates/2.2.6.md`](docs/updates/2.2.6.md)
 - 2.2.5 update notes: [`docs/updates/2.2.5.md`](docs/updates/2.2.5.md)
 - 2.2.4 update notes: [`docs/updates/2.2.4.md`](docs/updates/2.2.4.md)

{simplecadapi-2.2.6 → simplecadapi-2.2.6.post1}/README.md

@@ -149,20 +149,20 @@ the full crank cycle sweeps clean in the same sim ·
 
 ---
 
-## Update Notes (2.2.6)
+## Update Notes (2.2.6.post1)
 
 > Validate generated definitions, assembly constraints, and manufacturing
 > geometry before production use.
 
-- **Switch notebooks without leaving the CLI.** `sca cell open NOTEBOOK` moves the editor
-  and waits for its kernel; the write commands take `--open` to switch and write in one
-  step, and a refused write names the way out.
-- **`sca viewport` answers what the person sees.** The image's path, age and size, copied
-  out with `--out`, instead of reading `.sca-editor/viewport.png` by hand.
-- **Cache entries are signed and verified again.** `cryptography` ships as a dependency,
-  so marimo's cache verification no longer silently degrades to off.
+- **Keyword `scad.var` is a parameter again.** `scad.var(name="j1", default=0.0)` is read
+  by the editor's parameter panel like the positional form; before, it was skipped.
+- **A cached run costs much less.** On the desktop arm: cold 80 s to 35 s, nothing changed
+  24 s to 4 s, one joint edited 18 s to 3 s, cache 1.7 GB to 96 MB. Restored shapes are built
+  on first use, parameters and imported names are keyed by value, and the `use` calls of a
+  cell run in worker processes (`SCA_JOBS`, 1 turns it off).
+- **Slider drags are sent when they settle**, not step by step.
 
-Full notes for this version: [`docs/updates/2.2.6.md`](docs/updates/2.2.6.md).
+Full notes for this version: [`docs/updates/2.2.6.post1.md`](docs/updates/2.2.6.post1.md).
 Earlier versions: the [changelog](CHANGELOG.md) and [`docs/updates/`](docs/updates/).
 
 ---
@@ -183,7 +183,7 @@ in a compact public API for creating solids, applying features, tagging semantic
 intent, querying topology, exporting manufacturing files, and translating recorded
 models into FreeCAD workflows.
 
-Current release: `simplecadapi==2.2.6`.
+Current release: `simplecadapi==2.2.6.post1`.
 
 ## What It Provides
 
@@ -698,6 +698,7 @@ and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reco
 
 ## Documentation
 
+- 2.2.6.post1 update notes: [`docs/updates/2.2.6.post1.md`](docs/updates/2.2.6.post1.md)
 - 2.2.6 update notes: [`docs/updates/2.2.6.md`](docs/updates/2.2.6.md)
 - 2.2.5 update notes: [`docs/updates/2.2.5.md`](docs/updates/2.2.5.md)
 - 2.2.4 update notes: [`docs/updates/2.2.4.md`](docs/updates/2.2.4.md)

{simplecadapi-2.2.6 → simplecadapi-2.2.6.post1}/docs/skill/SKILL.md

@@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo
 license: Apache-2.0
 metadata:
   project: simplecadapi
-  version: 2.2.6
+  version: 2.2.6.post1
   package-name: simplecadapi
-  package-version: 2.2.6
+  package-version: 2.2.6.post1
 ---
 
 # SimpleCAD SDK Skill

simplecadapi-2.2.6.post1/docs/updates/2.2.6.post1.md

@@ -0,0 +1,44 @@
+# 2.2.6.post1 Update Notes
+
+A hotfix for the editor's parameter panel, and a round of speed work on the notebook cache
+and on `use`, measured on the desktop six-axis arm.
+
+## `scad.var(name=..., default=...)` is a parameter again
+
+The editor found a parameter's default only as the second *positional* argument of
+`scad.var`. A declaration written with keywords —
+
+```python
+J1 = scad.var(name="j1", default=0.0, comment="Joint 1")
+```
+
+— was skipped: no slider, no commit back to the file. Both forms are read now, and
+committing a value rewrites the right argument in either.
+
+## What a cached run costs
+
+| desktop arm | before | now |
+|---|---|---|
+| cold run | 80.5 s | 34.6 s |
+| nothing changed | 23.6 s | 4.0 s |
+| one joint angle edited | 18.2 s | 3.0 s |
+| a link length edited | 35.1 s | 19 s |
+| cache on disk | 1.7 GB | 96 MB |
+
+- **Restoring is cheaper.** A restored shape is built when something first uses it, so a
+  cached value no running cell reads costs nothing; the tag caches are rebuilt once, not
+  once per ancestor. The cache no longer stores a cell's private (`_name`) values and
+  compresses what it writes; entries from before are still read.
+- **Parameters are keyed by value.** A cell that reads one `scad.var` is not redone because a
+  neighbour defined in the same cell changed.
+- **A name, not a file.** `from lib.dims import A` depends on the definition of `A`.
+- **`use` is followed one call at a time.** A cell that uses a notebook by a literal path
+  depends on that notebook (its text, the modules it imports, the notebooks it uses): editing
+  one child redoes the cell that uses it, not its siblings. The editor kernel caches such
+  cells too.
+- **`use` calls run side by side.** The `use` calls a cell is about to make are started in
+  worker processes (threads would not help: OpenCASCADE keeps the interpreter lock) and the
+  cell finds them built. `SCA_JOBS` sets the number (default: the smaller of 4 and the
+  cores; `1` turns it off). Workers are started only when that saves more than they take to
+  start, and a notebook is locked between processes while it runs.
+- **Editor sliders.** A drag is sent when it pauses (250 ms) or ends, not step by step.

simplecadapi-2.2.6.post1/docs/updates/2.2.6.post1.zh-CN.md

@@ -0,0 +1,34 @@
+# 2.2.6.post1 更新说明
+
+编辑器参数面板的热修复，以及一轮针对 notebook 缓存和 `use` 的速度优化，数据来自桌面六轴机械臂。
+
+## `scad.var(name=..., default=...)` 重新被识别为参数
+
+编辑器只把 `scad.var` 的第二个**位置参数**当作默认值。用关键字写的声明——
+
+```python
+J1 = scad.var(name="j1", default=0.0, comment="Joint 1")
+```
+
+——会被跳过：没有滑块，也无法写回文件。现在两种写法都能读取，提交数值时也会改写对应的那个参数。
+
+## 缓存运行的代价
+
+| 桌面机械臂 | 之前 | 现在 |
+|---|---|---|
+| 冷启动 | 80.5 s | 34.6 s |
+| 什么都没改 | 23.6 s | 4.0 s |
+| 改一个关节角 | 18.2 s | 3.0 s |
+| 改一个连杆长度 | 35.1 s | 19 s |
+| 磁盘缓存 | 1.7 GB | 96 MB |
+
+- **恢复更便宜。** 恢复出来的形状在第一次被用到时才构建，没有 cell 读取的缓存值不花时间；标签缓存只重建一次，
+  不再每个祖先一次。缓存不再存 cell 私有（`_name`）变量的值，并压缩写入的内容；旧条目照样能读。
+- **参数按值定键。** 读取某个 `scad.var` 的 cell，不会因为同一个 cell 里的邻居参数变化而重跑。
+- **按名字而不是按文件。** `from lib.dims import A` 只依赖 `A` 的定义。
+- **`use` 按调用逐个跟踪。** 用字面量路径 `use` 一个 notebook 的 cell 依赖那个 notebook（文本、它导入的模块、
+  它再 `use` 的 notebook）：改一个子 notebook 只重跑用它的 cell，不动它的兄弟。编辑器内核也缓存这类 cell。
+- **`use` 并行。** cell 即将发出的 `use` 调用交给 worker 进程同时构建（线程没用：OpenCASCADE 不释放解释器锁），
+  cell 随后发现已经建好。`SCA_JOBS` 设置数量（默认 4 与核数的较小值；`1` 关闭）。只有省下的时间大于 worker
+  启动成本才会启动，并且 notebook 运行期间其状态目录在进程间加锁。
+- **编辑器滑块。** 拖动在停顿 250 ms 或松开时才发送，不再逐步发送。

{simplecadapi-2.2.6 → simplecadapi-2.2.6.post1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplecadapi"
-version = "2.2.6"
+version = "2.2.6.post1"
 description = "A simplified OCP-native CAD modeling Python API"
 readme = "README.md"
 license = { file = "LICENSE" }

{simplecadapi-2.2.6 → simplecadapi-2.2.6.post1}/src/simplecadapi/_internal/shape_pickle.py

@@ -19,6 +19,8 @@ from __future__ import annotations
 
 import io
 import re
+import threading
+import zlib
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Dict, List, Mapping, Set, Tuple
 
@@ -93,6 +95,20 @@ def _write_shape(shape: TopoDS_Shape) -> bytes:
     return stream.getvalue()
 
 
+_PACKED = b"SCZ1"
+"""Starts a payload stored compressed; entries written before it was
+introduced hold the BinTools bytes as they are, and are still read."""
+
+
+def _pack(raw: bytes) -> bytes:
+    # BinTools is bit-exact doubles: level 1 gets most of the ~10x for little time.
+    return _PACKED + zlib.compress(raw, 1)
+
+
+def _unpack(payload: bytes) -> bytes:
+    return zlib.decompress(payload[len(_PACKED) :]) if payload.startswith(_PACKED) else payload
+
+
 def _read_shape(payload: bytes) -> TopoDS_Shape:
     shape = TopoDS_Shape()
     BinTools.Read_s(shape, io.BytesIO(payload))
@@ -156,15 +172,55 @@ def _capture_states(wrapper: "AnyShape") -> Tuple[_EntityState, ...]:
     return tuple(states)
 
 
-def _find_entity(
-    cache: "_TopologyEntityCache", kind: str, shape: TopoDS_Shape
-) -> "_TopoEntity | None":
-    """Look an entity up without creating one (``cache.get`` would)."""
+def _entities_by_position(
+    cache: "_TopologyEntityCache", kind: str, shapes: TopTools_IndexedMapOfShape
+) -> Dict[int, "_TopoEntity"]:
+    """The entity of each position in *shapes* (``FindIndex`` is ``IsSame``),
+    found in one pass rather than one scan per position."""
 
+    found: Dict[int, "_TopoEntity"] = {}
     for entity in cache.entities(kind):
-        if entity.representative.IsSame(shape):
-            return entity
-    return None
+        position = shapes.FindIndex(entity.representative)
+        if position > 0:
+            found.setdefault(position, entity)
+    return found
+
+
+def _refresh_restored_tags(wrapper: "AnyShape") -> None:
+    """Rebuild the tag cache of every wrapper under *wrapper*, once each.
+
+    The restored tree has no ancestors above *wrapper*.  When none of its
+    bindings is passed downward, an entity's effective tags are its own
+    (local and legacy) and need no walk up through its parents; otherwise
+    the general refresh runs.
+    """
+
+    from ..core import TaggedMixin, TopologyPropagation
+
+    members: List[Any] = []
+    seen: Set[int] = set()
+    stack: List[Any] = [wrapper]
+    while stack:
+        item = stack.pop()
+        if id(item) in seen:
+            continue
+        seen.add(id(item))
+        members.append(item)
+        stack.extend(item.get_children())
+    tagged = [item for item in members if isinstance(item, TaggedMixin)]
+    if any(
+        binding.propagation.topology == TopologyPropagation.DOWNWARD
+        for item in tagged
+        for binding in item._local_tag_bindings()
+    ):
+        wrapper._refresh_tag_cache(recursive=True)
+        return
+    for item in tagged:
+        item._tag_cache.clear()
+        item._tag_cache.update(
+            binding.tag
+            for binding in (*item._local_tag_bindings(), *item._legacy_effective_bindings())
+        )
 
 
 _TOPO_ID_RE = re.compile(r"^(?P<kind>[a-z]+)_(?P<index>\d+)$")
@@ -195,16 +251,18 @@ def _renumber(cache: "_TopologyEntityCache", restored: Set[int]) -> None:
 def _apply_states(wrapper: "AnyShape", states: Tuple[_EntityState, ...]) -> None:
     cache = wrapper._topology_cache
     maps: Dict[str, TopTools_IndexedMapOfShape] = {}
+    by_index: Dict[str, Dict[int, "_TopoEntity"]] = {}
     restored: Set[int] = set()
     for state in states:
         shapes = maps.get(state.kind)
         if shapes is None:
             shapes = maps[state.kind] = _index_map(wrapper.wrapped, state.kind)
+            by_index[state.kind] = _entities_by_position(cache, state.kind, shapes)
         if state.index > shapes.Extent():
             raise ValueError(
                 f"pickled {state.kind} #{state.index} is outside the restored shape"
             )
-        entity = _find_entity(cache, state.kind, shapes.FindKey(state.index))
+        entity = by_index[state.kind].get(state.index)
         if entity is None:
             continue
         entity.topo_id = state.topo_id
@@ -228,28 +286,118 @@ def _apply_states(wrapper: "AnyShape", states: Tuple[_EntityState, ...]) -> None
         entity.incident_edge_ids.update(state.incident_edge_ids)
         restored.add(id(entity))
     _renumber(cache, restored)
-    wrapper._refresh_tag_cache(recursive=True)
+    _refresh_restored_tags(wrapper)
 
 
 def reduce_shape(wrapper: "AnyShape") -> Tuple[Any, Tuple[Any, ...]]:
     """``__reduce__`` implementation shared by every topology wrapper."""
 
-    payload = source_bytes(wrapper) or _write_shape(wrapper.wrapped)
+    payload = _pack(source_bytes(wrapper) or _write_shape(wrapper.wrapped))
     return (restore_shape, (type(wrapper).__name__, payload, _capture_states(wrapper)))
 
 
+_PENDING = "_pending_restore"
+"""The ``__dict__`` key under which a restored shape that is not built yet
+keeps what it needs to be: ``(payload, states)``."""
+
+_build_lock = threading.RLock()
+_building = threading.local()
+_lazy_classes: Dict[type, type] = {}
+
+
+class _PendingShape:
+    """Behaviour of a restored shape that has not been built yet.
+
+    The instance is empty.  Its first attribute read or write builds it (the
+    kernel shape from its bytes, the wrapper tree, the saved state) and puts
+    its real class back, after which none of this is in the way.  Pickling it
+    again hands back what it was restored from.
+    """
+
+    def __getattr__(self, name: str) -> Any:
+        if not name.startswith("__"):
+            _build(self)
+            try:
+                return object.__getattribute__(self, name)
+            except AttributeError:
+                pass
+        raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        _build(self)
+        object.__setattr__(self, name, value)
+
+    def __reduce__(self) -> Tuple[Any, Tuple[Any, ...]]:
+        pending = self.__dict__.get(_PENDING)
+        if pending is None:
+            _build(self)
+            return type(self).__reduce__(self)
+        return (restore_shape, (_real_class(type(self)).__name__, *pending))
+
+
+def _real_class(cls: type) -> type:
+    return cls.__mro__[2] if _PendingShape in cls.__mro__ else cls
+
+
+def _lazy_class(wrapper_type: type) -> type:
+    lazy = _lazy_classes.get(wrapper_type)
+    if lazy is None:
+        # Same name as the real class, so a repr or a ``type(x).__name__``
+        # does not tell the two apart.
+        lazy = _lazy_classes[wrapper_type] = type(
+            wrapper_type.__name__, (_PendingShape, wrapper_type), {"__module__": wrapper_type.__module__}
+        )
+    return lazy
+
+
+def is_pending(wrapper: "AnyShape") -> bool:
+    """Whether *wrapper* was restored and nothing has used it yet."""
+
+    return _PENDING in wrapper.__dict__
+
+
+def _build(wrapper: Any) -> None:
+    """Build a pending shape; a no-op for one already built (or being built
+    by this thread: its own constructor reads its attributes)."""
+
+    if _PENDING not in wrapper.__dict__:
+        return
+    with _build_lock:
+        pending = wrapper.__dict__.get(_PENDING)
+        building = _building.__dict__.setdefault("ids", set())
+        if pending is None or id(wrapper) in building:
+            return
+        building.add(id(wrapper))
+        try:
+            payload, states = pending
+            payload = _unpack(payload)
+            real = _real_class(type(wrapper))
+            real.__init__(wrapper, _read_shape(payload))
+            remember_source_bytes(wrapper, payload)
+            _apply_states(wrapper, states)
+            del wrapper.__dict__[_PENDING]
+            wrapper.__class__ = real
+        finally:
+            building.discard(id(wrapper))
+
+
 def restore_shape(
     class_name: str, payload: bytes, states: Tuple[_EntityState, ...]
 ) -> "AnyShape":
-    """Unpickle target: rebuild the wrapper and re-apply entity state."""
+    """Unpickle target: a shape that is built when it is first used.
+
+    Most values a cell cache restores are never read by the cells that run
+    (they are only there so that the cell counts as done), and building one
+    (decoding the kernel shape, the wrapper tree, the saved state) is most of
+    the time restoring costs.
+    """
 
     from .. import core
 
     wrapper_type = getattr(core, class_name)
-    wrapper = wrapper_type(_read_shape(payload))
-    remember_source_bytes(wrapper, payload)
-    _apply_states(wrapper, states)
+    wrapper = wrapper_type.__new__(_lazy_class(wrapper_type))
+    object.__setattr__(wrapper, "__dict__", {_PENDING: (payload, states)})
     return wrapper
 
 
-__all__ = ["reduce_shape", "remember_source_bytes", "restore_shape", "source_bytes"]
+__all__ = ["is_pending", "reduce_shape", "remember_source_bytes", "restore_shape", "source_bytes"]

{simplecadapi-2.2.6 → simplecadapi-2.2.6.post1}/src/simplecadapi/addon/versions.py

@@ -5,6 +5,9 @@ Supported syntax — deliberately a small, documented subset:
 * versions are dot-separated numeric components with optional
   pre-release suffixes (``2.1.2``, ``2.0.4b2``); a suffix sorts before
   the same numeric component without one (``2.0.4b2 < 2.0.4``);
+* a trailing ``.postN`` component is a post-release (PEP 440): it sorts
+  after the release it follows and before the next one
+  (``2.2.6 < 2.2.6.post1 < 2.2.6.post2 < 2.2.7``);
 * ranges are comma-separated clauses with the operators
   ``== != >= <= > <``; a bare version means exact equality;
 * clauses must be jointly satisfiable (``>=2.1,<2.0`` is rejected).
@@ -21,6 +24,7 @@ from . import AddonError
 
 _CLAUSE_RE = re.compile(r"^(==|!=|>=|<=|>|<)?\s*([0-9][0-9A-Za-z.]*)$")
 _COMPONENT_RE = re.compile(r"^([0-9]+)([a-zA-Z][0-9A-Za-z]*)?$")
+_POST_RE = re.compile(r"^post([0-9]+)$")
 
 
 class VersionSpecError(AddonError):
@@ -34,6 +38,12 @@ def version_key(text: str) -> tuple[tuple[int, int, str], ...]:
         raise VersionSpecError("empty version literal")
     components: list[tuple[int, int, str]] = []
     for part in stripped.split("."):
+        post = _POST_RE.match(part)
+        if post is not None and components:
+            # after the release it follows (a missing component pads as (0, 1, "")),
+            # and in order among post-releases
+            components.append((int(post.group(1)), 2, ""))
+            continue
         match = _COMPONENT_RE.match(part)
         if match is None:
             raise VersionSpecError(

{simplecadapi-2.2.6 → simplecadapi-2.2.6.post1}/src/simplecadapi/core.py

@@ -940,9 +940,28 @@ class TopoMixein:
         if child not in self.children:
             self.children.append(child)
             child.set_parent(self.self_shape_ref)
-            if isinstance(child, TaggedMixin):
+            if isinstance(child, TaggedMixin) and self._may_pass_tags_down():
                 child._refresh_tag_cache(recursive=True)
 
+    def _may_pass_tags_down(self) -> bool:
+        """Whether a new child of this entity can inherit any tag from it.
+
+        A child's effective tags are its own plus what its ancestors pass
+        down; an entity that holds no downward binding, and has no ancestor
+        that does, adds nothing, and the child's tag cache stays right.  A
+        shape being built (or restored) has no ancestors yet, so this spares
+        refreshing the whole subtree for every child added.
+        """
+
+        if not isinstance(self, TaggedMixin):
+            return True
+        if any(
+            binding.propagation.topology == TopologyPropagation.DOWNWARD
+            for binding in self._local_tag_bindings()
+        ):
+            return True
+        return bool(self._inherited_tag_bindings_with_paths())
+
     def get_children(self) -> List["AnyShape"]:
         return self.children