Product Updates

Cleaner async Python SDKs with constructor-based approach

David Adler

October 1, 2025 - 2 min read

Product Updates

---

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 _async suffix 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.

sdk = MyAPI(api_key="...")
 
# Synchronous operations
result = sdk.list_users()
 
# Asynchronous operations
result = await sdk.list_users_async()

# Synchronous client
sync_sdk = MyAPI(api_key="...")
result = sync_sdk.list_users()
 
# Asynchronous client
async_sdk = AsyncMyAPI(api_key="...")
result = await async_sdk.list_users()

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:

python:
  version: 1.0.0
  asyncMode: split  # Use constructor-based approach

The asyncMode setting accepts two values:

• both (default): Method-based approach with _async suffixes
• split: Constructor-based approach with separate classes

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.

Additional resources

• Python SDK generation design
• Gen.yaml configuration reference