Using Python in Mari

Introduction

Mari uses Python 2.7.13 and Unicode Character Set (UCS) 4.

Most of Mari’s functions are implemented through the use of manager objects, such as mari.projects, mari.menus, and so on.

Review Mari’s Python Documentation

1.

To view HTML documentation on Mari’s Python API, select Python > Documentation in Mari.

2.

To view example Python scripts, go to the Media/Scripts/examples sub-directory of the Mari application directory and open any of the .py files there in a text editor. You can also see the results of these example scripts in the Python menu in Mari.

Note:  Executing the Python "help" command in the Python Console also launches the HTML documentation in a web browser.

Tip:  To read more about Python, review its documentation, or interact with other Python users, you can also visit the Python programming language official website at http://www.python.org/.

Using the Python Console Palette

Mari's Python Console palette behaves in a very similar way to a standard Python console. Here’s how you use it:

1.

If the Python Console is already open, click the Console tab to give it focus; or if it's closed, right-click in the toolbar area on top of the Mari workspace and select Python Console to open it. You can also find it in the menu under View > Palettes.

The Python Console is divided into two parts. You use the lower part (input pane) to type in and execute your Python statements, and when you have done so, statements and their outputs appear in the upper part of the console (output pane).

2.

To enter a statement, type it into the input pane. As you type, Mari provides auto-complete suggestions, if any are available.

To use the usual editing functions, such as copy and paste, right-click on the input pane and select the desired function.

Tip:  To temporarily turn off Mari's auto-complete function while writing in the Python Console palette, press Esc when the auto-complete word appears. This only causes it to disappear until you continue typing, however, and auto-complete appears again if it detects a similar word when you resume.

3.

Mari utilizes a syntax highlighting scheme in the input pane, so that code can be more easily identified at a glance. Text in red represents strings, dark blue represents comments, and various Python keywords are represented by yellow, magenta, and blue.

4.

To execute the statement, click the Evaluate button or press Ctrl/Cmd+Return.

Your statement appears in the output pane, preceded by >>> (or ... if your statement spans multiple lines).

If you enter an invalid statement, Mari produces an error in the output pane.

5.

If you want to repeat a statement, you can step backwards or forwards through the history of your script by pressing Ctrl/Cmd+Up or Ctrl/Cmd+Down.

6.

If you want to clear the input and output panes, click the Clear button.

Note:  Sometimes you may get an error if you copy and paste statements into the Python Console from another source, like an e-mail. This may be caused by the mark-up or encoding of the source you copied the statement from. To fix the problem, re-enter the statement manually.

Tip:  You can increase or decrease the font size in the Python Console by holding down Ctrl/Cmd and pressing + or -.

7.

If you want to quickly open the Mari Python API Help without going to the Python > Documentation menu, click on Help in the Python Console palette.

A window with the Mari Python API Help appears. You can move this window around and keep typing in the input pane while it's open. This window cannot be docked like a palette, but you can change focus from the window, while it's still active, unlike most of Mari's dialogs.

Note:  If you are typing in the input pane while the Mari Python API Help window is open, and Mari detects an auto-complete suggestion, the suggestion appears in the Mari Python API Help automatically.

Saving or Importing a Script

If you would like your script to be automatically executed at start-up, do the following:

1.

Enter your script in any text editor.

2.

Save the text file with the extension .py (for example, my_module.py) to:

• the ~/Mari/Scripts sub-directory of the Mari application directory, or

• your own directory by setting the environment variable MARI_SCRIPT_PATH to a custom folder.

If a script called init.py exists, it is run first. If you need scripts to run in a specified order, you should put them in a separate folder and use a Python import statement in init.py.

You can also specify multiple directories to run scripts on start-up, using a path list separated by ':' or ';' as per the standard for your operating system.

• On Linux: /home/username/dir1:/home/username/dir2

• On Windows: C:\Users\username\dir1;C:\Users\username\dir2

• On Mac: /home/users/username/dir1;/home/users/username/dir2

3.

The import directory, contained in the following folders of your custom scripts path:

• On Linux: /Mari/Scripts

• On Windows: Documents\Mari\Scripts.

• On Mac: /Documents/Mari/Scripts

Scripts saved to this directory are imported rather than run, which prevents unnecessary pollution of the global namespace. If you save your custom script to the import directory, it is automatically imported before the scripts in the main folder are run.

Tip:  Python files and sub-folders that you wish to import without running in the import directory must be __init__.py files.

Loading a Script

To load a script through the Script Path entry box:

1.

Manually enter the script’s location, or

2.

Click on to launch the Python Script Path dialog box and browse to the location of the script.

3.

To execute the statement, click the Evaluate button.

Custom scripts load from the import directory prior to the scripts being run from the main folder. Mari uses particular order to load modules to ensure the proper, full functionality of the program when using Python scripts.

If existing start-up scripts do not work correctly due to the load module order, you can revert back to the old behavior by setting the environment variable MARI_OLD_PYTHON_INIT to any non-empty string other than 0.

Note:  Mari looks for metadata that is over 250MB in size and discards anything over this size. This check is performed on project load, and is intended to strip corrupt and problematic data. This affects metadata added using the Python API.

Terminal Mode

Mari provides a terminal mode, which allows users to access features through a Python shell on the command line. This is similar to the Python console palette in the Mari GUI, or to a standard Python shell. Terminal mode can be used to perform administrative actions such as archiving projects, exporting textures, and other tasks that do not require graphical interaction from the user.

Note:  Terminal mode is not a true "headless mode" because it still requires graphics functionality to run. Mari still initializes its GUI when starting up terminal mode - it just won’t display it.

You can supply the file name of a Python script to run on the command line, if desired. If supplied, Mari runs the specified script before providing the Python shell input prompt. It is also possible to start in "execute mode", which is the same as terminal mode but exists after running the provided script.

To start the terminal mode from a shell, use the following commands:

On Linux

cd /path/to/mari

# Normal terminal mode

./mari -t

# Terminal mode - run the script, then show a Python input prompt

./mari -t /path/to/script_name.py

# Execute mode - run the script, then exit

./mari -x /path/to/script_name.py

On Windows

cd \path\to\mari

# Normal terminal mode

Mari(Undefined variable: Custom.Version Number (Long)).exe -t

# Terminal mode - run the script, then show a Python input prompt

Mari(Undefined variable: Custom.Version Number (Long)).exe -t \path\to\script_name.py

# Execute mode - run the script, then exit

Mari(Undefined variable: Custom.Version Number (Long)).exe -x \path\to\script_name.py

On Mac

cd /path/to/Mari

# Normal terminal mode

./Mari(Undefined variable: Custom.Version Number (Long)) -t

# Terminal mode - run the script, then show a Python input prompt

./Mari(Undefined variable: Custom.Version Number (Long)) -t /path/to/script_name.py

# Execute mode - run the script, then exit

./Mari(Undefined variable: Custom.Version Number (Long)) -x /path/to/script_name.py

 

Using a Render License (Optional)

When running Mari in Execute or Terminal mode, Mari searches for a render license by default. A render license allows you to use Mari in headless mode without the full UI experience. If a render license is not available then Mari looks for an interactive license. To force Mari to use a render license, use either of the following arguments:

-r

--render

Using PySide in Mari

Mari ships PySide together with its Python scripting engine. PySide is a library of Python bindings for Qt, similar to PyQt. For more information on PySide, visit http://qt-project.org/wiki/PySide.