Using the Commandline Interface

req2flatpak comes with a simple commandline interface that covers basic usage and makes it easy to get started.

Example

You can, for example, invoke req2flatpak’s commandline interface like this:

./req2flatpak.py --requirements-file requirements.txt --target-platforms cp310-x86_64 cp310-aarch64

When invoked like this, req2flatpak will read the requirements file, query pypi about available downloads, choose appropriate downloads for the specified target platforms, and generate a flatpak-builder build module.

Documentation of Commandline Options

req2flatpak’s commandline interface supports the following commands and options.

usage: req2flatpak [-h] [--requirements [REQUIREMENTS ...]]
                   [--requirements-file [REQUIREMENTS_FILE]]
                   [--target-platforms TARGET_PLATFORMS [TARGET_PLATFORMS ...]]
                   [--cache] [--yaml] [--outfile [OUTFILE]] [--platform-info]
                   [--installed-packages]

Named Arguments

--requirements

One or more requirements can be specified as commandline arguments, e.g., ‘pandas==1.4.4’.

--requirements-file, -r

Requirements can be read from a specified requirements.txt file.

--target-platforms, -t

Target platforms can be specified as, e.g., ‘39-x86_64’ or ‘310-aarch64’.

--cache

Uses a persistent cache when querying pypi.

Default: False

--yaml

Write YAML instead of the default JSON. Needs the ‘pyyaml’ package.

Default: False

--outfile, -o

By default, writes JSON but specify a ‘.yaml’ extension and YAML will be written instead, provided you have the ‘pyyaml’ package.

Default: <_io.TextIOWrapper name=’<stdout>’ mode=’w’ encoding=’utf-8’>

--platform-info

Prints information about the current platform.

Default: False

--installed-packages

Prints installed packages in requirements.txt format.

Default: False

Specifying Python Package Requirements

You can specify python packages as individual commandline arguments or by providing a requirements.txt file. As a result, req2flatpak will include these packages in the generated build module.

It is important to note that req2flatpak expects all package versions to be fully specified. For example, req2flatpak will not accept a package version specification such as requests >= 2.0. Instead, req2flatpak expects all versions to be pinned using the == operator, such as, e.g., requests == 2.0.

The reason for this is that req2flatpak, by design, does not resolve or freeze dependencies. You can use other tools like pip-compile or poetry export to resolve and freeze dependencies and to export them into a requirements.txt file.

Specifying Target Platforms

One or more target platforms can be specified in a simple string format that includes the python version and system architecture.

As a result, req2flatpak will include suitable package downloads for each of the specified target platforms in the flatpak-builder build module that it generates.

The string format for specifying target platforms is <python_version>-<system-architecture>:

The python version is specified as, e.g., cp39 for cpython 3.9 or cp310 for cpython 3.10, and so on. Other python interpreters instead of cpython are not supported.
The system architecture can either be x86_64 or aarch64.

Querying Information about the Current Platform

req2flatpak provides a platform-info command for querying information about the current platform, i.e., about the python interpreter and system architecture used to run the req2flatpak script.

You can run the platform-info command on your target platform to save information about this platform. You can later use the information about your target platform when generating a flatpak build module using req2flatpak’s python apis by reading the platform information from a file and by creating a platform object from it.

Example:

./req2flatpak.py --platform-info

This will generate output like this:

{
    "python_version": [
     "3",
     "10",
     "6"
    ],
    "python_tags": [
     "cp310-cp310-manylinux_2_35_x86_64",
     "cp310-cp310-manylinux_2_34_x86_64",
     "cp310-cp310-manylinux_2_33_x86_64",
     "..."
    ]
}

...note that the list of tags has been shortened in the above output because the list of tags is about 700 lines long.

Querying Installed Python Packages

req2flatpak provides a command installed-packages which allows to query currently installed python packages.

You can run the installed-packages command on your target platform to find out which packages are already installed on this platform. You can later use this information when resolving and pinning python packages in your python application or library, e.g., when using pip, pip-compile or poetry, in order to make sure that your package versions are compatible with your target platform.