py2max 0.3.0__tar.gz → 0.3.3__tar.gz

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

@@ -2,6 +2,127 @@
 
 ## [Unreleased]
 
+## [0.3.3]
+
+### Removed: `serve` and `repl` CLI subcommands
+
+- The `py2max serve` and `py2max repl` subcommands -- thin stubs that only pointed at the separate `py2max-server` package since v0.3.0 -- have been removed. The interactive live editor and remote REPL still live in `py2max-server` (`pip install py2max-server`).
+
+### Fixed: Graph layouts (`graph:*`) are overlap-free and open on-screen
+
+- `GraphLayoutManager` now runs the dimension-aware overlap sweep (`prevent_overlaps`) after placement, so constraint/force engines no longer leave large UI objects (e.g. `scope~` at 130x130) overlapping their neighbours -- matching the guarantee the grid/flow managers already gave.
+- The patcher window is grown to enclose the laid-out graph plus a margin, so `optimize_layout()` output opens with the whole graph visible instead of spilling past the default 640x480 canvas (the window never shrinks below the default).
+
+### Fixed: Clustered grid layout squashed object sizes
+
+- The connection-aware clustering path of `GridLayoutManager` (`cluster_connected=True`) still wrote the manager's uniform 66x22 size back onto every clustered object, squashing UI objects (`scope~`, `ezdac~`, `dial`, ...) to text-box size. It now preserves each object's real width/height, matching the already-fixed non-clustered path.
+
+### Fixed: Example patches use valid Max connections
+
+- The layout example scripts (`tests/examples/layout/`) and matrix-layout tests wired control objects (`metro`, `loadbang`) straight into oscillator signal inlets, which Max rejects ("error connecting outlet ... to ... inlet"). They now use the correct idiom -- a float number box sets the oscillator frequency, `metro` triggers envelopes, and envelopes modulate amplitude through a `*~` VCA -- so the generated demo patches load cleanly.
+
+### New: `kwds_filter` utility
+
+- Added `py2max.utils.kwds_filter(kwds, **elems)`: returns `kwds` merged with the `elems` whose value is not `None` (legitimate falsy values such as `0` / `""` are kept, and the input is not mutated). Lets a method keep an optional parameter in its signature but omit it from the forwarded `**kwds` when the caller leaves it unset.
+
+### Improved: Build and test-output hygiene
+
+- Coverage HTML now writes to `build/coverage-html` and the test suite writes its artifacts under `build/test-output/` -- both within the git-ignored `build/` tree -- instead of a tracked `outputs/` directory. A new `make test-outputs` target writes all test artifacts flat into `build/test-outputs/` for quick inspection.
+
+## [0.3.2]
+
+### New: Patch editing and removal API
+
+- Loading a patch (`Patcher.from_dict` / `load`) now restores all ID-generation state -- object, node, edge, and semantic-ID counters -- so `add_*` calls made after a load no longer collide with existing object IDs. This fixes the headline "edit an existing patch" round-trip, which previously emitted duplicate IDs on the first post-load add.
+- Added a removal / editing API with referential-integrity cleanup: `remove_line` / `disconnect`, `remove_box` / `remove`, and `replace`. Removing a box also prunes its dangling patchlines and clears the associated node/edge/index bookkeeping, so no orphaned lines or stale IDs are left behind.
+
+### New: Graph-layout engines as layout managers
+
+- Three optional graph-layout backends -- HOLA (`hola-graph`), COLA plus force-directed / geometric layouts (`graph-layout`), and OGDF's layered / force-directed / planar layouts (`ogdf-py`) -- are now selectable as first-class layout managers via `layout="graph:<algo>"` (e.g. `graph:hola`, `graph:cola`, `graph:ogdf-sugiyama`). Because these algorithms need the whole graph, positions are applied on `optimize_layout()` rather than as each box is added, and each box's width/height is preserved so UI objects are not squashed. Eleven algorithms are available: `hola`, `cola`, `sugiyama`, `fruchterman-reingold`, `kamada-kawai`, `spectral`, `circular`, `shell`, `ogdf-sugiyama`, `ogdf-fmmm`, `ogdf-planarization`.
+- The engines are lazy-imported inside the manager, so `import py2max` still pulls **zero runtime dependencies**; a missing backend raises a clear error naming the package to install. Install with `pip install "py2max[graph]"` -- the `graph` extra now also bundles `hola-graph` alongside `graph-layout` and `ogdf-py`. Implemented as `GraphLayoutManager` in `py2max/layout/external.py`.
+
+### New: Layout gallery generator and docs page
+
+- `scripts/gen_layout_gallery.py` (run via `make gallery`) renders every supported graph layout over one shared sample patch to transparent SVGs under `docs/assets/imgs/`, using py2max's own SVG exporter so the results are directly comparable. Backends that are not installed are skipped rather than failing the run.
+- A new published **Layout Gallery** page (`docs/user_guide/layout_gallery.md`, linked in the User Guide navigation) shows the rendered layouts and documents the `graph:<algo>` layout-manager API. The older networkx / graphviz / tsmpy experiments were dropped in favor of the three maintained backends.
+- The generator also renders py2max's **built-in** managers (grid, flow, columnar, matrix) via `optimize_layout()` -- no external dependencies -- and the **Layout Managers** guide (`docs/user_guide/layout_managers.md`) now embeds these as inline visuals so each layout strategy can be seen, not just described.
+
+### Fixed: Generation correctness
+
+- `add_coll` / `add_dict` / `add_table` no longer discard a caller-supplied `text` argument when `name` is `None` (an operator-precedence bug that let the fallback string win).
+- `add_beap` strips the `.maxpat` suffix correctly; previously `rstrip(".maxpat")` could truncate names such as `drum.maxpat` down to `dru`.
+- Parallel patchlines between the same source and destination now receive incrementing `order` values, so they spread apart in Max instead of overlapping.
+- Comments created with `comment=` are emitted on every save path (`save_as`, `to_json`, `to_dict`), not only `save()` / `optimize_layout()`.
+- Hand-typed objects that are not in the built-in defaults now get one outlet instead of zero, so they can act as a connection source.
+- Load/save round-trip no longer injects `autosave` / `dependency_cache` defaults into nested subpatchers the source patch did not have; patches containing subpatchers now round-trip faithfully.
+
+### Fixed: Layout managers
+
+- `layout="columnar"` now works; it previously raised `NotImplementedError` despite being documented.
+- Layout optimizers preserve each object's real width and height. UI objects (`scope~`, `dial`, `slider`, `function`, `live.*`, comments) are no longer squashed to text-box size by `optimize_layout()`.
+- The managers now share a single directed-graph model (`PatchGraph`) rather than re-deriving adjacency from patchlines in each manager, and object classification no longer carries contradictory category assignments (its context inference uses maxref signal typing with word-boundary matching).
+
+### Improved: maxref bundle loading (lazy and thread-safe)
+
+- In bundle mode (no local Max install), the shipped catalog is no longer eagerly materialized into the cache on first access. The name-to-source map still loads once, but each object is now built from the in-memory bundle on demand, so a single-object query no longer constructs all ~1175 entries. A bundle object whose cache slot is empty is re-materialized from the bundle rather than returning nothing.
+- The process-wide maxref cache is now thread-safe: an `RLock` guards the lazy refdict / category-map initialization and cache population, so concurrent `Box.help()` / validation lookups no longer race on first load or mutate the cache unsafely.
+
+### Fixed: maxref outlet digests and parser robustness
+
+- Outlet `<digest>` text is now extracted symmetrically with inlets. A condition bug previously required the `<outlet>` element to have leading text and then stored that text instead of the digest, so outlet descriptions were dropped for almost every object (~2000 digests across ~1093 objects). `Box.help()` / `get_info()` now report outlet descriptions. The shipped offline `bundle.json.gz` was regenerated so bundle-mode users (Linux/Windows/no-Max) get the corrected data.
+- A raw `&` in reference prose no longer drops the whole object on parse. Ampersands that do not begin a valid XML entity are escaped before parsing, hardening against `.maxref.xml` markup variations across Max versions (valid entities like `&amp;`, `&quot;`, `&#181;` are left intact).
+
+### Improved: Cross-platform maxref discovery
+
+- Reference-page resolution now honors the `PY2MAX_MAX_REFPAGES` environment override on all platforms and auto-discovers a Windows `refpages` directory, so Windows users with Max installed read live reference data instead of always falling back to the bundled snapshot. A wheel-build test now asserts the offline `bundle.json.gz` actually ships in the built artifact.
+
+### Improved: SVG preview fidelity
+
+- The SVG exporter (`Patcher.to_svg` / `py2max preview`) now renders a more faithful preview instead of a uniform grey schematic:
+  - **Box colors are honored.** Colors set via `Box.set_color` / `apply_theme` (`bgcolor`, `bordercolor`, `textcolor`) are drawn, converted from Max's `[r, g, b, a]` floats to CSS.
+  - **UI objects get recognizable affordances** rather than an identical rectangle: message boxes draw the right-edge flag notch, `toggle` an X, `button` a circle, number boxes (`flonum` / `number`) the left triangle marker, `dial` a circle with a pointer, and `slider` a thumb bar.
+  - **Ports resolve from the box's own `numinlets` / `numoutlets`** (what is written to the `.maxpat`) rather than a maxref lookup. Ports therefore render correctly for objects maxref does not know and without a Max install, and patchline endpoints line up with the ports they connect to (both use the same counts).
+- `export_svg_string` now builds the document in memory instead of round-tripping through a temporary file.
+
+### Fixed: Layout classification and overlap resolution
+
+- Object classification (matrix / columnar layouts) is now factored into a clear precedence -- curated functional intent, then maxref signal typing for the unknown audio tail, then name patterns -- with the rationale documented. Curated sets must win because functional categories do not map to raw signal I/O (even `cycle~` exposes a signal inlet, so signal typing alone would call it a processor; `adc~` is an input though it is a signal source). The dead, never-effective `_refine_column_assignments_by_flow` no-op and its call site were removed.
+- `LayoutManager.prevent_overlaps` now converges. The previous version cached each object's rect before mutating it (so pushes stopped accumulating) and clamped boxes back inside the canvas (re-introducing the overlaps it had just removed), leaving dense layouts overlapping at the 50-iteration cap. It is replaced with a monotone sweep that pushes each object clear of already-placed ones along the axis of least penetration; it converges in a few passes, early-exits when nothing overlaps, and preserves each object's real size.
+
+### Improved: Patch transformers
+
+- `run_pipeline` now delegates to `compose`, removing a duplicated apply loop and giving the previously-unused (but exported) `compose` helper a real use.
+- The `add-comment` transformer's position is now reachable from the CLI: prefix the value with `above|below|left|right:` to place the comment (e.g. `--apply "add-comment=below:tempo"`), defaulting to `above`. A leading token that is not a position is kept as comment text, so `"note: hi"` is left intact.
+- Added two transformers backed by existing APIs: `apply-theme` (apply a named color theme -- `light` / `dark` / `blue` / `high-contrast`) and `scale-positions` (scale every object's x/y position by a factor, sizes unchanged).
+
+### Fixed: Converters module cleanup
+
+- Importing `py2max.export.converters` no longer constructs a `Patcher` as an import-time side effect (which pulled in maxref, layout, etc.). The default-attribute set is now computed lazily on first use and cached. Also removed a dead `_infer_category` helper and an unreachable `NotImplementedError` guard (the caller strips subpatcher dicts before that path).
+
+### Removed: Honest CLI help for the moved `serve` / `repl` subcommands
+
+- The `serve` and `repl` subcommands (whose implementations moved to `py2max-server` in 0.3.0) no longer advertise themselves as live in `--help`; they now removed.
+
+### Removed: MaxRefDB deprecated alias methods
+
+- Removed 12 long-deprecated `MaxRefDB` aliases in favor of the canonical API: `populate_from_maxref` / `populate_all_*` -> `populate([category=...])`, `search_objects` -> `search`, `get_objects_by_category` -> `by_category`, `get_all_categories` -> `.categories`, `get_object_count` -> `.count`, and `export_to_json` / `import_from_json` -> `export` / `load`. The database module is already off the import path (lazily loaded, stdlib-only), so this only trims its API surface. Callers, tests, and docs were updated to the canonical names.
+- While updating the SQLite demo scripts, also fixed two pre-existing broken examples: `from py2max import MaxRefDB` (correct: `from py2max.maxref import MaxRefDB`) and `create_database(...)` used as a free function (it is `MaxRefDB.create_database(...)`). Both `tests/examples/db/` scripts now run.
+
+### Removed: Obsolete layout experiments and vendored editor assets
+
+- Deleted the old graph-layout experiment tests (`tests/test_layout_hola{1,2,3}`, `test_layout_hola_graph`, `test_layout_networkx{1,2}`, `test_layout_nx_graphviz`, `test_layout_nx_orthogonal`, `test_layout_nx_tsmpy`). They exercised backends that are no longer supported (raw adaptagrams, networkx, pygraphviz, tsmpy) or duplicated the new `GraphLayoutManager` coverage, and only ever skipped. The maintained path is covered by `tests/test_layout_graph_manager.py`.
+- Removed the vendored browser libraries under `docs/js/` (SVG.js, WebCola, D3) -- reference copies for the interactive editor that moved to the separate `py2max-server` package in 0.3.0 -- and the stale Sphinx build output under `docs/build/` that predated the MkDocs migration and was being copied into the published site.
+- Pruned 30 obsolete design notes from the `docs/notes/` dev journal (REPL, SSE/WebSocket live-preview server, and interactive SVG-editor implementation notes), all for features that moved to `py2max-server`. The 13 still-relevant library/journal notes were kept.
+
+## [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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2max
-Version: 0.3.0
+Version: 0.3.3
 Summary: A library for offline generation of Max/MSP patcher (.maxpat) files.
 Keywords: Max,maxpat,offline
 Author: Shakeeb Alireza
@@ -21,6 +21,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Classifier: Typing :: Typed
+Requires-Dist: graph-layout>=0.4 ; extra == 'graph'
+Requires-Dist: ogdf-py>=0.3 ; python_full_version >= '3.10' and extra == 'graph'
+Requires-Dist: hola-graph>=0.1 ; extra == 'graph'
 Maintainer: Shakeeb Alireza
 Maintainer-email: Shakeeb Alireza <shakfu@users.noreply.github.com>
 Requires-Python: >=3.9
@@ -29,6 +32,7 @@ Project-URL: Documentation, https://github.com/shakfu/py2max#readme
 Project-URL: Repository, https://github.com/shakfu/py2max.git
 Project-URL: Issues, https://github.com/shakfu/py2max/issues
 Project-URL: Changelog, https://github.com/shakfu/py2max/blob/main/CHANGELOG.md
+Provides-Extra: graph
 Description-Content-Type: text/markdown
 
 # py2max
@@ -84,8 +88,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)
 
@@ -142,7 +176,7 @@ p.save()
 
 ### MaxRef Integration
 
-Access documentation for 1157 Max objects:
+Access documentation for 1175 Max objects:
 
 ```python
 p = Patcher('demo.maxpat')
@@ -186,10 +220,10 @@ osc = p.find_by_id('cycle_1')
 Query Max object metadata efficiently:
 
 ```python
-from py2max import MaxRefDB
+from py2max.maxref import MaxRefDB
 
 db = MaxRefDB()  # Auto-cached on first use
-print(len(db))   # 1157 objects
+print(len(db))   # 1175 objects
 
 if 'cycle~' in db:
     info = db['cycle~']
@@ -252,6 +286,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.3}/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)
 
@@ -109,7 +139,7 @@ p.save()
 
 ### MaxRef Integration
 
-Access documentation for 1157 Max objects:
+Access documentation for 1175 Max objects:
 
 ```python
 p = Patcher('demo.maxpat')
@@ -153,10 +183,10 @@ osc = p.find_by_id('cycle_1')
 Query Max object metadata efficiently:
 
 ```python
-from py2max import MaxRefDB
+from py2max.maxref import MaxRefDB
 
 db = MaxRefDB()  # Auto-cached on first use
-print(len(db))   # 1157 objects
+print(len(db))   # 1175 objects
 
 if 'cycle~' in db:
     info = db['cycle~']
@@ -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.3}/py2max/__init__.py

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

{py2max-0.3.0 → py2max-0.3.3}/py2max/cli.py

@@ -148,6 +148,7 @@ def _generate_test_source(name: str, data: Dict[str, Any]) -> str:
 
 
 def cmd_new(args: argparse.Namespace) -> int:
+    """Create a new, empty patcher file at the given path."""
     path = Path(args.path)
     if path.exists() and not args.force:
         print(f"Refusing to overwrite existing file: {path}", file=sys.stderr)
@@ -179,6 +180,7 @@ def cmd_new(args: argparse.Namespace) -> int:
 
 
 def cmd_info(args: argparse.Namespace) -> int:
+    """Print a summary of a patcher file (object and connection counts)."""
     path = Path(args.path)
     patcher = Patcher.from_file(path)
     _coerce_rect(patcher)
@@ -201,6 +203,7 @@ def cmd_info(args: argparse.Namespace) -> int:
 
 
 def cmd_optimize(args: argparse.Namespace) -> int:
+    """Re-run layout optimization on a patcher and write the result."""
     input_path = Path(args.input)
     save_path = Path(args.output) if args.output else input_path
 
@@ -222,6 +225,7 @@ def cmd_optimize(args: argparse.Namespace) -> int:
 
 
 def cmd_validate(args: argparse.Namespace) -> int:
+    """Validate a patcher's connections against maxref inlet/outlet metadata."""
     path = Path(args.path)
     patcher = Patcher.from_file(path)
     _coerce_rect(patcher)
@@ -272,6 +276,7 @@ def _parse_transform_spec(spec: str) -> tuple[str, str | None]:
 
 
 def cmd_transform(args: argparse.Namespace) -> int:
+    """Apply one or more transformers to a patcher (or list available ones)."""
     if args.list_transformers:
         for name, desc in available_transformers().items():
             print(f"{name}: {desc}")
@@ -316,6 +321,7 @@ def cmd_transform(args: argparse.Namespace) -> int:
 
 
 def cmd_convert(args: argparse.Namespace) -> int:
+    """Convert between formats (e.g. .maxpat to Python, maxref to SQLite)."""
     if args.mode == "maxpat-to-python":
         if not args.input or not args.output:
             print(
@@ -636,19 +642,6 @@ def cmd_db_cache(args: argparse.Namespace) -> int:
         return 1
 
 
-def cmd_serve(args: argparse.Namespace) -> int:
-    """The interactive server moved to the separate py2max-server package."""
-    target = getattr(args, "input", None) or "<patch.maxpat>"
-    print(
-        "The interactive server has moved to the separate 'py2max-server' package.\n"
-        "Install it and use its CLI instead:\n"
-        "    pip install py2max-server\n"
-        f"    py2max-server serve {target}",
-        file=sys.stderr,
-    )
-    return 1
-
-
 def cmd_preview(args: argparse.Namespace) -> int:
     """Generate SVG preview of a patcher."""
     import tempfile
@@ -695,20 +688,8 @@ def cmd_preview(args: argparse.Namespace) -> int:
         return 1
 
 
-def cmd_repl(args: argparse.Namespace) -> int:
-    """The remote REPL moved to the separate py2max-server package."""
-    target = getattr(args, "server", None) or "localhost:9000"
-    print(
-        "The remote REPL has moved to the separate 'py2max-server' package.\n"
-        "Install it and use its CLI instead:\n"
-        "    pip install py2max-server\n"
-        f"    py2max-server repl {target}",
-        file=sys.stderr,
-    )
-    return 1
-
-
 def cmd_maxref(args: argparse.Namespace) -> int:
+    """Query the Max object reference (list objects or show one's details)."""
     cache = MaxRefCache()
 
     if args.list:
@@ -783,6 +764,7 @@ def cmd_maxref(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
+    """Construct the top-level argument parser with all subcommands."""
     parser = argparse.ArgumentParser(
         prog="py2max", description="Utilities for working with Max patchers."
     )
@@ -836,33 +818,6 @@ def build_parser() -> argparse.ArgumentParser:
     val_parser.add_argument("path", help="Target .maxpat path")
     val_parser.set_defaults(func=cmd_validate)
 
-    serve_parser = subparsers.add_parser(
-        "serve", help="Start interactive server with live preview"
-    )
-    serve_parser.add_argument("input", help="Input .maxpat file")
-    serve_parser.add_argument(
-        "--port",
-        type=int,
-        default=8000,
-        help="HTTP server port (default: 8000, WebSocket on port+1)",
-    )
-    serve_parser.add_argument(
-        "--no-open", action="store_true", help="Don't automatically open browser"
-    )
-    serve_parser.add_argument(
-        "--no-save", action="store_true", help="Disable auto-save on changes"
-    )
-    serve_parser.add_argument(
-        "--repl",
-        action="store_true",
-        help="Start interactive REPL for live patch editing",
-    )
-    serve_parser.add_argument(
-        "--log-file",
-        help="Redirect server logs to file (enables single-terminal REPL mode when used with --repl)",
-    )
-    serve_parser.set_defaults(func=cmd_serve)
-
     preview_parser = subparsers.add_parser(
         "preview", help="Generate SVG preview of a patcher"
     )
@@ -1094,26 +1049,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     cache_clear.set_defaults(func=cmd_db)
 
-    # REPL client command
-    repl_parser = subparsers.add_parser("repl", help="Connect to remote REPL server")
-    repl_parser.add_argument(
-        "server",
-        nargs="?",
-        default="localhost:9000",
-        help="Server address (default: localhost:9000)",
-    )
-    repl_parser.add_argument(
-        "--token",
-        default=None,
-        help="Session token printed by the server "
-        "(or set PY2MAX_REPL_TOKEN). Required for authentication.",
-    )
-    repl_parser.set_defaults(func=cmd_repl)
-
     return parser
 
 
 def main(argv: List[str] | None = None) -> int:
+    """CLI entry point: parse ``argv`` and dispatch to the subcommand handler."""
     parser = build_parser()
     args = parser.parse_args(argv)
 

{py2max-0.3.0 → py2max-0.3.3}/py2max/core/abstract.py

@@ -60,6 +60,8 @@ class AbstractBox(ABC):
     id: Optional[str]
     maxclass: str
     patching_rect: Rect
+    numinlets: int
+    numoutlets: int
     _kwds: Dict[str, Any]
 
     @abstractmethod
@@ -135,8 +137,6 @@ class AbstractPatcher(ABC):
     _lines: list[AbstractPatchline]
     _edge_ids: list[tuple[str, str]]
     _id_counter: int = 0
-    _link_counter: int = 0
-    _last_link: Optional[tuple[str, str]]
     _reset_on_render: bool
     _flow_direction: str
     _cluster_connected: bool