From 5d040061f41b77d8149ef0d37acde0a4be716059 Mon Sep 17 00:00:00 2001 From: jan Date: Mon, 16 Feb 2026 13:57:16 -0800 Subject: [PATCH] [set_dead] improve docs --- masque/builder/builder.py | 19 ++++++++++++++++--- masque/builder/pather.py | 12 ++++++++++++ masque/builder/renderpather.py | 12 ++++++++++++ masque/pattern.py | 11 +++++++++-- 4 files changed, 49 insertions(+), 5 deletions(-) diff --git a/masque/builder/builder.py b/masque/builder/builder.py index 3c39710..40ea109 100644 --- a/masque/builder/builder.py +++ b/masque/builder/builder.py @@ -275,6 +275,10 @@ class Builder(PortList): Returns: self + Note: + If the builder is 'dead' (see `set_dead()`), geometry generation is + skipped but ports are still updated. + Raises: `PortError` if any ports specified in `map_in` or `map_out` do not exist in `self.ports` or `other_names`. @@ -350,6 +354,10 @@ class Builder(PortList): Returns: self + Note: + If the builder is 'dead' (see `set_dead()`), geometry generation is + skipped but ports are still updated. + Raises: `PortError` if any ports specified in `map_in` or `map_out` do not exist in `self.ports` or `other.ports`. @@ -425,13 +433,18 @@ class Builder(PortList): def set_dead(self) -> Self: """ - Disallows further changes through `plug()` or `place()`. + Suppresses geometry generation for subsequent `plug()` and `place()` + operations. Unlike a complete skip, the port state is still tracked + and updated, using 'best-effort' fallbacks for impossible transforms. + This allows a layout script to execute through problematic sections + while maintaining valid port references for downstream code. + This is meant for debugging: ``` dev.plug(a, ...) dev.set_dead() # added for debug purposes - dev.plug(b, ...) # usually raises an error, but now skipped - dev.plug(c, ...) # also skipped + dev.plug(b, ...) # usually raises an error, but now uses fallback port update + dev.plug(c, ...) # also updated via fallback dev.pattern.visualize() # shows the device as of the set_dead() call ``` diff --git a/masque/builder/pather.py b/masque/builder/pather.py index d58b282..c23e240 100644 --- a/masque/builder/pather.py +++ b/masque/builder/pather.py @@ -285,6 +285,12 @@ class Pather(Builder, PatherMixin): Returns: self + Note: + If the builder is 'dead', this operation will still attempt to update + the target port's location. If the pathing tool fails (e.g. due to an + impossible length), a dummy linear extension is used to maintain port + consistency for downstream operations. + Raises: BuildError if `distance` is too small to fit the bend (if a bend is present). LibraryError if no valid name could be picked for the pattern. @@ -359,6 +365,12 @@ class Pather(Builder, PatherMixin): Returns: self + Note: + If the builder is 'dead', this operation will still attempt to update + the target port's location. If the pathing tool fails (e.g. due to an + impossible length), a dummy linear extension is used to maintain port + consistency for downstream operations. + Raises: BuildError if `distance` is too small to fit the s-bend (for nonzero jog). LibraryError if no valid name could be picked for the pattern. diff --git a/masque/builder/renderpather.py b/masque/builder/renderpather.py index 863f3f1..ca8cf8a 100644 --- a/masque/builder/renderpather.py +++ b/masque/builder/renderpather.py @@ -408,6 +408,12 @@ class RenderPather(PatherMixin): Returns: self + Note: + If the builder is 'dead', this operation will still attempt to update + the target port's location. If the pathing tool fails (e.g. due to an + impossible length), a dummy linear extension is used to maintain port + consistency for downstream operations. + Raises: BuildError if `distance` is too small to fit the bend (if a bend is present). LibraryError if no valid name could be picked for the pattern. @@ -486,6 +492,12 @@ class RenderPather(PatherMixin): Returns: self + Note: + If the builder is 'dead', this operation will still attempt to update + the target port's location. If the pathing tool fails (e.g. due to an + impossible length), a dummy linear extension is used to maintain port + consistency for downstream operations. + Raises: BuildError if `distance` is too small to fit the s-bend (for nonzero jog). LibraryError if no valid name could be picked for the pattern. diff --git a/masque/pattern.py b/masque/pattern.py index 04780ec..d7bbc01 100644 --- a/masque/pattern.py +++ b/masque/pattern.py @@ -1133,7 +1133,10 @@ class Pattern(PortList, AnnotatableImpl, Mirrorable): append: If `True`, `other` is appended instead of being referenced. Note that this does not flatten `other`, so its refs will still be refs (now inside `self`). - skip_geometry: If `True`, only ports are added; geometry is skipped. + skip_geometry: If `True`, the operation only updates the port list and + skips adding any geometry (shapes, labels, or references). This + allows the pattern assembly to proceed for port-tracking purposes + even when layout generation is suppressed. Returns: self @@ -1282,7 +1285,11 @@ class Pattern(PortList, AnnotatableImpl, Mirrorable): any other ptypte. Non-allowed ptype connections will emit a warning. Order is ignored, i.e. `(a, b)` is equivalent to `(b, a)`. - skip_geometry: If `True`, only ports are updated; geometry is skipped. + skip_geometry: If `True`, only ports are updated and geometry is + skipped. If a valid transform cannot be found (e.g. due to + misaligned ports), a 'best-effort' dummy transform is used + to ensure new ports are still added at approximate locations, + allowing downstream routing to continue. Returns: self