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.