py2max 0.3.0__tar.gz → 0.3.1__tar.gz

{py2max-0.3.0 → py2max-0.3.1}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.3.1]
+
+### New: Standalone `gen.codebox~` Support
+
+- `Patcher.add_gen_codebox(code)` adds a self-contained `gen.codebox~` object -- a complete gen patch in a single box that lives directly in a regular Max patcher, distinct from the inner `codebox~` (emitted by `add_codebox`) that belongs inside a `gen~`/`rnbo~` subpatcher. This is the form emitted by gen transpilers. Code newlines are normalized to CRLF as Max expects, and `fontname`/`fontsize` default to the monospaced gen style.
+- Inlet/outlet counts are derived automatically from the code (the highest `inN` / `outN` references, floor of 1), matching gen's dynamic-I/O semantics. Explicit `numinlets` / `numoutlets` still override.
+- Available via the `add()` string shortcut too: `p.add("gen.codebox~ out1 = in1 * 0.5;")`. The shortcut suits single-line / `;`-terminated code; pass multi-line source to `add_gen_codebox()` directly.
+- Connection validation for `gen.codebox~` (and `codebox` / `codebox~`) now bound-checks against the box's own declared inlet/outlet counts rather than the static `.maxref.xml` entry, since codebox I/O is code-dependent. This both allows valid connections to/from wider codeboxes (e.g. from a second outlet) and rejects genuinely out-of-range ones.
+
 ## [0.3.0]
 
 ### Removed: Interactive Server Split Into `py2max-server` (breaking)

{py2max-0.3.0 → py2max-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2max
-Version: 0.3.0
+Version: 0.3.1
 Summary: A library for offline generation of Max/MSP patcher (.maxpat) files.
 Keywords: Max,maxpat,offline
 Author: Shakeeb Alireza
@@ -84,8 +84,38 @@ That's it! Open `my-synth.maxpat` in Max to see your patch.
 
 - **Offline Patch Generation** - Create Max patches programmatically without Max running
 - **Round-trip Conversion** - Load, modify, and save existing `.maxpat` files
+- **Max for Live (.amxd)** - Read/write binary `.amxd` device files with presentation-mode helpers
 - **Universal Object Support** - Works with any Max/MSP/Jitter object
-- **99% Test Coverage** - 418+ tests ensure reliability
+- **Fully typed** - Passes `mypy --strict`; no runtime dependencies
+- **High Test Coverage** - 420+ tests ensure reliability
+
+### Max for Live (.amxd)
+
+Generate Max for Live devices directly. `Patcher.save()` / `Patcher.from_file()`
+auto-detect the `.amxd` extension and read/write the binary device format,
+byte-for-byte compatible with Max-exported devices.
+
+```python
+from py2max import Patcher
+
+# device_type: "audio_effect" (default), "instrument", or "midi_effect"
+p = Patcher('gain.amxd', device_type='audio_effect')
+p.enable_presentation(devicewidth=120)        # render Ableton's device strip
+
+plugin = p.add_textbox('plugin~')             # audio in from Live
+gain = p.add('live.gain~', maxclass='live.gain~')
+plugout = p.add_textbox('plugout~')           # audio back to Live
+gain.add_to_presentation([20, 20, 60, 136])   # show the fader in the device
+
+p.add_line(plugin, gain, outlet=0, inlet=0)
+p.add_line(gain, plugout, outlet=0, inlet=0)
+p.save()                                       # writes a binary .amxd
+```
+
+Helpers: `Patcher.enable_presentation(devicewidth=...)`,
+`Box.add_to_presentation([x, y, w, h])` (rejects M4L infrastructure objects and
+rounds fractional coordinates), and `Patcher.enforce_integer_coords()`. M4L
+binary helpers live in `py2max.m4l`.
 
 ### Interactive Server (separate package)
 
@@ -252,6 +282,34 @@ p.link(sbox, dac)
 p.save()
 ```
 
+### Gen Codebox
+
+`add_gen_codebox()` adds a standalone `gen.codebox~` object -- a complete gen
+patch in a single box that sits directly in a regular Max patcher (unlike the
+inner `codebox~` from `add_codebox()`, which belongs inside a `gen~`/`rnbo~`
+subpatcher). Inlet/outlet counts are derived automatically from the highest
+`inN`/`outN` references in the code:
+
+```python
+p = Patcher('fbdelay.maxpat')
+
+# 1 inlet (in1), 1 outlet (out1)
+osc = p.add('cycle~ 440')
+cb = p.add_gen_codebox('''
+Param feedback(0.5, min=0.0, max=0.95);
+History fb(0.0);
+out1 = in1 + fb * feedback;
+fb = out1;
+''')
+dac = p.add('ezdac~')
+p.link(osc, cb)
+p.link(cb, dac)
+p.save()
+
+# Or via the add() string shortcut (single-line / `;`-terminated code)
+cb = p.add('gen.codebox~ out1 = in1 * 0.5;')
+```
+
 ### Object Search
 
 ```python

{py2max-0.3.0 → py2max-0.3.1}/README.md

@@ -51,8 +51,38 @@ That's it! Open `my-synth.maxpat` in Max to see your patch.
 
 - **Offline Patch Generation** - Create Max patches programmatically without Max running
 - **Round-trip Conversion** - Load, modify, and save existing `.maxpat` files
+- **Max for Live (.amxd)** - Read/write binary `.amxd` device files with presentation-mode helpers
 - **Universal Object Support** - Works with any Max/MSP/Jitter object
-- **99% Test Coverage** - 418+ tests ensure reliability
+- **Fully typed** - Passes `mypy --strict`; no runtime dependencies
+- **High Test Coverage** - 420+ tests ensure reliability
+
+### Max for Live (.amxd)
+
+Generate Max for Live devices directly. `Patcher.save()` / `Patcher.from_file()`
+auto-detect the `.amxd` extension and read/write the binary device format,
+byte-for-byte compatible with Max-exported devices.
+
+```python
+from py2max import Patcher
+
+# device_type: "audio_effect" (default), "instrument", or "midi_effect"
+p = Patcher('gain.amxd', device_type='audio_effect')
+p.enable_presentation(devicewidth=120)        # render Ableton's device strip
+
+plugin = p.add_textbox('plugin~')             # audio in from Live
+gain = p.add('live.gain~', maxclass='live.gain~')
+plugout = p.add_textbox('plugout~')           # audio back to Live
+gain.add_to_presentation([20, 20, 60, 136])   # show the fader in the device
+
+p.add_line(plugin, gain, outlet=0, inlet=0)
+p.add_line(gain, plugout, outlet=0, inlet=0)
+p.save()                                       # writes a binary .amxd
+```
+
+Helpers: `Patcher.enable_presentation(devicewidth=...)`,
+`Box.add_to_presentation([x, y, w, h])` (rejects M4L infrastructure objects and
+rounds fractional coordinates), and `Patcher.enforce_integer_coords()`. M4L
+binary helpers live in `py2max.m4l`.
 
 ### Interactive Server (separate package)
 
@@ -219,6 +249,34 @@ p.link(sbox, dac)
 p.save()
 ```
 
+### Gen Codebox
+
+`add_gen_codebox()` adds a standalone `gen.codebox~` object -- a complete gen
+patch in a single box that sits directly in a regular Max patcher (unlike the
+inner `codebox~` from `add_codebox()`, which belongs inside a `gen~`/`rnbo~`
+subpatcher). Inlet/outlet counts are derived automatically from the highest
+`inN`/`outN` references in the code:
+
+```python
+p = Patcher('fbdelay.maxpat')
+
+# 1 inlet (in1), 1 outlet (out1)
+osc = p.add('cycle~ 440')
+cb = p.add_gen_codebox('''
+Param feedback(0.5, min=0.0, max=0.95);
+History fb(0.0);
+out1 = in1 + fb * feedback;
+fb = out1;
+''')
+dac = p.add('ezdac~')
+p.link(osc, cb)
+p.link(cb, dac)
+p.save()
+
+# Or via the add() string shortcut (single-line / `;`-terminated code)
+cb = p.add('gen.codebox~ out1 = in1 * 0.5;')
+```
+
 ### Object Search
 
 ```python

{py2max-0.3.0 → py2max-0.3.1}/py2max/__init__.py

@@ -35,7 +35,7 @@ Example:
     >>> p.save()
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 from .core import Box, Patcher, Patchline
 from .exceptions import (

{py2max-0.3.0 → py2max-0.3.1}/py2max/core/factory.py

@@ -8,6 +8,7 @@ no API change -- adding a new object type means editing this file, not the
 core class.
 """
 
+import re
 import warnings
 from typing import (
     TYPE_CHECKING,
@@ -35,6 +36,23 @@ if TYPE_CHECKING:
 
 logger = get_logger(__name__)
 
+# Max objects whose inlet/outlet counts are determined by their code rather
+# than by a fixed maxref entry. Connection validation for these consults the
+# box's own declared numinlets/numoutlets instead of the static maxref data.
+DYNAMIC_IO_MAXCLASSES = frozenset({"gen.codebox~", "codebox", "codebox~"})
+
+
+def _max_gen_io_index(code: str, kind: str) -> int:
+    """Highest ``in<N>`` / ``out<N>`` index referenced in gen ``code``.
+
+    gen codeboxes derive their inlet/outlet count from the code: ``in1``,
+    ``in2``, ... and ``out1``, ``out2``, .... Returns at least 1 since a gen
+    codebox always has one signal inlet and one signal outlet.
+    """
+    indices = [int(m) for m in re.findall(rf"\b{kind}(\d+)\b", code)]
+    return max([1, *indices])
+
+
 # Box attributes valid on (nearly) every Max object, independent of an object's
 # own maxref attribute set. Used by add_box when validate_attrs is enabled to
 # whitelist universal/jbox attributes plus the structural keys py2max emits, so
@@ -260,9 +278,41 @@ class BoxFactoryMixin(AbstractPatcher):
             src_name = self._get_object_name(src_obj)
             dst_name = self._get_object_name(dst_obj)
 
-            is_valid, error_msg = maxref.validate_connection(
-                src_name, src_outlet, dst_name, dst_inlet
-            )
+            src_dynamic = src_obj.maxclass in DYNAMIC_IO_MAXCLASSES
+            dst_dynamic = dst_obj.maxclass in DYNAMIC_IO_MAXCLASSES
+
+            if src_dynamic or dst_dynamic:
+                # Codeboxes derive their inlet/outlet counts from their code,
+                # so bound-check indices against the box's own declared counts
+                # rather than the fixed maxref entry. Type checking is skipped
+                # because codebox I/O is always signal.
+                src_outlets = (
+                    src_obj.numoutlets
+                    if src_dynamic
+                    else maxref.get_outlet_count(src_name)
+                )
+                dst_inlets = (
+                    dst_obj.numinlets
+                    if dst_dynamic
+                    else maxref.get_inlet_count(dst_name)
+                )
+                error_msg = ""
+                if src_outlets is not None and src_outlet >= src_outlets:
+                    error_msg = (
+                        f"Object '{src_name}' only has {src_outlets} outlet(s), "
+                        f"cannot connect from outlet {src_outlet}"
+                    )
+                elif dst_inlets is not None and dst_inlet >= dst_inlets:
+                    error_msg = (
+                        f"Object '{dst_name}' only has {dst_inlets} inlet(s), "
+                        f"cannot connect to inlet {dst_inlet}"
+                    )
+                is_valid = not error_msg
+            else:
+                is_valid, error_msg = maxref.validate_connection(
+                    src_name, src_outlet, dst_name, dst_inlet
+                )
+
             if not is_valid:
                 logger.warning(
                     f"Connection validation failed: {src_name}[{src_outlet}] -> {dst_name}[{dst_inlet}]: {error_msg}"
@@ -473,6 +523,11 @@ class BoxFactoryMixin(AbstractPatcher):
             return self.add_subpatcher(value, **kwds)
         if maxclass == "gen~":
             return self.add_gen_tilde(**kwds)
+        if maxclass == "gen.codebox~":
+            # Tail is the gen code. value.split() collapses whitespace, so this
+            # shortcut suits single-line/`;`-terminated code; for multi-line
+            # source pass it to add_gen_codebox() directly.
+            return self.add_gen_codebox(txt, **kwds)
         if maxclass == "rnbo~":
             return self.add_rnbo(value, **kwds)
         return self.add_textbox(text=value, **kwds)
@@ -542,6 +597,57 @@ class BoxFactoryMixin(AbstractPatcher):
             code, patching_rect, id, comment, comment_pos, tilde=True, **kwds
         )
 
+    def add_gen_codebox(
+        self,
+        code: str,
+        patching_rect: Optional[Rect] = None,
+        id: Optional[str] = None,
+        numinlets: Optional[int] = None,
+        numoutlets: Optional[int] = None,
+        outlettype: Optional[List[str]] = None,
+        comment: Optional[str] = None,
+        comment_pos: Optional[str] = None,
+        **kwds: Any,
+    ) -> "Box":
+        """Add a standalone ``gen.codebox~`` object.
+
+        Unlike :meth:`add_codebox` (which emits the ``codebox~`` object meant to
+        live *inside* a ``gen~`` or ``rnbo~`` subpatcher), this creates the
+        self-contained ``gen.codebox~`` object that lives directly in a regular
+        Max patcher -- a complete gen patch in a single box, with no subpatcher
+        wrapper. This is the form emitted by gen transpilers.
+
+        A gen codebox's inlet/outlet counts are dynamic: they are determined by
+        the highest ``inN`` / ``outN`` references in the code. They are derived
+        automatically when ``numinlets`` / ``numoutlets`` are not given (each
+        defaults to at least 1).
+        """
+        if "\r" not in code:
+            code = code.replace("\n", "\r\n")
+
+        if numinlets is None:
+            numinlets = _max_gen_io_index(code, "in")
+        if numoutlets is None:
+            numoutlets = _max_gen_io_index(code, "out")
+
+        kwds.setdefault("fontname", "<Monospaced>")
+        kwds.setdefault("fontsize", 12.0)
+
+        return self.add_box(
+            Box(
+                id=id or self.get_id("gen.codebox~"),
+                code=code,
+                maxclass="gen.codebox~",
+                numinlets=numinlets,
+                numoutlets=numoutlets,
+                outlettype=outlettype or ["signal"] * numoutlets,
+                patching_rect=patching_rect or self.get_pos(),
+                **kwds,
+            ),
+            comment,
+            comment_pos,
+        )
+
     def add_message(
         self,
         text: Optional[str] = None,

{py2max-0.3.0 → py2max-0.3.1}/py2max/maxref/legacy.py

@@ -41,6 +41,13 @@ MAXCLASS_DEFAULTS: Dict[str, Dict[str, Any]] = {
         "outlettype": [""],
         "patching_rect": Rect(x=191.0, y=118.0, w=200.0, h=200.0),
     },
+    "gen.codebox~": {
+        "maxclass": "gen.codebox~",
+        "numinlets": 1,
+        "numoutlets": 1,
+        "outlettype": ["signal"],
+        "patching_rect": Rect(x=60.0, y=107.0, w=688.0, h=471.0),
+    },
     "dial": {
         "maxclass": "dial",
         "numinlets": 1,

{py2max-0.3.0 → py2max-0.3.1}/pyproject.toml

@@ -7,7 +7,7 @@ authors = [
 maintainers = [
     { name = "Shakeeb Alireza", email = "shakfu@users.noreply.github.com" }
 ]
-version = "0.3.0"
+version = "0.3.1"
 readme = "README.md"
 requires-python = ">=3.9"
 keywords = ["Max", "maxpat", "offline"]

py2max-0.3.1/tests/test_gen.py

@@ -0,0 +1,96 @@
+import pytest
+
+from py2max import InvalidConnectionError, Patcher
+
+
+def test_gen():
+    p = Patcher("outputs/test_gen.maxpat")
+    sbox = p.add_gen("@title windowSync")
+    sp = sbox.subpatcher
+    i3 = sp.add_textbox("in 3")
+    i4 = sp.add_textbox("in 4")
+    plus = sp.add_textbox("+")
+    sp.add_line(i3, plus)
+    sp.add_line(i4, plus)
+    p.save()
+
+
+def test_gen_tilde():
+    p = Patcher("outputs/test_gen_tilde.maxpat")
+    sbox = p.add_gen_tilde("@nocache 0")  # also p.add_gen(tilde=True)
+    sp = sbox.subpatcher
+    i1 = sp.add_textbox("in 1")
+    i2 = sp.add_textbox("in 2")
+    o1 = sp.add_textbox("out 1")
+    plus = sp.add_textbox("+")
+    sp.add_line(i1, plus)
+    sp.add_line(i2, plus, inlet=1)
+    sp.add_line(plus, o1)
+    p.save()
+
+
+def test_gen_codebox():
+    code = "Param fb(0.5, min=0.0, max=0.95);\nout1 = in1 * fb;"
+    p = Patcher("outputs/test_gen_codebox.maxpat")
+    box = p.add_gen_codebox(code)
+    d = box.to_dict()["box"]
+
+    # standalone gen.codebox~ lives directly in a regular ("box") patcher,
+    # unlike the inner "codebox~" emitted by add_codebox.
+    assert box.maxclass == "gen.codebox~"
+    assert p.classnamespace == "box"
+    assert box.numinlets == 1
+    assert box.numoutlets == 1
+    assert d["outlettype"] == ["signal"]
+    assert d["fontname"] == "<Monospaced>"
+    # newlines are normalized to CRLF as Max expects
+    assert "\r\n" in d["code"]
+    p.save()
+
+
+def test_gen_codebox_multi_io():
+    p = Patcher("outputs/test_gen_codebox_multi.maxpat")
+    box = p.add_gen_codebox("out1 = in1;\nout2 = in2;", numinlets=2, numoutlets=2)
+    assert box.numinlets == 2
+    assert box.numoutlets == 2
+    d = box.to_dict()["box"]
+    assert d["outlettype"] == ["signal", "signal"]
+    p.save()
+
+
+def test_gen_codebox_io_autoderived_from_code():
+    # inlet/outlet counts follow the highest in<N>/out<N> referenced in the code
+    p = Patcher("outputs/test_gen_codebox_auto.maxpat")
+    box = p.add_gen_codebox("out1 = in1 + in3;\nout2 = in2;")
+    assert box.numinlets == 3
+    assert box.numoutlets == 2
+    # always at least one signal inlet and outlet, even with no references
+    bare = p.add_gen_codebox("history h(0.);\nout1 = h;")
+    assert bare.numinlets == 1
+    assert bare.numoutlets == 1
+
+
+def test_gen_codebox_string_dispatch():
+    p = Patcher("outputs/test_gen_codebox_dispatch.maxpat")
+    box = p.add("gen.codebox~ out1 = in1 * 0.5;")
+    assert box.maxclass == "gen.codebox~"
+    assert box.to_dict()["box"]["code"].startswith("out1 = in1 * 0.5;")
+
+
+def test_gen_codebox_connection_validation():
+    # validation uses the codebox's declared (dynamic) I/O, not static maxref
+    p = Patcher("outputs/test_gen_codebox_validate.maxpat", validate_connections=True)
+    box = p.add_gen_codebox("out1 = in1 + in3;\nout2 = in2;")  # 3 in, 2 out
+    dac = p.add("ezdac~")
+    src = p.add("cycle~ 440")
+
+    # connecting from the second outlet is valid (codebox has 2 outlets)
+    p.add_line(box, dac, outlet=1)
+    # connecting into the third inlet is valid (codebox has 3 inlets)
+    p.add_line(src, box, inlet=2)
+
+    # out-of-range outlet/inlet are rejected against the box's own counts
+    with pytest.raises(InvalidConnectionError):
+        p.add_line(box, dac, outlet=5)
+    with pytest.raises(InvalidConnectionError):
+        p.add_line(src, box, inlet=9)

py2max-0.3.0/tests/test_gen.py

@@ -1,27 +0,0 @@
-from py2max import Patcher
-
-
-def test_gen():
-    p = Patcher("outputs/test_gen.maxpat")
-    sbox = p.add_gen("@title windowSync")
-    sp = sbox.subpatcher
-    i3 = sp.add_textbox("in 3")
-    i4 = sp.add_textbox("in 4")
-    plus = sp.add_textbox("+")
-    sp.add_line(i3, plus)
-    sp.add_line(i4, plus)
-    p.save()
-
-
-def test_gen_tilde():
-    p = Patcher("outputs/test_gen_tilde.maxpat")
-    sbox = p.add_gen_tilde("@nocache 0")  # also p.add_gen(tilde=True)
-    sp = sbox.subpatcher
-    i1 = sp.add_textbox("in 1")
-    i2 = sp.add_textbox("in 2")
-    o1 = sp.add_textbox("out 1")
-    plus = sp.add_textbox("+")
-    sp.add_line(i1, plus)
-    sp.add_line(i2, plus, inlet=1)
-    sp.add_line(plus, o1)
-    p.save()