diff options
| author | Jaime Resano <Jaime.Resano-Aisa@qt.io> | 2025-02-24 17:04:12 +0100 |
|---|---|---|
| committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2025-03-12 22:15:48 +0100 |
| commit | 8c491f70a0c28b4e4f863539d4a169fd72b2bba1 (patch) | |
| tree | 8bc6801fbc3c48c61cb75e09b0b799f9fb15e4ec /sources/pyside6/doc/tools | |
| parent | 58dc331da48ed85bfa8cc431568db4d8705cdffd (diff) | |
pyproject.toml: 4. Update pyside6-project documentation
This patch modifies the existing pyside6-project documentation to
include the new pyproject.toml file format.
The .pyproject file format is announced as deprecated.
Task-number: PYSIDE-2714
Change-Id: I1efd715babd3f288532b2bbc9d36897fcfc2e2a2
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Diffstat (limited to 'sources/pyside6/doc/tools')
| -rw-r--r-- | sources/pyside6/doc/tools/pyside-project.rst | 112 |
1 files changed, 98 insertions, 14 deletions
diff --git a/sources/pyside6/doc/tools/pyside-project.rst b/sources/pyside6/doc/tools/pyside-project.rst index e7cf813e4..c6913f363 100644 --- a/sources/pyside6/doc/tools/pyside-project.rst +++ b/sources/pyside6/doc/tools/pyside-project.rst @@ -4,23 +4,51 @@ pyside6-project =============== `pyside6-project` is a command line tool for creating, building and deploying -|project| applications. It operates on a project file which is also used by -`Qt Creator`_. +|project| applications. It operates on project files which are also supported +by `Qt Creator`_. -Project file format -------------------- +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. -The project file format is a simple `JSON`_-based format with the suffix -``.pyproject`` listing all files of the project excluding generated files -(typically ``.py``, ``.qml``, ``.qrc``, ``.ts``, or ``.ui`` files): +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 +:ref:`Migrating from *.pyproject to pyproject.toml<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: + +.. code-block:: toml + + [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: .. code-block:: json { - "files": ["main.py"] + "files": ["main.py", "main_window.py"] } - Usage ----- @@ -28,8 +56,7 @@ 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. + Creates a new QtWidgets project with a *Qt Widgets Designer*-based main window. *new-widget* Creates a new QtWidgets project with a main window. @@ -37,11 +64,14 @@ the below commands, passing the project name (directory): *new-quick* Creates a new QtQuick project. -The other commands take the project file as an argument. +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, generating the required build artifacts + Builds the project. Compiles resources, UI files, and QML files if existing and necessary. (see :ref:`tutorial_uifiles`, :ref:`tutorial_qrcfiles`). *run* @@ -54,11 +84,65 @@ It is also possible to specify a directory containing the project file. Updates translation (.ts) files (see :ref:`tutorial_translations`). *clean* - Cleans the build artifacts. + 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 :ref:`Migrating from *.pyproject to pyproject.toml <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: + +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: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + mkdir myproject + cd myproject + echo {"files": ["main.py", "my_widget.py"]} > myproject.pyproject + pyside6-project migrate-pyproject + +Generated pyproject.toml file: + +.. code-block:: toml + + [project] + name = "myproject" + + [tool.pyside6-project] + files = ["main.py", "my_widget.py"] .. _`Qt Creator`: https://www.qt.io/product/development-tools +.. _`Python Packaging User Guide specification: "Writing your pyproject.toml"`: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/ .. _`JSON`: https://www.json.org/ |