diff options
author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2019-04-24 14:24:06 +0200 |
---|---|---|
committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2019-04-24 14:24:09 +0200 |
commit | 8b892f71b749a623724ccecca881972a33c9d559 (patch) | |
tree | 88d7a2371481cafd559d4895efa41b6f166ed8ac /sources/pyside2/doc | |
parent | fff6ea0059b7394869166a01674a9afa230bc3a9 (diff) | |
parent | a7038d87ba6ec3b2beeee166930c24f290f6478f (diff) |
Merge remote-tracking branch 'origin/5.12' into 5.13
Change-Id: I28805a29caa05e996b490ba46e27ddbc243cc074
Diffstat (limited to 'sources/pyside2/doc')
-rw-r--r-- | sources/pyside2/doc/CMakeLists.txt | 8 | ||||
-rw-r--r-- | sources/pyside2/doc/contents.rst | 1 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment-cxfreeze.rst | 130 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment-fbs.rst | 106 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment-pyinstaller.rst | 124 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment.rst | 70 | ||||
-rw-r--r-- | sources/pyside2/doc/faq.rst | 4 | ||||
-rw-r--r-- | sources/pyside2/doc/tutorials/basictutorial/clickablebutton.rst | 6 | ||||
-rw-r--r-- | sources/pyside2/doc/tutorials/basictutorial/dialog.rst | 6 | ||||
-rw-r--r-- | sources/pyside2/doc/tutorials/basictutorial/uifiles.rst | 8 | ||||
-rw-r--r-- | sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst | 1 |
11 files changed, 456 insertions, 8 deletions
diff --git a/sources/pyside2/doc/CMakeLists.txt b/sources/pyside2/doc/CMakeLists.txt index b5bde885a..36f770367 100644 --- a/sources/pyside2/doc/CMakeLists.txt +++ b/sources/pyside2/doc/CMakeLists.txt @@ -90,16 +90,12 @@ add_custom_target(qdoc add_custom_target(apidoc COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/rst COMMAND ${SHIBOKEN_PYTHON_INTERPRETER} ${SPHINX_BUILD} -b html ${CMAKE_CURRENT_BINARY_DIR}/rst html - #copying shiboken2 and ApiExtractor doc htmls - COMMENT "Copying over the Shiboken2 and ApiExtractor doc HTMLs..." + #copying shiboken2 (including ApiExtractor) doc htmls + COMMENT "Copying over the Shiboken2 doc HTMLs..." COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/html/shiboken2 - COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/html/shiboken2/ApiExtractor COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_BINARY_DIR}/../../shiboken2/doc/html ${CMAKE_CURRENT_BINARY_DIR}/html/shiboken2 - COMMAND ${CMAKE_COMMAND} -E copy_directory - ${CMAKE_CURRENT_BINARY_DIR}/../../shiboken2/ApiExtractor/doc/html - ${CMAKE_CURRENT_BINARY_DIR}/html/shiboken2/ApiExtractor ) # create conf.py based on conf.py.in diff --git a/sources/pyside2/doc/contents.rst b/sources/pyside2/doc/contents.rst index d6b7f6ffb..675a5b73a 100644 --- a/sources/pyside2/doc/contents.rst +++ b/sources/pyside2/doc/contents.rst @@ -8,6 +8,7 @@ faq.rst gettingstarted.rst tutorials/index.rst + deployment.rst pysideapi2.rst licenses.rst diff --git a/sources/pyside2/doc/deployment-cxfreeze.rst b/sources/pyside2/doc/deployment-cxfreeze.rst new file mode 100644 index 000000000..40b65621b --- /dev/null +++ b/sources/pyside2/doc/deployment-cxfreeze.rst @@ -0,0 +1,130 @@ +===================== +|project| & cx_Freeze +===================== + +`cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ allows you to freeze your Python +application into executables. +The supported platforms are Linux, macOS, Windows, FreeBSD, among others. + + +You can read the `official documentation <https://cx-freeze.readthedocs.io/en/latest/index.html>`_ +to clarify any further question, and remember to contribute to +the project by `filing issues <https://sourceforge.net/projects/cx-freeze/>`_ +if you find any, or contributing to `their development <https://bitbucket.org/anthony_tuininga/cx_freeze/src>`_. + +Preparation +=========== + +Installing `cx_Freeze` can be done via **pip**:: + + pip install cx_freeze + +If you are using a virtual environment, remember to activate it before +installing `cx_Freeze` into it. + +After the installation, you will have the `cxfreeze` binary to deploy +your application. + +Freezing an application +======================= + +There are three options to work with `cx_Freeze`: + + 1. Using the `cxfreeze` script. + 2. Creating `setup.py` script to build the project. + 3. Using the module classes directly (for advanced purposes). + +We will cover the first two uses cases. + +Creating an example +------------------- + +Now, consider the following simple script, named `hello.py`:: + + import sys + import random + from PySide2.QtWidgets import (QApplication, QLabel, QPushButton, + QVBoxLayout, QWidget) + from PySide2.QtCore import Slot, Qt + + class MyWidget(QWidget): + def __init__(self): + QWidget.__init__(self) + + self.hello = ["Hallo Welt", "你好,世界", "Hei maailma", + "Hola Mundo", "Привет мир"] + + self.button = QPushButton("Click me!") + self.text = QLabel("Hello World") + self.text.setAlignment(Qt.AlignCenter) + + self.layout = QVBoxLayout() + self.layout.addWidget(self.text) + self.layout.addWidget(self.button) + self.setLayout(self.layout) + + # Connecting the signal + self.button.clicked.connect(self.magic) + + @Slot() + def magic(self): + self.text.setText(random.choice(self.hello)) + + if __name__ == "__main__": + app = QApplication(sys.argv) + + widget = MyWidget() + widget.resize(800, 600) + widget.show() + + sys.exit(app.exec_()) + + +Using `cxfreeze` executable +--------------------------- + +The command line to proceed will look like this:: + + cxfreeze hello.py + +This command will create a `dist/` directory that will contain the +executable and a `lib/` directory including all the shared libraries. + +To launch the application, you need to just go to the `dist/` directory +and execute the file:: + + cd dist/ + ./main + + +Using a setuptools script +------------------------- + +For this process, you will need an additional script called `setup.py`:: + + import sys + from cx_Freeze import setup, Executable + + setup(name = "MyApp", + version = "0.1", + description = "My GUI App", + executables = [Executable("hello.py")]) + +After that, you need to build the project using it:: + + python setup.py build + +This step will create a `build/` directory with the following structure:: + + build + └── exe.linux-x86_64-3.7 + └── lib + └── main + +The first directory inside `build/` will depend on the platform +you are using, in this case a `x86_64` Linux using Python 3.7. +The structure is the same as previously described, and you can simply +enter the directory and execute the file:: + + cd build/exe.linux-x86_64-3.7 + ./main diff --git a/sources/pyside2/doc/deployment-fbs.rst b/sources/pyside2/doc/deployment-fbs.rst new file mode 100644 index 000000000..94c52a08b --- /dev/null +++ b/sources/pyside2/doc/deployment-fbs.rst @@ -0,0 +1,106 @@ +=============== +|project| & fbs +=============== + +`fbs <https://build-system.fman.io>`_ provides a powerful environment for packaging, +creating installers, and signing your application, but also for managing the application's updates. +Since it is based on PyInstaller, it currently supports Linux, macOS, and Windows. + +You can read the `official tutorial <https://github.com/mherrmann/fbs-tutorial>`_ for more +details on how to use `fbs`, or check the +`documentation <https://build-system.fman.io/manual/>`_ for a complete set of features and +options. + +Preparation +=========== + +Installing `fbs` can be done via **pip**:: + + pip install fbs pyinstaller==3.4 + +If you are using a virtual environment, remember to activate it before +installing it. + +After the installation, you will be able to use the `fbs` executable. + +Starting a new project +====================== + +`fbs` provides nice features that allow you to create a base +project structure by executing the following command:: + + fbs startproject + +This process will prompt you to answer many questions to configure the details +of your project, like: + + * Application name + * Author name + * Qt bindings (PySide2 or PyQt5) + * Bundle indentified (for macOS) + +After the process finishes, you will have a `src/` directory that +will contain the following structure:: + + └── src + ├── build + │ └── settings + └── main + ├── icons + │ ├── base + │ ├── linux + │ └── mac + └── python + +Inside the `settings` directory you can find a couple of `json` files +that you can edit to include more information about your project. + +The main file will be under the `python` directory, and its content by default is:: + + from fbs_runtime.application_context import ApplicationContext + from PySide2.QtWidgets import QMainWindow + + import sys + + class AppContext(ApplicationContext): # 1. Subclass ApplicationContext + def run(self): # 2. Implement run() + window = QMainWindow() + version = self.build_settings['version'] + window.setWindowTitle("MyApp v" + version) + window.resize(250, 150) + window.show() + return self.app.exec_() # 3. End run() with this line + + if __name__ == '__main__': + appctxt = AppContext() # 4. Instantiate the subclass + exit_code = appctxt.run() # 5. Invoke run() + sys.exit(exit_code) + +The example will show an empty `QMainWindow`, and you can execute it by running:: + + fbs run + +Freezing the application +======================== + +Once you verify that the application is properly working, +you can continue with the freezing process:: + + fbs freeze + +After the process finishes, you will get a message stating the location +of your executable, e.g.:: + + Done. You can now run `target/MyApp/MyApp`. If that doesn't work, see + https://build-system.fman.io/troubleshooting. + + +Then executing the application will result in the same window +you saw with the `fbs run` command:: + + cd target/MyApp/ + ./MyApp + +.. note:: This is the case for Linux. For other platforms like macOS, you will need to + enter the directory: `target/MyApp.app/Contents/MacOS`, and for + Windows you will find a `MyApp.exe` executable. diff --git a/sources/pyside2/doc/deployment-pyinstaller.rst b/sources/pyside2/doc/deployment-pyinstaller.rst new file mode 100644 index 000000000..8e6a76052 --- /dev/null +++ b/sources/pyside2/doc/deployment-pyinstaller.rst @@ -0,0 +1,124 @@ +======================= +|project| & PyInstaller +======================= + +`PyInstaller <https://www.pyinstaller.org/>`_ allows you to freeze your python +application into a stand-alone executable. +The supported platforms are Linux, macOS, Windows, FreeBSD, and others. + +One of the main goals of `PyInstaller` is to be compatible with 3rd-party +Python modules, e.g.: |pymodname|. + +You can read the `official documentation <https://www.pyinstaller.org/documentation.html>`_ +to clarify any further question, and remember to contribute to +`the project <https://github.com/pyinstaller/pyinstaller>`_ +by filing issues if you find any, or contributing to their development. + +Preparation +=========== + +Installing `PyInstaller` can be done via **pip**:: + + pip install pyinstaller + +If you are using a virtual environment, remember to activate it before +installing `PyInstaller` into it. + +After the installation, the `pyinstaller` binary will be located in the `bin/` +directory of your virtual environment, or where your Python executable is located. + +If that directory is not in your `PATH`, you need to include the whole path +when executing `pyinstaller`. + +.. warning:: If you already have PySide2 or Shiboken2 installed in your system, PyInstaller will pick them + instead of your virtual environment ones. + +Freezing an application +======================= + +`PyInstaller` has many options that you can use. +To learn more about them you can just run `pyinstaller -h`. + +Two main features are the option to package the whole project +(including the shared libraries) into one executable file (`--onefile`), +and to prepare a directory that will contain +an executable next to all the used libraries. + +Additionally, for Windows you can enable opening a console during the +execution with the option `-c` (or equivalent `--console` or `--nowindowed`). +Further, you can specify to not open such console window +on macOS and Windows with the option `-w` (or equivalent `--windowed` or `--noconsole`). + +Creating an example +------------------- + +Now, consider the following simple script, named `hello.py`:: + + import sys + import random + from PySide2.QtWidgets import (QApplication, QLabel, QPushButton, + QVBoxLayout, QWidget) + from PySide2.QtCore import Slot, Qt + + class MyWidget(QWidget): + def __init__(self): + QWidget.__init__(self) + + self.hello = ["Hallo Welt", "你好,世界", "Hei maailma", + "Hola Mundo", "Привет мир"] + + self.button = QPushButton("Click me!") + self.text = QLabel("Hello World") + self.text.setAlignment(Qt.AlignCenter) + + self.layout = QVBoxLayout() + self.layout.addWidget(self.text) + self.layout.addWidget(self.button) + self.setLayout(self.layout) + + # Connecting the signal + self.button.clicked.connect(self.magic) + + @Slot() + def magic(self): + self.text.setText(random.choice(self.hello)) + + if __name__ == "__main__": + app = QApplication(sys.argv) + + widget = MyWidget() + widget.resize(800, 600) + widget.show() + + sys.exit(app.exec_()) + + +Since it has a UI, we will use the `--windowed` option. + +The command line to proceed will look like this:: + + pyinstaller --name="MyApplication" --windowed hello.py + +This process will create a `dist/` and `build/` directory. +The executable and all the shared libraries required by your application +will be placed inside `dist/MyApplication`. + +To execute the frozen application you can go inside `dist/MyApplication` and +execute the program:: + + cd dist/MyApplication/ + ./MyApplication + +.. note:: The directory inside `dist/` and the executable will have the same name. + +If you prefer to have everything bundled into one executable, i.e.: +no shared libraries next to the executable, you can use the option +`--onefile`:: + + pyinstaller --name="MyApplication" --windowed --onefile hello.py + +This process will take a bit longer, but in the end you will discover +an executable inside the `dist/` directory that you can execute:: + + cd dist/ + ./MyApplication diff --git a/sources/pyside2/doc/deployment.rst b/sources/pyside2/doc/deployment.rst new file mode 100644 index 000000000..582e38992 --- /dev/null +++ b/sources/pyside2/doc/deployment.rst @@ -0,0 +1,70 @@ +========== +Deployment +========== + +Deploying or freezing an application is a crucial part of many Python projects. +Most large projects are not based on a single Python file, so +the distribution of these applications becomes more difficult. + +The options for a project are: + 1. Sending a normal zip-file with the application's content. + 2. Building a proper `Python package (wheel) <https://packaging.python.org/>`_. + 3. Freezing the application in a single binary file, or into a directory. + +For the **third** option, there are many available tools: + * `PyInstaller <https://www.pyinstaller.org/>`_, + * `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_, + * `py2exe <http://www.py2exe.org/>`_, + * `py2app <https://py2app.readthedocs.io/en/latest/>`_, + +Since |project| is a cross-platform framework, +we would like to focus on solutions that at least work on +the three major platform supported by Qt: Linux, macOS, and Windows. + +The following table summarizes the above mentioned tools support: + +=========== ======= ===== ===== ======= +Name License Linux macOS Windows +=========== ======= ===== ===== ======= +py2exe MIT no no yes +py2app MIT no yes no +cx_Freeze MIT yes yes yes +PyInstaller GPL yes yes yes +=========== ======= ===== ===== ======= + +From the table we can see that only *cx_Freeze* and *PyInstaller* +meet our requirements. + +All tools are command-line based, and it could become +a hard task to include more resources to your application, such as +images, icons, and meta-information, because you will need to create +special hooks or separate scripts to handle them. +Additionally, since this only +allows you to freeze your current application, you don't have +any mechanism to update your application. + +To cover the update part, there is a tool built around PyInstaller +called `PyUpdater <https://www.pyupdater.org/>`_ which enables +a simple mechanism to ship applications updates. + +On top of all these features, including also a nice interface +that allows the user to install the application step by step, +or even better, provide templates to create new projects to easily +freeze-them-up is something really beneficial for both developers +and end-users. +This is where `fbs <https://build-system.fman.io>`_ enters the +game, being based on PyInstaller, but including all the nice features +we previously mentioned. + +Here you can find a set of tutorials on how to use the previously +described tools. + +.. note:: Deployment is possible only in Qt for Python 5.12.2 + +.. toctree:: + :name: mastertoc + :maxdepth: 2 + + deployment-pyinstaller.rst + deployment-cxfreeze.rst + deployment-fbs.rst diff --git a/sources/pyside2/doc/faq.rst b/sources/pyside2/doc/faq.rst index e09d98999..aabd017e9 100644 --- a/sources/pyside2/doc/faq.rst +++ b/sources/pyside2/doc/faq.rst @@ -29,11 +29,11 @@ Frequently Asked Questions **Does PySide2 have support for embedded Linux (Raspberry Pi, i.MX6 etc)?** Not at the moment. -**There are three wheels (pyside2, shiboken2, and shiboken2_generator) - what is the different between them?** +**There are three wheels (pyside2, shiboken2, and shiboken2_generator), what is the different between them?** Before the official release, everything was in one big wheel, but it made sense to split the projects in three different wheels: + * **pyside2**: contains all the PySide2 modules to use the Qt framework. Also depends on the shiboken2 module. * **shiboken2**: contains the shiboken2 module with helper functions for PySide2. diff --git a/sources/pyside2/doc/tutorials/basictutorial/clickablebutton.rst b/sources/pyside2/doc/tutorials/basictutorial/clickablebutton.rst index afec6d84f..accb54aea 100644 --- a/sources/pyside2/doc/tutorials/basictutorial/clickablebutton.rst +++ b/sources/pyside2/doc/tutorials/basictutorial/clickablebutton.rst @@ -11,6 +11,7 @@ click it. Let's start by importing the necessary PySide2 classes and python `sys` module: :: + import sys from PySide2.QtWidgets import QApplication, QPushButton from PySide2.QtCore import Slot @@ -31,12 +32,14 @@ console: Now, as mentioned in previous examples you must create the `QApplication` to run your PySide2 code: :: + # Create the Qt Application app = QApplication(sys.argv) Let's create the clickable button, which is a `QPushButton` instance. To label the button, we pass a python string to the constructor: :: + # Create a button button = QPushButton("Click me") @@ -52,11 +55,13 @@ The `QPushButton` has a predefined signal called **clicked**, which is triggered every time the button is clicked. We'll connect this signal to the `say_hello()` function: :: + # Connect the button to the function button.clicked.connect(say_hello) Finally, we show the button and start the Qt main loop: :: + # Show the button button.show() # Run the main Qt loop @@ -64,6 +69,7 @@ Finally, we show the button and start the Qt main loop: Here is the complete code for this example: :: + #!/usr/bin/python import sys diff --git a/sources/pyside2/doc/tutorials/basictutorial/dialog.rst b/sources/pyside2/doc/tutorials/basictutorial/dialog.rst index 1daa6b89d..cdb356b91 100644 --- a/sources/pyside2/doc/tutorials/basictutorial/dialog.rst +++ b/sources/pyside2/doc/tutorials/basictutorial/dialog.rst @@ -10,6 +10,7 @@ Let us just start with a simple stub that creates and shows a dialog. This stub is updated during the course of this tutorial, but you can use this stub as is if you need to: :: + import sys from PySide2.QtWidgets import QApplication, QDialog, QLineEdit, QPushButton @@ -49,6 +50,7 @@ enter their name, and a `QPushButton` that prints the contents of the `QLineEdit`. So, let's add the following code to the `init()` method of our Form: :: + # Create widgets self.edit = QLineEdit("Write my name here..") self.button = QPushButton("Show Greetings") @@ -64,6 +66,7 @@ in your application. In this case, let's use `QVBoxLayout` to lay out the widgets vertically. Add the following code to the `init()` method, after creating the widgets: :: + # Create layout and add widgets layout = QVBoxLayout() layout.addWidget(self.edit) @@ -82,6 +85,7 @@ Finally, we just have to add a function to our custom **Form** and *connect* our button to it. Our function will be a part of the Form, so you have to add it after the `init()` function: :: + # Greets the user def greetings(self): print ("Hello {}".format(self.edit.text())) @@ -94,6 +98,7 @@ Now that we have everything, we just need to *connect* the `QPushButton` to the `Form.greetings()` method. To do so, add the following line to the `init()` method: :: + # Add button signal to greetings slot self.button.clicked.connect(self.greetings) @@ -105,6 +110,7 @@ Complete code Here is the complete code for this tutorial: :: + import sys from PySide2.QtWidgets import (QLineEdit, QPushButton, QApplication, QVBoxLayout, QDialog) diff --git a/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst b/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst index 00731abc3..b00437bcb 100644 --- a/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst +++ b/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst @@ -15,6 +15,7 @@ Add a `QPushButton` to the center of the centralwidget. Your file (mainwindow.ui) should look something like this: :: + <?xml version="1.0" encoding="UTF-8"?> <ui version="4.0"> <class>MainWindow</class> @@ -79,11 +80,13 @@ Another option to interact with a **UI file** is to generate a Python class from it. This is possible thanks to the `pyside2-uic` tool. To use this tool, you need to run the following command on a console: :: + pyside2-uic mainwindow.ui > ui_mainwindow.py We redirect all the output of the command to a file called `ui_mainwindow.py`, which will be imported directly: :: + from ui_mainwindow import Ui_MainWindow Now to use it, we should create a personalized class for our widget @@ -91,6 +94,7 @@ to **setup** this generated design. To understand the idea, let's take a look at the whole code: :: + import sys from PySide2.QtWidgets import QApplication, QMainWindow from PySide2.QtCore import QFile @@ -115,6 +119,7 @@ examples, and our new basic class contains only two new lines that are in charge of loading the generated python class from the UI file: :: + self.ui = Ui_MainWindow() self.ui.setupUi(self) @@ -127,6 +132,7 @@ Loading it directly To load the UI file directly, we will need a class from the **QtUiTools** module: :: + from PySide2.QtUiTools import QUiLoader The `QUiLoader` lets us load the **ui file** dynamically @@ -141,6 +147,7 @@ and use it right away: The complete code of this example looks like this: :: + # File: main.py import sys from PySide2.QtUiTools import QUiLoader @@ -163,4 +170,5 @@ The complete code of this example looks like this: Then to execute it we just need to run the following on a command prompt: :: + python main.py diff --git a/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst b/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst index d291e8399..c34c50647 100644 --- a/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst +++ b/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst @@ -5,6 +5,7 @@ Web Browser Example The example demonstrates the power and simplicity offered by |project| to developers. It uses several |pymodname| submodules to offer a fluid and modern-looking UI that is apt for a web browser. The application offers the following features: + * Tab-based browsing experience using QTabWidget. * Download manager using a QProgressBar and QWebEngineDownloadItem. * Bookmark manager using QTreeView. |