https://github.com/israel-dryer/tkrouter
TkRouter is a lightweight routing library for Tkinter, bringing modern declarative navigation, animated transitions, nested routes, guards, and 404 handling to Python desktop apps.
https://github.com/israel-dryer/tkrouter
Last synced: 5 months ago
JSON representation
TkRouter is a lightweight routing library for Tkinter, bringing modern declarative navigation, animated transitions, nested routes, guards, and 404 handling to Python desktop apps.
- Host: GitHub
- URL: https://github.com/israel-dryer/tkrouter
- Owner: israel-dryer
- License: mit
- Created: 2025-05-03T20:08:47.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-05-03T21:03:03.000Z (6 months ago)
- Last Synced: 2025-05-03T21:24:33.473Z (6 months ago)
- Language: Python
- Size: 17.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TkRouter
A declarative routing system for building multi-page **Tkinter** applications with transitions, parameters, guards, and navigation history.
[Full documentation](https://tkrouter.readthedocs.io)
[](https://pypi.org/project/tkrouter/)
[](https://github.com/israel-dryer/tkrouter/blob/main/LICENSE)
---
## ✨ Features
* 🔀 Route matching with parameters (e.g., `/users/`)
* ❓ Query string parsing (e.g., `/logs?level=info`)
* 🔄 Animated transitions (slide, fade)
* 🔒 Route guards with optional redirects
* 🧱 Singleton router via `create_router()` / `get_router()`
* 🧭 Navigation history: `.back()`, `.forward()`, `.go()`
* 📢 Route observers with `on_change()`
* 🧩 Routed widgets: `RouteLinkButton`, `RouteLinkLabel`
* 🎨 Works with `tk.Frame` or `ttk.Frame`
---
## 📦 Installation
```bash
pip install tkrouter
```
---
## 🚀 CLI Utilities
After installation, these command-line scripts become available:
```bash
tkrouter-create # Generate a minimal main.py scaffold
tkrouter-demo-minimal # Basic home/about demo
tkrouter-demo-admin # Sidebar layout with query parameters
tkrouter-demo-unified # Flat nested routes with transitions
tkrouter-demo-guarded # Route guards with simulated login
```
---
## Quickstart
You can start a new Tkinter router-based app in two ways:
### 🚀 Option 1: Use the CLI
```bash
tkrouter-create
```
This generates a ready-to-run `main.py` file with a minimal working app.
---
### 🧪 Option 2: Use this snippet
```python
from tkinter import Tk
from tkrouter import create_router, get_router, RouterOutlet
from tkrouter.views import RoutedView
from tkrouter.widgets import RouteLinkButton
class Home(RoutedView):
def __init__(self, master):
super().__init__(master)
RouteLinkButton(self, "/about", text="Go to About").pack()
class About(RoutedView):
def __init__(self, master):
super().__init__(master)
RouteLinkButton(self, "/", text="Back to Home").pack()
ROUTES = {
"/": Home,
"/about": About,
}
root = Tk()
outlet = RouterOutlet(root)
outlet.pack(fill="both", expand=True)
create_router(ROUTES, outlet).navigate("/")
root.mainloop()
```
---
## 🧪 Example Demos
```bash
python -m tkrouter.examples.minimal_app
python -m tkrouter.examples.admin_console
python -m tkrouter.examples.unified_routing
python -m tkrouter.examples.guarded_routes
```
| Example | Description |
| ----------------- | -------------------------------------------------------------------- |
| `minimal_app` | Basic Home/About router demo |
| `admin_console` | Sidebar UI with dynamic **routes** and **query parameters** |
| `unified_routing` | Flat-style routing (e.g., `/dashboard/stats`) with slide transitions |
| `guarded_routes` | Route guard demo with simulated login and redirect fallback |
---
## 📚 API Overview
### Router Lifecycle
```python
create_router(routes: dict, outlet: RouterOutlet, transition_handler=None)
get_router() -> Router
```
### Route Config Format
```python
{
"/users/": {
"view": UserDetailPage,
"guard": is_logged_in,
"redirect": "/login",
"transition": slide_transition
}
}
```
* Supports **dynamic route parameters** using angle brackets (e.g., ``)
* Supports **query parameters** appended to URLs (e.g., `?tab=settings`)
### Transitions
```python
from tkrouter.transitions import slide_transition, simple_fade_transition
```
Set globally or per route config.
### Routed Widgets
* `RouteLinkButton(master, to, params=None, **kwargs)`
* `RouteLinkLabel(master, to, params=None, **kwargs)`
* `bind_route(widget, path, params=None)`
* `@with_route(path, params)` — for command binding
### Observing Route Changes
```python
get_router().on_change(lambda path, params: print("Route changed:", path, params))
```
---
## ⚠️ Exceptions
* `RouteNotFoundError` – Raised when no matching route is found
* `NavigationGuardError` – Raised when guard blocks navigation
---
## ✅ Compatibility
* Python 3.8 and newer
---
## 📄 License
MIT License © [Israel Dryer](https://github.com/israel-dryer/tkrouter)