py2pd 0.2.0__tar.gz → 0.2.2__tar.gz

{py2pd-0.2.0 → py2pd-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2pd
-Version: 0.2.0
+Version: 0.2.2
 Summary: Roundtrip parsing and generation of pure-data patches from python
 Keywords: puredata,pd,audio,dsp,music,synthesis,patching
 Author: Shakeeb Alireza

{py2pd-0.2.0 → py2pd-0.2.2}/pyproject.toml

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

{py2pd-0.2.0 → py2pd-0.2.2}/pyproject.toml.orig

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

{py2pd-0.2.0 → py2pd-0.2.2}/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.0"
+"""
+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.2"

{py2pd-0.2.0 → py2pd-0.2.2}/src/py2pd/api.py

@@ -1,8 +1,13 @@
 from collections import deque
+from pathlib import Path
 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 _fmt_num
+
 # Layout constants (pixels)
 ROW_HEIGHT = 25
 COLUMN_WIDTH = 50
@@ -52,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.
 
@@ -63,18 +74,74 @@ 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:
     """Escape special characters for PureData format."""
     save = re.sub(r"\\", r"\\\\", text)
-    save = re.sub(r";", r" \; ", save)
-    save = re.sub(r",", r" \, ", save)
+    # Absorb whitespace already flanking the separator: PureData puts one space
+    # between atoms, and "0, 1 10" would otherwise gain a second one.
+    save = re.sub(r"[ \t]*;[ \t]*", r" \; ", save)
+    save = re.sub(r"[ \t]*,[ \t]*", r" \, ", save)
     save = re.sub(r"\$(?=[0-9])", r"\$", save)
     return save
 
@@ -310,7 +377,8 @@ class Msg(Node):
     text : str
         Message content. Will be escaped for the PureData file format.
     num_inlets : int, optional
-        Number of inlets (default: 2 -- hot inlet + cold inlet for setting contents)
+        Number of inlets (default: 1). A message box has one inlet; contents
+        are replaced by sending ``set ...`` to it, not through a second inlet.
     num_outlets : int, optional
         Number of outlets (default: 1)
     escaped : bool, optional
@@ -323,7 +391,7 @@ class Msg(Node):
         x_pos: int,
         y_pos: int,
         text: str,
-        num_inlets: Optional[int] = 2,
+        num_inlets: Optional[int] = 1,
         num_outlets: Optional[int] = 1,
         *,
         escaped: bool = False,
@@ -368,10 +436,12 @@ class Float(Node):
         Y position in patch coordinates
     width : int
         Display width in characters (default: 5)
-    upper_limit : float
-        Maximum value; 0 means no limit (default: 0)
     lower_limit : float
         Minimum value; 0 means no limit (default: 0)
+    upper_limit : float
+        Maximum value; 0 means no limit (default: 0)
+    label_pos : int
+        Label placement: 0=left, 1=right, 2=top, 3=bottom (default: 0)
     label : str
         Label text (default: ``'-'`` for none)
     receive : str
@@ -385,8 +455,9 @@ class Float(Node):
         x_pos: int,
         y_pos: int,
         width: int = 5,
-        upper_limit: float = 0,
         lower_limit: float = 0,
+        upper_limit: float = 0,
+        label_pos: int = 0,
         label: str = "-",
         receive: str = "-",
         send: str = "-",
@@ -397,8 +468,9 @@ class Float(Node):
             "x_pos": x_pos,
             "y_pos": y_pos,
             "width": width,
-            "upper_limit": upper_limit,
             "lower_limit": lower_limit,
+            "upper_limit": upper_limit,
+            "label_pos": label_pos,
             "label": label,
             "receive": receive,
             "send": send,
@@ -410,8 +482,8 @@ class Float(Node):
         p = self.parameters
         return (
             f"#X floatatom {p['x_pos']} {p['y_pos']} {p['width']} "
-            f"{p['upper_limit']} {p['lower_limit']} {p['label']} "
-            f"{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']};\n"
         )
 
     @property
@@ -461,6 +533,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
 
@@ -605,7 +680,7 @@ class Subpatch(Node):
             # 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"
@@ -987,7 +1062,7 @@ class Symbol(Node):
         p = self.parameters
         return (
             f"#X symbolatom {p['x_pos']} {p['y_pos']} {p['width']} "
-            f"{p['lower_limit']} {p['upper_limit']} {p['label_pos']} "
+            f"{_fmt_num(p['lower_limit'])} {_fmt_num(p['upper_limit'])} {p['label_pos']} "
             f"{p['label']} {p['receive']} {p['send']};\n"
         )
 
@@ -1065,11 +1140,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
@@ -1143,11 +1218,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
@@ -1218,11 +1293,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
@@ -2143,7 +2218,7 @@ class Patcher:
 
     Attributes
     ----------
-    filename : str or None
+    filename : Path or None
         Default filename for save()
     nodes : list of Node
         All nodes in the patch
@@ -2153,7 +2228,7 @@ class Patcher:
         Manages automatic element positioning
     """
 
-    filename: Optional[str]
+    filename: Optional[Path]
     nodes: List[Node]
     connections: List[Connection]
     layout: LayoutManager
@@ -2161,7 +2236,7 @@ class Patcher:
 
     def __init__(
         self,
-        filename: Optional[str] = None,
+        filename: Optional[Union[str, Path]] = None,
         layout: Optional[LayoutManager] = None,
         *,
         validate_links: bool = True,
@@ -2175,8 +2250,9 @@ class Patcher:
 
         Parameters
         ----------
-        filename : str, optional
-            Default filename for save(). Can be overridden in save().
+        filename : str or Path, optional
+            Default filename for save(), stored as a ``Path``. Can be
+            overridden in save().
         layout : LayoutManager, optional
             Custom layout manager. If None, creates a default LayoutManager.
         validate_links : bool, optional
@@ -2193,7 +2269,7 @@ class Patcher:
         font_size : int, optional
             Patch font size written on the ``#N canvas`` line (default: 10).
         """
-        self.filename = filename
+        self.filename = Path(filename) if filename is not None else None
         self.nodes = []
         self.connections = []
         self.layout = layout if layout is not None else LayoutManager()
@@ -2204,6 +2280,9 @@ class Patcher:
         self.canvas_height = canvas_height
         self.font_size = font_size
         self._node_positions: Dict[int, int] = {}
+        # 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]:
@@ -2249,10 +2328,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)
 
@@ -2412,8 +2494,9 @@ class Patcher:
         self,
         *,
         width: int = 5,
-        upper_limit: float = 0,
         lower_limit: float = 0,
+        upper_limit: float = 0,
+        label_pos: int = 0,
         label: str = "-",
         receive: str = "-",
         send: str = "-",
@@ -2428,10 +2511,12 @@ class Patcher:
         ----------
         width : int
             Display width in characters (default: 5)
-        upper_limit : int
-            Maximum value (0 = no limit)
         lower_limit : int
             Minimum value (0 = no limit)
+        upper_limit : int
+            Maximum value (0 = no limit)
+        label_pos : int
+            Label placement: 0=left, 1=right, 2=top, 3=bottom
         label : str
             Label text (default: '-' for none)
         receive : str
@@ -2445,7 +2530,17 @@ class Patcher:
             The created number box
         """
         x_pos, y_pos, pos_update = self._resolve_position(x_pos, y_pos, new_row, new_col)
-        node = Float(x_pos, y_pos, width, upper_limit, lower_limit, label, receive, send)
+        node = Float(
+            x_pos,
+            y_pos,
+            width=width,
+            lower_limit=lower_limit,
+            upper_limit=upper_limit,
+            label_pos=label_pos,
+            label=label,
+            receive=receive,
+            send=send,
+        )
         self._register(node, pos_update)
         return node
 
@@ -2554,6 +2649,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,
@@ -3408,23 +3506,36 @@ class Patcher:
         connections_str = "".join(str(c) for c in self.connections)
         return f"{nodes_str}{connections_str}"
 
-    def save(self, filename: Optional[str] = None) -> None:
+    def save(
+        self,
+        filename: Optional[Union[str, Path]] = None,
+        *,
+        to_dir: Optional[Union[str, Path]] = None,
+    ) -> None:
         """Save the patch to a file.
 
         Parameters
         ----------
-        filename : str, optional
+        filename : str or Path, optional
             Path to the output .pd file. If not provided, uses the filename
             from the constructor.
+        to_dir : str or Path, optional
+            Directory to write into, created if missing. Only the base name of
+            *filename* is used, so one patch can be written to several
+            directories.
 
         Raises
         ------
         ValueError
             If no filename is provided and none was set in constructor.
         """
-        fn = filename or self.filename
+        fn = Path(filename) if filename is not None else self.filename
         if fn is None:
             raise ValueError("No filename specified. Provide filename or set in constructor.")
+        if to_dir is not None:
+            d = Path(to_dir)
+            d.mkdir(parents=True, exist_ok=True)
+            fn = d / fn.name
         with open(fn, "w", encoding="utf-8", newline="\n") as f:
             f.write(str(self) + "\n")
 

{py2pd-0.2.0 → py2pd-0.2.2}/src/py2pd/ast.py

@@ -1874,12 +1874,13 @@ def to_builder(ast: PdPatch) -> "api.Patcher":
             node = api.Float(
                 elem.position.x,
                 elem.position.y,
-                elem.width,
-                elem.upper_limit,
-                elem.lower_limit,
-                elem.label,
-                elem.receive,
-                elem.send,
+                width=elem.width,
+                lower_limit=elem.lower_limit,
+                upper_limit=elem.upper_limit,
+                label_pos=elem.label_pos,
+                label=elem.label,
+                receive=elem.receive,
+                send=elem.send,
             )
             patch.nodes.append(node)
             node_map.append(node)

{py2pd-0.2.0 → py2pd-0.2.2}/src/py2pd/integrations/hvcc.py

@@ -28,6 +28,7 @@ Usage::
 from dataclasses import dataclass, field
 from enum import Enum
 import os
+from pathlib import Path
 import re
 import shutil
 import subprocess
@@ -425,7 +426,7 @@ class HeavyPatcher(Patcher):
 
     Parameters
     ----------
-    filename : str, optional
+    filename : str or Path, optional
         Default filename for save().
     layout : LayoutManager, optional
         Custom layout manager.
@@ -435,7 +436,7 @@ class HeavyPatcher(Patcher):
 
     def __init__(
         self,
-        filename: Optional[str] = None,
+        filename: Optional[Union[str, Path]] = None,
         layout: Optional[LayoutManager] = None,
         generators: Sequence[HvccGenerator] | None = None,
     ) -> None: