From 12892e48fc24a6c46335ff65b3247e8548ecdd46 Mon Sep 17 00:00:00 2001 From: jsonbailey Date: Fri, 28 Aug 2026 15:34:00 -0500 Subject: [PATCH 1/2] docs: Add an async support section to the README Document the experimental AsyncLDClient: the caution about its experimental status, the redis>=4.2 requirement for async Redis, the [async] install extra, a usage example, and a deployment note (single event loop, construct once + start per worker loop, ASGI lifespan). Also add a sync/async parity checkbox to the PR template so changes to a sync file prompt matching async updates. --- .github/pull_request_template.md | 1 + README.md | 37 ++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index fc89ce0f..a0f0be7d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -3,6 +3,7 @@ - [ ] I have added test coverage for new or changed functionality - [ ] I have followed the repository's [pull request submission guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests) - [ ] I have validated my changes against all supported platform versions +- [ ] Sync/async parity: matching changes made to `async_*` siblings (or N/A) **Related issues** diff --git a/README.md b/README.md index db121c86..4826a6d8 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,43 @@ This version of the LaunchDarkly SDK is compatible with Python 3.10+. Refer to the [SDK reference guide](https://docs.launchdarkly.com/sdk/server-side/python) for instructions on getting started with using the SDK. +## Async support + +> [!CAUTION] +> The async implementation (`AsyncLDClient` and its associated async API) is experimental and should NOT be considered ready for production use. It may change or be removed without notice and is not subject to backwards compatibility guarantees. +> +> Pin to a specific minor version and review the changelog before upgrading. + +> [!NOTE] +> Using Redis with the async client (big segments or a persistent data store) requires `redis>=4.2.0`, the version that introduced `redis.asyncio`. The `redis` extra itself still permits older versions for synchronous use, so install `redis>=4.2.0` when using Redis with the async client. + +An async implementation, `AsyncLDClient`, is available for use with `asyncio`-based applications. It uses `aiohttp` for HTTP and requires installing the optional `async` extra: + +``` +pip install launchdarkly-server-sdk[async] +``` + +```python +import asyncio +from ldclient import Config, Context +from ldclient.async_client import AsyncLDClient + +async def main(): + async with AsyncLDClient(Config("sdk-key")) as client: + value = await client.variation("my-flag", Context.create("user-key"), False) + print(value) + +asyncio.run(main()) +``` + +### Deployment + +`AsyncLDClient` runs on the caller's event loop. It targets a single event loop and is not thread-safe. Use one client for the whole application. + +The constructor does not need a running event loop. So you can create the client once, before the application forks or preloads its workers. Then start the client on each worker's event loop with `await client.start()`. You can also use `async with AsyncLDClient(config) as client:`, which starts and closes the client for you. + +This model fits ASGI servers. Create the client at application startup, and start it in the ASGI lifespan handler. + ## Learn more Read our [documentation](http://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [complete reference guide for this SDK](http://docs.launchdarkly.com/docs/python-sdk-reference). From 564868af0886199875c116698d1c2cb90001ce55 Mon Sep 17 00:00:00 2001 From: jsonbailey Date: Fri, 28 Aug 2026 15:36:41 -0500 Subject: [PATCH 2/2] docs: Rename the async Deployment heading to Event loop --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4826a6d8..2218388d 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ async def main(): asyncio.run(main()) ``` -### Deployment +### Event loop `AsyncLDClient` runs on the caller's event loop. It targets a single event loop and is not thread-safe. Use one client for the whole application.