Creating a Python package
Packaging the application
To distribute the application to users we have to package it. We are going to use the setuptools library.
Currently, the project can only be run as a script directly, that is, by running the files directly with python3 /path/to/simplemdviewer_app.py. This is not a convenient way to run a desktop application.
The goal in this page is to make the project available as a console script and as a module:
- You'll know it is a console script when you are able to run it with
simplemdviewer - You'll know it is a module when you are able to run it with
python3 -m simplemdviewer
If you'd like to learn more about Python packaging, you'll be interested in the Python Packaging User Guide.
General structure
Let's recapitulate what the file structure of the project should be:
simplemdviewer
├── README.md
├── LICENSE.txt
├── MANIFEST.in # To add our QML file to the Python module
├── pyproject.toml # The main file to manage the project
├── 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.qmlCreate a simplemdviewer/pyproject.toml:
| |
Don't worry about the details for now. We will revisit each part as necessary.
The following four sections of the pyproject.toml are fairly straightforward:
[build-system]tells Python to fetch and use setuptools to build the project[project]contains the general metadata for the project[project.readme]specifies a default README file for the project in Markdown[tool.setuptools.data-files]mentions where setuptools should install additional data files that are not typically present in a Python package
Note
Previously, this tutorial used a combination of setup.py to initialize setuptools,
setup.cfg to manage metadata and package information, and pyproject.toml
to specify dependencies. However, PEP 621
has defined pyproject.toml as the main way to specify a project's metadata,
and setuptools has transitioned to
using pyproject.toml as a declarative way to define package information.
It is no longer necessary to initialize setuptools with a setup.py script,
and all metadata, package information, and dependencies are listed
in the pyproject.toml instead.
App metadata
Let's start with the metadata first so we can get it out of the way, namely the ones listed in the sections [project.readme] and [tool.setuptools.data-files].
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.
wget https://www.gnu.org/licenses/gpl-3.0.txt --output-document LICENSE.txtCreate a simplemdviewer/MANIFEST.in file with the following contents:
| |
This file is simply a declaration of additional source code files that should be present in the package when the application runs.
Some last pieces and we are ready to start changing the code. We are going to add:
- The Appstream metadata used to show the app in software stores.
- A Desktop Entry file to add the application to the application launcher.
- An application icon.
Create a new simplemdviewer/org.kde.simplemdviewer.desktop. This file is
used to show our Markdown Viewer in application menus/launchers.
| |