jan/masque
1
1
Fork 0
Code Issues Pull requests Releases Wiki Activity

[Builder / RenderPather] BREAKING remove aliases to old names

Browse source
This commit is contained in:
Jan Petykiewicz 2026-04-08 23:08:26 -07:00
commit 778b3d9be7
18 changed files with 131 additions and 153 deletions
Download patch file Download diff file Expand all files Collapse all files

2
masque/builder/__init__.py
View file

@ -1,8 +1,6 @@
from .pather import (
Pather as Pather,
PortPather as PortPather,
Builder as Builder,
RenderPather as RenderPather,
)
from .utils import ell as ell
from .tools import (

6
masque/builder/logging.py
View file

@ -1,5 +1,5 @@
"""
Logging and operation decorators for Builder/Pather
Logging and operation decorators for Pather
"""
from typing import TYPE_CHECKING, Any
from collections.abc import Iterator, Sequence, Callable
@ -31,7 +31,7 @@ def _format_log_args(**kwargs) -> str:
class PatherLogger:
"""
Encapsulates state for Pather/Builder diagnostic logging.
Encapsulates state for Pather diagnostic logging.
"""
debug: bool
indent: int
@ -90,7 +90,7 @@ def logged_op(
portspec_getter: Callable[[dict[str, Any]], str | Sequence[str] | None] | None = None,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
"""
Decorator to wrap Builder methods with logging.
Decorator to wrap Pather methods with logging.
"""
def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
sig = inspect.signature(func)

64
masque/builder/pather.py
View file

@ -38,11 +38,9 @@ class Pather(PortList):
The `Pather` holds context in the form of a `Library`, its underlying
pattern, and a set of `Tool`s for generating routing segments.
Routing operations (`trace`, `jog`, `uturn`, etc.) are by default
deferred: they record the intended path but do not immediately generate
geometry. `render()` must be called to generate the final layout.
Alternatively, setting `auto_render=True` in the constructor will
cause geometry to be generated incrementally after each routing step.
Routing operations (`trace`, `jog`, `uturn`, etc.) are rendered
incrementally by default. Set `auto_render=False` to defer geometry
generation until an explicit call to `render()`.
Examples: Creating a Pather
===========================
@ -58,8 +56,8 @@ class Pather(PortList):
connects port 'A' of the current pattern to port 'C' of `subdevice`.
- `pather.trace('my_port', ccw=True, length=100)` plans a 100-unit bend
starting at 'my_port'. If `auto_render=True`, geometry is added
immediately. Otherwise, call `pather.render()` later.
starting at 'my_port'. Geometry is added immediately by default.
Set `auto_render=False` to defer and call `pather.render()` later.
"""
__slots__ = (
'pattern', 'library', 'tools', 'paths',
@ -118,7 +116,7 @@ class Pather(PortList):
tools: Tool | MutableMapping[str | None, Tool] | None = None,
name: str | None = None,
debug: bool = False,
auto_render: bool = False,
auto_render: bool = True,
auto_render_append: bool = True,
) -> None:
"""
@ -1358,53 +1356,3 @@ class PortPather:
self.pather.rename_ports({name: None})
self.ports = [pp for pp in self.ports if pp != name]
return self
class Builder(Pather):
"""
Backward-compatible wrapper for Pather with auto_render=True.
"""
def __init__(
self,
library: ILibrary,
*,
pattern: Pattern | None = None,
ports: str | Mapping[str, Port] | None = None,
tools: Tool | MutableMapping[str | None, Tool] | None = None,
name: str | None = None,
debug: bool = False,
) -> None:
super().__init__(
library=library,
pattern=pattern,
ports=ports,
tools=tools,
name=name,
debug=debug,
auto_render=True,
)
class RenderPather(Pather):
"""
Backward-compatible wrapper for Pather with auto_render=False.
"""
def __init__(
self,
library: ILibrary,
*,
pattern: Pattern | None = None,
ports: str | Mapping[str, Port] | None = None,
tools: Tool | MutableMapping[str | None, Tool] | None = None,
name: str | None = None,
debug: bool = False,
) -> None:
super().__init__(
library=library,
pattern=pattern,
ports=ports,
tools=tools,
name=name,
debug=debug,
auto_render=False,
)

18
masque/builder/tools.py
View file

@ -25,8 +25,8 @@ from ..error import BuildError
@dataclass(frozen=True, slots=True)
class RenderStep:
"""
Representation of a single saved operation, used by `RenderPather` and passed
to `Tool.render()` when `RenderPather.render()` is called.
Representation of a single saved operation, used by deferred `Pather`
instances and passed to `Tool.render()` when `Pather.render()` is called.
"""
opcode: Literal['L', 'S', 'U', 'P']
""" What operation is being performed.
@ -128,7 +128,7 @@ class Tool:
Create a wire or waveguide that travels exactly `length` distance along the axis
of its input port.
Used by `Pather` and `RenderPather`.
Used by `Pather`.
The output port must be exactly `length` away along the input port's axis, but
may be placed an additional (unspecified) distance away along the perpendicular
@ -174,7 +174,7 @@ class Tool:
of its input port, and `jog` distance on the perpendicular axis.
`jog` is positive when moving left of the direction of travel (from input to ouput port).
Used by `Pather` and `RenderPather`.
Used by `Pather`.
The output port should be rotated to face the input port (i.e. plugging the device
into a port will move that port but keep its orientation).
@ -214,7 +214,7 @@ class Tool:
Plan a wire or waveguide that travels exactly `length` distance along the axis
of its input port.
Used by `RenderPather`.
Used by `Pather` when `auto_render=False`.
The output port must be exactly `length` away along the input port's axis, but
may be placed an additional (unspecified) distance away along the perpendicular
@ -266,7 +266,7 @@ class Tool:
Plan a wire or waveguide that travels exactly `length` distance along the axis
of its input port and `jog` distance along the perpendicular axis (i.e. an S-bend).
Used by `RenderPather`.
Used by `Pather` when `auto_render=False`.
The output port must have an orientation rotated by pi from the input port.
@ -315,7 +315,7 @@ class Tool:
Create a wire or waveguide that travels exactly `jog` distance along the axis
perpendicular to its input port (i.e. a U-bend).
Used by `Pather` and `RenderPather`. Tools may leave this unimplemented if they
Used by `Pather`. Tools may leave this unimplemented if they
do not support a native U-bend primitive.
The output port must have an orientation identical to the input port.
@ -354,7 +354,7 @@ class Tool:
Plan a wire or waveguide that travels exactly `jog` distance along the axis
perpendicular to its input port (i.e. a U-bend).
Used by `RenderPather`. This is an optional native-planning hook: tools may
Used by `Pather` when `auto_render=False`. This is an optional native-planning hook: tools may
implement it when they can represent a U-turn directly, otherwise they may rely
on `traceU()` or let `Pather` synthesize the route from simpler primitives.
@ -1323,7 +1323,7 @@ class PathTool(Tool, metaclass=ABCMeta):
# Transform the batch so the first port is local (at 0,0) but retains its global rotation.
# This allows the path to be rendered with its original orientation, simplified by
# translation to the origin. RenderPather.render will handle the final placement
# translation to the origin. Pather.render will handle the final placement
# (including rotation alignment) via `pat.plug`.
first_port = batch[0].start_port
translation = -first_port.offset