Skip to content

Commit 12892e4

Browse files
committed
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.
1 parent 0932672 commit 12892e4

2 files changed

Lines changed: 38 additions & 0 deletions

File tree

.github/pull_request_template.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
- [ ] I have added test coverage for new or changed functionality
44
- [ ] I have followed the repository's [pull request submission guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
55
- [ ] I have validated my changes against all supported platform versions
6+
- [ ] Sync/async parity: matching changes made to `async_*` siblings (or N/A)
67

78
**Related issues**
89

README.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,43 @@ This version of the LaunchDarkly SDK is compatible with Python 3.10+.
2020

2121
Refer to the [SDK reference guide](https://docs.launchdarkly.com/sdk/server-side/python) for instructions on getting started with using the SDK.
2222

23+
## Async support
24+
25+
> [!CAUTION]
26+
> 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.
27+
>
28+
> Pin to a specific minor version and review the changelog before upgrading.
29+
30+
> [!NOTE]
31+
> 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.
32+
33+
An async implementation, `AsyncLDClient`, is available for use with `asyncio`-based applications. It uses `aiohttp` for HTTP and requires installing the optional `async` extra:
34+
35+
```
36+
pip install launchdarkly-server-sdk[async]
37+
```
38+
39+
```python
40+
import asyncio
41+
from ldclient import Config, Context
42+
from ldclient.async_client import AsyncLDClient
43+
44+
async def main():
45+
async with AsyncLDClient(Config("sdk-key")) as client:
46+
value = await client.variation("my-flag", Context.create("user-key"), False)
47+
print(value)
48+
49+
asyncio.run(main())
50+
```
51+
52+
### Deployment
53+
54+
`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.
55+
56+
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.
57+
58+
This model fits ASGI servers. Create the client at application startup, and start it in the ASGI lifespan handler.
59+
2360
## Learn more
2461

2562
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).

0 commit comments

Comments
 (0)