appwrite / appwrite/sdk-generator
🚀 Feature: Native Asyncio Support for Python SDK
- Dominant language
- Twig
- Stars
- 325
- Forks
- 212
- Avg merge
- 7h 36m
- Merged PRs (30d)
- 91
Description
### 🔖 Feature description
I propose implementing native `asyncio` support for the Python SDK using a **Unified Client** architecture. Instead of introducing a separate `AsyncClient` or a `package.aio` submodule (which stalled previous attempts like PR #453), asynchronous capabilities should be integrated directly into the existing `Client` and Service classes.
**Core Implementation:**
1. A single `Client` object handles both workflows.
2. Every service method is generated in a "Dual-Mode" pair directly alongside each other:
- Synchronous: `def list(self, ...):`
- Asynchronous: `async def list_async(self, ...):`
3. We transition the underlying HTTP engine from `requests` to `httpx`, which natively supports both synchronous and asynchronous operations using an identical API shape, making the dual-mode generator templates trivial to maintain.
### 🎤 Pitch
The community has requested native Python async support for over two years (Issue [#26](https://github.com/appwrite/sdk-for-python/issues/26)). Implementing a unified "Dual-Mode" pattern solves the architectural friction that halted previous PRs:
1. **Maintainer Alignment:** It addresses the exact feedback provided by core contributors in PR #453, who requested that async methods live alongside sync methods without requiring users to instantiate a whole new `AsyncClient` class.
2. **Modern Developer Experience:** Frameworks like FastAPI, Starlette, and Sanic are now standard. Developers must be able to `await client.users.list_async()` natively without blocking the event loop or hacking together `ThreadPoolExecutors`.
3. **Zero Maintenance Drift:** By utilizing Twig `parameterDispatchBlock` filters in the generator (similar to the new dual-mode C++ SDK), the synchronous and asynchronous methods are generated from the exact same spec source. They will never fall out of sync as the API evolves.
4. **100% Backwards Compatible:** Existing code using `requests` semantics remains totally unaffected since standard `def` methods will work exactly as they did before.
### 👀 Have you spent some time to check if this issue has been raised before?
- [x] I checked and didn't find similar issue
### 🏢 Have you read the Code of Conduct?
- [x] I have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/HEAD/CODE_OF_CONDUCT.md)
Contributor guide
Research direction
Start by tracing the Python SDK generator and its existing Client and Service generation paths, then review PR #453 and the Twig parameterDispatchBlock reference named in the issue. Done means one Client exposes paired synchronous and asynchronous service methods, uses the proposed httpx transition, and preserves existing synchronous behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100