Learn how to write an application with PyQt/PySide.
Prerequisites
For the purposes of this tutorial, we will create the application on Linux.
To use Python together with QML, we can use either PySide,
the official Python bindings for the Qt framework or
PyQt, a project by
Riverbank Computing that allows you to write Qt applications using Python.
You will need Python installed, and that will be the case in any major Linux
distribution. But instead of using pip to install PySide/PyQt and Kirigami, you will
need to install them from your distribution. This ensures PySide/PyQt and
Kirigami will have been built for the same Qt version, allowing you to package
it easily. Any other dependencies can be installed from pip in a
Python virtual environment later.
To quickly generate this folder structure, just run: mkdir -p simplemdviewer/src/qml/
Development
The UI will be created in QML and the logic in Python. Users will write some
Markdown text, press a button, and the formatted text will be shown below it.
It is recommended to use a virtual environment. The venv module provides
support for virtual environments with their own site directories,
optionally isolated from system site directories.
Create a directory and a virtual environment for the project:
mkdir simplemdviewer
cd simplemdviewer
python3 -m venv --system-site-packages env/
Activate it using the activate script:
source env/bin/activate
We can verify that we are working in a virtual environment by checking
the VIRTUAL_ENV environment variable with env | grep VIRTUAL_ENV.
It’s time to write some code. At first the application will consist of two files:
a file with the QML description of the user interface, and a Python file that
loads the QML file.
Create a new directory simplemdviewer/src/ and add a new
simplemdviewer_app.py file in this directory:
#!/usr/bin/env python3importosimportsysimportsignalfromPyQt6.QtGuiimportQGuiApplicationfromPyQt6.QtCoreimportQUrlfromPyQt6.QtQmlimportQQmlApplicationEnginedefmain():"""Initializes and manages the application execution"""app=QGuiApplication(sys.argv)engine=QQmlApplicationEngine()"""Needed to close the app with Ctrl+C"""signal.signal(signal.SIGINT,signal.SIG_DFL)"""Needed to get proper KDE style outside of Plasma"""ifnotos.environ.get("QT_QUICK_CONTROLS_STYLE"):os.environ["QT_QUICK_CONTROLS_STYLE"]="org.kde.desktop"base_path=os.path.abspath(os.path.dirname(__file__))url=QUrl(f"file://{base_path}/qml/main.qml")engine.load(url)iflen(engine.rootObjects())==0:quit()app.exec()if__name__=="__main__":main()
#!/usr/bin/env python3importosimportsysimportsignalfromPySide6.QtGuiimportQGuiApplicationfromPySide6.QtCoreimportQUrlfromPySide6.QtQmlimportQQmlApplicationEnginedefmain():"""Initializes and manages the application execution"""app=QGuiApplication(sys.argv)engine=QQmlApplicationEngine()"""Needed to close the app with Ctrl+C"""signal.signal(signal.SIGINT,signal.SIG_DFL)"""Needed to get proper KDE style outside of Plasma"""ifnotos.environ.get("QT_QUICK_CONTROLS_STYLE"):os.environ["QT_QUICK_CONTROLS_STYLE"]="org.kde.desktop"base_path=os.path.abspath(os.path.dirname(__file__))url=QUrl(f"file://{base_path}/qml/main.qml")engine.load(url)iflen(engine.rootObjects())==0:quit()app.exec()if__name__=="__main__":main()
We have just created a
QGuiApplication
object that initializes the application and contains the main event loop. The
QQmlApplicationEngine
object loads the main.qml file.
Create a new src/qml/main.qml file that specifies the UI of the application:
Older distributions such as Debian or Ubuntu LTS that do not have an up-to-date Kirigami might require lowering the Kirigami import version from 3.20 to 3.15 to run.
We have just created a new QML-Kirigami-Python application. Run it:
python3 simplemdviewer_app.py
At the moment we have not used any interesting Python stuff. In reality,
the application can also run as a standalone QML one:
The MdConverter class contains the _source_text member
variable. The sourceText property exposes _source_text
to the QML system through the readSourceText() getter and the
setSourceText() setter functions in PyQt. In PySide, Python-like
setters and getters are used for this purpose.
When setting the sourceText property, the sourceTextChangedsignal
is emitted to let QML know that the property has changed. The mdFormat()
function returns the Markdown-formatted text and it has been declared as a
slot
so as to be invokable by the QML code.
The markdown Python package takes care of formatting. Let’s install
it in our virtual environment:
python3 -m pip install markdown
It is worth noting that in PySide, the Python decorator @QmlElement, along with
the QML_IMPORT_NAME and QML_IMPORT_MAJOR_VERSION takes care of registering the
class MdConveter with QML. In PyQt, this is done through the function
qmlRegisterType() inside simplemdviewer_app.py as seen below.
#!/usr/bin/env python3importosimportsysimportsignalfromPyQt6.QtGuiimportQGuiApplicationfromPyQt6.QtCoreimportQUrlfromPyQt6.QtQmlimportQQmlApplicationEngine,qmlRegisterTypefrommd_converterimportMdConverterdefmain():"""Initializes and manages the application execution"""app=QGuiApplication(sys.argv)engine=QQmlApplicationEngine()"""Needed to close the app with Ctrl+C"""signal.signal(signal.SIGINT,signal.SIG_DFL)"""Needed to get proper KDE style outside of Plasma"""ifnotos.environ.get("QT_QUICK_CONTROLS_STYLE"):os.environ["QT_QUICK_CONTROLS_STYLE"]="org.kde.desktop"qmlRegisterType(MdConverter,"org.kde.simplemdviewer",1,0,"MdConverter")base_path=os.path.abspath(os.path.dirname(__file__))url=QUrl(f"file://{base_path}/qml/main.qml")engine.load(url)iflen(engine.rootObjects())==0:quit()app.exec()if__name__=="__main__":main()
#!/usr/bin/env python3importosimportsysimportsignalfromPySide6.QtGuiimportQGuiApplicationfromPySide6.QtCoreimportQUrlfromPySide6.QtQmlimportQQmlApplicationEnginefrommd_converterimportMdConverter# noqa: F401defmain():"""Initializes and manages the application execution"""app=QGuiApplication(sys.argv)engine=QQmlApplicationEngine()"""Needed to close the app with Ctrl+C"""signal.signal(signal.SIGINT,signal.SIG_DFL)"""Needed to get proper KDE style outside of Plasma"""ifnotos.environ.get("QT_QUICK_CONTROLS_STYLE"):os.environ["QT_QUICK_CONTROLS_STYLE"]="org.kde.desktop"base_path=os.path.abspath(os.path.dirname(__file__))url=QUrl(f"file://{base_path}/qml/main.qml")engine.load(url)iflen(engine.rootObjects())==0:quit()app.exec()if__name__=="__main__":main()
In PyQt, the qmlRegisterType() function has registered the MdConverter type in the
QML system, in the library org.kde.simplemdviewer, version 1.0. In PySide, this registration is done in the
file where the class is defined i.e. md_converter.py through the @QmlElement decorator.
The import name and version of MdConverter type is set through the variables QML_IMPORT_NAME and
QML_IMPORT_MAJOR_VERSION. Finally, the Python import from md_converter import MdConverter in PySide's
simplemdviewer_app.py takes care of making Python and QML engine aware of the @QmlElement decorator.