# PyQt Preview - Live Preview Tool for PyQt GUI Development
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](https://www.python.org/downloads/)
[](https://github.com/your-username/pyqt-preview)
PyQt Preview is a development tool for PyQt5/PyQt6/PySide2/PySide6 GUI applications that provides live reloading when editing `.py` or `.ui` files—speeding up your development process. It works out of the box, is highly configurable, and supports advanced workflows for both beginners and professionals.
## Features
- **Live Reload**: Instantly reloads your PyQt application when files change
- **UI Compilation**: Automatically compiles .ui files to Python code
- **Multiple Frameworks**: Supports PyQt5, PyQt6, PySide2, and PySide6
- **Smart Watching**: Configurable file patterns and ignore rules
- **Zero Configuration**: Works out of the box with sensible defaults
- **Preserve State**: Maintains window position and size across reloads
- **Flexible Config**: TOML-based configuration with CLI overrides
- **Verbose Logging**: Optional detailed output for debugging
## Quick Start
### Installation
```bash
pip install pyqt-preview
```
### Basic Usage
```bash
# Preview a single PyQt application
pyqt-preview run app.py
# Watch a directory for changes
pyqt-preview run app.py --watch src/
# Specify UI files directory
pyqt-preview run app.py --watch . --ui-dir ui/
# Use with PySide instead of PyQt
pyqt-preview run app.py --framework pyside6
```
### Requirements
- Python 3.8+
- PyQt5/PyQt6 or PySide2/PySide6
- watchdog
- For .ui file compilation: `pyuic6`, `pyuic5`, `pyside6-uic`, or `pyside2-uic` (install via PyQt/PySide tools)
## How It Works
PyQt Preview watches your project files for changes, recompiles UI files if needed, and restarts your application automatically. Window geometry and focus can be preserved (see platform notes below).
## Configuration
Create a `.pyqt-preview.toml` file in your project root for custom settings:
```toml
[tool.pyqt-preview]
framework = "pyqt6" # pyqt5, pyqt6, pyside2, pyside6
watch_patterns = ["*.py", "*.ui"]
ignore_patterns = ["__pycache__", "*.pyc"]
ui_compiler = "auto" # auto, pyuic5, pyuic6, pyside2-uic, pyside6-uic
preserve_window_state = true
reload_delay = 0.5 # seconds
verbose = true
```
- **CLI flags always override config file and defaults.**
- See `pyqt-preview --help` for all options.
## Examples
See the `examples/` directory for working applications:
- `simple_app.py`: Basic PyQt6 app
- `simple_pyqt5.py`: PyQt5 compatibility
- `ui_app.py` + `demo.ui`: Qt Designer integration
## CLI Commands
### `run` Command
Start a PyQt application with live preview.
```bash
pyqt-preview run SCRIPT [OPTIONS]
Arguments:
SCRIPT Path to the Python script to run
Options:
--watch PATH Directory to watch for changes [default: .]
--ui-dir PATH Directory containing .ui files
--framework TEXT GUI framework (pyqt5|pyqt6|pyside2|pyside6)
--reload-delay FLOAT Delay before reload in seconds [default: 0.5]
--preserve-state Preserve window position and size
--keep-window-focus Prevent PyQt window from stealing focus on macOS
--config PATH Path to configuration file
--verbose Enable verbose logging
--help Show this message and exit
```
### `init` Command
Initialize a new PyQt Preview configuration file.
```bash
pyqt-preview init [OPTIONS]
Options:
--dir PATH Directory to initialize [default: current directory]
--framework TEXT GUI framework (pyqt5|pyqt6|pyside2|pyside6) [default: pyqt6]
--force Overwrite existing configuration
--help Show this message and exit
```
### `check` Command
Check the current configuration and system requirements.
```bash
pyqt-preview check [OPTIONS]
Options:
--config PATH Path to configuration file
--help Show this message and exit
```
### Global Options
```bash
pyqt-preview --version # Show version and exit
pyqt-preview --help # Show help message
```
## Window Focus Behavior Across Operating Systems
PyQt Preview attempts to minimize disruption to your workflow when reloading the UI. On some operating systems, PyQt/Qt applications may steal window focus from your editor or terminal when reloaded or launched. This behavior and available workarounds vary by platform:
| OS | Focus Stealing Issue | Workarounds/Limitations | Best Practice |
|---------|---------------------|----------------------------------------|------------------------------|
| macOS | Yes | AppleScript, but not 100% reliable | Provide opt-in flag, document|
| Windows | Yes | SetForegroundWindow, AutoHotkey, limited| Avoid, document limitation |
| Linux | Yes | wmctrl/xdotool, fragile | Avoid, respect WM policy |
- **macOS:** Use the `--keep-window-focus` flag (or `keep_window_focus = true` in config) to attempt to restore focus to your previously active app after UI reloads. This uses AppleScript and may not work with all editors or in all scenarios.
- **Windows & Linux:** Focus stealing is restricted by OS policies. There is no reliable, cross-platform way to restore focus to your previous app. Attempts to do so may be blocked or behave inconsistently. PyQt Preview does not support focus restoration on these platforms.
**Flag distinction:**
- `--preserve-state` preserves the window position and size (geometry) across reloads. It does not affect which application is focused.
- `--keep-window-focus` prevents the PyQt window from stealing focus on macOS, restoring focus to your editor or previously active app after reload. It does not affect window geometry.
- These flags are independent and can be used together for best workflow experience.
## Troubleshooting & FAQ
- **UI compiler not found:** Install the appropriate Qt tools (`pyuic6`, `pyuic5`, `pyside6-uic`, `pyside2-uic`).
- **Changes not detected:** Check your file patterns and ensure your editor saves files.
- **Too many reloads:** Increase `reload_delay` and add more ignore patterns.
- **Import errors after reload:** Check your `PYTHONPATH`, use absolute imports, and verify your project structure.
- **Verbose output:** Use `--verbose` for detailed logs.
## Roadmap
### Completed Features
- [x] Live reload for Python files
- [x] Automatic UI file compilation
- [x] Multi-framework support (PyQt5/6, PySide2/6)
- [x] Window state preservation
- [x] TOML configuration system
- [x] CLI with subcommands
### Planned Features
- [ ] Hot widget replacement (soft reload without full restart)
- [ ] Qt Designer integration improvements
- [ ] VS Code extension
- [ ] Plugin system for custom reload behaviors
- [ ] Remote preview capabilities
- [ ] Template system for common PyQt patterns
- [ ] AI/MCP integration (experimental/future)
## Documentation
- **[Quick Start Guide](TUTORIAL.md)**
- **[Complete Tutorial](docs/tutorials/getting-started.md)**
- **[Examples](examples/README.md)**
- **[Architecture Guide](docs/guides/architecture-guide.md)**
## Development & Contributing
### Setup
```bash
# Clone and enter directory
git clone https://github.com/your-username/pyqt-preview.git
cd pyqt-preview
# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in editable mode with dev dependencies
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
pytest --cov=pyqt_preview --cov-report=html
```
### Code Quality
```bash
black src/ tests/
isort src/ tests/
mypy src/
flake8 src/ tests/
```
### Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, code style, and PR process.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Inspired by modern web development live reload tools
- Built with the excellent [watchdog](https://github.com/gorakhargosh/watchdog) library
- Thanks to the PyQt and Qt communities
---
**Made with love for the PyQt community**
Raw data
{
"_id": null,
"home_page": null,
"name": "pyqt-preview",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "development, gui, live-reload, preview, pyqt",
"author": "PyQt Preview Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1a/a2/3893c63a871c1f6867664b0bc23e95d5b80cc5713df9fc0044125107d33f/pyqt_preview-0.2.0.tar.gz",
"platform": null,
"description": "# PyQt Preview - Live Preview Tool for PyQt GUI Development\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/astral-sh/ruff)\n[](https://www.python.org/downloads/)\n[](https://github.com/your-username/pyqt-preview)\n\nPyQt Preview is a development tool for PyQt5/PyQt6/PySide2/PySide6 GUI applications that provides live reloading when editing `.py` or `.ui` files\u2014speeding up your development process. It works out of the box, is highly configurable, and supports advanced workflows for both beginners and professionals.\n\n## Features\n\n- **Live Reload**: Instantly reloads your PyQt application when files change\n- **UI Compilation**: Automatically compiles .ui files to Python code\n- **Multiple Frameworks**: Supports PyQt5, PyQt6, PySide2, and PySide6\n- **Smart Watching**: Configurable file patterns and ignore rules\n- **Zero Configuration**: Works out of the box with sensible defaults\n- **Preserve State**: Maintains window position and size across reloads\n- **Flexible Config**: TOML-based configuration with CLI overrides\n- **Verbose Logging**: Optional detailed output for debugging\n\n## Quick Start\n\n### Installation\n\n```bash\npip install pyqt-preview\n```\n\n### Basic Usage\n\n```bash\n# Preview a single PyQt application\npyqt-preview run app.py\n\n# Watch a directory for changes\npyqt-preview run app.py --watch src/\n\n# Specify UI files directory\npyqt-preview run app.py --watch . --ui-dir ui/\n\n# Use with PySide instead of PyQt\npyqt-preview run app.py --framework pyside6\n```\n\n### Requirements\n- Python 3.8+\n- PyQt5/PyQt6 or PySide2/PySide6\n- watchdog\n- For .ui file compilation: `pyuic6`, `pyuic5`, `pyside6-uic`, or `pyside2-uic` (install via PyQt/PySide tools)\n\n## How It Works\n\nPyQt Preview watches your project files for changes, recompiles UI files if needed, and restarts your application automatically. Window geometry and focus can be preserved (see platform notes below).\n\n## Configuration\n\nCreate a `.pyqt-preview.toml` file in your project root for custom settings:\n\n```toml\n[tool.pyqt-preview]\nframework = \"pyqt6\" # pyqt5, pyqt6, pyside2, pyside6\nwatch_patterns = [\"*.py\", \"*.ui\"]\nignore_patterns = [\"__pycache__\", \"*.pyc\"]\nui_compiler = \"auto\" # auto, pyuic5, pyuic6, pyside2-uic, pyside6-uic\npreserve_window_state = true\nreload_delay = 0.5 # seconds\nverbose = true\n```\n\n- **CLI flags always override config file and defaults.**\n- See `pyqt-preview --help` for all options.\n\n## Examples\n\nSee the `examples/` directory for working applications:\n- `simple_app.py`: Basic PyQt6 app\n- `simple_pyqt5.py`: PyQt5 compatibility\n- `ui_app.py` + `demo.ui`: Qt Designer integration\n\n## CLI Commands\n\n### `run` Command\n\nStart a PyQt application with live preview.\n\n```bash\npyqt-preview run SCRIPT [OPTIONS]\n\nArguments:\n SCRIPT Path to the Python script to run\n\nOptions:\n --watch PATH Directory to watch for changes [default: .]\n --ui-dir PATH Directory containing .ui files\n --framework TEXT GUI framework (pyqt5|pyqt6|pyside2|pyside6)\n --reload-delay FLOAT Delay before reload in seconds [default: 0.5]\n --preserve-state Preserve window position and size\n --keep-window-focus Prevent PyQt window from stealing focus on macOS\n --config PATH Path to configuration file\n --verbose Enable verbose logging\n --help Show this message and exit\n```\n\n### `init` Command\n\nInitialize a new PyQt Preview configuration file.\n\n```bash\npyqt-preview init [OPTIONS]\n\nOptions:\n --dir PATH Directory to initialize [default: current directory]\n --framework TEXT GUI framework (pyqt5|pyqt6|pyside2|pyside6) [default: pyqt6]\n --force Overwrite existing configuration\n --help Show this message and exit\n```\n\n### `check` Command\n\nCheck the current configuration and system requirements.\n\n```bash\npyqt-preview check [OPTIONS]\n\nOptions:\n --config PATH Path to configuration file\n --help Show this message and exit\n```\n\n### Global Options\n\n```bash\npyqt-preview --version # Show version and exit\npyqt-preview --help # Show help message\n```\n\n## Window Focus Behavior Across Operating Systems\n\nPyQt Preview attempts to minimize disruption to your workflow when reloading the UI. On some operating systems, PyQt/Qt applications may steal window focus from your editor or terminal when reloaded or launched. This behavior and available workarounds vary by platform:\n\n| OS | Focus Stealing Issue | Workarounds/Limitations | Best Practice |\n|---------|---------------------|----------------------------------------|------------------------------|\n| macOS | Yes | AppleScript, but not 100% reliable | Provide opt-in flag, document|\n| Windows | Yes | SetForegroundWindow, AutoHotkey, limited| Avoid, document limitation |\n| Linux | Yes | wmctrl/xdotool, fragile | Avoid, respect WM policy |\n\n- **macOS:** Use the `--keep-window-focus` flag (or `keep_window_focus = true` in config) to attempt to restore focus to your previously active app after UI reloads. This uses AppleScript and may not work with all editors or in all scenarios.\n- **Windows & Linux:** Focus stealing is restricted by OS policies. There is no reliable, cross-platform way to restore focus to your previous app. Attempts to do so may be blocked or behave inconsistently. PyQt Preview does not support focus restoration on these platforms.\n\n**Flag distinction:**\n- `--preserve-state` preserves the window position and size (geometry) across reloads. It does not affect which application is focused.\n- `--keep-window-focus` prevents the PyQt window from stealing focus on macOS, restoring focus to your editor or previously active app after reload. It does not affect window geometry.\n- These flags are independent and can be used together for best workflow experience.\n\n## Troubleshooting & FAQ\n\n- **UI compiler not found:** Install the appropriate Qt tools (`pyuic6`, `pyuic5`, `pyside6-uic`, `pyside2-uic`).\n- **Changes not detected:** Check your file patterns and ensure your editor saves files.\n- **Too many reloads:** Increase `reload_delay` and add more ignore patterns.\n- **Import errors after reload:** Check your `PYTHONPATH`, use absolute imports, and verify your project structure.\n- **Verbose output:** Use `--verbose` for detailed logs.\n\n## Roadmap\n\n### Completed Features\n- [x] Live reload for Python files\n- [x] Automatic UI file compilation\n- [x] Multi-framework support (PyQt5/6, PySide2/6)\n- [x] Window state preservation\n- [x] TOML configuration system\n- [x] CLI with subcommands\n\n### Planned Features\n- [ ] Hot widget replacement (soft reload without full restart)\n- [ ] Qt Designer integration improvements\n- [ ] VS Code extension\n- [ ] Plugin system for custom reload behaviors\n- [ ] Remote preview capabilities\n- [ ] Template system for common PyQt patterns\n- [ ] AI/MCP integration (experimental/future)\n\n## Documentation\n\n- **[Quick Start Guide](TUTORIAL.md)**\n- **[Complete Tutorial](docs/tutorials/getting-started.md)**\n- **[Examples](examples/README.md)**\n- **[Architecture Guide](docs/guides/architecture-guide.md)**\n\n## Development & Contributing\n\n### Setup\n\n```bash\n# Clone and enter directory\ngit clone https://github.com/your-username/pyqt-preview.git\ncd pyqt-preview\n\n# Create virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in editable mode with dev dependencies\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\npytest --cov=pyqt_preview --cov-report=html\n```\n\n### Code Quality\n\n```bash\nblack src/ tests/\nisort src/ tests/\nmypy src/\nflake8 src/ tests/\n```\n\n### Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, code style, and PR process.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by modern web development live reload tools\n- Built with the excellent [watchdog](https://github.com/gorakhargosh/watchdog) library\n- Thanks to the PyQt and Qt communities\n\n---\n\n**Made with love for the PyQt community**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Live preview tool for PyQt GUI development",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/Reynear/pyqt-preview/issues",
"Documentation": "https://github.com/Reynear/pyqt-preview#readme",
"Homepage": "https://github.com/Reynear/pyqt-preview",
"Repository": "https://github.com/Reynear/pyqt-preview"
},
"split_keywords": [
"development",
" gui",
" live-reload",
" preview",
" pyqt"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bf6b327a84555cb18fcd55939c3007ec2c049d79fe52187baf344a03d779dffc",
"md5": "fc7192d27e200eae8922bd4d8fc65adb",
"sha256": "83a1d75e2f48f76a2318a3010d37ffc61d11679e5d503253d53ad108c921bc06"
},
"downloads": -1,
"filename": "pyqt_preview-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc7192d27e200eae8922bd4d8fc65adb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 19079,
"upload_time": "2025-07-14T05:29:28",
"upload_time_iso_8601": "2025-07-14T05:29:28.010779Z",
"url": "https://files.pythonhosted.org/packages/bf/6b/327a84555cb18fcd55939c3007ec2c049d79fe52187baf344a03d779dffc/pyqt_preview-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1aa23893c63a871c1f6867664b0bc23e95d5b80cc5713df9fc0044125107d33f",
"md5": "4701b636bad4247fe962010592cefbed",
"sha256": "1b5bc736bdd5179d469d2e03619ea118884ee30aa6e7f40c8024bb8c9fccb885"
},
"downloads": -1,
"filename": "pyqt_preview-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "4701b636bad4247fe962010592cefbed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 38808,
"upload_time": "2025-07-14T05:29:29",
"upload_time_iso_8601": "2025-07-14T05:29:29.409063Z",
"url": "https://files.pythonhosted.org/packages/1a/a2/3893c63a871c1f6867664b0bc23e95d5b80cc5713df9fc0044125107d33f/pyqt_preview-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 05:29:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Reynear",
"github_project": "pyqt-preview",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyqt-preview"
}
JSON
