pyside6-project

pyside6-project is a command line tool for creating, building and deploying Qt for Python applications. It operates on project files which are also supported by Qt Creator.

A project file contains a list of the source files used in the project. Typically they are .py, .qml, .qrc, .ts, or .ui files. It can also include other subproject files. Generated files such as compiled resources or compiled translations should not be included in the project file.

Currently, two project file formats are supported. Since PySide6 version 6.9.0, the *.pyproject file format is deprecated in favor of the new pyproject.toml file format. The *.pyproject file format is still supported for backward compatibility, but it is recommended to migrate to the new pyproject.toml file format. See Migrating from *.pyproject to pyproject.toml for more information.

pyproject.toml

PySide6 version 6.9.0 added support for the new Python standard pyproject.toml project file format. It is intended to replace the deprecated *.pyproject file format. The project source files are listed in the tool.pyside6-project table. For example:

[project]
name = "myproject"

[tool.pyside6-project]
files = ["main.py", "main_window.py"]

More information about the pyproject.toml file format can be found in Python Packaging User Guide specification: “Writing your pyproject.toml”.

*.pyproject

The deprecated *.pyproject project file uses a simple JSON-based format. The source files are listed in the files array of the JSON root object. For example:

{
    "files": ["main.py", "main_window.py"]
}

Usage

The tool has several subcommands. New projects can be created using the below commands, passing the project name (directory):

new-ui

Creates a new QtWidgets project with a Qt Widgets Designer-based main window.

new-widget

Creates a new QtWidgets project with a main window.

new-quick

Creates a new QtQuick project.

Using the optional --legacy-pyproject flag, the tool will create a legacy .pyproject file instead of a pyproject.toml file.

The following commands can receive a project file as an optional argument. It is also possible to specify a directory containing the project file.

build

Builds the project. Compiles resources, UI files, and QML files if existing and necessary. (see Using .ui files from Designer or QtCreator with QUiLoader and pyside6-uic, Using .qrc Files (pyside6-rcc)).

run

Builds the project and runs the main.

deploy

Deploys the application (see see pyside6-deploy: the deployment tool for Qt for Python).

lupdate

Updates translation (.ts) files (see Translating Applications).

clean

Cleans the build artifacts. For example, compiled resources.

qmllint

Runs the qmllint tool, checking the QML files.

migrate-pyproject

Migrates the content of one or more *.pyproject files to a pyproject.toml file. See Migrating from *.pyproject to pyproject.toml.

Considerations

For each file entry in the project files, pyside6-project does the following:

• <other project file>: Recursively handle subproject

• <name>.qrc: Runs the resource compiler to create a file rc_<name>.py

• <name>.ui: Runs the user interface compiler to create a file ui_<name>.py

For a Python file declaring a QML module, a directory matching the URI is created and populated with .qmltypes and qmldir files for use by code analysis tools. Currently, only one QML module consisting of several classes can be handled per project file.

Migrating from *.pyproject to pyproject.toml

Since PySide6 6.9.0, pyside6-project tool can create a new pyproject.toml file or update an existing one with the existing *.pyproject file content. To migrate an existing project, run pyside6-project command with the migrate-pyproject argument. For example:

pyside6-project migrate-pyproject

If no file is specified, the tool will read the *.pyproject files in the current working directory. In the case of having multiple *.pyproject files in the same directory, its contents will be merged. A new pyproject.toml file will be created if not existing. If the file already exists, a confirmation message is displayed to the user asking for confirmation before updating the file with the new content. For example:

mkdir myproject
cd myproject
echo {"files": ["main.py", "my_widget.py"]} > myproject.pyproject
pyside6-project migrate-pyproject

Generated pyproject.toml file:

[project]
name = "myproject"

[tool.pyside6-project]
files = ["main.py", "my_widget.py"]