(For more resources related to this topic, see here.)

Maya and Python are both excellent and elegant tools that can together achieve amazing results. And while it may be tempting to dive in and start wielding this power, it is prudent to understand some basic things first.

In this article, we will look at Python as a language, Maya as a program, and PyMEL as a framework. We will begin by briefly going over how to use the standard Python interpreter, the Maya Python interpreter, the Script Editor in Maya, and your Integrated Development Environment (IDE) or text editor in which you will do the majority of your development. Our goal for the article is to build a small library that can easily link us to documentation about Python and PyMEL objects. Building this library will illuminate how Maya, Python and PyMEL are designed, and demonstrate why PyMEL is superior to maya.cmds. We will use the powerful technique of type introspection to teach us more about Maya’s node-based design than any Hypergraph or static documentation can.

Creating your library

There are generally three different modes you will be developing in while programming Python in Maya: using the mayapy interpreter to evaluate short bits of code and explore ideas, using your Integrated Development Environment to work on the bulk of the code, and using Maya’s Script Editor to help iterate and test your work. In this section, we’ll start learning how to use all three tools to create a very simple library.

Using the interpreter

The first thing we must do is find your mayapy interpreter. It should be next to your Maya executable, named mayapy or mayapy.exe. It is a Python interpreter that can run Python code as if it were being run in a normal Maya session. When you launch it, it will start up the interpreter in interactive mode, which means you enter commands and it gives you results, interactively. The >>> and … characters in code blocks indicate something you should enter at the interactive prompt; the code listing in the article and your prompt should look basically the same. In later listings, long output lines will be elided with … to save on space.

Start a mayapy process by double clicking or calling it from the command line, and enter the following code:

 >>> print 'Hello, Maya!'
Hello, Maya!
>>> def hello():
...     return 'Hello, Maya!'
...
>>> hello()
'Hello, Maya!'  

The first statement prints a string, which shows up under the prompting line. The second statement is a multiline function definition. The … indicates the line is part of the preceding line. The blank line following the … indicates the end of the function. For brevity, we will leave out empty … lines in other code listings. After we define our hello function, we invoke it. It returns the string “Hello, Maya!“, which is printed out beneath the invocation.

Finding a place for our library

Now, we need to find a place to put our library file. In order for Python to load the file as a module, it needs to be on some path where Python can find it. We can see all available paths by looking at the path list on the sys module.

>>> import sys
>>> for p in sys.path:
...     print p
C:Program FilesAutodeskMaya2013binpython26.zip
C:Program FilesAutodeskMaya2013PythonDLLs
C:Program FilesAutodeskMaya2013Pythonlib
C:Program FilesAutodeskMaya2013Pythonlibplat-win
C:Program FilesAutodeskMaya2013Pythonliblib-tk
C:Program FilesAutodeskMaya2013bin
C:Program FilesAutodeskMaya2013Python
C:Program FilesAutodeskMaya2013Pythonlibsite-packages   

A number of paths will print out; I’ve replicated what’s on my Windows system, but yours will almost definitely be different. Unfortunately, the default paths don’t give us a place to put custom code. They are application installation directories, which we should not modify. Instead, we should be doing our coding outside of all the application installation directories. In fact, it’s a good practice to avoid editing anything in the application installation directories entirely.

Choosing a development root

Let’s decide where we will do our coding. To be concise, I’ll choose C:mayapybookpylib to house all of our Python code, but it can be anywhere. You’ll need to choose something appropriate if you are on OSX or Linux; we will use ~/mayapybook/pylib as our path on these systems, but I’ll refer only to the Windows path except where more clarity is needed. Create the development root folder, and inside of it create an empty file named minspect.py.

Now, we need to get C:mayapybookpylib onto Python’s sys.path so it can be imported. The easiest way to do this is to use the PYTHONPATH environment variable. From a Windows command line you can run the following to add the path, and ensure it worked:

> set PYTHONPATH=%PYTHONPATH%;C:mayapybookpylib
> mayapy.exe
>>> import sys
>>> 'C:\mayapybook\pylib' in sys.path
True
>>> import minspect
>>> minspect
<module 'minspect' from '...minspect.py'>     

The following is the equivalent commands on OSX or Linux:

$ export PYTHONPATH=$PYTHONPATH:~/mayapybook/pylib
$ mayapy
>>> import sys
>>> '~/mayapybook/pylib' in sys.path
True
>>> import minspect
>>> minspect
<module 'minspect' from '.../minspect.py'> 

There are actually a number of ways to get your development root onto Maya’s path. The option presented here (using environment variables before starting Maya or mayapy) is just one of the more straightforward choices, and it works for mayapy as well as normal Maya. Calling sys.path.append(‘C:\mayapybook\pylib’) inside your userSetup.py file, for example, would work for Maya but not mayapy (you would need to use maya.standalone.initialize to register user paths, as we will do later).

Using set or export to set environment variables only works for the current process and any new children. If you want it to work for unrelated processes, you may need to modify your global or user environment. Each OS is different, so you should refer to your operating system’s documentation or a Google search. Some possibilities are setx from the Windows command line, editing /etc/environment in Linux, or editing /etc/launchd.conf on OS X. If you are in a studio environment and don’t want to make changes to people’s machines, you should consider an alternative such as using a script to launch Maya which will set up the PYTHONPATH, instead of launching the maya executable directly.

Creating a function in your IDE

Now it is time to use our IDE to do some programming. We’ll start by turning the path printing code we wrote at the interactive prompt into a function in our file. Open C:mayapybookpylibminspect.py in your IDE and type the following code:

import sys
def syspath():
    print 'sys.path:'
    for p in sys.path:
        print '  ' + p   

Save the file, and bring up your mayapy interpreter. If you’ve closed down the one from the last session, make sure C:mayapybookpylib (or whatever you are using as your development root) is present on your sys.path or the following code will not work! See the preceding section for making sure your development root is on your sys.path.

>>> import minspect
>>> reload(minspect)
<module 'minspect' from '...minspect.py'>
>>> minspect.syspath()
C:Program FilesAutodeskMaya2013binpython26.zip
C:Program FilesAutodeskMaya2013PythonDLLs
C:Program FilesAutodeskMaya2013Pythonlib
C:Program FilesAutodeskMaya2013Pythonlibplat-win
C:Program FilesAutodeskMaya2013Pythonliblib-tk
C:Program FilesAutodeskMaya2013bin
C:Program FilesAutodeskMaya2013Python
C:Program FilesAutodeskMaya2013Pythonlibsite-packages   

First, we import the minspect module. It may already be imported if this was an old mayapy session. That is fine, as importing an already-imported module is fast in Python and causes no side effects. We then use the reload function, which we will explore in the next section, to make sure the most up-to-date code is loaded. Finally, we call the syspath function, and its output is printed. Your actual paths will likely vary.

Reloading code changes

It is very common as you develop that you’ll make changes to some code and want to immediately try out the changed code without restarting Maya or mayapy. You can do that with Python’s built-in reload function. The reload function takes a module object and reloads it from disk so that the new code will be used.

When we jump between our IDE and the interactive interpreter (or the Maya application) as we did earlier, we will usually reload the code to see the effect of our changes. I will usually write out the import and reload lines, but occasionally will only mention them in text preceding the code.

Keep in mind that reload is not a magic bullet. When you are dealing with simple data and functions as we are here, it is usually fine. But as you start building class hierarchies, decorators, and other things that have dependencies or state, the situation can quickly get out of control. Always test your code in a fresh version of Maya before declaring it done to be sure it does not have some lingering defect hidden by reloading.

Though once you are a master Pythonista you can ignore these warnings and figure out how to reload just about anything!