vultus-serpentis 0.1.0

Modern Tkinter utilities for TTK and TTKBootstrap applications

Vultus Serpentis

Modern Tkinter utilities for TTK and TTKBootstrap applications

Vultus Serpentis is a suite of integrated utilities for building modern Python Tkinter applications with support for both plain TTK and TTKBootstrap. It provides a clean, modular architecture for common GUI patterns including actions, validation, undo/redo, and event-driven communication.

Features

• 🎯 Actions: Swing-like Action class for centralizing UI component logic and state
• ✅ Validation: Flexible input validation framework with configurable feedback strategies
• ↩️ Commands: Robust undo/redo framework based on the command pattern
• 📡 Event Bus: Synchronous event bus for decoupled component communication
• 🎨 TTK/TTKBootstrap Support: Works with plain TTK, with enhanced features for TTKBootstrap
• 🧪 Well-Tested: 90%+ test coverage with comprehensive test suite
• 📦 Type-Safe: Full type hints with mypy strict mode compliance

Installation

Basic Installation (TTK only)

pip install vultus-serpentis

With TTKBootstrap Support

pip install vultus-serpentis[bootstrap]

Development Installation

pip install vultus-serpentis[dev]

Quick Start

Actions

from vultus_serpentis import Action
import tkinter as tk

def save_file():
    print("File saved!")

root = tk.Tk()
save_action = Action("Save", save_file, tooltip_text="Save the current file")

# Bind to multiple widgets
button = tk.Button(root)
save_action.bind_widget(button)

# Control state centrally
save_action.enabled = False  # Disables all bound widgets

Validation

from vultus_serpentis import ValidationBinder, RequiredValidator
import tkinter as tk

root = tk.Tk()
var = tk.StringVar()
entry = tk.Entry(root, textvariable=var)

# Validate with automatic feedback
with ValidationBinder(entry, var, [RequiredValidator()], debounce_ms=300):
    root.mainloop()

Commands (Undo/Redo)

from vultus_serpentis import Command, CommandManager

class IncrementCommand(Command):
    def __init__(self, counter):
        self.counter = counter
        self.old_value = counter.value
    
    def execute(self):
        self.counter.value += 1
        return True
    
    def undo(self):
        self.counter.value = self.old_value
        return True

manager = CommandManager.default()
manager.execute(IncrementCommand(my_counter))
manager.undo()  # Reverts the increment
manager.redo()  # Re-applies the increment

Event Bus

from vultus_serpentis import EventBus, Event
from dataclasses import dataclass

@dataclass
class FileOpenedEvent(Event):
    filename: str

bus = EventBus.default()

def on_file_opened(event):
    print(f"File opened: {event.filename}")

bus.subscribe(FileOpenedEvent, on_file_opened)
bus.publish(FileOpenedEvent(filename="document.txt"))

Architecture

Vultus Serpentis is designed with modularity in mind. Each module can be used independently or integrated together:

• common: Shared base classes (Observable, VultusException)
• events: Event bus for pub/sub messaging
• commands: Command pattern implementation for undo/redo
• actions: Action abstraction for UI components
• validation: Input validation with feedback strategies

TTK vs TTKBootstrap

The library works with plain TTK by default, with enhanced features when TTKBootstrap is available:

Feature	Plain TTK	TTKBootstrap
Core functionality	✅ Full support	✅ Full support
Validation feedback	Basic (bg/fg colors)	Enhanced (bootstyle, toast)
Action styling	Standard	Bootstyle-aware

Development

Running Tests

pytest

Type Checking

mypy vultus_serpentis

Code Quality

pylint vultus_serpentis

Coverage Report

pytest --cov=vultus_serpentis --cov-report=html

Requirements

• Python 3.9+
• tksimpletooltip >= 2.6.0
• ttkbootstrap >= 1.10.0 (optional, for enhanced features)

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please ensure:

1. All tests pass (pytest)
2. Code is type-checked (mypy --strict)
3. Code follows style guide (pylint)
4. Test coverage remains above 90%

Roadmap

• Phase 1: Foundation (Observable, VultusException)
• Phase 2: Event Bus implementation
• Phase 3: Command Framework
• Phase 4: Actions Module
• Phase 5: Validation Module
• Phase 6: Integration & Examples
• Phase 7: Documentation & PyPI Release

Examples

See the examples/ directory for complete working examples:

• demo_basic_ttk.py: Using Vultus Serpentis with plain TTK
• demo_bootstrap_enhanced.py: Enhanced features with TTKBootstrap
• demo_full_integration.py: All modules working together

Support

For issues, questions, or contributions, please visit the GitHub repository.