Create Mode:

polySphere -n "newSphere" -r 5;
polySphere -n "otherSphere" -r 2;

This creates two polygon sphere objects with the specified radii.

Edit Mode:

polySphere -e -r 1 newSphere otherSphere;

Try though you might, edit mode only works on one object at a time. In this case, the edit will only be applied to newSphere.

Query Mode:

polySphere -q -r newSphere otherSphere;

Just as is the case in edit mode, trying to specify multiple objects does not work—you can only query one object and one attribute at a time. Moreover, while the -r flag typically requires a decimal number, it requires no argument in query mode.

Fundamentally then, you as a programmer have two somewhat tedious problems to solve:

1. How do I make my command throw an error in create/edit modes when there is no argument specified, but not in query mode?
2. How do I make my command require an object in edit and query modes, but not in create mode?

In Complete Maya Programming, David Gould writes:

The various modes are simply a convention used to describe when certain operations can and can’t be performed. Since the operations of creating, editing, and querying are so common, they have been given their own convention that all commands should follow. The standard convention is that if a command supports querying and editing, it adds the query and edit flags. These are defined in their short and long forms as -q/query and -e/edit, respectively. (334-335)

Though this may have been the case at the time that Gould wrote, the API has included special functions for dealing with these modes at least as far back as version 8.5, so they are accessible to Python in all versions with official support. Specifically, the API includes MSyntax.enableQuery() and MSyntax.enableEdit() as part of the syntax definition. Calling these functions in the syntax creator does a couple of things:

1. Automatically adds the edit/query flags to the syntax definition, consequently permitting the use of the MArgParser.isEdit() and MArgParser.isQuery() functions
2. Automatically handles problem number 1 above by throwing descriptive errors^† when constructing the MArgDatabase object using the custom syntax

However, there are a couple of problems. Typically, you can rely on your MArgDatabase construction to catch a variety of syntax errors and provide the user with valuable information.^† For example, you can specify a minimum number of objects in your syntax creator that your command requires:

syntax.setObjectType(OM.MSyntax.kSelectionList, 1) # the command requires a minimum of 1 object

Using this function call, you can reliably parse arguments in your doIt() function like this:

try:
    argData = OM.MArgDatabase(self.syntax(), args) # if this fails, it will raise its own exception...
except:
    pass # ...so we can just pass here
else:
    # Do cool stuff here

…and get a descriptive error message in MEL^† like this if you try to invoke the command without supplying any objects:

// Error: line 1: This command requires at least 1 argument(s) to be specified or selected;  found 0. //

If you try to implement edit and query modes fully manually, as David Gould suggests, then this same technique still works. However, if you use MSyntax.enableQuery() or MSyntax.enableEdit() to add these modes, then they will not respect your minimum object requirements! You can therefore run into problems where your command tries to work with an object in the selection list, but it does not exist because Maya’s built-in error-trapping did not catch the problem. Consequently, you need to add an additional, manual check when you parse your arguments. It could look something like this:

# parse the arguments
try:
	argData = OM.MArgDatabase(self.syntax(), args) # if this fails, it will raise its own exception...
except:
	pass # ...so we can just pass here
else:
	# manually confirm the object list
	sList = OM.MSelectionList()
	argData.getObjects(sList)
	if (argData.isEdit() or argData.isQuery()) and sList.length() is not 1:
		sys.stderr.write ("ERROR: This command requires exactly 1 argument to be specified or selected;  found 0.")
		sys.exit()
	# Do cool stuff here

In the end, there is (at least presently) still some manual work required, though these simple function calls do go some way in helping you easily support additional command modes.

^†Presently, the Command Engine only throws descriptive syntax errors when a command is invoked from MEL. Invoking with a syntax error from Python simply prints no message, though the dysfunction will be contained.

While the command seems to behave as expected in MEL, it does not currently work as expected in Python. Namely, if you first call this command from Python, then the first time it is called it will return None. Thus, to work around this problem, you should either first call the command from MEL, or make the first invocation form Python a dummy, as in this example:

__allNodes__ = cmds.allNodeTypes() # This returns None
__allNodes__ = cmds.allNodeTypes() # This returns the list and can therefore be used throughout your module

Specifically, you might presume that using the MFn.kDagNode or the MFn.kTransform filter should limit the iterator to objects of type kDagSelection. In the former case, this could still include shape nodes, while the latter case properly excludes them. The problem, however, is that the iterator will still include objects of type kPlugSelection, presumably because plugs are technically part of a dependency node. As such, while a transform or any other DAG object could be captured using MItSelectionList.getDagPath(), you can get a difficult-to-find error if a plug has snuck into your selection somehow.

Although you can handle this problem in a variety of ways (such as including a check against the selection item type), I recommend instead using the getDependNode() function to get the node on which the plug exists, and then use a function set to get a a DAG path to this node. I have made a simple Python script so you can see the problem as well as a possible solution:

import maya.OpenMaya as OM
import maya.cmds as cmds

locator1 = cmds.spaceLocator()
mathNode = cmds.createNode('multMatrix')
locator2 = cmds.spaceLocator()

sList = OM.MSelectionList()
sList.add(locator1[0])
sList.add('%s%s'%(locator1[0],'.rotateX'))
sList.add(mathNode)
sList.add(locator2[0])
sList.add('locatorShape%s'%locator2[0].lstrip('locator'))

sListAsStrings = []
sList.getSelectionStrings(sListAsStrings)
print 'List: %s'%sListAsStrings

iter = OM.MItSelectionList(sList, OM.MFn.kDagNode)
node = OM.MObject()
path = OM.MDagPath()
items = {0:'kDagSelectionItem',
    1:'kAnimSelectionItem',
    2:'kDNselectionItem',
    3:'kPlugSelectionItem'}

while not iter.isDone():
    iter.getDependNode(node)
    OM.MFnDagNode(node).getPath(path)
    print '------------'
    print 'Item Type: %s'%(items[iter.itemType()])
    print 'Dependency Node: %s'%OM.MFnDependencyNode(node).name()
    print 'DAG Path: %s'%path.partialPathName()
    iter.next()

You should end up with something like:

List: [u'locator1', u'locator1.rotateX', u'multMatrix4', u'locator2', u'locatorShape2']
------------
Item Type: kDagSelectionItem
Dependency Node: locator1
DAG Path: locator1
------------
Item Type: kPlugSelectionItem
Dependency Node: locator1
DAG Path: locator1
------------
Item Type: kDagSelectionItem
Dependency Node: locator2
DAG Path: locator2
------------
Item Type: kDagSelectionItem
Dependency Node: locatorShape2
DAG Path: locatorShape2

1. Use sys.path.append() in your userSetup.py file
2. Set the value for PYTHONPATH in your maya.env file
3. Set the value for PYTHONPATH at the system level

Autodesk’s documentation can help you figure out the first two methods reasonably well, and they work fine for most situations. However, if you have locations you want to use with Maya as well as other interpreters, the third option may be helpful. While doing this on Windows is relatively easy, it is a little painful on Mac OSX.

Most Google searching will send you to some variation on this technique, whereby you create an environment.plist file containing the value for your PYTHONPATH variable and place it in a folder ~/.MacOSX. Maybe this will work for you, but maybe it won’t. It didn’t work for me. What’s the problem?

Apparently, when you start an application from Spotlight as opposed to Finder, it has a different parent process—one that does not use the environment.plist file. I have gotten used to using Spotlight to start all of my applications and to perform the majority of my menu operations because it saves me huge amounts of time while working (and I don’t want to have to remember where stuff is). Fortunately, there is a fix that will ensure your environment variables will be properly set in all contexts. I suggest you read about the details if you are interested, but if you just want to work then use the following solution:

1. If you do not have a launchd.conf file in /etc then create one
2. Edit launchd.conf to contain a line like this: setenv PYTHONPATH /Users/Shared/Autodesk/maya/scripts
3. Reboot

You can now confirm that this has worked by opening Terminal from Spotlight and entering the set command.