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):
- libegl1
- libpulse0

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

Metadata

Release files for winipyside 4.14.106

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for winipyside 4.14.106
File	Size	Uploaded
winipyside-4.14.106.tar.gz	29.9 kB	Oct 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for winipyside 4.14.106
File	Interpreter	ABI	Platform	Reset
winipyside-4.14.106-py3-none-any.whl 41.8 kB Oct 5, 2026	Python 3	none	any	Details

Total release size: 71.6 kB

Release files / winipyside-4.14.106.tar.gz

Download URL	winipyside-4.14.106.tar.gz
Size	29.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`53b2cc355c9d120a7f1f6d502430a7b027179a5ed93ec3c854a264a055f9f1b3`
BLAKE2b-256 checksum How to use checksums	`9cba9584c85d2616964cf2bf9a176271a0aa1112301cc1de03af5272a754633f`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","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.106-py3-none-any.whl

Download URL	winipyside-4.14.106-py3-none-any.whl
Size	41.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c4cc540b9d705e1b54b4b2a92595b70e69acf1760180c79de3608a3b24ed11ec`
BLAKE2b-256 checksum How to use checksums	`ecd7e19acad8644549b4b459215b4d5adb68341c3b63d931e2381d760975e412`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","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}`