An Example

In this section we walk through the pyproject.toml file for the PyQtChart project. PyQtChart is the set of bindings for the QtCharts v5 library and is built on top of PyQt5. It comprises a single extension module. The simplicitly of PyQtChart means that there is no need to provide any additional code in a project.py file.

If you want to look at a more complicated examples that require a project.py file then the QScintilla Python bindings and PyQt itself are good examples.

We show PyQtChart’s pyproject.toml file (downloadable from here) in its entirety below.

# Specify the build system requirements.
[build-system]
requires = ["sip >=5.3, <7", "PyQt-builder >=1.6, <2"]
build-backend = "sipbuild.api"

# Specify the PEP 566 metadata for the project.
[tool.sip.metadata]
name = "PyQtChart"
version = "5.15.2"
summary = "Python bindings for the Qt Charts library"
home-page = "https://www.riverbankcomputing.com/software/pyqtchart/"
author = "Riverbank Computing Limited"
author-email = "info@riverbankcomputing.com"
license = "GPL v3"
requires-dist = "PyQt5 (>=5.15)"
description-file = "README"

# Specify a PyQt-based project.
[tool.sip]
project-factory = "pyqtbuild:PyQtProject"

# Configure the project.
[tool.sip.project]
tag-prefix = "QtChart"

# Define and configure each set of bindings.
[tool.sip.bindings.QtChart]
qmake-QT = ["charts"]

We will now explain each section in turn. We assume you are familiar with the examples described in the SIP documentation.

The [build-system] section is used to specify the build system package requirements. For projects using SIP this will include the version requirements of the sip project. For PyQt projects it must also include the version requirements of the PyQt-builder project. Both SIP and PyQt-builder use semantic versioning so it is important that an upper version number is specified for each that will exclude future incompatible versions.

Note

So why does sip specify an upper version of 7 rather than 6? The answer is that it is known that PyQtChart does not use any SIP v5 features that have been removed in SIP v6.

The [tool.sip.metadata] section specifies the meta-data for the project. The requires-dist key is used to specify the minimum version of PyQt that is required.

The [tool.sip] section is used to configure the build system itself and we use the project-factory key to specify that the PyQtProject class is used to implement the concept of a project in the build system. This class implements the many PyQt-specific features of the build system including the definition of additional PyQt-specific keys in the pyproject.toml file itself.

The [tool.sip.project] section is used to specify one such PyQt-specific key tag-prefix. Current versions of PyQtChart use SIP’s %Timeline directive to define tags that are of the form QtChart_x_y_0 where x and y correspond to the major and minor versions of PyQtChart and, consequently, Qt. Projects that follow this convention do not need to use the tags key in the bindings sections to specify the particular %Timeline tag to use and can leave it to the build system to determine it dynamically from the version of Qt being used.

The [tool.sip.bindings.QtChart] section makes use of another PyQt-specific key added by PyQt-builder. This specifies that charts is added to the QT variable in any generated .pro file for this set of bindings. This is all that qmake needs in order to locate the header files and libraries of QtCharts.