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 library
and is built on top of PyQt. 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.