SmartAsync Logo

Getting Started

  • Overview
    • What is SmartAsync?
    • When is SmartAsync Useful?
    • When NOT to Use SmartAsync
    • How It Works
    • Key Features
    • Next Steps
  • Installation
    • Requirements
    • Install from PyPI
    • Install from Source
    • Verify Installation
    • Optional Dependencies
    • Next Steps
  • Quick Start
    • Installation
    • Your First SmartAsync Method
    • Using in Sync Context
    • Using in Async Context
    • Key Points
    • Next Steps
  • Basic Usage
    • The @smartasync Decorator
    • Calling from Sync Context
    • Calling from Async Context
    • Sync Methods in Async Context
    • Best Practices
    • Next Steps

How It Works

  • How SmartAsync Works - Technical Deep Dives
    • Core Concept
    • Available Guides
      • Sync → Async
      • Async → Sync
    • Implementation
    • Key Design Decisions
    • Performance
    • Related Documentation
  • How It Works: Sync → Async
    • Overview
    • Execution Flow
    • Step-by-Step
      • 1. User calls method (no await)
      • 2. Decorator detects context
      • 3. Pattern match: (False, True)
      • 4. Execute with asyncio.run()
      • 5. User receives result
    • Complete Example
    • What Happens Internally
    • Performance
    • Edge Cases
      • Nested asyncio.run() (forbidden)
      • Exception propagation
    • Key Points
    • Related
  • How It Works: Async → Sync
    • Overview
    • Execution Flow
    • Step-by-Step
      • 1. User awaits method in async context
      • 2. Decorator detects async context
      • 3. Pattern match: (True, False)
      • 4. Execute in thread pool
      • 5. User receives result
    • Complete Example
    • What Happens Internally
    • Why Thread Offloading?
      • Without threading (WRONG!)
      • With SmartAsync threading (CORRECT!)
    • Performance
    • Thread Safety Considerations
      • Connection per request (recommended)
      • Connection pooling (advanced)
    • Edge Cases
      • Sync method called from sync context
      • Exception propagation
    • Comparison with Manual Threading
      • Manual approach (verbose)
      • SmartAsync approach (clean)
    • Key Points
    • Related

Usage Scenarios

  • Usage Scenarios
    • Fundamentals
    • Architecture
    • Integration
  • Scenario A1: Sync Application Calling Async Libraries
    • Overview
    • Without SmartAsync
      • Traditional Approach 1: Manual asyncio.run() Everywhere
      • Traditional Approach 2: Stay Sync with Sync Libraries
      • Traditional Approach 3: Make Everything Async
    • With SmartAsync
      • Solution
    • Issues Impact on This Scenario
      • Issue #1: _sync_mode Ignored
      • Issue #2: Not Thread-Safe
      • Issue #3: Missing Edge Case Tests
      • Issue #4: Missing “When to Use” Documentation
    • Decision Matrix
    • When to Use SmartAsync for This Scenario
      • ✅ USE SmartAsync if:
      • ❌ DON’T use SmartAsync if:
      • 🤔 Consider Alternatives if:
    • Real-World Example: Data Processing Pipeline
      • Scenario
      • Before SmartAsync
      • After SmartAsync
    • Migration Path
      • From Sync Libraries to Async Libraries
    • Anti-Patterns
      • ❌ Anti-Pattern 1: Shared Instance in Multi-Threading
      • ❌ Anti-Pattern 2: Nested asyncio.run()
      • ❌ Anti-Pattern 3: Using in Tight Performance Loop
    • Testing Strategy
      • Test Your Code Using SmartAsync
    • Performance Characteristics
      • Overhead Analysis
    • Checklist for This Scenario
    • Summary
    • Related Scenarios
    • Further Reading
  • Scenario A2: Async App → Sync Legacy Library
    • 📋 The Problem
    • 🔴 Without SmartAsync
      • Naive Approach (WRONG!)
      • Manual Threading (VERBOSE!)
    • 🟢 With SmartAsync
      • Clean Solution
    • 💡 Complete Example: FastAPI + Legacy Database
      • Full Application
      • Run the API
    • ⚠️ Important Considerations
      • 1. Connection Pooling
      • 2. Transaction Management
      • 3. Thread Safety
      • 4. Performance
    • 🔗 Related Resources
    • 📚 Database Driver Compatibility
  • Scenario 03: Testing Async Code
    • 📋 The Problem
    • 💡 Solution with SmartAsync
    • 🎯 When to Use
    • ⚠️ Considerations
      • Performance
      • Coverage
      • Alternatives
    • 🔗 Related Scenarios
    • 📚 References
  • Scenario 04: Unified Library API
    • 📋 The Problem
    • 💡 Solution with SmartAsync
    • 🎯 When to Use
    • ⚠️ Considerations
      • Design Decisions
      • When NOT to Use
    • 🔗 Related Scenarios
    • 📚 Real-World Examples
    • 🎯 Success Metrics
  • Scenario 05: Gradual Migration
    • 📋 The Problem
    • 💡 Solution with SmartAsync
    • 🎯 Migration Strategies
      • Strategy 1: Bottom-Up
      • Strategy 2: Top-Down
      • Strategy 3: Critical Path
      • Strategy 4: Feature Branches
    • 🎯 When to Use
    • ⚠️ Considerations
      • Migration Planning
      • Monitoring
      • When NOT to Use
    • 🔗 Related Scenarios
    • 📚 Case Studies
    • 🎯 Success Criteria
  • Scenario 06: Plugin Systems
    • 📋 The Problem
    • 💡 Solution with SmartAsync
    • 🎯 When to Use
    • ⚠️ Considerations
      • Design Decisions
      • Advanced Patterns
      • When NOT to Use
    • 🔗 Related Scenarios
    • 📚 Real-World Plugin Systems
    • 🎯 Plugin Ecosystem Health
    • 🔍 Design Considerations
  • Scenario 07: Mixed Framework Integration
    • 📋 The Problem
    • 💡 Solution with SmartAsync
    • 🎯 When to Use
    • ⚠️ Considerations
      • Architecture Patterns
      • Performance Implications
      • Testing Strategy
      • When NOT to Use
    • 🔗 Related Scenarios
    • 📚 Integration Examples
      • Flask + Async Services
      • Django + Microservices
      • Celery + Modern APIs
    • 🎯 Integration Success Criteria
    • 🔍 Common Pitfalls
    • 📊 Decision Framework
  • Scenario 08: Web Scraping
    • 📋 The Problem
    • 💡 Solution with SmartAsync
    • 🎯 When to Use
    • ⚠️ Considerations
      • Design Patterns
      • Performance Optimization
      • Ethical Considerations
      • When NOT to Use
    • 🔗 Related Scenarios
    • 📚 Technology Stack
    • 🎯 Scraper Architecture
    • 🔍 Common Challenges
    • 📊 Performance Expectations
    • 🎯 Success Metrics
  • Scenario 09: Interactive Environments
    • 📋 The Problem
    • 💡 Solution with SmartAsync
    • 🎯 When to Use
    • ⚠️ Considerations
      • Notebook Best Practices
      • Teaching Async
      • Documentation Examples
      • When NOT to Use
    • 🔗 Related Scenarios
    • 📚 Interactive Tools
    • 🎯 Use Cases
      • Data Science
      • Education
      • API Development
      • Research
    • 🔍 Notebook Patterns
    • 📊 Comparison
    • 🎯 Success Metrics
    • 💡 Teaching Strategy

API Reference

  • @smartasync Decorator

Integrations

  • SmartSwitch Integration
    • Overview
    • Installation
    • Basic Usage
    • How It Works
      • Automatic Detection
    • Use Cases
      • Dynamic API Dispatching
      • Plugin Systems
    • Configuration
    • Requirements
    • Compatibility
    • Performance
    • See Also

Advanced Topics

  • SmartAsync - Technical Overview
    • What Is SmartAsync?
    • How It Works
      • Automatic Context Detection
      • Four Execution Scenarios
      • Implementation: Pattern Matching
    • Key Design Decisions
      • 1. Asymmetric Caching
      • 2. Pattern Matching Over Conditionals
      • 3. Thread Offloading for Sync-in-Async
    • Performance Characteristics
    • Primary Use Cases
      • 1. Sync App → Async Libraries
      • 2. Async App → Sync Libraries
      • 3. Unified Library API
    • Limitations
      • 1. Python 3.10+ Required
      • 2. Thread Pool Limits
      • 3. Thread-Local State
      • 4. Not Thread-Safe (by design)
    • Architecture
      • Decorator Flow
      • Caching Strategy
    • Testing
    • Comparison with Alternatives
    • Documentation Structure
    • Future Enhancements (Optional)
      • Configuration Options
      • Debug Mode
      • Loop Reuse Patterns
    • Summary
  • Comparison with Alternative Solutions
    • Overview
    • Existing Solutions
      • 1. asyncio.to_thread() (Python Stdlib 3.9+)
      • 2. asgiref.sync (Django Framework)
      • 3. anyio (Trio-compatible abstraction)
      • 4. asyncer (by Sebastián Ramírez - FastAPI author)
      • 5. nest_asyncio
    • Feature Comparison Matrix
    • What Makes SmartAsync Unique
      • 1. Automatic Context Detection
      • 2. Single Decorator for Both Directions
      • 3. Zero Configuration
      • 4. Pattern Matching Clarity
    • Unique Use Cases
      • 1. Testing Simplification
      • 2. Unified Library API
      • 3. Gradual Migration
    • When NOT to Use SmartAsync
      • 1. Need Fine-Grained Control
      • 2. Trio Support Required
      • 3. Nested Event Loops
      • 4. Python < 3.10
      • 5. Framework Integration
    • Performance Comparison
      • Overhead Analysis
    • Recommendations
      • Use SmartAsync When:
      • Use asgiref When:
      • Use anyio When:
      • Use asyncer When:
      • Use stdlib (asyncio.to_thread) When:
    • Summary
    • References
  • Performance
    • Overhead by Scenario
    • Real-World Impact
      • Network Requests
      • Database Queries
      • File I/O
    • When Overhead Matters
    • Optimization Tips
      • 1. Batch Operations
      • 2. Cache Results
      • 3. Use Async Context When Possible
    • Benchmarking
    • See Also
SmartAsync
  • Search

© Copyright 2025, Genropy Team.

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