Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/chadrik/usdstubgen

Generate PEP 484 stubs for static type analysis and code completion for Pixar's Universal Scene Description
https://github.com/chadrik/usdstubgen

Last synced: 3 months ago
JSON representation

Generate PEP 484 stubs for static type analysis and code completion for Pixar's Universal Scene Description

Awesome Lists containing this project

README

        

# 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`](https://mypy.readthedocs.io/en/stable/stubgen.html)
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](https://github.com/ymyzk/pep-561-samples)