PySide References

A collection of reusable PySide6 widgets with comprehensive examples and reference implementations. Each widget is presented in Jupyter notebooks with jupytext synchronization for easy exploration and modification.

Initial author GProtoZeroW Sept 2025

Acknowledgments

This project's documentation and code comments were refined with the assistance of Claude Opus 4 (Anthropic) for proofreading, spelling corrections, and clarity improvements. The AI assistant helped ensure consistent code, code formatting, proper grammar, and clear technical writing throughout the codebase.

Overview

This project provides well-documented, production-ready PySide6 widgets that can be used as:

• Drop-in components for your applications
• Reference implementations for creating custom widgets
• Learning resources for PySide6 development patterns

Requirements

• Python 3.8+
• PySide6
• attrs
• loguru
• jupytext (for notebook synchronization)
• jupyter or jupyterlab (for running notebooks)

Installation

Install directly from pyproject.toml:

pip install .

Project Structure (20250918)

pyside_references/
├── __init__.py                           # Project-wide loguru setup
├── widget_utilities.py                   # Base utilities for import
├── widget_utilities_DevNB.ipynb/.py       # Base class demo notebook
└── file_folder_widgets_collection/
    └── file_folder_selector_widget_DevNB.ipynb/.py  # File/folder selector widget

Usage

For Development/Learning

1. Open the .ipynb files in Jupyter to see live examples
2. Modify and experiment with the widgets interactively
3. Use jupytext to keep .py and .ipynb files synchronized

For Production

Import the widgets directly:

from pyside_references import setup_project_logging
from pyside_references.widget_utilities import WidgetUtilities
from pyside_references.file_folder_widget_collection.file_folder_selector_widget import (
    FileFolderSelectorQWidget, 
    FileFolderPathsODM
)

# Setup logging (optional)
setup_project_logging()

# Use the widgets in your application
widget = FileFolderSelectorQWidget()

Jupytext Synchronization

This project uses jupytext to maintain both .py and .ipynb versions of notebooks:

# Sync all notebooks
jupytext --sync **/*.py

# Watch for changes and auto-sync
jupytext --sync **/*.py --pipe-fmt py:percent

Naming Convention Rationale

This project uses Qt (A C++ Native project)-style naming (e.g., folder_QLineEdit, select_QPushButton) rather than strict Python PEP8. Here's why:

1. Qt Reality: PySide6/PyQt are wrappers around a C++ codebase that already uses its own conventions. Fighting this creates unnecessary friction.

2. Documentation Alignment: When you see QPushButton in your code, you can directly search the Qt/PySide docs without mental translation.

3. Self-Documenting Code:

   • folder_QLineEdit immediately tells you: it's for folder input AND it's a QLineEdit widget
   • QLineEdit_editingFinished_action clearly shows: it's a slot handling the editingFinished signal from a QLineEdit
   • select_QPushButton_clicked_action indicates: it handles the clicked signal from select QPushButton

4. Signal/Slot Clarity: Slot naming follows the pattern [widget]_[signal]_action, making signal-slot connections self-documenting. When debugging, you instantly know which widget and signal triggered a slot.

5. PEP8 Wisdom: PEP8 itself states: "A foolish consistency is the hobgoblin of little minds" and explicitly encourages breaking conventions when it improves readability.

The goal is practical, maintainable code that works well with the Qt ecosystem, not style guide purity.

Widget Collection

Currently Available

1. FileFolderSelectorQWidget - A unified file and folder selection widget with:

   • Synchronized path management via attrs-based ODM
   • Both text entry and dialog-based selection
   • Automatic path validation and normalization

2. WidgetUtilities - Base class providing:

   • Standard GUI initialization pattern
   • Debug utilities for widget inspection
   • Future pyautogui automation support

Coming Soon

• Matplotlib integration widgets
• Pandas DataFrame viewers and editors
• Plot configuration widgets
• Data transformation widgets

Contributing

This is a personal reference collection, but suggestions and improvements are welcome. The focus is on practical, working code that serves as good examples for real-world usage.

License

[Your chosen license]

Notes

• The capture_widget_info() method in WidgetUtilities is designed for future pyautogui automation
• All widgets follow a consistent initialization pattern for easy customization
• Validators in ODM classes are intentionally commented out for easy subclassing