1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
.. _pyside6-project:
pyside6-project
===============
`pyside6-project` is a command line tool for creating, building and deploying
|project| 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
: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", "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 :ref:`tutorial_uifiles`, :ref:`tutorial_qrcfiles`).
*run*
Builds the project and runs the main.
*deploy*
Deploys the application (see see :ref:`pyside6-deploy`).
*lupdate*
Updates translation (.ts) files (see :ref:`tutorial_translations`).
*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 :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/
|
