Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
57 commits
Select commit Hold shift + click to select a range
698b3a4
chore: add major changeset for posthog 8.0 capture v1 release
eli-r-ph Oct 6, 2026
5b43ec7
feat!: send capture through v1 by default; capture_ai to /i/v1/ai/eve…
eli-r-ph Oct 10, 2026
8da46d8
feat!: remove capture v0 and legacy transport options (#1018)
eli-r-ph Oct 10, 2026
29225eb
refactor!: split capture_v1 into capture_event and capture_send (#1019)
eli-r-ph Oct 10, 2026
20fdb14
feat!: report capture v1 results through CaptureError and on_error (#…
eli-r-ph Oct 10, 2026
a15eff4
feat: AI lane config and size-aware batching (#1022)
eli-r-ph Oct 10, 2026
252886c
test(mcp): fix get_tool checks for fastmcp 4.0.11 (#1050)
eli-r-ph Oct 14, 2026
305e74e
feat!: add per-event capture options (#1023)
eli-r-ph Oct 14, 2026
4cc19c1
feat!: add global and context option layers (#1024)
eli-r-ph Oct 14, 2026
f4b67b5
feat!: AI and MCP send personless as an event option (#1025)
eli-r-ph Oct 14, 2026
49399ed
chore(ci): run compliance harness 1.13.1 once per codec (#1026)
eli-r-ph Oct 14, 2026
dd9c122
feat!: AI wrappers always send through capture_ai (#1027)
eli-r-ph Oct 14, 2026
ed296dc
feat: add an AI capture lane to AsyncPosthog (#1028)
eli-r-ph Oct 14, 2026
5ec93d0
test: cover capture invariants on both lanes (#1029)
eli-r-ph Oct 14, 2026
63d3204
docs: 8.0 migration guide and openfeature-provider pin (#1030)
eli-r-ph Oct 20, 2026
331ae32
feat!: MCP no longer relabels the client SDK identity (#1034)
eli-r-ph Oct 20, 2026
2343064
fix!: follow capture redirects only to the same origin (#1035)
eli-r-ph Oct 20, 2026
0e7afbb
chore: sync main into v1 (7.65.0–7.67.0) (#1044)
eli-r-ph Oct 20, 2026
4d32397
feat!: exception level, keyword-only args, uuid and geoip (#1046)
eli-r-ph Oct 20, 2026
bddc729
fix(ai)!: AI integrations require a client with capture_ai (#1048)
eli-r-ph Oct 20, 2026
d5b29f1
chore: sync main into v1 (7.67.1–7.68.0) (#1051)
eli-r-ph Oct 20, 2026
fc04fbc
fix!: drop only the invalid event, not its whole batch (#1052)
eli-r-ph Oct 22, 2026
980f703
fix!: group_identify and alias never guess a distinct id (#1053)
eli-r-ph Oct 22, 2026
6fb23f9
fix: spread capture retry waits by up to 25% (#1058)
eli-r-ph Oct 22, 2026
f18160c
fix: read tracing headers by default in v1 integrations (port of #106…
eli-r-ph Oct 22, 2026
9972f15
fix: report capture's dropped duplicate copies as drops (#1113)
eli-r-ph Oct 23, 2026
a06ac45
docs: mark the migration guide to link the public capture v1 guide (#…
eli-r-ph Oct 23, 2026
c587bdb
chore: sync main into v1 (7.69.0–7.75.6) (#1120)
eli-r-ph Oct 23, 2026
537190e
fix: fill feature flag properties below context tags and super proper…
eli-r-ph Oct 23, 2026
cfdb4ec
fix: own capture connection retries and redact hook error logs (#1125)
eli-r-ph Oct 27, 2026
06fbd90
fix: fill OpenTelemetry trace IDs below context tags and super proper…
eli-r-ph Oct 27, 2026
327f50b
fix: add OpenTelemetry span IDs to async capture_exception (#1123)
eli-r-ph Oct 27, 2026
150a6fe
fix: retry capture requests that get 404 or 429 (#1132)
eli-r-ph Oct 27, 2026
2a2f26d
test: an event JSON cannot serialize is dropped alone (#1138)
eli-r-ph Oct 28, 2026
fd1f241
chore: run the capture v1 compliance suites from harness 1.25.0 (#1137)
eli-r-ph Oct 28, 2026
875a1f6
chore: run the capture v1 compliance suites from harness 1.26.0 (#1142)
eli-r-ph Oct 29, 2026
3f429dd
chore: sync main into v1 (7.75.7–7.81.1) (#1169)
eli-r-ph Nov 2, 2026
4d54d2b
fix(ai): treat an empty or whitespace distinct id as missing in AI in…
eli-r-ph Nov 2, 2026
3f37e3d
docs: ask users to review before_send hooks for the v1 event shape (#…
eli-r-ph Nov 2, 2026
4f2b004
fix: whole-second timestamps and 8.0 migration guide gaps (#1168)
eli-r-ph Nov 3, 2026
db98af0
chore: sync main into v1 (7.81.2–7.82.2) (#1174)
eli-r-ph Nov 4, 2026
0b637fc
chore: sync main into v1 (7.83.0–7.83.1, flags v4) (#1175)
eli-r-ph Nov 4, 2026
504e50d
feat!: send $lib and $lib_version per event; MCP event options, Celer…
eli-r-ph Nov 9, 2026
4f60c33
docs: show how to keep identity calls under a global personless setti…
eli-r-ph Nov 11, 2026
994adb7
chore: merge main into v1 up to 7.86.x (emails, MCP alignment, flags,…
eli-r-ph Nov 11, 2026
c9185bd
chore: merge main into v1 (7.87.0-7.87.1: $experiment_exposure, IPv6 …
eli-r-ph Nov 11, 2026
268c613
docs: regenerate the 8.x and migration references from this branch
eli-r-ph Nov 11, 2026
80563b2
test(benchmarks): run the paired benchmarks against capture v1
eli-r-ph Nov 11, 2026
c5e8ca1
docs: drop the GitHub link from the 8.0 guide's Celery eager note (#1…
eli-r-ph Nov 12, 2026
0ded23d
docs: pin the reference install line to the page's major (#1234)
eli-r-ph Nov 12, 2026
3e804b9
feat!: default identify-style events to person processing on (#1247)
eli-r-ph Nov 16, 2026
dd8ad56
chore: merge main (v7.87.2-v7.91.2) into v1
eli-r-ph Nov 16, 2026
c8ab322
docs: regenerate the 8.x reference with main's new API
eli-r-ph Nov 16, 2026
018d15d
chore: merge main (#1257) into v1
eli-r-ph Nov 16, 2026
ea491a7
chore: merge main into v1 (to 36027e3c)
eli-r-ph Nov 17, 2026
e2b12f8
fix: skip an already-captured sys.exc_info() exception in capture_exc…
eli-r-ph Nov 17, 2026
c9f67fa
fix: AI options on streaming connect errors; benchmark baseline route…
eli-r-ph Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 74 additions & 21 deletions .github/workflows/sdk-compliance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@ name: SDK Compliance Tests

permissions:
contents: read
packages: read
pull-requests: write

on:
pull_request:
Expand All @@ -23,26 +21,81 @@ jobs:
with:
python-version: "3.12"
- name: Install adapter and test dependencies
run: python -m pip install -e . -r sdk_compliance_adapter/requirements.txt pytest pytest-timeout pytest-asyncio
run: python -m pip install -e ".[zstd]" -r sdk_compliance_adapter/requirements.txt pytest pytest-timeout pytest-asyncio
- name: Test adapter protocol
run: python -m pytest sdk_compliance_adapter/test_adapter.py --timeout=30

compliance:
name: PostHog SDK compliance tests (capture v0)
uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@003d4162421193b458bbaa93fbb7bb0d0104bc3b # 1.31.1
with:
adapter-dockerfile: "sdk_compliance_adapter/Dockerfile"
adapter-context: "."
test-harness-version: "1.31.1"
continue-on-error: false
report-name: "sdk-compliance-report-v0"

compliance-v1:
name: PostHog SDK compliance tests (capture v1)
uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@003d4162421193b458bbaa93fbb7bb0d0104bc3b # 1.31.1
with:
adapter-dockerfile: "sdk_compliance_adapter/Dockerfile.v1"
adapter-context: "."
test-harness-version: "1.31.1"
continue-on-error: false
report-name: "sdk-compliance-report-v1"
# The harness has one enable_compression flag but a test per codec, so each
# job runs the adapter with one codec. The reusable harness workflow cannot
# pass the COMPRESSION env var, so this job runs the containers directly.
# The SDK has no brotli support, so there is no br job.
name: PostHog SDK compliance tests (${{ matrix.compression }})
runs-on: ubuntu-latest
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
compression: [gzip, deflate, zstd]
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ matrix.compression }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
env:
HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness:1.31.1@sha256:f84d5c70dd72ea4436957ea6dbbc1f6836b6f6cbb472c749711d0f3659d85377
steps:
- name: Check out source code
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Pull test harness
run: docker pull "$HARNESS_IMAGE"

- name: Build SDK adapter
run: docker build -f sdk_compliance_adapter/Dockerfile -t sdk-adapter:test .

- name: Start SDK adapter
run: |
docker network create test-network
docker run -d \
--name sdk-adapter \
--network test-network \
-e COMPRESSION=${{ matrix.compression }} \
sdk-adapter:test

- name: Run compliance suite
run: |
mkdir -p report
docker run --rm \
--name test-harness \
--network test-network \
-v "${GITHUB_WORKSPACE}/report:/report" \
"$HARNESS_IMAGE" \
run \
--adapter-url http://sdk-adapter:8080 \
--mock-url http://test-harness:8081 \
--output text \
--report /report/sdk-compliance-report.md \
--sdk-type server

- name: Publish report to the job summary
if: always()
run: |
if [ -f report/sdk-compliance-report.md ]; then
cat report/sdk-compliance-report.md >> "$GITHUB_STEP_SUMMARY"
fi

- name: Upload compliance report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: sdk-compliance-report-${{ matrix.compression }}
path: report/sdk-compliance-report.md

- name: Show adapter logs on failure
if: failure()
run: docker logs sdk-adapter || true

- name: Stop containers
if: always()
run: |
docker rm -f sdk-adapter || true
docker network rm test-network || true
5 changes: 5 additions & 0 deletions .sampo/changesets/ai-blank-distinct-id-personless.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: patch
---

AI integrations (LLM wrappers, embeddings, LangChain and OpenAI Agents) treat an empty or whitespace-only `distinct_id` as missing, as the client does: the event uses its trace or run ID and is personless. Before, an empty ID gave streaming calls, embeddings and LangChain the trace or run ID with person processing on, so PostHog created a person for each trace or run. Non-streaming wrapper calls used a random personless ID, and OpenAI Agents already treated an empty ID as missing. A whitespace-only ID was sent as given.
5 changes: 5 additions & 0 deletions .sampo/changesets/ai-integrations-require-capture-ai.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

The AI integrations no longer fall back to `capture` for a client object without `capture_ai`. Creating an OpenAI, Anthropic or Gemini wrapper, the LangChain `CallbackHandler`, or the OpenAI Agents or Claude Agent SDK processor with such a client now logs one error and captures no AI events. Provider calls still work. The error shows up when you set the integration up, and not after a provider call. A `Client` or `AsyncPosthog` instance, and the default global client, work as before.
5 changes: 5 additions & 0 deletions .sampo/changesets/ai-posthog-options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: minor
---

AI integrations take capture options. Every wrapper method that takes `posthog_properties` also takes `posthog_options` (OpenAI, Anthropic, Gemini, sync and async, and the Claude Agent SDK `query()` and `PostHogClaudeSDKClient`), and the Gemini clients take it as a default for every call. LangChain's `CallbackHandler` and `PostHogMiddleware`, and `instrument()` and the tracing processors for OpenAI Agents and the Claude Agent SDK, take `options=`. LangChain also reads `posthog_options` from run metadata. These options win over context options and `super_options`. An event without a distinct ID still always sends `process_person_profile: False`, and a value that is not a dict is logged and ignored.
5 changes: 5 additions & 0 deletions .sampo/changesets/async-exception-span-ids.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: minor
---

`AsyncPosthog.capture_exception` now adds the active OpenTelemetry span's `$trace_id` and `$span_id`, like `Client.capture_exception`, even when `capture_trace_context` is off.
5 changes: 5 additions & 0 deletions .sampo/changesets/call-disable-geoip-event-value.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

A `disable_geoip` argument to a call now counts as a value of that event. It wins over a `$geoip_disable` in context tags or `super_properties`, and a `$geoip_disable` in the call's own `properties` still wins over it. `disable_geoip=False` now sends `$geoip_disable: false`, so it turns GeoIP lookup on for that event even when a context tag or `super_properties` turns it off. The client's `disable_geoip` setting keeps its place below every caller value. `AsyncPosthog` follows the same rules.
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
pypi/posthog: patch
---

Capture makes one connection try per attempt, so every physical request carries its own attempt number and request timestamp. posthog-python 7.x.x also retried a failed connection up to twice inside each attempt, reusing the request timestamp, which shifted the events' stored time by the time spent connecting.

When `before_send` raises, the error line names the event and the exception type, not the exception message. The traceback is logged at debug level.

Events without `NaN` or `Infinity` are encoded once, without first copying them to replace non-finite numbers. Events that contain them still send those values as `null`.
5 changes: 5 additions & 0 deletions .sampo/changesets/capture-retry-404-429.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: patch
---

Capture retries `404` and `429` responses like `408` and `500`, `502`, `503`, `504`, with the same backoff and `Retry-After` handling.
5 changes: 5 additions & 0 deletions .sampo/changesets/capture-retry-jitter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: patch
---

Capture retry waits now vary randomly by up to 25%, so many clients do not retry at the same moment.
5 changes: 5 additions & 0 deletions .sampo/changesets/capture-same-origin-redirects.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

Capture follows a `307` or `308` redirect only to the origin of `host`, at most 5 times, for the sync and async clients. Any other redirect fails the batch and reaches `on_error`. In posthog-python 7.x.x the sync client followed redirects to any origin and resent the event batch there.
5 changes: 5 additions & 0 deletions .sampo/changesets/capture-timestamp-fraction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: patch
---

Capture timestamps always have six fractional-second digits, even on a whole second: `2026-01-02T03:04:05.000000+00:00`, not `2026-01-02T03:04:05+00:00`. This applies to the event `timestamp`, the batch `created_at` and the `PostHog-Request-Timestamp` header. The `timestamp` that `before_send` receives has the same format.
5 changes: 5 additions & 0 deletions .sampo/changesets/capture-v1-major.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

Capture v1 is the only capture path. Events and AI events send to the capture v1 endpoints, and the legacy v0 capture path is removed. See the [migration guide](https://github.com/PostHog/posthog-python/blob/main/docs/migration-7.x-to-8.0.md) for breaking changes.
5 changes: 5 additions & 0 deletions .sampo/changesets/celery-context-options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: minor
---

The Celery integration propagates context options from the publisher to the worker, like tags. Options set with `set_context_option` before a task is published apply to every event captured while the task runs. `propagate_context=False` sends none of them.
5 changes: 5 additions & 0 deletions .sampo/changesets/duplicate-event-uuid.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: patch
---

Capture keeps the first event for each uuid in a request and drops the later copies. `on_error` now reports each dropped copy in `CaptureError.drops` as `(uuid, "duplicate_event_uuid")`, and the SDK does not resend it. Each entry of `CaptureError.drops` is a `CaptureDroppedEvent` from `posthog.capture_send`, a tuple that also has `uuid` and `details` fields. `verdict_summary()` counts each drop by its own reason.
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

`capture_exception` takes a `level=` argument on `Client`, `AsyncPosthog` and the module, which sets `$exception_level` (default `"error"`). Reserved exception properties passed in `properties`, such as `$exception_list` and `$exception_level`, are now ignored. In posthog-python 7.x.x they overrode the SDK's values with a `DeprecationWarning`. `AsyncPosthog.capture_exception` now sends `$exception_level`.
5 changes: 5 additions & 0 deletions .sampo/changesets/identity-and-context-rules.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

`group_identify` falls back to the context distinct ID and then to `$<group_type>_<group_key>` instead of a random ID, and no longer adds the context session ID. `alias()` no longer takes its target from the context distinct ID. Context tags and options now apply to `alias` and `group_identify`, but context tags, context options, `super_options` and `super_properties` do not set `process_person_profile` on identify-style events (`$identify`, `$create_alias`, `$merge_dangerously`, `$groupidentify`, `$set` and `$set_once`) whose distinct ID the SDK did not generate. Those events default to `True` unless the call sets it. An empty or whitespace-only `distinct_id` counts as missing, and generated personless distinct IDs are UUIDv7. `AsyncPosthog` follows the same rules.
5 changes: 5 additions & 0 deletions .sampo/changesets/invalid-events-and-sizes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

An invalid event no longer costs the rest of its batch. An event with a missing, empty or non-string name, or with a non-string `distinct_id` after `before_send`, is dropped locally, an event that cannot be serialized is dropped alone (a non-finite float such as `NaN` is still sent as `null`), and a property key JSON cannot represent is dropped from its event. The analytics per-event limit is now capture's 10 MiB request limit instead of 900 KiB. A personal API key (`phx_...`) disables the client like an empty key. The SDK's own log lines no longer include event content or invalid timestamp values. `AsyncPosthog` follows the same rules.
5 changes: 5 additions & 0 deletions .sampo/changesets/invalid-uuid-warning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

An invalid event `uuid` is still replaced with a generated one, but the SDK now logs one warning instead of an error, and the warning no longer includes the value. An empty string `uuid` counts as unset, so the SDK generates one without logging. `AsyncPosthog` follows the same rules.
5 changes: 5 additions & 0 deletions .sampo/changesets/lib-is-an-sdk-value.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

Events send `$lib` and `$lib_version` as they are at send time, whoever set them. If no `$lib` is set in the call's `properties`, a context tag or `super_properties`, the SDK sets both to `posthog-python` and the installed version. If `$lib` is `posthog-python` and `$lib_version` is missing, the SDK fills in the version. A `$lib` that names another library is sent with whatever `$lib_version` it has, so set both when you override them. Only a non-empty string counts as set. In posthog-python 7.x.x the SDK overwrote a `$lib` or `$lib_version` set in a call or a context tag. `before_send` can still change or remove both, and `AsyncPosthog` follows the same rules.
5 changes: 5 additions & 0 deletions .sampo/changesets/mcp-event-options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: minor
---

MCP events take capture options. The `PostHogMCP` capture methods and `McpAnalytics.capture` take an `event_options` argument, and `MCPAnalyticsOptions(event_options=...)` sets options on every event `instrument()` captures automatically, from a function of `(request, extra)` like `event_properties`. An event without an identity still always sends `process_person_profile: False`. `PostHogMCP.capture()` keeps the core client's `options` argument.
5 changes: 5 additions & 0 deletions .sampo/changesets/mcp-keeps-sdk-identity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

MCP instrumentation no longer relabels the whole client. In posthog-python 7.x.x, `posthog.mcp.instrument()` and `PostHogMCP` changed `$lib` on every event the client sent, including the app's own, and the SDK name in its request headers, feature flag requests included. `instrument()` without a client relabeled the global client. Now only MCP analytics events report `posthog-python-mcp`, and everything else reports `posthog-python`. The label is set in each MCP event's own properties, so a `$lib` in `super_properties` no longer replaces it. `before_send` can.
5 changes: 5 additions & 0 deletions .sampo/changesets/openfeature-provider-posthog-8.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/openfeature-provider-posthog: minor
---

Supports posthog-python 8.x.x as well as 7.x.x.
5 changes: 5 additions & 0 deletions .sampo/changesets/request-keyword-only.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

The parameters after `path` in `posthog.request.post` and after `host` in `posthog.request.flags` are keyword-only. With `gzip` removed, a posthog-python 7.x.x call that passed them by position bound them to the wrong parameter. It now raises `TypeError`.
5 changes: 5 additions & 0 deletions .sampo/changesets/session-id-drop-warning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

A `$session_id` or `$window_id` that is not a string is not sent, because capture v1 would reject the whole batch, and the SDK logs a warning for each one. The warning names the key and the value's type, not the value. `None` counts as unset and drops without a warning. An empty string is sent. In posthog-python 7.x.x these values were sent as properties.
5 changes: 5 additions & 0 deletions .sampo/changesets/trace-ids-as-sdk-values.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: major
---

The `$trace_id` and `$span_id` that the SDK takes from the active OpenTelemetry span now fill after the call's `properties`, context tags and `super_properties`, and before `before_send`. A `$trace_id` or `$span_id` in a context tag or `super_properties` now replaces the span's IDs, and setting either key stops the SDK adding both. `AsyncPosthog` follows the same rules.
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Follow [Public API changes](./CONTRIBUTING.md#public-api-changes). As an agent,

Before changing capture configuration, serialization, routing, or retries, read the relevant implementation and tests.

Preserve v0 defaults/compatibility; strictly typed v1 options and `$set`/`$set_once` relocation; v1-only compression (zlib-wrapped deflate, optional zstd); partial-only per-event retries with stable identity; accumulated drop reporting even on 2xx; v1 retries on `404` and `429` like `408` and 5xx; `Retry-After` as a minimum bounded by the shared 30s ceiling; and inline blocking retries with `sync_mode=True`.
Capture v1 is the only capture protocol (`capture` posts to `/i/v1/analytics/events`, `capture_ai` to `/i/v1/ai/events`); per-event `options` sent as given, layered over `super_options` and context options, with legacy `$` option properties hoisted once after `before_send` (identify-style events instead resolve `process_person_profile` from the call before any layer, default it to `true` unless the SDK generated the distinct ID, and drop `$process_person_profile` before `before_send` once the option is set); `$set`/`$set_once` relocation; compression (gzip, zlib-wrapped deflate, optional zstd, default none), set per lane by `capture_compression` and `capture_ai_compression`; partial-only per-event retries with stable identity; accumulated drop reporting even on 2xx; terminal v1 `429`; `Retry-After` as a minimum bounded by the shared 30s ceiling; and inline blocking retries with `sync_mode=True`.

## Mirror and build safety

Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ uv sync --extra dev --extra test

## CI-aligned checks

Run the smallest relevant tests first, for example `pytest posthog/test/test_capture_v1.py --timeout=30` for v1 transport changes. Then run these core CI-aligned checks from the repository root in the activated `.venv` populated by the setup commands above:
Run the smallest relevant tests first, for example `pytest posthog/test/test_capture_send.py --timeout=30` for v1 transport changes. Then run these core CI-aligned checks from the repository root in the activated `.venv` populated by the setup commands above:

```bash
ruff format --check .
Expand Down
12 changes: 8 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,21 @@ SDK usage examples and code snippets live in the official documentation so they

| SDK Version | Python Versions Supported | Notes |
| ------------- | ---------------------------- | -------------------------- |
| 7.3.1+ | 3.10, 3.11, 3.12, 3.13, 3.14 | Added Python 3.14 support |
| 8.0.0+ | 3.10, 3.11, 3.12, 3.13, 3.14 | Capture v1 only |
| 7.3.1 - 7.x.x | 3.10, 3.11, 3.12, 3.13, 3.14 | Added Python 3.14 support |
| 7.0.0 - 7.0.1 | 3.10, 3.11, 3.12, 3.13 | Dropped Python 3.9 support |
| 4.0.1 - 6.x | 3.9, 3.10, 3.11, 3.12, 3.13 | Python 3.9+ required |
| 4.0.1 - 6.x.x | 3.9, 3.10, 3.11, 3.12, 3.13 | Python 3.9+ required |

To upgrade from posthog-python 7.x.x to 8.0.0, see the [migration guide](docs/migration-7.x-to-8.0.md).

## Documentation

- [Python library docs](https://posthog.com/docs/libraries/python)
- [Migrating from posthog-python 7.x.x to 8.0.0](docs/migration-7.x-to-8.0.md)
- [Django framework docs](https://posthog.com/docs/libraries/django)
- [Flask framework docs](https://posthog.com/docs/libraries/flask)
- [Request integration configuration](references/middleware_configuration.md) — shared middleware options and compatibility notes
- [OpenFeature provider docs](https://posthog.com/docs/feature-flags/installation/openfeature) — use PostHog flags through the [OpenFeature](https://openfeature.dev) Python SDK
- [Request integration configuration](references/middleware_configuration.md), with shared middleware options and compatibility notes
- [OpenFeature provider docs](https://posthog.com/docs/feature-flags/installation/openfeature), to use PostHog flags through the [OpenFeature](https://openfeature.dev) Python SDK

## Contributing

Expand Down
Loading
Loading