Genro Routes Logo

Getting Started

  • Installation
    • Requirements
    • From PyPI
    • With Optional Dependencies
      • Development Tools
      • Documentation Tools
      • All Dependencies
    • From Source
    • Verify Installation
    • Next Steps
  • Quick Start
    • Installation
    • Your First Router
    • Custom Entry Names
    • One Class, One Router
    • Building Hierarchies
    • Adding Plugins
    • Validating Arguments
    • Response Schemas
    • Execution Context
    • Next Steps
    • Need Help?
  • Examples Gallery
    • Library Wrappers
      • 1. Standard Faker
      • 2. Magic Faker (Dynamic Mapping)
      • 3. Syntax Highlighting (Pygments)
      • 4. QR Code Generator
    • Architectural Patterns
      • 5. Authentication & Roles
      • 6. Service Composition
      • 7. Self-Documentation (Meta-Example)
    • LLM & MCP Integration
      • 8. MCP Bridge
      • 9. Repository Explorer
      • 10. Deep Repo Explorer
    • Running the Examples
  • Genro Routes - Frequently Asked Questions
    • What is Genro Routes?
      • What problem does Genro Routes solve?
      • Genro Routes vs function dictionary?
      • Is Genro Routes a web framework?
    • Core Concepts
      • What is a Router?
      • How does the @route decorator work?
      • What is RoutingClass?
    • Hierarchies and Child Routers
      • How do I organize nested routers?
      • How do I access child routers?
      • Do plugins inherit to children?
    • Plugin System
      • What are plugins?
      • How do I use built-in plugins?
      • How do I configure plugins at runtime?
      • Can I create custom plugins?
    • Advanced Use Cases
      • How do I handle errors and defaults?
      • What exceptions can node() raise?
      • What is a root node?
      • How do I introspect the structure?
    • Comparisons
      • Genro Routes vs decorator dispatch?
    • Troubleshooting
      • “No plugin named ‘X’ attached to router”
      • “Handler name collision”
      • Plugins don’t propagate to children
      • ValidationError with Pydantic
    • Best Practices
      • When should I use Genro Routes?
      • Does plugin order matter?
      • How do I test code with Genro Routes?
    • Context and Shared State
      • How do I access a database connection from my handlers?
      • What happened to DbRoutingClass?
    • Useful Links
    • Contributing

User Guide

  • Basic Usage
    • Overview
    • Creating Your First Router
    • Registering Handlers
    • One Class, One Router
    • Database Access via Context
      • Multiple Surfaces via Composition
    • Calling Handlers
    • Using Prefixes and Custom Names
    • Checking Node Errors
    • Exceptions: NotFound, NotAuthenticated, NotAuthorized, NotAvailable
    • Custom Exception Mapping
    • Catch-All Routing with default_entry
    • Building Hierarchies
    • Introspection
    • Custom Metadata with meta_*
    • Execution Context
    • Wrapping Handler Results
    • Next Steps
  • Plugin Development
    • Overview
    • Built-in Plugins
    • Shorthand Plugin Syntax
    • Built-in Plugins API Reference
      • AuthPlugin API
      • EnvPlugin API
      • PydanticPlugin API
      • OpenAPI generation (transport layer, not core)
      • ChannelPlugin API
    • Creating Custom Plugins
      • Basic Plugin Structure
      • Constructor Signature
    • Plugin Hooks
    • Plugin Execution Order
      • The Onion Model
      • Example: Logging then Validation
      • Practical Ordering Guidelines
      • Visualizing the Stack
      • configure(**kwargs)
      • on_decore(router, func, entry)
      • wrap_handler(router, entry, call_next)
      • deny_reason(entry, **filters)
      • entry_metadata(router, entry)
      • on_attached_to_parent(parent_plugin)
      • on_parent_config_changed(old_config, new_config)
    • Plugin Inheritance
      • Inheritance Rules
      • Why This Design?
      • Example: AuthPlugin Inheritance
    • Plugin Registration
    • Per-Instance State
    • Plugin Configuration
      • Defining Configuration
      • Reading Configuration
      • Configuring at Runtime
      • The _target Parameter
      • The flags Parameter
    • Complete Example: Authorization Plugin
    • Best Practices
    • Runtime Plugin Management
      • Enabling and Disabling Plugins
      • Storing Runtime Data
    • Next Steps
  • Plugin Configuration
    • Overview
    • Target Syntax
    • Glob Pattern Syntax
    • Basic Configuration
    • Attaching Plugins in Batch
    • Batch Updates
    • Introspection
    • Exposing Configuration API
    • Error Handling
    • Best Practices
    • Next Steps
  • Hierarchical Routers
    • Overview
    • Managing Hierarchies
    • Basic Instance Attachment
    • Multiple Surfaces: Composition
    • Grouping with Section
    • Composing Services
    • Auto-Detachment
    • Parent Tracking
    • Plugin Inheritance
    • Path Navigation
    • Introspection
    • Catch-All Routes with default_entry
    • Real-World Examples
      • Microservice-Style Organization
      • Multi-Level Organization
      • Dynamic Service Replacement
    • Best Practices
      • Logical Grouping
      • Shared Plugins at Root
      • Deep Hierarchies
      • Retrieve Child Instances
      • Explicit Detachment
      • Prevent Name Collisions
    • Common Patterns
      • Parent-Aware Children
      • Conditional Attachment
      • Multi-Surface Services
    • Next Steps
  • Branches: Lazy Subtrees and Aliases
    • Overview
    • Declaring Branches
    • Factory (lazy) vs Instance (eager)
    • Aliases: Symlinks to Branches
    • Introspection: nodes() Never Builds
    • Reverse Lookup and Lazy Branches
    • Errors Are Deferred and Repeatable
    • Runtime Management
    • Attaching an existing instance
    • Next Steps
  • add_branches Visual Guide
    • Core Concept
    • Scenario 1: Attaching a Child
    • Scenario 2: Child with Its Own Children
    • Scenario 3: Multiple Surfaces — Composition
    • Syntax Reference
      • add_branches({"name": alias, "instance": child})
      • include (on Router — low level)
      • detach_instance (on Router)
    • Scenario 4: Entry Alias
    • Decision Guide
    • Real-World Example
  • Execution Context
    • RoutingContext in 30 seconds
    • Parent chain — layered contexts
    • Slot + parent chain — instance-scoped context
      • How it works under the hood
    • Adapter usage pattern
    • Database access
    • Subclassing RoutingContext
    • Summary
  • Why One Name Per Operation
    • The question
    • Short answer
    • The REST model and its limits
    • Where the industry went
    • How genro-routes handles this
    • Benefits
    • What if I need REST-style paths?
    • Summary
  • Best Practices
    • Router Design
      • Keep Services Focused
      • Use Meaningful Names
      • Leverage Prefixes for Organization
    • Hierarchy Design
      • Flat is Better Than Deep
      • Use Sections for Organization
      • Attaching Child Instances
    • Plugin Usage
      • Apply Plugins at the Right Level
      • Compose Simple Plugins
      • Configure Plugins Explicitly
    • Error Handling
      • Let Errors Propagate
      • Use Plugin Wrappers for Cross-Cutting Concerns
    • Testing
      • Test Handlers in Isolation
      • Test Hierarchies
      • Test Plugin Behavior
    • Performance
      • Attach Plugins Early
      • Cache Handler References
    • Anti-Patterns
      • Global State in Plugins
      • Circular Dependencies
      • Over-Configuration
    • Summary
    • Next Steps

Reference

  • API Reference
    • Constructor and slots
    • Lazy binding
    • Marker discovery
    • Handler table and wrapping
    • Lookup and execution
    • Children (instance hierarchies)
    • Introspection
    • Hooks for subclasses
    • BaseRouter
      • BaseRouter.__init__()
      • BaseRouter.instance
      • BaseRouter.name
      • BaseRouter.prefix
      • BaseRouter.description
      • BaseRouter.default_entry
      • BaseRouter.current_capabilities
      • BaseRouter.add_entry()
      • BaseRouter.include()
      • BaseRouter.add_branches()
      • BaseRouter.remove_branch()
      • BaseRouter.branches
      • BaseRouter.detach_instance()
      • BaseRouter.get_url()
      • BaseRouter.router_at_path()
      • BaseRouter.nodes()
      • BaseRouter.node()
      • BaseRouter.iter_plugins()
    • Internal state
    • Global registry
    • Attaching plugins
    • Wrapping pipeline
    • Inheritance behaviour
    • Router
      • Router.__init__()
      • Router.register_plugin()
      • Router.available_plugins()
      • Router.plug()
      • Router.iter_plugins()
      • Router.get_config()
      • Router.__getattr__()
      • Router.set_plugin_enabled()
      • Router.is_plugin_enabled()
      • Router.set_runtime_data()
      • Router.get_runtime_data()
      • Router.instance
      • Router.name
      • Router.prefix
      • Router.description
      • Router.default_entry
    • Re-exports
    • route()
    • RoutingClass
      • RoutingClass.route
      • RoutingClass.add_branches()
      • RoutingClass.remove_branch()
      • RoutingClass.branches
      • RoutingClass.routing
      • RoutingClass.ctx
      • RoutingClass.capabilities
      • RoutingClass.result_wrapper()
    • Router
      • Router.__init__()
      • Router.register_plugin()
      • Router.available_plugins()
      • Router.plug()
      • Router.iter_plugins()
      • Router.get_config()
      • Router.__getattr__()
      • Router.set_plugin_enabled()
      • Router.is_plugin_enabled()
      • Router.set_runtime_data()
      • Router.get_runtime_data()
      • Router.instance
      • Router.name
      • Router.prefix
      • Router.description
      • Router.default_entry
  • Plugin API Reference
    • External plugin API
    • PydanticPlugin: strict validation and _coerce
    • Auto-Generated Plugin API
      • AuthPlugin
        • AuthPlugin.plugin_code
        • AuthPlugin.plugin_description
        • AuthPlugin.plugin_code
        • AuthPlugin.plugin_description
        • AuthPlugin.plugin_default_param
        • AuthPlugin.configure()
        • AuthPlugin.deny_reason()
        • AuthPlugin.name
      • EnvPlugin
        • EnvPlugin.plugin_code
        • EnvPlugin.plugin_description
        • EnvPlugin.plugin_code
        • EnvPlugin.plugin_description
        • EnvPlugin.plugin_default_param
        • EnvPlugin.configure()
        • EnvPlugin.deny_reason()
        • EnvPlugin.name
      • CapabilitiesSet
        • CapabilitiesSet.__iter__()
        • CapabilitiesSet.__contains__()
        • CapabilitiesSet.__len__()
      • capability()
      • Configuration
      • LoggingPlugin
        • LoggingPlugin.plugin_code
        • LoggingPlugin.plugin_description
        • LoggingPlugin.plugin_code
        • LoggingPlugin.plugin_description
        • LoggingPlugin.__init__()
        • LoggingPlugin.configure()
        • LoggingPlugin.wrap_handler()
      • ChannelPlugin
        • ChannelPlugin.plugin_code
        • ChannelPlugin.plugin_description
        • ChannelPlugin.plugin_default_param
        • ChannelPlugin.configure()
        • ChannelPlugin.deny_reason()
        • ChannelPlugin.name
      • Strict by default
      • PydanticPlugin
        • PydanticPlugin.plugin_code
        • PydanticPlugin.plugin_description
        • PydanticPlugin.plugin_code
        • PydanticPlugin.plugin_description
        • PydanticPlugin.__init__()
        • PydanticPlugin.configure()
        • PydanticPlugin.on_decore()
        • PydanticPlugin.wrap_handler()
        • PydanticPlugin.get_model()
        • PydanticPlugin.name
        • PydanticPlugin.entry_metadata()
  • Genro Routes Architecture (current state)
    • Router and hierarchy
    • Branches (declarative subtrees: factory, instance, alias)
    • Plugin store
      • Plugin lifecycle
    • Plugin Inheritance
      • Inheritance Rules (Default Behavior)
      • Plugin Hooks for Inheritance
        • on_attached_to_parent(parent_plugin)
        • on_parent_config_changed(old_config, new_config)
      • Plugin API
      • Plugin Inheritance Behavior
    • Introspection data (nodes)
    • Admin/CLI/UI implications
    • CLI transport adapter
      • Data flow
      • Key design decisions
  • genro-routes — Code Reading Guide
    • Table of Contents
    • 1. The big idea
    • 2. File map
    • 3. The @route decorator — markers, not mutations
      • What it does
      • Why it is surprising
      • Why it is built this way
      • Details worth noting
    • 4. RouterInterface — the minimal contract
    • 5. BaseRouter — the routing core
      • 5.1 Constructor and slots
      • 5.2 Lazy binding
      • 5.3 Handler registration
      • 5.4 Path resolution — _find_candidate_node(path)
      • 5.5 Children — include() and detach_instance()
      • 5.6 Introspection — nodes()
      • 5.7 Hooks for subclasses
    • 6. RouterNode — the callable wrapper
      • What it does
      • Path → parameter mapping (_assign_partial)
      • Precedence: path > kwargs
      • Exception mapping
    • 7. RoutingClass — the mixin that ties everything together
      • 7.1 __slots__ — state isolation
      • 7.2 The route property — one router per instance
      • 7.3 __setattr__ — child auto-detach ⚠️
      • 7.4 add_branches — hierarchical composition
      • 7.5 Section — the grouping node
      • 7.6 routing property — the proxy
      • 7.7 ctx property — slot + parent chain
    • 8. Router — BaseRouter + plugin pipeline
      • 8.1 Global registry
      • 8.2 plug(name) — attaching a plugin
      • 8.3 __getattr__ — fluent plugin access
      • 8.4 Middleware pipeline — _wrap_handler
      • 8.5 Plugin inheritance — _on_attached_to_parent
      • 8.6 is_plugin_enabled — 5-level cascade
    • 9. The plugin system
      • 9.1 MethodEntry — the record of a handler
      • 9.2 BasePlugin — the contract
      • 9.3 __init_subclass__ — the most elegant pattern ⚠️
      • 9.4 Configuration store
      • 9.5 Inheritance: “follow if aligned, ignore if customized”
    • 10. The built-in plugins
      • 10.1 LoggingPlugin (plugins/logging.py, 175 lines)
      • 10.2 PydanticPlugin (plugins/pydantic.py, 247 lines)
      • 10.3 AuthPlugin (plugins/auth.py, 170 lines)
      • 10.4 EnvPlugin + CapabilitiesSet (plugins/env.py, 307 lines)
      • 10.5 ChannelPlugin (plugins/channel.py, 143 lines)
      • 10.6 OpenAPI (out of core)
    • 11. Exceptions
    • 12. Non-standard patterns — reasoned recap
      • 12.1 @route as pure marker
      • 12.2 Lazy binding
      • 12.3 __init_subclass__ on BasePlugin
      • 12.4 __setattr__ on RoutingClass
      • 12.5 __getattr__ on Router
      • 12.6 object.__setattr__ scattered through the code
      • 12.7 safe_is_instance with a string
      • 12.8 Intentional name mangling (__entries_raw)
      • 12.9 Operations-first, not REST
      • 12.10 CapabilitiesSet with dir() and dynamic calls
    • 13. The CLI adapter
      • Internal architecture
      • CLI design choices
    • 14. Quick glossary
Genro Routes
  • Python Module Index

Python Module Index

g
 
g
- genro_routes
    genro_routes.core.base_router
    genro_routes.core.decorators
    genro_routes.core.router
    genro_routes.plugins.auth
    genro_routes.plugins.channel
    genro_routes.plugins.env
    genro_routes.plugins.logging
    genro_routes.plugins.pydantic

© Copyright 2025-2026, Softwell S.r.l..

Built with Sphinx using a theme provided by Read the Docs.