Documentation: Add FAQ section with advanced patterns and best practices

[genro]

Overview

Add a FAQ (Frequently Asked Questions) section to the documentation covering advanced patterns, common pitfalls, and best practices.

Motivation

Users often need guidance on:

• Performance optimization patterns
• Advanced plugin usage
• Architectural patterns (multi-switcher, prefix tricks, etc.)
• Common pitfalls and solutions

A dedicated FAQ section makes this knowledge easily discoverable.

Proposed Structure

docs/faq.md (or docs/guide/faq.md):

Performance

Q: How can I avoid plugin overhead for internal methods?

A: Use the prefix pattern to separate validated entry points from fast internal methods:

class Handler:
    api = Switcher(prefix='route_').plug('pydantic')
    
    @api
    def route_process(self, data: dict):
        # Validated via switcher
        return self.process(data)
    
    def process(self, data):
        # Fast direct call
        return data

Call via switcher: api('process') → validated
Call direct: obj.process() → fast

Q: What is the plugin overhead?

A: See #29 for benchmarks. For typical I/O-bound operations (API calls, DB queries), plugin overhead is negligible.

---

Architecture

Q: Can I use multiple Switchers on the same class?

A: Yes! Multi-switcher pattern:

class Handler:
    public = Switcher().plug('pydantic').plug('logging')
    internal = Switcher()
    
    @public
    def api_method(self): pass
    
    @internal
    def internal_method(self): pass

Q: How do I organize API routes vs internal methods?

A: Use prefix and naming conventions:

• api_* methods → decorated with api = Switcher(prefix='api_')
• _internal_* methods → not decorated (private convention)

---

Plugins

Q: Can I enable/disable plugins at runtime?

A: Yes, use the configure API:

# Global
sw.logging.configure.flags = 'enabled,print'

# Per-method
sw.logging.configure['method'].flags = 'enabled:off'

# Per-thread (uses contextvars)
with sw.enable(sw.pydantic, methods=['critical']):
    # pydantic enabled only for 'critical' in this context

Q: Can I create custom plugins?

A: Yes! Extend BasePlugin:

from smartswitch.core import BasePlugin

class TimingPlugin(BasePlugin):
    def wrap_handler(self, switch, entry, call_next):
        def wrapper(*args, **kwargs):
            start = time.time()
            result = call_next(*args, **kwargs)
            print(f"{entry.name}: {time.time() - start:.4f}s")
            return result
        return wrapper

sw = Switcher().plug(TimingPlugin())

---

Common Pitfalls

Q: My Pydantic validation isn't working

A: Make sure:

1. Plugin is enabled: flags='enabled' or enabled=True
2. Type hints are present on function
3. Pydantic is installed: pip install smartswitch[pydantic]

Q: Logging shows nothing

A: Check:

1. Plugin is enabled: flags='enabled,print' or configure Python logging
2. If using log mode, ensure logging is configured
3. LoggingPlugin auto-falls back to print() if no handlers

Q: I get "method not found" errors

A: Verify:

1. Method is decorated with switcher: @sw
2. Prefix matches: Switcher(prefix='api_') strips api_ from method names
3. Method name is correct in call: sw('method_name')

---

Best Practices

Q: When should I use SmartSwitch vs regular dispatch?

A: Use SmartSwitch when you need:

• Runtime method selection by name
• Plugin-based middleware (validation, logging, etc.)
• Type-based or value-based dispatch
• Uniform API for CLI/HTTP/etc.

Don't use for simple static dispatch (use regular function calls).

Q: Should I validate all methods?

A: No. Best practice:

• Public API: Always validate (user input)
• Internal methods: Validate at boundaries only
• Performance-critical: Profile first, optimize if needed

Q: How do I handle async methods?

A: SmartSwitch works with async functions. Plugins must be async-aware. Built-in plugins (Pydantic, Logging) support async.

---

Implementation

• Create docs/faq.md or docs/guide/faq.md
• Add initial content (above template)
• Link from main documentation
• Add more Q&A as common questions arise
• Keep updated with new features

Related Issues

• Performance: Measure plugin overhead to evaluate optimization needs #29 - Performance measurements (FAQ entry on overhead)
• Feature Request: Optional Method Wrapping (wrap_methods parameter) #24 - wrap_methods pattern (FAQ entry on alternatives)

Priority

Medium - Improves documentation quality and reduces support burden.

---

Note: FAQ should be living document - add entries as patterns emerge and questions are asked.