winipyside
A utilities package for PySide6
Overview
Winipyside is a production-ready PySide6 utilities package that provides reusable, well-tested components for building Qt desktop applications. It features encrypted file I/O with AES-GCM, a full-featured media player with encrypted video playback support, an embedded web browser with cookie management, toast notifications, and a modular page-based UI framework.
Key Highlights
- 🔐 Encrypted File I/O: Transparent AES-GCM encryption for files and media playback
- 🎬 Media Player: Full-featured player with encrypted video support, speed control, and fullscreen mode
- 🌐 Web Browser: Embedded browser with cookie management and Qt/Python cookie conversion
- 🔔 Notifications: Toast notification system with auto-positioning and smart text truncation
- 🏗️ UI Framework: Modular page-based architecture with lifecycle hooks and navigation
- ✅ Type Safe: 100% type annotated with strict mypy checking
- 🧪 Well Tested: Comprehensive test suite with pytest and pytest-qt
- 🚀 CI/CD Ready: Production-ready workflows for headless environments
Features
🔐 Encrypted File I/O
Transparent encryption/decryption for files and media with AES-GCM:
- Chunked encryption for efficient streaming (64KB chunks)
- Random access support with position mapping
- Zero-copy decryption for media playback
- Authenticated encryption with nonces and tags
🎬 Media Player
Full-featured video player with advanced controls:
- Play/pause, speed control (0.2x-5x), volume slider
- Seekable progress bar with throttled updates
- Fullscreen mode with automatic UI hiding
- Native encrypted video playback without temporary files
- Position resumption and smart resource management
🌐 Web Browser
Embedded Chromium-based browser:
- Navigation controls (back, forward, address bar)
- Automatic cookie tracking
- QNetworkCookie ↔ http.cookiejar.Cookie conversion
- Domain-based cookie retrieval
🏗️ UI Framework
Modular architecture for building complex applications:
- Lifecycle hooks:
base_setup()→pre_setup()→setup()→post_setup() - Page-based navigation with QStackedWidget
- Dynamic subclass discovery
- SVG icon support
- Automatic display name generation
Installation
Requirements
- Python 3.12 or 3.13
- PySide6
- System dependencies (Linux only):
libegl1libpulse0
Install from PyPI
pip install winipyside
Install from Source
git clone https://github.com/Winipedia/winipyside.git
cd winipyside
uv sync
Linux System Dependencies
sudo apt-get update
sudo apt-get install -y libegl1 libpulse0
Quick Start
Basic Application
from PySide6.QtWidgets import QApplication
from winipyside.src.ui.windows.base.base import Base as BaseWindow
from winipyside.src.ui.pages.browser import Browser
class MyApp(BaseWindow):
@classmethod
def get_all_page_classes(cls):
return [Browser]
@classmethod
def get_start_page_cls(cls):
return Browser
def pre_setup(self) -> None:
pass
def setup(self) -> None:
self.resize(1280, 720)
def post_setup(self) -> None:
pass
if __name__ == "__main__":
app = QApplication([])
window = MyApp()
window.show()
app.exec()
Encrypted Video Playback
from pathlib import Path
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from PySide6.QtCore import QUrl, QIODevice
from PySide6.QtMultimedia import QMediaPlayer, QAudioOutput
from winipyside.src.core.py_qiodevice import EncryptedPyQFile
# Generate encryption key
key = AESGCM.generate_key(bit_length=256)
aes_gcm = AESGCM(key)
# Play encrypted video
video_path = Path("encrypted_video.mp4")
encrypted_file = EncryptedPyQFile(video_path, aes_gcm)
encrypted_file.open(QIODevice.OpenModeFlag.ReadOnly)
player = QMediaPlayer()
player.setAudioOutput(QAudioOutput())
player.setSourceDevice(encrypted_file, QUrl.fromLocalFile(str(video_path)))
player.play()
Toast Notifications
from winipyside.src.ui.widgets.notification import Notification
from pyqttoast import ToastIcon
Notification(
title="Success",
text="Operation completed successfully!",
icon=ToastIcon.SUCCESS,
duration=5000,
)
Documentation
Comprehensive documentation is available in the docs/ directory:
- Core Package - Encrypted file I/O and QIODevice wrappers
- UI Base - Foundation framework and lifecycle management
- UI Widgets - Reusable widgets (Browser, MediaPlayer, Notifications)
- UI Pages - Page components for navigation
- UI Windows - Main window framework
- API Reference - Complete API documentation
Architecture
winipyside/
├── src/
│ ├── core/ # Encrypted file I/O
│ └── ui/
│ ├── base/ # Base classes and lifecycle
│ ├── widgets/ # Reusable widgets
│ ├── pages/ # Page components
│ └── windows/ # Window framework
├── resources/ # SVG icons and static resources
└── dev/
├── builders/ # Build utilities
├── cli/ # CLI commands
├── configs/ # CI/CD configuration
└── tests/ # Test fixtures
Development
Setup Development Environment
# Clone the repository
git clone https://github.com/Winipedia/winipyside.git
cd winipyside
# Install dependencies with uv
uv sync
# Install pre-commit hooks
uv run pre-commit install
# get familiar with pyrig
Contributing
Contributions are welcome! Please follow these guidelines:
- Fork the repository and create a feature branch
- Write tests for new functionality
- Ensure all tests pass and code quality checks succeed
- Update documentation as needed
- Submit a pull request with a clear description
Code Standards
- Follow Google docstring convention
- Maintain 100% type coverage
- Write comprehensive tests (aim for >90% coverage)
- Use descriptive variable names
- Keep functions focused and small
License
This project is licensed under the MIT License, see the LICENSE file for details.
Acknowledgments
- Built with Pyrig - Python project scaffolding framework
- Uses PySide6 - Qt for Python
- Toast notifications powered by pyqttoast
Support
- Documentation: docs/
- Issues: GitHub Issues
- Discussions: GitHub Discussions
1 maintainer
Release files for winipyside 4.14.58
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| winipyside-4.14.58.tar.gz | 29.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| winipyside-4.14.58-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 71.3 kB
Release files / winipyside-4.14.58.tar.gz
| Download URL | winipyside-4.14.58.tar.gz |
|---|---|
| Size | 29.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
59e114143a6938114e484f26a6c131f387b20ba3c5d82b8a872998b3744e33fe
|
|
BLAKE2b-256 checksum How to use checksums |
669d5234157d10f25e29be4c0d2570321cd4dff0470f273c42a0b2365b5c0dae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / winipyside-4.14.58-py3-none-any.whl
| Download URL | winipyside-4.14.58-py3-none-any.whl |
|---|---|
| Size | 41.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4819ba492d909b75c033c3217a64fed59f4c15bddc25fb637dde75bbdbdd8520
|
|
BLAKE2b-256 checksum How to use checksums |
b260b663c283c3d0553c40e6b9447e03f3bfbb105dd2b7f8c8b46ebebaf74075
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
