Add async request handling with tracking IDs#3
Merged
thorwhalen merged 3 commits intomasterfrom Nov 19, 2025
Merged
Conversation
Implements boilerplate-minimal async task processing for long-running operations.
Clients can now choose between synchronous (blocking) and asynchronous (task-based) execution.
## Key Features
### Core Async Functionality
- Task-based async execution with unique task IDs
- Client-controlled sync/async mode via query param or header
- Standard HTTP patterns for task management
- Built-in task status tracking and result retrieval
- Support for both sync and async Python functions
### Task Management
- Automatic task management endpoints:
- GET /tasks/ - List all tasks
- GET /tasks/{id} - Get complete task info
- GET /tasks/{id}/status - Get task status
- GET /tasks/{id}/result - Get result (with optional wait)
- DELETE /tasks/{id} - Cancel/delete task
### Flexible Configuration
- Simple case: just specify `async_funcs=['function_name']`
- Advanced: per-function TaskConfig with custom executors
- Multiple execution backends:
- ThreadPoolTaskExecutor (I/O-bound tasks)
- ProcessPoolTaskExecutor (CPU-bound tasks)
- Custom executors via TaskExecutor interface
- Pluggable storage backends via TaskStore interface
- TTL-based result expiration
### Developer Experience
- Convention-based with escape hatches
- Zero external dependencies (uses stdlib)
- Fully backward compatible
- Comprehensive test coverage (16 tests)
- Ready for au package integration
## Implementation Details
### New Modules
- `qh/async_tasks.py` - Core task management, stores, and executors
- `qh/async_endpoints.py` - HTTP endpoints for task management
- `qh/async_example.py` - Comprehensive usage examples
- `qh/tests/test_async_tasks.py` - Full test suite
### Modified Modules
- `qh/app.py` - Added async_funcs and async_config parameters to mk_app
- `qh/config.py` - Added async_config field to RouteConfig
- `qh/endpoint.py` - Added async execution logic to endpoint creation
- `qh/__init__.py` - Exported async task classes and functions
### API Examples
Simple case:
```python
app = mk_app([expensive_func], async_funcs=['expensive_func'])
# POST /expensive_func?async=true -> Returns task_id
```
Advanced configuration:
```python
app = mk_app(
[cpu_func, io_func],
async_funcs=['cpu_func', 'io_func'],
async_config={
'cpu_func': TaskConfig(
executor=ProcessPoolTaskExecutor(max_workers=4),
ttl=3600
),
'io_func': TaskConfig(async_mode='always')
}
)
```
## Design Philosophy
Following qh's "convention over configuration" approach:
- Default conventions use thread pools and query params
- Explicit configuration available for all aspects
- Built on standard patterns (HTTP 202 Accepted, polling)
- No external dependencies required (au integration optional)
## Testing
All 16 async tests passing:
- Basic sync/async execution
- Task status and result retrieval
- Failed task handling
- Multiple configuration modes (query, header, always)
- TTL and cleanup
- Native async functions
- Task management endpoints
- Multiple function support
## Documentation
Comprehensive README update with:
- Quickstart examples
- Advanced configuration
- Real-world use cases
- Migration guide
- Comparison with other frameworks
- au package integration guide
## Future Enhancements
The implementation is designed to support:
- Integration with au package for distributed execution
- Custom storage backends (Redis, database, etc.)
- WebSocket-based result streaming
- Task prioritization and scheduling
- Task dependencies and workflows
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.