usdstubgen

Generate USD .pyi stubs for static type analysis and IDE completion

Usage

./usdstubgen.py -h
usage: usdstubgen.py [-h] [--force-update] [--builddir BUILDDIR] [--release]
                     [--processes PROCESSES] [--verbose] [--query QUERY]
                     xmldir srcdir pkgdir

Generates __init__.pyi files which will live alongside their .py equivalent.
pyi files will be properly detected in pycharm 2017+ and other editors that
fully support PEP484.

positional arguments:
  xmldir                Directory in which to find Doxygen xml files
  srcdir                Directory in which to find USD source code
  pkgdir                Directory in which to find the pxr python package

optional arguments:
  -h, --help            show this help message and exit
  --force-update, -f    Force update json package data
  --builddir BUILDDIR   Directory in which to generate pyi files
  --release             Copy pyi files from builddir to pkgdir
  --processes PROCESSES, -p PROCESSES
                        Number of simulataneous processes to run
  --verbose, -v         Enabled verbose output
  --query QUERY, -q QUERY
                        Query the cache. Overrides other behavior

In order to use this, you must have the USD xml files generated by the docs. To build these, you need to enable a cmake define:

cmake -D PXR_BUILD_DOCUMENTATION=TRUE ...

Then build the stubs:

python usdstubgen.py "${INSTALL_PREFIX}/docs/doxy_xml" "${SOURCE_DIR}" "${INSTALL_PREFIX}/lib/python" --builddir="${BUILD_DIR}/pystubs" --release -f

Development Status

Unsupported! I'll do what I can to help, but I'm pretty strapped for time these days. Pull requests are welcome!

I wanted to get this out there because people keep asking for something like this and while this tool is not the most polished, it works alright. My hope was that boost.python would add support for stub generation, or USD would switch to a different binding generator with stubgen support, but it's been a few years since I wrote this and I figured it could help some people out before something better comes along.

TODO

If someone is feeling really ambitious, here's what I would love to see done with this project:

• Get rid of stubs.py. This is an ancient module that's copied out of pymel and it's a mess. A good alternative could be the stubgen tool includd with mypy, though it will likely require some modification to provide it with hints from the xml docs
• Make python 2 and 3 compatble
• Make it more accurate. There are still a number of objects missing.
• Add CI support for building the stubs
• Release the stubs to PyPI as a PEP 561 stub-only package