<div align="center">
<img alt="icon.png" height="60" src="https://github.com/JezaChen/PyQtInspect-README-Assets/blob/main/Images/icon.png?raw=true"/>
</div>
<h1 align="center">PyQtInspect</h1>
<p align="center">To inspect PyQt/PySide program elements like Chrome's element inspector.</p>
<p align="center">
<a href="https://jeza-chen.com/PyQtInspect-README-zh">中文文档</a> |
<a href="https://pypi.org/project/PyQtInspect/">PyPI</a>
</p>
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_:
- Debugging 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.
When debugging, please **start the GUI server first**, then launch the Python program to be debugged.
### Start the Debugging 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.
<img alt="start_server.png" height="600" src="https://github.com/JezaChen/PyQtInspect-README-Assets/blob/main/Images/start_server.png?raw=true"/>
### Start the Debugged Side
#### 1. Running Program Source Code with `PyQtInspect` Attached (Recommended)
It's the **recommended** startup method which requires full access to the Python source code of
the program to be debugged.
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:
```powershell
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 [`PyQt-Fluent-Widgets`][1],
the demo gallery program is run with `python examples/gallery/demo.py`.
Now you can start the `PyQtInspect` client with
`python -m PyQtInspect --file examples/gallery/demo.py`.
**Note: Only PyQt5 programs do not need the `--qt-support` parameter;
other frameworks need to specify this parameter explicitly!**
#### 2. Using PyCharm (Recommended)
Directly debug the `PyQtInspect` module in PyCharm without affecting program debugging.
Also taking [`PyQt-Fluent-Widgets`][1] as an example,
you can create a new Debug configuration with the following parameters:
Then just Run/Debug as usual.
#### 3. Attach to Process (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][3], 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][2], 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 [`jezachen@163.com`](mailto:jezachen@163.com).**
[1]: https://github.com/zhiyiYo/PyQt-Fluent-Widgets
[2]: https://www.riverbankcomputing.com/pipermail/pyqt/2017-January/038650.html
[3]: https://pypi.org/project/PyQtInspect/#files
Raw data
{
"_id": null,
"home_page": "https://jeza-chen.com/PyqtInspect",
"name": "PyQtInspect",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "pyqt pyside inspect",
"author": "Jianzhang Chen",
"author_email": "jezachen@163.com",
"download_url": "https://files.pythonhosted.org/packages/4f/fc/8b65f37e50b30818e843a9cd27883aa121b309d0efc32f79ca66961b73f1/pyqtinspect-0.3.5.tar.gz",
"platform": null,
"description": "<div align=\"center\">\r\n<img alt=\"icon.png\" height=\"60\" src=\"https://github.com/JezaChen/PyQtInspect-README-Assets/blob/main/Images/icon.png?raw=true\"/>\r\n</div>\r\n<h1 align=\"center\">PyQtInspect</h1>\r\n<p align=\"center\">To inspect PyQt/PySide program elements like Chrome's element inspector.</p>\r\n\r\n<p align=\"center\">\r\n<a href=\"https://jeza-chen.com/PyQtInspect-README-zh\">\u4e2d\u6587\u6587\u6863</a> | \r\n<a href=\"https://pypi.org/project/PyQtInspect/\">PyPI</a>\r\n</p>\r\n\r\nFor Python GUI programs developed with PyQt/PySide using Qt Widgets,\r\nit is difficult to view control information, locate the codes where they are defined, \r\nand perform other operations at runtime. \r\nIt's not as easy as inspecting HTML elements in Chrome/Firefox browsers. \r\nThis project aims to solve this problem by providing an element inspector tool for PyQt/PySide programs, \r\nsimilar to Chrome's element inspector.\r\n\r\n\r\n\r\n## Requirements\r\n\r\n- Python 3.7+\r\n\r\n- One of the following Qt for Python frameworks: PyQt5/PySide2/PyQt6/Pyside6\r\n\r\n## Installation\r\n\r\nSimply install using `pip install PyQtInspect`.\r\n\r\n## How to Start\r\n\r\nThe PyQtInspect architecture is divided into _two parts_:\r\n\r\n- Debugging side (**Server**): A GUI program for viewing element information, locating code, etc.\r\n\r\n- Debugged side (**Client**): Runs within the Python program to be debugged, \r\n patches the host program's Qt framework, and transmits information to the server.\r\n\r\nWhen debugging, please **start the GUI server first**, then launch the Python program to be debugged.\r\n\r\n### Start the Debugging Side\r\n\r\nEnter `pqi-server` in the terminal to start the server-side GUI program. \r\nAfter launching, specify the listening port (default is `19394`) \r\nand click the `Serve` button to start listening.\r\n\r\n<img alt=\"start_server.png\" height=\"600\" src=\"https://github.com/JezaChen/PyQtInspect-README-Assets/blob/main/Images/start_server.png?raw=true\"/>\r\n\r\n### Start the Debugged Side\r\n\r\n#### 1. Running Program Source Code with `PyQtInspect` Attached (Recommended)\r\n\r\nIt's the **recommended** startup method which requires full access to the Python source code of \r\nthe program to be debugged.\r\n\r\nIf you run this program to be debugged with `python xxx.py param1 param2`, \r\nsimply **insert** `-m PyQtInspect --file` **between** `python` and `xxx.py`, i.e.,\r\nuse `python -m PyQtInspect --file xxx.py param1 param2` to attach the PyQtInspect client\r\nto the `xxx.py` program with parameters `param1` and `param2`.\r\n\r\nThe complete startup command is:\r\n\r\n```powershell\r\npython -m PyQtInspect [--port N] [--client hostname] [--multiprocess] [--show-pqi-stack] [--qt-support=[pyqt5|pyside2|pyqt6|pyside6]] --file executable_file [file_args]\r\n```\r\n\r\nEach parameter is explained as follows:\r\n\r\n* `--port`: Specify the server's listening port, default is `19394`\r\n* `--client`: Specify the server's listening address, default is `127.0.0.1`\r\n* `--multiprocess`: Specify whether to support **multiprocess inspecting**, **disabled by default**\r\n* `--show-pqi-stack`: Specify whether to display the call stack related to `PyQtInspect`, **disabled by default**\r\n* `--qt-support`: Specify the Qt framework used by the program being debugged, **default is `pyqt5`**; optional values are `pyqt5`, `pyside2`, `pyqt6`, `pyside6`\r\n* `--file`: Specify the path to the Python source code file of the program to be debugged\r\n* `file_args`: Command-line arguments for starting the program to be debugged\r\n\r\nFor example, to debug [`PyQt-Fluent-Widgets`][1], \r\nthe demo gallery program is run with `python examples/gallery/demo.py`.\r\nNow you can start the `PyQtInspect` client with \r\n`python -m PyQtInspect --file examples/gallery/demo.py`.\r\n\r\n**Note: Only PyQt5 programs do not need the `--qt-support` parameter; \r\nother frameworks need to specify this parameter explicitly!**\r\n\r\n#### 2. Using PyCharm (Recommended)\r\n\r\nDirectly debug the `PyQtInspect` module in PyCharm without affecting program debugging.\r\n\r\nAlso taking [`PyQt-Fluent-Widgets`][1] as an example,\r\nyou can create a new Debug configuration with the following parameters:\r\n\r\n\r\n\r\nThen just Run/Debug as usual.\r\n\r\n#### 3. Attach to Process (Currently Unstable)\r\n\r\nIf the source code of the program to be debugged is not available, \r\nyou can attempt to start the `PyQtInspect` client by **attaching** to the process.\r\n\r\nClick `More->Attach` To Process, select the process window of the program to be debugged, \r\nand click the `Attach` button.\r\n\r\n**Note: Most controls will not have their creation call stack information \r\nunless they are created after attaching.**\r\n\r\n\r\n\r\n## Usage\r\n\r\n### Inspecting Element Information\r\n\r\nClick the `Inspect` button, **hover** the mouse over the control you want to inspect, \r\nand preview the control information.\r\n\r\n\r\n\r\nClick the left mouse button to select the control. \r\nYou can then locate the creation call stack, execute code, view hierarchy information, etc.\r\n\r\n\r\n\r\n### Call Stack Location\r\n\r\nThe area below the control information section shows the call stack at the time the control was created.\r\nClicking on it will open `PyCharm`, locating the corresponding file and line.\r\n\r\n\r\n\r\nIf PyCharm fails to open, you can set the PyCharm path in `More->Settings` manually.\r\n\r\n**p.s. For the PyQtInspect client started via Attach to Process, \r\nif the control was already created during the attach process, \r\nthe call stack information will not be available, and this area will be empty.**\r\n\r\n### Executing Code\r\nAfter selecting a control, \r\nclick the `Run Code` button to execute code within the scope of the selected control \r\n**(where the selected control instance is `self`, \r\nessentially executing code within one of the control's methods)**.\r\n\r\n\r\n\r\n### Viewing Hierarchy Information\r\nA hierarchy navigation bar is at the bottom of the tool, \r\nallowing you **to directly view, highlight, \r\nand locate ancestor and child controls of the selected control**.\r\nIt also makes it easier to switch between controls within the hierarchy.\r\n\r\nCombined with mouse selection, users can make more precise selections.\r\n\r\n\r\n\r\n### Simulate Left Click with Right Click During Inspection \r\n\r\n_(Enabled by Default, Disable in `More->Mock Right Button Down as Left`)_\r\n\r\nSince some controls only appear after a left click, \r\nright-clicking can simulate a left click to facilitate inspection.\r\n\r\n\r\n\r\n### Force Selection with F8 \r\n\r\n_(Enabled by Default, Disable in `More->Press F8 to Finish Inspect`)_\r\n\r\nFor controls that are difficult to select with a mouse click, \r\nyou can complete the selection with F8. \r\nNote that F8 **is only used to finish selection** during the inspection process;\r\npressing F8 **WILL NOT start selection** if inspection is not active.\r\n\r\n## Source Code\r\n\r\nCurrently, the source code distribution package can be downloaded from \r\n[PyPi][3], and the GitHub repository will be opened soon.\r\n\r\n## Known Issues\r\n- **Patching fails with multiple inheritance involving more than two PyQt classes**, such as class `A(B, C)`, \r\n where `B` and `C` inherit from **QObject**. This might cause the `__init__` method of `C` to not execute, leading to exceptions.\r\n > [The author of PyQt has warned against multiple inheritance with more than two PyQt classes][2], as it can also cause abnormal behavior in PyQt itself.\r\n\r\n- Cannot select some controls for **PyQt6**.\r\n\r\n- For some computers, sometimes the `QEnterEvent` will have the type `170` (which is `QEvent.DynamicPropertyChange`),\r\n which may cause crash when accessing the `propertyName` method.\r\n\r\n**If you encounter any problems before the GitHub repository is opened,\r\nplease email me at [`jezachen@163.com`](mailto:jezachen@163.com).**\r\n\r\n\r\n[1]: https://github.com/zhiyiYo/PyQt-Fluent-Widgets\r\n[2]: https://www.riverbankcomputing.com/pipermail/pyqt/2017-January/038650.html\r\n[3]: https://pypi.org/project/PyQtInspect/#files\r\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "To inspect PyQt/PySide program elements like Chrome's element inspector",
"version": "0.3.5",
"project_urls": {
"Homepage": "https://jeza-chen.com/PyqtInspect"
},
"split_keywords": [
"pyqt",
"pyside",
"inspect"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0bf2a4834cec4c32e9a831765050474b7520ab1ef368b68382b91c55454d70c8",
"md5": "5de1e4fa65de2af5aba474df3a6d76eb",
"sha256": "3ddbff3885151e504c6d390e001f8afa67c81133f4891e0d3f6140279feb5fdc"
},
"downloads": -1,
"filename": "PyQtInspect-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5de1e4fa65de2af5aba474df3a6d76eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 4061203,
"upload_time": "2024-08-21T03:00:05",
"upload_time_iso_8601": "2024-08-21T03:00:05.151819Z",
"url": "https://files.pythonhosted.org/packages/0b/f2/a4834cec4c32e9a831765050474b7520ab1ef368b68382b91c55454d70c8/PyQtInspect-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4ffc8b65f37e50b30818e843a9cd27883aa121b309d0efc32f79ca66961b73f1",
"md5": "1a719eca9f5d844178fe9243c282cf09",
"sha256": "7a32c69468ad60809cd9965065c75c0e69457ab2b735c8674dd5b93ba0dacf4f"
},
"downloads": -1,
"filename": "pyqtinspect-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "1a719eca9f5d844178fe9243c282cf09",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 3968276,
"upload_time": "2024-08-21T03:00:08",
"upload_time_iso_8601": "2024-08-21T03:00:08.872711Z",
"url": "https://files.pythonhosted.org/packages/4f/fc/8b65f37e50b30818e843a9cd27883aa121b309d0efc32f79ca66961b73f1/pyqtinspect-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-21 03:00:08",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pyqtinspect"
}
JSON