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.119

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.119
File	Size	Uploaded
winipyside-4.14.119.tar.gz	32.3 kB	Oct 9, 2026	Details

Built distribution (wheel)

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

Total release size: 74.1 kB

Release files / winipyside-4.14.119.tar.gz

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

Download URL	winipyside-4.14.119-py3-none-any.whl
Size	41.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1b52c4a567ef02c8699e4c38b1e333884388b359037d2dff81b57ace1b11839e`
BLAKE2b-256 checksum How to use checksums	`6e4d23a1f8cc8dc627215ac65c074b0bf9ed21b266518267678e51b4a127e77f`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","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}`