py2pd 0.2.1__tar.gz → 0.2.3__tar.gz

{py2pd-0.2.1 → py2pd-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2pd
-Version: 0.2.1
+Version: 0.2.3
 Summary: Roundtrip parsing and generation of pure-data patches from python
 Keywords: puredata,pd,audio,dsp,music,synthesis,patching
 Author: Shakeeb Alireza
@@ -483,4 +483,4 @@ from py2pd import (
 
 `PdConnectionError` is raised eagerly by `link()` when outlet or inlet indices exceed the node's known I/O counts. `Node.__getitem__` (e.g., `osc[2]`) raises `ValueError` for out-of-range outlet indices. Both checks are skipped for objects with unknown counts (`num_outlets=None` / `num_inlets=None`), and `link()` warns instead of raising when the patch was created with `validate_links=False`.
 
-`to_builder()` issues `UnsupportedElementWarning` (from `py2pd.ast`) for any statement the Builder cannot represent, rather than dropping patch content silently.
+`to_builder()` issues `UnsupportedElementWarning` (from `py2pd.ast`) for a connection it cannot rebuild, rather than dropping patch content silently. Statements the Builder does not model are carried verbatim instead of warned about, so `parse -> to_builder -> from_builder -> serialize` returns the bytes it started with.

{py2pd-0.2.1 → py2pd-0.2.3}/README.md

@@ -451,4 +451,4 @@ from py2pd import (
 
 `PdConnectionError` is raised eagerly by `link()` when outlet or inlet indices exceed the node's known I/O counts. `Node.__getitem__` (e.g., `osc[2]`) raises `ValueError` for out-of-range outlet indices. Both checks are skipped for objects with unknown counts (`num_outlets=None` / `num_inlets=None`), and `link()` warns instead of raising when the patch was created with `validate_links=False`.
 
-`to_builder()` issues `UnsupportedElementWarning` (from `py2pd.ast`) for any statement the Builder cannot represent, rather than dropping patch content silently.
+`to_builder()` issues `UnsupportedElementWarning` (from `py2pd.ast`) for a connection it cannot rebuild, rather than dropping patch content silently. Statements the Builder does not model are carried verbatim instead of warned about, so `parse -> to_builder -> from_builder -> serialize` returns the bytes it started with.

{py2pd-0.2.1 → py2pd-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "py2pd"
-version = "0.2.1"
+version = "0.2.3"
 description = "Roundtrip parsing and generation of pure-data patches from python"
 readme = "README.md"
 requires-python = ">=3.13"

{py2pd-0.2.1 → py2pd-0.2.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "py2pd"
-version = "0.2.1"
+version = "0.2.3"
 description = "Roundtrip parsing and generation of pure-data patches from python"
 readme = "README.md"
 requires-python = ">=3.13"

{py2pd-0.2.1 → py2pd-0.2.3}/src/py2pd/__init__.py

@@ -1,92 +1,94 @@
-"""
-py2pd - Python to PureData
-==========================
-
-Write PureData patches as Python programs.
-
-Builder API example:
-  >>> from py2pd import Patcher
-  >>> p = Patcher('patch.pd')
-  >>> osc = p.add('osc~ 440')
-  >>> dac = p.add('dac~')
-  >>> p.link(osc, dac)
-  >>> p.link(osc, dac, inlet=1)  # stereo
-  >>> p.save()
-
-AST API example (round-trip):
-  >>> from py2pd import parse_file, serialize
-  >>> ast = parse_file('input.pd')
-  >>> # Modify the AST...
-  >>> with open('output.pd', 'w') as f:
-  ...     f.write(serialize(ast))
-"""
-
-from .api import (
-    COLUMN_WIDTH,
-    DEFAULT_MARGIN,
-    ROW_HEIGHT,
-    SUBPATCH_CANVAS_HEIGHT,
-    SUBPATCH_CANVAS_WIDTH,
-    Abstraction,
-    CycleWarning,
-    GridLayoutManager,
-    InvalidConnectionError,
-    LayoutManager,
-    NodeNotFoundError,
-    Patcher,
-    PdConnectionError,
-    PdConnectionWarning,
-    lookup_object_io,
-)
-from .ast import (
-    ParseError,
-    UnsupportedElementWarning,
-    from_builder,
-    parse,
-    parse_file,
-    serialize,
-    serialize_to_file,
-    to_builder,
-)
-from .discover import (
-    default_search_paths,
-    discover_externals,
-    extract_declare_paths,
-)
-
-__all__ = [
-    # Builder API
-    "Patcher",
-    "Abstraction",
-    "LayoutManager",
-    "GridLayoutManager",
-    # Exceptions
-    "PdConnectionError",
-    "NodeNotFoundError",
-    "InvalidConnectionError",
-    "CycleWarning",
-    "PdConnectionWarning",
-    "UnsupportedElementWarning",
-    "ParseError",
-    # Object registry
-    "lookup_object_io",
-    # Layout constants
-    "ROW_HEIGHT",
-    "COLUMN_WIDTH",
-    "DEFAULT_MARGIN",
-    "SUBPATCH_CANVAS_WIDTH",
-    "SUBPATCH_CANVAS_HEIGHT",
-    # AST functions
-    "parse",
-    "parse_file",
-    "serialize",
-    "serialize_to_file",
-    "from_builder",
-    "to_builder",
-    # Discovery
-    "discover_externals",
-    "default_search_paths",
-    "extract_declare_paths",
-]
-
-__version__ = "0.2.1"
+"""
+py2pd - Python to PureData
+==========================
+
+Write PureData patches as Python programs.
+
+Builder API example:
+  >>> from py2pd import Patcher
+  >>> p = Patcher('patch.pd')
+  >>> osc = p.add('osc~ 440')
+  >>> dac = p.add('dac~')
+  >>> p.link(osc, dac)
+  >>> p.link(osc, dac, inlet=1)  # stereo
+  >>> p.save()
+
+AST API example (round-trip):
+  >>> from py2pd import parse_file, serialize
+  >>> ast = parse_file('input.pd')
+  >>> # Modify the AST...
+  >>> with open('output.pd', 'w') as f:
+  ...     f.write(serialize(ast))
+"""
+
+from .api import (
+    COLUMN_WIDTH,
+    DEFAULT_MARGIN,
+    ROW_HEIGHT,
+    SUBPATCH_CANVAS_HEIGHT,
+    SUBPATCH_CANVAS_WIDTH,
+    Abstraction,
+    CycleWarning,
+    GridLayoutManager,
+    InvalidConnectionError,
+    LayoutManager,
+    NodeNotFoundError,
+    Patcher,
+    PdConnectionError,
+    PdConnectionWarning,
+    SubpatchIOOrderWarning,
+    lookup_object_io,
+)
+from .ast import (
+    ParseError,
+    UnsupportedElementWarning,
+    from_builder,
+    parse,
+    parse_file,
+    serialize,
+    serialize_to_file,
+    to_builder,
+)
+from .discover import (
+    default_search_paths,
+    discover_externals,
+    extract_declare_paths,
+)
+
+__all__ = [
+    # Builder API
+    "Patcher",
+    "Abstraction",
+    "LayoutManager",
+    "GridLayoutManager",
+    # Exceptions
+    "PdConnectionError",
+    "NodeNotFoundError",
+    "InvalidConnectionError",
+    "CycleWarning",
+    "PdConnectionWarning",
+    "SubpatchIOOrderWarning",
+    "UnsupportedElementWarning",
+    "ParseError",
+    # Object registry
+    "lookup_object_io",
+    # Layout constants
+    "ROW_HEIGHT",
+    "COLUMN_WIDTH",
+    "DEFAULT_MARGIN",
+    "SUBPATCH_CANVAS_WIDTH",
+    "SUBPATCH_CANVAS_HEIGHT",
+    # AST functions
+    "parse",
+    "parse_file",
+    "serialize",
+    "serialize_to_file",
+    "from_builder",
+    "to_builder",
+    # Discovery
+    "discover_externals",
+    "default_search_paths",
+    "extract_declare_paths",
+]
+
+__version__ = "0.2.3"

{py2pd-0.2.1 → py2pd-0.2.3}/src/py2pd/api.py

@@ -4,6 +4,10 @@ import re
 from typing import Any, Callable, Dict, FrozenSet, List, Optional, Sequence, Set, Tuple, Union
 import warnings
 
+# The builder writes the same number format as the AST serializer, so it uses
+# the same helper. ast imports api only lazily, so this direction does not cycle.
+from .ast import PdCoords, PdDeclare, _fmt_num
+
 # Layout constants (pixels)
 ROW_HEIGHT = 25
 COLUMN_WIDTH = 50
@@ -53,6 +57,12 @@ class CycleWarning(UserWarning):
     pass
 
 
+class SubpatchIOOrderWarning(UserWarning):
+    """A subpatch's inlet or outlet order will not match creation order."""
+
+    pass
+
+
 class PdConnectionWarning(UserWarning):
     """Warning raised for an out-of-range connection when validation is advisory.
 
@@ -64,11 +74,65 @@ class PdConnectionWarning(UserWarning):
     pass
 
 
-def _fmt_coord(value: float) -> str:
-    """Format a coordinate the way PureData writes it -- integral values as integers."""
-    if isinstance(value, int) or float(value).is_integer():
-        return str(int(value))
-    return repr(float(value))
+_IO_KINDS = (("inlet", ("inlet", "inlet~")), ("outlet", ("outlet", "outlet~")))
+
+
+def _subpatch_io_nodes(src: "Patcher", names: Tuple[str, str]) -> List["Obj"]:
+    """The inlet or outlet objects of *src*, in creation order."""
+    return [
+        n
+        for n in src.nodes
+        if isinstance(n, Obj) and n.parameters["text"].split()[:1] in ([names[0]], [names[1]])
+    ]
+
+
+def _order_subpatch_io(src: "Patcher") -> None:
+    """Spread a subpatch's inlet and outlet objects so PureData orders them by creation.
+
+    PureData derives a subpatch's inlet and outlet order from the x position of
+    the ``inlet`` / ``outlet`` objects, breaking a tie in reverse file order.
+    The default layout stacks every node at one x, so two inlets created in
+    order reach the parent reversed -- a patch that loads without complaint and
+    is wired backwards.
+
+    Only a tie is repaired, and only among objects the caller never positioned:
+    distinct positions already give an unambiguous order, and an explicit
+    ``x_pos`` is a decision to respect. Repositioning is by creation order, so
+    ``link(..., inlet=n)`` means the n-th ``inlet`` object created.
+    """
+    for _, names in _IO_KINDS:
+        nodes = _subpatch_io_nodes(src, names)
+        if len(nodes) < 2:
+            continue
+        xs = [n.parameters["x_pos"] for n in nodes]
+        if len(set(xs)) == len(xs):
+            continue  # already unambiguous
+        if any(id(n) in src._explicit_x for n in nodes):
+            continue  # the caller placed at least one; leave the layout alone
+        base = min(xs)
+        for i, node in enumerate(nodes):
+            node.parameters["x_pos"] = base + i * SUBPATCH_IO_SPACING
+
+
+def _warn_on_ambiguous_subpatch_io(src: "Patcher", name: str) -> None:
+    """Warn when a subpatch's inlet or outlet order will not match creation order.
+
+    PureData orders a subpatch's inlets and outlets by the x position of the
+    ``inlet`` / ``outlet`` objects inside it, and breaks a tie in reverse file
+    order. The default layout stacks every node at the same x, so two inlets
+    created in order arrive at the parent reversed -- a patch that loads
+    without complaint and is wired wrong.
+    """
+    for kind, names in _IO_KINDS:
+        xs = [n.parameters["x_pos"] for n in _subpatch_io_nodes(src, names)]
+        if len(xs) > 1 and len(set(xs)) != len(xs):
+            warnings.warn(
+                f"subpatch {name!r} has {len(xs)} {kind}s sharing an x position; "
+                f"PureData orders them by x and will not use creation order. "
+                f"Give each {kind} a distinct x_pos to fix the order.",
+                SubpatchIOOrderWarning,
+                stacklevel=3,
+            )
 
 
 def escape(text: str) -> str:
@@ -157,6 +221,20 @@ class Node:
     hidden: bool = False
     num_inlets: Optional[int] = None
     num_outlets: Optional[int] = None
+    # A carried statement that followed the #X connect lines in the file it was
+    # read from, and so must be written back after them.
+    after_connections: bool = False
+
+    @property
+    def occupies_connect_index(self) -> bool:
+        """Whether PureData counts this node when numbering ``#X connect``.
+
+        Almost everything does. ``#X declare``, ``#A`` array data and ``#X f``
+        box widths are statements rather than objects, so they sit in the node
+        list without taking an index; a node that returns False here shifts no
+        connection.
+        """
+        return True
 
     class Outlet:
         """Reference to a specific outlet of a Node, used for creating connections."""
@@ -399,6 +477,7 @@ class Float(Node):
         send: str = "-",
         num_inlets: Optional[int] = 1,
         num_outlets: Optional[int] = 1,
+        font_size: Optional[int] = None,
     ) -> None:
         self.parameters = {
             "x_pos": x_pos,
@@ -410,16 +489,18 @@ class Float(Node):
             "label": label,
             "receive": receive,
             "send": send,
+            "font_size": font_size,
         }
         self.num_inlets = num_inlets
         self.num_outlets = num_outlets
 
     def __str__(self) -> str:
         p = self.parameters
+        tail = "" if p["font_size"] is None else f" {p['font_size']}"
         return (
             f"#X floatatom {p['x_pos']} {p['y_pos']} {p['width']} "
-            f"{p['lower_limit']} {p['upper_limit']} {p['label_pos']} "
-            f"{p['label']} {p['receive']} {p['send']};\n"
+            f"{_fmt_num(p['lower_limit'])} {_fmt_num(p['upper_limit'])} {p['label_pos']} "
+            f"{p['label']} {p['receive']} {p['send']}{tail};\n"
         )
 
     @property
@@ -469,6 +550,9 @@ class Comment(Node):
 
 
 # Default subpatch canvas dimensions (pixels)
+# Horizontal gap applied when spreading a subpatch's inlet/outlet objects so
+# PureData orders them by creation rather than by an arbitrary tie-break.
+SUBPATCH_IO_SPACING = 70
 SUBPATCH_CANVAS_WIDTH = 300
 SUBPATCH_CANVAS_HEIGHT = 180
 
@@ -543,6 +627,12 @@ class Subpatch(Node):
         is_graph: bool = False,
         gop_rect: Tuple[float, float, float, float] = (0, 1, 1, 0),
         gop_margins: Optional[Tuple[int, int]] = (0, 0),
+        canvas_x: int = 0,
+        canvas_y: int = 0,
+        canvas_name: str = "(subpatch)",
+        canvas_font_size: int = 10,
+        open_on_load: int = 0,
+        restore_kind: Optional[str] = None,
     ) -> None:
         """Create a subpatch node.
 
@@ -600,6 +690,12 @@ class Subpatch(Node):
             "is_graph": is_graph,
             "gop_rect": gop_rect,
             "gop_margins": gop_margins,
+            "canvas_x": canvas_x,
+            "canvas_y": canvas_y,
+            "canvas_name": canvas_name,
+            "canvas_font_size": canvas_font_size,
+            "open_on_load": open_on_load,
+            "restore_kind": restore_kind,
         }
         self.num_inlets = num_inlets
         self.num_outlets = num_outlets
@@ -607,23 +703,28 @@ class Subpatch(Node):
     def __str__(self) -> str:
         p = self.parameters
         coords_line = ""
-        if p["graph_on_parent"]:
+        carries_own_coords = any(isinstance(n, Coords) for n in self.src.nodes)
+        if p["graph_on_parent"] and not carries_own_coords:
             # PureData encodes "hide object name and arguments" in the
             # graph-on-parent flag itself: 1 = shown, 2 = hidden. There is no
             # separate field, and the two values after the flag are the
             # viewport margins.
             gop_flag = 2 if p["hide_name"] else 1
-            rect = " ".join(_fmt_coord(v) for v in p.get("gop_rect", (0, 1, 1, 0)))
+            rect = " ".join(_fmt_num(v) for v in p.get("gop_rect", (0, 1, 1, 0)))
             margins = p.get("gop_margins", (0, 0))
             tail = "" if margins is None else f" {margins[0]} {margins[1]}"
             coords_line = f"#X coords {rect} {p['gop_width']} {p['gop_height']} {gop_flag}{tail};\n"
-        restore = (
-            f"#X restore {p['x_pos']} {p['y_pos']} graph;\n"
-            if p.get("is_graph")
-            else f"#X restore {p['x_pos']} {p['y_pos']} pd {p['name']};\n"
-        )
+        # A parsed subpatch keeps the kind PureData wrote ("page" and others
+        # exist); one the builder created derives it from is_graph. A graph
+        # canvas closes without a name.
+        kind = p.get("restore_kind") or ("graph" if p.get("is_graph") else "pd")
+        name = "" if kind == "graph" else p["name"]
+        suffix = f" {name}" if name else ""
+        restore = f"#X restore {p['x_pos']} {p['y_pos']} {kind}{suffix};\n"
         return (
-            f"#N canvas 0 0 {self.canvas_width} {self.canvas_height} (subpatch) 0;\n"
+            f"#N canvas {p['canvas_x']} {p['canvas_y']} "
+            f"{self.canvas_width} {self.canvas_height} "
+            f"{p['canvas_name']} {p['open_on_load']};\n"
             f"{self.src._subpatch_str()}"
             f"{coords_line}"
             f"{restore}"
@@ -778,6 +879,89 @@ class Array(Node):
         return f"Array({p['name']!r}, {p['length']})"
 
 
+class Raw(Node):
+    """A statement py2pd has no builder node for, carried verbatim.
+
+    ``#X scalar``, ``#X listbox``, ``#A`` array data and ``#X f`` box widths
+    have no builder representation, but a patch read with ``to_builder()`` must
+    still write back what it read. The text is stored exactly as parsed.
+
+    Parameters
+    ----------
+    text : str
+        The statement without its trailing semicolon.
+    is_object : bool
+        Whether PureData counts the statement as an object on the canvas, which
+        decides whether it takes a ``#X connect`` index.
+    """
+
+    def __init__(self, text: str, is_object: bool = False) -> None:
+        self.hidden = True
+        self.parameters = {"text": text, "is_object": is_object}
+        self.num_inlets = None
+        self.num_outlets = None
+
+    @property
+    def occupies_connect_index(self) -> bool:
+        return bool(self.parameters["is_object"])
+
+    def __str__(self) -> str:
+        return f"{self.parameters['text']};\n"
+
+    def __repr__(self) -> str:
+        return f"Raw({self.parameters['text'][:40]!r})"
+
+
+class Declare(Node):
+    """A ``#X declare`` statement (search paths and libraries).
+
+    Wraps the AST's ``PdDeclare`` rather than re-modelling it, so the builder
+    writes back exactly what the parser read and ``extract_declare_paths()``
+    keeps working on a patch that went through the builder.
+    """
+
+    def __init__(self, declare: "PdDeclare") -> None:
+        self.hidden = True
+        self.parameters = {"declare": declare}
+        self.num_inlets = 0
+        self.num_outlets = 0
+
+    @property
+    def occupies_connect_index(self) -> bool:
+        return False
+
+    def __str__(self) -> str:
+        return f"{self.parameters['declare']}\n"
+
+    def __repr__(self) -> str:
+        return f"Declare({self.parameters['declare']!r})"
+
+
+class Coords(Node):
+    """An ``#X coords`` statement that no subpatch consumed.
+
+    A subpatch folds its own ``#X coords`` into graph-on-parent parameters. One
+    on the top-level canvas, or a second one inside a subpatch, has nowhere to
+    go, so it is carried as its parsed ``PdCoords``.
+    """
+
+    def __init__(self, coords: "PdCoords") -> None:
+        self.hidden = True
+        self.parameters = {"coords": coords}
+        self.num_inlets = 0
+        self.num_outlets = 0
+
+    @property
+    def occupies_connect_index(self) -> bool:
+        return False
+
+    def __str__(self) -> str:
+        return f"{self.parameters['coords']}\n"
+
+    def __repr__(self) -> str:
+        return f"Coords({self.parameters['coords']!r})"
+
+
 # An IEM GUI colour is either a legacy packed negative integer (PureData < 0.47)
 # or a hex string such as ``#fcfcfc`` (PureData >= 0.47). Both are accepted and
 # written out unchanged.
@@ -976,6 +1160,7 @@ class Symbol(Node):
         label: str = "-",
         receive: str = "-",
         send: str = "-",
+        font_size: Optional[int] = None,
     ) -> None:
         self.parameters = {
             "x_pos": x_pos,
@@ -987,16 +1172,18 @@ class Symbol(Node):
             "label": label,
             "receive": receive,
             "send": send,
+            "font_size": font_size,
         }
         self.num_inlets = 1
         self.num_outlets = 1
 
     def __str__(self) -> str:
         p = self.parameters
+        tail = "" if p["font_size"] is None else f" {p['font_size']}"
         return (
             f"#X symbolatom {p['x_pos']} {p['y_pos']} {p['width']} "
-            f"{p['lower_limit']} {p['upper_limit']} {p['label_pos']} "
-            f"{p['label']} {p['receive']} {p['send']};\n"
+            f"{_fmt_num(p['lower_limit'])} {_fmt_num(p['upper_limit'])} {p['label_pos']} "
+            f"{p['label']} {p['receive']} {p['send']}{tail};\n"
         )
 
     @property
@@ -1073,11 +1260,11 @@ class NumberBox(Node):
         p = self.parameters
         return (
             f"#X obj {p['x_pos']} {p['y_pos']} nbx {p['width']} {p['height']} "
-            f"{p['min_val']} {p['max_val']} {p['log_flag']} {p['init']} "
+            f"{_fmt_num(p['min_val'])} {_fmt_num(p['max_val'])} {p['log_flag']} {p['init']} "
             f"{p['send']} {p['receive']} {p['label']} "
             f"{p['label_x']} {p['label_y']} {p['font']} {p['font_size']} "
             f"{p['bg_color']} {p['fg_color']} {p['label_color']} "
-            f"{p['init_value']} {p['log_height']};\n"
+            f"{_fmt_num(p['init_value'])} {p['log_height']};\n"
         )
 
     @property
@@ -1151,11 +1338,11 @@ class VSlider(Node):
         p = self.parameters
         return (
             f"#X obj {p['x_pos']} {p['y_pos']} vsl {p['width']} {p['height']} "
-            f"{p['min_val']} {p['max_val']} {p['log_flag']} {p['init']} "
+            f"{_fmt_num(p['min_val'])} {_fmt_num(p['max_val'])} {p['log_flag']} {p['init']} "
             f"{p['send']} {p['receive']} {p['label']} "
             f"{p['label_x']} {p['label_y']} {p['font']} {p['font_size']} "
             f"{p['bg_color']} {p['fg_color']} {p['label_color']} "
-            f"{p['init_value']} {p['steady']};\n"
+            f"{_fmt_num(p['init_value'])} {p['steady']};\n"
         )
 
     @property
@@ -1226,11 +1413,11 @@ class HSlider(Node):
         p = self.parameters
         return (
             f"#X obj {p['x_pos']} {p['y_pos']} hsl {p['width']} {p['height']} "
-            f"{p['min_val']} {p['max_val']} {p['log_flag']} {p['init']} "
+            f"{_fmt_num(p['min_val'])} {_fmt_num(p['max_val'])} {p['log_flag']} {p['init']} "
             f"{p['send']} {p['receive']} {p['label']} "
             f"{p['label_x']} {p['label_y']} {p['font']} {p['font_size']} "
             f"{p['bg_color']} {p['fg_color']} {p['label_color']} "
-            f"{p['init_value']} {p['steady']};\n"
+            f"{_fmt_num(p['init_value'])} {p['steady']};\n"
         )
 
     @property
@@ -2213,6 +2400,17 @@ class Patcher:
         self.canvas_height = canvas_height
         self.font_size = font_size
         self._node_positions: Dict[int, int] = {}
+        # Statements above the #N canvas line (#N struct and friends), carried
+        # verbatim so a parsed patch writes back what it read.
+        self.preamble: List[str] = []
+        # Set once a node that takes no #X connect index is added. While it is
+        # False the connect index is the list position, which is the common case.
+        self._has_unindexed = False
+        self._connect_prefix: List[int] = []
+        self._connect_prefix_len = -1
+        # Nodes whose x the caller set. Subpatch I/O ordering may reposition
+        # the others; it must never move one the caller placed.
+        self._explicit_x: Set[int] = set()
 
     @property
     def row_head(self) -> Optional[Node]:
@@ -2258,10 +2456,13 @@ class Patcher:
     ) -> Tuple[int, int, Callable[[Node], None]]:
         """Resolve position for a new element."""
         was_absolute = x_pos >= 0 and y_pos >= 0
+        x_was_given = x_pos >= 0
         computed_x, computed_y = self.layout.compute_position(new_row, new_col, x_pos, y_pos)
 
         def position_update(node: Node) -> None:
             self.layout.register_node(node, new_row, new_col, was_absolute)
+            if x_was_given:
+                self._explicit_x.add(id(node))
 
         return (computed_x, computed_y, position_update)
 
@@ -2492,6 +2693,12 @@ class Patcher:
         is_graph: bool = False,
         gop_rect: Tuple[float, float, float, float] = (0, 1, 1, 0),
         gop_margins: Optional[Tuple[int, int]] = (0, 0),
+        canvas_x: int = 0,
+        canvas_y: int = 0,
+        canvas_name: str = "(subpatch)",
+        canvas_font_size: int = 10,
+        open_on_load: int = 0,
+        restore_kind: Optional[str] = None,
     ) -> Subpatch:
         """Add a subpatch to the patch.
 
@@ -2576,6 +2783,9 @@ class Patcher:
                 and n.parameters["text"].split()[:1] in (["outlet"], ["outlet~"])
             )
 
+        _order_subpatch_io(src)
+        _warn_on_ambiguous_subpatch_io(src, name)
+
         x_pos, y_pos, pos_update = self._resolve_position(x_pos, y_pos, new_row, new_col)
         node = Subpatch(
             x_pos,
@@ -2593,6 +2803,12 @@ class Patcher:
             is_graph=is_graph,
             gop_rect=gop_rect,
             gop_margins=gop_margins,
+            canvas_x=canvas_x,
+            canvas_y=canvas_y,
+            canvas_name=canvas_name,
+            canvas_font_size=canvas_font_size,
+            open_on_load=open_on_load,
+            restore_kind=restore_kind,
         )
         self._register(node, pos_update)
         return node
@@ -2654,7 +2870,9 @@ class Patcher:
         self._register(node, pos_update)
         return node
 
-    def add_array(self, name: str, length: int) -> Array:
+    def add_array(
+        self, name: str, length: int, element_type: str = "float", save_flag: int = 0
+    ) -> Array:
         """Declare an array in the subpatch.
 
         Parameters
@@ -2665,6 +2883,12 @@ class Patcher:
         length : int
             the array length
 
+        element_type : str
+            the array's data type (default ``'float'``)
+
+        save_flag : int
+            whether PureData saves the contents with the patch (default 0)
+
         Returns
         -------
         node : Array
@@ -2672,9 +2896,9 @@ class Patcher:
 
         Notes
         -----
-        The array will not have a graph. Its contents are not stored.
+        The array will not have a graph.
         """
-        node = Array(name, length)
+        node = Array(name, length, element_type, save_flag)
         self._register(node)
         return node
 
@@ -3359,8 +3583,8 @@ class Patcher:
             outlet = source.index
             source = source.owner
 
-        source_index = self._index_of(source, "Source")
-        sink_index = self._index_of(sink, "Sink")
+        source_index = self._connect_index_of(source, "Source")
+        sink_index = self._connect_index_of(sink, "Sink")
 
         if outlet < 0:
             raise PdConnectionError(f"Outlet index must be non-negative, got {outlet}")
@@ -3380,6 +3604,62 @@ class Patcher:
 
         self.connections.append(Connection(source_index, outlet, sink_index, inlet))
 
+    def _connect_index_of(self, node: Node, role: str) -> int:
+        """Return *node*'s ``#X connect`` index.
+
+        Equal to the list position until a node that takes no index is added,
+        after which it is the count of index-taking nodes before it. The prefix
+        sums are cached against the node count, so the link pass over a parsed
+        patch rebuilds them once rather than per connection.
+        """
+        position = self._index_of(node, role)
+        if not self._has_unindexed:
+            return position
+        if self._connect_prefix_len != len(self.nodes):
+            prefix: List[int] = []
+            count = 0
+            for existing in self.nodes:
+                prefix.append(count)
+                if existing.occupies_connect_index:
+                    count += 1
+            self._connect_prefix = prefix
+            self._connect_prefix_len = len(self.nodes)
+        return self._connect_prefix[position]
+
+    def add_raw(self, text: str, is_object: bool = False, after_connections: bool = False) -> Raw:
+        """Append a statement the builder does not model, written back verbatim.
+
+        Parameters
+        ----------
+        text : str
+            The statement without its trailing semicolon.
+        is_object : bool
+            Whether PureData counts it as an object, and so whether it takes a
+            ``#X connect`` index.
+        """
+        node = Raw(text, is_object)
+        node.after_connections = after_connections
+        if not node.occupies_connect_index:
+            self._has_unindexed = True
+        self._register(node)
+        return node
+
+    def add_declare(self, declare: PdDeclare, after_connections: bool = False) -> Declare:
+        """Append a ``#X declare`` statement, written back verbatim."""
+        node = Declare(declare)
+        node.after_connections = after_connections
+        self._has_unindexed = True
+        self._register(node)
+        return node
+
+    def add_coords(self, coords: PdCoords, after_connections: bool = False) -> Coords:
+        """Append an ``#X coords`` statement no subpatch consumed."""
+        node = Coords(coords)
+        node.after_connections = after_connections
+        self._has_unindexed = True
+        self._register(node)
+        return node
+
     def _index_of(self, node: Node, role: str) -> int:
         """Return *node*'s position in ``self.nodes``.
 
@@ -3415,20 +3695,27 @@ class Patcher:
     add_link = link
 
     def __str__(self) -> str:
+        preamble = "".join(f"{line};\n" for line in self.preamble)
         canvas = (
             f"#N canvas {self.canvas_x} {self.canvas_y} "
             f"{self.canvas_width} {self.canvas_height} {self.font_size};\n"
         )
-        return f"{canvas}{self._subpatch_str().rstrip()}"
+        return f"{preamble}{canvas}{self._subpatch_str().rstrip()}"
 
     def __repr__(self) -> str:
         return f"Patcher(nodes={len(self.nodes)}, connections={len(self.connections)})"
 
     def _subpatch_str(self) -> str:
-        """Internal: generate string for patch contents."""
-        nodes_str = "".join(str(n) for n in self.nodes)
+        """Internal: generate string for patch contents.
+
+        A statement read from after the ``#X connect`` block goes back there.
+        PureData writes canvas properties such as ``#X coords`` below the
+        connections, and moving one above them changes the file it wrote.
+        """
+        nodes_str = "".join(str(n) for n in self.nodes if not n.after_connections)
         connections_str = "".join(str(c) for c in self.connections)
-        return f"{nodes_str}{connections_str}"
+        trailing_str = "".join(str(n) for n in self.nodes if n.after_connections)
+        return f"{nodes_str}{connections_str}{trailing_str}"
 
     def save(
         self,

{py2pd-0.2.1 → py2pd-0.2.3}/src/py2pd/ast.py

@@ -782,10 +782,10 @@ class ParseError(Exception):
 class UnsupportedElementWarning(UserWarning):
     """Warning issued when converting to the builder API would lose an element.
 
-    The builder models the common subset of the file format. Statements it has
-    no node for -- data structure templates, scalars, array data, box widths --
-    survive in the AST but cannot be carried into a ``Patcher``. Parse and
-    serialize through :func:`parse` / :func:`serialize` to keep them.
+    Statements the builder does not model -- data structure templates, scalars,
+    array data, box widths -- are carried verbatim by ``Raw``, ``Declare`` and
+    ``Coords`` nodes, so they no longer raise this. It is left for a connection
+    whose endpoint has no builder node at all.
     """
 
     pass
@@ -1512,13 +1512,16 @@ def from_builder(patch: "api.Patcher") -> PdPatch:
         patch.font_size,
     )
     elements: List[PdElement] = []
+    # Carried statements PureData wrote below the #X connect block.
+    trailing: List[PdElement] = []
 
     for node in patch.nodes:
         if isinstance(node, api.Obj):
-            text = node.parameters["text"]
-            parts = text.split(None, 1)
-            class_name = parts[0] if parts else ""
-            args = tuple(parts[1].split()) if len(parts) > 1 else ()
+            # The parser's tokenizer, not str.split(): a plain whitespace split
+            # eats an escaped trailing space, rewriting the object's last atom.
+            tokens = _tokenize(node.parameters["text"])
+            class_name = tokens[0] if tokens else ""
+            args = tuple(tokens[1:])
             pos = Position(node.parameters["x_pos"], node.parameters["y_pos"])
             elements.append(PdObj(pos, class_name, args))
 
@@ -1539,13 +1542,23 @@ def from_builder(patch: "api.Patcher") -> PdPatch:
                     p["width"],
                     p["lower_limit"],
                     p["upper_limit"],
-                    0,
+                    p["label_pos"],
                     p["label"],
                     p["receive"],
                     p["send"],
+                    p["font_size"],
                 )
             )
 
+        elif isinstance(node, (api.Raw, api.Declare, api.Coords)):
+            if isinstance(node, api.Raw):
+                carried: PdElement = PdRaw(node.parameters["text"], node.parameters["is_object"])
+            elif isinstance(node, api.Declare):
+                carried = node.parameters["declare"]
+            else:
+                carried = node.parameters["coords"]
+            (trailing if node.after_connections else elements).append(carried)
+
         elif isinstance(node, api.Array):
             p = node.parameters
             elements.append(PdArray(p["name"], p["length"], p["element_type"], p["save_flag"]))
@@ -1556,15 +1569,19 @@ def from_builder(patch: "api.Patcher") -> PdPatch:
             p = node.parameters
             pos = Position(p["x_pos"], p["y_pos"])
             subpatch_canvas = CanvasProperties(
-                0, 0, node.canvas_width, node.canvas_height, 10, "(subpatch)", 0
-            )
-            restore = (
-                PdRestore(pos, "", "graph")
-                if p.get("is_graph")
-                else PdRestore(pos, p["name"], "pd")
+                p["canvas_x"],
+                p["canvas_y"],
+                node.canvas_width,
+                node.canvas_height,
+                p["canvas_font_size"],
+                p["canvas_name"],
+                p["open_on_load"],
             )
+            kind = p.get("restore_kind") or ("graph" if p.get("is_graph") else "pd")
+            restore = PdRestore(pos, "" if kind == "graph" else p["name"], kind)
             inner_elements = list(inner_ast.elements)
-            if p["graph_on_parent"]:
+            carries_own_coords = any(isinstance(e, PdCoords) for e in inner_elements)
+            if p["graph_on_parent"] and not carries_own_coords:
                 rect = p.get("gop_rect", (0, 1, 1, 0))
                 margins = p.get("gop_margins", (0, 0))
                 inner_elements.append(
@@ -1641,6 +1658,7 @@ def from_builder(patch: "api.Patcher") -> PdPatch:
                     p["label"],
                     p["receive"],
                     p["send"],
+                    p["font_size"],
                 )
             )
 
@@ -1817,8 +1835,9 @@ def from_builder(patch: "api.Patcher") -> PdPatch:
     # Add connections
     for conn in patch.connections:
         elements.append(PdConnect(conn.source, conn.outlet_index, conn.sink, conn.inlet_index))
+    elements.extend(trailing)
 
-    return PdPatch(canvas, elements)
+    return PdPatch(canvas, elements, [PdRaw(line) for line in patch.preamble])
 
 
 def to_builder(ast: PdPatch) -> "api.Patcher":
@@ -1853,9 +1872,14 @@ def to_builder(ast: PdPatch) -> "api.Patcher":
         font_size=ast.canvas.font_size,
     )
 
+    patch.preamble = [raw.text for raw in ast.preamble]
+
     # First pass: create all nodes (non-connections)
     node_map: List[Optional[api.Node]] = []  # Track nodes for linking
     node: api.Node
+    # PureData writes canvas properties below the #X connect block. A carried
+    # statement remembers which side of it that block it came from.
+    seen_connect = False
     for elem in ast.elements:
         if isinstance(elem, PdObj):
             # elem.text is already in PureData's escaped form; escaping it a
@@ -1881,6 +1905,7 @@ def to_builder(ast: PdPatch) -> "api.Patcher":
                 label=elem.label,
                 receive=elem.receive,
                 send=elem.send,
+                font_size=elem.font_size,
             )
             patch.nodes.append(node)
             node_map.append(node)
@@ -1896,6 +1921,7 @@ def to_builder(ast: PdPatch) -> "api.Patcher":
                 label=elem.label,
                 receive=elem.receive,
                 send=elem.send,
+                font_size=elem.font_size,
             )
             patch.nodes.append(node)
             node_map.append(node)
@@ -1906,12 +1932,10 @@ def to_builder(ast: PdPatch) -> "api.Patcher":
             node_map.append(node)
 
         elif isinstance(elem, PdArray):
-            node = patch.add_array(elem.name, elem.size)
+            node = patch.add_array(elem.name, elem.size, elem.dtype, elem.save_flag)
             node_map.append(node)
 
         elif isinstance(elem, PdSubpatch):
-            # Recursively convert subpatch
-            inner_patch = to_builder(PdPatch(elem.canvas, elem.elements))
             name = elem.restore.name if elem.restore else "subpatch"
             pos = elem.restore.position if elem.restore else Position(0, 0)
             # Extract GOP settings from PdCoords if present
@@ -1934,6 +1958,10 @@ def to_builder(ast: PdPatch) -> "api.Patcher":
                         else (sub_elem.x_margin or 0, sub_elem.y_margin or 0)
                     )
                     break
+            # The folded coords stays in the recursion as a carried node: the
+            # writers below regenerate one only when the inner patch has none,
+            # which keeps a parsed coords at the line PureData wrote it on.
+            inner_patch = to_builder(PdPatch(elem.canvas, elem.elements))
             if elem.restore is not None and elem.restore.is_graph:
                 gop_kwargs["is_graph"] = True
             node = patch.add_subpatch(
@@ -1943,6 +1971,12 @@ def to_builder(ast: PdPatch) -> "api.Patcher":
                 y_pos=pos.y,
                 canvas_width=elem.canvas.width,
                 canvas_height=elem.canvas.height,
+                canvas_x=elem.canvas.x,
+                canvas_y=elem.canvas.y,
+                canvas_name=elem.canvas.name if elem.canvas.name is not None else "(subpatch)",
+                canvas_font_size=elem.canvas.font_size,
+                open_on_load=elem.canvas.open_on_load,
+                restore_kind=elem.restore.kind if elem.restore is not None else None,
                 **gop_kwargs,
             )
             node_map.append(node)
@@ -2155,26 +2189,26 @@ def to_builder(ast: PdPatch) -> "api.Patcher":
             node_map.append(node)
 
         elif isinstance(elem, PdRaw):
-            # The builder has no representation for these, so converting drops
-            # them. Say so rather than losing patch content silently; the AST
-            # API round-trips them intact.
-            kind = " ".join(elem.text.split()[:2]) or "?"
-            warnings.warn(
-                f"to_builder() cannot represent {kind!r} statements; "
-                f"dropping: {elem.text[:60]!r}. Use the AST API to preserve them.",
-                UnsupportedElementWarning,
-                stacklevel=2,
-            )
+            # The builder models no such statement, but it must still write back
+            # what it read, so the text is carried verbatim.
+            node = patch.add_raw(elem.text, elem.is_object, after_connections=seen_connect)
             # Only occupy a connect index if Pd counts the statement as an
             # object, otherwise every following index shifts.
             if elem.is_object:
-                node_map.append(None)
+                node_map.append(node)
+
+        elif isinstance(elem, PdDeclare):
+            # Not an object, so it consumes no connect index.
+            patch.add_declare(elem, after_connections=seen_connect)
+
+        elif isinstance(elem, PdCoords):
+            # A subpatch strips the coords it folds into its own parameters
+            # before recursing, so anything reaching here belongs to this canvas.
+            patch.add_coords(elem, after_connections=seen_connect)
 
-        elif isinstance(elem, (PdConnect, PdCoords, PdDeclare)):
-            # None of these is an object, so none consumes a connect index.
-            # Connections are handled in the second pass; coords are folded into
-            # the enclosing subpatch; declare has no builder equivalent.
-            pass
+        elif isinstance(elem, PdConnect):
+            # Not an object, and handled in the second pass.
+            seen_connect = True
 
         else:
             node_map.append(None)  # Placeholder for unknown elements
@@ -2231,7 +2265,7 @@ def transform(patch: PdPatch, transformer: ElementTransformer) -> PdPatch:
         if transformed is not None:
             new_elements.append(transformed)
 
-    return PdPatch(patch.canvas, new_elements)
+    return PdPatch(patch.canvas, new_elements, patch.preamble)
 
 
 def find_objects(patch: PdPatch, predicate: ElementPredicate) -> List[PdElement]:

{py2pd-0.2.1 → py2pd-0.2.3}/src/py2pd/discover.py

@@ -12,7 +12,7 @@ import sys
 from typing import Dict, List, Optional, Tuple
 
 from .api import _infer_abstraction_io
-from .ast import PdDeclare, PdElement, PdPatch, PdSubpatch
+from .ast import ParseError, PdDeclare, PdElement, PdPatch, PdSubpatch
 
 # Maps sys.platform prefix to recognized binary extensions for externals
 _EXTERNAL_EXTENSIONS = {
@@ -98,6 +98,7 @@ def discover_externals(
         Mapping of external name to (num_inlets, num_outlets).
         Binary externals have (None, None) since I/O cannot be inferred.
         First-found wins when the same name appears in multiple paths.
+        A ``.pd`` file that cannot be read or parsed is skipped.
     """
     paths: List[str] = []
     if search_paths:
@@ -130,7 +131,9 @@ def discover_externals(
                     try:
                         inlets, outlets = _infer_abstraction_io(full_path)
                         registry[name] = (inlets, outlets)
-                    except OSError:
+                    except (OSError, ParseError):
+                        # An unreadable or unparseable candidate is an unusable
+                        # candidate, not a reason to abandon the whole scan.
                         continue
                 continue
 

{py2pd-0.2.1 → py2pd-0.2.3}/src/py2pd/integrations/cypd.py

@@ -220,13 +220,13 @@ def validate_patch(
     TypeError
         If *patch* is not a ``Patcher`` or ``PdPatch``.
     """
-    _ensure_libpd()
-
-    import cypd
-
     content = _serialize_input(patch)
 
     with _libpd_lock:
+        _ensure_libpd()
+
+        import cypd
+
         return _validate_locked(
             cypd,
             content,