diff --git a/README.md b/README.md index 3f0fad6..ef1743d 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![Go Reference](https://pkg.go.dev/badge/github.com/patch-it-dev/patch-it-plugins.svg)](https://pkg.go.dev/github.com/patch-it-dev/patch-it-plugins) [![Go version](https://img.shields.io/github/go-mod/go-version/patch-it-dev/patch-it-plugins)](go.mod) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-3f5bf0)](LICENSE) -[![Plugins](https://img.shields.io/badge/plugins-21-3f5bf0)](docs/plugins.md) +[![Plugins](https://img.shields.io/badge/plugins-22-3f5bf0)](docs/plugins.md) [![Docs](https://img.shields.io/badge/docs-docs.patch--it.dev-3f5bf0)](https://docs.patch-it.dev) [![Discussions](https://img.shields.io/github/discussions/patch-it-dev/patch-it-plugins)](https://github.com/patch-it-dev/patch-it-plugins/discussions) diff --git a/docs/plugins.json b/docs/plugins.json index 31ad65e..2f2fdf8 100644 --- a/docs/plugins.json +++ b/docs/plugins.json @@ -1,7 +1,7 @@ { "_comment": "Generated from the plugin registry and docs/plugins.md by `make plugins-json` (go run ./cmd/list-plugins). Don't edit by hand.", "$schema": "./plugins.schema.json", - "count": 21, + "count": 22, "plugins": [ { "id": "algolia-ingestion", @@ -143,6 +143,16 @@ "status": "live", "provider_page": "providers/openai-models.md" }, + { + "id": "posthog", + "provider": "PostHog", + "layer": "sdk", + "watches": "Members removed in the posthog Python SDK 8.0.0", + "format": "removedmembers", + "source_url": "https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md", + "status": "live", + "provider_page": "providers/posthog.md" + }, { "id": "redis", "provider": "Redis", diff --git a/docs/plugins.md b/docs/plugins.md index 7283a01..172cf70 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -30,6 +30,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe | [`vertex-ai-models`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/vertex-ai-models.md) | Google | AI models | Generative AI model deprecations on Vertex AI | `feed` | [Vertex AI generative AI release notes (Atom)](https://docs.cloud.google.com/feeds/generative-ai-on-vertex-ai-release-notes.xml) | live | | [`redis`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/redis.md) | Redis | runtime | Commands removed entirely from Redis's own command catalog between two snapshots | `catalog` | [redis/redis-doc `commands.json`](https://github.com/redis/redis-doc/blob/master/commands.json) | live | | [`cloudflare`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/cloudflare.md) | Cloudflare | API | REST API operations Cloudflare deprecates, breaking on their end-of-life date when it gives one | `feed` | [Cloudflare API deprecations (RSS)](https://developers.cloudflare.com/fundamentals/api/reference/deprecations/index.xml) | live | +| [`posthog`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/posthog.md) | PostHog | SDK | Members removed in the posthog Python SDK 8.0.0 | `removedmembers` | [posthog-python 7.x to 8.0 migration guide](https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md) | live | ## The columns @@ -40,8 +41,8 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe | Provider | Whose API, SDK or package it is. | | Layer | Which kind of dependency it covers: `API`, `SDK`, `package`, `runtime`, `CI` or `AI models`. | | What it watches | The kind of change it reports, in a few words. | -| Format plugin | Which shared reader it is built on: `openapi` (a spec per release, diffed), `retirements` (a deprecations page), `migrationguide` (an SDK's migration guide), `removedmembers` (a package's table of removed members), `changelog` (a release changelog file), `feed` (an RSS or Atom feed), `catalog` (a structured JSON catalog of names, diffed between two snapshots), `apichangelog` (a vendor's machine-readable API changelog, in JSON). | +| Format plugin | Which shared reader it is built on: `openapi` (a spec per release, diffed), `retirements` (a deprecations page), `migrationguide` (an SDK's migration guide), `removedmembers` (a package's table of removed members, in RST or Markdown), `changelog` (a release changelog file), `feed` (an RSS or Atom feed), `catalog` (a structured JSON catalog of names, diffed between two snapshots), `apichangelog` (a vendor's machine-readable API changelog, in JSON). | | Source | The provider's own public page or file the plugin reads. Every event links back to it. | | Status | `live`: in the code on `main`. patch-it's hosted ingestion service runs it daily from the next release, which is cut automatically. `planned`: accepted, not written yet. `paused`: in the code but deliberately switched off, with the reason in the row. | -Some plugins read one pinned release (`anthropic` 1.0.0, `numpy` 2.0.0, `textual` 0.86.0, `urllib3` 2.0.0): a newer release of the same package is a new entry in that plugin, not a new row, unless it changes the format. +Some plugins read one pinned release (`anthropic` 1.0.0, `numpy` 2.0.0, `posthog` 8.0.0, `textual` 0.86.0, `urllib3` 2.0.0): a newer release of the same package is a new entry in that plugin, not a new row, unless it changes the format. diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 74595e3..d7883b7 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -78,7 +78,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp | `plugins/openapi` | An OpenAPI spec per release, diffed with `diff/` and turned into events by `normalize/` | An `adapter.Adapter` in `adapter/` (latest tag, fetch a tag's spec) and a `plugin.Register(Plugin{Adapter: …})` line | | `plugins/retirements` | A model provider's deprecations page (a table of date, model, replacement) | A `retire.Page` in `retire/providers.go` | | `plugins/migrationguide` | An SDK's migration guide at a release tag (removed request parameters) | A `sdkguide.Guide` in `sdkguide/` | -| `plugins/removedmembers` | A package's table of removed members at a release tag | A `removedmembers.Guide` | +| `plugins/removedmembers` | A package's table of removed members at a release tag (an RST simple table or a Markdown pipe table) | A `removedmembers.Guide` | | `plugins/changelog` | A `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst` at a release tag | A `changelog.File` | | `plugins/feed` | An RSS or Atom feed | A `feed.Feed` with a reader for that vendor's entries | | `plugins/catalog` | A flat JSON catalog, one entry per name, with no release tags to pin — a commit SHA stands in | A `catalog.Catalog`, diffed between two snapshots for names that disappeared entirely | diff --git a/plugins/removedmembers/markdown.go b/plugins/removedmembers/markdown.go new file mode 100644 index 0000000..e1c3869 --- /dev/null +++ b/plugins/removedmembers/markdown.go @@ -0,0 +1,203 @@ +package removedmembers + +import ( + "fmt" + "regexp" + "slices" + "strings" +) + +var ( + codeSpan = regexp.MustCompile("`([^`]+)`") + ident = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$`) + // A cell that is only a list of code spans: "§", "§, §", "§ and §", + // "§, §, and §" (each § a code span). + nameList = regexp.MustCompile(`^§(?:(?:,| and|, and| or|, or) §)*$`) + delimCell = regexp.MustCompile(`^:?-{3,}:?$`) +) + +// parseMarkdown reads a Markdown pipe table: the first one under the heading +// g.Section, before the next heading. Its first column is what was removed, its +// second what to use instead. +// +// A row becomes one Removal per name in its first cell, but only when that +// cell is nothing but code spans naming members ("`A`, `B`"). A cell of prose +// ("The `backoff` dependency") or a span that isn't a name code writes +// ("`gzip=True`") drops the whole row; a name in g.EnvVars drops that name. The replacement is the second cell +// only when it's exactly one code span naming a member. +func parseMarkdown(page []byte, g Guide) ([]Removal, error) { + lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") + inFence := false + // heading reports a line's heading text, outside fenced code (a "# 7.x.x" + // comment in a Python block isn't a heading). + heading := func(l string) (string, bool) { + if strings.HasPrefix(strings.TrimSpace(l), "```") { + inFence = !inFence + return "", false + } + if inFence { + return "", false + } + t := strings.TrimLeft(l, "#") + if n := len(l) - len(t); n == 0 || n > 6 || !strings.HasPrefix(t, " ") { + return "", false + } + return strings.TrimSpace(strings.TrimRight(strings.TrimSpace(t), "#")), true + } + start := -1 + for i, l := range lines { + if h, ok := heading(l); ok && h == g.Section { + start = i + break + } + } + if start < 0 { + return nil, fmt.Errorf("no %q section: the guide's shape may have changed", g.Section) + } + table := -1 + for i := start + 1; i+1 < len(lines); i++ { + if _, ok := heading(lines[i]); ok { + break + } + if !inFence && isRow(lines[i]) && isDelimiter(lines[i+1]) { + table = i + break + } + } + if table < 0 { + return nil, fmt.Errorf("no table under %q", g.Section) + } + header := pipeCells(lines[table]) + if len(header) < 2 || !strings.EqualFold(header[0], g.header()) { + return nil, fmt.Errorf("the table under %q isn't the removed members: %q", g.Section, lines[table]) + } + head := g.Section + "\n" + lines[table] + "\n" + lines[table+1] + var out []Removal + for i := table + 2; i < len(lines) && isRow(lines[i]); i++ { + cells := pipeCells(lines[i]) + excerpt := head + "\n" + lines[i] + if len(cells) != len(header) { + out = append(out, Removal{Member: lines[i], Excerpt: excerpt, + Dropped: fmt.Sprintf("%d cells, the header has %d", len(cells), len(header))}) + continue + } + guideline := header[1] + ": " + cells[1] + names, why := memberNames(cells[0], g.Module) + if why != "" { + out = append(out, Removal{Member: cells[0], Guideline: guideline, Excerpt: excerpt, Dropped: why}) + continue + } + repl := soleName(cells[1], g.Module) + for _, n := range names { + r := Removal{Member: n, Guideline: guideline, Excerpt: excerpt} + if p, ok := g.Paths[n]; ok { + r.Member = p + } + switch { + case slices.Contains(g.EnvVars, n): + r.Dropped = "an environment variable, not a member of the package" + case g.StillWork[n] != "": + r.Dropped = g.StillWork[n] + case repl != "" && repl != n: + r.Replacement = repl + } + out = append(out, r) + } + } + if len(out) == 0 { + return nil, fmt.Errorf("the removed members table under %q is empty", g.Section) + } + return out, nil +} + +func isRow(l string) bool { + return strings.HasPrefix(strings.TrimSpace(l), "|") +} + +func isDelimiter(l string) bool { + if !isRow(l) { + return false + } + cells := pipeCells(l) + for _, c := range cells { + if !delimCell.MatchString(c) { + return false + } + } + return len(cells) > 0 +} + +// pipeCells splits a table row on the pipes outside code spans, each cell +// trimmed. An escaped pipe (\|) is part of its cell. +func pipeCells(row string) []string { + row = strings.TrimSpace(row) + row = strings.TrimPrefix(row, "|") + if strings.HasSuffix(row, "|") && !strings.HasSuffix(row, `\|`) { + row = row[:len(row)-1] + } + var cells []string + var cur strings.Builder + inCode := false + for i := 0; i < len(row); i++ { + c := row[i] + switch { + case c == '\\' && i+1 < len(row) && row[i+1] == '|': + cur.WriteByte('|') + i++ + case c == '`': + inCode = !inCode + cur.WriteByte(c) + case c == '|' && !inCode: + cells = append(cells, strings.TrimSpace(cur.String())) + cur.Reset() + default: + cur.WriteByte(c) + } + } + return append(cells, strings.TrimSpace(cur.String())) +} + +// memberNames reads a first cell that is only a list of code spans, each a +// name as code writes it after importing the package (the package's own +// prefix, "posthog.", stripped, as the changelog plugin does). why says why a +// cell isn't one. +func memberNames(cell, module string) (names []string, why string) { + spans := codeSpan.FindAllStringSubmatch(cell, -1) + if len(spans) == 0 { + return nil, "no code span: not a member's name" + } + rest := strings.Join(strings.Fields(codeSpan.ReplaceAllString(cell, "§")), " ") + if !nameList.MatchString(rest) { + return nil, "prose around the names, not a list of members (a parameter, a dependency…)" + } + for _, s := range spans { + n, ok := cleanName(s[1], module) + if !ok { + return nil, fmt.Sprintf("`%s` isn't a name code writes", s[1]) + } + names = append(names, n) + } + return names, "" +} + +// soleName is the cell's one name when the cell is exactly one code span +// naming a member, or "". +func soleName(cell, module string) string { + m := codeSpan.FindStringSubmatch(cell) + if m == nil || m[0] != strings.TrimSpace(cell) { + return "" + } + n, ok := cleanName(m[1], module) + if !ok { + return "" + } + return n +} + +func cleanName(s, module string) (string, bool) { + s = strings.TrimSuffix(strings.TrimSpace(s), "()") + if module != "" { + s = strings.TrimPrefix(s, module+".") + } + return s, ident.MatchString(s) && s != module +} diff --git a/plugins/removedmembers/posthog.go b/plugins/removedmembers/posthog.go new file mode 100644 index 0000000..7f6b8ce --- /dev/null +++ b/plugins/removedmembers/posthog.go @@ -0,0 +1,80 @@ +package removedmembers + +// PostHog8 is the posthog Python SDK's guide to 8.0.0, +// docs/migration-7.x-to-8.0.md at tag posthog-v8.0.0 (commit +// 6edff41425188056e48f6119457dc9bc0669ca99), and its "Fix removed APIs" +// table: "8.x.x removes these options and APIs". The guide isn't in the repo +// at posthog-v7.91.4, the release before, and is unchanged at posthog-v8.0.2. +// Checked 2026-11-19. +// +// The table is Markdown, | Removed | Use instead |. Names are kept as code +// writes them after `import posthog` or a `from posthog. import`: +// `posthog.` is stripped (`posthog.capture_v1` is `capture_v1`), as the +// changelog plugin and NumPy's `np.` do; other prefixes are kept +// (`request.batch_post`). One event per name, as NumPy has one per member. Its +// 7 rows, each checked against the code at posthog-v7.91.4 and posthog-v8.0.0: +// +// - `capture_mode`, `CaptureMode`, `POSTHOG_CAPTURE_MODE` | Nothing: +// removed_symbol for CaptureMode (the enum; posthog.CaptureMode is an +// alias of posthog.capture_mode.CaptureMode). capture_mode is dropped +// (StillWork): the guide's own "Rename deprecated settings" table says +// `posthog.capture_mode` "still work[s] or ha[s] no effect in 8.x.x", +// and the name also covers a Client argument and a module, which the row +// doesn't tell apart. POSTHOG_CAPTURE_MODE is the environment variable +// capture_mode read (EnvVars): no code imports it. +// - `gzip=True` | `capture_compression`: dropped. It's an argument value, of +// a call the row doesn't name (Client's gzip argument, per the code); a +// removed_parameter needs the call, and guessing it isn't reading the +// guide. +// - `CaptureV1Error` | `CaptureError`: removed_symbol capture_v1.CaptureV1Error +// (its module, Paths), with CaptureError +// in the migration hint, not a renamed_symbol (NewReplacements): +// CaptureError is new in 8.0.0, so a renamed import fails on 7.x, and the +// module changes too, from posthog.capture_v1 to posthog, which renaming +// the name alone wouldn't fix. The row doesn't say so; the guide does a +// few paragraphs below ("Replace `from posthog.capture_v1 import +// CaptureV1Error` with `from posthog import CaptureError`. There is no +// alias."). +// - `posthog.capture_v1` | `posthog.capture_event` and +// `posthog.capture_send`: removed_symbol capture_v1 (the module; two +// replacements, so no rename). +// - `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, +// `AI_EVENTS_ENDPOINT` | Send events through a client: four removed_symbol +// (advice, not a name). The cell spells the module out only for the +// first: EVENTS_ENDPOINT and AI_EVENTS_ENDPOINT are posthog.request's and +// async_batch_post is the private posthog._async_request's, never +// top-level (Paths, checked against references/public_api_snapshot.txt +// and the code at posthog-v7.91.4). +// - The `gzip` parameter of `request.post` and `request.flags` | Nothing: +// dropped, prose. Not a removed_parameter either: both take **kwargs in +// 8.0.0, so gzip= raises nothing and is sent in the request body, as the +// guide says. +// - The `backoff` dependency | Your own requirements…: dropped, prose, and a +// dependency rather than a member. +// +// 7 events. The guide's other tables (endpoints, AI lane arguments, error +// fields, retries, dropped events, options, and "Rename deprecated settings", +// whose old names still work) aren't under the heading, so they're never read. +var PostHog8 = Guide{ + Package: "posthog", + Module: "posthog", + Release: "8.0.0", + Tag: "posthog-v8.0.0", + Repo: "PostHog/posthog-python", + Path: "docs/migration-7.x-to-8.0.md", + Section: "Fix removed APIs", + Format: FormatMarkdown, + Header: "Removed", + EnvVars: []string{"POSTHOG_CAPTURE_MODE"}, + Paths: map[string]string{ + "CaptureV1Error": "capture_v1.CaptureV1Error", + "async_batch_post": "_async_request.async_batch_post", + "EVENTS_ENDPOINT": "request.EVENTS_ENDPOINT", + "AI_EVENTS_ENDPOINT": "request.AI_EVENTS_ENDPOINT", + }, + StillWork: map[string]string{ + "capture_mode": `the guide's "Rename deprecated settings" table: posthog.capture_mode still works or has no effect in 8.x.x`, + }, + // Every replacement in the table is new in 8.0.0. + NewReplacements: true, +} diff --git a/plugins/removedmembers/posthog_test.go b/plugins/removedmembers/posthog_test.go new file mode 100644 index 0000000..cccf046 --- /dev/null +++ b/plugins/removedmembers/posthog_test.go @@ -0,0 +1,237 @@ +package removedmembers + +import ( + "slices" + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/kit/kittest" +) + +// The guide as published at tag posthog-v8.0.0 (fetched 2026-11-19), whole. +const posthogSource = "testdata/migration-7.x-to-8.0-posthog-v8.0.0.md" + +func TestPostHogRegistersItself(t *testing.T) { + kittest.Registered(t, Plugin{Guide: PostHog8}) +} + +// The golden test: the saved guide in, every event out. +func TestPostHogGolden(t *testing.T) { + kittest.Golden(t, "testdata/golden/posthog-8.0.0.json", posthogIngest(t)) +} + +// Each of the "Fix removed APIs" table's 7 rows, decided: every name is a +// removal, its "Use instead" in the hint (each replacement is new in 8.0.0, +// so none is a rename), and what isn't a removed member of the package is no +// event. +func TestPostHogEachRowOfTheTable(t *testing.T) { + type want struct { + change event.PackageChange + replacement string + } + got := map[string]want{} + for _, e := range posthogIngest(t) { + if len(e.Subject.Symbols) != 1 { + t.Fatalf("%v: one symbol per event", e.Subject.Symbols) + } + if e.API != "posthog" || e.Version != "8.0.0" || e.Subject.Ecosystem != "pypi" || e.Subject.Package != "posthog" || + e.ChangeType != event.ChangeTypeBreaking || !strings.HasPrefix(e.SourceExcerpt, "Fix removed APIs\n| Removed | Use instead |") { + t.Errorf("%+v", e) + } + got[e.Subject.Symbols[0]] = want{e.Subject.Change, e.Subject.Replacement} + } + removed := want{change: event.PackageRemovedSymbol} + expect := map[string]want{ + "CaptureMode": removed, // | Nothing (capture_mode, in the same row, still works: dropped) + // | `CaptureError`, new in 8.0.0 and in another module: in the hint, + // not a rename. It's posthog.capture_v1's, written in full. + "capture_v1.CaptureV1Error": removed, + "capture_v1": removed, // two replacements: `posthog.capture_event` and `posthog.capture_send` + // | Send events through a client. The cell spells out `request.` only + // for the first name; the others' real modules, from the code. + "request.batch_post": removed, + "_async_request.async_batch_post": removed, + "request.EVENTS_ENDPOINT": removed, + "request.AI_EVENTS_ENDPOINT": removed, + } + if len(got) != len(expect) { + t.Errorf("%d events, want %d: %v", len(got), len(expect), got) + } + for sym, w := range expect { + if g, ok := got[sym]; !ok || g != w { + t.Errorf("%s: %+v, want %+v", sym, g, w) + } + } +} + +// The pinned drop test. The guide has eight more tables, and this one has +// four rows (and one name) that aren't removed members; none may become an +// event. Each is +// shown to be there, and to read as names, so the test isn't vacuous. +func TestPostHogDropsWhatIsNotARemovedMember(t *testing.T) { + events := posthogIngest(t) + var symbols []string + for _, e := range events { + symbols = append(symbols, e.Subject.Symbols...) + symbols = append(symbols, e.Subject.Replacement) + } + + // The table's own rows: an environment variable, an argument value, and + // two rows of prose (a parameter, a dependency). With the rules off, each + // is a row of the table, with names in code spans. + rs, err := Parse(kittest.Read(t, posthogSource), PostHog8) + if err != nil { + t.Fatal(err) + } + dropped := map[string]string{} + for _, r := range rs { + if r.Dropped != "" { + dropped[r.Member] = r.Dropped + } + } + for _, member := range []string{ + "POSTHOG_CAPTURE_MODE", + "capture_mode", + "`gzip=True`", + "The `gzip` parameter of `request.post` and `request.flags`", + "The `backoff` dependency", + } { + if dropped[member] == "" { + t.Errorf("%q: not read and dropped (%v)", member, dropped) + } + } + if len(dropped) != 5 { + t.Errorf("%d dropped, want 5: %v", len(dropped), dropped) + } + if !strings.Contains(dropped["capture_mode"], "Rename deprecated settings") { + t.Errorf("capture_mode: dropped for %q, want the guide's own reason", dropped["capture_mode"]) + } + for _, name := range []string{"POSTHOG_CAPTURE_MODE", "capture_mode", "gzip", "gzip=True", "request.post", "request.flags", "backoff", "capture_compression"} { + if slices.Contains(symbols, name) { + t.Errorf("an event names %q", name) + } + } + + // The guide's other tables, read as if each were the removals table. The + // "Rename deprecated settings" one would rename _use_ai_lane to + // enable_full_ai_capture, a wrong breaking change (the old names still + // work in 8.x.x); the "Prepare your proxy" one would remove capture. Only + // the Section heading keeps them out. + for _, other := range []struct{ section, header, name string }{ + {"Rename deprecated settings", "Old", "_use_ai_lane"}, + {"Rename deprecated settings", "Old", "trust_tracing_headers"}, + {"Prepare your proxy", "Method", "capture"}, + {"Route AI events", "Argument", "capture_ai_compression"}, + {"Update error handling", "Field", "drops"}, + {"Move to event options", "Option", "cookieless_mode"}, + } { + g := PostHog8 + g.Section, g.Header = other.section, other.header + rs, err := Parse(kittest.Read(t, posthogSource), g) + if err != nil { + t.Fatal(err) + } + read := false + for _, r := range rs { + read = read || (r.Dropped == "" && r.Member == other.name) + } + if !read { + t.Errorf("%q isn't read from the %q table: its drop proves nothing", other.name, other.section) + } + if slices.Contains(symbols, other.name) { + t.Errorf("an event names %q, from the %q table", other.name, other.section) + } + } +} + +func TestPipeCells(t *testing.T) { + for row, want := range map[string][]string{ + "| Removed | Use instead |": {"Removed", "Use instead"}, + "| --- | --- |": {"---", "---"}, + "| `a`, `b` | Nothing |": {"`a`, `b`", "Nothing"}, + "| `x | y` | a \\| b |": {"`x | y`", "a | b"}, + "|`a`|`b`|": {"`a`", "`b`"}, + "| `request.batch_post`, `EVENTS_ENDPOINT` |": {"`request.batch_post`, `EVENTS_ENDPOINT`"}, + "| one | two | three |": {"one", "two", "three"}, + } { + if got := pipeCells(row); !slices.Equal(got, want) { + t.Errorf("pipeCells(%q) = %q, want %q", row, got, want) + } + } +} + +func TestMarkdownTable(t *testing.T) { + g := Guide{Package: "acme", Module: "acme", Section: "Removed", Format: FormatMarkdown, Header: "Removed", EnvVars: []string{"ACME_MODE"}} + page := strings.Join([]string{ + "# Guide", + "## Removed", + "```python", + "# not a heading", + "```", + "Text before the table.", + "", + "| Removed | Use instead |", + "| :--- | ---: |", + "| `acme.old_fn()` | `acme.new_fn` |", + "| `A`, `B`, and `ACME_MODE` | Nothing |", + "| `C` | `D` and `E` |", + "| `F` | Use `G` instead |", + "| `same` | `same` |", + "| `x=1` | `y` |", + "| The `dep` dependency | Nothing |", + "| `short` |", + "", + "| Removed | Use instead |", + "| --- | --- |", + "| `not_read` | `the second table` |", + }, "\n") + rs, err := Parse([]byte(page), g) + if err != nil { + t.Fatal(err) + } + type row struct{ member, replacement, dropped string } + var got []row + for _, r := range rs { + d := "" + if r.Dropped != "" { + d = "dropped" + } + got = append(got, row{r.Member, r.Replacement, d}) + } + want := []row{ + {"old_fn", "new_fn", ""}, + {"A", "", ""}, + {"B", "", ""}, + {"ACME_MODE", "", "dropped"}, + {"C", "", ""}, + {"F", "", ""}, + {"same", "", ""}, + {"`x=1`", "", "dropped"}, + {"The `dep` dependency", "", "dropped"}, + {"| `short` |", "", "dropped"}, + } + if !slices.Equal(got, want) { + t.Errorf("got\n%v\nwant\n%v", got, want) + } + if rs[0].Guideline != "Use instead: `acme.new_fn`" || + rs[0].Excerpt != "Removed\n| Removed | Use instead |\n| :--- | ---: |\n| `acme.old_fn()` | `acme.new_fn` |" { + t.Errorf("%+v", rs[0]) + } + + for name, page := range map[string]string{ + "no section": "## Other\n| Removed | Use instead |\n| --- | --- |\n| `a` | b |", + "no table": "## Removed\ntext\n## Next\n| Removed | Use instead |\n| --- | --- |\n| `a` | b |", + "another table": "## Removed\n| Method | Endpoint |\n| --- | --- |\n| `a` | b |", + } { + if _, err := Parse([]byte(page), g); err == nil { + t.Errorf("%s: no error", name) + } + } +} + +// posthogIngest runs the plugin over the saved guide. +func posthogIngest(t *testing.T) []event.EventV2 { + t.Helper() + return kittest.Ingest(t, Plugin{Guide: PostHog8}, kittest.Pages{PostHog8.URL(): posthogSource}) +} diff --git a/plugins/removedmembers/removedmembers.go b/plugins/removedmembers/removedmembers.go index 862d783..9aa4080 100644 --- a/plugins/removedmembers/removedmembers.go +++ b/plugins/removedmembers/removedmembers.go @@ -11,11 +11,18 @@ // upgrade. Every other row (no replacement, a builtin, an expression, a // sentence of advice) becomes a `removed_symbol`, which the patch-it client // opens as an issue: precision over recall. +// +// A guide's table is an RST simple table (NumPy) or a Markdown pipe table +// (PostHog, markdown.go). A Markdown row may list several members in one cell; +// each is its own event, as each NumPy row is. A row the reader can't read as +// members of the package (prose, an argument value, an environment variable) +// is dropped and logged, never guessed at. package removedmembers import ( "context" "fmt" + "log" "regexp" "strings" @@ -25,6 +32,7 @@ import ( func init() { plugin.Register(Plugin{Guide: NumPy2}) + plugin.Register(Plugin{Guide: PostHog8}) } // Guide is one package's guide to one release. @@ -35,6 +43,62 @@ type Guide struct { Repo string // owner/name on GitHub Path string // the guide's path in the repo at the release tag Section string // the heading the table is under + + // Tag is the release tag; "" is "v" + Release. + Tag string + // Format is how the table is written: FormatRST (the default) or + // FormatMarkdown. + Format Format + // Header is the table's first column heading, matched case-insensitively + // (as a prefix in an RST table); "" is "removed member". + Header string + // Effect is what code using any removed member gets, said in every + // event's description after ". was removed": only for a + // guide whose members are all attributes of Module and all fail the same + // way. "" says only that it was removed. + Effect string + // EnvVars are names in the table that are environment variables, not + // members of the package: no code imports one, so they're dropped. Listed + // by hand from the code, not guessed from a prefix (a package can have + // constants named like its environment variables). + EnvVars []string + // NewReplacements says the release's replacements are new in it: a + // rename fix wouldn't run on the release before, and may need a different + // import. A row with one replacement is then a removed_symbol, with the + // replacement in the migration hint (the guide's own cell), not a + // renamed_symbol the client would apply as a rename. NumPy 2.0's + // replacements already worked on 1.x, so it doesn't set this. + NewReplacements bool + // Paths gives a name the table writes in shorthand the path code imports + // it by, after Module ("EVENTS_ENDPOINT" -> "request.EVENTS_ENDPOINT"), + // checked by hand against the package at the release before. A guide's + // cell can list names that share a prefix only the first one spells out. + Paths map[string]string + // StillWork are names the table lists as removed but the same guide says + // still work or have no effect: no event, with the guide's reason. + StillWork map[string]string +} + +// Format is how a guide writes its table. +type Format string + +const ( + FormatRST Format = "" + FormatMarkdown Format = "markdown" +) + +func (g Guide) tag() string { + if g.Tag != "" { + return g.Tag + } + return "v" + g.Release +} + +func (g Guide) header() string { + if g.Header != "" { + return g.Header + } + return "removed member" } // NumPy2 is NumPy's 2.0 migration guide, "Main namespace" table. @@ -45,11 +109,12 @@ var NumPy2 = Guide{ Repo: "numpy/numpy", Path: "doc/source/numpy_2_0_migration_guide.rst", Section: "Main namespace", + Effect: "code using it raises AttributeError", } // URL is the guide as it was at the release tag: its own provenance. func (g Guide) URL() string { - return fmt.Sprintf("https://raw.githubusercontent.com/%s/v%s/%s", g.Repo, g.Release, g.Path) + return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", g.Repo, g.tag(), g.Path) } // Removal is one removed member and the guide's guideline for it. @@ -58,12 +123,22 @@ type Removal struct { Guideline string Replacement string // the one member to use instead, or "" Excerpt string // the table's header and the row + Dropped string // why it isn't an event; "" when it is } -// Parse reads the section's table: an RST simple table, the member in the -// first column, the guideline in the second, a guideline continued on the next -// lines indented to the second column. +// Parse reads the section's table: one Removal per member, and one per row or +// name it drops, with the reason in Dropped. func Parse(page []byte, g Guide) ([]Removal, error) { + if g.Format == FormatMarkdown { + return parseMarkdown(page, g) + } + return parseRST(page, g) +} + +// parseRST reads an RST simple table, the member in the first column, the +// guideline in the second, a guideline continued on the next lines indented to +// the second column. +func parseRST(page []byte, g Guide) ([]Removal, error) { lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") start := -1 for i, l := range lines { @@ -90,7 +165,7 @@ func Parse(page []byte, g Guide) ([]Removal, error) { col++ } header := lines[border+1] - if !strings.HasPrefix(strings.ToLower(header), "removed member") { + if !strings.HasPrefix(strings.ToLower(header), strings.ToLower(g.header())) { return nil, fmt.Errorf("the table under %q isn't the removed members: %q", g.Section, header) } head := strings.Join([]string{lines[border], header, lines[border+2]}, "\n") @@ -152,12 +227,19 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) var events []event.EventV2 var rejected []error for _, r := range removals { + if r.Dropped != "" { + log.Printf("%s %s: dropped %q: %s", g.Package, g.Release, r.Member, r.Dropped) + continue + } subject := event.Subject{ Type: event.SubjectPackageRelease, Ecosystem: "pypi", Package: g.Package, Change: event.PackageRemovedSymbol, Symbols: []string{r.Member}, } - desc := fmt.Sprintf("%s.%s was removed in %s %s: code using it raises AttributeError.", g.Module, r.Member, g.Package, g.Release) - if r.Replacement != "" { + desc := fmt.Sprintf("`%s` was removed in %s %s.", r.Member, g.Package, g.Release) + if g.Effect != "" { + desc = fmt.Sprintf("%s.%s was removed in %s %s: %s.", g.Module, r.Member, g.Package, g.Release, g.Effect) + } + if r.Replacement != "" && !g.NewReplacements { subject.Change, subject.Replacement = event.PackageRenamedSymbol, r.Replacement } e := event.EventV2{ @@ -184,6 +266,6 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) Label: g.URL(), Events: events, Rejected: rejected, - Baselines: []plugin.Spec{plugin.Baseline(g.Package, g.Release, "v"+g.Release, g.URL(), page, false, now)}, + Baselines: []plugin.Spec{plugin.Baseline(g.Package, g.Release, g.tag(), g.URL(), page, false, now)}, }, nil } diff --git a/plugins/removedmembers/testdata/README.md b/plugins/removedmembers/testdata/README.md index 56caa22..9ca57db 100644 --- a/plugins/removedmembers/testdata/README.md +++ b/plugins/removedmembers/testdata/README.md @@ -1,7 +1,8 @@ -# Saved removed-members guide +# Saved removed-members guides -The golden file under `golden/` is what the plugin stores from it (`go test ./plugins/removedmembers -update`). +The golden files under `golden/` are what the plugin stores from them (`go test ./plugins/removedmembers -update`). | File | URL | Fetched | License | Quote | |---|---|---|---|---| | `numpy_2_0_migration_guide-v2.0.0.rst` | https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst | 2026-11-04 | BSD-3-Clause (NumPy), kept whole | "The table below provides replacements for the removed members:" | +| `migration-7.x-to-8.0-posthog-v8.0.0.md` | https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md (commit 6edff41425188056e48f6119457dc9bc0669ca99) | 2026-11-19 | MIT (the repo's LICENSE is the MIT text, with two copyright lines, so GitHub's detector says NOASSERTION; PyPI says MIT), kept whole, byte for byte | "8.x.x removes these options and APIs:" (Fix removed APIs), with rows such as "\| `CaptureV1Error` \| `CaptureError` \|" | diff --git a/plugins/removedmembers/testdata/golden/posthog-8.0.0.json b/plugins/removedmembers/testdata/golden/posthog-8.0.0.json new file mode 100644 index 0000000..4439b59 --- /dev/null +++ b/plugins/removedmembers/testdata/golden/posthog-8.0.0.json @@ -0,0 +1,163 @@ +[ + { + "id": 1, + "fingerprint": "sha256:cc0790387fbe50505a8c3116cb1678892d2b49643002a99259eeb81144bc4159", + "api": "posthog", + "version": "8.0.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "posthog", + "change": "removed_symbol", + "symbols": [ + "CaptureMode" + ] + }, + "description": "`CaptureMode` was removed in posthog 8.0.0.", + "migration_hint": "Use instead: Nothing (posthog's migration guide for 8.0.0)", + "source_url": "https://raw.githubusercontent.com/PostHog/posthog-python/posthog-v8.0.0/docs/migration-7.x-to-8.0.md", + "source_excerpt": "Fix removed APIs\n| Removed | Use instead |\n| --- | --- |\n| `capture_mode`, `CaptureMode`, `POSTHOG_CAPTURE_MODE` | Nothing |", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 2, + "fingerprint": "sha256:0ac3ae87979a15b9bd217da712b7deb2c20063e72f2a717a436c11040384fd37", + "api": "posthog", + "version": "8.0.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "posthog", + "change": "removed_symbol", + "symbols": [ + "capture_v1.CaptureV1Error" + ] + }, + "description": "`capture_v1.CaptureV1Error` was removed in posthog 8.0.0.", + "migration_hint": "Use instead: `CaptureError` (posthog's migration guide for 8.0.0)", + "source_url": "https://raw.githubusercontent.com/PostHog/posthog-python/posthog-v8.0.0/docs/migration-7.x-to-8.0.md", + "source_excerpt": "Fix removed APIs\n| Removed | Use instead |\n| --- | --- |\n| `CaptureV1Error` | `CaptureError` |", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 3, + "fingerprint": "sha256:1a38df0902754ee8485ccc7462afb9cff35c7de933e11b3205c93babbdb05863", + "api": "posthog", + "version": "8.0.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "posthog", + "change": "removed_symbol", + "symbols": [ + "capture_v1" + ] + }, + "description": "`capture_v1` was removed in posthog 8.0.0.", + "migration_hint": "Use instead: `posthog.capture_event` and `posthog.capture_send` (posthog's migration guide for 8.0.0)", + "source_url": "https://raw.githubusercontent.com/PostHog/posthog-python/posthog-v8.0.0/docs/migration-7.x-to-8.0.md", + "source_excerpt": "Fix removed APIs\n| Removed | Use instead |\n| --- | --- |\n| `posthog.capture_v1` | `posthog.capture_event` and `posthog.capture_send` |", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 4, + "fingerprint": "sha256:0736d4f7aee4ddfa0c13654ba26a45586844d6628d353e5d43b84f646b6dd0f6", + "api": "posthog", + "version": "8.0.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "posthog", + "change": "removed_symbol", + "symbols": [ + "request.batch_post" + ] + }, + "description": "`request.batch_post` was removed in posthog 8.0.0.", + "migration_hint": "Use instead: Send events through a client (posthog's migration guide for 8.0.0)", + "source_url": "https://raw.githubusercontent.com/PostHog/posthog-python/posthog-v8.0.0/docs/migration-7.x-to-8.0.md", + "source_excerpt": "Fix removed APIs\n| Removed | Use instead |\n| --- | --- |\n| `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, `AI_EVENTS_ENDPOINT` | Send events through a client |", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 5, + "fingerprint": "sha256:417930dab98562db2bb15d2bd3926baf9689950100e9e9ffe78d5bc9c26602ad", + "api": "posthog", + "version": "8.0.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "posthog", + "change": "removed_symbol", + "symbols": [ + "_async_request.async_batch_post" + ] + }, + "description": "`_async_request.async_batch_post` was removed in posthog 8.0.0.", + "migration_hint": "Use instead: Send events through a client (posthog's migration guide for 8.0.0)", + "source_url": "https://raw.githubusercontent.com/PostHog/posthog-python/posthog-v8.0.0/docs/migration-7.x-to-8.0.md", + "source_excerpt": "Fix removed APIs\n| Removed | Use instead |\n| --- | --- |\n| `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, `AI_EVENTS_ENDPOINT` | Send events through a client |", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 6, + "fingerprint": "sha256:4184ff3cbb866e22be67075e91e9e1d05b6ac9711ea5fc0bbae6b7a8d3b2d814", + "api": "posthog", + "version": "8.0.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "posthog", + "change": "removed_symbol", + "symbols": [ + "request.EVENTS_ENDPOINT" + ] + }, + "description": "`request.EVENTS_ENDPOINT` was removed in posthog 8.0.0.", + "migration_hint": "Use instead: Send events through a client (posthog's migration guide for 8.0.0)", + "source_url": "https://raw.githubusercontent.com/PostHog/posthog-python/posthog-v8.0.0/docs/migration-7.x-to-8.0.md", + "source_excerpt": "Fix removed APIs\n| Removed | Use instead |\n| --- | --- |\n| `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, `AI_EVENTS_ENDPOINT` | Send events through a client |", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 7, + "fingerprint": "sha256:8639fcae424bb8a4c15aebef34c5aa1f6c1fd80ed5d5817b7ff07d8ea57c6ef6", + "api": "posthog", + "version": "8.0.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "posthog", + "change": "removed_symbol", + "symbols": [ + "request.AI_EVENTS_ENDPOINT" + ] + }, + "description": "`request.AI_EVENTS_ENDPOINT` was removed in posthog 8.0.0.", + "migration_hint": "Use instead: Send events through a client (posthog's migration guide for 8.0.0)", + "source_url": "https://raw.githubusercontent.com/PostHog/posthog-python/posthog-v8.0.0/docs/migration-7.x-to-8.0.md", + "source_excerpt": "Fix removed APIs\n| Removed | Use instead |\n| --- | --- |\n| `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, `AI_EVENTS_ENDPOINT` | Send events through a client |", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + } +] diff --git a/plugins/removedmembers/testdata/migration-7.x-to-8.0-posthog-v8.0.0.md b/plugins/removedmembers/testdata/migration-7.x-to-8.0-posthog-v8.0.0.md new file mode 100644 index 0000000..f0e0edf --- /dev/null +++ b/plugins/removedmembers/testdata/migration-7.x-to-8.0-posthog-v8.0.0.md @@ -0,0 +1,495 @@ +# Migrate the Python SDK from 7.x.x to 8.0.0 + +The Python SDK 8.x.x sends every event to the [capture v1](https://posthog.com/docs/api/capture-v1) endpoints, `/i/v1/analytics/events` and `/i/v1/ai/events`, and removes the legacy capture path. Most apps upgrade without code changes. + +Use the top right copy page button to work through this with your agents. + +You don't need to make every change on the day you upgrade your SDK. Required changes fall in these categories: + +- **Before you upgrade**: you should make these changes before you upgrade your SDK to 8.x.x. +- **During your upgrade**: These are changes that you need to make in the same PR that upgrades your SDK version. +- **Follow ups**: These are changes that can come in follow up PRs because 8.x.x has limited backward compatibility for methods that are to be deprecated. + +## Checklist + +Read the checklist first, then the sections that apply to you. + +**Before you upgrade** + +- [ ] You send events through your own proxy → [Prepare your proxy](#prepare-your-proxy) +- [ ] A proxy redirects capture requests to another host → [Prepare your proxy](#prepare-your-proxy) +- [ ] You pass a personal API key (`phx_...`) as the project token → [Use a project token](#use-a-project-token) +- [ ] You use `openfeature-provider-posthog` below 0.2.0 → [Update OpenFeature](#update-openfeature) + +**During your upgrade** + +- [ ] You pass `Client` or `AsyncPosthog` constructor arguments by position after `host` → [Fix removed APIs](#fix-removed-apis) +- [ ] You call `posthog.request.post` or `posthog.request.flags` with positional arguments after `path` or `host` → [Fix removed APIs](#fix-removed-apis) +- [ ] You set `capture_mode`, `POSTHOG_CAPTURE_MODE`, or `gzip` → [Fix removed APIs](#fix-removed-apis) +- [ ] You import `CaptureMode`, `posthog.capture_mode`, `CaptureV1Error`, `posthog.capture_v1`, `request.batch_post`, `EVENTS_ENDPOINT`, or `AI_EVENTS_ENDPOINT` → [Fix removed APIs](#fix-removed-apis) +- [ ] Your `before_send` hook returns a new dict, in the client or in MCP → [Copy options in before_send](#copy-options-in-before_send) +- [ ] You test the AI integrations with a mock client and assert on `capture` → [Route AI events](#route-ai-events) +- [ ] You pass your own client object to the AI integrations → [Route AI events](#route-ai-events) +- [ ] You call `alias()` without a `distinct_id` and rely on the context distinct ID → [Fix identity calls](#fix-identity-calls) +- [ ] You turn person processing off with `super_options`, `super_properties`, a context option, or a context tag, and expect identify-style events, such as those from `alias`, `group_identify`, `set`, or `set_once`, to follow it → [Fix identity calls](#fix-identity-calls) +- [ ] You reuse one event `uuid` for more than one event → [Check event IDs](#check-event-ids) +- [ ] You expect `super_properties` to override a call's properties, including `$set` and `$groups` → [Check property precedence](#check-property-precedence) +- [ ] You set `$is_server`, `$geoip_disable`, or a system property such as `$os`, and expect the SDK's value to win → [Check property precedence](#check-property-precedence) +- [ ] You set `$lib` or `$lib_version` yourself → [Check SDK identity](#check-sdk-identity) +- [ ] An insight or dashboard filters on `$lib = posthog-python-mcp` → [Check SDK identity](#check-sdk-identity) +- [ ] You read event content from the SDK's debug log, or alert on SDK log lines → [Update error handling](#update-error-handling) +- [ ] You set `$exception_level` or another reserved exception property in `capture_exception(properties=...)` → [Check exceptions](#check-exceptions) +- [ ] You run the Django, Flask, or ASGI integration on 7.68.x to 7.70.x without tracing headers turned on → [Check tracing headers](#check-tracing-headers) + +**Follow ups** + +- [ ] You set legacy option properties like `$process_person_profile` → [Move to event options](#move-to-event-options) +- [ ] You capture `$ai_` events with `capture()` → [Send AI events with capture_ai](#send-ai-events-with-capture_ai) +- [ ] You use `trust_tracing_headers` or `_use_ai_lane`, set `posthog.capture_mode`, or pass a `gzip=` keyword to `request.post` → [Rename deprecated settings](#rename-deprecated-settings) + +## Before you upgrade + +### Prepare your proxy + +8.x.x sends events to these endpoints: + +| Method | Endpoint | +| --- | --- | +| `capture`, `set`, `set_once`, `alias`, `group_identify`, `capture_exception`, `AsyncPosthog.capture_immediate` | `/i/v1/analytics/events` | +| `capture_ai`, `capture_ai_immediate`, and the AI wrapper integrations | `/i/v1/ai/events` | +| OpenTelemetry (`posthog.ai.otel`) | `/i/v0/ai/otel`, unchanged | + +If you send events through your own reverse proxy, update it before you upgrade: + +- **Forward both routes.** Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog. +- **Pass the headers through unchanged.** Pass `Authorization`, every `PostHog-*` header, `Content-Type`, `Content-Encoding`, and `User-Agent`. `Authorization` holds the project token, sent as `Bearer `. PostHog answers `401` without `Authorization` and `400` without the others, and the batch fails. +- **Accept request bodies up to 20 MB.** AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A `413` from the proxy fails the batch. +- **Pass the capture response through.** Return PostHog's status code and response body unchanged. A proxy that answers the capture path with its own `200` fails the batch. + +PostHog's managed reverse proxy already does this. See the [proxy guides](https://posthog.com/docs/advanced/proxy). + +The SDK follows a `307` or `308` redirect only to the origin of `host`, at most 5 times. The origin is the same scheme, host, and port. + +Any other redirect fails the batch and reaches `on_error`. In 7.x.x the sync client followed redirects to any origin. + +If a proxy redirects capture requests to another host, point `host` at the final host. + +### Use a project token + +A personal API key (`phx_...`) passed as the project token disables the client and logs one error, as an empty key does. Capture rejects personal API keys, and the SDK no longer sends one with every request. + +### Update OpenFeature + +`openfeature-provider-posthog` 0.2.0 works with `posthog` 7.x.x and 8.x.x. Older provider versions require `posthog` below 8.0.0, so upgrade the provider before or with `posthog`. + +## During your upgrade + +### Fix removed APIs + +8.x.x removes these options and APIs: + +| Removed | Use instead | +| --- | --- | +| `capture_mode`, `CaptureMode`, `POSTHOG_CAPTURE_MODE` | Nothing | +| `gzip=True` | `capture_compression` | +| `CaptureV1Error` | `CaptureError` | +| `posthog.capture_v1` | `posthog.capture_event` and `posthog.capture_send` | +| `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, `AI_EVENTS_ENDPOINT` | Send events through a client | +| The `gzip` parameter of `request.post` and `request.flags` | Nothing | +| The `backoff` dependency | Your own requirements, if your code imports it | + +Capture v1 is the only path. Setting `posthog.capture_mode` on the module has no effect. + +For gzip, set `capture_compression=CaptureCompression.GZIP`. `capture_compression` defaults to no compression. `POSTHOG_CAPTURE_COMPRESSION` still works. + +`capture_compression` and `capture_ai_compression` take `CaptureCompression.GZIP`, `DEFLATE`, or `ZSTD`. `ZSTD` needs the `zstandard` package, so install `posthog[zstd]`. Without it, the client raises `ValueError`. + +Replace `from posthog.capture_v1 import CaptureV1Error` with `from posthog import CaptureError`. There is no alias. + +The parameters after `path` in `request.post` and after `host` in `request.flags` are keyword-only, so a 7.x.x call that passes them by position raises `TypeError`. A `gzip=` keyword raises no error. It's sent as a field in the request body. + +The `posthoganalytics` package has the same changes. For example, import `CaptureError` from `posthoganalytics`. + +Constructor arguments after `host` are keyword-only: + +```python +# 7.x.x +Posthog("", "https://us.i.posthog.com", True) + +# 8.x.x +Posthog("", host="https://us.i.posthog.com", debug=True) +``` + +### Copy options in before_send + +Review your `before_send` hooks for the new event shape. Capture v1 sends processing options in an `options` object, next to `properties`. + +To change an option, edit `options`. A hook that returns a new dict must copy `options`, or the event is sent without them. + +That includes the `process_person_profile = false` the SDK sets for an event without a distinct ID. Without it, PostHog would create a person for the event's generated ID. + +A hook that builds an identify-style event, or renames an event to one, must set the `process_person_profile` option itself (see [Fix identity calls](#fix-identity-calls)). + +A hook that spreads the event into the new dict keeps `options`: + +```python +def remove_email(event): + properties = {key: value for key, value in event["properties"].items() if key != "email"} + return {**event, "properties": properties} +``` + +The same applies to MCP's `before_send`. It gets each event's `options` in an `options` key of `PostHogCaptureEvent`. + +An MCP hook that returns a new dict must copy them, or the event is sent without the anonymous `process_person_profile: False`. + +### Route AI events + +8.x.x routes AI events to their own endpoint: + +- **The endpoint.** `capture_ai` and the AI wrapper integrations send to `/i/v1/ai/events`. The AI endpoint accepts events up to 8 MiB. +- **Event names.** `capture_ai` sends any event name to the AI endpoint. PostHog drops an event whose name doesn't start with `$ai_` as `misrouted_event`, and `on_error` reports it. The SDK writes only a debug log. +- **Custom clients.** The AI integrations call your client's `capture_ai`, and never `capture`. A custom client object must implement `capture_ai` and accept its `options` keyword argument. +- **Clients without `capture_ai`.** The wrapper, callback handler, or tracing processor logs one error when you create it and captures no AI events. Provider calls still work. Before, such a client got `capture` calls. +- **Mock clients.** Tests that pass a `Mock` client to an AI integration must assert on `mock.capture_ai`, not `mock.capture`. +- **OpenTelemetry.** The OpenTelemetry integration (`PostHogSpanProcessor`, `PostHogTraceExporter`) is unchanged. It still exports spans over OTLP to `/i/v0/ai/otel`. +- **Content capture.** `enable_full_ai_capture` now controls only content: string truncation and media redaction. It no longer chooses the endpoint. +- **Fallback IDs.** When an AI integration or MCP falls back to a trace, run, or session ID, it turns person processing off with a per-event option. This is the only option the integrations set on their own. It wins over your `posthog_options`, `options`, `super_options`, and context options. `before_send` can still change it. +- **Empty distinct IDs.** An empty or whitespace-only distinct ID passed to an AI integration, such as `posthog_distinct_id=""`, counts as missing. The integration falls back the same way and turns person processing off. +- **Empty distinct IDs in 7.x.x.** An empty ID gave non-streaming wrapper calls a random personless ID. Streaming calls, embeddings, and LangChain used the trace or run ID with person processing on. OpenAI Agents already treated an empty ID as missing. Every integration sent a whitespace-only ID as given, with person processing on. +- **Async capture.** `AsyncPosthog` has `capture_ai` and `capture_ai_immediate`. It sends events with `requests` in a worker thread, and uses `httpx` only for feature flags and remote config. +- **Async content settings.** `AsyncPosthog` accepts `privacy_mode` and `enable_full_ai_capture`, with the same meaning as on `Client`. An AI integration given an `AsyncPosthog` client used to always truncate and redact media. + +`Client` and `AsyncPosthog` have new arguments for the AI lane: + +| Argument | Default | +| --- | --- | +| `capture_ai_compression` | No compression | +| `capture_ai_max_queue_size` | 1000 | +| `capture_ai_timeout` | 30 seconds | +| `capture_ai_max_event_bytes` | 8 MiB plus 64 KiB | + +`POSTHOG_CAPTURE_COMPRESSION` doesn't apply to `capture_ai_compression`. You can only lower `capture_ai_max_event_bytes`. + +The AI lane doesn't use `max_queue_size`, `timeout`, or `capture_compression`. An invalid `capture_ai_*` value raises `ValueError` when you create the client. + +The module-level client has no AI lane settings. To change them, create a `Client`. + +### Fix identity calls + +- **Empty IDs.** An empty or whitespace-only `distinct_id` counts as missing, so the event gets a generated personless distinct ID. 7.x.x sent a whitespace-only ID, and capture dropped the event. +- **Generated IDs.** Generated personless distinct IDs are UUIDv7. 7.x.x generated UUIDv4. +- **Group fallback.** `group_identify` uses the `distinct_id` you pass, then the context distinct ID, then `$_`. 7.x.x fell back to a random ID, which created a new person on every call. +- **Long group IDs.** If `$_` is over 200 bytes, pass `distinct_id`. PostHog drops an event whose distinct ID is over 200 bytes. +- **Long distinct IDs.** PostHog drops an event whose `distinct_id` is over 200 UTF-8 bytes (`distinct_id_too_large`), and `on_error` reports it. 7.x.x sent events to legacy capture, which shortened the ID to 200 characters and kept the event. +- **Group sessions.** `group_identify` no longer adds the context session ID. A session takes the person of its latest event, and this event's distinct ID isn't the session's user. +- **Alias.** `alias()` needs an explicit `distinct_id`. It no longer falls back to the context distinct ID, which can come from a request header the client controls. Without one, the SDK drops the call with a warning. +- **Context values.** Context tags and context options now apply to `alias` and `group_identify`, below the call's own values, as they do for `capture`. + +Identify-style events default to person processing on. These are `$identify`, `$create_alias`, `$merge_dangerously`, `$groupidentify`, `$set`, and `$set_once`, whether `alias`, `group_identify`, `set`, `set_once`, `capture`, or `capture_ai` sends them. + +The SDK sets `process_person_profile: True` on them unless the call sets the `process_person_profile` option, a `capture` or `capture_ai` call sets a `$process_person_profile` property, or the SDK generated the distinct ID. PostHog drops the `$create_alias` and `$groupidentify` events when person processing is off, with an ingestion warning, and ignores the person update of `$set` and `$set_once`. + +- **Call values.** The call's own value wins over context options and tags, `super_options`, and `super_properties`. So a `False` set there never reaches these events when the SDK didn't generate the distinct ID. In 7.x.x, `$process_person_profile: False` in `super_properties` reached them too. +- **Legacy property.** When a `capture` or `capture_ai` call sets only the `$process_person_profile` property, the SDK moves it into the option. The `properties` of `set`, `set_once`, and `group_identify` are person and group properties, so pass `process_person_profile` in the call's `options`. +- **`None` values.** A `None` option or property counts as unset here, so the event gets `True`. +- **Generated IDs.** An event whose distinct ID the SDK generated gets no default. Context options and `super_options` still fill it, then the personless `process_person_profile: False`. +- **`before_send`.** The hook sees the value and can change it. The SDK first removes any `$process_person_profile` property from these events, including one from a context tag or `super_properties`, so the hook sees only the option. +- **Built events.** A hook that builds an identify-style event, or renames an event to one, must set the option itself. + +To keep one of these events personless, set `process_person_profile: False` on the call or in `before_send`, or turn off person processing for the project in PostHog. + +### Check event IDs + +- **Duplicates.** Each event needs its own UUID. Capture keeps the first event for each UUID in a request and drops the later copies. `on_error` reports each dropped copy in `CaptureError.drops` as `(uuid, "duplicate_event_uuid")`. 7.x.x sent every copy. Older PostHog versions reject the whole batch with a 400 `duplicate_event_uuid` instead. +- **Accepted forms.** The SDK accepts a UUID with hyphens, 32 hex digits, `{...}` braces, or a `urn:uuid:` prefix, in any case. It sends the lowercase hyphenated form and returns that form from `capture`. +- **Other values.** The SDK replaces any other value with a generated UUID. It logs one warning that names the rule, not the value. An empty string counts as unset, so the SDK generates a UUID without a warning. This applies to `AsyncPosthog` too. +- **Generated UUIDs.** Generated UUIDs are UUIDv7. + +### Check property precedence + +An event's options and properties come from five steps, in this order. Steps 2 to 4 fill only the options and properties that the steps before them left unset: + +1. The `options` and `properties` of the call, then the call's `disable_geoip` argument, which fills `$geoip_disable`. An identify-style event also gets `process_person_profile: True` here when the call leaves it unset and the SDK didn't generate its distinct ID (see [Fix identity calls](#fix-identity-calls)). +2. Context options and tags. +3. `super_options` and `super_properties`. +4. Values the SDK sets: + - `$lib` and `$lib_version` as a pair (see [Check SDK identity](#check-sdk-identity)) + - `$is_server` from `is_server` + - `$geoip_disable` from the client's `disable_geoip` setting + - System properties such as `$os` and `$python_version` + - The `$feature/` and `$active_feature_flags` properties from `flags` or `send_feature_flags` + - `$trace_id` and `$span_id` from the active OpenTelemetry span (in `capture` and `capture_ai` only with `capture_trace_context=True`, and always in `capture_exception`) + - `options.process_person_profile = false` for events without a distinct ID + - `$release_id` from `POSTHOG_RELEASE_ID` +5. `before_send`, which sees the result of steps 1 to 4 and can change or remove any of it. + +A property set to `None` counts as set, so no later step fills it. A `None` option counts as unset, so a later step can fill it. + +`$lib` and `$lib_version` are the exception. They count as set only when they're non-empty strings (see [Check SDK identity](#check-sdk-identity)). + +`$set`, `$set_once`, `$groups`, and `$group_set` fill one level deep. When the call and a later step both set one of them to a dict, the later step adds only the keys the call left out. + +For example, `super_properties={"$set": {"plan": "free", "source": "web"}}` and a call with `properties={"$set": {"plan": "pro"}}` send `{"plan": "pro", "source": "web"}`. A `$set` in `super_properties` or a context tag sets those person properties on every event it reaches. + +These changes follow from this order: + +- **Call properties.** Properties passed to a call now override `super_properties`. +- **SDK values.** A `$is_server`, `$geoip_disable`, `$lib`, `$lib_version`, or system property such as `$os` that you set in a call or a context tag now wins over the SDK's value. In 7.x.x the SDK overwrote it. +- **SDK values and `super_properties`.** `super_properties` win over the SDK's value too. So `super_properties={"$geoip_disable": False}` turns GeoIP lookup on for events, even with `disable_geoip=True`. So does `None`, in the event's properties, a context tag or `super_properties`: a `None` property counts as set, so the SDK adds no `True`. +- **Feature flag properties.** Feature flag properties from `flags` or `send_feature_flags` still lose to the same key in the call's `properties`, a context tag, or `super_properties`, as in 7.x.x. +- **Trace IDs.** A `$trace_id` or `$span_id` in a context tag or `super_properties` now replaces the active OpenTelemetry span's IDs. In 7.x.x the span's IDs beat context tags. +- **Trace ID pairs.** Setting either key in the call's `properties`, a context tag, or `super_properties` stops the SDK adding both. In 7.x.x the SDK still added the other key. +- **The `disable_geoip` argument.** A `disable_geoip` argument to a call belongs to that event, so it wins over context tags and `super_properties`. A `$geoip_disable` in the call's own `properties` still wins over it. +- **`disable_geoip=False`.** It now sends `$geoip_disable: false`. In 7.x.x it sent no `$geoip_disable` property. +- **The `groups` argument.** It merges into a `$groups` property of the call, and wins key by key. In 7.x.x it replaced the property. MCP events merge their identity's groups into a custom `$groups` property the same way. +- **Merged dicts.** A `$set`, `$set_once`, `$groups`, or `$group_set` in `super_properties` no longer replaces the whole value of the call. The two merge, and the call wins key by key. +- **Events without a distinct ID.** An event without a distinct ID gets `options.process_person_profile = false`. To turn person processing on for it, set the `process_person_profile` option. +- **Minimal flag events.** When the server enables minimal `$feature_flag_called` events, those events now keep `$window_id`. Their options still apply, because the trim removes only properties. + +### Check SDK identity + +By default every event carries `$lib: "posthog-python"` and the installed package version in `$lib_version`. PostHog stores the values the event is sent with. + +You can set them in a call's `properties`, a context tag, or `super_properties`. Like any other property, each one comes from the most specific place that sets it, so set both in the same place. + +`$lib` and `$lib_version` count as set only when they're non-empty strings. `before_send` sees both and can change or remove them. + +If you set `$lib` without `$lib_version`, the SDK adds its own version only when `$lib` is `posthog-python`. The SDK replaces a `$lib_version` that has no `$lib` with its own. + +| You set | 8.x.x sends | 7.x.x sent | +| --- | --- | --- | +| `$lib` or `$lib_version` in a call or a context tag | Your value | The SDK's value | +| `super_properties={"$lib": "my-lib"}` | No `$lib_version` | The SDK version | +| `super_properties={"$lib_version": "1.0"}` without a `$lib` | The SDK's `$lib` and version | `1.0` | + +If an event reaches PostHog without `$lib`, PostHog fills both from the SDK name and version your request sends. If `$lib` is that SDK name and `$lib_version` is missing, empty, or not a string, PostHog fills `$lib_version` the same way. + +MCP analytics events from `posthog.mcp.instrument()` or `PostHogMCP` report `posthog-python-mcp` and the installed package version. The integration sets both in each event's own properties, so neither a context tag nor `super_properties` replaces them, but `before_send` can. + +In 7.x.x the MCP integration relabeled the whole client, or the default client when `instrument()` got none. That covered the app's own events, the request headers, and feature flag requests. + +In 8.x.x those report `posthog-python`, so one client can serve both. + +Custom events from `PostHogMCP.capture()` now report `posthog-python`. In 7.x.x they reported `posthog-python-mcp`. + +Custom events from `McpAnalytics.capture()`, the handle `instrument()` returns, still report `posthog-python-mcp`. If an insight or dashboard filters on `$lib = posthog-python-mcp`, check that it still finds the events you expect. + +### Update error handling + +Capture v1 returns a result for every event, even when the request succeeds. An event can be dropped inside a 2xx response, for example when it's over a product quota. + +8.x.x reports those events as failures. When the whole request is over the billing limit, capture returns a `402` with no per-event results instead. + +Every capture failure is a `CaptureError`, a subclass of `APIError`. It has `endpoint`, `request_id`, and `attempts`, and these fields: + +| Field | Holds | +| --- | --- | +| `status` | The HTTP status, or `0` when the request never got a response | +| `drops` | A `CaptureDroppedEvent(uuid, details)` for each event capture dropped in a 2xx response | +| `retry_exhausted` | The UUIDs still waiting for a retry after the last attempt | +| `event_results` | A `CaptureEventResult(result, details)` for each UUID that got a result in a 2xx response | +| `verdict_summary()` | Counts such as `drop/llm_events_over_quota=1, retry/not_persisted=1` | + +When `status` is `0`, `__cause__` holds the network error. In 7.x.x, `on_error` received the raw `requests` exception. + +`CaptureDroppedEvent` and `CaptureEventResult` come from `posthog.capture_send`. A `CaptureDroppedEvent` is a tuple, so `for uuid, details in error.drops` also works. An event missing from `event_results` never got a result. + +`on_error` and the SDK's log lines change with it: + +- **Every failure.** `on_error(error, batch)` receives every failure, including in `sync_mode` and from `AsyncPosthog.capture_immediate`. +- **Logs with `on_error`.** With `on_error` set, the SDK logs nothing for a failed batch. +- **Logs without `on_error`.** The SDK logs one line per failed batch, for example `2 event(s) not persisted by /i/v1/analytics/events: ...`. The line never contains event content or the server's response text. After a 2xx response it also counts the lost events by PostHog's reason, for example `drop/event_too_big=1`. +- **Removed log lines.** The 7.x.x lines `error uploading: ...`, `async capture upload failed (...)`, and `Immediate async capture failed (...)` are gone. In `sync_mode`, a failed request no longer logs the 7.x.x `Error in capture: ...` line, or the same line for another method. Update any log-based alerts that match these lines. +- **Failures in `sync_mode`.** A failed `capture()` calls `on_error` and returns `None`. With `debug=True` it calls `on_error` and then re-raises the error. +- **Retries in `sync_mode`.** The SDK retries a failed request like a background batch, in the calling thread. With the default `max_retries` of 3, a call makes up to 4 attempts. Each attempt can take up to `timeout` (`capture_ai_timeout` for AI events). 7.x.x made one attempt. +- **Blocking in `sync_mode`.** With the defaults, an analytics event whose requests keep timing out blocks the call for about a minute. +- **Captures inside `on_error`.** If a capture inside `on_error` fails, the SDK logs the failure and doesn't call `on_error` again. +- **Event content.** The SDK's own log lines no longer contain event content. The debug line for a queued event names the event and the lane. The invalid timestamp warning no longer includes the value. To inspect events, use `before_send`. +- **Hook errors.** When your `before_send` hook raises, the error line names the event and the exception type, not the exception message. The message can hold the data the hook was removing. The SDK logs the traceback at debug level. + +Retries differ from 7.x.x in four ways: + +| Behavior | 7.x.x | 8.x.x | +| --- | --- | --- | +| Statuses retried | `429` and every 5xx, but not `404` | `404`, `408`, `429`, `500`, `502`, `503`, `504`, and network errors | +| Connection tries in each attempt | Up to three | One | +| First retry wait | Up to 1 second | 100 ms | +| `Consumer` default retries | 10 | 3 | + +In 8.x.x, any other error status fails the batch at once, including the other 5xx codes. In 7.x.x, a capture request could block for up to three times the `timeout` per attempt. + +In 8.x.x the wait doubles each attempt, up to 30 seconds. Each wait varies randomly by up to 25%, so many clients don't retry at the same moment. + +A `Retry-After` header sets a minimum wait, up to 30 seconds. + +Capture itself doesn't return `429`, but a proxy in front of it can. + +### Check dropped events + +Capture rejects a whole batch when one event can't be parsed. 8.x.x drops only the invalid event, so the rest of the batch is delivered. + +| Event | 8.x.x | 7.x.x | +| --- | --- | --- | +| The name is missing, `None`, empty, or not a string | Dropped, with a warning | Sent | +| A `before_send` hook sets `distinct_id` to `None` or a non-string | Dropped, with a warning | Sent, and capture rejected the whole batch | +| The name is over 200 UTF-8 bytes | Dropped by PostHog as `event_name_too_long` | Sent, with no name limit | +| A `NaN` or infinite `float` value | Sent as `null` | Sent as `null` from 7.75.0 | +| It can't be serialized to JSON, for example with a circular reference | Dropped and logged | Logged the same line | +| A property or option key JSON can't represent, such as a tuple | Key dropped without a log | Event dropped | +| A key is an `int`, finite `float`, `bool`, or `None` | Key converted to a string | Key converted to a string | +| A key is a `NaN` or infinite `float` | Event dropped | Event dropped | + +The SDK logs one warning per reason per process for a dropped name or `distinct_id`. It doesn't convert the hook's `distinct_id` or make up an ID. + +`on_error` reports an event that PostHog drops for its name. Before 7.75.0, a `NaN` or infinite `float` value made the JSON invalid, so capture rejected the whole batch. A `NaN` value in `$set` sets that person property to `null`. A circular reference logs `Error in capture: maximum recursion depth exceeded` with a long traceback. + +Capture v1 sends `$session_id` and `$window_id` as top-level event fields, not as properties. The SDK moves them out of `properties` for you, by the value's type: + +- **A string.** The SDK sends it as given, including `""`. +- **`None`.** It counts as unset, and the SDK removes it. +- **Any other value.** The SDK removes it and doesn't send it, because capture would reject the whole batch. 7.x.x sent it as a property. The SDK logs a warning for each one, with the key and the value's type but not the value. + +8.x.x applies these size and batch rules: + +- **Analytics events.** The SDK drops and logs an analytics event over 10 MiB, because no capture request can carry it. 7.x.x dropped events over 900 KiB. +- **Capture's own limit.** Capture drops an event over its own per-event limit and reports it in `CaptureError.drops` as `event_too_big`. +- **AI events.** The SDK drops and logs an AI event over `capture_ai_max_event_bytes`. +- **Batches.** A batch stops before an event that would take it past 5 MiB. A larger event is sent alone. +- **Queues.** `flush()` and `shutdown()` drain the analytics and AI queues at the same time. + +### Check exceptions + +- **The `level=` argument.** `capture_exception` takes a `level=` argument on `Client`, `AsyncPosthog`, and the module. It sets `$exception_level`, for example `"warning"` or `"fatal"`. The default is `"error"`, and an unknown value counts as unset. +- **Reserved properties.** `capture_exception` ignores reserved exception properties in `properties`, such as `$exception_list`, `$exception_level`, and `$exception_source`. In 7.x.x they overrode the SDK's values, with a `DeprecationWarning`. Use `level=` instead of `$exception_level`. +- **Async level.** `AsyncPosthog.capture_exception` now sends `$exception_level`. +- **Async trace IDs.** `AsyncPosthog.capture_exception` now adds `$trace_id` and `$span_id` from the active OpenTelemetry span, like `Client.capture_exception`. In 7.x.x it added them only with `capture_trace_context=True`. + +### Check tracing headers + +The Django, Flask, and ASGI integrations read the `X-PostHog-Distinct-Id` and `X-PostHog-Session-Id` headers by default, as in 7.71.0 and later. The headers only fill a missing distinct ID or session ID, and any client can set them, so never use them for authentication. + +- **Turn it off.** Set `POSTHOG_MW_CAPTURE_TRACING_HEADERS = False` in Django, or pass `capture_tracing_headers=False` to the Flask or ASGI integration. +- **Upgrades from 7.68.x, 7.69.x, or 7.70.x.** If you never turned these headers on, they're now read. + +## Follow ups + +### Move to event options + +Capture v1 sends processing options in an `options` object, next to `properties`. `capture`, `capture_ai`, `set`, `set_once`, `alias`, `group_identify`, and `capture_exception` take an `options` argument: + +```python +posthog.capture("signed_up", distinct_id="user-1", options={"cookieless_mode": True}) +``` + +The MCP capture methods take `event_options` instead (see [Add MCP event options](#add-mcp-event-options)). The AI integrations take `posthog_options` (see [Send AI events with capture_ai](#send-ai-events-with-capture_ai)). + +- **Every event.** `super_options`, a new `Client`, `AsyncPosthog`, and module setting, sets options on every event, like `super_properties`. +- **One context.** `set_context_option(key, value)` sets an option for the current context, like `tag()`. `get_context_options()` returns the options of the current context. Both exist on `Client` and as module functions. +- **Async contexts.** `AsyncPosthog` has no context methods, like it has no `tag()`, so call the module functions. They apply to every client in the context. +- **Celery workers.** The Celery integration propagates context options to workers, like tags. A propagated `process_person_profile: True` turns person processing on for worker events without a distinct ID. Each of those events creates a person. +- **Celery eager mode.** In eager mode (`task_always_eager`), Celery publishes nothing, so the distinct ID, tags, and options don't reach the task's events. To carry them, pass the task's PostHog headers with `task.apply(headers=...)` or `task.apply_async(headers=...)`. +- **Methods reached.** Context tags and options reach `capture`, `capture_ai`, `capture_exception`, `alias`, and `group_identify`. Context options also reach `set` and `set_once`. `super_properties` and `super_options` reach every method. +- **Validation.** Options are sent as given. PostHog validates them. It drops an event with an option value it can't read, such as a list for `cookieless_mode`, as `invalid_options`, and `on_error` reports it. +- **Values that aren't a dict.** The SDK logs an `options` value that isn't a dict as an error and ignores it. It still sends the event. +- **Boolean options.** Pass `True` or `False` for `cookieless_mode`, `disable_skew_correction`, and `process_person_profile`. PostHog also reads common forms such as `"false"`, `"off"`, or `0`. + +Each option replaces a legacy option property: + +| Option | Replaces | +| --- | --- | +| `cookieless_mode` | `$cookieless_mode` | +| `disable_skew_correction` | `$ignore_sent_at` | +| `product_tour_id` | `$product_tour_id` | +| `process_person_profile` | `$process_person_profile` | + +Legacy option properties still work, but an option overrides its legacy property. Use options. + +These four options are the full set. PostHog ignores any other key in `options`. + +Session and window IDs stay `$session_id` and `$window_id` properties (see [Check dropped events](#check-dropped-events)). + +### Send AI events with capture_ai + +Send `$ai_` events with `capture_ai`. `capture()` sends every event to `/i/v1/analytics/events`, including `$ai_` events. + +PostHog accepts them there for now, but this is temporary. + +The AI integrations take capture options: + +- **Wrapper methods.** Every wrapper method that takes `posthog_properties` also takes `posthog_options`, for the events of that call. This covers the sync and async OpenAI, Anthropic, and Gemini wrappers, and the Claude Agent SDK `query()` and `PostHogClaudeSDKClient`. The name keeps it apart from the Claude Agent SDK's own `options`. +- **Gemini clients.** The Gemini clients take `posthog_options` as a default for every call. A call's `posthog_options` win key by key. +- **Handlers and processors.** LangChain's `CallbackHandler` and `PostHogMiddleware` take `options=` for every event. So do OpenAI Agents' `instrument()` and `PostHogTracingProcessor`, and the Claude Agent SDK's `instrument()` and `PostHogClaudeAgentProcessor`. +- **Run metadata.** LangChain also reads `posthog_options` from run metadata, like `posthog_properties`. Like properties, the handler's or processor's options win over a run's or a query's. +- **Failed runs.** The `$exception` event LangChain captures for a failed run gets the same options. +- **Precedence.** These are the event's own options, so they win over context options and `super_options`, which still fill the keys they leave unset. `before_send` can still change them. +- **Values that aren't a dict.** The SDK logs a value that isn't a dict as a warning and ignores it. The provider call still runs, and the provider never receives `posthog_options`. + +Pass `posthog_options` to a wrapper call, or `options` to a handler: + +```python +from posthog.ai.langchain import CallbackHandler +from posthog.ai.openai import OpenAI + +client = OpenAI(posthog_client=posthog_client) +client.chat.completions.create( + model="gpt-5-mini", + messages=[{"role": "user", "content": "Hello"}], + posthog_distinct_id="user-1", + posthog_options={"cookieless_mode": True}, +) + +handler = CallbackHandler( + posthog_client, distinct_id="user-1", options={"cookieless_mode": True} +) +``` + +### Add MCP event options + +MCP events take options like other events, through an `event_options` argument and an `event_options` callback. + +- **The argument.** The `PostHogMCP` capture methods and `McpAnalytics.capture`, on the handle `instrument()` returns, take an `event_options` argument. The capture methods are `capture_tool_call`, `capture_initialize`, `capture_tools_list`, `capture_missing_capability`, and `capture_feedback`. +- **What the argument sets.** It sets options on that event. For a failed tool call, it also sets them on the `$exception` event. +- **The callback.** `MCPAnalyticsOptions(event_options=...)` sets options on every event `instrument()` captures automatically, including `$exception` events. It doesn't apply to `McpAnalytics.capture`. +- **The callback's shape.** Like `event_properties`, it's a function of `(request, extra)` that returns a dict or `None`, and it can be sync or async. +- **The core `capture`.** `PostHogMCP.capture()` is the core client's `capture`, so it takes `options`. The MCP capture methods take `event_options`. +- **Precedence.** The SDK passes these options as the event's own options, so they win over context options and `super_options`. +- **Events without an identity.** An event without an identity always sends `process_person_profile: False`, even when `event_options` sets it to `True`. Its distinct ID is the session ID, so person processing would create a person for each session. To process a person, identify the user with `identify` or pass `distinct_id`. +- **Values that aren't a dict.** The SDK logs an `event_options` value that isn't a dict and ignores it. It still sends the event. + +Set the callback in `instrument()`, or pass the argument to a capture method: + +```python +from posthog.mcp import MCPAnalyticsOptions, PostHogMCP, instrument + +instrument( + server, + posthog, + MCPAnalyticsOptions(event_options=lambda request, extra: {"cookieless_mode": True}), +) + +mcp_client = PostHogMCP("phc_...") +mcp_client.capture_tool_call( + "search_docs", + distinct_id="user-1", + event_options={"process_person_profile": False}, +) +``` + +`instrument()` captures `$mcp_tool_call` after the tool handler returns. A context you open inside the handler has ended by then, so options you set in it with `set_context_option` don't reach `$mcp_tool_call`. + +Events you capture inside that context still get them. To set options on `$mcp_tool_call`, use the `event_options` callback. + +### Rename deprecated settings + +These old names still work or have no effect in 8.x.x: + +| Old | New | +| --- | --- | +| `trust_tracing_headers`, `POSTHOG_MW_TRUST_TRACING_HEADERS` | `capture_tracing_headers`, `POSTHOG_MW_CAPTURE_TRACING_HEADERS` | +| `_use_ai_lane`, `_enable_multimodal_capture` | `enable_full_ai_capture` | +| `posthog.capture_mode` | Nothing | +| A `gzip=` keyword on `request.post` or `request.flags` | Nothing | + +The 7.68.x tracing header names still work, but are deprecated. `_use_ai_lane` and `_enable_multimodal_capture` still work as aliases. + +Setting `posthog.capture_mode` on the module has no effect. A `gzip=` keyword raises no error, and it's sent as a field in the request body. diff --git a/providers/README.md b/providers/README.md index 12c13e7..11d3f80 100644 --- a/providers/README.md +++ b/providers/README.md @@ -22,6 +22,7 @@ One page per plugin id: `providers/.md`. Start from [`_template.md`](_templ | [anthropic-models.md](anthropic-models.md) | `anthropic-models` | `retirements` | | [anthropic.md](anthropic.md) | `anthropic` | `migrationguide` | | [numpy.md](numpy.md) | `numpy` | `removedmembers` | +| [posthog.md](posthog.md) | `posthog` | `removedmembers` | | [textual.md](textual.md) | `textual` | `changelog` | | [urllib3.md](urllib3.md) | `urllib3` | `changelog` | | [github-actions.md](github-actions.md) | `github-actions` | `feed` | diff --git a/providers/posthog.md b/providers/posthog.md new file mode 100644 index 0000000..473547b --- /dev/null +++ b/providers/posthog.md @@ -0,0 +1,57 @@ +# PostHog (`posthog`) + +## What it watches + +Members removed from the `posthog` Python SDK in 8.0.0 (`CaptureMode`, `posthog.capture_v1`, `posthog.capture_v1.CaptureV1Error`, `posthog.request.batch_post`…): code using one breaks on the upgrade. One event per member. Pinned to that release. + +Format plugin: `removedmembers` (`plugins/removedmembers`), reading a Markdown table. + +## Why this source + +- **Source:** [`docs/migration-7.x-to-8.0.md` at posthog-v8.0.0](https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md) (commit `6edff41425188056e48f6119457dc9bc0669ca99`), read raw at the tag. Checked on 2026-11-19. The guide isn't in the repo at posthog-v7.91.4, the release before, and is the same at posthog-v8.0.2. MIT. +- **Why this one:** it's PostHog's own migration guide for the SDK's 8.0.0, and its "Fix removed APIs" section is a table of what 8.0.0 removed and what to use instead. A tag never changes, so the URL is its own citation, and 8.0.0 is a version a repo pins. +- **Alternatives considered:** + - **`references/public_api_snapshot.txt`** in the same repo: a generated listing of the public API at every tag. Diffing it between two releases gives every removed name with its full path, but no reason, replacement or announcement. The plugin reads the guide, and the listing was used to check the paths of the guide's names. + - **PostHog's REST API spec.** It's served only live, at , and isn't committed anywhere, so there's no release to pin or replay. Its history, measured on 2026-11-19 over the two Wayback Machine snapshots of the schema (app.posthog.com, 2024-05-06 and 2025-11-09) and the live copy (about two and a half years): + - operations: 391, 815, then 2,787; + - deprecations: 0 in either snapshot. The live copy marks 8 operations `deprecated: true`, all on organization routes (`advanced_activity_logs`, `desktop_beta_terms`, `integrations`) that weren't in the 2025-11-09 snapshot: they arrived already deprecated, so no operation a caller used was deprecated in the window; + - removals: 155 between the snapshots and 397 between the 2025 snapshot and live, none marked deprecated first. 308 of the 397 are `/api/environments/` operations, and 254 of those have a `/api/projects/` twin in the live spec: PostHog moving routes, not removing them. + + So the `deprecationsOnly` rule would find nothing, and a removal diff would be mostly route moves. + - **The SDK changelogs** (`posthog/CHANGELOG.md`): the 8.0.0 entry files its breaking changes under "Major changes", which the `changelog` plugin doesn't read as breaking, and in long sentences rather than plain removals. + - **The rendered docs** on posthog.com, and `references/posthog-python-migration.md` in the same repo: the same guide, as a live page and with posthog.com's front matter. +- **Quote:** "8.x.x removes these options and APIs:" (Fix removed APIs), with rows such as "| `CaptureV1Error` | `CaptureError` |". + +## How the provider announces changes + +- Package versions (SemVer). posthog-python releases often (7.89.0 to 8.0.0 in five days). 8.0.0 shipped on 2026-11-17. +- **Forced on a fresh install** for an unpinned or open pin (`posthog>=7`), otherwise when the team upgrades. +- A major release gets a migration guide in `docs/`; this is the first one there. + +## What the plugin reads and ignores + +- Reads the table under "Fix removed APIs", `| Removed | Use instead |`. A row becomes one event per name, but only when its first cell is nothing but code spans naming members. Names are written as code writes them after the import: `posthog.` is stripped, other prefixes kept. +- `removed_symbol` for every name, with the "Use instead" cell in the migration hint. Not `renamed_symbol`, even when that cell is one name: every replacement is new in 8.0.0, so a renamed import would fail on 7.x, and `CaptureError` also moves module (below). The 7 rows, checked against the code at posthog-v7.91.4 and posthog-v8.0.0: + + | Row | Events | + |---|---| + | `capture_mode`, `CaptureMode`, `POSTHOG_CAPTURE_MODE` → Nothing | `removed_symbol` `CaptureMode` (importable from `posthog`). `capture_mode` dropped: the guide's own "Rename deprecated settings" table says `posthog.capture_mode` still works or has no effect in 8.x.x, and the name also covers a `Client` argument and a module, which the row doesn't tell apart. `POSTHOG_CAPTURE_MODE` is an environment variable, not a member: dropped | + | `gzip=True` → `capture_compression` | Dropped: an argument value of a call the row doesn't name (`removed_parameter` needs the call) | + | `CaptureV1Error` → `CaptureError` | `removed_symbol` `capture_v1.CaptureV1Error` (its module), with `CaptureError` in the hint | + | `posthog.capture_v1` → `posthog.capture_event` and `posthog.capture_send` | `removed_symbol` `capture_v1` (two replacements) | + | `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, `AI_EVENTS_ENDPOINT` → Send events through a client | `removed_symbol` for each of the four, at the module the code has them in: `request.batch_post`, `_async_request.async_batch_post` (a private module), `request.EVENTS_ENDPOINT`, `request.AI_EVENTS_ENDPOINT`. The cell spells out `request.` only for the first. Checked against `references/public_api_snapshot.txt` and the code at posthog-v7.91.4 | + | The `gzip` parameter of `request.post` and `request.flags` → Nothing | Dropped: prose. Not a `removed_parameter` either: both take `**kwargs` in 8.0.0, so `gzip=` raises nothing and is sent in the request body, as the guide says | + | The `backoff` dependency → Your own requirements… | Dropped: prose, and a dependency | + + 7 events. The event's description says only that the member was removed: what code gets differs by member (an `ImportError` for most, an `AttributeError` for a module attribute). +- **`CaptureV1Error` → `CaptureError` moves module too:** from `posthog.capture_v1` to `posthog`, and `CaptureError` is new in 8.0.0. The row says only the names; the guide says the rest a few paragraphs below ("Replace `from posthog.capture_v1 import CaptureV1Error` with `from posthog import CaptureError`. There is no alias."). +- Ignores the guide's eight other tables (endpoints, AI lane arguments, error fields, retries, SDK identity, dropped events, options, and "Rename deprecated settings", whose old names still work in 8.x.x) and its prose (behavior changes such as property precedence and retries). + +## Known gaps + +- PostHog's REST API itself (see above: no pinned spec, and nothing deprecated in its history). +- **Importing the `posthog.capture_mode` module directly** (`from posthog.capture_mode import …`) breaks in 8.0.0 and gets no event of its own: the row's `capture_mode` is dropped because the guide says setting it still works. The usual use of that module, `CaptureMode`, is an event. +- posthog-js and posthog-node, and PostHog's other SDKs. +- Later majors of posthog-python: each is a new entry in this plugin. +- Behavior changes in 8.0.0 that aren't removals (keyword-only arguments, property precedence, retries, routing of AI events). +- The `posthoganalytics` package, which the guide says has the same changes.