# Vultus Serpentis
**Modern Tkinter utilities for TTK and TTKBootstrap applications**
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
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)
```bash
pip install vultus-serpentis
```
### With TTKBootstrap Support
```bash
pip install vultus-serpentis[bootstrap]
```
### Development Installation
```bash
pip install vultus-serpentis[dev]
```
## Quick Start
### Actions
```python
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
```python
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)
```python
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
```python
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
```bash
pytest
```
### Type Checking
```bash
mypy vultus_serpentis
```
### Code Quality
```bash
pylint vultus_serpentis
```
### Coverage Report
```bash
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
- [x] 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](https://github.com/yourusername/vultus-serpentis).
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/vultus-serpentis",
"name": "vultus-serpentis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "gui framework observable event-bus commands validation actions tkinter mvc",
"author": "Vultus Serpentis Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cb/27/3925459e69e2b8ad9132619c4eb46ed5d8788a827bfe7b694d39a09ff0bc/vultus-serpentis-0.1.0.tar.gz",
"platform": null,
"description": "# Vultus Serpentis\r\n\r\n**Modern Tkinter utilities for TTK and TTKBootstrap applications**\r\n\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nVultus 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.\r\n\r\n## Features\r\n\r\n- \ud83c\udfaf **Actions**: Swing-like Action class for centralizing UI component logic and state\r\n- \u2705 **Validation**: Flexible input validation framework with configurable feedback strategies\r\n- \u21a9\ufe0f **Commands**: Robust undo/redo framework based on the command pattern\r\n- \ud83d\udce1 **Event Bus**: Synchronous event bus for decoupled component communication\r\n- \ud83c\udfa8 **TTK/TTKBootstrap Support**: Works with plain TTK, with enhanced features for TTKBootstrap\r\n- \ud83e\uddea **Well-Tested**: 90%+ test coverage with comprehensive test suite\r\n- \ud83d\udce6 **Type-Safe**: Full type hints with mypy strict mode compliance\r\n\r\n## Installation\r\n\r\n### Basic Installation (TTK only)\r\n\r\n```bash\r\npip install vultus-serpentis\r\n```\r\n\r\n### With TTKBootstrap Support\r\n\r\n```bash\r\npip install vultus-serpentis[bootstrap]\r\n```\r\n\r\n### Development Installation\r\n\r\n```bash\r\npip install vultus-serpentis[dev]\r\n```\r\n\r\n## Quick Start\r\n\r\n### Actions\r\n\r\n```python\r\nfrom vultus_serpentis import Action\r\nimport tkinter as tk\r\n\r\ndef save_file():\r\n print(\"File saved!\")\r\n\r\nroot = tk.Tk()\r\nsave_action = Action(\"Save\", save_file, tooltip_text=\"Save the current file\")\r\n\r\n# Bind to multiple widgets\r\nbutton = tk.Button(root)\r\nsave_action.bind_widget(button)\r\n\r\n# Control state centrally\r\nsave_action.enabled = False # Disables all bound widgets\r\n```\r\n\r\n### Validation\r\n\r\n```python\r\nfrom vultus_serpentis import ValidationBinder, RequiredValidator\r\nimport tkinter as tk\r\n\r\nroot = tk.Tk()\r\nvar = tk.StringVar()\r\nentry = tk.Entry(root, textvariable=var)\r\n\r\n# Validate with automatic feedback\r\nwith ValidationBinder(entry, var, [RequiredValidator()], debounce_ms=300):\r\n root.mainloop()\r\n```\r\n\r\n### Commands (Undo/Redo)\r\n\r\n```python\r\nfrom vultus_serpentis import Command, CommandManager\r\n\r\nclass IncrementCommand(Command):\r\n def __init__(self, counter):\r\n self.counter = counter\r\n self.old_value = counter.value\r\n \r\n def execute(self):\r\n self.counter.value += 1\r\n return True\r\n \r\n def undo(self):\r\n self.counter.value = self.old_value\r\n return True\r\n\r\nmanager = CommandManager.default()\r\nmanager.execute(IncrementCommand(my_counter))\r\nmanager.undo() # Reverts the increment\r\nmanager.redo() # Re-applies the increment\r\n```\r\n\r\n### Event Bus\r\n\r\n```python\r\nfrom vultus_serpentis import EventBus, Event\r\nfrom dataclasses import dataclass\r\n\r\n@dataclass\r\nclass FileOpenedEvent(Event):\r\n filename: str\r\n\r\nbus = EventBus.default()\r\n\r\ndef on_file_opened(event):\r\n print(f\"File opened: {event.filename}\")\r\n\r\nbus.subscribe(FileOpenedEvent, on_file_opened)\r\nbus.publish(FileOpenedEvent(filename=\"document.txt\"))\r\n```\r\n\r\n## Architecture\r\n\r\nVultus Serpentis is designed with modularity in mind. Each module can be used independently or integrated together:\r\n\r\n- **`common`**: Shared base classes (Observable, VultusException)\r\n- **`events`**: Event bus for pub/sub messaging\r\n- **`commands`**: Command pattern implementation for undo/redo\r\n- **`actions`**: Action abstraction for UI components\r\n- **`validation`**: Input validation with feedback strategies\r\n\r\n### TTK vs TTKBootstrap\r\n\r\nThe library works with plain TTK by default, with enhanced features when TTKBootstrap is available:\r\n\r\n| Feature | Plain TTK | TTKBootstrap |\r\n|---------|-----------|--------------|\r\n| Core functionality | \u2705 Full support | \u2705 Full support |\r\n| Validation feedback | Basic (bg/fg colors) | Enhanced (bootstyle, toast) |\r\n| Action styling | Standard | Bootstyle-aware |\r\n\r\n## Development\r\n\r\n### Running Tests\r\n\r\n```bash\r\npytest\r\n```\r\n\r\n### Type Checking\r\n\r\n```bash\r\nmypy vultus_serpentis\r\n```\r\n\r\n### Code Quality\r\n\r\n```bash\r\npylint vultus_serpentis\r\n```\r\n\r\n### Coverage Report\r\n\r\n```bash\r\npytest --cov=vultus_serpentis --cov-report=html\r\n```\r\n\r\n## Requirements\r\n\r\n- Python 3.9+\r\n- tksimpletooltip >= 2.6.0\r\n- ttkbootstrap >= 1.10.0 (optional, for enhanced features)\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please ensure:\r\n\r\n1. All tests pass (`pytest`)\r\n2. Code is type-checked (`mypy --strict`)\r\n3. Code follows style guide (`pylint`)\r\n4. Test coverage remains above 90%\r\n\r\n## Roadmap\r\n\r\n- [x] Phase 1: Foundation (Observable, VultusException)\r\n- [ ] Phase 2: Event Bus implementation\r\n- [ ] Phase 3: Command Framework\r\n- [ ] Phase 4: Actions Module\r\n- [ ] Phase 5: Validation Module\r\n- [ ] Phase 6: Integration & Examples\r\n- [ ] Phase 7: Documentation & PyPI Release\r\n\r\n## Examples\r\n\r\nSee the `examples/` directory for complete working examples:\r\n\r\n- `demo_basic_ttk.py`: Using Vultus Serpentis with plain TTK\r\n- `demo_bootstrap_enhanced.py`: Enhanced features with TTKBootstrap\r\n- `demo_full_integration.py`: All modules working together\r\n\r\n## Support\r\n\r\nFor issues, questions, or contributions, please visit the [GitHub repository](https://github.com/yourusername/vultus-serpentis).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Modern Tkinter utilities for TTK and TTKBootstrap applications",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/yourusername/vultus-serpentis/blob/main/README.md",
"Homepage": "https://github.com/yourusername/vultus-serpentis",
"Repository": "https://github.com/yourusername/vultus-serpentis"
},
"split_keywords": [
"gui",
"framework",
"observable",
"event-bus",
"commands",
"validation",
"actions",
"tkinter",
"mvc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "119e5e2525a3f0530272bba8b0f8fbe3b13dd5be367b329435caa57a21dd9451",
"md5": "4200b1a6281a884b5133ecb72dc8d405",
"sha256": "2b11c257eccf543a50081d5f0dac88cbe6a84df7136871688cf86600e87c0a9b"
},
"downloads": -1,
"filename": "vultus_serpentis-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4200b1a6281a884b5133ecb72dc8d405",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17916,
"upload_time": "2025-10-07T16:33:05",
"upload_time_iso_8601": "2025-10-07T16:33:05.286080Z",
"url": "https://files.pythonhosted.org/packages/11/9e/5e2525a3f0530272bba8b0f8fbe3b13dd5be367b329435caa57a21dd9451/vultus_serpentis-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb273925459e69e2b8ad9132619c4eb46ed5d8788a827bfe7b694d39a09ff0bc",
"md5": "eea4f3e71f60afc1d41305f5c8a532f3",
"sha256": "5a729a8dc2362a74ab55cbe19631f79a0f5dd80dca0baefa260d032b9bad92cf"
},
"downloads": -1,
"filename": "vultus-serpentis-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "eea4f3e71f60afc1d41305f5c8a532f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 30268,
"upload_time": "2025-10-07T16:33:06",
"upload_time_iso_8601": "2025-10-07T16:33:06.582707Z",
"url": "https://files.pythonhosted.org/packages/cb/27/3925459e69e2b8ad9132619c4eb46ed5d8788a827bfe7b694d39a09ff0bc/vultus-serpentis-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 16:33:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "vultus-serpentis",
"github_not_found": true,
"lcname": "vultus-serpentis"
}
JSON
