Awesome
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 ofpymel
and it's a mess. A good alternative could be thestubgen
tool includd withmypy
, 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