py2max 0.3.1__tar.gz → 0.3.4__tar.gz

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

@@ -2,6 +2,135 @@
 
 ## [Unreleased]
 
+## [0.3.4]
+
+### New: Param docking in layouts
+
+- `Patcher(..., param_placement=True)` docks value/UI "param" objects (`flonum`, `number`, `message`, `toggle`, `slider`, `dial`, `live.*`) next to the single object they drive, instead of spreading them through the signal graph. During `optimize_layout()`, a param whose outgoing connections all go to one non-param target is placed perpendicular to the signal flow -- above the target for a horizontal flow, to its left for a vertical flow (and to the right / below when the flow hugs that edge) -- ordered by, and for a lone param aligned to, the inlet it feeds, then de-overlapped. Works across every built-in layout (grid, flow, columnar, matrix). Off by default; a control that fans out to more than one object is left in the flow. Implemented as `LayoutManager.place_params()`.
+
+### New: Patch linting and message-type-aware connection validation
+
+- Added `Patcher.lint()` (and the `py2max.lint` module: `lint()`, `Finding`) -- a patch-level health check returning structured findings with a `severity`, a `code`, and object/connection references. It covers invalid connections, out-of-range outlet/inlet indices, orphaned patchlines, duplicate IDs, overlapping objects, off-canvas objects, and unknown object classes.
+- **Linting runs automatically on `save()`**: error-severity findings (bad connections, out-of-range ports, orphaned lines, duplicate IDs) are logged. Pass `Patcher(strict=True)` to raise `InvalidPatchError` on any error instead. Layout warnings (overlaps / off-canvas / unknown objects) are left to an explicit `lint()` or `py2max validate` to keep normal saves quiet. This is on by default and non-breaking -- saves still succeed unless `strict=True`.
+- Connection validation is now **message-type aware and bidirectional**. The previous check only rejected a signal outlet wired into a non-signal inlet; it now also catches a control outlet (a bang from `metro` / `loadbang` / `button`) wired into an oscillator's signal inlet -- e.g. `metro -> cycle~`, which Max rejects. The rules are deliberately conservative (ambiguous cases and maxref-unknown objects are allowed) so on-by-default checking never rejects a valid patch; notably a bang into `adsr~` (a legitimate envelope trigger) is *not* flagged.
+- Port typing is now modeled in `py2max/maxref/porttypes.py`, normalizing maxref's placeholder control types (`OUTLET_TYPE` / `INLET_TYPE`) into message kinds, and resolving **argument-dependent port counts** that maxref reports as the arg-less default -- both value-scaled (`limi~ 2` -> 2 in/out) and arg-count-scaled (`select a b c` -> 4 outlets, `route`, `pack`/`unpack`, `selector~`/`switch`) -- plus curated overrides for the handful of objects maxref mis-types.
+- `py2max validate` (CLI) now reports the full lint result -- errors and warnings with codes -- and exits non-zero on any error.
+- A corpus test re-lints every shipped layout example patch and fails on any error, so Max-invalid wiring can no longer ship unnoticed.
+- Subpatchers are handled: a subpatcher/bpatcher box's inlet/outlet count is derived from the `inlet` / `outlet` objects it contains (not the maxref default), and `lint()` recurses into nested patchers -- findings inside a subpatcher are reported path-qualified (e.g. `sub-box-id/obj-1`).
+- Inlet acceptance is now derived from each object's `<methodlist>` -- its real message vocabulary in Max's own docs -- rather than the placeholder inlet `type` (Cycling '74 ships `INLET_TYPE`/`OUTLET_TYPE` for control ports, so the type attribute alone is useless). This is what distinguishes a bang into `cycle~` (no `bang` method -> rejected) from a bang into `adsr~` (has an `anything` wildcard method -> allowed), replacing hand-curation with data that generalizes to all ~1050 objects that carry method lists. The shipped `bundle.json.gz` was regenerated so no-Max users get the same data (a `test_bundle_method_data_quality` guard prevents a future regeneration from dropping it).
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2max
-Version: 0.3.1
+Version: 0.3.4
 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
@@ -172,7 +176,7 @@ p.save()
 
 ### MaxRef Integration
 
-Access documentation for 1157 Max objects:
+Access documentation for 1175 Max objects:
 
 ```python
 p = Patcher('demo.maxpat')
@@ -216,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~']

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

@@ -139,7 +139,7 @@ p.save()
 
 ### MaxRef Integration
 
-Access documentation for 1157 Max objects:
+Access documentation for 1175 Max objects:
 
 ```python
 p = Patcher('demo.maxpat')
@@ -183,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~']

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

@@ -35,7 +35,7 @@ Example:
     >>> p.save()
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.4"
 
 from .core import Box, Patcher, Patchline
 from .exceptions import (
@@ -48,6 +48,7 @@ from .exceptions import (
     PatcherIOError,
     Py2MaxError,
 )
+from .lint import Finding, lint
 
 __all__ = [
     # Version
@@ -56,6 +57,9 @@ __all__ = [
     "Patcher",
     "Box",
     "Patchline",
+    # Linting
+    "lint",
+    "Finding",
     # Exceptions
     "Py2MaxError",
     "InvalidConnectionError",

{py2max-0.3.1 → py2max-0.3.4}/py2max/cli.py

@@ -15,12 +15,12 @@ try:  # pragma: no cover - optional dependency
 except Exception:  # pragma: no cover - optional dependency
     yaml = None
 
-from .core import Patcher, Patchline
+from .core import Patcher
 from .core.common import Rect
 from .exceptions import Py2MaxError
 from .export import export_svg
 from .export.converters import maxpat_to_python, maxref_to_sqlite
-from .maxref import MaxRefCache, MaxRefDB, validate_connection
+from .maxref import MaxRefCache, MaxRefDB
 from .transformers import available_transformers, create_transformer, run_pipeline
 
 LAYOUT_CHOICES = ["horizontal", "vertical", "grid", "flow", "matrix"]
@@ -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,44 +225,23 @@ 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)
 
-    errors: List[str] = []
-
-    for line in patcher._lines:
-        patchline = cast(Patchline, line)
-        src_id, dst_id = patchline.src, patchline.dst
-        src_port = int(patchline.source[1]) if len(patchline.source) > 1 else 0
-        dst_port = (
-            int(patchline.destination[1]) if len(patchline.destination) > 1 else 0
-        )
-
-        src_obj = patcher._objects.get(src_id)
-        dst_obj = patcher._objects.get(dst_id)
-
-        if not src_obj or not dst_obj:
-            errors.append(f"Dangling connection: {src_id} -> {dst_id}")
-            continue
-
-        src_name = _object_name(src_obj)
-        dst_name = _object_name(dst_obj)
-
-        is_valid, message = validate_connection(src_name, src_port, dst_name, dst_port)
-        if not is_valid:
-            errors.append(
-                f"Invalid connection {src_name}[{src_port}] -> {dst_name}[{dst_port}]: {message}"
-            )
-
-    if errors:
-        print("Connection validation failed:", file=sys.stderr)
-        for error in errors:
-            print(f"  - {error}", file=sys.stderr)
-        return 1
+    findings = patcher.lint()
+    if not findings:
+        print("Patch is clean: no lint findings.")
+        return 0
 
-    print("All connections are valid.")
-    return 0
+    errors = [f for f in findings if f.severity == "error"]
+    warnings = [f for f in findings if f.severity == "warning"]
+    stream = sys.stderr if errors else sys.stdout
+    for finding in findings:
+        print(f"  {finding}", file=stream)
+    print(f"{len(errors)} error(s), {len(warnings)} warning(s).", file=stream)
+    return 1 if errors else 0
 
 
 def _parse_transform_spec(spec: str) -> tuple[str, str | None]:
@@ -272,6 +254,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 +299,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 +620,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 +666,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 +742,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 +796,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 +1027,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.1 → py2max-0.3.4}/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