py2max 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -2,6 +2,98 @@
 
 ## [Unreleased]
 
+## [0.3.0]
+
+### Removed: Interactive Server Split Into `py2max-server` (breaking)
+
+The browser-based live editor and remote REPL have moved to a separate companion package, [`py2max-server`](https://github.com/shakfu/py2max-server), so the core library stays small, offline, and dependency-free.
+
+- Removed `Patcher.serve()` and the `py2max serve` / `py2max repl` CLI commands; those CLI subcommands now print a pointer to `py2max-server`.
+- Removed the `[server]` optional-dependency extra (`websockets`, `ptpython`) and the bundled browser assets (`py2max/static/`).
+- Install the server features with `pip install py2max-server` and use `py2max-server serve <patch>` / `py2max-server repl …`. The remote REPL now requires token authentication (passed via `--token` or `PY2MAX_REPL_TOKEN`).
+
+### New: `Patcher.encapsulate()`
+
+- `Patcher.encapsulate(boxes, text="p sub")` wraps a selection of boxes into a subpatcher, auto-generating `inlet`/`outlet` objects for any connections that cross the selection boundary and rewiring the parent through the new subpatcher box. Connections wholly inside the selection move into the subpatcher; connections wholly outside it are untouched. Ports are de-duplicated by source, matching how patches are built by hand. Returns the new subpatcher `Box`.
+
+### New: Preset / `pattrstorage` Scaffolding
+
+- `Patcher.add_pattrstorage(name)`, `Patcher.add_autopattr()`, and `Patcher.add_preset_system(name)` (which adds both and wires `autopattr` -> `pattrstorage`) scaffold a Max preset system. Any object with a scripting name (`varname`) or `parameter_enable=1` participates.
+- `Patcher.enable_parameter(box, longname, shortname="", ptype=0, initial=None)` turns an existing UI box into a Max parameter (sets `parameter_enable` and the `saved_attribute_attributes`), so it participates in presets and, in a Max for Live device, appears as an automatable parameter.
+
+### New: Keyword-Attribute Validation (`validate_attrs`)
+
+- `Patcher(validate_attrs=True)` warns (`UserWarning`) when an object is given a keyword that is not a known attribute for its Max class -- catching typos like `inital=` for `initial=`. The known set is the object's maxref attributes plus a universal box-attribute whitelist; objects with no maxref entry are skipped. Off by default and warn-only, so it never changes generated output.
+
+### New: Multichannel (`mc.`) / Polyphony Helpers
+
+- `Patcher.add_mc(text, chans=None)` adds a multichannel object, prefixing `mc.` and appending `@chans` (e.g. `add_mc("cycle~ 440", chans=4)` -> `mc.cycle~ 440 @chans 4`).
+- `Patcher.add_poly(target, voices=1)` adds a `poly~` object hosting N voices of a target patch.
+
+### Improved: SVG Export (Max-faithful preview)
+
+- The `preview` / `to_svg` output now approximates Max's look: a light patcher background, signal vs message/control **ports colored distinctly** (signal green, control dark), signal **cables drawn thicker and in a distinct color**, and subpatcher boxes tinted so they stand out. Object text is intentionally not truncated, matching Max (objects size to their text).
+
+### Changed: Documentation moved to MkDocs
+
+- Documentation migrated from Sphinx/reStructuredText to **MkDocs + Material + mkdocstrings** (all Markdown, matching the rest of the repo). The API reference is generated from the (now fully typed) docstrings, including `Patcher`'s mixin-provided methods. The changelog and contributing pages are single-source includes of `CHANGELOG.md` / `CONTRIBUTING.md`. Build with `make docs`, preview with `make docs-serve`, publish with `make docs-deploy`. `docs/notes/` is retained as a historical journal but excluded from the published site.
+
+### New: Color / Theme Helpers
+
+- `Box.set_color(bg=..., text=..., border=...)` sets a box's `bgcolor`/`textcolor`/`bordercolor`; each accepts a named color (e.g. `"red"`), a hex string (`"#ff8800"`), or an `[r, g, b(, a)]` float sequence. Returns the box for chaining.
+- `Patcher.apply_theme(theme)` applies a color theme to every box (recursing into subpatchers). Built-in themes: `"light"`, `"dark"`, `"blue"`, `"high-contrast"`; or pass a dict of `bg`/`text`/`border` colors.
+- `py2max.core.colors` exposes the `MAX_COLORS` named palette and `resolve_color()`.
+
+### Security
+
+- **Removed a misleading path-traversal check** in `Patcher.save_as()`. The previous `..`/`/etc` allowlist was trivially bypassable and gave a false sense of safety; for an offline file generator it provided no real protection. Genuinely unresolvable paths still raise `PatcherIOError`.
+
+### Typed: Full `mypy --strict`
+
+- The entire package is now annotated and passes `mypy --strict`, backing the shipped `py.typed` marker. `[tool.mypy]` enforces `strict = true`. Core has **no runtime dependencies**.
+
+### Changed: Lighter Core Imports
+
+- `import py2max` no longer eagerly imports `sqlite3`, the maxref database layer, or `py2max.m4l`. `MaxRefDB` is now available lazily via `from py2max.maxref import MaxRefDB` (removed from the top-level `py2max` namespace).
+
+### Internal: `Patcher` Decomposition
+
+- Split the ~1660-line `Patcher` class into focused mixins composed via inheritance: object creation (`BoxFactoryMixin` in `core/factory.py`) and serialization (`SerializationMixin` in `core/serialization.py`). The public API is unchanged; adding a new object type now means editing `core/factory.py` rather than the core class.
+
+### Fixed
+
+- Object-name resolution (used by connection validation and object classification) now reads the box `text` property, so it resolves correctly for boxes loaded from a file. Previously it inspected only programmatic kwargs and returned `newobj` for loaded boxes.
+- `Box.oid` now returns the trailing numeric part of any id (e.g. `cycle_1` -> 1) instead of raising `ValueError` under `semantic_ids=True`.
+- The `py2max` CLI now reports all `Py2MaxError`s (not just `InvalidConnectionError`) as a clean error message instead of leaking a traceback.
+- Fixed an `inital` -> `initial` keyword typo in the simple-synthesis tutorial.
+
+### Testing & Tooling
+
+- The test suite is now hermetic: a `conftest.py` autouse fixture isolates each test in a temporary working directory, so relative `outputs/` writes no longer accumulate in the repo. Fixture reads are anchored at the test file.
+- Promoted the `.amxd` byte-for-byte fixtures from the gitignored `outputs/` into tracked `tests/data/`, so that verification runs in CI and on fresh checkouts instead of only on the author's machine.
+- Repo-wide `ruff` lint and format cleanup.
+
+### New: Max for Live Support (`py2max.m4l`)
+
+Implements [issue #9](https://github.com/shakfu/py2max/issues/9). See [`docs/notes/amxd.md`](https://github.com/shakfu/py2max/blob/main/docs/notes/amxd.md) for the on-disk format, embedded-project block, and verification details.
+
+- **`.amxd` read/write**: byte-for-byte compatible with Max-exported devices; verified against real fixtures and end-to-end in Live 12.
+- **Device-type discrimination**: Audio Effect / Instrument / MIDI Effect via `Patcher(device_type=...)` or the `pack_amxd` / `write_amxd` `device_type` argument.
+- **Presentation-mode helpers**: `Patcher.enable_presentation(devicewidth=...)`, `Patcher.enforce_integer_coords()`, `Box.add_to_presentation([x, y, w, h])` (rejects M4L infrastructure objects, rounds fractional coords with a warning).
+- `Patcher.save()` / `Patcher.from_file()` auto-detect the `.amxd` extension; `.maxpat` path is unchanged.
+
+### Changed: M4L Module Layout & Imports
+
+- All M4L code (binary format + presentation helpers) lives in a single module `py2max/m4l.py`. Previously briefly split as `py2max/amxd.py`.
+- M4L symbols are reachable only via `from py2max.m4l import …`; nothing is re-exported from the top-level `py2max` namespace.
+
+### New: Prebuilt MaxRef Bundle (Linux Support)
+
+- Ship `py2max/maxref/data/bundle.json.gz` in the wheel (1175 objects, ~1 MiB compressed, ~7 MiB raw).
+- `MaxRefCache._get_refdict()` falls back to the bundle when no local Max installation is found, pre-seeding the parser cache so `Box.help()`, `get_inlet_count`, `get_outlet_count`, and connection validation work identically on Linux.
+- Regenerate with `uv run python scripts/build_maxref_bundle.py` on a machine with Max installed; commit the result.
+- Bundle stores full parsed data (methods, attributes, inlets/outlets, digests, descriptions) — not a trimmed subset — so introspection parity with macOS/Windows is preserved.
+
 ## [0.2.1] - 2026-01-11
 
 ### New: Dagre Layout Algorithm

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2max
-Version: 0.2.1
+Version: 0.3.0
 Summary: A library for offline generation of Max/MSP patcher (.maxpat) files.
 Keywords: Max,maxpat,offline
 Author: Shakeeb Alireza
@@ -12,7 +12,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: Topic :: Multimedia :: Sound/Audio
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -22,15 +21,14 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Classifier: Typing :: Typed
-Requires-Dist: websockets>=12.0 ; extra == 'server'
-Requires-Dist: ptpython>=3.0.0 ; extra == 'server'
+Maintainer: Shakeeb Alireza
+Maintainer-email: Shakeeb Alireza <shakfu@users.noreply.github.com>
 Requires-Python: >=3.9
-Project-URL: Changelog, https://github.com/shakfu/py2max/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://github.com/shakfu/py2max#readme
 Project-URL: Homepage, https://github.com/shakfu/py2max
-Project-URL: Issues, https://github.com/shakfu/py2max/issues
+Project-URL: Documentation, https://github.com/shakfu/py2max#readme
 Project-URL: Repository, https://github.com/shakfu/py2max.git
-Provides-Extra: server
+Project-URL: Issues, https://github.com/shakfu/py2max/issues
+Project-URL: Changelog, https://github.com/shakfu/py2max/blob/main/CHANGELOG.md
 Description-Content-Type: text/markdown
 
 # py2max
@@ -46,9 +44,13 @@ If you are looking for Python 3 externals for Max/MSP, check out the [py-js](htt
 
 ```bash
 pip install py2max
+```
+
+For the browser-based live editor and remote REPL, install the companion
+[`py2max-server`](https://github.com/shakfu/py2max-server) package:
 
-# With interactive server support
-pip install py2max[server]
+```bash
+pip install py2max-server
 ```
 
 For development:
@@ -85,12 +87,15 @@ That's it! Open `my-synth.maxpat` in Max to see your patch.
 - **Universal Object Support** - Works with any Max/MSP/Jitter object
 - **99% Test Coverage** - 418+ tests ensure reliability
 
-### Interactive Server (New in 0.2.x)
+### Interactive Server (separate package)
 
-Real-time browser-based patch editing with bidirectional sync:
+Real-time browser-based patch editing with bidirectional sync lives in the
+companion [`py2max-server`](https://github.com/shakfu/py2max-server) package, so
+the core library stays small and offline:
 
 ```bash
-py2max serve my-patch.maxpat
+pip install py2max-server
+py2max-server serve my-patch.maxpat
 # Opens browser at http://localhost:8000
 ```
 
@@ -285,12 +290,15 @@ py2max validate demo.maxpat
 
 ### Interactive Server
 
+Provided by the separate [`py2max-server`](https://github.com/shakfu/py2max-server)
+package (`pip install py2max-server`):
+
 ```bash
 # Start server with browser editing
-py2max serve my-patch.maxpat
+py2max-server serve my-patch.maxpat
 
 # With REPL in same terminal
-py2max serve my-patch.maxpat --repl
+py2max-server serve my-patch.maxpat --repl
 ```
 
 ### MaxRef Database
@@ -350,18 +358,21 @@ All classes are extendable via `**kwargs`, allowing any Max object configuration
 
 ## Caveats
 
-- Max doesn't refresh from file when open - close and reopen to see changes, or use `py2max serve` for live editing
+- Max doesn't refresh from file when open - close and reopen to see changes, or use `py2max-server serve` (from the separate `py2max-server` package) for live editing
 - For tilde variants, use the `_tilde` suffix: `p.add_gen()` vs `p.add_gen_tilde()`
 - API docs in progress - see `CLAUDE.md` for comprehensive usage
 
 ## Examples
 
-See the `examples/` directory for demonstrations:
+The [`tests/examples/`](tests/examples/) directory contains working, tested
+examples organized by topic (see its [README](tests/examples/README.md)):
 
-- `auto_layout_demo.py` - Complex synthesizer with layout optimization
-- `nested_patcher_demo.py` - Subpatcher navigation
-- `columnar_layout_demo.py` - Functional column organization
-- `matrix_layout_demo.py` - Signal chain matrix layout
+- `quickstart/basic_patch.py` - Simple oscillator patch
+- `tutorial/signal_processing_chain.py` - Complex audio processing chain
+- `tutorial/generative_music.py` - Generative music system with patterns
+- `layout/grid_layout_examples.py` - Grid layout with clustering
+- `advanced/data_containers.py` - Tables, collections, and dictionaries
+- `api/patcher_api_examples.py` - Patcher API reference examples
 
 External usage:
 

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

@@ -11,9 +11,13 @@ If you are looking for Python 3 externals for Max/MSP, check out the [py-js](htt
 
 ```bash
 pip install py2max
+```
+
+For the browser-based live editor and remote REPL, install the companion
+[`py2max-server`](https://github.com/shakfu/py2max-server) package:
 
-# With interactive server support
-pip install py2max[server]
+```bash
+pip install py2max-server
 ```
 
 For development:
@@ -50,12 +54,15 @@ That's it! Open `my-synth.maxpat` in Max to see your patch.
 - **Universal Object Support** - Works with any Max/MSP/Jitter object
 - **99% Test Coverage** - 418+ tests ensure reliability
 
-### Interactive Server (New in 0.2.x)
+### Interactive Server (separate package)
 
-Real-time browser-based patch editing with bidirectional sync:
+Real-time browser-based patch editing with bidirectional sync lives in the
+companion [`py2max-server`](https://github.com/shakfu/py2max-server) package, so
+the core library stays small and offline:
 
 ```bash
-py2max serve my-patch.maxpat
+pip install py2max-server
+py2max-server serve my-patch.maxpat
 # Opens browser at http://localhost:8000
 ```
 
@@ -250,12 +257,15 @@ py2max validate demo.maxpat
 
 ### Interactive Server
 
+Provided by the separate [`py2max-server`](https://github.com/shakfu/py2max-server)
+package (`pip install py2max-server`):
+
 ```bash
 # Start server with browser editing
-py2max serve my-patch.maxpat
+py2max-server serve my-patch.maxpat
 
 # With REPL in same terminal
-py2max serve my-patch.maxpat --repl
+py2max-server serve my-patch.maxpat --repl
 ```
 
 ### MaxRef Database
@@ -315,18 +325,21 @@ All classes are extendable via `**kwargs`, allowing any Max object configuration
 
 ## Caveats
 
-- Max doesn't refresh from file when open - close and reopen to see changes, or use `py2max serve` for live editing
+- Max doesn't refresh from file when open - close and reopen to see changes, or use `py2max-server serve` (from the separate `py2max-server` package) for live editing
 - For tilde variants, use the `_tilde` suffix: `p.add_gen()` vs `p.add_gen_tilde()`
 - API docs in progress - see `CLAUDE.md` for comprehensive usage
 
 ## Examples
 
-See the `examples/` directory for demonstrations:
+The [`tests/examples/`](tests/examples/) directory contains working, tested
+examples organized by topic (see its [README](tests/examples/README.md)):
 
-- `auto_layout_demo.py` - Complex synthesizer with layout optimization
-- `nested_patcher_demo.py` - Subpatcher navigation
-- `columnar_layout_demo.py` - Functional column organization
-- `matrix_layout_demo.py` - Signal chain matrix layout
+- `quickstart/basic_patch.py` - Simple oscillator patch
+- `tutorial/signal_processing_chain.py` - Complex audio processing chain
+- `tutorial/generative_music.py` - Generative music system with patterns
+- `layout/grid_layout_examples.py` - Grid layout with clustering
+- `advanced/data_containers.py` - Tables, collections, and dictionaries
+- `api/patcher_api_examples.py` - Patcher API reference examples
 
 External usage:
 

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

@@ -8,7 +8,10 @@ Main Classes:
     Patcher: Core class for creating and managing Max patches
     Box: Represents individual Max objects (oscillators, effects, etc.)
     Patchline: Represents connections between objects
-    MaxRefDB: SQLite database for Max object reference data
+
+The SQLite Max-reference database is available as ``from py2max.maxref import
+MaxRefDB`` -- kept out of the top-level import so ``import py2max`` does not pull
+in ``sqlite3`` and the database layer.
 
 Exceptions:
     Py2MaxError: Base exception for all py2max errors
@@ -32,10 +35,9 @@ Example:
     >>> p.save()
 """
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 from .core import Box, Patcher, Patchline
-from .maxref import MaxRefDB
 from .exceptions import (
     DatabaseError,
     InvalidConnectionError,
@@ -54,7 +56,6 @@ __all__ = [
     "Patcher",
     "Box",
     "Patchline",
-    "MaxRefDB",
     # Exceptions
     "Py2MaxError",
     "InvalidConnectionError",

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

@@ -17,7 +17,7 @@ except Exception:  # pragma: no cover - optional dependency
 
 from .core import Patcher, Patchline
 from .core.common import Rect
-from .exceptions import InvalidConnectionError
+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
@@ -42,15 +42,13 @@ def _to_pascal_case(name: str) -> str:
     )
 
 
-def _object_name(box) -> str:
-    maxclass = getattr(box, "maxclass", "newobj")
-    text = getattr(box, "text", "") or ""
-    if maxclass == "newobj" and text:
-        return text.split()[0]
-    return maxclass
+def _object_name(box: Any) -> str:
+    from .utils import object_name
 
+    return object_name(box)
 
-def _unique_object_labels(boxes: Iterable) -> List[str]:
+
+def _unique_object_labels(boxes: Iterable[Any]) -> List[str]:
     labels: set[str] = set()
     for box in boxes:
         labels.add(_object_name(box))
@@ -63,7 +61,7 @@ def _coerce_rect(patcher: Patcher) -> None:
         patcher.rect = Rect(*rect)
 
 
-def _format_args(method: dict) -> List[str]:
+def _format_args(method: Dict[str, Any]) -> List[str]:
     args: List[str] = []
     for arg in method.get("args", []):
         name = _sanitize_identifier(arg.get("name", "arg"))
@@ -75,7 +73,7 @@ def _format_args(method: dict) -> List[str]:
     return args
 
 
-def _dump_code(name: str, data: dict) -> None:
+def _dump_code(name: str, data: Dict[str, Any]) -> None:
     class_name = _to_pascal_case(name)
     digest = data.get("digest", "")
     description = data.get("description", "")
@@ -112,7 +110,7 @@ def _dump_code(name: str, data: dict) -> None:
         print("        raise NotImplementedError\n")
 
 
-def _dump_tests(name: str, data: dict) -> None:
+def _dump_tests(name: str, data: Dict[str, Any]) -> None:
     base = _sanitize_identifier(name)
     for method_name, method in sorted(data.get("methods", {}).items()):
         identifier = _sanitize_identifier(method_name)
@@ -123,7 +121,7 @@ def _dump_tests(name: str, data: dict) -> None:
         print("    # TODO: implement test\n")
 
 
-def _generate_test_source(name: str, data: dict) -> str:
+def _generate_test_source(name: str, data: Dict[str, Any]) -> str:
     base = _sanitize_identifier(name)
     lines = [
         "from py2max.maxref import MaxRefCache",
@@ -639,108 +637,16 @@ def cmd_db_cache(args: argparse.Namespace) -> int:
 
 
 def cmd_serve(args: argparse.Namespace) -> int:
-    """Start interactive WebSocket server for a patcher."""
-    import asyncio
-
-    input_path = Path(args.input)
-
-    if not input_path.exists():
-        print(f"Input file not found: {input_path}", file=sys.stderr)
-        return 1
-
-    # Check if websockets is installed
-    import importlib.util
-
-    if importlib.util.find_spec("websockets") is None:
-        print("Error: websockets package required for server.", file=sys.stderr)
-        print("Install with: pip install websockets", file=sys.stderr)
-        return 1
-
-    # Check if ptpython is installed (if --repl requested)
-    if args.repl:
-        if importlib.util.find_spec("ptpython") is None:
-            print("Error: ptpython package required for REPL.", file=sys.stderr)
-            print(
-                "Install with: pip install ptpython or uv add ptpython", file=sys.stderr
-            )
-            return 1
-
-    # Load patcher
-    patcher = Patcher.from_file(input_path)
-    _coerce_rect(patcher)
-
-    # Start interactive server
-    try:
-        print(f"Starting server for: {input_path}")
-        print(f"HTTP server: http://localhost:{args.port}")
-        print(f"WebSocket server: ws://localhost:{args.port + 1}")
-        print("Interactive editing enabled - changes sync bidirectionally")
-        if not args.no_save:
-            print(f"Auto-save enabled: changes will be saved to {input_path}")
-        if args.repl:
-            print("REPL mode enabled - type 'commands()' for help")
-        print("Press Ctrl+C to stop")
-
-        async def run_server():
-            # Check if using single-terminal mode (Option 2b)
-            if args.repl and args.log_file:
-                # Option 2b: Single terminal with log redirection
-                from .server.inline import start_background_server_repl
-
-                log_file_path = Path(args.log_file)
-                await start_background_server_repl(
-                    patcher, port=args.port, log_file=log_file_path
-                )
-                return
-
-            # Option 2a: Client-server mode (default)
-            server = await patcher.serve(port=args.port, auto_open=not args.no_open)
-
-            # Start REPL server (always running, can connect remotely)
-            from .server.rpc import start_repl_server
-
-            repl_port = args.port + 2  # HTTP=8000, WS=8001, REPL=8002
-            repl_server = await start_repl_server(patcher, server, port=repl_port)
-
-            print()
-            print("=" * 70)
-            print("REPL server started")
-            print(f"Connect with: py2max repl localhost:{repl_port}")
-            print("=" * 70)
-            print()
-
-            if args.repl:
-                # Show deprecation warning if --repl used without --log-file
-                print("WARNING: --repl flag without --log-file is deprecated.")
-                print("For single-terminal mode, use: --repl --log-file server.log")
-                print(
-                    "For client-server mode (recommended), in a separate terminal run:"
-                )
-                print(f"  py2max repl localhost:{repl_port}")
-                print()
-
-            # Keep running until interrupted
-            try:
-                while True:
-                    await asyncio.sleep(1)
-            except KeyboardInterrupt:
-                print("\nStopping server...")
-                repl_server.close()
-                await repl_server.wait_closed()
-                await server.stop()
-
-        asyncio.run(run_server())
-        return 0
-
-    except KeyboardInterrupt:
-        print("\nStopping server...")
-        return 0
-    except Exception as e:
-        print(f"Error starting server: {e}", file=sys.stderr)
-        import traceback
-
-        traceback.print_exc()
-        return 1
+    """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:
@@ -790,48 +696,16 @@ def cmd_preview(args: argparse.Namespace) -> int:
 
 
 def cmd_repl(args: argparse.Namespace) -> int:
-    """Connect to remote REPL server."""
-    import asyncio
-
-    # Parse server address
-    server = args.server
-    if ":" in server:
-        host, port_str = server.rsplit(":", 1)
-        try:
-            port = int(port_str)
-        except ValueError:
-            print(f"Invalid port number: {port_str}", file=sys.stderr)
-            return 1
-    else:
-        host = server
-        port = 9000
-
-    # Check if websockets is installed
-    import importlib.util
-
-    if importlib.util.find_spec("websockets") is None:
-        print("Error: websockets package required for REPL client.", file=sys.stderr)
-        print("Install with: pip install websockets", file=sys.stderr)
-        return 1
-
-    # Check if ptpython is installed
-    if importlib.util.find_spec("ptpython") is None:
-        print("Error: ptpython package required for REPL.", file=sys.stderr)
-        print("Install with: pip install ptpython or uv add ptpython", file=sys.stderr)
-        return 1
-
-    # Start REPL client
-    try:
-        from .server.client import start_repl_client
-
-        return asyncio.run(start_repl_client(host, port))
-
-    except KeyboardInterrupt:
-        print("\nDisconnected.")
-        return 0
-    except Exception as e:
-        print(f"Error: {e}", file=sys.stderr)
-        return 1
+    """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:
@@ -1228,6 +1102,12 @@ def build_parser() -> argparse.ArgumentParser:
         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
@@ -1242,8 +1122,8 @@ def main(argv: List[str] | None = None) -> int:
         return 1
 
     try:
-        return args.func(args)
-    except InvalidConnectionError as exc:
+        return cast(int, args.func(args))
+    except Py2MaxError as exc:
         print(f"Error: {exc}", file=sys.stderr)
         return 1
 

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

@@ -6,7 +6,7 @@ between core.py and layout.py modules.
 
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Any, Callable, Optional, Union
+from typing import Any, Callable, Dict, Iterator, Optional, Union
 
 from .common import Rect
 
@@ -60,7 +60,7 @@ class AbstractBox(ABC):
     id: Optional[str]
     maxclass: str
     patching_rect: Rect
-    _kwds: dict
+    _kwds: Dict[str, Any]
 
     @abstractmethod
     def render(self) -> None:
@@ -68,12 +68,12 @@ class AbstractBox(ABC):
         ...
 
     @abstractmethod
-    def to_dict(self) -> dict:
+    def to_dict(self) -> Dict[str, Any]:
         """Convert the box to a dictionary representation."""
         ...
 
     @abstractmethod
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Any]:
         """Make the box iterable."""
         ...
 
@@ -99,7 +99,7 @@ class AbstractPatchline(ABC):
         ...
 
     @abstractmethod
-    def to_dict(self) -> dict:
+    def to_dict(self) -> Dict[str, Any]:
         """Convert the patchline to a dictionary representation."""
         ...
 
@@ -143,4 +143,32 @@ class AbstractPatcher(ABC):
     _layout_mgr: AbstractLayoutManager
     _auto_hints: bool
     _validate_connections: bool
+    _validate_attrs: bool
     _maxclass_methods: dict[str, Callable[..., Any]]
+    _semantic_ids: bool
+    _semantic_counters: dict[str, int]
+    _device_type: str
+    classnamespace: str
+    _pending_comments: list[tuple[str, str, Optional[str]]]
+    # Rendered (dict) forms, populated by render() and read by serialization.
+    boxes: list[dict[str, Any]]
+    lines: list[dict[str, Any]]
+
+    # Core methods implemented by Patcher and relied on by the BoxFactory and
+    # serialization mixins. Declared here (non-abstract) so each mixin can be
+    # type-checked in isolation; Patcher provides the real implementations.
+    def get_id(self, object_name: Optional[str] = None) -> str:
+        """Generate an object id (implemented by Patcher)."""
+        raise NotImplementedError
+
+    def get_pos(self, maxclass: Optional[str] = None) -> Rect:
+        """Get a box position from the layout manager (implemented by Patcher)."""
+        raise NotImplementedError
+
+    def render(self, reset: bool = False) -> None:
+        """Render boxes/lines to dicts (implemented by Patcher)."""
+        raise NotImplementedError
+
+    def _process_pending_comments(self) -> None:
+        """Position deferred associated comments (implemented by Patcher)."""
+        raise NotImplementedError