Exceptions

Core exceptions for the LinkForge library.

Custom exceptions for the LinkForge ecosystem.

Defines the exception hierarchy used across models, parsers, and generators to provide granular error handling and categorized validation failures.

Core Components:

• ValidationErrorCode: Enum of standardized error categories.

• LinkForgeError: Base exception for the entire ecosystem.

• RobotModelError: Failures related to the IR and physical consistency.

• RobotParserError: Failures during format import and resolution.

• RobotGeneratorError: Failures during format export.

class linkforge.core.exceptions.ValidationErrorCode(*values)

Bases: StrEnum

Categorized error codes for robot validation failures.

INVALID_NAME = 'invalid_name'

DUPLICATE_NAME = 'duplicate_name'

NAME_EMPTY = 'name_empty'

NOT_FOUND = 'not_found'

HAS_CYCLE = 'has_cycle'

NO_ROOT = 'no_root'

MULTIPLE_ROOTS = 'multiple_roots'

OUT_OF_RANGE = 'out_of_range'

VALUE_EMPTY = 'value_empty'

INVALID_VALUE = 'invalid_value'

PHYSICS_VIOLATION = 'physics_violation'

INERTIA_TRIANGLE_INEQUALITY = 'inertia_triangle_inequality'

MESH_UNWELDED = 'mesh_unwelded'

MESH_DUPLICATE_FACE = 'mesh_duplicate_face'

MESH_DEGENERATE = 'mesh_degenerate'

MESH_BOUNDARY_EDGE = 'mesh_boundary_edge'

MESH_NON_MANIFOLD = 'mesh_non_manifold'

MESH_INCONSISTENT_WINDING = 'mesh_inconsistent_winding'

MESH_SLIVER = 'mesh_sliver'

GENERIC_FAILURE = 'generic_failure'

exception linkforge.core.exceptions.LinkForgeError

Bases: Exception

Base category for all LinkForge-related exceptions.

exception linkforge.core.exceptions.RobotModelError

Bases: LinkForgeError

Exception raised for structural or logic errors in the Robot model.

exception linkforge.core.exceptions.RobotGeneratorError

Bases: LinkForgeError

Exception raised during robot generation or export.

exception linkforge.core.exceptions.RobotParserError

Bases: LinkForgeError

Exception raised during robot parsing or import.

exception linkforge.core.exceptions.RobotParserIOError(filepath='unknown', reason='error')

Bases: RobotParserError

Exception raised for file-level or I/O errors during parsing.

Parameters:

• filepath (Path | str)

• reason (str)

__init__(filepath='unknown', reason='error')

Parameters:

• filepath (Path | str)

• reason (str)

exception linkforge.core.exceptions.RobotParserXMLRootError(actual_tag='unknown', expected_tag='robot')

Bases: RobotParserError

Exception raised when the XML root element is invalid.

Parameters:

• actual_tag (str)

• expected_tag (str)

__init__(actual_tag='unknown', expected_tag='robot')

Parameters:

• actual_tag (str)

• expected_tag (str)

exception linkforge.core.exceptions.RobotParserUnexpectedError(source_area='unknown', original_error=None)

Bases: RobotParserError

General wrapper for unexpected parsing failures.

Parameters:

• source_area (str)

• original_error (Any)

__init__(source_area='unknown', original_error=None)

Parameters:

• source_area (str)

• original_error (Any)

exception linkforge.core.exceptions.RobotPhysicsError(code, message, target=None, value=None)

Bases: RobotModelError

Exception raised for unphysical properties (e.g. negative mass or volume).

Parameters:

• code (ValidationErrorCode)

• message (str)

• target (str | None)

• value (Any)

__init__(code, message, target=None, value=None)

Parameters:

• code (ValidationErrorCode)

• message (str)

• target (str | None)

• value (Any)

exception linkforge.core.exceptions.RobotValidationError(code, message, target=None, value=None)

Bases: RobotModelError

Exception raised for structural or logic validation failures.

Now structured using ValidationErrorCode for robust error handling.

Parameters:

• code (ValidationErrorCode)

• message (str)

• target (str | None)

• value (Any)

__init__(code, message, target=None, value=None)

Parameters:

• code (ValidationErrorCode)

• message (str)

• target (str | None)

• value (Any)

exception linkforge.core.exceptions.RobotSecurityError(path='unknown', reason='violation')

Bases: RobotModelError

Exception raised for security-related errors (e.g. sandbox escapes).

Parameters:

• path (str)

• reason (str)

__init__(path='unknown', reason='violation')

Parameters:

• path (str)

• reason (str)

exception linkforge.core.exceptions.RobotMathError(code, message, target=None, value=None)

Bases: RobotModelError

Exception raised for invalid numerical values (NaN, Inf, or Out of Range).

Parameters:

• code (ValidationErrorCode)

• message (str)

• target (str | None)

• value (Any)

__init__(code, message, target=None, value=None)

Parameters:

• code (ValidationErrorCode)

• message (str)

• target (str | None)

• value (Any)

exception linkforge.core.exceptions.RobotXacroError(message='failure', context=None)

Bases: RobotParserError

General exception for XACRO resolution failures.

Parameters:

• message (str)

• context (str | None)

__init__(message='failure', context=None)

Parameters:

• message (str)

• context (str | None)

exception linkforge.core.exceptions.RobotXacroRecursionError(depth='unknown', reason=None)

Bases: RobotXacroError

Exception raised for circular dependencies or max depth in XACRO.

Parameters:

• depth (int | str)

• reason (str | None)

__init__(depth='unknown', reason=None)

Parameters:

• depth (int | str)

• reason (str | None)

exception linkforge.core.exceptions.RobotXacroExpressionError(expression='unknown', reason='error')

Bases: RobotXacroError

Exception raised for failures in XACRO math or property evaluation.

Parameters:

• expression (str)

• reason (str)

__init__(expression='unknown', reason='error')

Parameters:

• expression (str)

• reason (str)

exception linkforge.core.exceptions.XacroDetectedError(message='XACRO detected')

Bases: RobotParserError

Raised when XACRO content is detected in a URDF parser.

Parameters:

message (str)

__init__(message='XACRO detected')

Parameters:

message (str)