docs: sort the 8.0.0 migration guide, and add the facts from the retired posthog.com Python page

.sampo/changesets/ai-integrations-require-capture-ai.md

@@ -2,4 +2,4 @@
 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.
+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.

.sampo/changesets/capture-hook-log-and-connection-retries.md

@@ -2,7 +2,7 @@
 pypi/posthog: patch
 ---
 
-Capture makes one connection try per attempt, so every physical request carries its own attempt number and request timestamp. 7.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.
+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.
 

.sampo/changesets/capture-same-origin-redirects.md

@@ -2,4 +2,4 @@
 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 7.x the sync client followed redirects to any origin and resent the event batch there.
+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.

.sampo/changesets/exception-level-and-reserved-properties.md

@@ -2,4 +2,4 @@
 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 7.x they overrode the SDK's values with a `DeprecationWarning`. `AsyncPosthog.capture_exception` now sends `$exception_level`.
+`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`.

.sampo/changesets/identity-and-context-rules.md

@@ -2,4 +2,4 @@
 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 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.
+`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.

.sampo/changesets/lib-is-an-sdk-value.md

@@ -2,4 +2,4 @@
 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 7.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.
+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.

.sampo/changesets/mcp-keeps-sdk-identity.md

@@ -2,4 +2,4 @@
 pypi/posthog: major
 ---
 
-MCP instrumentation no longer relabels the whole client. In 7.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.
+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.

.sampo/changesets/openfeature-provider-posthog-8.md

@@ -2,4 +2,4 @@
 pypi/openfeature-provider-posthog: minor
 ---
 
-Supports posthog 8.x as well as 7.x.
+Supports posthog-python 8.x.x as well as 7.x.x.

.sampo/changesets/request-keyword-only.md

@@ -2,4 +2,4 @@
 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 7.x call that passed them by position bound them to the wrong parameter. It now raises `TypeError`.
+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`.

.sampo/changesets/session-id-drop-warning.md

@@ -2,4 +2,4 @@
 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 7.x these values were sent as properties.
+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.

README.md

@@ -18,19 +18,21 @@ SDK usage examples and code snippets live in the official documentation so they
 
 | SDK Version   | Python Versions Supported    | Notes                      |
 | ------------- | ---------------------------- | -------------------------- |
-| 8.0.0+        | 3.10, 3.11, 3.12, 3.13, 3.14 | Capture v1 only, see the [migration guide](docs/migration-7.x-to-8.0.md) |
-| 7.3.1 - 7.x   | 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 7.x to 8.0](docs/migration-7.x-to-8.0.md)
+- [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
 

bin/docs_scripts/generate_markdown.py

@@ -214,6 +214,16 @@ def nest(markdown: str) -> str:
     return "\n".join(out)
 
 
+def migration_page(guides: list[str]) -> list[str]:
+    """The migration page. One guide's H1 becomes the page title, so the page shows one title."""
+    title = "PostHog Python SDK migration guides"
+    if len(guides) == 1 and guides[0].startswith("# "):
+        heading, _, rest = guides[0].partition("\n")
+        title, guides = heading[2:].strip(), [rest.strip()]
+    head = f"---\ntitle: {json.dumps(title)}\nsidebar: Docs\nshowTitle: true\n---"
+    return [head, *guides]
+
+
 def getting_started(major: int) -> str:
     """docs/getting-started.md for one major. Its install line pins that major, so a
     reader never installs a major the page doesn't describe."""
@@ -255,20 +265,17 @@ def main() -> None:
         started,
         *reference(pkg, capabilities(opts.sdk_specs), declared >= major),
     ]
-    title = f"PostHog Python SDK {major}.x" + (
-        "" if declared >= major else " (experimental)"
-    )
+    title = f"PostHog Python SDK {major}.x"
     write(f"posthog-python-{major}.md", [front_matter(title, body), *body])
     if declared >= major:
         write(
             "posthog-python-reference.md",
             [front_matter("PostHog Python SDK", body), *body],
         )
     if guides := sorted((ROOT / "docs").glob("migration-*.md"), reverse=True):
-        head = "---\ntitle: PostHog Python SDK migration guides\nsidebar: Docs\nshowTitle: true\n---"
         write(
             "posthog-python-migration.md",
-            [head, *(g.read_text().strip() for g in guides)],
+            migration_page([g.read_text().strip() for g in guides]),
         )
 
 

docs/getting-started.md

@@ -37,3 +37,26 @@ posthog.shutdown()
 ```
 
 In an asyncio app, use `AsyncPosthog` as an async context manager instead. See [AsyncClient](#asyncclient).
+
+## Use AsyncPosthog in FastAPI
+
+Keep one `AsyncPosthog` client for the lifetime of your app. A FastAPI lifespan handler does this.
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from posthog import AsyncPosthog
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with AsyncPosthog("<ph_project_token>", host="<ph_client_api_host>") as posthog:
+        app.state.posthog = posthog
+        yield
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## The posthoganalytics package
+
+`posthoganalytics` is the same SDK under another module name. Use it when another module named `posthog` is on your import path.