Python completion files for OpenMaya 2 and Mari

So as I’m starting to expand my knowledge of Maya and slowly weaning myself off the tragedy of both PyMEL (and cmds, yes, I do use it sometimes /noshame), OpenMaya  and onto more C++ and the Python API 2.0 in general, I’m going to make an admission here: I’m not the kind of guy who can open up Sublime Text, and immediately start banging my head on the keyboard until I have some semblance of a feature implemented. I’m more the kind of person who will painstakingly setup their development environment to the point where it might seem like insanity, but really, I liken to more of how a soldier carefully applies tape to the soles of their feet before slipping their socks and boots on, in order to handle the brutality of a long route march without complaint.

Which is why, you can imagine, I was aghast to discover this was the entirety of what Autodesk provides for their completion files for OpenMaya 2, the new version of the Python API that is supposedly the second coming of Christ.


Nope, I’m not kidding; it’s a total of two SLOC. (And, yes, if we combine all 4 OpenMaya modules together, it’s a grand total of 8, but fuck you.)

And let’s not rag on Autodesk here; The Foundry is notorious for this sort of thing as well. Their flagship products’ Python APIs are still documented using epydoc, for goodness’ sake! (When I was initially writing the Mari Tools, a key stumbling block I had the terrible documentation provided with the product.)

It’s not just them, either; nearly every major DCC product either has no API, or some of the most unfriendly ones ever devised that basically are nothing more than a tick mark on a feature list, which essentially reads as, “We have one, but you’d be better off going through our C++ SDK instead, you wannabe SDE. Get used to using a real programming language!”

Compare any of the above documented APIs with something like Amazon’s boto for S3, or even more something more relevant, ftrack’s, and the differences may not seem like much at first glance. And perhaps, they are negligible for real programmers who are more fluent in C++/Python than I am. But for someone like me, who is kind of in the middle of that painful transition, such documentation helpers are an incredible boost to productivity.

So what is to be done? Well, with the help of Python’s inspect module, we can certainly do a lot of the grunt work ourselves (and it’s what essentially companies do anyway). And thus the Lord came down from the heavens, and he said:

Behold, completion files for Maya and Mari!

Warning: these generated auto-completions, while adequate, are far from perfect; even today I am continuing to find problems here and there in the generated completion files such as incorrect call arguments, wrong definition types etc. These completion files are not intended to be final; what is intended, though, is that I am including the source for these in my Maya/Mari tools, which will be updated as I improve the auto-completion generation scripts. So hopefully in the future you will be able to just generate these from simply invoking a menu command within Maya/Mari itself.

I eventually plan to make a more agnostic version of the scripts that I used to generate the auto-completion files for these two API, but for now, because of the odd behaviour of how Mari handles exposing its modules to the Python interpreter compared to more conventional methods, it’s a little tricky.

If you want to try this on your own, though, here’s the source, but be warned: hastily-written code only lies ahead. You can, however, get the general gist (heh) of things, and see how I made judicious use of inspect’s various convenience methods to help identify an object, and then extract the docstring for it using either its doc property or inspect.getdoc() to do so.

Hope that helps anyone looking to get into OM2/Mari stuff, or even, perhaps, start generating completion files for other Python APIs you know of!

3 comments on “Python completion files for OpenMaya 2 and MariAdd yours →

  1. Hey Alex!

    Yea, I need to update this post with Raffaele’s findings; I want that to coincide with another draft that I’m writing about introspection/reflection in Python and C#. I’ll get around to it eventually 🙂

  2. from maya.api import _OpenMaya_py2 as OpenMaya
    from maya.api import _OpenMayaAnim_py2 as OpenMayaAnim
    from maya.api import _OpenMayaRender_py2 as OpenMayaRender
    from maya.api import _OpenMayaUI_py2 as OpenMayaUI

    These will get you the built-in autocomplete moduels for Python API 2.0.

    It’s not documented anywhere, it’s basically just word-of-mouth at this point, like everything to do with Autodesk and The Foundry.

Leave a Reply