ezqt-widgets 2.7.2

A collection of custom and reusable Qt widgets for PySide6. Provides advanced, reusable, and stylish graphical components to facilitate the development of modern and user-friendly interfaces.

EzQt-Widgets

EzQt-Widgets is a modern collection of custom and reusable Qt widgets for PySide6 featuring advanced animated components, full type hints, and a simple API suitable for professional desktop applications.

📦 Installation

uv add ezqt-widgets

Or with pip:

pip install ezqt-widgets

Or from source:

git clone https://github.com/neuraaak/ezqt-widgets.git
cd ezqt-widgets && uv sync --all-extras

🚀 Quick Start

from ezqt_widgets import DateButton, IconButton, ToggleSwitch, AutoCompleteInput
from PySide6.QtWidgets import QApplication, QVBoxLayout, QWidget

app = QApplication([])
window = QWidget()
layout = QVBoxLayout()

# Create widgets
date_button = DateButton(placeholder="Select a date")
icon_button = IconButton(icon="path/to/icon.png", text="Click me")
toggle = ToggleSwitch(checked=True)
auto_input = AutoCompleteInput(completions=["Option 1", "Option 2", "Option 3"])

# Connect signals
date_button.dateChanged.connect(lambda date: print(f"Date: {date}"))
icon_button.clicked.connect(lambda: print("Button clicked"))
toggle.toggled.connect(lambda checked: print(f"Toggle: {checked}"))

# Add to layout
layout.addWidget(date_button)
layout.addWidget(icon_button)
layout.addWidget(toggle)
layout.addWidget(auto_input)

window.setLayout(layout)
window.show()
app.exec()

🎯 Key Features

• ✅ PySide6 Compatible: All widgets based on PySide6
• ✅ Full Type Hints: Complete typing support for IDEs and linters
• ✅ Qt Signals: Native integration with Qt signal system
• ✅ QSS Styling: Complete Qt stylesheet support
• ✅ Smooth Animations: Configurable animations with easing curves
• ✅ Accessibility: Accessibility features support
• ✅ Comprehensive Tests: Complete test suite (~211 tests, ~80% coverage)
• ✅ CLI Tools: Command-line interface for examples and testing

📚 Documentation

Full documentation is available online: neuraaak.github.io/ezqt-widgets

• 📖 Getting Started – Installation and first steps
• 🎯 API Reference – Complete widget reference (auto-generated)
• 🎨 QSS Style Guide – QSS customization and best practices
• 💡 Examples – Usage examples and demonstrations
• 🖥️ CLI – Command-line interface guide
• 🧪 Testing – Test suite documentation
• 🔧 Development – Environment setup and contribution

🧪 Testing

Comprehensive test suite with 211+ test cases covering all widgets.

# Install dev dependencies
uv sync --all-extras

# Run all tests
uv run pytest tests/

# Run specific test types
uv run python tests/run_tests.py --type unit

# With coverage
uv run python tests/run_tests.py --coverage

# Using CLI
ezqt test --unit
ezqt test --coverage

See the Testing Guide for complete details.

🛠️ Development Setup

For contributors and developers:

# Clone and install in development mode
git clone https://github.com/neuraaak/ezqt-widgets.git
cd ezqt-widgets
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

# Verify CLI installation
ezqt --version
ezqt info

See the Development Guide for detailed setup instructions.

🎨 Available Widgets

🎛️ Button Widgets (4)

Widget	Description
DateButton	Date picker button with integrated calendar
DatePickerDialog	Modal calendar dialog for date selection
IconButton	Button with icon support and optional text
LoaderButton	Button with integrated loading animation

⌨️ Input Widgets (6)

Widget	Description
AutoCompleteInput	Text field with autocompletion
FilePickerInput	Field with folder button opening a file/directory dialog
PasswordInput	Password field with strength bar and visibility toggle
SearchInput	Search field with history management
SpinBoxInput	Numeric spin box with − and + buttons
TabReplaceTextEdit	Text editor with tab replacement

🏷️ Label Widgets (4)

Widget	Description
ClickableTagLabel	Clickable tag with toggle state
FramedLabel	Framed label for advanced styling
HoverLabel	Label with hover icon display
IndicatorLabel	Status indicator with colored LED

🔧 Miscellaneous Widgets (9)

Widget	Description
CircularTimer	Animated circular timer
CollapsibleSection	Accordion-style section with expand/collapse animation
DraggableItem	Draggable list item component
DraggableList	List with draggable and reorderable items
NotificationBanner	Animated slide-down banner with INFO/WARNING/ERROR/SUCCESS levels
OptionSelector	Option selector with animated selector
ThemeIcon	QIcon that adapts color to the active dark/light theme
ToggleIcon	Toggleable icon (open/closed states)
ToggleSwitch	Modern toggle switch with animation

📦 Dependencies

• PySide6>=6.7.3,<7.0.0 – Qt for Python framework
• click>=8.2.1 – Command-line interface toolkit
• rich>=13.0.0 – Terminal formatting and output
• PyYAML>=6.0 – YAML configuration support
• typing_extensions>=4.0.0 – Extended typing support

🔧 Quick API Reference

from ezqt_widgets import (
    # Button widgets
    DateButton, DatePickerDialog, IconButton, LoaderButton,
    # Input widgets
    AutoCompleteInput, FilePickerInput, PasswordInput,
    SearchInput, SpinBoxInput, TabReplaceTextEdit,
    # Label widgets
    ClickableTagLabel, FramedLabel, HoverLabel, IndicatorLabel,
    # Misc widgets
    CircularTimer, CollapsibleSection, DraggableItem, DraggableList,
    NotificationBanner, OptionSelector, ThemeIcon, ToggleIcon, ToggleSwitch,
)

# Button examples
date_btn = DateButton(placeholder="Select date")
icon_btn = IconButton(icon="path/to/icon.png", text="Click")
loader_btn = LoaderButton(loading_text="Loading...")

# Input examples
auto_input = AutoCompleteInput(completions=["A", "B", "C"])
search_input = SearchInput(max_history=20)
spin_box = SpinBoxInput(minimum=0, maximum=100, value=50)

# Misc examples
timer = CircularTimer(duration=5000, loop=True)
switch = ToggleSwitch(checked=True)
selector = OptionSelector(options=["Small", "Medium", "Large"])

📄 License

MIT License – See LICENSE file for details.

🔗 Links

• Repository: https://github.com/neuraaak/ezqt-widgets
• Issues: GitHub Issues
• Documentation: neuraaak.github.io/ezqt-widgets
• PyPI: pypi.org/project/ezqt-widgets
• Changelog: CHANGELOG.md

---

EzQt-Widgets – Modern, typed, and beautiful Qt widgets for Python. 🎨