pyside6-qml-stubgen

Generate QML stub files (.qmltypes) from Python modules (which use PySide6)

Installation

This tool can be installed though PyPI:

pip install pyside6-qml-stubgen

If you want to use a development version, instead clone the repo and then install using pip:

git clone https://github.com/matsjoyce/pyside6-qml-stubgen.git
pip install ./pyside6-qml-stubgen

This tool has been tested on Linux, Windows and MacOS using pip-installed PySide6 (on GitHub Actions), and on Arch Linux using system packages. It does not run with PyQt6, although it should be possible in theory (send a PR if you get it working). And finally, it does not run using Qt 5 (PySide2 or PyQt5), as that version is no longer being developed, and QML in Qt 5 has less features than in Qt 6, making it a less attractive target for this sort of tool.

[!WARNING] Does not work on Qt 6.10 from PyPI on Linux and MacOS due to https://bugreports.qt.io/browse/PYSIDE-3241

Simple example

As an example, we'll run this tool on https://github.com/matsjoyce/fantasia2. There are two steps to type checking your QML code when using PySide6. First generate the QML type stubs using this tool:

pyside6-qml-stubgen fantasia2 --out-dir qmltypes --ignore fantasia2/alembic/

This command will generate a folder tree containing .qmltypes files and qmldir files matching the runtime structure of QML modules registered by the Python modules.

The second step is to run qmllint on your QML files using the type stubs:

/usr/lib/qt6/bin/qmllint fantasia2/*.qml -I ./qmltypes

If you change the QML files, you can just rerun qmllint. If you change the Python interface, you should rerun both commands.

Links to other projects

This tool relies heavily on PySide6, and is inspired by the metaobjectdump.py tool, although this tool uses a runtime approach instead of static analysis, as that works better on large programs.

Command-line arguments

$ pyside6-qml-stubgen --help
Generate QML stub files (.qmltypes) from Python modules (which use PySide6)

Usage:
    pyside6-qml-stubgen <in-dir>... --out-dir=<out-dir> [--ignore=<path>...] [--metatypes-dir=<dir>] [--qmltyperegistrar-path=<path>] [--force-rebuild] [--file-relative-path=<div>] [--extra-external-modules=<modules>]
    pyside6-qml-stubgen (-h | --help)
    pyside6-qml-stubgen --version

Options:
    --ignore=<path>                     Ignore all Python files that are children of this path
    --metatypes-dir=<dir>               Directory of the Qt 6 metatype files for core modules (automatically detected if not provided)
    --qmltyperegistrar-path=<path>      Path of the qmltyperegistrar tool (automatically detected if not provided)
    --force-rebuild                     Rebuild the stubs from scratch instead of doing a partial update
    --file-relative-path=<div>          Make all paths in generated type files relative to this path
                                            (useful for if the generated stubs need to be used on different systems)
    --extra-external-modules=<modules>  Additional modules which should be assumed to contain QML exposed types (comma separated)
    -h --help                           Show this screen
    --version                           Show version