feat: Add asyncio capture client

[marandaneto]

💡 Motivation and Context

Starts the stacked implementation for #103 by adding an asyncio-native client for event capture. This introduces AsyncClient / AsyncPosthog, async HTTP helpers, and an asyncio queue/consumer pipeline so async applications can enqueue and flush events without daemon threads.

This first PR intentionally focuses on the capture lifecycle and API shape. Async feature flag evaluation is stacked in the next PR. Review feedback was addressed by removing sensitive request/response payloads from async debug logs, running temporary sync flag fallback calls off the event loop, and parameterizing identify-method enqueue coverage.

💚 How did you test it?

• uv run ruff check posthog/async_client.py posthog/test/test_async_client.py
• uv run ruff check posthog/async_request.py posthog/test/test_async_request.py
• uv run --extra test pytest posthog/test/test_async_client.py posthog/test/test_async_request.py --verbose --timeout=30
• uv run python -W error -c "import posthog; from posthog import AsyncPosthog"
• uv run --extra dev python .github/scripts/check_public_api.py

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran sampo add to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Implemented with pi. The stack is split so reviewers can first inspect the async capture/queue/request foundation, then the async feature flag layer, then docs. httpx is added as an optional posthog[async] dependency and imported lazily so normal import posthog still works without the extra.

[github-actions]

posthog-python Compliance Report

Date: 2026-07-02 14:11:02 UTC
Duration: 177225ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	518ms
Format Validation.Event Has Uuid	✅	1507ms
Format Validation.Event Has Lib Properties	✅	1506ms
Format Validation.Distinct Id Is String	✅	1507ms
Format Validation.Token Is Present	✅	1507ms
Format Validation.Custom Properties Preserved	✅	1508ms
Format Validation.Event Has Timestamp	✅	1507ms
Retry Behavior.Retries On 503	✅	9515ms
Retry Behavior.Does Not Retry On 400	✅	3510ms
Retry Behavior.Does Not Retry On 401	✅	3508ms
Retry Behavior.Respects Retry After Header	✅	9514ms
Retry Behavior.Implements Backoff	✅	23528ms
Retry Behavior.Retries On 500	✅	7506ms
Retry Behavior.Retries On 502	✅	7512ms
Retry Behavior.Retries On 504	✅	7513ms
Retry Behavior.Max Retries Respected	✅	23519ms
Deduplication.Generates Unique Uuids	✅	1509ms
Deduplication.Preserves Uuid On Retry	✅	7513ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	14515ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7515ms
Deduplication.No Duplicate Events In Batch	✅	1504ms
Deduplication.Different Events Have Different Uuids	✅	1507ms
Compression.Sends Gzip When Enabled	✅	1507ms
Batch Format.Uses Proper Batch Structure	✅	1506ms
Batch Format.Flush With No Events Sends Nothing	✅	1006ms
Batch Format.Multiple Events Batched Together	✅	1505ms
Error Handling.Does Not Retry On 403	✅	3508ms
Error Handling.Does Not Retry On 413	✅	3508ms
Error Handling.Retries On 408	✅	7515ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	1004ms
Request Payload.Flags Request Uses V2 Query Param	✅	1006ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	1006ms
Request Payload.Flags Request Omits Authorization Header	✅	1007ms
Request Payload.Token In Flags Body Matches Init	✅	1007ms
Request Payload.Groups Round Trip	✅	1006ms
Request Payload.Groups Default To Empty Object	✅	1007ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	1006ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	1007ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	1007ms
Request Lifecycle.No Flags Request On Init Alone	✅	503ms
Request Lifecycle.No Flags Request On Normal Capture	✅	1509ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	1011ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	1002ms
Retry Behavior.Retries Flags On 502	✅	1007ms
Retry Behavior.Retries Flags On 504	✅	1006ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	1510ms

[greptile-apps]

Comments Outside Diff (1)

1. posthog/async_client.py, line 661-665 (link)

   Poller.stop() blocks the event loop during shutdown

   Poller.stop() calls self.join() on its underlying threading.Thread. If the poller thread is in the middle of executing a feature-flag poll request when shutdown() is called, this join() will block the event loop for up to feature_flags_request_timeout_seconds (default 3 s). The same risk applies to _shutdown_flag_definition_cache_provider() and _unregister_duplicate_client() if they perform any I/O or lock acquisition. Consider wrapping these with await asyncio.get_event_loop().run_in_executor(None, self.poller.stop) (and equivalents) so the event loop remains responsive during teardown.

_{Reviews (1): Last reviewed commit: "Avoid logging async request payloads" | Re-trigger Greptile}

[marandaneto]

Addressed the Greptile shutdown feedback in 43e6275 — async shutdown now offloads the inherited blocking cleanup path (Poller.stop(), flag cache provider shutdown, duplicate-client unregister) via asyncio.to_thread, with test coverage.

[marandaneto]

• feat: Add async feature flag evaluation #720
• docs: Document async SDK usage #721

related PRs for early feedback @dustinbyrne
wont finish before my PTO but i can get a pair of eyes so i can at least polish it a bit or learn if the idea is far from ideal