Core: Patcher, Box, Patchline¶

py2max.core.Patcher ¶

Bases: BoxFactoryMixin, SerializationMixin, AbstractPatcher

Core class for creating and managing Max/MSP patches.

The Patcher class provides a high-level interface for creating Max/MSP patches programmatically. It handles object positioning, connection validation, and automatic layout management.

Features

Automatic object positioning with multiple layout managers
Connection validation using Max object metadata
Support for all major Max object types
Hierarchical patch organization with subpatchers
Export to .maxpat file format

Parameters:

Name	Type	Description	Default
`path`	`Optional[Union[str, Path]]`	Output file path for the patch.	`None`
`title`	`Optional[str]`	Optional title for the patch.	`None`
`parent`	`Optional[AbstractPatcher]`	Parent patcher for hierarchical organization.	`None`
`classnamespace`	`Optional[str]`	Namespace for object classes (e.g., 'rnbo').	`None`
`reset_on_render`	`bool`	Whether to reset layout on render.	`True`
`layout`	`str`	Layout manager type ('horizontal', 'vertical', 'grid', 'flow', 'matrix').	`'horizontal'`
`auto_hints`	`bool`	Whether to automatically generate object hints.	`False`
`openinpresentation`	`int`	Presentation mode setting.	`0`
`validate_connections`	`bool`	Whether to validate patchline connections.	`False`
`validate_attrs`	`bool`	Whether to warn (UserWarning) when an object is given a keyword that is not a known attribute for its Max class -- catches typos like `inital=` for `initial=`. Off by default.	`False`
`flow_direction`	`str`	Direction for flow-based layouts ('horizontal', 'vertical').	`'horizontal'`
`cluster_connected`	`bool`	Whether to cluster connected objects in grid layout.	`False`
`num_dimensions`	`int`	Number of rows used by the matrix layout (also treated as column count when flow_direction='column').	`4`
`dimension_spacing`	`float`	Spacing between rows/columns for matrix layout variants.	`100.0`
`semantic_ids`	`bool`	Whether to generate semantic IDs based on object names (e.g., 'cycle_1') instead of numeric IDs (e.g., 'obj-1'). Enables more readable debugging.	`False`

Example

p = Patcher('my-patch.maxpat', layout='grid') osc = p.add_textbox('cycle~ 440') gain = p.add_textbox('gain~') p.add_line(osc, gain) p.save()

With semantic IDs¶

p = Patcher('my-patch.maxpat', semantic_ids=True) osc1 = p.add_textbox('cycle~ 440') # ID: 'cycle_1' osc2 = p.add_textbox('cycle~ 220') # ID: 'cycle_2' gain = p.add_textbox('gain~') # ID: 'gain_1'

width `property` ¶

width: float

width of patcher window.

height `property` ¶

height: float

height of patcher windows.

to_dict ¶

to_dict() -> Dict[str, Any]

create dict from object with extra kwds included

to_json ¶

to_json() -> str

cascade convert to json

save_as ¶

save_as(path: Union[str, Path]) -> None

Save the patch to a specified file path.

Renders all objects and connections, then saves the patch as a .maxpat JSON file (or a binary .amxd) that can be opened in Max/MSP.

Parameters:

Name	Type	Description	Default
`path`	`Union[str, Path]`	File path where the patch should be saved.	required

Raises:

Type	Description
`PatcherIOError`	If file cannot be written or path is invalid.

save ¶

save() -> None

Save the patch to the default file path.

Uses the path specified during Patcher creation. If no path was specified, this method will do nothing. Before saving, processes any pending associated comments to ensure they are positioned correctly relative to their boxes.

add_box ¶

add_box(
    box: Box,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
) -> Box

registers the box and adds it to the patcher

add_associated_comment ¶

add_associated_comment(
    box: Box,
    comment: str,
    comment_pos: Optional[str] = None,
) -> None

Store a comment association to be processed later during layout optimization or save.

This defers the actual comment positioning until after layout optimization, ensuring comments stay properly positioned relative to their associated boxes.

add_patchline_by_index ¶

add_patchline_by_index(
    src_id: str,
    dst_id: str,
    dst_inlet: int = 0,
    src_outlet: int = 0,
) -> Patchline

Patchline creation between two objects using stored indexes

add_patchline ¶

add_patchline(
    src_id: str,
    src_outlet: int,
    dst_id: str,
    dst_inlet: int,
) -> Patchline

Primary patchline creation method with validation and logging.

Parameters:

Name	Type	Description	Default
`src_id`	`str`	Source object ID.	required
`src_outlet`	`int`	Source outlet index.	required
`dst_id`	`str`	Destination object ID.	required
`dst_inlet`	`int`	Destination inlet index.	required

Returns:

Type	Description
`Patchline`	Created Patchline object.

Raises:

Type	Description
`InvalidConnectionError`	If connection validation fails.

add_line ¶

add_line(
    src_obj: Box,
    dst_obj: Box,
    inlet: int = 0,
    outlet: int = 0,
) -> Patchline

Create a connection between two objects.

Connects an outlet of the source object to an inlet of the destination object. Validates the connection if validation is enabled.

Parameters:

Name	Type	Description	Default
`src_obj`	`Box`	Source object to connect from.	required
`dst_obj`	`Box`	Destination object to connect to.	required
`inlet`	`int`	Destination inlet index (default: 0).	`0`
`outlet`	`int`	Source outlet index (default: 0).	`0`

Returns:

Type	Description
`Patchline`	The created Patchline object.

Raises:

Type	Description
`InvalidConnectionError`	If connection validation fails.

Example

osc = p.add_textbox('cycle~ 440') gain = p.add_textbox('gain~') p.add_line(osc, gain) # Connect outlet 0 to inlet 0

add_textbox ¶

add_textbox(
    text: str,
    maxclass: Optional[str] = None,
    numinlets: Optional[int] = None,
    numoutlets: Optional[int] = None,
    outlettype: Optional[List[str]] = None,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a text-based Max object to the patch.

Creates a Max object from a text specification (e.g., 'cycle~ 440'). Automatically looks up default attributes and applies appropriate maxclass based on the object type.

Parameters:

Name	Type	Description	Default
`text`	`str`	Max object specification (e.g., 'cycle~ 440', 'gain~').	required
`maxclass`	`Optional[str]`	Override the automatically determined maxclass.	`None`
`numinlets`	`Optional[int]`	Number of input connections.	`None`
`numoutlets`	`Optional[int]`	Number of output connections.	`None`
`outlettype`	`Optional[List[str]]`	Types of outputs (e.g., ['signal', 'int']).	`None`
`patching_rect`	`Optional[Rect]`	Position and size rectangle.	`None`
`id`	`Optional[str]`	Unique identifier for the object.	`None`
`comment`	`Optional[str]`	Optional comment text.	`None`
`comment_pos`	`Optional[str]`	Comment position ('above', 'below', etc.).	`None`
`**kwds`	`Any`	Additional Max object properties.	`{}`

Returns:

Type	Description
`Box`	The created Box object.

Example

osc = p.add_textbox('cycle~ 440') gain = p.add_textbox('gain~') metro = p.add_textbox('metro 500')

add ¶

add(value: Any, *args: Any, **kwds: Any) -> Box

generic adder: value can be a number or a list or text for an object.

add_codebox ¶

add_codebox(
    code: str,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    tilde: bool = False,
    **kwds: Any,
) -> Box

Add a codebox.

add_codebox_tilde ¶

add_codebox_tilde(
    code: str,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a codebox_tilde

add_message ¶

add_message(
    text: Optional[str] = None,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a max message.

add_comment ¶

add_comment(
    text: str,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    justify: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a basic comment object.

add_intbox ¶

add_intbox(
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    **kwds: Any,
) -> Box

Add an int box object.

add_floatbox ¶

add_floatbox(
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    **kwds: Any,
) -> Box

Add an float box object.

add_floatparam ¶

add_floatparam(
    longname: str,
    initial: Optional[float] = None,
    minimum: Optional[float] = None,
    maximum: Optional[float] = None,
    shortname: Optional[str] = None,
    id: Optional[str] = None,
    rect: Optional[Rect] = None,
    hint: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a float parameter object.

add_intparam ¶

add_intparam(
    longname: str,
    initial: Optional[int] = None,
    minimum: Optional[int] = None,
    maximum: Optional[int] = None,
    shortname: Optional[str] = None,
    id: Optional[str] = None,
    rect: Optional[Rect] = None,
    hint: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add an int parameter object.

add_pattrstorage ¶

add_pattrstorage(name: str = 'presets', **kwds: Any) -> Box

Add a pattrstorage object for saving and recalling named presets.

pattrstorage stores presets of every parameter-enabled and pattr-bound object in the patcher. Pair it with :meth:add_autopattr (or use :meth:add_preset_system) so named objects are exposed automatically.

Parameters:

Name	Type	Description	Default
`name`	`str`	the storage name (the pattrstorage argument).	`'presets'`
`**kwds`	`Any`	extra attributes forwarded to the box.	`{}`

add_autopattr ¶

add_autopattr(**kwds: Any) -> Box

Add an autopattr object exposing named objects to the pattr system.

Any object with a scripting name (varname) is bound automatically, so it participates in pattrstorage presets without a per-object pattr.

add_preset_system ¶

add_preset_system(
    name: str = "presets", **kwds: Any
) -> Tuple[Box, Box]

Add a standard preset system: autopattr + pattrstorage, wired.

Connects autopattr to pattrstorage so that any object with a scripting name (varname) or parameter_enable=1 participates in presets. Returns (autopattr_box, pattrstorage_box).

enable_parameter ¶

enable_parameter(
    box: Box,
    longname: str,
    shortname: str = "",
    ptype: int = 0,
    initial: Optional[float] = None,
) -> Box

Mark an existing box as a Max parameter.

Parameterized objects participate in pattrstorage presets and, in a Max for Live device, appear as automatable parameters. Use this to turn a plain UI object (toggle, dial, slider, ...) into a parameter without rebuilding it.

Parameters:

Name	Type	Description	Default
`box`	`Box`	the box to parameterize.	required
`longname`	`str`	parameter long name (its preset/automation name).	required
`shortname`	`str`	optional short name.	`''`
`ptype`	`int`	parameter type (0=float, 1=int, 2=enum, 3=blob).	`0`
`initial`	`Optional[float]`	optional initial value.	`None`

Returns:

Type	Description
`Box`	The same box, for chaining.

add_attr ¶

add_attr(
    name: str,
    value: float,
    shortname: Optional[str] = None,
    id: Optional[str] = None,
    rect: Optional[Rect] = None,
    hint: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    autovar: bool = True,
    show_label: bool = False,
    **kwds: Any,
) -> Box

create a param-linke attrui entry

add_subpatcher ¶

add_subpatcher(
    text: str,
    maxclass: Optional[str] = None,
    numinlets: Optional[int] = None,
    numoutlets: Optional[int] = None,
    outlettype: Optional[List[str]] = None,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    patcher: Optional[Patcher] = None,
    **kwds: Any,
) -> Box

Add a subpatcher object.

encapsulate ¶

encapsulate(
    boxes: Iterable[Box],
    text: str = "p subpatch",
    **kwds: Any,
) -> Box

Wrap the given boxes into a subpatcher, auto-generating inlet/outlet objects for connections that cross the selection boundary.

Connections wholly inside the selection move into the subpatcher.
Connections crossing in/out are rewired through generated inlet / outlet objects and the new subpatcher box's ports.
Connections wholly outside the selection are left untouched.

Inlets/outlets are de-duplicated by source port, so multiple wires from the same outlet share a single port, matching how patches are usually built by hand.

Parameters:

Name	Type	Description	Default
`boxes`	`Iterable[Box]`	boxes belonging to this patcher to move into a subpatcher.	required
`text`	`str`	the subpatcher box text (e.g. `"p voice"`).	`'p subpatch'`
`**kwds`	`Any`	forwarded to `add_subpatcher` (e.g. `patching_rect`).	`{}`

Returns:

Type	Description
`Box`	The new subpatcher Box added to this patcher.

add_gen ¶

add_gen(
    text: Optional[str] = None,
    tilde: bool = False,
    **kwds: Any,
) -> Box

Add a gen object.

add_gen_tilde ¶

add_gen_tilde(
    text: Optional[str] = None, **kwds: Any
) -> Box

Add a gen~ object.

add_rnbo ¶

add_rnbo(text: str = 'rnbo~', **kwds: Any) -> Box

Add an rnbo~ object.

add_mc ¶

add_mc(
    text: str, chans: Optional[int] = None, **kwds: Any
) -> Box

Add a multichannel (mc.) object.

Prefixes mc. to the object name if not already present, and appends an @chans attribute when chans is given. A single patchline between two mc. objects carries all channels.

Example

p.add_mc("cycle~ 440", chans=4) # -> "mc.cycle~ 440 @chans 4"

add_poly ¶

add_poly(target: str, voices: int = 1, **kwds: Any) -> Box

Add a poly~ object hosting voices instances of target.

target is the patch (or subpatcher) name loaded into each voice.

Example

p.add_poly("mysynth", 8) # -> "poly~ mysynth 8"

add_coll ¶

add_coll(
    name: Optional[str] = None,
    dictionary: Optional[Dict[Any, Any]] = None,
    embed: int = 1,
    patching_rect: Optional[Rect] = None,
    text: Optional[str] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a coll object with option to pre-populate from a py dictionary.

add_dict ¶

add_dict(
    name: Optional[str] = None,
    dictionary: Optional[Dict[Any, Any]] = None,
    embed: int = 1,
    patching_rect: Optional[Rect] = None,
    text: Optional[str] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a dict object with option to pre-populate from a py dictionary.

add_table ¶

add_table(
    name: Optional[str] = None,
    array: Optional[List[Union[int, float]]] = None,
    embed: int = 1,
    patching_rect: Optional[Rect] = None,
    text: Optional[str] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    tilde: bool = False,
    **kwds: Any,
) -> Box

Add a table object with option to pre-populate from a py list.

add_table_tilde ¶

add_table_tilde(
    name: Optional[str] = None,
    array: Optional[List[Union[int, float]]] = None,
    embed: int = 1,
    patching_rect: Optional[Rect] = None,
    text: Optional[str] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a table~ object with option to pre-populate from a py list.

add_itable ¶

add_itable(
    name: Optional[str] = None,
    array: Optional[List[Union[int, float]]] = None,
    patching_rect: Optional[Rect] = None,
    text: Optional[str] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a itable object with option to pre-populate from a py list.

add_umenu ¶

add_umenu(
    prefix: Optional[str] = None,
    autopopulate: int = 1,
    items: Optional[List[str]] = None,
    patching_rect: Optional[Rect] = None,
    depth: Optional[int] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a umenu object with option to pre-populate items from a py list.

add_bpatcher ¶

add_bpatcher(
    name: str,
    numinlets: int = 1,
    numoutlets: int = 1,
    outlettype: Optional[List[str]] = None,
    bgmode: int = 0,
    border: int = 0,
    clickthrough: int = 0,
    enablehscroll: int = 0,
    enablevscroll: int = 0,
    lockeddragscroll: int = 0,
    offset: Optional[List[float]] = None,
    viewvisibility: int = 1,
    patching_rect: Optional[Rect] = None,
    id: Optional[str] = None,
    comment: Optional[str] = None,
    comment_pos: Optional[str] = None,
    **kwds: Any,
) -> Box

Add a bpatcher object -- name or patch of bpatcher .maxpat is required.

add_beap ¶

add_beap(name: str, **kwds: Any) -> Box

Add a beap bpatcher object.

find_by_id ¶

find_by_id(box_id: str) -> Optional[Box]

Find a box by its ID.

Parameters:

Name	Type	Description	Default
`box_id`	`str`	The ID of the box to find.	required

Returns:

Type	Description
`Optional[Box]`	The Box object if found, None otherwise.

Example

p = Patcher('patch.maxpat') osc = p.add_textbox('cycle~ 440') found = p.find_by_id(osc.id) assert found is osc

find_by_type ¶

find_by_type(maxclass: str) -> List[Box]

Find all boxes of a specific Max object type.

Parameters:

Name	Type	Description	Default
`maxclass`	`str`	The Max object class name (e.g., 'newobj', 'message', 'comment').	required

Returns:

Type	Description
`List[Box]`	List of Box objects matching the type.

Example

p = Patcher('patch.maxpat') p.add_textbox('cycle~ 440') p.add_textbox('saw~ 220') p.add_message('bang') oscillators = [b for b in p.find_by_type('newobj') ... if 'cycle~' in b.text or 'saw~' in b.text] assert len(oscillators) == 2

find_by_text ¶

find_by_text(
    pattern: str, case_sensitive: bool = False
) -> List[Box]

Find all boxes whose text matches a pattern.

Parameters:

Name	Type	Description	Default
`pattern`	`str`	The text pattern to search for (substring match).	required
`case_sensitive`	`bool`	Whether the search should be case-sensitive (default: False).	`False`

Returns:

Type	Description
`List[Box]`	List of Box objects whose text contains the pattern.

Example

p = Patcher('patch.maxpat') p.add_textbox('cycle~ 440') p.add_textbox('saw~ 220') p.add_textbox('gain~ 0.5') oscillators = p.find_by_text('~') assert len(oscillators) == 3 just_cycle = p.find_by_text('cycle') assert len(just_cycle) == 1

apply_theme ¶

apply_theme(
    theme: Union[str, Dict[str, ColorLike]],
) -> Patcher

Apply a color theme to every box in this patcher (and subpatchers).

theme is a named theme ("light", "dark", "blue", "high-contrast") or a dict with "bg" / "text" / "border" color values (each a name, hex string, or float sequence). Returns self for chaining.

Example

Patcher('p.maxpat').apply_theme('dark')

from_dict `classmethod` ¶

from_dict(
    patcher_dict: Dict[str, Any],
    save_to: Optional[str] = None,
) -> Patcher

create a patcher instance from a dict

from_file `classmethod` ¶

from_file(
    path: Union[str, Path], save_to: Optional[str] = None
) -> Patcher

create a patcher instance from a .maxpat or .amxd file

find ¶

find(text: str) -> Optional[Box]

Find box object by maxclass or text pattern.

Recursively searches through all objects in the patch (including subpatchers) to find one matching the specified maxclass or text prefix.

Parameters:

Name	Type	Description	Default
`text`	`str`	The maxclass name or text pattern to search for.	required

Returns:

Type	Description
`Optional[Box]`	The first matching Box object, or None if not found.

find_box ¶

find_box(text: str) -> Optional[Box]

Find a box in this patcher (non-recursive) by maxclass or text prefix.

returns box if found else None

find_box_with_index ¶

find_box_with_index(text: str) -> Optional[Tuple[int, Box]]

Find a box and its index by maxclass or text prefix (non-recursive).

returns (index, box) if found

render ¶

render(reset: bool = False) -> None

cascade convert py2max objects to dicts.

enable_presentation ¶

enable_presentation(
    devicewidth: Optional[int] = None,
) -> Patcher

Configure this patcher to open as a Max for Live device.

Sets openinpresentation=1 so Ableton Live renders the device strip instead of the patcher view, and optionally sets devicewidth. Ableton's device strip height is fixed at ~170 px; only width is author-controlled.

enforce_integer_coords ¶

enforce_integer_coords() -> int

Round all rect coordinates in this patcher tree to integers.

Ableton renders fractional device-strip coordinates blurry on non-retina displays. Returns the number of rects that were non-integer and got rounded. Recurses into subpatchers.

to_svg ¶

to_svg(
    output_path: Union[str, Path],
    show_ports: bool = True,
    title: Optional[str] = None,
) -> None

Export this patcher to SVG format.

Parameters:

Name	Type	Description	Default
`output_path`	`Union[str, Path]`	Output file path for the SVG.	required
`show_ports`	`bool`	Whether to show inlet/outlet ports on boxes.	`True`
`title`	`Optional[str]`	Optional title to display at top of SVG.	`None`

Example

p = Patcher('my-patch.maxpat') osc = p.add_textbox('cycle~ 440') dac = p.add_textbox('ezdac~') p.add_line(osc, dac) p.to_svg('/tmp/my-patch.svg')

to_svg_string ¶

to_svg_string(
    show_ports: bool = True, title: Optional[str] = None
) -> str

Export this patcher to SVG format as a string.

Parameters:

Name	Type	Description	Default
`show_ports`	`bool`	Whether to show inlet/outlet ports on boxes.	`True`
`title`	`Optional[str]`	Optional title to display at top of SVG.	`None`

Returns:

Type	Description
`str`	SVG content as a string.

Example

p = Patcher('my-patch.maxpat') osc = p.add_textbox('cycle~ 440') svg_content = p.to_svg_string()

get_id ¶

get_id(object_name: Optional[str] = None) -> str

Generate object ID, optionally semantic based on object name.

Parameters:

Name	Type	Description	Default
`object_name`	`Optional[str]`	Optional Max object name (e.g., 'cycle~', 'gain~'). Used to generate semantic IDs like 'cycle_1' when semantic_ids mode is enabled.	`None`

Returns:

Type	Description
`str`	Object ID string (e.g., 'obj-5' or 'cycle_1').

set_layout_mgr ¶

set_layout_mgr(name: str) -> layout_module.LayoutManager

takes a name and returns an instance of a layout manager

get_pos ¶

get_pos(maxclass: Optional[str] = None) -> Rect

get box rect (position) via maxclass or layout_manager

optimize_layout ¶

optimize_layout() -> None

Optimize object positions based on layout manager type.

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:

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.

py2max.core.Box ¶

Bases: 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.

Parameters:

Name	Type	Description	Default
`maxclass`	`Optional[str]`	Max object class name (e.g., 'newobj', 'flonum').	`None`
`numinlets`	`Optional[int]`	Number of input connections.	`None`
`numoutlets`	`Optional[int]`	Number of output connections.	`None`
`id`	`Optional[str]`	Unique identifier for the object.	`None`
`patching_rect`	`Optional[Rect]`	Position and size rectangle.	`None`
`**kwds`	`Any`	Additional Max object properties.	`{}`

Attributes:

Name	Type	Description
`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.

oid `property` ¶

oid: Optional[int]

Trailing numeric part of the object id, or None if it has none.

Works for numeric ids (obj-5 -> 5) and semantic ids (cycle_1 -> 1).

subpatcher `property` ¶

subpatcher: Optional[Patcher]

synonym for parent patcher object

text `property` ¶

text: Any

Get the text content of the box.

render ¶

render() -> None

convert self and children to dictionary.

to_dict ¶

to_dict() -> Dict[str, Any]

create dict from object with extra kwds included

from_dict `classmethod` ¶

from_dict(obj_dict: Dict[str, Any]) -> Box

create instance from dict

set_color ¶

set_color(
    bg: Optional[ColorLike] = None,
    text: Optional[ColorLike] = None,
    border: Optional[ColorLike] = None,
) -> Box

Set this box's colors, returning self for chaining.

Each argument accepts a named color (e.g. "red"), a hex string ("#ff8800"), or an [r, g, b(, a)] float sequence (0..1). Sets the bgcolor / textcolor / bordercolor attributes respectively.

Example

p.add_textbox("toggle").set_color(bg="blue", text="white")

add_to_presentation ¶

add_to_presentation(
    rect: Any, *, strict: bool = False
) -> Box

Mark this box as a presentation-mode UI element (Max for Live).

Sets presentation=1 and presentation_rect on the box. Rounds fractional coordinates to integers with a warning. Raises if the box is M4L infrastructure (live.remote~, live.map, etc.) that must stay hidden from the device strip.

Parameters:

Name	Type	Description	Default
`rect`	`Any`	[x, y, width, height] in device-strip coordinates.	required
`strict`	`bool`	if True, warn when this isn't a known UI class.	`False`

help_text ¶

help_text() -> str

Get formatted help documentation for this Max object.

Returns:

Type	Description
`str`	Formatted help string with object documentation from .maxref.xml files.

help ¶

help() -> None

Print formatted help documentation for this Max object.

get_info ¶

get_info() -> Optional[Dict[str, Any]]

Get complete object information from .maxref.xml files.

Returns:

Type	Description
`Optional[Dict[str, Any]]`	Dictionary with complete object information or None if not found.

get_inlet_count ¶

get_inlet_count() -> Optional[int]

Get the number of inlets for this object from maxref data.

Returns:

Type	Description
`Optional[int]`	Number of inlets or None if unknown.

get_outlet_count ¶

get_outlet_count() -> Optional[int]

Get the number of outlets for this object from maxref data.

Returns:

Type	Description
`Optional[int]`	Number of outlets or None if unknown.

get_inlet_types ¶

get_inlet_types() -> List[str]

Get the inlet types for this object from maxref data

Returns:

Type	Description
`List[str]`	List of inlet type strings

get_outlet_types ¶

get_outlet_types() -> List[str]

Get the outlet types for this object from maxref data

Returns:

Type	Description
`List[str]`	List of outlet type strings

py2max.core.Patchline ¶

Bases: AbstractPatchline

Represents a connection between two Max objects.

A Patchline connects an outlet of one object to an inlet of another, enabling signal or message flow between objects in a patch.

Parameters:

Name	Type	Description	Default
`source`	`Optional[List[Any]]`	Source connection as [object_id, outlet_index].	`None`
`destination`	`Optional[List[Any]]`	Destination connection as [object_id, inlet_index].	`None`
`**kwds`	`Any`	Additional patchline properties.	`{}`

Attributes:

Name	Type	Description
`source`		Source object ID and outlet index.
`destination`		Destination object ID and inlet index.

src `property` ¶

src: str

first object from source list

dst `property` ¶

dst: str

first object from destination list

to_tuple ¶

to_tuple() -> Tuple[str, str, str, str, Union[str, int]]

Return a tuple describing the patchline.

to_dict ¶

to_dict() -> Dict[str, Any]

create dict from object with extra kwds included

from_dict `classmethod` ¶

from_dict(obj_dict: Dict[str, Any]) -> Patchline

convert toPatchline object from dict

Core: Patcher, Box, Patchline¶

py2max.core.Patcher ¶

With semantic IDs¶

width property ¶

height property ¶

to_dict ¶

to_json ¶

save_as ¶

save ¶

add_box ¶

add_associated_comment ¶

add_patchline_by_index ¶

add_patchline ¶

add_line ¶

add_textbox ¶

add ¶

add_codebox ¶

add_codebox_tilde ¶

add_message ¶

add_comment ¶

add_intbox ¶

add_floatbox ¶

add_floatparam ¶

add_intparam ¶

add_pattrstorage ¶

add_autopattr ¶

add_preset_system ¶

enable_parameter ¶

add_attr ¶

add_subpatcher ¶

encapsulate ¶

add_gen ¶

add_gen_tilde ¶

add_rnbo ¶

add_mc ¶

add_poly ¶

add_coll ¶

add_dict ¶

add_table ¶

add_table_tilde ¶

add_itable ¶

add_umenu ¶

add_bpatcher ¶

add_beap ¶

find_by_id ¶

find_by_type ¶

find_by_text ¶

apply_theme ¶

from_dict classmethod ¶

from_file classmethod ¶

find ¶

find_box ¶

find_box_with_index ¶

render ¶

enable_presentation ¶

enforce_integer_coords ¶

to_svg ¶

to_svg_string ¶

get_id ¶

set_layout_mgr ¶

get_pos ¶

optimize_layout ¶

py2max.core.Box ¶

oid property ¶

subpatcher property ¶

text property ¶

render ¶

to_dict ¶

from_dict classmethod ¶

set_color ¶

add_to_presentation ¶

help_text ¶

help ¶

get_info ¶

get_inlet_count ¶

get_outlet_count ¶

get_inlet_types ¶

get_outlet_types ¶

py2max.core.Patchline ¶

src property ¶

width `property` ¶

height `property` ¶

from_dict `classmethod` ¶

from_file `classmethod` ¶

oid `property` ¶

subpatcher `property` ¶

text `property` ¶

from_dict `classmethod` ¶

src `property` ¶

dst `property` ¶

from_dict `classmethod` ¶