PyQtInspect 0.3.6

To inspect PyQt/PySide program elements like Chrome's element inspector

PyQtInspect

To inspect PyQt/PySide program elements like Chrome's element inspector.

中文文档 | PyPI

For Python GUI programs developed with PyQt/PySide using Qt Widgets, it is difficult to view control information, locate the codes where they are defined, and perform other operations at runtime. It's not as easy as inspecting HTML elements in Chrome/Firefox browsers. This project aims to solve this problem by providing an element inspector tool for PyQt/PySide programs, similar to Chrome's element inspector.

Requirements

• Python 3.7+

• One of the following Qt for Python frameworks: PyQt5/PySide2/PyQt6/Pyside6

Installation

Simply install using pip install PyQtInspect.

How to Start

The PyQtInspect architecture is divided into two parts:

• Debugger side (Server): A GUI program for viewing element information, locating code, etc.

• Debugged side (Client): Runs within the Python program to be debugged, patches the host program's Qt framework, and transmits information to the server.

Start Modes

Two start modes are currently supported:

• Detached Mode: Manually start the server first, then launch the client to connect to the server. The server will not close when the client closes.
• Direct Mode: Start the client directly, which will also launch a local server at the same time (no need to launch the server in advance). The server will close when the client closes.

In Direct Mode, running each debugged program will automatically create a corresponding server, forming a one-to-one relationship. Users cannot manually specify the server’s listening port, close the connection, or attach to other processes. Detached Mode supports remote debugging (the server and client are on different machines), whereas Direct Mode does not, as both the client and the server which is automatically launched run on the same machine.

Additionally, PyQtInspect supports running in PyCharm and other IDEs, and attaching to PyQt/PySide processes.

Start in Direct Mode

This is the recommended method, which starts both the PyQtInspect server and client at the same time. It requires full access to the Python source code of the debugged program.

If you typically run PyQt5 applications using python xxx.py param1 param2, just insert the -m PyQtInspect --direct --file argument between python and xxx.py, like so: python -m PyQtInspect --direct --file xxx.py param1 param2 to start PyQtInspect.

If the debugged program uses PySide2/PyQt6/Pyside6, you need to add the --qt-support parameter to specify the corresponding Qt framework. For example, for a PySide2 program, the full command is python -m PyQtInspect --direct --qt-support=pyside2 --file xxx.py param1 param2.

The complete command is:

python -m PyQtInspect --direct [--multiprocess] [--show-pqi-stack] [--qt-support=[pyqt5|pyside2|pyqt6|pyside6]] --file executable_file [file_args]

Explanation of parameters:

• --direct: Specifies the start mode as Direct Mode
• --multiprocess: Specify whether to support multiprocess inspecting, disabled by default
• --show-pqi-stack: Specify whether to display the call stack related to PyQtInspect, disabled by default
• --qt-support: Specify the Qt framework used by the program being debugged, default is pyqt5; optional values are pyqt5, pyside2, pyqt6, pyside6
• --file: Specify the path to the Python source code file of the program to be debugged
• file_args: Command-line arguments for starting the program to be debugged

For example, to debug the PySide2 version of PyQt-Fluent-Widgets, which is usually run with python examples/gallery/demo.py, new you can use python -m PyQtInspect --direct --qt-support=pyside2 --file examples/gallery/demo.py to start the PyQtInspect server and client in Direct Mode.

Start in Detached Mode

In Detached Mode, make sure to start the GUI server before launching the debugged Python program.

Start the Debugger Side

Enter pqi-server in the terminal to start the server-side GUI program. After launching, specify the listening port (default is 19394) and click the Serve button to start listening.

Start the Debugged Side: Running Program Source Code attached with PyQtInspect

This requires full access to the Python source code of the debugged program.

If you run this program to be debugged with python xxx.py param1 param2, simply insert -m PyQtInspect --file between python and xxx.py, i.e., use python -m PyQtInspect --file xxx.py param1 param2 to attach the PyQtInspect client to the xxx.py program with parameters param1 and param2.

The complete startup command is:

python -m PyQtInspect [--port N] [--client hostname] [--multiprocess] [--show-pqi-stack] [--qt-support=[pyqt5|pyside2|pyqt6|pyside6]] --file executable_file [file_args]

Each parameter is explained as follows:

• --port: Specify the server's listening port, default is 19394
• --client: Specify the server's listening address, default is 127.0.0.1
• --multiprocess: Specify whether to support multiprocess inspecting, disabled by default
• --show-pqi-stack: Specify whether to display the call stack related to PyQtInspect, disabled by default
• --qt-support: Specify the Qt framework used by the program being debugged, default is pyqt5; optional values are pyqt5, pyside2, pyqt6, pyside6
• --file: Specify the path to the Python source code file of the program to be debugged
• file_args: Command-line arguments for starting the program to be debugged

For example, to debug the PySide2 version of PyQt-Fluent-Widgets, the demo gallery program is run with python examples/gallery/demo.py. Now you can start the PyQtInspect client with python -m PyQtInspect --qt-support=pyside2 --file examples/gallery/demo.py. You can specify other parameters as needed. Make sure the server is already running and listening on port 19394(default port) before starting the client.

Note: Only PyQt5 programs do not need the --qt-support parameter; other frameworks need to specify this parameter explicitly!

Other Running Methods

Running PyQtInspect in PyCharm (supports Detached Mode/Direct Mode) (Recommended)

Directly debug the PyQtInspect module in PyCharm without affecting program debugging.

Also taking PyQt-Fluent-Widgets as an example, you can create a new Debug configuration with the following parameters:

Then just Run/Debug as usual.

Attach to Process (supports Detached Mode only, currently unstable)

If the source code of the program to be debugged is not available, you can attempt to start the PyQtInspect client by attaching to the process.

Click More->Attach To Process, select the process window of the program to be debugged, and click the Attach button.

Note: Most controls will not have their creation call stack information unless they are created after attaching.

Usage

Inspecting Element Information

Click the Inspect button, hover the mouse over the control you want to inspect, and preview the control information.

Click the left mouse button to select the control. You can then locate the creation call stack, execute code, view hierarchy information, etc.

Call Stack Location

The area below the control information section shows the call stack at the time the control was created. Clicking on it will open PyCharm, locating the corresponding file and line.

If PyCharm fails to open, you can set the PyCharm path in More->Settings manually.

p.s. For the PyQtInspect client started via Attach to Process, if the control was already created during the attach process, the call stack information will not be available, and this area will be empty.

Executing Code

After selecting a control, click the Run Code button to execute code within the scope of the selected control (where the selected control instance is self, essentially executing code within one of the control's methods).

Viewing Hierarchy Information

A hierarchy navigation bar is at the bottom of the tool, allowing you to directly view, highlight, and locate ancestor and child controls of the selected control. It also makes it easier to switch between controls within the hierarchy.

Combined with mouse selection, users can make more precise selections.

Simulate Left Click with Right Click During Inspection

(Enabled by Default, Disable in More->Mock Right Button Down as Left)

Since some controls only appear after a left click, right-clicking can simulate a left click to facilitate inspection.

Force Selection with F8

(Enabled by Default, Disable in More->Press F8 to Finish Inspect)

For controls that are difficult to select with a mouse click, you can complete the selection with F8. Note that F8 is only used to finish selection during the inspection process; pressing F8 WILL NOT start selection if inspection is not active.

Source Code

Currently, the source code distribution package can be downloaded from PyPi, and the GitHub repository will be opened soon.

Known Issues

• Patching fails with multiple inheritance involving more than two PyQt classes, such as class A(B, C), where B and C inherit from QObject. This might cause the __init__ method of C to not execute, leading to exceptions.

  The author of PyQt has warned against multiple inheritance with more than two PyQt classes, as it can also cause abnormal behavior in PyQt itself.

• Cannot select some controls for PyQt6.

• For some computers, sometimes the QEnterEvent will have the type 170 (which is QEvent.DynamicPropertyChange), which may cause crash when accessing the propertyName method.

If you encounter any problems before the GitHub repository is opened, please email me at [e-mail].