Skip to content

Enable Python-SIP type stub generation

Kate Corcoran requested to merge thecodewarrior/krita:pykrita-stubs into master

This MR adds the built-in SIP type stub generation to the standard build process, generating a krita.pyi file.

The starting point for my solution was this krita-artists.org post pointing out that SIP can generate stubs, but it isn't currently configured to do so.

Publishing

Because this is my first MR and I'm not familiar with the Krita release process, this MR doesn't include the process for publishing the generated stubs, it just puts them next to the krita.so file. Ideally they would published to PyPI as pykrita-stubs, with the version number matching the Krita version.

History

Attempts at creating PyKrita stubs have a long history, with the most complete version to date being zerobikappa/krita-python-auto-complete, which tries to generate type stubs heuristically based on the C++ source code. However, scanning the source code can only do so much.

For example:

  • The DockWidgetFactoryBase.DockPosition enum is defined in the .sip file, so it's missing from the generated stubs
  • SIP performs automatic conversions on some types, but the generator isn't aware of all of them (e.g. QStringList -> list[str], qint32 -> int)
  • The generated stubs include non-existent functions (e.g. Resource.resource())
  • The generated stubs use the incorrect name in many cases (e.g. KisDocument, KisView, KoResourceSP)

Limitations

Unlike the previous source code scanner based approach, the SIP-generated stubs have no docstrings. SIP supports writing docstrings in their .sip files using the %Docstring directive, but it won't extract doc comments from the C++ source code.

Test Plan

Run the build and check _install/lib/krita-python-libs/PyKrita/krita.pyi. The file should have stubs for everything generated by SIP, plus a section at the bottom for the hand-written DockWidgetFactory stub.

Formalities Checklist

  • I confirmed this builds.
  • I confirmed Krita ran and the relevant functions work.
  • I tested the relevant unit tests and can confirm they are not broken. (If not possible, don't hesitate to ask for help!)
  • I made sure my commits build individually and have good descriptions as per KDE guidelines.
  • I made sure my code conforms to the standards set in the HACKING file.
  • I can confirm the code is licensed and attributed appropriately, and that unattributed code is mine, as per KDE Licensing Policy.
  • Does the patch add a user-visible feature? If yes, is there a documentation MR ready for it at Krita Documentation Repository?

Reminder: the reviewer is responsible for merging the patch, this is to ensure at the least two people can build the patch. In case a patch breaks the build, both the author and the reviewer should be contacted to fix the build. If this is not possible, the commits shall be reverted, and a notification with the reasoning and any relevant logs shall be sent to the mailing list, kimageshop@kde.org.

Merge request reports