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)

⌨️ Input Widgets (6)

🏷️ Label Widgets (4)

🔧 Miscellaneous Widgets (9)

📦 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. 🎨