Context Managers

Context managers for restoring state after running requested tools.

These are generally quite useful for creating tools which must modify state that is normally under control of the user. By using these, the state will be set back to what the user left it at.

For example, several of Maya’s tools work easiest when they are operating on the current selection, but that selection is not something that we want to expose to the user of our higher level tool.

Attributes

mayatools.context.attrs(*args, **kwds)

Change some attributes, and reset them when leaving the context.

Parameters:

• args – Mappings of attributes to values.
• kwargs – More attributes and values.

Returns:

A dictionary of the original values will be bound to the target of the with statement. Changed to that dictionary will be applied.

This is very for tools that must modify global state:

>>> with mayatools.context.attrs({'defaultRenderGlobals.imageFormat': 8}):
...     # Playblast with confidence that the render globals will be reset.

Selections

mayatools.context.selection(*args, **kwds)

A context manager that resets selections after exiting.

Parameters:

• args – Passed to cmds.select.
• kwargs – Passed to cmds.select.

A list of the original selection will be bound to the target of the with statement. Changes to that list will be applied.

Example:

>>> with selection(clear=True):
...     # Do something with an empty selection, but restore the user's
...     # selection when we are done.

Commands

mayatools.context.command(func, *args, **kwargs)

A context manager that uses the standard query interface.

Pass any values via keyword arguments and their original values will be saved via func(*args, query=True, yourAttribute=True), and finally restored via func(*args, yourAttribute=original) or func(*args, edit=True, yourAttribute=original) if you also specify edit=True.

Parameters:

• func – A callable, or name of a Maya command.
• args – Positional arguments for the given func.
• kwargs – Values to set within the context. edit is special and marks if values should be set with an edit flag or not.

A dictionary of the original values will be bound to the target of the with statement. Changed to that dictionary will be applied.

If you are already using a query pattern like:

>>> current_time_unit = cmds.currentUnit(time)
>>> cmds.currentUnit(time='film')
>>> 
>>> try:
...     # Do something.
... finally:
...     cmds.currentUnit(time=current_time_unit)

then you can use this manager directly:

>>> with command(cmds.currentUnit, time='film') as originals:
...     # Do something.

or as a context manager factory:

>>> currentUnit = command(cmds.currentUnit)
>>> with currentUnit(time='film') as originals:
...     # Do something.

If your command requires the edit keyword, pass it to this function:

>>> with ctx.command(cmds.camera, my_camera, edit=True, overscan=1):
...     # Do something with the camera.

User Interface

UI Refreshes

mayatools.context.suspend_refresh()

A context mananger that stops the graph from running or the view updating.

Can be nested, where only the outermost context manager will resume refresing.

>>> with suspend_refresh():
...     do_something_with_high_drawing_cost()

See also

There are caveats with disabling the refresh cycle. Be sure to read about cmds.refresh.

Action Progress

class mayatools.context.progress(status, max=100, min=0, cancellable=False)

A context manager to assist with the global progress bar.

Parameters:

• status (str) – The status message.
• max (int) – The maximum value.
• min (int) – The minimum value.
• cancellable (bool) – If the process is cancellable.

If the process is cancellable, you must periodically check was_cancelled() to see if the user did cancel the action. You must be more defensive in your programming than normal since this must allow the main event loop to process user events.

with progress("Testing", max=100, cancellable=True) as p:
    for i in range(100):
        if p.was_cancelled():
            cmds.warn('You cancelled the process!')
            break
        time.sleep(0.02)
        p.update(i, 'Testing %d of 100' % (i + 1))

hide()

Hide the progress bar.

show()

Show the progress bar.

step(size=1)

Increment the value.

update(value=None, status=None, min=None, max=None)

Update the value and status.

was_cancelled(max_time=0.01)

Check if the user requested the action be cancelled.

Parameters:max_time (float) – The maximum number of seconds to spend in the main event loop checking for user actions. Returns bool:True if the user requested the action be cancelled.