py2max 0.3.4__tar.gz → 0.3.6__tar.gz

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

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.3.6]
+
+### Removed: incremental layout; `optimize_layout()` is batch-only again
+
+- `Patcher.optimize_layout()` no longer takes the `changed_objects` parameter added in 0.3.5 -- it takes no arguments and always performs a full, whole-patch layout. The incremental machinery in the layout managers was removed with it: `LayoutManager.should_use_incremental`, `get_affected_objects`, `get_connected_objects`, `_incremental_layout`, `_find_non_overlapping_position`, and the `INCREMENTAL_THRESHOLD` constant (`layout/base.py`); the `optimize_layout(changed_objects)` overrides in `layout/grid.py` and `layout/flow.py` (they now implement `_full_layout` and inherit the batch entry point, with flow's `<2 objects` guard moved into `_full_layout`); and `layout/matrix.py`'s override (now `_full_layout`, with `ColumnarLayoutManager` inheriting it).
+- **Rationale (scope split):** py2max owns *batch* layout -- arranging a whole patch once, typically at the end of programmatic creation. Interactive, per-edit ("live") relayout belongs to the editor that owns the editing session (`py2max-server`), which handles it client-side. The incremental path existed only to serve that live case and was never exercised by a batch caller (batch `optimize_layout()` always passed `changed_objects=None`), so it was dead weight in the library. This reverses the 0.3.5 change, which had added the parameter as a prerequisite for a server-side auto-layout approach that was subsequently dropped.
+- **Breaking:** calling `optimize_layout()` with an argument (e.g. `optimize_layout({obj.id})`) now raises `TypeError`; drop the argument. The `test_optimize_layout_forwards_changed_objects` / `..._incremental_leaves_untouched_objects_fixed` regression tests were replaced by `test_optimize_layout_is_batch_only`.
+
+## [0.3.5]
+
+### Fixed: `Patcher.optimize_layout()` now reaches the incremental layout path
+
+- `Patcher.optimize_layout()` gained an optional `changed_objects: Optional[Set[str]]` parameter and forwards it to the layout manager. It previously called the manager with no arguments, silently discarding any change set, so the incremental layout engine (`layout/base.py` `optimize_layout(changed_objects)` / `should_use_incremental` / `_incremental_layout`) was unreachable through the public API -- every call forced a full relayout. Passing a set of object IDs now lets managers that support it (grid, flow) reposition only those objects and their patchline neighbours; `None` (the default) preserves the previous full-relayout behaviour, so the change is backward compatible. Matrix/columnar managers still recompute in full (they ignore the argument by design). This is the core prerequisite for server-side auto-layout, which lives in `py2max-server`.
+
 ## [0.3.4]
 
 ### New: Param docking in layouts

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py2max
-Version: 0.3.4
+Version: 0.3.6
 Summary: A library for offline generation of Max/MSP patcher (.maxpat) files.
 Keywords: Max,maxpat,offline
 Author: Shakeeb Alireza

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

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

{py2max-0.3.4 → py2max-0.3.6}/py2max/core/patcher.py

@@ -657,18 +657,20 @@ class Patcher(BoxFactoryMixin, SerializationMixin, AbstractPatcher):
         return self._layout_mgr.get_pos()
 
     def optimize_layout(self) -> None:
-        """Optimize object positions based on layout manager type.
+        """Arrange the whole patch based on the active layout manager.
 
-        Calls the layout manager's optimization method to improve object
-        positioning, then repositions any associated comments based on
-        the new box positions. The effect depends on the layout manager:
+        Calls the layout manager to lay out every object, then repositions any
+        associated comments based on the new box positions. The effect depends
+        on the layout manager:
 
         - FlowLayoutManager: Arranges objects by signal flow topology
         - GridLayoutManager: Clusters connected objects together
         - Other managers: May have limited or no effect
 
-        This method should be called after all objects and connections
-        have been added to the patch.
+        This is a batch, whole-patch operation intended to be called once after
+        all objects and connections have been added. Interactive, per-edit
+        relayout is out of scope for py2max (see ``docs/auto-layout.md`` in
+        py2max-server).
         """
         if hasattr(self._layout_mgr, "optimize_layout"):
             self._layout_mgr.optimize_layout()

{py2max-0.3.4 → py2max-0.3.6}/py2max/layout/base.py

@@ -3,17 +3,12 @@
 This module provides the base LayoutManager class that all layout managers inherit from.
 """
 
-from typing import Any, Dict, List, Optional, Set, Tuple, cast
+from typing import Any, Dict, List, Optional, Tuple, cast
 
 from py2max.core.abstract import AbstractLayoutManager, AbstractPatcher
 from py2max.core.common import Rect
 from py2max.maxref import MAXCLASS_DEFAULTS
 
-from .graph import PatchGraph
-
-# Threshold for incremental vs full layout (30% of total objects)
-INCREMENTAL_THRESHOLD = 0.3
-
 # Value/UI "param" objects: their role is to set a value on one object's inlet,
 # so they read better docked next to that object than spread through the graph.
 PARAM_MAXCLASSES = frozenset(
@@ -358,81 +353,18 @@ class LayoutManager(AbstractLayoutManager):
             return tx + tw / 2
         return tx + tw * min(inlet, n_inlets - 1) / (n_inlets - 1)
 
-    def get_connected_objects(self, obj_ids: Set[str]) -> Set[str]:
-        """Get all objects connected to the given objects via patchlines.
-
-        Args:
-            obj_ids: Set of object IDs to find connections for.
-
-        Returns:
-            Set of object IDs that are directly connected to the input objects.
-        """
-        return PatchGraph(self.parent._lines).neighbors_of(obj_ids)
-
-    def get_affected_objects(self, changed_objects: Set[str]) -> Set[str]:
-        """Get all objects affected by changes to the given objects.
-
-        This includes the changed objects themselves plus their immediate
-        neighbors (objects connected via patchlines).
-
-        Args:
-            changed_objects: Set of object IDs that have changed.
-
-        Returns:
-            Set of all affected object IDs.
-        """
-        affected = set(changed_objects)
-        neighbors = self.get_connected_objects(changed_objects)
-        affected.update(neighbors)
-        return affected
-
-    def should_use_incremental(self, changed_objects: Optional[Set[str]]) -> bool:
-        """Determine whether to use incremental or full layout.
-
-        Uses incremental layout when:
-        - changed_objects is provided
-        - The number of affected objects is less than INCREMENTAL_THRESHOLD
-          of total objects
-
-        Args:
-            changed_objects: Set of changed object IDs, or None for full layout.
-
-        Returns:
-            True if incremental layout should be used.
-        """
-        if changed_objects is None:
-            return False
-
-        total_objects = len(self.parent._objects)
-        if total_objects == 0:
-            return False
-
-        affected = self.get_affected_objects(changed_objects)
-        return len(affected) < total_objects * INCREMENTAL_THRESHOLD
+    def optimize_layout(self) -> None:
+        """Arrange every object in the patch (batch, whole-patch layout).
 
-    def optimize_layout(self, changed_objects: Optional[Set[str]] = None) -> None:
-        """Optimize the layout of objects.
+        This is py2max's batch layout entry point: it always performs a full
+        layout of the entire patch. Subclasses implement their algorithm in
+        ``_full_layout()``.
 
-        If changed_objects is provided and the number of affected objects
-        is small relative to the total, only those objects and their
-        neighbors will be repositioned (incremental layout). Otherwise,
-        a full layout recalculation is performed.
-
-        Args:
-            changed_objects: Optional set of object IDs that have changed.
-                If None, performs full layout optimization.
-
-        Subclasses should override _full_layout() and optionally
-        _incremental_layout() to implement specific algorithms.
+        Interactive, per-edit ("incremental") relayout is intentionally out of
+        scope for py2max; it belongs to the editor/server that owns the live
+        editing session. See ``docs/auto-layout.md`` in py2max-server.
         """
-        if self.should_use_incremental(changed_objects):
-            # changed_objects is guaranteed non-None here since should_use_incremental
-            # returns False when changed_objects is None
-            assert changed_objects is not None
-            affected = self.get_affected_objects(changed_objects)
-            self._incremental_layout(affected)
-        else:
-            self._full_layout()
+        self._full_layout()
 
     def _full_layout(self) -> None:
         """Perform full layout optimization.
@@ -441,120 +373,3 @@ class LayoutManager(AbstractLayoutManager):
         full layout algorithm.
         """
         pass
-
-    def _incremental_layout(self, affected_objects: Set[str]) -> None:
-        """Perform incremental layout optimization for affected objects.
-
-        This method repositions only the affected objects while keeping
-        other objects in their current positions. The default implementation
-        finds optimal positions for affected objects that minimize overlap
-        with existing objects.
-
-        Args:
-            affected_objects: Set of object IDs to reposition.
-
-        Subclasses can override this for more sophisticated incremental layouts.
-        """
-        if not affected_objects:
-            return
-
-        # Get current positions of non-affected objects (these are fixed)
-        fixed_positions: Dict[str, Rect] = {}
-        for obj_id, obj in self.parent._objects.items():
-            if obj_id not in affected_objects:
-                if hasattr(obj, "patching_rect"):
-                    fixed_positions[obj_id] = obj.patching_rect
-
-        # For each affected object, find a position that doesn't overlap
-        for obj_id in affected_objects:
-            if obj_id not in self.parent._objects:
-                continue
-
-            obj = self.parent._objects[obj_id]
-            if not hasattr(obj, "patching_rect"):
-                continue
-
-            current_rect = obj.patching_rect
-
-            # Try to find a nearby position that doesn't overlap
-            best_pos = self._find_non_overlapping_position(
-                current_rect, fixed_positions, affected_objects
-            )
-
-            if best_pos:
-                obj.patching_rect = best_pos
-                # Add to fixed positions for subsequent objects
-                fixed_positions[obj_id] = best_pos
-
-        # Final overlap prevention pass
-        self.prevent_overlaps()
-
-    def _find_non_overlapping_position(
-        self,
-        rect: Rect,
-        fixed_positions: Dict[str, Rect],
-        exclude_ids: Set[str],
-    ) -> Optional[Rect]:
-        """Find a position for rect that doesn't overlap with fixed positions.
-
-        Tries positions in a spiral pattern around the current position.
-
-        Args:
-            rect: The rectangle to position.
-            fixed_positions: Dictionary of fixed object positions.
-            exclude_ids: Object IDs to exclude from overlap checking.
-
-        Returns:
-            A non-overlapping Rect, or the original rect if no better position found.
-        """
-        pad = self.pad
-        min_gap = 10.0
-
-        def overlaps_any(test_rect: Rect) -> bool:
-            for obj_id, fixed_rect in fixed_positions.items():
-                if obj_id in exclude_ids:
-                    continue
-                # Check overlap
-                if (
-                    test_rect.x < fixed_rect.x + fixed_rect.w + min_gap
-                    and fixed_rect.x < test_rect.x + test_rect.w + min_gap
-                    and test_rect.y < fixed_rect.y + fixed_rect.h + min_gap
-                    and fixed_rect.y < test_rect.y + test_rect.h + min_gap
-                ):
-                    return True
-            return False
-
-        # If current position doesn't overlap, keep it
-        if not overlaps_any(rect):
-            return rect
-
-        # Try positions in a spiral pattern
-        step = pad / 2
-        max_radius = max(self.parent.width, self.parent.height) / 2
-
-        for radius in range(1, int(max_radius / step) + 1):
-            offset = radius * step
-            # Try 8 directions
-            for dx, dy in [
-                (offset, 0),
-                (-offset, 0),
-                (0, offset),
-                (0, -offset),
-                (offset, offset),
-                (-offset, offset),
-                (offset, -offset),
-                (-offset, -offset),
-            ]:
-                new_x = rect.x + dx
-                new_y = rect.y + dy
-
-                # Ensure within bounds
-                new_x = max(pad, min(new_x, self.parent.width - rect.w - pad))
-                new_y = max(pad, min(new_y, self.parent.height - rect.h - pad))
-
-                test_rect = Rect(new_x, new_y, rect.w, rect.h)
-                if not overlaps_any(test_rect):
-                    return test_rect
-
-        # No non-overlapping position found, return original
-        return rect

{py2max-0.3.4 → py2max-0.3.6}/py2max/layout/flow.py

@@ -365,27 +365,11 @@ class FlowLayoutManager(LayoutManager):
 
         return Rect(x, y, w, h)
 
-    def optimize_layout(self, changed_objects: Optional[Set[str]] = None) -> None:
-        """Optimize the layout of all existing objects based on their connections.
-
-        Args:
-            changed_objects: Optional set of object IDs that have changed.
-                If provided and small relative to total objects, only
-                affected objects will be repositioned (incremental layout).
-        """
+    def _full_layout(self) -> None:
+        """Perform full layout optimization based on signal flow analysis."""
         if len(self.parent._objects) < 2:
             return  # Nothing to optimize
 
-        # Use parent's incremental layout decision logic
-        if self.should_use_incremental(changed_objects):
-            assert changed_objects is not None
-            affected = self.get_affected_objects(changed_objects)
-            self._incremental_layout(affected)
-        else:
-            self._full_layout()
-
-    def _full_layout(self) -> None:
-        """Perform full layout optimization based on signal flow analysis."""
         positions = self._calculate_positions()
 
         # Apply optimized positions to existing objects. The computed position

{py2max-0.3.4 → py2max-0.3.6}/py2max/layout/grid.py

@@ -83,22 +83,6 @@ class GridLayoutManager(LayoutManager):
         x = pad + x_shift
         return Rect(x, y, w, h)
 
-    def optimize_layout(self, changed_objects: Optional[Set[str]] = None) -> None:
-        """Optimize the layout to cluster connected objects together.
-
-        Args:
-            changed_objects: Optional set of object IDs that have changed.
-                If provided and small relative to total objects, only
-                affected objects will be repositioned (incremental layout).
-        """
-        # Use parent's incremental layout decision logic
-        if self.should_use_incremental(changed_objects):
-            assert changed_objects is not None
-            affected = self.get_affected_objects(changed_objects)
-            self._incremental_layout(affected)
-        else:
-            self._full_layout()
-
     def _full_layout(self) -> None:
         """Perform full layout optimization."""
         if not self.cluster_connected or len(self.parent._objects) < 2:

{py2max-0.3.4 → py2max-0.3.6}/py2max/layout/matrix.py

@@ -3,7 +3,7 @@
 This module provides MatrixLayoutManager for matrix and columnar-based layouts.
 """
 
-from typing import Any, Dict, List, Optional, Set, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 
 from py2max.core.abstract import AbstractBox, AbstractPatcher
 from py2max.core.common import Rect
@@ -272,12 +272,11 @@ class MatrixLayoutManager(LayoutManager):
 
         return Rect(x, y, w, h)
 
-    def optimize_layout(self, changed_objects: Optional[Set[str]] = None) -> None:
-        """Optimize the layout based on flow_direction setting.
+    def _full_layout(self) -> None:
+        """Arrange objects based on the ``flow_direction`` setting.
 
-        ``changed_objects`` is accepted for interface compatibility with
-        ``LayoutManager`` but ignored: the matrix layout always recomputes the
-        full arrangement from the signal-chain analysis.
+        The matrix layout always recomputes the full arrangement from the
+        signal-chain analysis.
         """
         if len(self.parent._objects) < 1:
             return

{py2max-0.3.4 → py2max-0.3.6}/pyproject.toml

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

{py2max-0.3.4 → py2max-0.3.6}/tests/test_patcher.py

@@ -2,6 +2,7 @@ from pathlib import Path
 
 from py2max import Patcher
 import json
+import pytest
 
 DATA_DIR = Path(__file__).parent / "data"
 
@@ -33,6 +34,35 @@ def test_patcher_from_file():
     p.save_as("outputs/test_complex2.maxpat")
 
 
+def test_optimize_layout_is_batch_only():
+    """``optimize_layout`` is a batch, whole-patch operation that takes no
+    arguments.
+
+    Interactive, per-edit ("incremental") relayout was intentionally removed
+    from py2max; it belongs to the editor/server that owns the live editing
+    session (see docs/auto-layout.md in py2max-server). Passing a change set is
+    therefore a TypeError, at both the facade and the layout-manager level.
+    """
+    p = Patcher("outputs/test_optimize_batch_only.maxpat", layout="grid")
+    a = p.add_textbox("cycle~ 440")
+    b = p.add_textbox("gain~")
+    p.add_line(a, b)
+
+    # The batch call arranges every object and must not raise.
+    p.optimize_layout()
+    assert a.patching_rect and b.patching_rect
+
+    # The removed incremental API is gone at both levels.
+    with pytest.raises(TypeError):
+        p.optimize_layout({a.id})  # type: ignore[call-arg]
+    with pytest.raises(TypeError):
+        p._layout_mgr.optimize_layout({a.id})  # type: ignore[call-arg]
+
+    # The incremental helpers no longer exist on the layout manager.
+    assert not hasattr(p._layout_mgr, "should_use_incremental")
+    assert not hasattr(p._layout_mgr, "_incremental_layout")
+
+
 def test_patcher_from_file_comparison_complex():
     pd = Patcher.from_file(DATA_DIR / "complex.maxpat").to_dict()
     with open(DATA_DIR / "complex.maxpat") as f: