Nova Flow OS
KDE Developer Platform
KDE Developer Platform
  • KDE Developer Platform
    • Getting started
      • Building KDE software
        • KDE software
        • Where to find the development team
        • Learning more
        • Choose what to work on
        • Source code cross-referencing
        • Installing build dependencies
        • Set up a development environment
        • Building KDE software with kdesrc-build
        • Basic troubleshooting
        • Tips and tricks
        • IDE Configuration
          • Setting up an IDE for KDE development
          • Visual Studio Code
          • Qt Creator
          • Kate
          • KDevelop
          • CLion
          • Sublime Text
        • Building KDE software manually
        • Building KDE software with distrobox and podman
      • Kirigami
        • KDE is ours
        • Setting up and getting started
        • Explaining pages
        • Layouts, ListViews, and Cards
        • Adding actions
        • Adding a dialog
        • Using separate files
        • Next steps
        • Colors and themes in Kirigami
        • Typography
        • Actions based components
        • Page rows and page stacks
        • Scrollable pages and list views
        • Cards
        • Drawers
        • Chips
        • Dialog types
        • Controls and interactive elements
        • Form layouts
        • Inline messages
        • Action toolbars
        • Progress bars and indicators
        • List views
        • Understanding CMakeLists
        • Figuring out main.cpp
        • Connect logic to your QML user interface
        • Connect models to your QML user interface
        • About page
        • Introduction to Kirigami Addons
        • FormCard About pages
        • Form delegates in your settings pages
      • KXmlGui
        • Getting started with KXmlGui
        • Hello World!
        • Creating the main window
        • Using actions
        • Saving and loading
        • Command line interface
      • Python with Kirigami
        • Apps with QML and Python
        • Your first Python + Kirigami application
        • Creating a Python package
        • Creating a Flatpak
      • Common programming mistakes
      • Adding a new KDE project
    • Features
      • Icons
      • Configuration
        • The KConfig Framework
        • Introduction to KConfig
        • Using KConfig XT
        • KDE Frameworks 6 porting guide
        • Settings module (KCM) development
        • KConfigDialog
      • D-Bus
        • What is D-Bus practically useful for?
        • Introduction to D-Bus
        • Accessing D-Bus interfaces
        • Intermediate D-Bus
        • Creating D-Bus interfaces
        • Using custom types with D-Bus
        • D-Bus autostart services
      • Create your own mouse cursor theme
      • Session management
      • Archives
      • Desktop file
      • KAuth
        • Privilege Escalation
        • Using actions in your applications
      • KIdleTime
      • Akonadi: personal information management
        • Debugging Akonadi Resources
        • Using Akonadi in applications
      • Concurrent programming
      • Solid
      • Sonnet
    • Plasma themes and plugins
      • Getting started
      • Plasma Widget tutorial
        • How to create a plasmoid
        • Setup
        • Porting Plasmoids to KF6
        • Testing
        • QML
        • Plasma's QML API
        • Widget Properties
        • Configuration
        • Translations / i18n
        • Examples
        • C++ API
      • KWin Effects
      • Plasma Desktop scripting
        • Javascript Interaction With Plasma Shells
        • Templates
        • Examples
        • API documentation
        • Configuration keys
      • Plasma Style tutorial
        • Creating a Plasma Style quickstart
        • Understanding Plasma Styles
        • SVG elements and Inkscape
        • Background SVG format
        • System and accent colors
        • Theme elements reference
        • Porting themes to Plasma 5
        • Porting themes to Plasma 6
      • Aurorae window decorations
      • KWin scripting tutorial
        • Quick start
        • KWin scripting API
      • Wallpapers
      • Plasma comic
        • Tutorial
        • Testing and debugging
        • Examples
      • Create a custom Window Switcher
      • KRunner C++ Plugin
        • Basic Anatomy of a Runner
        • KRunner metadata format
    • Applications
      • Creating sensor faces
      • Dolphin
        • Creating Dolphin service menus
      • Kate
        • Kate plugin tutorial
      • KMines
        • Making a KMines theme
      • Writing tests
        • Appium automation testing
    • Packaging
      • Android
        • KDE on Android
        • Building applications for Android
        • Packaging and publishing applications for Android
        • Publishing on Google Play
          • Introduction
          • Packaging your app
          • Adding your app to Google Play
          • Publishing your app
          • Releasing new versions of old apps
        • Porting applications to Android
          • Basic porting
          • Making applications run well on Android
          • Metadata
      • Windows
        • Packaging and publishing applications for Windows
        • Publish your app in the Microsoft Store
          • Packaging your app for the Microsoft Store
          • Submitting your app to the Microsoft Store
      • Plasma Mobile
        • KDE on mobile devices
        • Porting a new device to Plasma Mobile
        • KDE Telephony stack
          • General Overview
          • Kernel layer
          • System daemons
            • General overview
            • Developing Telephony functionality
            • ModemManager Telephony functions
          • Session daemons
          • QML declarative plugin layer
          • KDE application layer
        • Execute applications
      • Distributing KDE software as Flatpak
        • Your first Flatpak
        • Extending your package
        • Nightly Flatpaks and Flathub
        • Testing your Flatpak
    • System administration
      • Shell scripting with KDE dialogs
      • Kiosk: Simple configuration management for large deployment
        • Abstract
        • Introduction to Kiosk
        • Kiosk keys
    • Contribute to the documentation
    • About
      • Readme
      • License
        • Creative Commons Attribution-ShareAlike 4.0 International
        • GNU General Public License 3.0 or later
Powered by GitBook
On this page
  • Packaging the application
  • App metadata
  • Calling the app
  1. KDE Developer Platform
  2. Getting started
  3. Python with Kirigami

Creating a Python package

Understand the requirements to create your own Python package.

PreviousYour first Python + Kirigami applicationNextCreating a Flatpak

Last updated 8 months ago

Packaging the application

To distribute the application to users we have to package it. We are going to use the library.

If you'd like to learn more about Python packaging, you'll be interested in the .

Let's recapitulate what the file structure of the project should be:

simplemdviewer
├── README.md
├── LICENSE.txt
├── MANIFEST.in                        # To add our QML file
├── pyproject.toml                     # To declare the tools used to build
├── setup.py                           # To import setuptools
├── setup.cfg                          # The setuptools metadata
├── org.kde.simplemdviewer.desktop
├── org.kde.simplemdviewer.json
├── org.kde.simplemdviewer.svg
├── org.kde.simplemdviewer.metainfo.xml
└── src/
    ├── __init__.py                    # To import the src/ directory as a package
    ├── __main__.py                    # To signal simplemdviewer_app as the entrypoint
    ├── simplemdviewer_app.py
    ├── md_converter.py
    └── qml/
        └── main.qml

Create a simplemdviewer/pyproject.toml to tell the Python build tools what is needed to build our project:

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

Create a simplemdviewer/setup.py to call setuptools:

from setuptools import setup
setup()

Add a new simplemdviewer/setup.cfg to describe the application:

[metadata]
name = org.kde.simplemdviewer
version = 0.1
url = https://mydomain.org/simplemdviewer
author= Example Author
author_email = example@author.org
maintainer = Example Author
maintainer_email = example@author.org
description = A simple markdown viewer
long_description = file: README.md
long_description_content_type = text/markdown
classifiers =
    Development Status :: 5 - Production/Stable
    License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
    Intended Audience :: End Users/Desktop
    Topic :: Utilities
    Programming Language :: Python
    Operating System :: POSIX :: Linux
keywords= viewer converter markdown

[options]
packages = simplemdviewer
package_dir =
    simplemdviewer = src
include_package_data = True
install_requires =
    markdown

In the metadata section we have provided information about the application.

Create an empty simplemdviewer/src/__init__.py file. This file just needs to be present in order to import a directory as a package.

touch __init__.py

Since we are using a custom package directory, namely src/, we pass it as the correct package_dir to find our simplemdviewer application.

It is good to have a README.md file as well.

Create a simplemdviewer/README.md:

# Simple Markdown Viewer

A simple Markdown viewer created with Kirigami, QML and Python.

Apart from the Python stuff, we have to add the QML code to the distribution package as well.

Create a simplemdviewer/MANIFEST.in file with the following contents:

include src/qml/*.qml

App metadata

Some last pieces and we are ready to build. We are going to add:

  1. An application icon.

Create a new simplemdviewer/org.kde.simplemdviewer.desktop. This file is used to show our Markdown Viewer in application menus/launchers.

[Desktop Entry]
Name=Simple Markdown Viewer
Name[ca]=Visualitzador senzill de Markdown
Name[cs]=Jednoduché prohlížení souborů Markdown
Name[eo]=Simpla Markdown-Vidilo
Name[es]=Sencillo visor de Markdown
Name[fr]=Afficheur simple pour langage « Markdown »
Name[it]=Visore Markdown semplice
Name[ja]=シンプルな Markdown ビューアー
Name[nl]=Eenvoudige Markdown-viewer
Name[sl]=Preprosti ogledovalnik Markdown
Name[sv]=Enkel Markdown-visning
Name[tr]=Basit Markdown Görüntüleyicisi
Name[uk]=Простий переглядач Markdown
Name[x-test]=xxSimple Markdown Viewerxx
Name[zh_TW]=簡單 Markdown 檢視器
GenericName=Markdown Viewer
GenericName[ca]=Visualitzador de Markdown
GenericName[cs]=Prohlížeč souborů Markdown
GenericName[eo]=Markdown-Vidilo
GenericName[es]=Visor de Markdown
GenericName[fr]=Afficheur pour langage « Markdown »
GenericName[it]=Visore Markdown
GenericName[ja]=Markdown ビューアー
GenericName[nl]=Markdown-viewer
GenericName[sl]=Ogledovalnik Markdown
GenericName[sv]=Markdown-visning
GenericName[tr]=Markdown Görüntüleyicisi
GenericName[uk]=Переглядач Markdown
GenericName[x-test]=xxMarkdown Viewerxx
GenericName[zh_TW]=Markdown 檢視器
Comment=A simple Markdown viewer application
Comment[ca]=Una aplicació senzilla de visualització de Markdown
Comment[cs]=Jednoduchá aplikace pro prohlížení souborů Markdown
Comment[eo]=Simpla Markdown-vidila aplikaĵo
Comment[es]=Una sencilla aplicación de visor de Markdown
Comment[fr]=Une application d'afficheur pour langage « Markdown »
Comment[it]=L'applicazione di un visore Markdown semplice
Comment[ja]=シンプルな Markdown ビューアーアプリケーション
Comment[nl]=Een eenvoudige toepassing als Markdown-viewer
Comment[sl]=Aplikacija preprostega ogledovalnika Markdown
Comment[sv]=Ett enkelt Markdown-visningsprogram
Comment[tr]=Basit bir Markdown görüntüleyici uygulama
Comment[uk]=Проста програма для перегляду Markdown
Comment[x-test]=xxA simple Markdown viewer applicationxx
Comment[zh_TW]=一個簡單的 Markdown 檢視器應用程式
Version=1.0
Exec=simplemdviewer
Icon=org.kde.simplemdviewer
Type=Application
Terminal=false
Categories=Office;
X-KDE-FormFactor=desktop;tablet;handset;

Add a new simplemdviewer/org.kde.simplemdviewer.metainfo.xml. This file is used to show the application in app stores.

<?xml version="1.0" encoding="utf-8"?>
<component type="desktop">
  <id>org.kde.simplemdviewer</id>
  <metadata_license>CC0-1.0</metadata_license>
  <project_license>GPL-3.0+</project_license>
  <name>Simple Markdown Viewer</name>
  <name xml:lang="ca">Visualitzador senzill de Markdown</name>
  <name xml:lang="cs">Jednoduché prohlížení souborů Markdown</name>
  <name xml:lang="eo">Simpla Markdown-Vidilo</name>
  <name xml:lang="es">Sencillo visor de Markdown</name>
  <name xml:lang="fr">Afficheur simple pour langage « Markdown »</name>
  <name xml:lang="it">Visore Markdown semplice</name>
  <name xml:lang="ja">シンプルな Markdown ビューアー</name>
  <name xml:lang="nl">Eenvoudige Markdown-viewer</name>
  <name xml:lang="sl">Enostavni ogledovalnik Markdown</name>
  <name xml:lang="sv">Enkel Markdown-visning</name>
  <name xml:lang="tr">Basit Markdown Görüntüleyicisi</name>
  <name xml:lang="uk">Простий переглядач Markdown</name>
  <name xml:lang="x-test">xxSimple Markdown Viewerxx</name>
  <name xml:lang="zh-TW">簡單 Markdown 檢視器</name>
  <summary>A simple markdown viewer application</summary>
  <summary xml:lang="ca">Una aplicació senzilla de visualització de Markdown</summary>
  <summary xml:lang="eo">Simpla markdown-spektila aplikaĵo</summary>
  <summary xml:lang="es">Una sencilla aplicación de visor markdown</summary>
  <summary xml:lang="fr">Une application d'afficheur simple pour langage « Markdown »</summary>
  <summary xml:lang="it">L'applicazione di un visore Markdown semplice</summary>
  <summary xml:lang="ja">シンプルな markdown ビューアーアプリケーション</summary>
  <summary xml:lang="nl">Een eenvoudige toepassing als Markdown-viewer</summary>
  <summary xml:lang="sl">Aplikacija enostavnega ogledovalnika Markdown</summary>
  <summary xml:lang="sv">Ett enkelt Markdown-visningsprogram</summary>
  <summary xml:lang="tr">Basit bir Markdown görüntüleyici uygulama</summary>
  <summary xml:lang="uk">Проста програма для перегляду Markdown</summary>
  <summary xml:lang="x-test">xxA simple markdown viewer applicationxx</summary>
  <summary xml:lang="zh-TW">一個簡單的 Markdown 檢視器應用程式</summary>
  <description>
    <p>Simple Markdown Viewer is a showcase application for QML with Python development</p>
    <p xml:lang="ca">El visualitzador senzill de Markdown és una aplicació per a presentar el desenvolupament del QML amb el Python</p>
    <p xml:lang="eo">Simple Markdown Viewer estas montra aplikaĵo por QML kun Python-evoluo</p>
    <p xml:lang="es">Sencillo visor de Markdown es una aplicación de demostración para QML con desarrollo en Python</p>
    <p xml:lang="fr">Un afficheur simple pour langage « Markdown » est une application majeure pour QML pour les développement sous Python</p>
    <p xml:lang="it">Visore Markdown semplice è un'applicazione dimostrativa per QML nello sviluppo in Python</p>
    <p xml:lang="ja">シンプルな Markdown ビューアーは Python 開発による QML のサンプルアプリケーションです。</p>
    <p xml:lang="nl">Eenvoudige Markdown-viewer is een uitstelkast voor QML met Python ontwikkeling</p>
    <p xml:lang="sl">Enostavni ogledovalnik Markdown je predstavitvena aplikacija za razvoj QML s Pythonom</p>
    <p xml:lang="sv">Enkel Markdown-visning är ett förevisningsprogram för QML med Python-utveckling</p>
    <p xml:lang="tr">Basit Markdown Görüntüleyicisi, Python ile QML geliştirmek için bir vitrin uygulamadır</p>
    <p xml:lang="uk">Проста програма для перегляду Markdown є прикладом програми для розробки з QML за допомогою Python</p>
    <p xml:lang="x-test">xxSimple Markdown Viewer is a showcase application for QML with Python developmentxx</p>
    <p xml:lang="zh-TW">《簡單 Markdown 檢視器》是用來示範 QML 與 Python 併用開發的應用程式</p>
  </description>
  <url type="homepage">https://mydomain.org/simplemdviewer</url>
  <releases>
    <release version="0.1" date="2022-02-25">
      <description>
        <p>First release</p>
      </description>
    </release>
  </releases>
  <provides>
    <binary>simplemdviewer</binary>
  </provides>
</component>

For this tutorial the well known Markdown icon is okay.

  1. Open Markdown-mark.svg in Inkscape.

  2. Type Ctrl+a to select everything.

  3. On the top W: text field, type 128 and press Enter.

  4. Go to File -> Document Properties...

  5. Change the Width: text field to 128 and press Enter.

  6. Save the file.

Now we have to let setup.cfg know about the new files. Let’s also provide an easy way to open the application from the console by just typing simplemdviewer.

Update simplemdviewer/setup.cfg to:

[metadata]
name = org.kde.simplemdviewer
version = 0.1
url = https://mydomain.org/simplemdviewer
author= Example Author
author_email = example@author.org
maintainer = Example Author
maintainer_email = example@author.org
description = A simple markdown viewer
long_description = file: README.md
long_description_content_type = text/markdown
classifiers =
    Development Status :: 5 - Production/Stable
    License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
    Intended Audience :: End Users/Desktop
    Topic :: Utilities
    Programming Language :: Python
    Operating System :: POSIX :: Linux
keywords= viewer converter markdown

[options]
packages = simplemdviewer
package_dir =
    simplemdviewer = src
include_package_data = True
install_requires =
    markdown

[options.data_files]
share/applications =
    org.kde.simplemdviewer.desktop
share/icons/hicolor/scalable/apps =
    org.kde.simplemdviewer.svg
share/metainfo =
     org.kde.simplemdviewer.metainfo.xml

[options.entry_points]
console_scripts =
    simplemdviewer = simplemdviewer.simplemdviewer_app:main

The last step is to tinker with the way we import modules.

Update simplemdviewer/src/simplemdviewer_app.py to

#!/usr/bin/env python3

import os
import sys
import signal
from PySide6.QtGui import QGuiApplication
from PySide6.QtCore import QUrl
from PySide6.QtQml import QQmlApplicationEngine

# from md_converter import MdConverter
from simplemdviewer.md_converter import MdConverter  # noqa: F401


def main():
    """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"""
    if not os.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)

    if len(engine.rootObjects()) == 0:
        quit()

    app.exec()


if __name__ == "__main__":
    main()

Create a __main__.py file into the src/ directory. Now that there's a module, this tells the build tools what's the main function, the entrypoint for running the application.

from . import simplemdviewer_app

simplemdviewer_app.main()

Calling the app

This last step will facilitate the execution of the package during development and let us call the application by its name.

From inside the simplemdviewer/ directory, install the app locally as a module and try running it:

python3 -m pip install -e .
python3 -m simplemdviewer

If you have put the required files in the right places, running the application as a module should work.

It’s time to generate the package for our program.

Make sure that the latest version of build is installed:

python3 -m pip install --upgrade build

Execute from inside the simplemdviewer/ directory:

python3 -m build

As soon as the build completes, two archives will be created in the dist/ directory:

  1. the org.kde.simplemdviewer-0.1.tar.gz source archive

  2. the org.kde.simplemdviewer-0.1-py3-none-any.whl package ready for distribution in places such as PyPI

Install the newly-created package into the virtual environment:

python3 -m pip install dist/org.kde.simplemdviewer-0.1.tar.gz

Run:

simplemdviewer

At this point we can tag and release the source code. Linux distributions will package it and the application will be added to their software repositories.

Well done.

The options section contains the project dependencies and the that our is going to provide. There is a lot of and available.

For more details on dependency management in setuptools, check .

Another important piece is the license of our project. Create a simplemdviewer/LICENSE.txt and add the text of the of our project.

The metadata used to show the app in software stores.

A file to add the application to the application launcher.

Get the icon and save it as simplemdviewer/org.kde.simplemdviewer.svg.

We need the icon to be perfectly squared, which can be accomplished with :

setuptools
Python Packaging User Guide
import package
distribution package
options
classifiers
here
license
Appstream
Desktop Entry
Markdown
Inkscape