maxref

Dynamic Max object information parsed from .maxref.xml files (or the bundled fallback). Provides object help, inlet/outlet counts and types, connection validation, and the MaxRefCache / MaxRefDB access layers.

from py2max.maxref import get_object_help, get_available_objects

objects = get_available_objects()        # 1175+ objects
print(get_object_help('umenu'))

Max object reference system for py2max.

This subpackage provides access to Max object documentation and metadata:

• MaxRefCache: Cache for parsed .maxref.xml files
• MaxRefDB: SQLite database for Max object reference data
• MAXCLASS_DEFAULTS: Dictionary of default object properties
• Various helper functions for object introspection

Example

from py2max.maxref import get_object_info, MAXCLASS_DEFAULTS info = get_object_info('cycle~') defaults = MAXCLASS_DEFAULTS.get('cycle~')

MaxClassDefaults

Object-defaults lookup with two layers.

1. Curated overrides (legacy.MAXCLASS_DEFAULTS) -- authoritative, hand-tuned defaults for common/UI objects, including the correct patching_rect geometry the XML cannot provide.
2. Dynamic maxref discovery (get_legacy_defaults over .maxref.xml) -- the fallback for the long tail of objects not in layer 1.

Curated overrides win on purpose: maxref-derived defaults use a generic 60x22 box and cannot infer UI sizes, so an object present in both layers must use its curated entry.

get

get(key: str, default: Any = None) -> Any

Get defaults with fallback

keys

keys() -> Set[str]

Get all available keys

MaxRefCache

Cache for parsed MaxRef data

refdict property

refdict: Dict[str, Path]

Get dictionary of available .maxref.xml files

category_map property

category_map: Dict[str, str]

Get dictionary mapping object names to categories (jit, max, msp, m4l)

get_object_data

get_object_data(name: str) -> Optional[Dict[str, Any]]

Get parsed data for Max object by name with improved error handling

get_all_jit_objects

get_all_jit_objects() -> List[str]

Get list of all Jitter objects (jit-ref category)

get_all_m4l_objects

get_all_m4l_objects() -> List[str]

Get list of all Max for Live objects (m4l-ref category)

get_all_max_objects

get_all_max_objects() -> List[str]

Get list of all Max objects (max-ref category)

get_all_msp_objects

get_all_msp_objects() -> List[str]

Get list of all MSP objects (msp-ref category)

get_available_objects

get_available_objects() -> List[str]

Get list of all available Max objects with .maxref.xml files

get_inlet_count

get_inlet_count(maxclass: str) -> Optional[int]

Get the number of inlets for a Max object.

Parameters:

Name	Type	Description	Default
maxclass	str	The Max object class name	required

Returns:

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

get_inlet_types

get_inlet_types(maxclass: str) -> List[str]

Get the inlet types for a Max object.

Parameters:

Name	Type	Description	Default
maxclass	str	The Max object class name	required

Returns:

Type	Description
List[str]	List of inlet type strings

get_legacy_defaults

get_legacy_defaults(name: str) -> Dict[str, Any]

Get legacy-compatible defaults for a Max object

This function extracts basic information needed for backwards compatibility with the old MAXCLASS_DEFAULTS structure.

get_object_help

get_object_help(name: str) -> str

Get formatted help text for a Max object

Parameters:

Name	Type	Description	Default
name	str	Max object name	required

Returns:

Type	Description
str	Formatted help text string

get_object_info

get_object_info(name: str) -> Optional[Dict[str, Any]]

Get information about a Max object from its .maxref.xml file

Parameters:

Name	Type	Description	Default
name	str	Max object name (e.g., 'umenu', 'cycle~', 'gain~')	required

Returns:

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

get_objects_by_category

get_objects_by_category(category: str) -> List[str]

Get list of objects in a specific category (jit, max, msp, m4l)

Parameters:

Name	Type	Description	Default
category	str	Category name ('jit', 'max', 'msp', or 'm4l')	required

Returns:

Type	Description
List[str]	Sorted list of object names in that category

get_outlet_count

get_outlet_count(maxclass: str) -> Optional[int]

Get the number of outlets for a Max object.

Parameters:

Name	Type	Description	Default
maxclass	str	The Max object class name	required

Returns:

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

get_outlet_types

get_outlet_types(maxclass: str) -> List[str]

Get the outlet types for a Max object.

Parameters:

Name	Type	Description	Default
maxclass	str	The Max object class name	required

Returns:

Type	Description
List[str]	List of outlet type strings

replace_tags

replace_tags(text: str, sub: str, *tags: str) -> str

Replace XML tags with substitution string

validate_connection

validate_connection(
    src_maxclass: str,
    src_outlet: int,
    dst_maxclass: str,
    dst_inlet: int,
    src_text: Optional[str] = None,
    dst_text: Optional[str] = None,
) -> tuple[bool, str]

Validate a connection between two Max objects using the port-type model.

Checks (a) that the outlet/inlet indices are in range (arg-aware, so limi~ 2 is understood to have two ports) and (b) that the outlet's message kind is compatible with the inlet -- catching a control outlet wired into a signal-only inlet (e.g. metro -> cycle~), which Max rejects.

The message-type check is deliberately conservative: only clearly-wrong connections fail; anything ambiguous (or involving a maxref-unknown object) is allowed, so validation never rejects a valid patch.

Parameters:

Name	Type	Description	Default
src_maxclass	str	Source object's maxclass.	required
src_outlet	int	Source outlet index (0-based).	required
dst_maxclass	str	Destination object's maxclass.	required
dst_inlet	int	Destination inlet index (0-based).	required
src_text	Optional[str]	Source box text (enables arg-aware outlet counts).	None
dst_text	Optional[str]	Destination box text (enables arg-aware inlet counts).	None

Returns:

Type	Description
bool	Tuple of (is_valid: bool, error_message: str). is_valid is False
str	only for a definite error.