Product Updates
Cleaner async Python SDKs with constructor-based approach
David Adler
October 1, 2025 - 2 min read
Python SDK generation now supports a constructor-based approach for handling synchronous and asynchronous operations. This eliminates method name duplication and provides a cleaner interface for SDK users.
Same functionality, new interface
Previously, Python SDKs used a method-based approach where every operation had two methods: a synchronous version and an asynchronous version with an _async suffix. This approach created several issues:
- Method name pollution: Every operation appeared twice in autocomplete and documentation
- Naming confusion: The
_asyncsuffix was awkward and non-standard - Unclear intent: The SDK interface didn’t clearly communicate which mode it was in
The new approach uses separate constructors for synchronous and asynchronous clients. All method names are now identical between sync and async versions. The choice happens once at instantiation, not repeatedly for every method call.
Old approach: method-based
New approach: constructor-based
The constructor pattern for handling async is more Pythonic with the added benefits of improved IDE suggestions (no duplicate method names) and enforcing clear user intent by making async usage a more explicit choice.
Configuring the new behavior
Constructor-based async can be enabled in your gen.yaml file:
The asyncMode setting accepts two values:
both(default): Method-based approach with_asyncsuffixessplit: Constructor-based approach with separate classes
Breaking change
Switching to asyncMode: split is a breaking change. Existing SDK users will need to update their code to use the new constructor pattern.
Why this matters
Python’s async ecosystem uses an event loop to manage non-blocking I/O operations, similar to JavaScript’s event model. However, async functions in Python aren’t easily interoperable with synchronous functions — async code “colors” all the functions it touches.
While async is increasingly popular, synchronous code remains the default for many Python applications. Supporting both patterns cleanly requires a clear separation at the SDK level, which constructor-based async provides.
This change aligns Python SDK generation with patterns used by established Python libraries and provides a more intuitive interface for developers familiar with Python’s async conventions.