py2max 0.2.1__py3-none-any.whl

py2max/core/__init__.py

@@ -0,0 +1,39 @@
+"""Core patcher functionality for py2max.
+
+This subpackage contains the core classes for creating and managing Max/MSP patches:
+
+- Patcher: Core class for creating and managing Max patches
+- Box: Represents individual Max objects
+- Patchline: Represents connections between objects
+- Rect: Rectangle data structure for positioning
+
+Abstract base classes are also provided for type checking and interface definitions.
+"""
+
+from py2max.exceptions import InvalidConnectionError
+
+from .abstract import (
+    AbstractBox,
+    AbstractLayoutManager,
+    AbstractPatcher,
+    AbstractPatchline,
+)
+from .box import Box
+from .common import Rect
+from .patcher import Patcher
+from .patchline import Patchline
+
+__all__ = [
+    # Core classes
+    "Patcher",
+    "Box",
+    "Patchline",
+    "Rect",
+    # Abstract base classes
+    "AbstractPatcher",
+    "AbstractBox",
+    "AbstractPatchline",
+    "AbstractLayoutManager",
+    # Backward compatibility - exceptions re-exported
+    "InvalidConnectionError",
+]

py2max/core/abstract.py

@@ -0,0 +1,146 @@
+"""Abstract base classes for py2max core objects.
+
+This module defines abstract base classes to break circular dependencies
+between core.py and layout.py modules.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+from .common import Rect
+
+
+class AbstractLayoutManager(ABC):
+    """Abstract base class for LayoutManager objects.
+
+    This class defines the interface that layout managers expect from
+    a LayoutManager object, allowing layout.py to reference LayoutManager without
+    creating circular imports.
+    """
+
+    # Required attributes
+    box_height: float
+
+    @abstractmethod
+    def get_rect_from_maxclass(self, maxclass: str) -> Optional[Rect]:
+        """retrieves default patching_rect from defaults dictionary."""
+        ...
+
+    @abstractmethod
+    def get_relative_pos(self, rect: Rect) -> Rect:
+        """returns a relative position for the object"""
+        ...
+
+    @abstractmethod
+    def get_absolute_pos(self, rect: Rect) -> Rect:
+        """returns an absolute position for the object"""
+        ...
+
+    @abstractmethod
+    def get_pos(self, maxclass: Optional[str] = None) -> Rect:
+        """get box rect (position) via maxclass or layout_manager"""
+        ...
+
+    @abstractmethod
+    def above(self, rect: Rect) -> Rect:
+        """Return a position of a comment above the object"""
+        ...
+
+
+class AbstractBox(ABC):
+    """Abstract base class for Box objects.
+
+    This class defines the interface that layout managers expect from
+    a Box object, allowing layout.py to reference Box without
+    creating circular imports.
+    """
+
+    # These are instance attributes, not properties
+    id: Optional[str]
+    maxclass: str
+    patching_rect: Rect
+    _kwds: dict
+
+    @abstractmethod
+    def render(self) -> None:
+        """Render the box object."""
+        ...
+
+    @abstractmethod
+    def to_dict(self) -> dict:
+        """Convert the box to a dictionary representation."""
+        ...
+
+    @abstractmethod
+    def __iter__(self):
+        """Make the box iterable."""
+        ...
+
+
+class AbstractPatchline(ABC):
+    """Abstract base class for Patchline objects.
+
+    This class defines the interface that layout managers expect from
+    a Patchline object, allowing layout.py to reference Patchline without
+    creating circular imports.
+    """
+
+    @property
+    @abstractmethod
+    def src(self) -> str:
+        """Source object identifier."""
+        ...
+
+    @property
+    @abstractmethod
+    def dst(self) -> str:
+        """Destination object identifier."""
+        ...
+
+    @abstractmethod
+    def to_dict(self) -> dict:
+        """Convert the patchline to a dictionary representation."""
+        ...
+
+
+class AbstractPatcher(ABC):
+    """Abstract base class for Patcher objects.
+
+    This class defines the interface that layout managers expect from
+    a Patcher object, allowing layout.py to reference Patcher without
+    creating circular imports.
+    """
+
+    @property
+    @abstractmethod
+    def width(self) -> float:
+        """Width of patcher window."""
+        ...
+
+    @property
+    @abstractmethod
+    def height(self) -> float:
+        """Height of patcher window."""
+        ...
+
+    # rect is an instance attribute, not a property
+    rect: Rect
+
+    _path: Optional[Union[str, Path]]
+    _parent: Optional["AbstractPatcher"]
+    _node_ids: list[str]
+    _objects: dict[str, AbstractBox]
+    _boxes: list[AbstractBox]
+    _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
+    _layout_mgr: AbstractLayoutManager
+    _auto_hints: bool
+    _validate_connections: bool
+    _maxclass_methods: dict[str, Callable[..., Any]]

py2max/core/box.py

@@ -0,0 +1,231 @@
+"""Box class for representing Max objects in a patch."""
+
+from typing import TYPE_CHECKING, List, Optional
+
+from .abstract import AbstractBox
+from .common import Rect
+
+if TYPE_CHECKING:
+    from .patcher import Patcher
+
+
+class Box(AbstractBox):
+    """Represents a Max object in a patch.
+
+    The Box class encapsulates a single Max object with its properties,
+    position, and connections. It provides methods for introspection
+    and help information.
+
+    Args:
+        maxclass: Max object class name (e.g., 'newobj', 'flonum').
+        numinlets: Number of input connections.
+        numoutlets: Number of output connections.
+        id: Unique identifier for the object.
+        patching_rect: Position and size rectangle.
+        **kwds: Additional Max object properties.
+
+    Attributes:
+        id: Unique identifier for the object.
+        maxclass: Max object class name.
+        numinlets: Number of input connections.
+        numoutlets: Number of output connections.
+        patching_rect: Position and size as Rect.
+    """
+
+    def __init__(
+        self,
+        maxclass: Optional[str] = None,
+        numinlets: Optional[int] = None,
+        numoutlets: Optional[int] = None,
+        id: Optional[str] = None,
+        patching_rect: Optional[Rect] = None,
+        **kwds,
+    ):
+        self.id = id
+        self.maxclass = maxclass or "newobj"
+        self.numinlets = numinlets or 0
+        self.numoutlets = numoutlets or 1
+        # self.outlettype = outlettype
+        self.patching_rect = patching_rect or Rect(0, 0, 62, 22)
+
+        self._kwds = self._remove_none_entries(kwds)
+        self._patcher: Optional["Patcher"] = self._kwds.pop("patcher", None)
+
+    def _remove_none_entries(self, kwds):
+        """removes items in the dict which have None values.
+
+        TODO: make recursive in case of nested dicts.
+        """
+        return {k: v for k, v in kwds.items() if v is not None}
+
+    def __iter__(self):
+        yield self
+        if self._patcher:
+            yield from iter(self._patcher)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(id='{self.id}', maxclass='{self.maxclass}')"
+
+    def __pt_repr__(self):
+        """Custom representation for ptpython REPL.
+
+        Provides rich colored output when displaying objects in the ptpython REPL.
+        Shows object type, ID, position, and text content in a readable format.
+        """
+        from prompt_toolkit.formatted_text import HTML
+
+        # Get object details
+        obj_type = self.maxclass or "newobj"
+        obj_id = self.id or "unknown"
+        text = getattr(self, "text", None) or ""
+
+        # Get position
+        rect = self.patching_rect
+        if rect:
+            pos = f"[{rect.x:.0f}, {rect.y:.0f}]"
+        else:
+            pos = "[?, ?]"
+
+        # Build colored representation
+        if text:
+            return HTML(
+                f"<ansigreen>{obj_type}</ansigreen> "
+                f"<ansicyan>{obj_id}</ansicyan> "
+                f"at {pos}: <ansiyellow>'{text}'</ansiyellow>"
+            )
+        else:
+            return HTML(
+                f"<ansigreen>{obj_type}</ansigreen> "
+                f"<ansicyan>{obj_id}</ansicyan> "
+                f"at {pos}"
+            )
+
+    def render(self):
+        """convert self and children to dictionary."""
+        if self._patcher:
+            self._patcher.render()
+            self.patcher = self._patcher.to_dict()
+
+    def to_dict(self):
+        """create dict from object with extra kwds included"""
+        d = vars(self).copy()
+        to_del = [k for k in d if k.startswith("_")]
+        for k in to_del:
+            del d[k]
+        d.update(self._kwds)
+        return dict(box=d)
+
+    @classmethod
+    def from_dict(cls, obj_dict):
+        """create instance from dict"""
+        box = cls()
+        box.__dict__.update(obj_dict)
+        if hasattr(box, "patcher"):
+            # Lazy import to avoid circular dependency
+            from .patcher import Patcher
+
+            box._patcher = Patcher.from_dict(getattr(box, "patcher"))
+        return box
+
+    @property
+    def oid(self) -> Optional[int]:
+        """numerical part of object id as int"""
+        if self.id:
+            return int(self.id[4:])
+        return None
+
+    @property
+    def subpatcher(self):
+        """synonym for parent patcher object"""
+        return self._patcher
+
+    @property
+    def text(self):
+        """Get the text content of the box."""
+        # Check if text is stored as a direct attribute (from file loading)
+        if "text" in self.__dict__:
+            return self.__dict__["text"]
+        # Otherwise get from _kwds (from programmatic creation)
+        return self._kwds.get("text", "")
+
+    def help_text(self) -> str:
+        """Get formatted help documentation for this Max object.
+
+        Returns:
+            Formatted help string with object documentation from .maxref.xml files.
+        """
+        from py2max import maxref
+
+        return maxref.get_object_help(self.maxclass)
+
+    def help(self) -> None:
+        """Print formatted help documentation for this Max object."""
+        print(self.help_text())
+
+    def get_info(self) -> Optional[dict]:
+        """Get complete object information from .maxref.xml files.
+
+        Returns:
+            Dictionary with complete object information or None if not found.
+        """
+        from py2max import maxref
+
+        return maxref.get_object_info(self.maxclass)
+
+    def get_inlet_count(self) -> Optional[int]:
+        """Get the number of inlets for this object from maxref data.
+
+        Returns:
+            Number of inlets or None if unknown.
+        """
+        from py2max.maxref import get_inlet_count
+
+        object_name = self._get_object_name()
+        return get_inlet_count(object_name)
+
+    def get_outlet_count(self) -> Optional[int]:
+        """Get the number of outlets for this object from maxref data.
+
+        Returns:
+            Number of outlets or None if unknown.
+        """
+        from py2max.maxref import get_outlet_count
+
+        object_name = self._get_object_name()
+        return get_outlet_count(object_name)
+
+    def get_inlet_types(self) -> List[str]:
+        """Get the inlet types for this object from maxref data
+
+        Returns:
+            List of inlet type strings
+        """
+        from py2max.maxref import get_inlet_types
+
+        object_name = self._get_object_name()
+        return get_inlet_types(object_name)
+
+    def get_outlet_types(self) -> List[str]:
+        """Get the outlet types for this object from maxref data
+
+        Returns:
+            List of outlet type strings
+        """
+        from py2max.maxref import get_outlet_types
+
+        object_name = self._get_object_name()
+        return get_outlet_types(object_name)
+
+    def _get_object_name(self) -> str:
+        """Get the actual object name for this Box.
+
+        For 'newobj' maxclass objects, extract the first word from the text field.
+        For other objects, use the maxclass directly.
+        """
+        if self.maxclass == "newobj":
+            # Text is stored in _kwds for Box objects
+            text = self._kwds.get("text", "")
+            if text:
+                # Extract the first word from text (the object name)
+                return text.split()[0] if text.split() else self.maxclass
+        return self.maxclass

py2max/core/common.py

@@ -0,0 +1,19 @@
+"""Common data structures and utilities for py2max.
+
+This module contains shared data structures used throughout the py2max library.
+"""
+
+from typing import NamedTuple
+
+
+class Rect(NamedTuple):
+    """Rectangle data structure for object positioning.
+
+    Represents a rectangular area in Max patch coordinates using four coordinates:
+    x (horizontal position), y (vertical position), w (width), and h (height).
+    """
+
+    x: float
+    y: float
+    w: float
+    h: float