SmartSwitch Logo

Getting Started

  • What is SmartSwitch?
    • The Problem
    • The Solution
      • Named Handler Registry
      • Plugin-Based Composition
    • When to Use SmartSwitch
    • When NOT to Use SmartSwitch
    • Service-Ready Architecture
      • The Pattern: Organize → Expose
    • Key Features
    • Next Steps
  • Installation
    • Requirements
    • Install from PyPI
    • Install from source
    • Development Installation
    • Verify Installation
    • Next Steps
  • Quick Start
    • Installation
    • The Two Core Patterns
      • Pattern 1: Named Handler Registry
        • Basic Registration
        • Custom Aliases
        • Prefix-Based Auto-Naming
        • Hierarchical Organization
      • Pattern 2: Plugin System
        • Basic Plugin Usage
        • Creating Custom Plugins
        • Chaining Multiple Plugins
    • Real-World Example: API Router
    • Key Concepts Summary
      • Named Handler Registry
      • Plugin System
    • Next Steps
    • Quick Reference
  • Basic Usage
    • Creating a Switcher
    • Registering Handlers
      • Simple Registration
      • Handlers with Arguments
    • Calling Handlers
      • By Name
      • Error Handling
    • Custom Aliases
    • Prefix Conventions
    • Using Plugins
      • Logging Plugin
      • Custom Plugins
    • Descriptor Protocol
    • Inspecting Handlers
    • Best Practices
      • 1. Use Descriptive Names
      • 2. Validate Inputs
      • 3. Document Handlers
      • 4. Group Related Handlers
    • Next Steps

User Guide

  • Named Handlers Guide
    • Basic Named Handler Access
    • One-Liner Invocation
    • Custom Aliases
    • Explicit Named Dispatch
    • Prefix-Based Auto-Naming
      • Real-World Example: Protocol Handlers
      • Prefix with Description
      • When Prefix Doesn’t Match
      • Explicit Names Override Prefix
    • Handler Registry
    • Duplicate Name Detection
      • Duplicate Alias Detection
    • Handler Not Found
    • Common Patterns
      • Command Dispatcher
      • Plugin Registry
      • Method Routing
      • Configuration-Based Dispatch
    • Combining Named and Automatic Dispatch
    • Descriptor Protocol for Class Usage
    • Performance Characteristics
    • Best Practices
    • Next Steps
  • API Discovery and Introspection
    • Listing Registered Handlers
      • With Prefix Stripping
    • Organizing Multiple Switchers
    • Parent-Child Relationship Management
      • Setting Parent Dynamically
      • Adding Children
      • Querying Children
      • Reparenting
      • Removing Children
      • Recursive API Discovery
    • API Reference
      • Methods
      • Properties
  • Best Practices
    • Design Principles
      • 1. Use Descriptive Names
      • 2. Use Prefix Conventions
    • Performance Best Practices
      • When to Use SmartSwitch
      • Use Direct Named Access for Hot Paths
      • Cache Switchers
    • Error Handling Best Practices
      • Validate Inputs in Handlers
      • Handle Missing Handlers Gracefully
      • Provide Helpful Error Messages
    • Testing Best Practices
      • Test Each Handler Independently
      • Test Rule Priority
      • Test Default Handler
      • Test Edge Cases
    • Documentation Best Practices
      • Document Your Switcher
      • Document Handler Intent
    • Organization Best Practices
      • Group Related Handlers
      • Use Separate Files for Large Switchers
    • Security Best Practices
      • Validate User Input
      • Sanitize All Inputs
      • Avoid Exposing Internal Handlers
    • SmartPublisher Integration
      • Use Complete Type Hints
      • Write Comprehensive Docstrings
      • Provide Clear Parameter Descriptions
      • Use Modern Type Hint Syntax
      • Example: Well-Documented Handler
    • Next Steps

Plugin System

  • Plugin System
    • Overview
    • Quick Start
    • Built-in Plugins
    • Plugin Topics
      • Plugin Development Guide
        • Overview
        • Quick Links
        • The Plugin Protocol
        • Plugin Lifecycle (v0.6.0+)
        • Plugin Naming
        • Basic Plugin Example
        • Accessing the Plugin
        • Advanced Plugin Example: Retry Logic
        • Plugin Initialization Parameters
        • Storing State
        • Chaining Multiple Plugins
        • Standard vs External Plugins
        • Best Practices
        • Plugin Protocol Reference
        • FAQ
        • Summary
      • Plugin Middleware Pattern
        • Overview
        • The Middleware Analogy
        • Execution Phases
        • Reference Implementation: LoggingPlugin
        • Chain of Execution with Multiple Plugins
        • Plugin Naming Guidelines
        • Use Cases and Examples
        • Why Plugins Are Useful
        • Summary
      • LoggingPlugin
        • Quick Start
        • Configuration System
        • Available Flags
        • Default Behavior
        • Common Patterns
        • Runtime Configuration
        • Output Formats
        • Auto-Fallback Behavior
        • Custom Logger
        • Pydantic Integration
        • Combining with Other Plugins
        • API Reference
        • See Also
      • Plugin Development
      • Middleware Pattern
      • Logging Plugin
    • Plugin Order Matters
    • Creating Custom Plugins
    • Next Steps
  • Plugin Development Guide
    • Overview
    • Quick Links
    • The Plugin Protocol
    • Plugin Lifecycle (v0.6.0+)
      • Understanding the Three Phases
        • Phase 1: Decoration (Happens ONCE when @sw is applied)
        • Phase 2: Call (Happens EVERY TIME the function is called)
        • Phase 3: Exit (Happens EVERY TIME, on return or exception)
      • The on_decorate() Hook
      • Metadata Sharing Between Plugins
      • BasePlugin Class
      • Global Plugin Registry
    • Plugin Naming
      • Core Principle: Name by Function, Not Framework
      • Why This Matters
      • External Package Naming
      • Naming Guidelines Summary
    • Basic Plugin Example
    • Accessing the Plugin
      • Custom Plugin Names
    • Advanced Plugin Example: Retry Logic
    • Plugin Initialization Parameters
    • Storing State
    • Chaining Multiple Plugins
    • Standard vs External Plugins
      • Creating an External Plugin Package
    • Best Practices
      • 1. Use @wraps to Preserve Metadata
      • 2. Store Switcher Reference Carefully
      • 3. Provide Clear Public Methods
      • 4. Document Plugin Behavior
      • 5. Handle Edge Cases
      • 6. Test Thoroughly
    • Plugin Protocol Reference
      • Required
      • Recommended
      • Optional
    • FAQ
    • Summary
  • Plugin Middleware Pattern
    • Overview
    • The Middleware Analogy
    • Execution Phases
      • Phase 1: onCalling (Before)
      • Phase 2: Function Execution
      • Phase 3: onCalled (After)
    • Reference Implementation: LoggingPlugin
      • Complete Code with Detailed Annotations
      • Execution Flow Diagram
      • Error Flow Diagram
      • Key Implementation Details
        • 1. Why try/except/finally?
        • 2. The Three Modes
        • 3. Timing Implementation
        • 4. Circular Buffer for History
        • 5. Silent File Write Failures
    • Chain of Execution with Multiple Plugins
    • Plugin Naming Guidelines
      • Rule: Name by Function, Not by Framework
      • Why This Matters
      • External Package Naming
    • Use Cases and Examples
      • 1. External Metrics: Prometheus
      • 2. External Metrics: DataDog/StatsD
      • 3. Distributed Tracing: OpenTelemetry
    • Why Plugins Are Useful
      • 1. Separation of Concerns
      • 2. Composability
      • 3. Zero Code Modification
      • 4. Reusability
    • Summary
  • LoggingPlugin
    • Quick Start
    • Configuration System
      • 1. Flags String (Concise)
      • 2. Individual Parameters (Explicit)
    • Available Flags
      • State Flag
      • Output Destination
      • Content Flags
    • Default Behavior
    • Common Patterns
      • Tutorial/Demo Mode
      • Debugging Inputs Only
      • Performance Analysis
      • Production Monitoring
    • Runtime Configuration
      • Access Plugin
      • Global Configuration
      • Per-Method Configuration
      • Dynamic Changes
    • Output Formats
      • Before (Input Parameters)
      • After (Return Value)
      • With Timing
      • Exception Handling
    • Auto-Fallback Behavior
    • Custom Logger
    • Pydantic Integration
    • Combining with Other Plugins
    • API Reference
      • .plug('logging', **kwargs)
      • Runtime Configuration API
    • See Also

Examples

  • Examples
    • Command-Line Tool
    • API Request Router
    • Plugin System Integration
    • Event Handler System
    • State Machine
    • Next Steps

API Reference

  • API Reference
    • Switcher Class

Advanced

  • Architecture Deep Dive
    • Architecture Overview
    • Registration Flow
    • Named Dispatch Flow
    • Class Relationships
    • Module Structure
    • Component Responsibilities
      • Switcher (Main Engine)
      • BasePlugin (Plugin Base Class)
      • _SwitchCall (Dispatch Proxy)
      • MethodEntry (Method Metadata)
    • Key Design Decisions
      • 1. Named Registry (Not Rule-Based)
      • 2. Plugin System with Two Hooks
      • 3. Prefix-Based Auto-Naming
      • 4. Hierarchical Organization
      • 5. Plugin Inheritance
      • 6. Thread-Local Runtime Data
    • Component Interaction Summary
    • Performance Characteristics
    • Thread Safety Considerations
    • Plugin System Details
      • Plugin Registration
      • Plugin Naming
      • Metadata Namespace Convention
    • Introspection API
      • describe() Method
      • Direct Access
    • Future Extension Points
    • Design Principles Applied
SmartSwitch
  • Search

© Copyright 2025, Genropy Team.

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