An Example — PyQt-builder v1.14.1 Documentation

# 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.