Importing Maya's built-in Python functionality

Python is a really useful language, but it doesn't actually offer that much out of the box other than some basic commands for manipulating simple data. In order to do truly interesting things, you'll generally need to extend Python's built-in functionality with one or more libraries, including the one that provides access to Maya's functionality.

How to do it...

First, let's import the main Maya scripting library for Python, maya.cmds:

import maya.cmds as cmds

Once we've done that, we can use cmds instead of maya.cmds. For example, if we have this code:

maya.cmds.polyCube()

We can instead use the following:

cmds.polyCube()

That might seem like a minor change, but in the course of a full script, it can save you a great deal of typing. Less typing means fewer typos, so it's well worth doing.

Now that we've done this, let's see what cmds has to offer by listing its contents. Python offers a handy way to display the contents of any object via the dir() command. Let's use that to get a list of all the commands in maya.cmds:

commandList = dir(cmds)
for command in commandList:
    print(command)

Run the preceding code, and you'll see a long list of everything defined in the maya.cmds library. This will be an extensive list, indeed. Most of the commands you'll see are covered in the official docs, but it's good to know how to use dir to investigate a given library.

You can also use dir to investigate a specific command. For example, try the following code:

props = dir(cmds.polyCube)
for prop in props:
    print(prop)

Run the preceding code, and you'll see all of the properties for the polyCube command itself. However, the results will likely look a bit odd in that none of them have anything to do with generating a polygonal cube. That's because maya.cmds.[commandName] is a built-in function. So, if you use dir() to investigate it further, you'll just see the capabilities that are common to Python functions. For details on the specifics of a command, consult the built-in documentation for Maya's commands, which can be accessed by going to Help | Maya Scripting Reference | Python Command Reference.

How it works...

Like any other specific subdomain of Python functionality, the commands that expose Maya's toolset to Python are part of a library. In order to make use of them, you have to first import the library. Virtually, every script you write will require the "maya.cmds" library, and you will likely need to include additional libraries occasionally for additional capabilities, such as communicating with a webserver or reading in a particular file format.

Although you could just leave it at import maya.cmds, that would require a lot of additional typing. By using the import [library] as [shortName] syntax, you can tell Python to use a custom name as an alias for maya.cmds. You could use almost any name you want (import maya.cmds as MyUncleFred would work just fine), but in practice, you want to use something both short and descriptive. You'll also want to make sure that you don't overwrite any of Python's built-in libraries. For example, you could do the following:

import maya.cmds as math

This would rename maya.cmds as math and cause trouble if you wanted to use any of the functions defined in the math library. Don't do that.

For the sake of this book and consistency with Maya's documentation, we will be using "cmds" as the shorthand for "maya.cmds".

There's more...

The maya.cmds library is only one of several libraries that can be used to interface Maya with Python. One of the great things about Python support in Maya is that the old way of doing things, where there was both MEL (for day-to-day tasks) and the C++ API (for larger scale plugins), is unified under the banner of Python. The maya.cmds library handles the MEL component, but for functions previously accessed through the C++ API, you'll want to use maya.OpenMaya instead.

It (maya.cmds) is a lightweight wrapper around the MEL commands that many Maya users have grown accustomed to, and it has the benefit of being officially supported by Autodesk. However, it is not the only way to access MEL commands. There is also a third-party library, PyMEL (accessed by importing pymel.core). PyMEL has the benefit of being more "Pythonic" and offering nicer syntax, but is not directly supported by Autodesk. It also introduces additional layers of abstraction on top of the built-in functionality, which can lead to poorer performance.