Genro Routes for Dummies

Quick Start

Install

pip install genro-routes          # Core (zero dependencies)
pip install genro-routes[pydantic] # With validation support

Write your service

from genro_routes import RoutingClass, Router, route

class BookStore(RoutingClass):
    def __init__(self):
        self.catalog = [
            {"id": 1, "title": "Dune", "author": "Herbert"},
            {"id": 2, "title": "Neuromancer", "author": "Gibson"},
        ]
        self.api = Router(self, name="api")

    @route("api")
    def list_books(self):
        return self.catalog

    @route("api")
    def find_book(self, book_id: int):
        return next((b for b in self.catalog if b["id"] == book_id), None)

    @route("api")
    def add_book(self, title: str, author: str):
        book = {"id": len(self.catalog) + 1, "title": title, "author": author}
        self.catalog.append(book)
        return book

Call it directly — no server needed

store = BookStore()

store.api.node("list_books")()              # [{"id": 1, ...}, {"id": 2, ...}]
store.api.node("find_book")(book_id=1)      # {"id": 1, "title": "Dune", ...}
store.api.node("add_book")(title="Snow Crash", author="Stephenson")

# Introspect all registered handlers
info = store.api.nodes()
print(info["entries"].keys())  # dict_keys(['list_books', 'find_book', 'add_book'])

Test it — this is your entire test

def test_find_book():
    store = BookStore()
    result = store.api.node("find_book")(book_id=1)
    assert result["title"] == "Dune"

def test_add_book():
    store = BookStore()
    book = store.api.node("add_book")(title="Snow Crash", author="Stephenson")
    assert book["id"] == 3
    assert len(store.api.node("list_books")()) == 3

Now expose it via HTTP — three lines

# With genro-asgi (the HTTP bridge)
from genro_asgi import GenroASGI

store = BookStore()
app = GenroASGI(store)  # That's it. uvicorn app:app

# GET  /api/list_books     → [{"id": 1, ...}]
# GET  /api/find_book?book_id=1  → {"id": 1, "title": "Dune"}
# POST /api/add_book       → {"id": 3, ...}

Same BookStore, same logic, zero changes. The ASGI adapter maps router entries to HTTP endpoints, infers GET/POST from parameter types, and handles serialization.

The Plugin System

Plugins attach to routers and form a pipeline. Every handler call passes through all attached plugins. They propagate automatically from parent to child routers.

Three ways to configure

1. In the decorator — static, per-handler

@route("api", auth_rule="admin", pydantic_disabled=True)

2. On the plugin instance — runtime, global or targeted

router.auth.configure(rule="user")                          # All handlers
router.auth.configure(_target="admin_panel", rule="admin")   # One handler

3. Via the routing proxy — wildcards and introspection

svc.routing.configure("api:auth/admin_*", rule="admin")  # Glob pattern
svc.routing.configure("?")                              # Show full config tree

At a glance

Tag-based access control. Handlers declare required tags, requests declare user tags. The plugin matches them and blocks unauthorized access.

What happens at runtime

class API(RoutingClass):
    def __init__(self):
        self.api = Router(self, name="api").plug("auth")

    @route("api", auth_rule="admin")
    def delete_user(self, user_id: int): ...

    @route("api")                       # No rule = public
    def health(self): ...

svc = API()

# Authorized — works
svc.api.node("delete_user", auth_tags="admin")(user_id=42)

# Wrong tags — raises NotAuthorized (403)
svc.api.node("delete_user", auth_tags="guest")

# No tags at all — raises NotAuthenticated (401)
svc.api.node("delete_user")

# Public handler — always works
svc.api.node("health")()

Filtered introspection

# nodes() shows only what the user can access:
svc.api.nodes(auth_tags="admin")            # Sees: delete_user, health
svc.api.nodes(auth_tags="guest")            # Sees: health only
svc.api.nodes()                            # Sees: health only (no tags = no access)

Rule expressions

@route("api", auth_rule="admin|moderator")     # Admin OR moderator
@route("api", auth_rule="admin&internal")      # Admin AND internal
@route("api", auth_rule="!guest")              # NOT guest
@route("api", auth_rule="(admin|mod)&!banned") # Grouping

Parameters

Two jobs: (1) validates inputs against type hints at runtime, (2) generates JSON response schemas from return types so bridges (OpenAPI, MCP) can document your API automatically.

from typing import TypedDict

class BookResponse(TypedDict):
    id: int
    title: str
    author: str

class API(RoutingClass):
    def __init__(self):
        self.api = Router(self, name="api").plug("pydantic")

    @route("api")
    def get_book(self, book_id: int) -> BookResponse:
        return {"id": book_id, "title": "Dune", "author": "Herbert"}

svc = API()
svc.api.node("get_book")(book_id=1)       # OK → {"id": 1, ...}
svc.api.node("get_book")(book_id="abc")   # ValidationError!

Response schema for free

# The return type annotation auto-generates a JSON Schema:
entry = svc.api._entries["get_book"]
schema = entry.metadata["pydantic"]["response_schema"]
# {"type": "object", "properties": {"id": {"type": "integer"}, ...}}

# OpenAPI and MCP bridges pick this up automatically.

Supported return types: TypedDict, dataclass, dict, list, str, int, bool, Pydantic models — anything Pydantic can serialize.

Skip validation for a handler

@route("api", pydantic_disabled=True)
def raw_handler(self, data): ...  # No validation, no schema

Parameters

Controls OpenAPI 3.1 schema generation. Overrides HTTP methods, adds tags, marks deprecated. Integrates with auth + env + pydantic automatically.

self.api = Router(self, name="api").plug("openapi").plug("auth").plug("pydantic")

@route("api", auth_rule="admin",
       openapi_tags="admin",
       openapi_deprecated=True,
       openapi_method="delete")
def remove_item(self, item_id: int): ...

# Generate full spec:
spec = svc.api.nodes(mode="openapi")
# {"paths": {"/remove_item": {"delete": {"security": [...], ...}}}}

# Or hierarchical (preserves router tree):
spec = svc.api.nodes(mode="h_openapi")

Auto-inference

Without explicit method: GET for scalar-only params (str, int, bool), POST for complex params (dict, list, models).

Cross-plugin integration

Parameters

Capability-based filtering. Handlers declare what the system must have (Redis, JWT, Stripe). If requirements aren't met, the handler disappears from introspection and raises NotAvailable on direct call.

from genro_routes.plugins.env import CapabilitiesSet, capability

class SystemCaps(CapabilitiesSet):
    @capability
    def redis(self) -> bool:
        return True

    @capability
    def stripe(self) -> bool:
        return False

class PaymentAPI(RoutingClass):
    def __init__(self):
        self.api = Router(self, name="api").plug("env")
        self.capabilities = SystemCaps()

    @route("api", env_requires="redis")
    def cached_lookup(self): ...        # Visible (redis available)

    @route("api", env_requires="stripe|paypal")
    def charge(self): ...                # Hidden (neither available)

svc = PaymentAPI()
svc.api.nodes()  # Shows cached_lookup only. charge is invisible.
svc.api.node("charge")()  # Raises NotAvailable!

# Provide capabilities at request time:
svc.api.node("charge", env_capabilities="stripe")()  # Now works

Same rule syntax as auth: | OR, & AND, ! NOT, () grouping.

Accumulation: Capabilities from parent instances are inherited. Request-time capabilities add to the set.

Parameters

Wraps handler calls with timing. Logs "start" before and "end (X ms)" after. Useful for debugging and monitoring.

self.api = Router(self, name="api").plug("logging")

@route("api")
def slow_op(self):
    time.sleep(0.1)
    return "done"

# Output:
#   slow_op start
#   slow_op end (100.45 ms)

Fine-grained control

@route("api", logging_flags="before,after:off")  # Start only, skip timing
def fast_op(self): ...

# At runtime:
router.logging.configure(enabled=False)                    # Silence all
router.logging.configure(_target="slow_op", after=True)    # Re-enable one
router.logging.configure(print=True)                       # Force print()

Parameters

Flag syntax: "enabled" → True. "before:off" → False. "enabled,after:off" → enabled=True, after=False.

Service Composition

Real applications are built from independent modules. Each module is a RoutingClass with its own router. Connect them with attach_instance.

class App(RoutingClass):
    def __init__(self):
        self.api = Router(self, name="api", branch=True).plug("auth")

        self.users = UsersService()
        self.orders = OrdersService()
        self.notify = NotifyService()

        self.api.attach_instance(self.users, name="users")
        self.api.attach_instance(self.orders, name="orders")
        self.api.attach_instance(self.notify, name="notify")

app = App()
app.api.node("users/list_users")()
app.api.node("orders/approve_order")(order_id="123")

# Introspect the entire tree:
tree = app.api.nodes()
print(tree["routers"].keys())  # dict_keys(['users', 'orders', 'notify'])

Composition features

• branch=True — pure namespace, no handlers at root level
• prefix="handle_" — strip method prefixes (handle_list → entry list)
• Auto-detach on attribute replacement — swap child services at runtime
• Dotted path resolution — "users/list_users" walks the tree

Cheat Sheet

Essentials

Plugins

Composition

Exceptions