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:
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!