Using Python bindings for KDE Frameworks

Several of SonicDE's frameworks have Python bindings. Most notably:

• KCoreAddons
  • KAboutData
  • KAboutLicense
  • KSandbox
• KGuiAddons
  • KSystemClipboard
  • KCursorSaver
  • KColorUtils
• KWidgetsAddons
  • KMessageDialog
  • KMessageBox
  • KContextualHelpButton
  • KFontChooser
  • KSeparator
• KStatusNotifierItem
  • KStatusNotifierItem
• KNotifications
  • KNotification
• KUnitConversion
• KXmlGui
  • KXmlGuiWindow
  • KActionCollection
  • KBugReport
  • KToolBar

#Bindings installation

As with Kirigami and PySide6, the bindings must be built against the same Qt version as PySide6, so don't install them with pip: use the ones from your SonicDE installation (see Building Sonic-DE). Frameworks that have bindings build them by default, through their BUILD_PYTHON_BINDINGS CMake option.

They must also match your Python version, as each binding is built for one: a virtual environment using another version of Python can't import them.

Contributing to the bindings: To make another framework available in Python, its C++ library needs to use ECMGeneratePythonBindings; the existing frameworks do this in their python/ folders. When the project is built, this generates a CPython .so file that is installed in Python's site-packages directory, such as /usr/lib64/python3.14/site-packages/, which makes it available to Python scripts. If the site-packages files are installed elsewhere, point Python to them with PYTHONPATH. To propose a change, open a pull request in the framework's repository.

#Reading C++ documentation for use in Python

In the API reference, the top of each class page lists its include and the CMake component it belongs to:

#include <KAboutData>

find_package(KF6 REQUIRED COMPONENTS CoreAddons)

In Python, this translates to the following import, with the name of the framework's module:

from KCoreAddons import KAboutData

Where in C++ you would use:

KAboutData aboutData(
    QStringLiteral("foo"), QStringLiteral("Foo"), QStringLiteral("0.1"),
    QStringLiteral("To Foo or not To Foo"),
    KAboutLicense::GPL,
    QStringLiteral("Copyright 2017 Bar Foundation"), QString(),
    QStringLiteral("https://www.foo-the-app.net"));
aboutData.setDesktopFileName(QStringLiteral("org.barfoundation.foo"));
KAboutData::setApplicationData(aboutData);

auto icon = QIcon::fromTheme(QStringLiteral("start-here-sonicde"));
QApplication::setWindowIcon(icon);

In Python you would write:

aboutData = KAboutData(
    "foo", "Foo", "0.1",
    "To Foo or not To Foo",
    KAboutLicense.GPL,
    "Copyright 2017 Bar Foundation", "",
    "https://www.foo-the-app.net")
aboutData.setDesktopFileName("org.barfoundation.foo")
KAboutData.setApplicationData(aboutData)

icon = QIcon.fromTheme("start-here-sonicde")
QApplication.setWindowIcon(icon)

PySide6 has no QString or QStringLiteral, and uses the native Python str type instead. So the default QString() constructor, which creates an empty QString, becomes "", and QStringLiteral() can simply be left out.

Static functions written with :: (like QIcon::fromTheme()) are called with . in Python. The same goes for enums (like KAboutLicense::GPL).