Creating a Python package

Understand the requirements to create your own Python package.

Packaging the application

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

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

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:

Create a simplemdviewer/setup.py to call setuptools:

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

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

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

For more details on dependency management in setuptools, check here.

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

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:

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

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:

App metadata

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

  1. The Appstream metadata used to show the app in software stores.

  2. A Desktop Entry file to add the application to the application launcher.

  3. An application icon.

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

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

For this tutorial the well known Markdown icon is okay.

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

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

  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:

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

Update simplemdviewer/src/simplemdviewer_app.py to

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.

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:

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:

Execute from inside the simplemdviewer/ directory:

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:

Run:

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.

PreviousYour first Python + Kirigami applicationNextCreating a Flatpak

Last updated