rofunc.utils.robolab.formatter.mjcf_parser.debugging

Implements PyMJCF debug mode.

PyMJCF debug mode stores a stack trace each time the MJCF object is modified. If Mujoco raises a compile error on the generated XML model, we would then be able to find the original source line that created the offending element.

1.  Module Contents

1.1.  Classes

DebugContext

A helper object to store debug information for a generated XML string.

1.2.  Functions

debug_mode	Returns a boolean that indicates whether PyMJCF debug mode is enabled.
enable_debug_mode	Enables PyMJCF debug mode.
disable_debug_mode	Disables PyMJCF debug mode.
get_full_dump_dir	Gets the directory to dump full debug info files.
set_full_dump_dir	Sets the directory to dump full debug info files.
get_current_stack_trace	Returns the stack trace of the current execution frame.
freeze_current_stack_trace	A context manager that freezes the stack trace.

1.3.  Data

FLAGS
StackTraceEntry
ElementDebugInfo
MODULE_PATH
DEBUG_METADATA_PREFIX

1.4.  API

rofunc.utils.robolab.formatter.mjcf_parser.debugging.FLAGS = None

rofunc.utils.robolab.formatter.mjcf_parser.debugging.StackTraceEntry = None

rofunc.utils.robolab.formatter.mjcf_parser.debugging.ElementDebugInfo = None

rofunc.utils.robolab.formatter.mjcf_parser.debugging.MODULE_PATH = None

rofunc.utils.robolab.formatter.mjcf_parser.debugging.DEBUG_METADATA_PREFIX = 'pymjcfdebug'

rofunc.utils.robolab.formatter.mjcf_parser.debugging.debug_mode()

Returns a boolean that indicates whether PyMJCF debug mode is enabled.

rofunc.utils.robolab.formatter.mjcf_parser.debugging.enable_debug_mode()

Enables PyMJCF debug mode.

rofunc.utils.robolab.formatter.mjcf_parser.debugging.disable_debug_mode()

Disables PyMJCF debug mode.

rofunc.utils.robolab.formatter.mjcf_parser.debugging.get_full_dump_dir()

Gets the directory to dump full debug info files.

rofunc.utils.robolab.formatter.mjcf_parser.debugging.set_full_dump_dir(dump_path)

Sets the directory to dump full debug info files.

rofunc.utils.robolab.formatter.mjcf_parser.debugging.get_current_stack_trace()

Returns the stack trace of the current execution frame.

Returns:

A list of StackTraceEntry named tuples corresponding to the current stack trace of the process, truncated to immediately before entry into PyMJCF internal code.

rofunc.utils.robolab.formatter.mjcf_parser.debugging.freeze_current_stack_trace()

A context manager that freezes the stack trace.

AVOID USING THIS CONTEXT MANAGER OUTSIDE OF INTERNAL PYMJCF IMPLEMENTATION, AS IT REDUCES THE USEFULNESS OF DEBUG MODE.

If PyMJCF debug mode is enabled, calls to debugging.get_current_stack_trace within this context will always return the stack trace from when this context was entered.

The frozen stack is global to this debugging module. That is, if the context is entered while another one is still active, then the stack trace of the outermost one is returned.

This context significantly speeds up bulk operations in debug mode, e.g. parsing an existing XML string or creating a deeply-nested element, as it prevents the same stack trace from being repeatedly constructed.

Yields:

None

class rofunc.utils.robolab.formatter.mjcf_parser.debugging.DebugContext

A helper object to store debug information for a generated XML string.

This class is intended for internal use within the PyMJCF implementation.

Initialization

register_element_for_debugging(elem)

Registers an Element and returns debugging metadata for the XML.

Args:

elem: An mjcf.Element.

Returns:

An lxml.etree.Comment that represents debugging metadata in the generated XML.

commit_xml_string(xml_string)

Commits the XML string associated with this debug context.

This function also formats the XML string to make sure that the debugging metadata appears on the same line as the corresponding XML element.

Args:

xml_string: A pretty-printed XML string.

Returns:

A reformatted XML string where all debugging metadata appears on the same line as the corresponding XML element.

process_and_raise_last_exception()

Processes and re-raises the last ValueError caught.

This function will insert the relevant line from the source XML to the error message. If debug mode is enabled, additional debugging information is appended to the error message. If debug mode is not enabled, the error message instructs the user to enable it by rerunning the executable with an appropriate flag.

property default_dump_dir

property debug_mode

dump_full_debug_info_to_disk(dump_dir=None)

Dumps full debug information to disk.

Full debug information consists of an XML file whose elements are tagged with a unique ID, and a stack trace file for each element ID. Each stack trace file consists of a stack trace for when the element was created, and when each attribute was last modified.

Args:

dump_dir: Full path to the directory in which dump files are created.

Raises:

ValueError: If neither dump_dir nor the global dump path is given. The

global dump path can be specified either via the –pymjcf_debug_full_dump_dir flag or via debugging.set_full_dump_dir.