feat(flags): add a flag_fallback_cache that tracks feature flag evaluation results and uses them as fallback values whenever the /flags API isn't available (#275)

* default send_feature_flags false

* bump version

.github/workflows/call-flags-project-board.yml

@@ -0,0 +1,17 @@
+# This workflow is used to call the flags-project-board workflow when a pull request is opened, ready for review, review requested, synchronized, converted to draft, or reopened.
+# It is used to update the feature flags project board with the pull request information.
+
+name: Call Feature Flags Project Workflow
+
+on:
+    pull_request:
+        types: [opened, ready_for_review, review_requested, synchronize, converted_to_draft, reopened]
+
+jobs:
+    call-flags-project:
+        uses: PostHog/.github/.github/workflows/flags-project-board.yml@main
+        with:
+            pr_number: ${{ github.event.pull_request.number }}
+            pr_node_id: ${{ github.event.pull_request.node_id }}
+            is_draft: ${{ github.event.pull_request.draft }}
+        secrets: inherit

CHANGELOG.md

@@ -1,3 +1,78 @@
+# 6.0.3 - 2025-07-07
+
+- feat: add a feature flag evaluation cache (local storage or redis) to support returning flag evaluations when the service is down
+
+# 6.0.2 - 2025-07-02
+
+- fix: send_feature_flags changed to default to false in `Client::capture_exception`
+
+# 6.0.1
+
+- fix: response `$process_person_profile` property when passed to capture
+
+# 6.0.0
+
+This release contains a number of major breaking changes:
+- feat: make distinct_id an optional parameter in posthog.capture and related functions
+- feat: make capture and related functions return `Optional[str]`, which is the UUID of the sent event, if it was sent
+- fix: remove `identify` (prefer `posthog.set()`), and `page` and `screen` (prefer `posthog.capture()`)
+- fix: delete exception-capture specific integrations module. Prefer the general-purpose django middleware as a replacement for the django `Integration`.
+
+To migrate to this version, you'll mostly just need to switch to using named keyword arguments, rather than positional ones. For example:
+```python
+# Old calling convention
+posthog.capture("user123", "button_clicked", {"button_id": "123"})
+# New calling convention
+posthog.capture(distinct_id="user123", event="button_clicked", properties={"button_id": "123"})
+
+# Better pattern
+with posthog.new_context():
+    posthog.identify_context("user123")
+
+    # The event name is the first argument, and can be passed positionally, or as a keyword argument in a later position
+    posthog.capture("button_pressed")
+```
+
+Generally, arguments are now appropriately typed, and docstrings have been updated. If something is unclear, please open an issue, or submit a PR!
+
+# 5.4.0 - 2025-06-20
+
+- feat: add support to session_id context on page method
+
+# 5.3.0 - 2025-06-19
+
+- fix: safely handle exception values
+
+# 5.2.0 - 2025-06-19
+
+- feat: construct artificial stack traces if no traceback is available on a captured exception
+
+## 5.1.0 - 2025-06-18
+
+- feat: session and distinct ID's can now be associated with contexts, and are used as such
+- feat: django http request middleware
+
+## 5.0.0 - 2025-06-16
+
+- fix: removed deprecated sentry integration
+
+## 4.10.0 - 2025-06-13
+
+- fix: no longer fail in autocapture.
+
+## 4.9.0 - 2025-06-13
+
+- feat(ai): track reasoning and cache tokens in the LangChain callback
+
+## 4.8.0 - 2025-06-10
+
+- fix: export scoped, rather than tracked, decorator
+- feat: allow use of contexts without error tracking
+
+## 4.7.0 - 2025-06-10
+
+- feat: add support for parse endpoint in responses API (no longer beta)
+
 ## 4.6.2 - 2025-06-09
 
 - fix: replace `import posthog` with direct method imports

Makefile

@@ -35,8 +35,23 @@ release_analytics:
 e2e_test:
 	.buildscripts/e2e.sh
 
-django_example:
-	python -m pip install -e ".[sentry]"
-	cd sentry_django_example && python manage.py runserver 8080
+prep_local:
+	rm -rf ../posthog-python-local
+	mkdir ../posthog-python-local
+	cp -r . ../posthog-python-local/
+	cd ../posthog-python-local && rm -rf dist build posthoganalytics .git
+	cd ../posthog-python-local && mkdir posthoganalytics
+	cd ../posthog-python-local && cp -r posthog/* posthoganalytics/
+	cd ../posthog-python-local && find ./posthoganalytics -type f -name "*.py" -exec sed -i.bak -e 's/from posthog /from posthoganalytics /g' {} \;
+	cd ../posthog-python-local && find ./posthoganalytics -type f -name "*.py" -exec sed -i.bak -e 's/from posthog\./from posthoganalytics\./g' {} \;
+	cd ../posthog-python-local && find ./posthoganalytics -name "*.bak" -delete
+	cd ../posthog-python-local && rm -rf posthog
+	cd ../posthog-python-local && sed -i.bak 's/from version import VERSION/from posthoganalytics.version import VERSION/' setup_analytics.py
+	cd ../posthog-python-local && rm setup_analytics.py.bak
+	cd ../posthog-python-local && sed -i.bak 's/"posthog"/"posthoganalytics"/' setup.py
+	cd ../posthog-python-local && rm setup.py.bak
+	cd ../posthog-python-local && python -c "import setup_analytics" 2>/dev/null || true
+	@echo "Local copy created at ../posthog-python-local"
+	@echo "Install with: pip install -e ../posthog-python-local"
 
-.PHONY: test lint release e2e_test
+.PHONY: test lint release e2e_test prep_local

README.md

@@ -32,7 +32,7 @@ We recommend using [uv](https://docs.astral.sh/uv/). It's super fast.
 ```bash
 uv python install 3.9.19
 uv python pin 3.9.19
-uv venv env
+uv venv
 source env/bin/activate
 uv sync --extra dev --extra test
 pre-commit install
@@ -43,24 +43,24 @@ make test
 
 Assuming you have a [local version of PostHog](https://posthog.com/docs/developing-locally) running, you can run `python3 example.py` to see the library in action.
 
-### Running the Django Sentry Integration Locally
-
-There's a sample Django project included, called `sentry_django_example`, which explains how to use PostHog with Sentry.
-
-There's 2 places of importance (Changes required are all marked with TODO in the sample project directory)
-
-1. Settings.py
-    1. Input your Sentry DSN
-    2. Input your Sentry Org and ProjectID details into `PosthogIntegration()`
-    3. Add `POSTHOG_DJANGO` to settings.py. This allows the `PosthogDistinctIdMiddleware` to get the distinct_ids
-
-2. urls.py
-    1. This includes the `sentry-debug/` endpoint, which generates an exception
-
-To run things: `make django_example`. This installs the posthog-python library with the sentry-sdk add-on, and then runs the django app.
-Also start the PostHog app locally.
-Then navigate to `http://127.0.0.1:8080/sentry-debug/` and you should get an event in both Sentry and PostHog, with links to each other.
-
 ### Releasing Versions
 
-Updated are released using GitHub Actions: after bumping `version.py` in `master` and adding to `CHANGELOG.md`, go to [our release workflow's page](https://github.com/PostHog/posthog-python/actions/workflows/release.yaml) and dispatch it manually, using workflow from `master`.
+Updates are released automatically using GitHub Actions when `version.py` is updated on `master`. After bumping `version.py` in `master` and adding to `CHANGELOG.md`, the [release workflow](https://github.com/PostHog/posthog-python/blob/master/.github/workflows/release.yaml) will automatically trigger and deploy the new version.
+
+If you need to check the latest runs or manually trigger a release, you can go to [our release workflow's page](https://github.com/PostHog/posthog-python/actions/workflows/release.yaml) and dispatch it manually, using workflow from `master`.
+
+
+### Testing changes locally with the PostHog app
+
+You can run `make prep_local`, and it'll create a new folder alongside the SDK repo one called `posthog-python-local`, which you can then import into the posthog project by changing pyproject.toml to look like this:
+```toml
+dependencies = [
+    ...
+    "posthoganalytics" #NOTE: no version number
+    ...
+]
+...
+[tools.uv.sources]
+posthoganalytics = { path = "../posthog-python-local" }
+```
+This'll let you build and test SDK changes fully locally, incorporating them into your local posthog app stack. It mainly takes care of the `posthog -> posthoganalytics` module renaming. You'll need to re-run `make prep_local` each time you make a change, and re-run `uv sync --active` in the posthog app project.

example.py

@@ -41,9 +41,9 @@ print(
 
 # Capture an event
 posthog.capture(
-    "distinct_id",
     "event",
-    {"property1": "value", "property2": "value"},
+    distinct_id="distinct_id",
+    properties={"property1": "value", "property2": "value"},
     send_feature_flags=True,
 )
 
@@ -65,31 +65,35 @@ exit()
 posthog.alias("distinct_id", "new_distinct_id")
 
 posthog.capture(
-    "new_distinct_id", "event2", {"property1": "value", "property2": "value"}
+    "event2",
+    distinct_id="new_distinct_id",
+    properties={"property1": "value", "property2": "value"},
 )
 posthog.capture(
-    "new_distinct_id",
     "event-with-groups",
-    {"property1": "value", "property2": "value"},
+    distinct_id="new_distinct_id",
+    properties={"property1": "value", "property2": "value"},
     groups={"company": "id:5"},
 )
 
 # # Add properties to the person
-posthog.identify("new_distinct_id", {"email": "something@something.com"})
+posthog.set(
+    distinct_id="new_distinct_id", properties={"email": "something@something.com"}
+)
 
 # Add properties to a group
 posthog.group_identify("company", "id:5", {"employees": 11})
 
 # properties set only once to the person
-posthog.set_once("new_distinct_id", {"self_serve_signup": True})
+posthog.set_once(distinct_id="new_distinct_id", properties={"self_serve_signup": True})
 
 
 posthog.set_once(
-    "new_distinct_id", {"self_serve_signup": False}
+    distinct_id="new_distinct_id", properties={"self_serve_signup": False}
 )  # this will not change the property (because it was already set)
 
-posthog.set("new_distinct_id", {"current_browser": "Chrome"})
-posthog.set("new_distinct_id", {"current_browser": "Firefox"})
+posthog.set(distinct_id="new_distinct_id", properties={"current_browser": "Chrome"})
+posthog.set(distinct_id="new_distinct_id", properties={"current_browser": "Firefox"})
 
 
 # #############################################################################

mypy-baseline.txt

@@ -22,19 +22,25 @@ posthog/client.py:0: error: Library stubs not installed for "six"  [import-untyp
 posthog/client.py:0: note: Hint: "python3 -m pip install types-six"
 posthog/client.py:0: error: Name "queue" already defined (by an import)  [no-redef]
 posthog/client.py:0: error: Need type annotation for "queue"  [var-annotated]
-posthog/client.py:0: error: Item "None" of "Any | None" has no attribute "get"  [union-attr]
-simulator.py:0: error: Unexpected keyword argument "anonymous_id" for "capture"  [call-arg]
-posthog/__init__.py:0: note: "capture" defined here
-simulator.py:0: error: Unexpected keyword argument "anonymous_id" for "identify"  [call-arg]
-posthog/__init__.py:0: note: "identify" defined here
-simulator.py:0: error: Unexpected keyword argument "traits" for "identify"  [call-arg]
-posthog/__init__.py:0: note: "identify" defined here
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "Any | list[Any]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "dict[Any, Any]", variable has type "None")  [assignment]
+posthog/client.py:0: error: "None" has no attribute "__iter__" (not iterable)  [attr-defined]
+posthog/client.py:0: error: Statement is unreachable  [unreachable]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "Any | dict[Any, Any]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "Any | dict[Any, Any]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "dict[Never, Never]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "dict[Never, Never]", variable has type "None")  [assignment]
+posthog/client.py:0: error: Right operand of "and" is never evaluated  [unreachable]
+posthog/client.py:0: error: Incompatible types in assignment (expression has type "Poller", variable has type "None")  [assignment]
+posthog/client.py:0: error: "None" has no attribute "start"  [attr-defined]
+posthog/client.py:0: error: "None" has no attribute "get"  [attr-defined]
+posthog/client.py:0: error: Statement is unreachable  [unreachable]
+posthog/client.py:0: error: Statement is unreachable  [unreachable]
 example.py:0: error: Statement is unreachable  [unreachable]
-posthog/sentry/posthog_integration.py:0: error: Statement is unreachable  [unreachable]
 posthog/ai/utils.py:0: error: Need type annotation for "output" (hint: "output: list[<type>] = ...")  [var-annotated]
 posthog/ai/utils.py:0: error: Function "builtins.any" is not valid as a type  [valid-type]
 posthog/ai/utils.py:0: note: Perhaps you meant "typing.Any" instead of "any"?
 posthog/ai/utils.py:0: error: Function "builtins.any" is not valid as a type  [valid-type]
 posthog/ai/utils.py:0: note: Perhaps you meant "typing.Any" instead of "any"?
-sentry_django_example/sentry_django_example/settings.py:0: error: Need type annotation for "ALLOWED_HOSTS" (hint: "ALLOWED_HOSTS: list[<type>] = ...")  [var-annotated]
-sentry_django_example/sentry_django_example/settings.py:0: error: Incompatible types in assignment (expression has type "str", variable has type "None")  [assignment]
+posthog/client.py:0: error: Name "urlparse" already defined (possibly by an import)  [no-redef]
+posthog/client.py:0: error: Name "parse_qs" already defined (possibly by an import)  [no-redef]

posthog/__init__.py

@@ -1,21 +1,43 @@
 import datetime  # noqa: F401
-import warnings
-from typing import Callable, Dict, List, Optional, Tuple  # noqa: F401
+from typing import Callable, Dict, Optional, Any  # noqa: F401
+from typing_extensions import Unpack
 
+from posthog.args import OptionalCaptureArgs, OptionalSetArgs, ExceptionArg
 from posthog.client import Client
-from posthog.exception_capture import Integrations  # noqa: F401
-from posthog.scopes import clear_tags, get_tags, new_context, scoped, tag
+from posthog.contexts import (
+    new_context as inner_new_context,
+    scoped as inner_scoped,
+    tag as inner_tag,
+    set_context_session as inner_set_context_session,
+    identify_context as inner_identify_context,
+)
 from posthog.types import FeatureFlag, FlagsAndPayloads
 from posthog.version import VERSION
 
 __version__ = VERSION
 
 """Context management."""
-new_context = new_context
-tag = tag
-get_tags = get_tags
-clear_tags = clear_tags
-tracked = scoped
+
+
+def new_context(fresh=False, capture_exceptions=True):
+    return inner_new_context(fresh=fresh, capture_exceptions=capture_exceptions)
+
+
+def scoped(fresh=False, capture_exceptions=True):
+    return inner_scoped(fresh=fresh, capture_exceptions=capture_exceptions)
+
+
+def set_context_session(session_id: str):
+    return inner_set_context_session(session_id)
+
+
+def identify_context(distinct_id: str):
+    return inner_identify_context(distinct_id)
+
+
+def tag(name: str, value: Any):
+    return inner_tag(name, value)
+
 
 """Settings."""
 api_key = None  # type: Optional[str]
@@ -33,7 +55,6 @@ feature_flags_request_timeout_seconds = 3  # type: int
 super_properties = None  # type: Optional[Dict]
 # Currently alpha, use at your own risk
 enable_exception_autocapture = False  # type: bool
-exception_autocapture_integrations = []  # type: List[Integrations]
 log_captured_exceptions = False  # type: bool
 # Used to determine in app paths for exception autocapture. Defaults to the current working directory
 project_root = None  # type: Optional[str]
@@ -43,206 +64,100 @@ privacy_mode = False  # type: bool
 default_client = None  # type: Optional[Client]
 
 
-def capture(
-    distinct_id,  # type: str
-    event,  # type: str
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    groups=None,  # type: Optional[Dict]
-    send_feature_flags=False,
-    disable_geoip=None,  # type: Optional[bool]
-):
-    # type: (...) -> Tuple[bool, dict]
+# NOTE - this and following functions take unpacked kwargs because we needed to make
+# it impossible to write `posthog.capture(distinct-id, event-name)` - basically, to enforce
+# the breaking change made between 5.3.0 and 6.0.0. This decision can be unrolled in later
+# versions, without a breaking change, to get back the type information in function signatures
+def capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str]:
     """
     Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up.
 
     A `capture` call requires
-    - `distinct id` which uniquely identifies your user
     - `event name` to specify the event
     - We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on.
 
-    Optionally you can submit
-    - `properties`, which can be a dict with any information you'd like to add
-    - `groups`, which is a dict of group type -> group key mappings
+    Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.
 
     For example:
     ```python
-    posthog.capture('distinct id', 'opened app')
-    posthog.capture('distinct id', 'movie played', {'movie_id': '123', 'category': 'romcom'})
+    # Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)
+    with posthog.new_context():
+        # Associate this context with some user, by distinct_id
+        posthog.identify_context('some user')
 
-    posthog.capture('distinct id', 'purchase', groups={'company': 'id:5'})
+        # Capture an event, associated with the context-level distinct ID ('some user')
+        posthog.capture('movie started')
+
+        # Capture an event associated with some other user (overriding the context-level distinct ID)
+        posthog.capture('movie joined', distinct_id='some-other-user')
+
+        # Capture an event with some properties
+        posthog.capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})
+
+        # Capture an event with some properties
+        posthog.capture('purchase', properties={'product_id': '123', 'category': 'romcom'})
+        # Capture an event with some associated group
+        posthog.capture('purchase', groups={'company': 'id:5'})
+
+        # Adding a tag to the current context will cause it to appear on all subsequent events
+        posthog.tag_context('some-tag', 'some-value')
+
+        posthog.capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict
     ```
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-    return _proxy(
-        "capture",
-        distinct_id=distinct_id,
-        event=event,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        groups=groups,
-        send_feature_flags=send_feature_flags,
-        disable_geoip=disable_geoip,
-    )
+    return _proxy("capture", event, **kwargs)
 
 
-def identify(
-    distinct_id,  # type: str
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    disable_geoip=None,  # type: Optional[bool]
-):
-    # type: (...) -> Tuple[bool, dict]
-    """
-    Identify lets you add metadata on your users so you can more easily identify who they are in PostHog, and even do things like segment users by these properties.
-
-    An `identify` call requires
-    - `distinct id` which uniquely identifies your user
-    - `properties` with a dict with any key: value pairs
-
-    For example:
-    ```python
-    posthog.identify('distinct id', {
-        'email': 'dwayne@gmail.com',
-        'name': 'Dwayne Johnson'
-    })
-    ```
-    """
-
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-    return _proxy(
-        "identify",
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        disable_geoip=disable_geoip,
-    )
-
-
-def set(
-    distinct_id,  # type: str
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    disable_geoip=None,  # type: Optional[bool]
-):
-    # type: (...) -> Tuple[bool, dict]
+def set(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
     """
     Set properties on a user record.
-    This will overwrite previous people property values, just like `identify`.
+    This will overwrite previous people property values. Generally operates similar to `capture`, with
+    distinct_id being an optional argument, defaulting to the current context's distinct ID.
 
-     A `set` call requires
-     - `distinct id` which uniquely identifies your user
-     - `properties` with a dict with any key: value pairs
+    If there is no context-level distinct ID, and no override distinct_id is passed, this function
+    will do nothing.
+
+    Context tags are folded into $set properties, so tagging the current context and then calling `set` will
+    cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).
 
      For example:
      ```python
-     posthog.set('distinct id', {
+     posthog.set(distinct_id='distinct id', properties={
          'current_browser': 'Chrome',
      })
      ```
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-    return _proxy(
-        "set",
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        disable_geoip=disable_geoip,
-    )
+    return _proxy("set", **kwargs)
 
 
-def set_once(
-    distinct_id,  # type: str
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    disable_geoip=None,  # type: Optional[bool]
-):
-    # type: (...) -> Tuple[bool, dict]
+def set_once(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
     """
     Set properties on a user record, only if they do not yet exist.
-    This will not overwrite previous people property values, unlike `identify`.
+    This will not overwrite previous people property values, unlike `set`.
 
-     A `set_once` call requires
-     - `distinct id` which uniquely identifies your user
-     - `properties` with a dict with any key: value pairs
-
-     For example:
-     ```python
-     posthog.set_once('distinct id', {
-         'referred_by': 'friend',
-     })
+    Otherwise, operates in an identical manner to `set`.
      ```
     """
-
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-    return _proxy(
-        "set_once",
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        disable_geoip=disable_geoip,
-    )
+    return _proxy("set_once", **kwargs)
 
 
 def group_identify(
     group_type,  # type: str
     group_key,  # type: str
     properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
     timestamp=None,  # type: Optional[datetime.datetime]
     uuid=None,  # type: Optional[str]
     disable_geoip=None,  # type: Optional[bool]
 ):
-    # type: (...) -> Tuple[bool, dict]
+    # type: (...) -> Optional[str]
     """
     Set properties on a group
 
      A `group_identify` call requires
      - `group_type` type of your group
      - `group_key` unique identifier of the group
-     - `properties` with a dict with any key: value pairs
 
      For example:
      ```python
@@ -252,19 +167,11 @@ def group_identify(
      ```
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
     return _proxy(
         "group_identify",
         group_type=group_type,
         group_key=group_key,
         properties=properties,
-        context=context,
         timestamp=timestamp,
         uuid=uuid,
         disable_geoip=disable_geoip,
@@ -274,18 +181,16 @@ def group_identify(
 def alias(
     previous_id,  # type: str
     distinct_id,  # type: str
-    context=None,  # type: Optional[Dict]
     timestamp=None,  # type: Optional[datetime.datetime]
     uuid=None,  # type: Optional[str]
     disable_geoip=None,  # type: Optional[bool]
 ):
-    # type: (...) -> Tuple[bool, dict]
+    # type: (...) -> Optional[str]
     """
-    To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like "Which marketing channels leads to users churning after a month?" or "What do users do on our website before signing up?"
-
-    In a purely back-end implementation, this means whenever an anonymous user does something, you'll want to send a session ID ([Django](https://stackoverflow.com/questions/526179/in-django-how-can-i-find-out-the-request-session-sessionid-and-use-it-as-a-vari), [Flask](https://stackoverflow.com/questions/15156132/flask-login-how-to-get-session-id)) with the capture call. Then, when that users signs up, you want to do an alias call with the session ID and the newly created user ID.
-
-    The same concept applies for when a user logs in.
+    To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
+    This will allow you to answer questions like "Which marketing channels leads to users churning after a month?" or
+    "What do users do on our website before signing up?". Particularly useful for associating user behaviour before and after
+    they e.g. register, login, or perform some other identifying action.
 
     An `alias` call requires
     - `previous distinct id` the unique ID of the user before
@@ -297,18 +202,10 @@ def alias(
     ```
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
     return _proxy(
         "alias",
         previous_id=previous_id,
         distinct_id=distinct_id,
-        context=context,
         timestamp=timestamp,
         uuid=uuid,
         disable_geoip=disable_geoip,
@@ -316,58 +213,33 @@ def alias(
 
 
 def capture_exception(
-    exception=None,  # type: Optional[BaseException]
-    distinct_id=None,  # type: Optional[str]
-    properties=None,  # type: Optional[Dict]
-    context=None,  # type: Optional[Dict]
-    timestamp=None,  # type: Optional[datetime.datetime]
-    uuid=None,  # type: Optional[str]
-    groups=None,  # type: Optional[Dict]
-    **kwargs,
+    exception: Optional[ExceptionArg] = None,
+    **kwargs: Unpack[OptionalCaptureArgs],
 ):
-    # type: (...) -> Tuple[bool, dict]
     """
-    capture_exception allows you to capture exceptions that happen in your code. This is useful for debugging and understanding what errors your users are encountering.
-    This function never raises an exception, even if it fails to send the event.
+    capture_exception allows you to capture exceptions that happen in your code.
 
-    A `capture_exception` call does not require any fields, but we recommend sending:
-    - `distinct id` which uniquely identifies your user for which this exception happens
+    Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog.
+    This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception,
+    if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context
+    boundary (e.g. by existing a `with posthog.new_context():` block already)
+
+    A `capture_exception` call does not require any fields, but we recommend passing an exception of some kind:
     - `exception` to specify the exception to capture. If not provided, the current exception is captured via `sys.exc_info()`
 
-    Optionally you can submit
-    - `properties`, which can be a dict with any information you'd like to add
-    - `groups`, which is a dict of group type -> group key mappings
-    - remaining `kwargs` will be logged if `log_captured_exceptions` is enabled
+    If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised
+    and the point at which it is captured (the "traceback").
 
-    For example:
-    ```python
-    try:
-        1 / 0
-    except Exception as e:
-        posthog.capture_exception(e, 'my specific distinct id')
-        posthog.capture_exception(distinct_id='my specific distinct id')
+    If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError("Some Error"))`, the stack trace
+    captured will be the full stack trace at the moment the exception was captured.
 
-    ```
+    Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently,
+    which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason.
+
+    `capture_exception` takes the same set of optional arguments as `capture`.
     """
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-    return _proxy(
-        "capture_exception",
-        exception=exception,
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        groups=groups,
-        **kwargs,
-    )
+    return _proxy("capture_exception", exception=exception, **kwargs)
 
 
 def feature_enabled(
@@ -554,16 +426,6 @@ def load_feature_flags():
     return _proxy("load_feature_flags")
 
 
-def page(*args, **kwargs):
-    """Send a page call."""
-    _proxy("page", *args, **kwargs)
-
-
-def screen(*args, **kwargs):
-    """Send a screen call."""
-    _proxy("screen", *args, **kwargs)
-
-
 def flush():
     """Tell the client to flush."""
     _proxy("flush")
@@ -583,6 +445,8 @@ def shutdown():
 def setup():
     global default_client
     if not default_client:
+        if not api_key:
+            raise ValueError("API key is required")
         default_client = Client(
             api_key,
             host=host,
@@ -591,7 +455,6 @@ def setup():
             send=send,
             sync_mode=sync_mode,
             personal_api_key=personal_api_key,
-            project_api_key=project_api_key,
             poll_interval=poll_interval,
             disabled=disabled,
             disable_geoip=disable_geoip,
@@ -602,7 +465,6 @@ def setup():
             # or deprecate this proxy option fully (it's already in the process of deprecation, no new clients should be using this method since like 5-6 months)
             enable_exception_autocapture=enable_exception_autocapture,
             log_captured_exceptions=log_captured_exceptions,
-            exception_autocapture_integrations=exception_autocapture_integrations,
         )
 
     # always set incase user changes it

posthog/ai/langchain/callbacks.py

@@ -14,7 +14,6 @@ from typing import (
     List,
     Optional,
     Sequence,
-    Tuple,
     Union,
     cast,
 )
@@ -85,7 +84,7 @@ class CallbackHandler(BaseCallbackHandler):
     _client: Client
     """PostHog client instance."""
 
-    _distinct_id: Optional[Union[str, int, float, UUID]]
+    _distinct_id: Optional[Union[str, int, UUID]]
     """Distinct ID of the user to associate the trace with."""
 
     _trace_id: Optional[Union[str, int, float, UUID]]
@@ -113,7 +112,7 @@ class CallbackHandler(BaseCallbackHandler):
         self,
         client: Optional[Client] = None,
         *,
-        distinct_id: Optional[Union[str, int, float, UUID]] = None,
+        distinct_id: Optional[Union[str, int, UUID]] = None,
         trace_id: Optional[Union[str, int, float, UUID]] = None,
         properties: Optional[Dict[str, Any]] = None,
         privacy_mode: bool = False,
@@ -569,9 +568,14 @@ class CallbackHandler(BaseCallbackHandler):
             event_properties["$ai_is_error"] = True
         else:
             # Add usage
-            input_tokens, output_tokens = _parse_usage(output)
-            event_properties["$ai_input_tokens"] = input_tokens
-            event_properties["$ai_output_tokens"] = output_tokens
+            usage = _parse_usage(output)
+            event_properties["$ai_input_tokens"] = usage.input_tokens
+            event_properties["$ai_output_tokens"] = usage.output_tokens
+            event_properties["$ai_cache_creation_input_tokens"] = (
+                usage.cache_write_tokens
+            )
+            event_properties["$ai_cache_read_input_tokens"] = usage.cache_read_tokens
+            event_properties["$ai_reasoning_tokens"] = usage.reasoning_tokens
 
             # Generation results
             generation_result = output.generations[-1]
@@ -647,9 +651,18 @@ def _convert_message_to_dict(message: BaseMessage) -> Dict[str, Any]:
     return message_dict
 
 
+@dataclass
+class ModelUsage:
+    input_tokens: Optional[int]
+    output_tokens: Optional[int]
+    cache_write_tokens: Optional[int]
+    cache_read_tokens: Optional[int]
+    reasoning_tokens: Optional[int]
+
+
 def _parse_usage_model(
-    usage: Union[BaseModel, Dict],
-) -> Tuple[Union[int, None], Union[int, None]]:
+    usage: Union[BaseModel, dict],
+) -> ModelUsage:
     if isinstance(usage, BaseModel):
         usage = usage.__dict__
 
@@ -657,15 +670,23 @@ def _parse_usage_model(
         # https://pypi.org/project/langchain-anthropic/ (works also for Bedrock-Anthropic)
         ("input_tokens", "input"),
         ("output_tokens", "output"),
+        ("cache_creation_input_tokens", "cache_write"),
+        ("cache_read_input_tokens", "cache_read"),
         # https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/get-token-count
         ("prompt_token_count", "input"),
         ("candidates_token_count", "output"),
+        ("cached_content_token_count", "cache_read"),
+        ("thoughts_token_count", "reasoning"),
         # Bedrock: https://docs.aws.amazon.com/bedrock/latest/userguide/monitoring-cw.html#runtime-cloudwatch-metrics
         ("inputTokenCount", "input"),
         ("outputTokenCount", "output"),
+        ("cacheCreationInputTokenCount", "cache_write"),
+        ("cacheReadInputTokenCount", "cache_read"),
         # Bedrock Anthropic
         ("prompt_tokens", "input"),
         ("completion_tokens", "output"),
+        ("cache_creation_input_tokens", "cache_write"),
+        ("cache_read_input_tokens", "cache_read"),
         # langchain-ibm https://pypi.org/project/langchain-ibm/
         ("input_token_count", "input"),
         ("generated_token_count", "output"),
@@ -683,13 +704,45 @@ def _parse_usage_model(
 
             parsed_usage[type_key] = final_count
 
-    return parsed_usage.get("input"), parsed_usage.get("output")
+    # Caching (OpenAI & langchain 0.3.9+)
+    if "input_token_details" in usage and isinstance(
+        usage["input_token_details"], dict
+    ):
+        parsed_usage["cache_write"] = usage["input_token_details"].get("cache_creation")
+        parsed_usage["cache_read"] = usage["input_token_details"].get("cache_read")
+
+    # Reasoning (OpenAI & langchain 0.3.9+)
+    if "output_token_details" in usage and isinstance(
+        usage["output_token_details"], dict
+    ):
+        parsed_usage["reasoning"] = usage["output_token_details"].get("reasoning")
+
+    field_mapping = {
+        "input": "input_tokens",
+        "output": "output_tokens",
+        "cache_write": "cache_write_tokens",
+        "cache_read": "cache_read_tokens",
+        "reasoning": "reasoning_tokens",
+    }
+    return ModelUsage(
+        **{
+            dataclass_key: parsed_usage.get(mapped_key) or 0
+            for mapped_key, dataclass_key in field_mapping.items()
+        },
+    )
 
 
-def _parse_usage(response: LLMResult):
+def _parse_usage(response: LLMResult) -> ModelUsage:
     # langchain-anthropic uses the usage field
     llm_usage_keys = ["token_usage", "usage"]
-    llm_usage: Tuple[Union[int, None], Union[int, None]] = (None, None)
+    llm_usage: ModelUsage = ModelUsage(
+        input_tokens=None,
+        output_tokens=None,
+        cache_write_tokens=None,
+        cache_read_tokens=None,
+        reasoning_tokens=None,
+    )
+
     if response.llm_output is not None:
         for key in llm_usage_keys:
             if response.llm_output.get(key):

posthog/ai/openai/openai.py

@@ -230,6 +230,42 @@ class WrappedResponses:
                 groups=posthog_groups,
             )
 
+    def parse(
+        self,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_trace_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool = False,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        """
+        Parse structured output using OpenAI's 'responses.parse' method, but also track usage in PostHog.
+
+        Args:
+            posthog_distinct_id: Optional ID to associate with the usage event.
+            posthog_trace_id: Optional trace UUID for linking events.
+            posthog_properties: Optional dictionary of extra properties to include in the event.
+            posthog_privacy_mode: Whether to anonymize the input and output.
+            posthog_groups: Optional dictionary of groups to associate with the event.
+            **kwargs: Any additional parameters for the OpenAI Responses Parse API.
+
+        Returns:
+            The response from OpenAI's responses.parse call.
+        """
+        return call_llm_and_track_usage(
+            posthog_distinct_id,
+            self._client._ph_client,
+            "openai",
+            posthog_trace_id,
+            posthog_properties,
+            posthog_privacy_mode,
+            posthog_groups,
+            self._client.base_url,
+            self._original.parse,
+            **kwargs,
+        )
+
 
 class WrappedChat:
     """Wrapper for OpenAI chat that tracks usage in PostHog."""

posthog/ai/openai/openai_async.py

@@ -230,6 +230,42 @@ class WrappedResponses:
                 groups=posthog_groups,
             )
 
+    async def parse(
+        self,
+        posthog_distinct_id: Optional[str] = None,
+        posthog_trace_id: Optional[str] = None,
+        posthog_properties: Optional[Dict[str, Any]] = None,
+        posthog_privacy_mode: bool = False,
+        posthog_groups: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        """
+        Parse structured output using OpenAI's 'responses.parse' method, but also track usage in PostHog.
+
+        Args:
+            posthog_distinct_id: Optional ID to associate with the usage event.
+            posthog_trace_id: Optional trace UUID for linking events.
+            posthog_properties: Optional dictionary of extra properties to include in the event.
+            posthog_privacy_mode: Whether to anonymize the input and output.
+            posthog_groups: Optional dictionary of groups to associate with the event.
+            **kwargs: Any additional parameters for the OpenAI Responses Parse API.
+
+        Returns:
+            The response from OpenAI's responses.parse call.
+        """
+        return await call_llm_and_track_usage_async(
+            posthog_distinct_id,
+            self._client._ph_client,
+            "openai",
+            posthog_trace_id,
+            posthog_properties,
+            posthog_privacy_mode,
+            posthog_groups,
+            self._client.base_url,
+            self._original.parse,
+            **kwargs,
+        )
+
 
 class WrappedChat:
     """Async wrapper for OpenAI chat that tracks usage in PostHog."""

posthog/args.py

@@ -0,0 +1,68 @@
+from typing import TypedDict, Optional, Any, Dict, Union, Tuple, Type
+from types import TracebackType
+from typing_extensions import NotRequired  # For Python < 3.11 compatibility
+from datetime import datetime
+import numbers
+from uuid import UUID
+
+ID_TYPES = Union[numbers.Number, str, UUID, int]
+
+
+class OptionalCaptureArgs(TypedDict):
+    """Optional arguments for the capture method.
+
+    Args:
+        distinct_id: Unique identifier for the person associated with this event. If not set, the context
+            distinct_id is used, if available, otherwise a UUID is generated, and the event is marked
+            as personless. Setting context-level distinct_id's is recommended.
+        properties: Dictionary of properties to track with the event
+        timestamp: When the event occurred (defaults to current time)
+        uuid: Unique identifier for this specific event. If not provided, one is generated. The event
+            UUID is returned, so you can correlate it with actions in your app (like showing users an
+            error ID if you capture an exception).
+        groups: Group identifiers to associate with this event (format: {group_type: group_key})
+        send_feature_flags: Whether to include currently active feature flags in the event properties.
+            Defaults to False
+        disable_geoip: Whether to disable GeoIP lookup for this event. Defaults to False.
+    """
+
+    distinct_id: NotRequired[Optional[ID_TYPES]]
+    properties: NotRequired[Optional[Dict[str, Any]]]
+    timestamp: NotRequired[Optional[Union[datetime, str]]]
+    uuid: NotRequired[Optional[str]]
+    groups: NotRequired[Optional[Dict[str, str]]]
+    send_feature_flags: NotRequired[
+        Optional[bool]
+    ]  # Optional so we can tell if the user is intentionally overriding a client setting or not
+    disable_geoip: NotRequired[
+        Optional[bool]
+    ]  # As above, optional so we can tell if the user is intentionally overriding a client setting or not
+
+
+class OptionalSetArgs(TypedDict):
+    """Optional arguments for the set method.
+
+    Args:
+        distinct_id: Unique identifier for the user to set properties on. If not set, the context
+            distinct_id is used, if available, otherwise this function does nothing. Setting
+            context-level distinct_id's is recommended.
+        properties: Dictionary of properties to set on the person
+        timestamp: When the properties were set (defaults to current time)
+        uuid: Unique identifier for this operation. If not provided, one is generated. This
+            UUID is returned, so you can correlate it with actions in your app.
+        disable_geoip: Whether to disable GeoIP lookup for this operation. Defaults to False.
+    """
+
+    distinct_id: NotRequired[Optional[ID_TYPES]]
+    properties: NotRequired[Optional[Dict[str, Any]]]
+    timestamp: NotRequired[Optional[Union[datetime, str]]]
+    uuid: NotRequired[Optional[str]]
+    disable_geoip: NotRequired[Optional[bool]]
+
+
+ExcInfo = Union[
+    Tuple[Type[BaseException], BaseException, Optional[TracebackType]],
+    Tuple[None, None, None],
+]
+
+ExceptionArg = Union[BaseException, ExcInfo]

posthog/client.py

@@ -1,24 +1,24 @@
 import atexit
 import logging
-import numbers
 import os
-import platform
 import sys
-import warnings
 from datetime import datetime, timedelta
-from typing import Any, Optional, Union
-from uuid import UUID, uuid4
+from typing import Any, Dict, Optional, Union
+from typing_extensions import Unpack
+from uuid import uuid4
 
-import distro  # For Linux OS detection
 from dateutil.tz import tzutc
 from six import string_types
 
+from posthog.args import OptionalCaptureArgs, OptionalSetArgs, ID_TYPES, ExceptionArg
 from posthog.consumer import Consumer
 from posthog.exception_capture import ExceptionCapture
 from posthog.exception_utils import (
     exc_info_from_error,
     exceptions_from_error_tuple,
     handle_in_app,
+    exception_is_already_captured,
+    mark_exception_as_captured,
 )
 from posthog.feature_flags import InconclusiveMatchError, match_feature_flag_properties
 from posthog.poller import Poller
@@ -31,7 +31,12 @@ from posthog.request import (
     get,
     remote_config,
 )
-from posthog.scopes import get_tags
+from posthog.contexts import (
+    _get_current_context,
+    get_context_distinct_id,
+    get_context_session_id,
+    new_context,
+)
 from posthog.types import (
     FeatureFlag,
     FeatureFlagResult,
@@ -44,7 +49,15 @@ from posthog.types import (
     to_payloads,
     to_values,
 )
-from posthog.utils import SizeLimitedDict, clean, guess_timezone, remove_trailing_slash
+from posthog.utils import (
+    FlagCache,
+    RedisFlagCache,
+    SizeLimitedDict,
+    clean,
+    guess_timezone,
+    remove_trailing_slash,
+    system_context,
+)
 from posthog.version import VERSION
 
 try:
@@ -53,72 +66,67 @@ except ImportError:
     import Queue as queue
 
 
-ID_TYPES = (numbers.Number, string_types, UUID)
 MAX_DICT_SIZE = 50_000
 
 
-def get_os_info():
-    """
-    Returns standardized OS name and version information.
-    Similar to how user agent parsing works in JS.
-    """
-    os_name = ""
-    os_version = ""
+def get_identity_state(passed) -> tuple[str, bool]:
+    """Returns the distinct id to use, and whether this is a personless event or not"""
+    stringified = stringify_id(passed)
+    if stringified and len(stringified):
+        return (stringified, False)
 
-    platform_name = sys.platform
+    context_id = get_context_distinct_id()
+    if context_id:
+        return (context_id, False)
 
-    if platform_name.startswith("win"):
-        os_name = "Windows"
-        if hasattr(platform, "win32_ver"):
-            win_version = platform.win32_ver()[0]
-            if win_version:
-                os_version = win_version
-
-    elif platform_name == "darwin":
-        os_name = "Mac OS X"
-        if hasattr(platform, "mac_ver"):
-            mac_version = platform.mac_ver()[0]
-            if mac_version:
-                os_version = mac_version
-
-    elif platform_name.startswith("linux"):
-        os_name = "Linux"
-        linux_info = distro.info()
-        if linux_info["version"]:
-            os_version = linux_info["version"]
-
-    elif platform_name.startswith("freebsd"):
-        os_name = "FreeBSD"
-        if hasattr(platform, "release"):
-            os_version = platform.release()
-
-    else:
-        os_name = platform_name
-        if hasattr(platform, "release"):
-            os_version = platform.release()
-
-    return os_name, os_version
+    return (str(uuid4()), True)
 
 
-def system_context() -> dict[str, Any]:
-    os_name, os_version = get_os_info()
+def add_context_tags(properties):
+    current_context = _get_current_context()
+    if current_context:
+        context_tags = current_context.collect_tags()
+        # We want explicitly passed properties to override context tags
+        context_tags.update(properties)
+        properties = context_tags
 
-    return {
-        "$python_runtime": platform.python_implementation(),
-        "$python_version": "%s.%s.%s" % (sys.version_info[:3]),
-        "$os": os_name,
-        "$os_version": os_version,
-    }
+    if "$session_id" not in properties and get_context_session_id():
+        properties["$session_id"] = get_context_session_id()
+
+    return properties
 
 
 class Client(object):
-    """Create a new PostHog client."""
+    """Create a new PostHog client.
+
+    Examples:
+        Basic usage:
+        >>> client = Client("your-api-key")
+
+        With memory-based feature flag fallback cache:
+        >>> client = Client(
+        ...     "your-api-key",
+        ...     flag_fallback_cache_url="memory://local/?ttl=300&size=10000"
+        ... )
+
+        With Redis fallback cache for high-scale applications:
+        >>> client = Client(
+        ...     "your-api-key",
+        ...     flag_fallback_cache_url="redis://localhost:6379/0/?ttl=300"
+        ... )
+
+        With Redis authentication:
+        >>> client = Client(
+        ...     "your-api-key",
+        ...     flag_fallback_cache_url="redis://username:password@localhost:6379/0/?ttl=300"
+        ... )
+    """
 
     log = logging.getLogger("posthog")
 
     def __init__(
         self,
-        api_key=None,
+        project_api_key: str,
         host=None,
         debug=False,
         max_queue_size=10000,
@@ -133,7 +141,6 @@ class Client(object):
         thread=1,
         poll_interval=30,
         personal_api_key=None,
-        project_api_key=None,
         disabled=False,
         disable_geoip=True,
         historical_migration=False,
@@ -141,17 +148,15 @@ class Client(object):
         super_properties=None,
         enable_exception_autocapture=False,
         log_captured_exceptions=False,
-        exception_autocapture_integrations=None,
         project_root=None,
         privacy_mode=False,
         before_send=None,
+        flag_fallback_cache_url=None,
     ):
         self.queue = queue.Queue(max_queue_size)
 
         # api_key: This should be the Team API Key (token), public
-        self.api_key = project_api_key or api_key
-
-        require("api_key", self.api_key, string_types)
+        self.api_key = project_api_key
 
         self.on_error = on_error
         self.debug = debug
@@ -172,13 +177,14 @@ class Client(object):
         )
         self.poller = None
         self.distinct_ids_feature_flags_reported = SizeLimitedDict(MAX_DICT_SIZE, set)
+        self.flag_cache = self._initialize_flag_cache(flag_fallback_cache_url)
+        self.flag_definition_version = 0
         self.disabled = disabled
         self.disable_geoip = disable_geoip
         self.historical_migration = historical_migration
         self.super_properties = super_properties
         self.enable_exception_autocapture = enable_exception_autocapture
         self.log_captured_exceptions = log_captured_exceptions
-        self.exception_autocapture_integrations = exception_autocapture_integrations
         self.exception_capture = None
         self.privacy_mode = privacy_mode
 
@@ -210,9 +216,7 @@ class Client(object):
             self.before_send = None
 
         if self.enable_exception_autocapture:
-            self.exception_capture = ExceptionCapture(
-                self, integrations=self.exception_autocapture_integrations
-            )
+            self.exception_capture = ExceptionCapture(self)
 
         if sync_mode:
             self.consumers = None
@@ -245,6 +249,11 @@ class Client(object):
                 if send:
                     consumer.start()
 
+    def new_context(self, fresh=False, capture_exceptions=True):
+        return new_context(
+            fresh=fresh, capture_exceptions=capture_exceptions, client=self
+        )
+
     @property
     def feature_flags(self):
         """
@@ -267,36 +276,6 @@ class Client(object):
             "feature_flags_by_key should be initialized when feature_flags is set"
         )
 
-    def identify(
-        self,
-        distinct_id=None,
-        properties=None,
-        context=None,
-        timestamp=None,
-        uuid=None,
-        disable_geoip=None,
-    ):
-        if context is not None:
-            warnings.warn(
-                "The 'context' parameter is deprecated and will be removed in a future version.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
-        properties = properties or {}
-        require("distinct_id", distinct_id, ID_TYPES)
-        require("properties", properties, dict)
-
-        msg = {
-            "timestamp": timestamp,
-            "distinct_id": distinct_id,
-            "$set": properties,
-            "event": "$identify",
-            "uuid": uuid,
-        }
-
-        return self._enqueue(msg, disable_geoip)
-
     def get_feature_variants(
         self,
         distinct_id,
@@ -347,8 +326,8 @@ class Client(object):
 
     def get_flags_decision(
         self,
-        distinct_id,
-        groups=None,
+        distinct_id: Optional[ID_TYPES] = None,
+        groups: Optional[dict] = {},
         person_properties=None,
         group_properties=None,
         disable_geoip=None,
@@ -356,14 +335,14 @@ class Client(object):
         """
         Get feature flags decision, using either flags() or decide() API based on rollout.
         """
-        require("distinct_id", distinct_id, ID_TYPES)
+
+        if distinct_id is None:
+            distinct_id = get_context_distinct_id()
 
         if disable_geoip is None:
             disable_geoip = self.disable_geoip
 
-        if groups:
-            require("groups", groups, dict)
-        else:
+        if not groups:
             groups = {}
 
         request_data = {
@@ -384,34 +363,24 @@ class Client(object):
         return normalize_flags_response(resp_data)
 
     def capture(
-        self,
-        distinct_id=None,
-        event=None,
-        properties=None,
-        context=None,
-        timestamp=None,
-        uuid=None,
-        groups=None,
-        send_feature_flags=False,
-        disable_geoip=None,
-    ):
-        if context is not None:
-            warnings.warn(
-                "The 'context' parameter is deprecated and will be removed in a future version.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+        self, event: str, **kwargs: Unpack[OptionalCaptureArgs]
+    ) -> Optional[str]:
+        distinct_id = kwargs.get("distinct_id", None)
+        properties = kwargs.get("properties", None)
+        timestamp = kwargs.get("timestamp", None)
+        uuid = kwargs.get("uuid", None)
+        groups = kwargs.get("groups", None)
+        send_feature_flags = kwargs.get("send_feature_flags", False)
+        disable_geoip = kwargs.get("disable_geoip", None)
 
         properties = {**(properties or {}), **system_context()}
 
-        require("distinct_id", distinct_id, ID_TYPES)
-        require("properties", properties, dict)
-        require("event", event, string_types)
+        properties = add_context_tags(properties)
 
-        # Grab current context tags, if any exist
-        context_tags = get_tags()
-        if context_tags:
-            properties.update(context_tags)
+        (distinct_id, personless) = get_identity_state(distinct_id)
+
+        if personless and "$process_person_profile" not in properties:
+            properties["$process_person_profile"] = False
 
         msg = {
             "properties": properties,
@@ -422,7 +391,6 @@ class Client(object):
         }
 
         if groups:
-            require("groups", groups, dict)
             msg["properties"]["$groups"] = groups
 
         extra_properties: dict[str, Any] = {}
@@ -462,25 +430,21 @@ class Client(object):
 
         return self._enqueue(msg, disable_geoip)
 
-    def set(
-        self,
-        distinct_id=None,
-        properties=None,
-        context=None,
-        timestamp=None,
-        uuid=None,
-        disable_geoip=None,
-    ):
-        if context is not None:
-            warnings.warn(
-                "The 'context' parameter is deprecated and will be removed in a future version.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+    def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
+        distinct_id = kwargs.get("distinct_id", None)
+        properties = kwargs.get("properties", None)
+        timestamp = kwargs.get("timestamp", None)
+        uuid = kwargs.get("uuid", None)
+        disable_geoip = kwargs.get("disable_geoip", None)
 
         properties = properties or {}
-        require("distinct_id", distinct_id, ID_TYPES)
-        require("properties", properties, dict)
+
+        properties = add_context_tags(properties)
+
+        (distinct_id, personless) = get_identity_state(distinct_id)
+
+        if personless or not properties:
+            return None  # Personless set() does nothing
 
         msg = {
             "timestamp": timestamp,
@@ -492,25 +456,20 @@ class Client(object):
 
         return self._enqueue(msg, disable_geoip)
 
-    def set_once(
-        self,
-        distinct_id=None,
-        properties=None,
-        context=None,
-        timestamp=None,
-        uuid=None,
-        disable_geoip=None,
-    ):
-        if context is not None:
-            warnings.warn(
-                "The 'context' parameter is deprecated and will be removed in a future version.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
+    def set_once(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
+        distinct_id = kwargs.get("distinct_id", None)
+        properties = kwargs.get("properties", None)
+        timestamp = kwargs.get("timestamp", None)
+        uuid = kwargs.get("uuid", None)
+        disable_geoip = kwargs.get("disable_geoip", None)
         properties = properties or {}
-        require("distinct_id", distinct_id, ID_TYPES)
-        require("properties", properties, dict)
+
+        properties = add_context_tags(properties)
+
+        (distinct_id, personless) = get_identity_state(distinct_id)
+
+        if personless or not properties:
+            return None  # Personless set_once() does nothing
 
         msg = {
             "timestamp": timestamp,
@@ -524,30 +483,18 @@ class Client(object):
 
     def group_identify(
         self,
-        group_type=None,
-        group_key=None,
+        group_type: str,
+        group_key: str,
         properties=None,
-        context=None,
         timestamp=None,
         uuid=None,
         disable_geoip=None,
         distinct_id=None,
     ):
-        if context is not None:
-            warnings.warn(
-                "The 'context' parameter is deprecated and will be removed in a future version.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
         properties = properties or {}
-        require("group_type", group_type, ID_TYPES)
-        require("group_key", group_key, ID_TYPES)
-        require("properties", properties, dict)
 
-        if distinct_id:
-            require("distinct_id", distinct_id, ID_TYPES)
-        else:
-            distinct_id = "${}_{}".format(group_type, group_key)
+        # group_identify is purposefully always personful
+        distinct_id = get_identity_state(distinct_id)[0]
 
         msg = {
             "event": "$groupidentify",
@@ -561,26 +508,24 @@ class Client(object):
             "uuid": uuid,
         }
 
+        # NOTE - group_identify doesn't generally use context properties - should it?
+        if get_context_session_id():
+            msg["properties"]["$session_id"] = get_context_session_id()
+
         return self._enqueue(msg, disable_geoip)
 
     def alias(
         self,
-        previous_id=None,
-        distinct_id=None,
-        context=None,
+        previous_id: str,
+        distinct_id: Optional[str],
         timestamp=None,
         uuid=None,
         disable_geoip=None,
     ):
-        if context is not None:
-            warnings.warn(
-                "The 'context' parameter is deprecated and will be removed in a future version.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
+        (distinct_id, personless) = get_identity_state(distinct_id)
 
-        require("previous_id", previous_id, ID_TYPES)
-        require("distinct_id", distinct_id, ID_TYPES)
+        if personless:
+            return None  # Personless alias() does nothing - should this throw?
 
         msg = {
             "properties": {
@@ -590,82 +535,32 @@ class Client(object):
             "timestamp": timestamp,
             "event": "$create_alias",
             "distinct_id": previous_id,
-        }
-
-        return self._enqueue(msg, disable_geoip)
-
-    def page(
-        self,
-        distinct_id=None,
-        url=None,
-        properties=None,
-        context=None,
-        timestamp=None,
-        uuid=None,
-        disable_geoip=None,
-    ):
-        if context is not None:
-            warnings.warn(
-                "The 'context' parameter is deprecated and will be removed in a future version.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
-        properties = properties or {}
-        require("distinct_id", distinct_id, ID_TYPES)
-        require("properties", properties, dict)
-
-        require("url", url, string_types)
-        properties["$current_url"] = url
-
-        msg = {
-            "event": "$pageview",
-            "properties": properties,
-            "timestamp": timestamp,
-            "distinct_id": distinct_id,
             "uuid": uuid,
         }
 
+        if get_context_session_id():
+            msg["properties"]["$session_id"] = get_context_session_id()
+
         return self._enqueue(msg, disable_geoip)
 
     def capture_exception(
         self,
-        exception=None,
-        distinct_id=None,
-        properties=None,
-        context=None,
-        timestamp=None,
-        uuid=None,
-        groups=None,
-        **kwargs,
+        exception: Optional[ExceptionArg],
+        **kwargs: Unpack[OptionalCaptureArgs],
     ):
-        if context is not None:
-            warnings.warn(
-                "The 'context' parameter is deprecated and will be removed in a future version.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
+        distinct_id = kwargs.get("distinct_id", None)
+        properties = kwargs.get("properties", None)
+        send_feature_flags = kwargs.get("send_feature_flags", False)
+        disable_geoip = kwargs.get("disable_geoip", None)
         # this function shouldn't ever throw an error, so it logs exceptions instead of raising them.
         # this is important to ensure we don't unexpectedly re-raise exceptions in the user's code.
         try:
             properties = properties or {}
 
             # Check if this exception has already been captured
-            if exception is not None and hasattr(
-                exception, "__posthog_exception_captured"
-            ):
+            if exception is not None and exception_is_already_captured(exception):
                 self.log.debug("Exception already captured, skipping")
-                return
-
-            # if there's no distinct_id, we'll generate one and set personless mode
-            # via $process_person_profile = false
-            if distinct_id is None:
-                properties["$process_person_profile"] = False
-                distinct_id = uuid4()
-
-            require("distinct_id", distinct_id, ID_TYPES)
-            require("properties", properties, dict)
+                return None
 
             if exception is not None:
                 exc_info = exc_info_from_error(exception)
@@ -674,7 +569,7 @@ class Client(object):
 
             if exc_info is None or exc_info == (None, None, None):
                 self.log.warning("No exception information available")
-                return
+                return None
 
             # Format stack trace for cymbal
             all_exceptions_with_trace = exceptions_from_error_tuple(exc_info)
@@ -703,40 +598,54 @@ class Client(object):
             if self.log_captured_exceptions:
                 self.log.exception(exception, extra=kwargs)
 
+            timestamp = kwargs.get("timestamp", None)
+            uuid = kwargs.get("uuid", None)
+            groups = kwargs.get("groups", None)
             res = self.capture(
-                distinct_id, "$exception", properties, context, timestamp, uuid, groups
+                "$exception",
+                distinct_id=distinct_id,
+                properties=properties,
+                timestamp=timestamp,
+                uuid=uuid,
+                groups=groups,
+                send_feature_flags=send_feature_flags,
+                disable_geoip=disable_geoip,
             )
 
             # Mark the exception as captured to prevent duplicate captures
-            if exception is not None:
-                setattr(exception, "__posthog_exception_captured", True)
+            if exception is not None and res is not None:
+                mark_exception_as_captured(exception, res)
 
             return res
         except Exception as e:
             self.log.exception(f"Failed to capture exception: {e}")
 
     def _enqueue(self, msg, disable_geoip):
+        # type: (...) -> Optional[str]
         """Push a new `msg` onto the queue, return `(success, msg)`"""
 
         if self.disabled:
-            return False, "disabled"
+            return None
 
         timestamp = msg["timestamp"]
         if timestamp is None:
             timestamp = datetime.now(tz=tzutc())
 
-        require("timestamp", timestamp, datetime)
-
         # add common
         timestamp = guess_timezone(timestamp)
         msg["timestamp"] = timestamp.isoformat()
 
-        # only send if "uuid" is truthy
         if "uuid" in msg:
             uuid = msg.pop("uuid")
             if uuid:
                 msg["uuid"] = stringify_id(uuid)
 
+        if "uuid" not in msg:
+            # Always send a uuid, so we can always return one
+            msg["uuid"] = stringify_id(uuid4())
+
+        sent_uuid = msg["uuid"]
+
         if not msg.get("properties"):
             msg["properties"] = {}
         msg["properties"]["$lib"] = "posthog-python"
@@ -760,7 +669,7 @@ class Client(object):
                 modified_msg = self.before_send(msg)
                 if modified_msg is None:
                     self.log.debug("Event dropped by before_send callback")
-                    return True, None
+                    return None
                 msg = modified_msg
             except Exception as e:
                 self.log.exception(f"Error in before_send callback: {e}")
@@ -770,7 +679,7 @@ class Client(object):
 
         # if send is False, return msg as if it was successfully queued
         if not self.send:
-            return True, msg
+            return sent_uuid
 
         if self.sync_mode:
             self.log.debug("enqueued with blocking %s.", msg["event"])
@@ -783,15 +692,15 @@ class Client(object):
                 historical_migration=self.historical_migration,
             )
 
-            return True, msg
+            return sent_uuid
 
         try:
             self.queue.put(msg, block=False)
             self.log.debug("enqueued %s.", msg["event"])
-            return True, msg
+            return sent_uuid
         except queue.Full:
             self.log.warning("analytics-python queue is full")
-            return False, msg
+            return None
 
     def flush(self):
         """Forces a flush from the internal queue to the server"""
@@ -826,6 +735,9 @@ class Client(object):
 
     def _load_feature_flags(self):
         try:
+            # Store old flags to detect changes
+            old_flags_by_key: dict[str, dict] = self.feature_flags_by_key or {}
+
             response = get(
                 self.personal_api_key,
                 f"/api/feature_flag/local_evaluation/?token={self.api_key}&send_cohorts",
@@ -837,6 +749,14 @@ class Client(object):
             self.group_type_mapping = response["group_type_mapping"] or {}
             self.cohorts = response["cohorts"] or {}
 
+            # Check if flag definitions changed and update version
+            if self.flag_cache and old_flags_by_key != (
+                self.feature_flags_by_key or {}
+            ):
+                old_version = self.flag_definition_version
+                self.flag_definition_version += 1
+                self.flag_cache.invalidate_version(old_version)
+
         except APIError as e:
             if e.status == 401:
                 self.log.error(
@@ -858,6 +778,10 @@ class Client(object):
                 self.group_type_mapping = {}
                 self.cohorts = {}
 
+                # Clear flag cache when quota limited
+                if self.flag_cache:
+                    self.flag_cache.clear()
+
                 if self.debug:
                     raise APIError(
                         status=402,
@@ -969,21 +893,17 @@ class Client(object):
 
     def _get_feature_flag_result(
         self,
-        key,
-        distinct_id,
+        key: str,
+        distinct_id: ID_TYPES,
         *,
         override_match_value: Optional[FlagValue] = None,
-        groups={},
+        groups: Dict[str, str] = {},
         person_properties={},
         group_properties={},
         only_evaluate_locally=False,
         send_feature_flag_events=True,
         disable_geoip=None,
     ) -> Optional[FeatureFlagResult]:
-        require("key", key, string_types)
-        require("distinct_id", distinct_id, ID_TYPES)
-        require("groups", groups, dict)
-
         if self.disabled:
             return None
 
@@ -1012,6 +932,12 @@ class Client(object):
             flag_result = FeatureFlagResult.from_value_and_payload(
                 key, lookup_match_value, payload
             )
+
+            # Cache successful local evaluation
+            if self.flag_cache and flag_result:
+                self.flag_cache.set_cached_flag(
+                    distinct_id, key, flag_result, self.flag_definition_version
+                )
         elif not only_evaluate_locally:
             try:
                 flag_details, request_id = self._get_feature_flag_details_from_decide(
@@ -1025,12 +951,30 @@ class Client(object):
                 flag_result = FeatureFlagResult.from_flag_details(
                     flag_details, override_match_value
                 )
+
+                # Cache successful remote evaluation
+                if self.flag_cache and flag_result:
+                    self.flag_cache.set_cached_flag(
+                        distinct_id, key, flag_result, self.flag_definition_version
+                    )
+
                 self.log.debug(
                     f"Successfully computed flag remotely: #{key} -> #{flag_result}"
                 )
             except Exception as e:
                 self.log.exception(f"[FEATURE FLAGS] Unable to get flag remotely: {e}")
 
+                # Fallback to cached value if remote evaluation fails
+                if self.flag_cache:
+                    stale_result = self.flag_cache.get_stale_cached_flag(
+                        distinct_id, key
+                    )
+                    if stale_result:
+                        self.log.info(
+                            f"[FEATURE FLAGS] Using stale cached value for flag {key}"
+                        )
+                        flag_result = stale_result
+
         if send_feature_flag_events:
             self._capture_feature_flag_called(
                 distinct_id,
@@ -1109,7 +1053,7 @@ class Client(object):
     def _locally_evaluate_flag(
         self,
         key: str,
-        distinct_id: str,
+        distinct_id: ID_TYPES,
         groups: dict[str, str],
         person_properties: dict[str, str],
         group_properties: dict[str, str],
@@ -1173,7 +1117,7 @@ class Client(object):
     def _get_feature_flag_details_from_decide(
         self,
         key: str,
-        distinct_id: str,
+        distinct_id: ID_TYPES,
         groups: dict[str, str],
         person_properties: dict[str, str],
         group_properties: dict[str, str],
@@ -1192,12 +1136,12 @@ class Client(object):
 
     def _capture_feature_flag_called(
         self,
-        distinct_id: str,
+        distinct_id: ID_TYPES,
         key: str,
         response: Optional[FlagValue],
         payload: Optional[str],
         flag_was_locally_evaluated: bool,
-        groups: dict[str, str],
+        groups: Dict[str, str],
         disable_geoip: Optional[bool],
         request_id: Optional[str],
         flag_details: Optional[FeatureFlag],
@@ -1235,9 +1179,9 @@ class Client(object):
                         properties["$feature_flag_id"] = flag_details.metadata.id
 
             self.capture(
-                distinct_id,
                 "$feature_flag_called",
-                properties,
+                distinct_id=distinct_id,
+                properties=properties,
                 groups=groups,
                 disable_geoip=disable_geoip,
             )
@@ -1355,16 +1299,13 @@ class Client(object):
 
     def _get_all_flags_and_payloads_locally(
         self,
-        distinct_id,
+        distinct_id: ID_TYPES,
         *,
-        groups={},
+        groups: Dict[str, Union[str, int]],
         person_properties={},
         group_properties={},
         warn_on_unknown_groups=False,
     ) -> tuple[FlagsAndPayloads, bool]:
-        require("distinct_id", distinct_id, ID_TYPES)
-        require("groups", groups, dict)
-
         if self.feature_flags is None and self.personal_api_key:
             self.load_feature_flags()
 
@@ -1404,6 +1345,99 @@ class Client(object):
             "featureFlagPayloads": payloads,
         }, fallback_to_decide
 
+    def _initialize_flag_cache(self, cache_url):
+        """Initialize feature flag cache for graceful degradation during service outages.
+
+        When enabled, the cache stores flag evaluation results and serves them as fallback
+        when the PostHog API is unavailable. This ensures your application continues to
+        receive flag values even during outages.
+
+        Args:
+            cache_url: Cache configuration URL. Examples:
+                - None: Disable caching
+                - "memory://local/?ttl=300&size=10000": Memory cache with TTL and size
+                - "redis://localhost:6379/0/?ttl=300": Redis cache with TTL
+                - "redis://username:password@host:port/?ttl=300": Redis with auth
+
+        Example usage:
+            # Memory cache
+            client = Client(
+                "your-api-key",
+                flag_fallback_cache_url="memory://local/?ttl=300&size=10000"
+            )
+
+            # Redis cache
+            client = Client(
+                "your-api-key",
+                flag_fallback_cache_url="redis://localhost:6379/0/?ttl=300"
+            )
+
+            # Normal evaluation - cache is populated
+            flag_value = client.get_feature_flag("my-flag", "user123")
+
+            # During API outage - returns cached value instead of None
+            flag_value = client.get_feature_flag("my-flag", "user123")  # Uses cache
+        """
+        if not cache_url:
+            return None
+
+        try:
+            from urllib.parse import urlparse, parse_qs
+        except ImportError:
+            from urlparse import urlparse, parse_qs
+
+        try:
+            parsed = urlparse(cache_url)
+            scheme = parsed.scheme.lower()
+            query_params = parse_qs(parsed.query)
+            ttl = int(query_params.get("ttl", [300])[0])
+
+            if scheme == "memory":
+                size = int(query_params.get("size", [10000])[0])
+                return FlagCache(size, ttl)
+
+            elif scheme == "redis":
+                try:
+                    # Not worth importing redis if we're not using it
+                    import redis
+
+                    redis_url = f"{parsed.scheme}://"
+                    if parsed.username or parsed.password:
+                        redis_url += f"{parsed.username or ''}:{parsed.password or ''}@"
+                    redis_url += (
+                        f"{parsed.hostname or 'localhost'}:{parsed.port or 6379}"
+                    )
+                    if parsed.path:
+                        redis_url += parsed.path
+
+                    client = redis.from_url(redis_url)
+
+                    # Test connection before using it
+                    client.ping()
+
+                    return RedisFlagCache(client, default_ttl=ttl)
+
+                except ImportError:
+                    self.log.warning(
+                        "[FEATURE FLAGS] Redis not available, flag caching disabled"
+                    )
+                    return None
+                except Exception as e:
+                    self.log.warning(
+                        f"[FEATURE FLAGS] Redis connection failed: {e}, flag caching disabled"
+                    )
+                    return None
+            else:
+                raise ValueError(
+                    f"Unknown cache URL scheme: {scheme}. Supported schemes: memory, redis"
+                )
+
+        except Exception as e:
+            self.log.warning(
+                f"[FEATURE FLAGS] Failed to parse cache URL '{cache_url}': {e}"
+            )
+            return None
+
     def feature_flag_definitions(self):
         return self.feature_flags
 
@@ -1426,13 +1460,6 @@ class Client(object):
         return all_person_properties, all_group_properties
 
 
-def require(name, field, data_type):
-    """Require that the named `field` has the right `data_type`"""
-    if not isinstance(field, data_type):
-        msg = "{0} must have {1}, got: {2}".format(name, data_type, field)
-        raise AssertionError(msg)
-
-
 def stringify_id(val):
     if val is None:
         return None

posthog/contexts.py

@@ -0,0 +1,254 @@
+import contextvars
+from contextlib import contextmanager
+from typing import Optional, Any, Callable, Dict, TypeVar, cast, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # To avoid circular imports
+    from posthog.client import Client
+
+
+class ContextScope:
+    def __init__(
+        self,
+        parent=None,
+        fresh: bool = False,
+        capture_exceptions: bool = True,
+        client: Optional["Client"] = None,
+    ):
+        self.client: Optional[Client] = client
+        self.parent = parent
+        self.fresh = fresh
+        self.capture_exceptions = capture_exceptions
+        self.session_id: Optional[str] = None
+        self.distinct_id: Optional[str] = None
+        self.tags: Dict[str, Any] = {}
+
+    def set_session_id(self, session_id: str):
+        self.session_id = session_id
+
+    def set_distinct_id(self, distinct_id: str):
+        self.distinct_id = distinct_id
+
+    def add_tag(self, key: str, value: Any):
+        self.tags[key] = value
+
+    def get_parent(self):
+        return self.parent
+
+    def get_session_id(self) -> Optional[str]:
+        if self.session_id is not None:
+            return self.session_id
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_session_id()
+        return None
+
+    def get_distinct_id(self) -> Optional[str]:
+        if self.distinct_id is not None:
+            return self.distinct_id
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_distinct_id()
+        return None
+
+    def collect_tags(self) -> Dict[str, Any]:
+        tags = self.tags.copy()
+        if self.parent and not self.fresh:
+            # We want child tags to take precedence over parent tags,
+            # so we can't use a simple update here, instead collecting
+            # the parent tags and then updating with the child tags.
+            new_tags = self.parent.collect_tags()
+            tags.update(new_tags)
+        return tags
+
+
+_context_stack: contextvars.ContextVar[Optional[ContextScope]] = contextvars.ContextVar(
+    "posthog_context_stack", default=None
+)
+
+
+def _get_current_context() -> Optional[ContextScope]:
+    return _context_stack.get()
+
+
+@contextmanager
+def new_context(
+    fresh=False, capture_exceptions=True, client: Optional["Client"] = None
+):
+    """
+    Create a new context scope that will be active for the duration of the with block.
+    Any tags set within this scope will be isolated to this context. Any exceptions raised
+    or events captured within the context will be tagged with the context tags.
+
+    Args:
+        fresh: Whether to start with a fresh context (default: False).
+               If False, inherits tags, identity and session id's from parent context.
+               If True, starts with no state
+        capture_exceptions: Whether to capture exceptions raised within the context (default: True).
+               If True, captures exceptions and tags them with the context tags before propagating them.
+               If False, exceptions will propagate without being tagged or captured.
+        client: Optional client instance to use for capturing exceptions (default: None).
+                If provided, the client will be used to capture exceptions within the context.
+                If not provided, the default (global) client will be used. Note that the passed
+                client is only used to capture exceptions within the context - other events captured
+                within the context via `Client.capture` or `posthog.capture` will still carry the context
+                state (tags, identity, session id), but will be captured by the client directly used (or
+                the global one, in the case of `posthog.capture`)
+
+    Examples:
+        # Inherit parent context tags
+        with posthog.new_context():
+            posthog.tag("request_id", "123")
+            # Both this event and the exception will be tagged with the context tags
+            posthog.capture("event_name", {"property": "value"})
+            raise ValueError("Something went wrong")
+
+        # Start with fresh context (no inherited tags)
+        with posthog.new_context(fresh=True):
+            posthog.tag("request_id", "123")
+            # Both this event and the exception will be tagged with the context tags
+            posthog.capture("event_name", {"property": "value"})
+            raise ValueError("Something went wrong")
+
+    """
+    from posthog import capture_exception
+
+    current_context = _get_current_context()
+    new_context = ContextScope(current_context, fresh, capture_exceptions, client)
+    _context_stack.set(new_context)
+
+    try:
+        yield
+    except Exception as e:
+        if new_context.capture_exceptions:
+            if new_context.client:
+                new_context.client.capture_exception(e)
+            else:
+                capture_exception(e)
+        raise
+    finally:
+        _context_stack.set(new_context.get_parent())
+
+
+def tag(key: str, value: Any) -> None:
+    """
+    Add a tag to the current context. All tags are added as properties to any event, including exceptions, captured
+    within the context.
+
+    Args:
+        key: The tag key
+        value: The tag value
+
+    Example:
+        posthog.tag("user_id", "123")
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.add_tag(key, value)
+
+
+def get_tags() -> Dict[str, Any]:
+    """
+    Get all tags from the current context. Note, modifying
+    the returned dictionary will not affect the current context.
+
+    Returns:
+        Dict of all tags in the current context
+    """
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.collect_tags()
+    return {}
+
+
+def identify_context(distinct_id: str) -> None:
+    """
+    Identify the current context with a distinct ID, associating all events captured in this or
+    child contexts with the given distinct ID (unless identify_context is called again). This is overridden by
+    distinct id's passed directly to posthog.capture and related methods (identify, set etc). Entering a
+    fresh context will clear the context-level distinct ID. The distinct-id passed should be uniquely associated
+    with one of your users. Events captured outside of a context, or in a context with no associated distinct
+    ID, will be assigned a random UUID, and captured as "personless".
+
+    Args:
+        distinct_id: The distinct ID to associate with the current context and its children.
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_distinct_id(distinct_id)
+
+
+def set_context_session(session_id: str) -> None:
+    """
+    Set the session ID for the current context, associating all events captured in this or
+    child contexts with the given session ID (unless set_context_session is called again).
+    Entering a fresh context will clear the context-level session ID.
+
+    Args:
+        session_id: The session ID to associate with the current context and its children. See https://posthog.com/docs/data/sessions
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_session_id(session_id)
+
+
+def get_context_session_id() -> Optional[str]:
+    """
+    Get the session ID for the current context.
+
+    Returns:
+        The session ID if set, None otherwise
+    """
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_session_id()
+    return None
+
+
+def get_context_distinct_id() -> Optional[str]:
+    """
+    Get the distinct ID for the current context.
+
+    Returns:
+        The distinct ID if set, None otherwise
+    """
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_distinct_id()
+    return None
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def scoped(fresh=False, capture_exceptions=True):
+    """
+    Decorator that creates a new context for the function. Simply wraps
+    the function in a with posthog.new_context(): block.
+
+    Args:
+        fresh: Whether to start with a fresh context (default: False)
+        capture_exceptions: Whether to capture and track exceptions with posthog error tracking (default: True)
+
+    Example:
+        @posthog.scoped()
+        def process_payment(payment_id):
+            posthog.tag("payment_id", payment_id)
+            posthog.tag("payment_method", "credit_card")
+
+            # This event will be captured with tags
+            posthog.capture("payment_started")
+            # If this raises an exception, it will be captured with tags
+            # and then re-raised
+            some_risky_function()
+    """
+
+    def decorator(func: F) -> F:
+        from functools import wraps
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            with new_context(fresh=fresh, capture_exceptions=capture_exceptions):
+                return func(*args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator

posthog/exception_capture.py

@@ -6,47 +6,25 @@
 import logging
 import sys
 import threading
-from enum import Enum
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from posthog.client import Client
 
 
-class Integrations(str, Enum):
-    Django = "django"
-
-
 class ExceptionCapture:
     # TODO: Add client side rate limiting to prevent spamming the server with exceptions
 
     log = logging.getLogger("posthog")
 
-    def __init__(
-        self, client: "Client", integrations: Optional[List[Integrations]] = None
-    ):
+    def __init__(self, client: "Client"):
         self.client = client
         self.original_excepthook = sys.excepthook
         sys.excepthook = self.exception_handler
         threading.excepthook = self.thread_exception_handler
-        self.enabled_integrations = []
-
-        for integration in integrations or []:
-            # TODO: Maybe find a better way of enabling integrations
-            # This is very annoying currently if we had to add any configuration per integration
-            if integration == Integrations.Django:
-                try:
-                    from posthog.exception_integrations.django import DjangoIntegration
-
-                    enabled_integration = DjangoIntegration(self.exception_receiver)
-                    self.enabled_integrations.append(enabled_integration)
-                except Exception as e:
-                    self.log.exception(f"Failed to enable Django integration: {e}")
 
     def close(self):
         sys.excepthook = self.original_excepthook
-        for integration in self.enabled_integrations:
-            integration.uninstall()
 
     def exception_handler(self, exc_type, exc_value, exc_traceback):
         # don't affect default behaviour.
@@ -66,6 +44,6 @@ class ExceptionCapture:
     def capture_exception(self, exception, metadata=None):
         try:
             distinct_id = metadata.get("distinct_id") if metadata else None
-            self.client.capture_exception(exception, distinct_id)
+            self.client.capture_exception(exception, distinct_id=distinct_id)
         except Exception as e:
             self.log.exception(f"Failed to capture exception: {e}")

posthog/exception_integrations/__init__.py

@@ -1,5 +0,0 @@
-class IntegrationEnablingError(Exception):
-    """
-    The integration could not be enabled due to a user error like
-    `django` not being installed for the `DjangoIntegration`.
-    """

posthog/exception_integrations/django.py

@@ -1,117 +0,0 @@
-# Portions of this file are derived from getsentry/sentry-javascript by Software, Inc. dba Sentry
-# Licensed under the MIT License
-
-# 💖open source (under MIT License)
-
-import re
-import sys
-from typing import TYPE_CHECKING
-
-from posthog.exception_integrations import IntegrationEnablingError
-
-try:
-    from django import VERSION as DJANGO_VERSION
-    from django.core import signals
-
-except ImportError:
-    raise IntegrationEnablingError("Django not installed")
-
-
-if TYPE_CHECKING:
-    from typing import Any, Dict  # noqa: F401
-
-    from django.core.handlers.wsgi import WSGIRequest  # noqa: F401
-
-
-class DjangoIntegration:
-    # TODO: Abstract integrations one we have more and can see patterns
-    """
-    Autocapture errors from a Django application.
-    """
-
-    identifier = "django"
-
-    def __init__(self, capture_exception_fn=None):
-        if DJANGO_VERSION < (4, 2):
-            raise IntegrationEnablingError("Django 4.2 or newer is required.")
-
-        # TODO: Right now this seems too complicated / overkill for us, but seems like we can automatically plug in middlewares
-        # which is great for users (they don't need to do this) and everything should just work.
-        # We should consider this in the future, but for now we can just use the middleware and signals handlers.
-        # See: https://github.com/getsentry/sentry-python/blob/269d96d6e9821122fbff280e6a26956e5ed03c0b/sentry_sdk/integrations/django/__init__.py
-
-        self.capture_exception_fn = capture_exception_fn
-
-        def _got_request_exception(request=None, **kwargs):
-            # type: (WSGIRequest, **Any) -> None
-
-            extra_props = {}
-            if request is not None:
-                # get headers metadata
-                extra_props = DjangoRequestExtractor(request).extract_person_data()
-
-            self.capture_exception_fn(sys.exc_info(), extra_props)
-
-        signals.got_request_exception.connect(_got_request_exception)
-
-    def uninstall(self):
-        pass
-
-
-class DjangoRequestExtractor:
-    def __init__(self, request):
-        # type: (Any) -> None
-        self.request = request
-
-    def extract_person_data(self):
-        headers = self.headers()
-
-        # Extract traceparent and tracestate headers
-        traceparent = headers.get("Traceparent")
-        tracestate = headers.get("Tracestate")
-
-        # Extract the distinct_id from tracestate
-        distinct_id = None
-        if tracestate:
-            # TODO: Align on the format of the distinct_id in tracestate
-            # We can't have comma or equals in header values here, so maybe we should base64 encode it?
-            match = re.search(r"posthog-distinct-id=([^,]+)", tracestate)
-            if match:
-                distinct_id = match.group(1)
-
-        return {
-            **self.user(),
-            "distinct_id": distinct_id,
-            "ip": headers.get("X-Forwarded-For"),
-            "user_agent": headers.get("User-Agent"),
-            "traceparent": traceparent,
-            "$request_path": self.request.path,
-        }
-
-    def user(self):
-        user_data: dict[str, str] = {}
-
-        user = getattr(self.request, "user", None)
-
-        if user is None or not user.is_authenticated:
-            return user_data
-
-        try:
-            user_id = str(user.pk)
-            if user_id:
-                user_data.setdefault("$user_id", user_id)
-        except Exception:
-            pass
-
-        try:
-            email = str(user.email)
-            if email:
-                user_data.setdefault("email", email)
-        except Exception:
-            pass
-
-        return user_data
-
-    def headers(self):
-        # type: () -> Dict[str, str]
-        return dict(self.request.headers)

posthog/exception_utils.py

@@ -9,8 +9,26 @@ import linecache
 import os
 import re
 import sys
+import types
 from datetime import datetime
-from typing import TYPE_CHECKING
+from types import FrameType, TracebackType  # noqa: F401
+from typing import (  # noqa: F401
+    Any,
+    Dict,
+    Iterator,
+    List,
+    Literal,
+    Optional,
+    Set,
+    Tuple,
+    TypedDict,
+    TypeVar,
+    Union,
+    cast,
+    TYPE_CHECKING,
+)
+
+from posthog.args import ExcInfo, ExceptionArg  # noqa: F401
 
 try:
     # Python 3.11
@@ -22,85 +40,61 @@ except ImportError:
 
 DEFAULT_MAX_VALUE_LENGTH = 1024
 
+LogLevelStr = Literal["fatal", "critical", "error", "warning", "info", "debug"]
 
-if TYPE_CHECKING:
-    from types import FrameType, TracebackType
-    from typing import (  # noqa: F401
-        Any,
-        Callable,
-        Dict,
-        Iterator,
-        List,
-        Literal,
-        Optional,
-        Set,
-        Tuple,
-        Type,
-        TypedDict,
-        TypeVar,
-        Union,
-        cast,
-    )
-
-    ExcInfo = Union[
-        Tuple[Type[BaseException], BaseException, Optional[TracebackType]],
-        Tuple[None, None, None],
-    ]
-    LogLevelStr = Literal["fatal", "critical", "error", "warning", "info", "debug"]
-
-    Event = TypedDict(
-        "Event",
-        {
-            "breadcrumbs": Dict[
-                Literal["values"], List[Dict[str, Any]]
-            ],  # TODO: We can expand on this type
-            "check_in_id": str,
-            "contexts": Dict[str, Dict[str, object]],
-            "dist": str,
-            "duration": Optional[float],
-            "environment": str,
-            "errors": List[Dict[str, Any]],  # TODO: We can expand on this type
-            "event_id": str,
-            "exception": Dict[
-                Literal["values"], List[Dict[str, Any]]
-            ],  # TODO: We can expand on this type
-            # "extra": MutableMapping[str, object],
-            # "fingerprint": List[str],
-            "level": LogLevelStr,
-            # "logentry": Mapping[str, object],
-            "logger": str,
-            # "measurements": Dict[str, MeasurementValue],
-            "message": str,
-            "modules": Dict[str, str],
-            # "monitor_config": Mapping[str, object],
-            "monitor_slug": Optional[str],
-            "platform": Literal["python"],
-            "profile": object,  # Should be sentry_sdk.profiler.Profile, but we can't import that here due to circular imports
-            "release": str,
-            "request": Dict[str, object],
-            # "sdk": Mapping[str, object],
-            "server_name": str,
-            "spans": List[Dict[str, object]],
-            "stacktrace": Dict[
-                str, object
-            ],  # We access this key in the code, but I am unsure whether we ever set it
-            "start_timestamp": datetime,
-            "status": Optional[str],
-            # "tags": MutableMapping[
-            #     str, str
-            # ],  # Tags must be less than 200 characters each
-            "threads": Dict[
-                Literal["values"], List[Dict[str, Any]]
-            ],  # TODO: We can expand on this type
-            "timestamp": Optional[datetime],  # Must be set before sending the event
-            "transaction": str,
-            # "transaction_info": Mapping[str, Any],  # TODO: We can expand on this type
-            "type": Literal["check_in", "transaction"],
-            "user": Dict[str, object],
-            "_metrics_summary": Dict[str, object],
-        },
-        total=False,
-    )
+Event = TypedDict(
+    "Event",
+    {
+        "breadcrumbs": Dict[
+            Literal["values"], List[Dict[str, Any]]
+        ],  # TODO: We can expand on this type
+        "check_in_id": str,
+        "contexts": Dict[str, Dict[str, object]],
+        "dist": str,
+        "duration": Optional[float],
+        "environment": str,
+        "errors": List[Dict[str, Any]],  # TODO: We can expand on this type
+        "event_id": str,
+        "exception": Dict[
+            Literal["values"], List[Dict[str, Any]]
+        ],  # TODO: We can expand on this type
+        # "extra": MutableMapping[str, object],
+        # "fingerprint": List[str],
+        "level": LogLevelStr,
+        # "logentry": Mapping[str, object],
+        "logger": str,
+        # "measurements": Dict[str, MeasurementValue],
+        "message": str,
+        "modules": Dict[str, str],
+        # "monitor_config": Mapping[str, object],
+        "monitor_slug": Optional[str],
+        "platform": Literal["python"],
+        "profile": object,
+        "release": str,
+        "request": Dict[str, object],
+        # "sdk": Mapping[str, object],
+        "server_name": str,
+        "spans": List[Dict[str, object]],
+        "stacktrace": Dict[
+            str, object
+        ],  # We access this key in the code, but I am unsure whether we ever set it
+        "start_timestamp": datetime,
+        "status": Optional[str],
+        # "tags": MutableMapping[
+        #     str, str
+        # ],  # Tags must be less than 200 characters each
+        "threads": Dict[
+            Literal["values"], List[Dict[str, Any]]
+        ],  # TODO: We can expand on this type
+        "timestamp": Optional[datetime],  # Must be set before sending the event
+        "transaction": str,
+        # "transaction_info": Mapping[str, Any],  # TODO: We can expand on this type
+        "type": Literal["check_in", "transaction"],
+        "user": Dict[str, object],
+        "_metrics_summary": Dict[str, object],
+    },
+    total=False,
+)
 
 
 epoch = datetime(1970, 1, 1)
@@ -136,9 +130,6 @@ def event_hint_with_exc_info(exc_info=None):
 class AnnotatedValue:
     """
     Meta information for a data field in the event payload.
-    This is to tell Relay that we have tampered with the fields value.
-    See:
-    https://github.com/getsentry/relay/blob/be12cd49a0f06ea932ed9b9f93a655de5d6ad6d1/relay-general/src/types/meta.rs#L407-L423
     """
 
     __slots__ = ("value", "metadata")
@@ -364,12 +355,9 @@ def filename_for_module(module, abs_path):
 def serialize_frame(
     frame,
     tb_lineno=None,
-    include_local_variables=True,
-    include_source_context=True,
     max_value_length=None,
-    custom_repr=None,
 ):
-    # type: (FrameType, Optional[int], bool, bool, Optional[int], Optional[Callable[..., Optional[str]]]) -> Dict[str, Any]
+    # type: (FrameType, Optional[int], Optional[int]) -> Dict[str, Any]
     f_code = getattr(frame, "f_code", None)
     if not f_code:
         abs_path = None
@@ -394,50 +382,13 @@ def serialize_frame(
         "lineno": tb_lineno,
     }  # type: Dict[str, Any]
 
-    if include_source_context:
-        rv["pre_context"], rv["context_line"], rv["post_context"] = get_source_context(
-            frame, tb_lineno, max_value_length
-        )
-
-    if include_local_variables:
-        # TODO(nk): Sort out this current invalid import
-        # from sentry_sdk.serializer import serialize
-
-        # rv["vars"] = serialize(
-        #     dict(frame.f_locals), is_vars=True, custom_repr=custom_repr
-        # )
-        pass
+    rv["pre_context"], rv["context_line"], rv["post_context"] = get_source_context(
+        frame, tb_lineno, max_value_length
+    )
 
     return rv
 
 
-def current_stacktrace(
-    include_local_variables=True,  # type: bool
-    include_source_context=True,  # type: bool
-    max_value_length=None,  # type: Optional[int]
-):
-    # type: (...) -> Dict[str, Any]
-    __tracebackhide__ = True
-    frames = []
-
-    f = sys._getframe()  # type: Optional[FrameType]
-    while f is not None:
-        if not should_hide_frame(f):
-            frames.append(
-                serialize_frame(
-                    f,
-                    include_local_variables=include_local_variables,
-                    include_source_context=include_source_context,
-                    max_value_length=max_value_length,
-                )
-            )
-        f = f.f_back
-
-    frames.reverse()
-
-    return {"frames": frames, "type": "raw"}
-
-
 def get_errno(exc_value):
     # type: (BaseException) -> Optional[Any]
     return getattr(exc_value, "errno", None)
@@ -445,18 +396,19 @@ def get_errno(exc_value):
 
 def get_error_message(exc_value):
     # type: (Optional[BaseException]) -> str
-    return (
+    message = (
         getattr(exc_value, "message", "")
         or getattr(exc_value, "detail", "")
-        or safe_str(exc_value)
+        or exc_value
     )
 
+    return safe_str(message)
+
 
 def single_exception_from_error_tuple(
     exc_type,  # type: Optional[type]
     exc_value,  # type: Optional[BaseException]
     tb,  # type: Optional[TracebackType]
-    client_options=None,  # type: Optional[Dict[str, Any]]
     mechanism=None,  # type: Optional[Dict[str, Any]]
     exception_id=None,  # type: Optional[int]
     parent_id=None,  # type: Optional[int]
@@ -464,10 +416,7 @@ def single_exception_from_error_tuple(
 ):
     # type: (...) -> Dict[str, Any]
     """
-    Creates a dict that goes into the events `exception.values` list and is ingestible by Sentry.
-
-    See the Exception Interface documentation for more details:
-    https://develop.sentry.dev/sdk/event-payloads/exception/
+    Creates a dict that goes into the events `exception.values` list
     """
     exception_value = {}  # type: Dict[str, Any]
     exception_value["mechanism"] = (
@@ -507,25 +456,13 @@ def single_exception_from_error_tuple(
     exception_value["type"] = get_type_name(exc_type)
     exception_value["value"] = get_error_message(exc_value)
 
-    if client_options is None:
-        include_local_variables = True
-        include_source_context = True
-        max_value_length = DEFAULT_MAX_VALUE_LENGTH  # fallback
-        custom_repr = None
-    else:
-        include_local_variables = client_options["include_local_variables"]
-        include_source_context = client_options["include_source_context"]
-        max_value_length = client_options["max_value_length"]
-        custom_repr = client_options.get("custom_repr")
+    max_value_length = DEFAULT_MAX_VALUE_LENGTH  # fallback
 
     frames = [
         serialize_frame(
             tb.tb_frame,
             tb_lineno=tb.tb_lineno,
-            include_local_variables=include_local_variables,
-            include_source_context=include_source_context,
             max_value_length=max_value_length,
-            custom_repr=custom_repr,
         )
         for tb in iter_stacks(tb)
     ]
@@ -581,7 +518,6 @@ def exceptions_from_error(
     exc_type,  # type: Optional[type]
     exc_value,  # type: Optional[BaseException]
     tb,  # type: Optional[TracebackType]
-    client_options=None,  # type: Optional[Dict[str, Any]]
     mechanism=None,  # type: Optional[Dict[str, Any]]
     exception_id=0,  # type: int
     parent_id=0,  # type: int
@@ -591,16 +527,12 @@ def exceptions_from_error(
     """
     Creates the list of exceptions.
     This can include chained exceptions and exceptions from an ExceptionGroup.
-
-    See the Exception Interface documentation for more details:
-    https://develop.sentry.dev/sdk/event-payloads/exception/
     """
 
     parent = single_exception_from_error_tuple(
         exc_type=exc_type,
         exc_value=exc_value,
         tb=tb,
-        client_options=client_options,
         mechanism=mechanism,
         exception_id=exception_id,
         parent_id=parent_id,
@@ -628,7 +560,6 @@ def exceptions_from_error(
                 exc_type=type(cause),
                 exc_value=cause,
                 tb=getattr(cause, "__traceback__", None),
-                client_options=client_options,
                 mechanism=mechanism,
                 exception_id=exception_id,
                 source="__cause__",
@@ -649,7 +580,6 @@ def exceptions_from_error(
                 exc_type=type(context),
                 exc_value=context,
                 tb=getattr(context, "__traceback__", None),
-                client_options=client_options,
                 mechanism=mechanism,
                 exception_id=exception_id,
                 source="__context__",
@@ -664,7 +594,6 @@ def exceptions_from_error(
                 exc_type=type(e),
                 exc_value=e,
                 tb=getattr(e, "__traceback__", None),
-                client_options=client_options,
                 mechanism=mechanism,
                 exception_id=exception_id,
                 parent_id=parent_id,
@@ -677,7 +606,6 @@ def exceptions_from_error(
 
 def exceptions_from_error_tuple(
     exc_info,  # type: ExcInfo
-    client_options=None,  # type: Optional[Dict[str, Any]]
     mechanism=None,  # type: Optional[Dict[str, Any]]
 ):
     # type: (...) -> List[Dict[str, Any]]
@@ -692,7 +620,6 @@ def exceptions_from_error_tuple(
             exc_type=exc_type,
             exc_value=exc_value,
             tb=tb,
-            client_options=client_options,
             mechanism=mechanism,
             exception_id=0,
             parent_id=0,
@@ -702,9 +629,7 @@ def exceptions_from_error_tuple(
         exceptions = []
         for exc_type, exc_value, tb in walk_exception_chain(exc_info):
             exceptions.append(
-                single_exception_from_error_tuple(
-                    exc_type, exc_value, tb, client_options, mechanism
-                )
+                single_exception_from_error_tuple(exc_type, exc_value, tb, mechanism)
             )
 
     exceptions.reverse()
@@ -793,11 +718,42 @@ def set_in_app_in_frames(frames, in_app_exclude, in_app_include, project_root=No
     return frames
 
 
+def exception_is_already_captured(error):
+    # type: (ExceptionArg) -> bool
+    if isinstance(error, BaseException):
+        return hasattr(error, "__posthog_exception_captured")
+    # Autocaptured exceptions are passed as a tuple from our system hooks,
+    # the second item is the exception value (the first is the exception type)
+    elif isinstance(error, tuple) and len(error) > 1:
+        return error[1] is not None and hasattr(
+            error[1], "__posthog_exception_captured"
+        )
+    else:
+        return False  # type: ignore[unreachable]
+
+
+def mark_exception_as_captured(error, uuid):
+    # type: (ExceptionArg, str) -> None
+    if isinstance(error, BaseException):
+        setattr(error, "__posthog_exception_captured", True)
+        setattr(error, "__posthog_exception_uuid", uuid)
+    # Autocaptured exceptions are passed as a tuple from our system hooks,
+    # the second item is the exception value (the first is the exception type)
+    elif isinstance(error, tuple) and len(error) > 1:
+        if error[1] is not None:
+            setattr(error[1], "__posthog_exception_captured", True)
+            setattr(error[1], "__posthog_exception_uuid", uuid)
+
+
 def exc_info_from_error(error):
-    # type: (Union[BaseException, ExcInfo]) -> ExcInfo
+    # type: (ExceptionArg) -> ExcInfo
     if isinstance(error, tuple) and len(error) == 3:
         exc_type, exc_value, tb = error
     elif isinstance(error, BaseException):
+        try:
+            construct_artificial_traceback(error)
+        except Exception:
+            pass
         tb = getattr(error, "__traceback__", None)
         if tb is not None:
             exc_type = type(error)
@@ -822,25 +778,29 @@ def exc_info_from_error(error):
     return exc_info
 
 
-def event_from_exception(
-    exc_info,  # type: Union[BaseException, ExcInfo]
-    client_options=None,  # type: Optional[Dict[str, Any]]
-    mechanism=None,  # type: Optional[Dict[str, Any]]
-):
-    # type: (...) -> Tuple[Event, Dict[str, Any]]
-    exc_info = exc_info_from_error(exc_info)
-    hint = event_hint_with_exc_info(exc_info)
-    return (
-        {
-            "level": "error",
-            "exception": {
-                "values": exceptions_from_error_tuple(
-                    exc_info, client_options, mechanism
-                )
-            },
-        },
-        hint,
-    )
+def construct_artificial_traceback(e):
+    # type: (BaseException) -> None
+    if getattr(e, "__traceback__", None) is not None:
+        return
+
+    depth = 0
+    frames = []
+    while True:
+        try:
+            frame = sys._getframe(depth)
+            depth += 1
+        except ValueError:
+            break
+
+        frames.append(frame)
+
+    frames.reverse()
+
+    tb = None
+    for frame in frames:
+        tb = types.TracebackType(tb, frame, frame.f_lasti, frame.f_lineno)
+
+    setattr(e, "__traceback__", tb)
 
 
 def _module_in_list(name, items):

posthog/integrations/django.py

@@ -0,0 +1,160 @@
+from typing import TYPE_CHECKING, cast
+from posthog import contexts
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse  # noqa: F401
+    from typing import Callable, Dict, Any, Optional  # noqa: F401
+
+
+class PosthogContextMiddleware:
+    """Middleware to automatically track Django requests.
+
+    This middleware wraps all calls with a posthog context. It attempts to extract the following from the request headers:
+    - Session ID, (extracted from `X-POSTHOG-SESSION-ID`)
+    - Distinct ID, (extracted from `X-POSTHOG-DISTINCT-ID`)
+    - Request URL as $current_url
+    - Request Method as $request_method
+
+    The context will also auto-capture exceptions and send them to PostHog, unless you disable it by setting
+    `POSTHOG_MW_CAPTURE_EXCEPTIONS` to `False` in your Django settings.
+
+    The middleware behaviour is customisable through 3 additional functions:
+    - `POSTHOG_MW_EXTRA_TAGS`, which is a Callable[[HttpRequest], Dict[str, Any]] expected to return a dictionary of additional tags to be added to the context.
+    - `POSTHOG_MW_REQUEST_FILTER`, which is a Callable[[HttpRequest], bool] expected to return `False` if the request should not be tracked.
+    - `POSTHOG_MW_TAG_MAP`, which is a Callable[[Dict[str, Any]], Dict[str, Any]], which you can use to modify the tags before they're added to the context.
+
+    You can use the `POSTHOG_MW_TAG_MAP` function to remove any default tags you don't want to capture, or override them with your own values.
+
+    Context tags are automatically included as properties on all events captured within a context, including exceptions.
+    See the context documentation for more information. The extracted distinct ID and session ID, if found, are used to
+    associate all events captured in the middleware context with the same distinct ID and session as currently active on the
+    frontend. See the documentation for `set_context_session` and `identify_context` for more details.
+    """
+
+    def __init__(self, get_response):
+        # type: (Callable[[HttpRequest], HttpResponse]) -> None
+        self.get_response = get_response
+
+        from django.conf import settings
+
+        if hasattr(settings, "POSTHOG_MW_EXTRA_TAGS") and callable(
+            settings.POSTHOG_MW_EXTRA_TAGS
+        ):
+            self.extra_tags = cast(
+                "Optional[Callable[[HttpRequest], Dict[str, Any]]]",
+                settings.POSTHOG_MW_EXTRA_TAGS,
+            )
+        else:
+            self.extra_tags = None
+
+        if hasattr(settings, "POSTHOG_MW_REQUEST_FILTER") and callable(
+            settings.POSTHOG_MW_REQUEST_FILTER
+        ):
+            self.request_filter = cast(
+                "Optional[Callable[[HttpRequest], bool]]",
+                settings.POSTHOG_MW_REQUEST_FILTER,
+            )
+        else:
+            self.request_filter = None
+
+        if hasattr(settings, "POSTHOG_MW_TAG_MAP") and callable(
+            settings.POSTHOG_MW_TAG_MAP
+        ):
+            self.tag_map = cast(
+                "Optional[Callable[[Dict[str, Any]], Dict[str, Any]]]",
+                settings.POSTHOG_MW_TAG_MAP,
+            )
+        else:
+            self.tag_map = None
+
+        if hasattr(settings, "POSTHOG_MW_CAPTURE_EXCEPTIONS") and isinstance(
+            settings.POSTHOG_MW_CAPTURE_EXCEPTIONS, bool
+        ):
+            self.capture_exceptions = settings.POSTHOG_MW_CAPTURE_EXCEPTIONS
+        else:
+            self.capture_exceptions = True
+
+    def extract_tags(self, request):
+        # type: (HttpRequest) -> Dict[str, Any]
+        tags = {}
+
+        (user_id, user_email) = self.extract_request_user(request)
+
+        # Extract session ID from X-POSTHOG-SESSION-ID header
+        session_id = request.headers.get("X-POSTHOG-SESSION-ID")
+        if session_id:
+            contexts.set_context_session(session_id)
+
+        # Extract distinct ID from X-POSTHOG-DISTINCT-ID header or request user id
+        distinct_id = request.headers.get("X-POSTHOG-DISTINCT-ID") or user_id
+        if distinct_id:
+            contexts.identify_context(distinct_id)
+
+        # Extract user email
+        if user_email:
+            tags["email"] = user_email
+
+        # Extract current URL
+        absolute_url = request.build_absolute_uri()
+        if absolute_url:
+            tags["$current_url"] = absolute_url
+
+        # Extract request method
+        if request.method:
+            tags["$request_method"] = request.method
+
+        # Extract request path
+        if request.path:
+            tags["$request_path"] = request.path
+
+        # Extract IP address
+        ip_address = request.headers.get("X-Forwarded-For")
+        if ip_address:
+            tags["$ip_address"] = ip_address
+
+        # Extract user agent
+        user_agent = request.headers.get("User-Agent")
+        if user_agent:
+            tags["$user_agent"] = user_agent
+
+        # Apply extra tags if configured
+        if self.extra_tags:
+            extra = self.extra_tags(request)
+            if extra:
+                tags.update(extra)
+
+        # Apply tag mapping if configured
+        if self.tag_map:
+            tags = self.tag_map(tags)
+
+        return tags
+
+    def extract_request_user(self, request):
+        user_id = None
+        email = None
+
+        user = getattr(request, "user", None)
+
+        if user and getattr(user, "is_authenticated", False):
+            try:
+                user_id = str(user.pk)
+            except Exception:
+                pass
+
+            try:
+                email = str(user.email)
+            except Exception:
+                pass
+
+        return user_id, email
+
+    def __call__(self, request):
+        # type: (HttpRequest) -> HttpResponse
+        if self.request_filter and not self.request_filter(request):
+            return self.get_response(request)
+
+        with contexts.new_context(self.capture_exceptions):
+            for k, v in self.extract_tags(request).items():
+                contexts.tag(k, v)
+
+            return self.get_response(request)

posthog/scopes.py

@@ -1,122 +0,0 @@
-import contextvars
-from contextlib import contextmanager
-from typing import Any, Callable, Dict, TypeVar, cast
-
-_context_stack: contextvars.ContextVar[list] = contextvars.ContextVar(
-    "posthog_context_stack", default=[{}]
-)
-
-
-def _get_current_context() -> Dict[str, Any]:
-    return _context_stack.get()[-1]
-
-
-@contextmanager
-def new_context(fresh=False):
-    """
-     Create a new context scope that will be active for the duration of the with block.
-     Any tags set within this scope will be isolated to this context. Any exceptions raised
-    or events captured within the context will be tagged with the context tags.
-
-     Args:
-         fresh: Whether to start with a fresh context (default: False).
-                If False, inherits tags from parent context.
-                If True, starts with no tags.
-
-     Examples:
-         # Inherit parent context tags
-         with posthog.new_context():
-             posthog.tag("request_id", "123")
-             # Both this event and the exception will be tagged with the context tags
-             posthog.capture("event_name", {"property": "value"})
-             raise ValueError("Something went wrong")
-
-         # Start with fresh context (no inherited tags)
-         with posthog.new_context(fresh=True):
-             posthog.tag("request_id", "123")
-             # Both this event and the exception will be tagged with the context tags
-             posthog.capture("event_name", {"property": "value"})
-             raise ValueError("Something went wrong")
-
-    """
-    from posthog import capture_exception
-
-    current_tags = _get_current_context().copy()
-    current_stack = _context_stack.get()
-    new_stack = current_stack + [{}] if fresh else current_stack + [current_tags]
-    token = _context_stack.set(new_stack)
-
-    try:
-        yield
-    except Exception as e:
-        capture_exception(e)
-        raise
-    finally:
-        _context_stack.reset(token)
-
-
-def tag(key: str, value: Any) -> None:
-    """
-    Add a tag to the current context.
-
-    Args:
-        key: The tag key
-        value: The tag value
-
-    Example:
-        posthog.tag("user_id", "123")
-    """
-    _get_current_context()[key] = value
-
-
-def get_tags() -> Dict[str, Any]:
-    """
-    Get all tags from the current context. Note, modifying
-    the returned dictionary will not affect the current context.
-
-    Returns:
-        Dict of all tags in the current context
-    """
-    return _get_current_context().copy()
-
-
-def clear_tags() -> None:
-    """Clear all tags in the current context."""
-    _get_current_context().clear()
-
-
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-def scoped(fresh=False):
-    """
-    Decorator that creates a new context for the function. Simply wraps
-    the function in a with posthog.new_context(): block.
-
-    Args:
-        fresh: Whether to start with a fresh context (default: False)
-
-    Example:
-        @posthog.scoped()
-        def process_payment(payment_id):
-            posthog.tag("payment_id", payment_id)
-            posthog.tag("payment_method", "credit_card")
-
-            # This event will be captured with tags
-            posthog.capture("payment_started")
-            # If this raises an exception, it will be captured with tags
-            # and then re-raised
-            some_risky_function()
-    """
-
-    def decorator(func: F) -> F:
-        from functools import wraps
-
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            with new_context(fresh=fresh):
-                return func(*args, **kwargs)
-
-        return cast(F, wrapper)
-
-    return decorator

posthog/sentry/__init__.py

@@ -1 +0,0 @@
-POSTHOG_ID_TAG = "posthog_distinct_id"

posthog/sentry/django.py

@@ -1,28 +0,0 @@
-from django.conf import settings
-from sentry_sdk import configure_scope
-
-from posthog.sentry import POSTHOG_ID_TAG
-
-GET_DISTINCT_ID = getattr(settings, "POSTHOG_DJANGO", {}).get("distinct_id")
-
-
-def get_distinct_id(request):
-    if not GET_DISTINCT_ID:
-        return None
-    try:
-        return GET_DISTINCT_ID(request)
-    except:  # noqa: E722
-        return None
-
-
-class PosthogDistinctIdMiddleware:
-    def __init__(self, get_response):
-        self.get_response = get_response
-
-    def __call__(self, request):
-        with configure_scope() as scope:
-            distinct_id = get_distinct_id(request)
-            if distinct_id:
-                scope.set_tag(POSTHOG_ID_TAG, distinct_id)
-            response = self.get_response(request)
-        return response

posthog/sentry/posthog_integration.py

@@ -1,57 +0,0 @@
-from sentry_sdk._types import MYPY
-from sentry_sdk.hub import Hub
-from sentry_sdk.integrations import Integration
-from sentry_sdk.scope import add_global_event_processor
-from sentry_sdk.utils import Dsn
-
-from posthog import capture, host
-from posthog.request import DEFAULT_HOST
-from posthog.sentry import POSTHOG_ID_TAG
-
-if MYPY:
-    from typing import Optional  # noqa: F401
-
-    from sentry_sdk._types import Event, Hint  # noqa: F401
-
-
-class PostHogIntegration(Integration):
-    identifier = "posthog-python"
-    organization = None  # The Sentry organization, used to send a direct link from PostHog to Sentry
-    project_id = (
-        None  # The Sentry project id, used to send a direct link from PostHog to Sentry
-    )
-    prefix = "https://sentry.io/organizations/"  # URL of a hosted sentry instance (default: https://sentry.io/organizations/)
-
-    @staticmethod
-    def setup_once():
-        @add_global_event_processor
-        def processor(event, hint):
-            # type: (Event, Optional[Hint]) -> Optional[Event]
-            if Hub.current.get_integration(PostHogIntegration) is not None:
-                if event.get("level") != "error":
-                    return event
-
-                if event.get("tags", {}).get(POSTHOG_ID_TAG):
-                    posthog_distinct_id = event["tags"][POSTHOG_ID_TAG]
-                    event["tags"]["PostHog URL"] = (
-                        f"{host or DEFAULT_HOST}/person/{posthog_distinct_id}"
-                    )
-
-                    properties = {
-                        "$sentry_event_id": event["event_id"],
-                        "$sentry_exception": event["exception"],
-                    }
-
-                    if PostHogIntegration.organization:
-                        project_id = PostHogIntegration.project_id or (
-                            not not Hub.current.client.dsn
-                            and Dsn(Hub.current.client.dsn).project_id
-                        )
-                        if project_id:
-                            properties["$sentry_url"] = (
-                                f"{PostHogIntegration.prefix}{PostHogIntegration.organization}/issues/?project={project_id}&query={event['event_id']}"
-                            )
-
-                    capture(posthog_distinct_id, "$exception", properties)
-
-            return event

posthog/test/ai/langchain/test_callbacks.py

@@ -1378,11 +1378,11 @@ def test_langgraph_agent(mock_client):
     )
     graph.invoke(inputs, config={"callbacks": [cb]})
     calls = [call[1] for call in mock_client.capture.call_args_list]
-    assert len(calls) == 21
+    assert len(calls) == 15
     for call in calls:
         assert call["properties"]["$ai_trace_id"] == "test-trace-id"
     assert len([call for call in calls if call["event"] == "$ai_generation"]) == 2
-    assert len([call for call in calls if call["event"] == "$ai_span"]) == 18
+    assert len([call for call in calls if call["event"] == "$ai_span"]) == 12
     assert len([call for call in calls if call["event"] == "$ai_trace"]) == 1
 
 
@@ -1435,11 +1435,13 @@ def test_span_set_parent_ids_for_third_level_run(mock_client, trace_id):
 
     assert mock_client.capture.call_count == 3
 
-    span2, span1, trace = [
-        call[1]["properties"] for call in mock_client.capture.call_args_list
-    ]
-    assert span2["$ai_parent_id"] == span1["$ai_span_id"]
-    assert span1["$ai_parent_id"] == trace["$ai_trace_id"]
+    calls = mock_client.capture.call_args_list
+    span_props_2 = calls[0][1]["properties"]
+    span_props_1 = calls[1][1]["properties"]
+    trace_props = calls[2][1]["properties"]
+
+    assert span_props_2["$ai_parent_id"] == span_props_1["$ai_span_id"]
+    assert span_props_1["$ai_parent_id"] == trace_props["$ai_trace_id"]
 
 
 def test_captures_error_with_details_in_span(mock_client):
@@ -1478,3 +1480,250 @@ def test_captures_error_without_details_in_span(mock_client):
         == "ValueError"
     )
     assert mock_client.capture.call_args_list[1][1]["properties"]["$ai_is_error"]
+
+
+def test_openai_reasoning_tokens(mock_client):
+    """Test that OpenAI reasoning tokens are captured correctly."""
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Think step by step about this problem")]
+    )
+
+    # Mock response with reasoning tokens in output_token_details
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Let me think through this step by step...",
+                usage_metadata={
+                    "input_tokens": 10,
+                    "output_tokens": 25,
+                    "total_tokens": 35,
+                    "output_token_details": {"reasoning": 15},  # 15 reasoning tokens
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Let me think through this step by step..."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 10
+    assert generation_props["$ai_output_tokens"] == 25
+    assert generation_props["$ai_reasoning_tokens"] == 15
+
+
+def test_anthropic_cache_write_and_read_tokens(mock_client):
+    """Test that Anthropic cache creation and read tokens are captured correctly."""
+    prompt = ChatPromptTemplate.from_messages([("user", "Analyze this large document")])
+
+    # First call with cache creation
+    model_write = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="I've analyzed the document and cached the context.",
+                usage_metadata={
+                    "total_tokens": 1050,
+                    "input_tokens": 1000,
+                    "output_tokens": 50,
+                    "cache_creation_input_tokens": 800,  # Anthropic cache write
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model_write
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "I've analyzed the document and cached the context."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 1000
+    assert generation_props["$ai_output_tokens"] == 50
+    assert generation_props["$ai_cache_creation_input_tokens"] == 800
+    assert generation_props["$ai_cache_read_input_tokens"] == 0
+    assert generation_props["$ai_reasoning_tokens"] == 0
+
+    # Reset mock for second call
+    mock_client.reset_mock()
+
+    # Second call with cache read
+    model_read = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Using cached analysis to provide quick response.",
+                usage_metadata={
+                    "input_tokens": 200,
+                    "output_tokens": 30,
+                    "total_tokens": 1030,
+                    "cache_read_input_tokens": 800,  # Anthropic cache read
+                },
+            )
+        ]
+    )
+
+    chain = prompt | model_read
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Using cached analysis to provide quick response."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 200
+    assert generation_props["$ai_output_tokens"] == 30
+    assert generation_props["$ai_cache_creation_input_tokens"] == 0
+    assert generation_props["$ai_cache_read_input_tokens"] == 800
+    assert generation_props["$ai_reasoning_tokens"] == 0
+
+
+def test_openai_cache_read_tokens(mock_client):
+    """Test that OpenAI cache read tokens are captured correctly."""
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Use the cached prompt for this request")]
+    )
+
+    # Mock response with cache read tokens in input_token_details
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Response using cached prompt context.",
+                usage_metadata={
+                    "input_tokens": 150,
+                    "output_tokens": 40,
+                    "total_tokens": 190,
+                    "input_token_details": {
+                        "cache_read": 100,  # 100 tokens read from cache
+                        "cache_creation": 0,
+                    },
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Response using cached prompt context."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 150
+    assert generation_props["$ai_output_tokens"] == 40
+    assert generation_props["$ai_cache_read_input_tokens"] == 100
+    assert generation_props["$ai_cache_creation_input_tokens"] == 0
+    assert generation_props["$ai_reasoning_tokens"] == 0
+
+
+def test_openai_cache_creation_tokens(mock_client):
+    """Test that OpenAI cache creation tokens are captured correctly."""
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Create a cache for this large prompt context")]
+    )
+
+    # Mock response with cache creation tokens in input_token_details
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Created cache for the prompt context.",
+                usage_metadata={
+                    "input_tokens": 2000,
+                    "output_tokens": 25,
+                    "total_tokens": 2025,
+                    "input_token_details": {
+                        "cache_creation": 1500,  # 1500 tokens written to cache
+                        "cache_read": 0,
+                    },
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Created cache for the prompt context."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 2000
+    assert generation_props["$ai_output_tokens"] == 25
+    assert generation_props["$ai_cache_creation_input_tokens"] == 1500
+    assert generation_props["$ai_cache_read_input_tokens"] == 0
+    assert generation_props["$ai_reasoning_tokens"] == 0
+
+
+def test_combined_reasoning_and_cache_tokens(mock_client):
+    """Test that both reasoning tokens and cache tokens can be captured together."""
+    prompt = ChatPromptTemplate.from_messages(
+        [("user", "Think through this cached problem")]
+    )
+
+    # Mock response with both reasoning and cache tokens
+    model = FakeMessagesListChatModel(
+        responses=[
+            AIMessage(
+                content="Let me reason through this using cached context...",
+                usage_metadata={
+                    "input_tokens": 500,
+                    "output_tokens": 100,
+                    "total_tokens": 600,
+                    "input_token_details": {"cache_read": 300, "cache_creation": 0},
+                    "output_token_details": {"reasoning": 60},  # 60 reasoning tokens
+                },
+            )
+        ]
+    )
+
+    callbacks = [CallbackHandler(mock_client)]
+    chain = prompt | model
+    result = chain.invoke({}, config={"callbacks": callbacks})
+
+    assert result.content == "Let me reason through this using cached context..."
+    assert mock_client.capture.call_count == 3
+
+    generation_args = mock_client.capture.call_args_list[1][1]
+    generation_props = generation_args["properties"]
+
+    assert generation_args["event"] == "$ai_generation"
+    assert generation_props["$ai_input_tokens"] == 500
+    assert generation_props["$ai_output_tokens"] == 100
+    assert generation_props["$ai_cache_read_input_tokens"] == 300
+    assert generation_props["$ai_cache_creation_input_tokens"] == 0
+    assert generation_props["$ai_reasoning_tokens"] == 60
+
+
+@pytest.mark.skipif(not OPENAI_API_KEY, reason="OPENAI_API_KEY is not set")
+def test_openai_reasoning_tokens(mock_client):
+    model = ChatOpenAI(
+        api_key=OPENAI_API_KEY, model="o4-mini", max_completion_tokens=10
+    )
+    cb = CallbackHandler(
+        mock_client, trace_id="test-trace-id", distinct_id="test-distinct-id"
+    )
+    model.invoke("what is the weather in sf", config={"callbacks": [cb]})
+    call = mock_client.capture.call_args_list[0][1]
+    assert call["properties"]["$ai_reasoning_tokens"] is not None
+    assert call["properties"]["$ai_input_tokens"] is not None
+    assert call["properties"]["$ai_output_tokens"] is not None

posthog/test/ai/openai/test_openai.py

@@ -26,6 +26,11 @@ try:
         ResponseOutputMessage,
         ResponseOutputText,
         ResponseUsage,
+        ParsedResponse,
+    )
+    from openai.types.responses.parsed_response import (
+        ParsedResponseOutputMessage,
+        ParsedResponseOutputText,
     )
 
     from posthog.ai.openai import OpenAI
@@ -115,6 +120,59 @@ def mock_openai_response_with_responses_api():
     )
 
 
+@pytest.fixture
+def mock_parsed_response():
+    return ParsedResponse(
+        id="test",
+        model="gpt-4o-2024-08-06",
+        object="response",
+        created_at=1741476542,
+        status="completed",
+        error=None,
+        incomplete_details=None,
+        instructions=None,
+        max_output_tokens=None,
+        tools=[],
+        tool_choice="auto",
+        output=[
+            ParsedResponseOutputMessage(
+                id="msg_123",
+                type="message",
+                role="assistant",
+                status="completed",
+                content=[
+                    ParsedResponseOutputText(
+                        type="output_text",
+                        text='{"name": "Science Fair", "date": "Friday", "participants": ["Alice", "Bob"]}',
+                        annotations=[],
+                        parsed={
+                            "name": "Science Fair",
+                            "date": "Friday",
+                            "participants": ["Alice", "Bob"],
+                        },
+                    )
+                ],
+            )
+        ],
+        output_parsed={
+            "name": "Science Fair",
+            "date": "Friday",
+            "participants": ["Alice", "Bob"],
+        },
+        parallel_tool_calls=True,
+        previous_response_id=None,
+        usage=ResponseUsage(
+            input_tokens=15,
+            output_tokens=20,
+            input_tokens_details={"prompt_tokens": 15, "cached_tokens": 0},
+            output_tokens_details={"reasoning_tokens": 5},
+            total_tokens=35,
+        ),
+        user=None,
+        metadata={},
+    )
+
+
 @pytest.fixture
 def mock_embedding_response():
     return CreateEmbeddingResponse(
@@ -646,3 +704,73 @@ def test_responses_api(mock_client, mock_openai_response_with_responses_api):
         assert props["$ai_http_status"] == 200
         assert props["foo"] == "bar"
         assert isinstance(props["$ai_latency"], float)
+
+
+def test_responses_parse(mock_client, mock_parsed_response):
+    with patch(
+        "openai.resources.responses.Responses.parse",
+        return_value=mock_parsed_response,
+    ):
+        client = OpenAI(api_key="test-key", posthog_client=mock_client)
+        response = client.responses.parse(
+            model="gpt-4o-2024-08-06",
+            input=[
+                {"role": "system", "content": "Extract the event information."},
+                {
+                    "role": "user",
+                    "content": "Alice and Bob are going to a science fair on Friday.",
+                },
+            ],
+            text={
+                "format": {
+                    "type": "json_schema",
+                    "json_schema": {
+                        "name": "event",
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "name": {"type": "string"},
+                                "date": {"type": "string"},
+                                "participants": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                },
+                            },
+                            "required": ["name", "date", "participants"],
+                        },
+                    },
+                }
+            },
+            posthog_distinct_id="test-id",
+            posthog_properties={"foo": "bar"},
+        )
+
+        assert response == mock_parsed_response
+        assert mock_client.capture.call_count == 1
+
+        call_args = mock_client.capture.call_args[1]
+        props = call_args["properties"]
+
+        assert call_args["distinct_id"] == "test-id"
+        assert call_args["event"] == "$ai_generation"
+        assert props["$ai_provider"] == "openai"
+        assert props["$ai_model"] == "gpt-4o-2024-08-06"
+        assert props["$ai_input"] == [
+            {"role": "system", "content": "Extract the event information."},
+            {
+                "role": "user",
+                "content": "Alice and Bob are going to a science fair on Friday.",
+            },
+        ]
+        assert props["$ai_output_choices"] == [
+            {
+                "role": "assistant",
+                "content": '{"name": "Science Fair", "date": "Friday", "participants": ["Alice", "Bob"]}',
+            }
+        ]
+        assert props["$ai_input_tokens"] == 15
+        assert props["$ai_output_tokens"] == 20
+        assert props["$ai_reasoning_tokens"] == 5
+        assert props["$ai_http_status"] == 200
+        assert props["foo"] == "bar"
+        assert isinstance(props["$ai_latency"], float)

posthog/test/exception_integrations/__init__.py

@@ -1,3 +0,0 @@
-import pytest
-
-pytest.importorskip("django")

posthog/test/exception_integrations/test_django.py

@@ -1,121 +0,0 @@
-from posthog.exception_integrations.django import DjangoRequestExtractor
-from django.test import RequestFactory
-from django.conf import settings
-from django.core.management import call_command
-import django
-
-DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
-
-# setup a test app
-if not settings.configured:
-    settings.configure(
-        SECRET_KEY="test",
-        DEFAULT_CHARSET="utf-8",
-        INSTALLED_APPS=[
-            "django.contrib.auth",
-            "django.contrib.contenttypes",
-        ],
-        DATABASES={
-            "default": {
-                "ENGINE": "django.db.backends.sqlite3",
-                "NAME": ":memory:",
-            }
-        },
-    )
-    django.setup()
-
-    call_command("migrate", verbosity=0, interactive=False)
-
-
-def mock_request_factory(override_headers):
-    factory = RequestFactory(
-        headers={
-            "User-Agent": DEFAULT_USER_AGENT,
-            "Referrer": "http://example.com",
-            "X-Forwarded-For": "193.4.5.12",
-            **(override_headers or {}),
-        }
-    )
-
-    request = factory.get("/api/endpoint")
-    return request
-
-
-def test_request_extractor_with_no_trace():
-    request = mock_request_factory(None)
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": None,
-        "distinct_id": None,
-        "$request_path": "/api/endpoint",
-    }
-
-
-def test_request_extractor_with_trace():
-    request = mock_request_factory(
-        {"traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"}
-    )
-
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
-        "distinct_id": None,
-        "$request_path": "/api/endpoint",
-    }
-
-
-def test_request_extractor_with_tracestate():
-    request = mock_request_factory(
-        {
-            "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
-            "tracestate": "posthog-distinct-id=1234",
-        }
-    )
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
-        "distinct_id": "1234",
-        "$request_path": "/api/endpoint",
-    }
-
-
-def test_request_extractor_with_complicated_tracestate():
-    request = mock_request_factory(
-        {"tracestate": "posthog-distinct-id=alohaMountainsXUYZ,rojo=00f067aa0ba902b7"}
-    )
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": None,
-        "distinct_id": "alohaMountainsXUYZ",
-        "$request_path": "/api/endpoint",
-    }
-
-
-def test_request_extractor_with_request_user():
-    from django.contrib.auth.models import User
-
-    user = User.objects.create_user(
-        username="test", email="test@posthog.com", password="top_secret"
-    )
-
-    request = mock_request_factory(None)
-    request.user = user
-
-    extractor = DjangoRequestExtractor(request)
-    assert extractor.extract_person_data() == {
-        "ip": "193.4.5.12",
-        "user_agent": DEFAULT_USER_AGENT,
-        "traceparent": None,
-        "distinct_id": None,
-        "$request_path": "/api/endpoint",
-        "email": "test@posthog.com",
-        "$user_id": "1",
-    }

posthog/test/integrations/test_middleware.py

@@ -0,0 +1,173 @@
+from posthog.contexts import (
+    new_context,
+    get_context_session_id,
+    get_context_distinct_id,
+)
+import unittest
+from unittest.mock import Mock
+
+from posthog.integrations.django import PosthogContextMiddleware
+
+
+class MockRequest:
+    """Mock Django HttpRequest object"""
+
+    def __init__(
+        self,
+        headers=None,
+        method="GET",
+        path="/test",
+        host="example.com",
+        is_secure=False,
+    ):
+        self.headers = headers or {}
+        self.method = method
+        self.path = path
+        self._host = host
+        self._is_secure = is_secure
+
+    def build_absolute_uri(self):
+        scheme = "https" if self._is_secure else "http"
+        return f"{scheme}://{self._host}{self.path}"
+
+
+class TestPosthogContextMiddleware(unittest.TestCase):
+    def create_middleware(
+        self,
+        extra_tags=None,
+        request_filter=None,
+        tag_map=None,
+        capture_exceptions=True,
+    ):
+        """Helper to create middleware instance without calling __init__"""
+        middleware = PosthogContextMiddleware.__new__(PosthogContextMiddleware)
+        middleware.get_response = Mock()
+        middleware.extra_tags = extra_tags
+        middleware.request_filter = request_filter
+        middleware.tag_map = tag_map
+        middleware.capture_exceptions = capture_exceptions
+        return middleware
+
+    def test_extract_tags_basic(self):
+        with new_context():
+            """Test basic tag extraction from request"""
+            middleware = self.create_middleware()
+            request = MockRequest(
+                headers={
+                    "X-POSTHOG-SESSION-ID": "session-123",
+                    "X-POSTHOG-DISTINCT-ID": "user-456",
+                },
+                method="POST",
+                path="/api/test",
+                host="example.com",
+                is_secure=True,
+            )
+
+            tags = middleware.extract_tags(request)
+
+            self.assertEqual(get_context_session_id(), "session-123")
+            self.assertEqual(get_context_distinct_id(), "user-456")
+            self.assertEqual(tags["$current_url"], "https://example.com/api/test")
+            self.assertEqual(tags["$request_method"], "POST")
+
+    def test_extract_tags_missing_headers(self):
+        """Test tag extraction when PostHog headers are missing"""
+
+        with new_context():
+            middleware = self.create_middleware()
+            request = MockRequest(headers={}, method="GET", path="/home")
+
+            tags = middleware.extract_tags(request)
+
+            self.assertIsNone(get_context_session_id())
+            self.assertIsNone(get_context_distinct_id())
+            self.assertEqual(tags["$current_url"], "http://example.com/home")
+            self.assertEqual(tags["$request_method"], "GET")
+
+    def test_extract_tags_partial_headers(self):
+        """Test tag extraction with only some PostHog headers present"""
+
+        with new_context():
+            middleware = self.create_middleware()
+            request = MockRequest(
+                headers={"X-POSTHOG-SESSION-ID": "session-only"}, method="PUT"
+            )
+
+            tags = middleware.extract_tags(request)
+
+            self.assertEqual(get_context_session_id(), "session-only")
+            self.assertIsNone(get_context_distinct_id())
+            self.assertEqual(tags["$request_method"], "PUT")
+
+    def test_extract_tags_with_extra_tags(self):
+        """Test tag extraction with extra_tags function"""
+
+        def extra_tags_func(request):
+            return {"custom_tag": "custom_value", "user_id": "789"}
+
+        with new_context():
+            middleware = self.create_middleware(extra_tags=extra_tags_func)
+            request = MockRequest(
+                headers={"X-POSTHOG-SESSION-ID": "session-123"}, method="GET"
+            )
+
+            tags = middleware.extract_tags(request)
+
+            self.assertEqual(get_context_session_id(), "session-123")
+            self.assertEqual(tags["custom_tag"], "custom_value")
+            self.assertEqual(tags["user_id"], "789")
+
+    def test_extract_tags_with_tag_map(self):
+        """Test tag extraction with tag_map function"""
+
+        def extra_tags_func(request):
+            return {"custom_tag": "custom_value", "user_id": "789"}
+
+        def tag_map_func(tags):
+            if "custom_tag" in tags:
+                tags["mapped_custom_tag"] = f"mapped_{tags['custom_tag']}"
+                del tags["custom_tag"]
+            return tags
+
+        with new_context():
+            middleware = self.create_middleware(
+                tag_map=tag_map_func, extra_tags=extra_tags_func
+            )
+            request = MockRequest(
+                headers={"X-POSTHOG-SESSION-ID": "session-123"}, method="GET"
+            )
+
+            tags = middleware.extract_tags(request)
+
+            self.assertEqual(tags["mapped_custom_tag"], "mapped_custom_value")
+
+    def test_extract_tags_extra_tags_returns_none(self):
+        """Test tag extraction when extra_tags returns None"""
+
+        def extra_tags_func(request):
+            return None
+
+        middleware = self.create_middleware(extra_tags=extra_tags_func)
+        request = MockRequest(method="GET")
+
+        tags = middleware.extract_tags(request)
+
+        self.assertEqual(tags["$request_method"], "GET")
+        # Should not crash when extra_tags returns None
+
+    def test_extract_tags_extra_tags_returns_empty_dict(self):
+        """Test tag extraction when extra_tags returns empty dict"""
+
+        def extra_tags_func(request):
+            return {}
+
+        middleware = self.create_middleware(extra_tags=extra_tags_func)
+        request = MockRequest(method="PATCH")
+
+        tags = middleware.extract_tags(request)
+
+        self.assertEqual(tags["$request_method"], "PATCH")
+
+
+if __name__ == "__main__":
+    unittest.main()

posthog/test/test_before_send.py

@@ -40,16 +40,30 @@ class TestClient(unittest.TestCase):
             event["properties"]["processed_by_before_send"] = True
             return event
 
-        client = Client(
-            FAKE_TEST_API_KEY, on_error=self.set_fail, before_send=my_before_send
-        )
-        success, msg = client.capture("user1", "test_event", {"original": "value"})
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=my_before_send,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture(
+                "test_event", distinct_id="user1", properties={"original": "value"}
+            )
 
-        self.assertTrue(success)
-        self.assertEqual(msg["properties"]["processed_by_before_send"], True)
-        self.assertEqual(msg["properties"]["original"], "value")
-        self.assertEqual(len(processed_events), 1)
-        self.assertEqual(processed_events[0]["event"], "test_event")
+            self.assertIsNotNone(msg_uuid)
+
+            # Get the enqueued message from the mock
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+
+            self.assertEqual(
+                enqueued_msg["properties"]["processed_by_before_send"], True
+            )
+            self.assertEqual(enqueued_msg["properties"]["original"], "value")
+            self.assertEqual(len(processed_events), 1)
+            self.assertEqual(processed_events[0]["event"], "test_event")
 
     def test_before_send_callback_drops_event(self):
         """Test that before_send callback can drop events by returning None."""
@@ -59,20 +73,27 @@ class TestClient(unittest.TestCase):
                 return None
             return event
 
-        client = Client(
-            FAKE_TEST_API_KEY, on_error=self.set_fail, before_send=drop_test_events
-        )
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=drop_test_events,
+                sync_mode=True,
+            )
 
-        # Event should be dropped
-        success, msg = client.capture("user1", "test_drop_me")
-        self.assertTrue(success)
-        self.assertIsNone(msg)
+            # Event should be dropped
+            msg_uuid = client.capture("test_drop_me", distinct_id="user1")
+            self.assertIsNone(msg_uuid)
 
-        # Event should go through
-        success, msg = client.capture("user1", "keep_me")
-        self.assertTrue(success)
-        self.assertIsNotNone(msg)
-        self.assertEqual(msg["event"], "keep_me")
+            # Event should go through
+            msg_uuid = client.capture("keep_me", distinct_id="user1")
+            self.assertIsNotNone(msg_uuid)
+
+            # Check the enqueued message
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+            self.assertEqual(enqueued_msg["event"], "keep_me")
 
     def test_before_send_callback_handles_exceptions(self):
         """Test that exceptions in before_send don't crash the client."""
@@ -80,18 +101,26 @@ class TestClient(unittest.TestCase):
         def buggy_before_send(event):
             raise ValueError("Oops!")
 
-        client = Client(
-            FAKE_TEST_API_KEY, on_error=self.set_fail, before_send=buggy_before_send
-        )
-        success, msg = client.capture("user1", "robust_event")
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=buggy_before_send,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture("robust_event", distinct_id="user1")
 
-        # Event should still be sent despite the exception
-        self.assertTrue(success)
-        self.assertIsNotNone(msg)
-        self.assertEqual(msg["event"], "robust_event")
+            # Event should still be sent despite the exception
+            self.assertIsNotNone(msg_uuid)
+
+            # Check the enqueued message
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+            self.assertEqual(enqueued_msg["event"], "robust_event")
 
     def test_before_send_callback_works_with_all_event_types(self):
-        """Test that before_send works with capture, identify, set, etc."""
+        """Test that before_send works with capture, set, etc."""
 
         def add_marker(event):
             if "properties" not in event:
@@ -99,38 +128,46 @@ class TestClient(unittest.TestCase):
             event["properties"]["marked"] = True
             return event
 
-        client = Client(
-            FAKE_TEST_API_KEY, on_error=self.set_fail, before_send=add_marker
-        )
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=add_marker,
+                sync_mode=True,
+            )
 
-        # Test capture
-        success, msg = client.capture("user1", "event")
-        self.assertTrue(success)
-        self.assertTrue(msg["properties"]["marked"])
+            # Test capture
+            msg_uuid = client.capture("event", distinct_id="user1")
+            self.assertIsNotNone(msg_uuid)
 
-        # Test identify
-        success, msg = client.identify("user1", {"trait": "value"})
-        self.assertTrue(success)
-        self.assertTrue(msg["properties"]["marked"])
+            # Test set
+            msg_uuid = client.set(distinct_id="user1", properties={"prop": "value"})
+            self.assertIsNotNone(msg_uuid)
 
-        # Test set
-        success, msg = client.set("user1", {"prop": "value"})
-        self.assertTrue(success)
-        self.assertTrue(msg["properties"]["marked"])
-
-        # Test page
-        success, msg = client.page("user1", "https://example.com")
-        self.assertTrue(success)
-        self.assertTrue(msg["properties"]["marked"])
+            # Check all events were marked
+            self.assertEqual(mock_post.call_count, 2)
+            for call in mock_post.call_args_list:
+                batch_data = call[1]["batch"]
+                enqueued_msg = batch_data[0]
+                self.assertTrue(enqueued_msg["properties"]["marked"])
 
     def test_before_send_callback_disabled_when_none(self):
         """Test that client works normally when before_send is None."""
-        client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, before_send=None)
-        success, msg = client.capture("user1", "normal_event")
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=None,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture("normal_event", distinct_id="user1")
+            self.assertIsNotNone(msg_uuid)
 
-        self.assertTrue(success)
-        self.assertIsNotNone(msg)
-        self.assertEqual(msg["event"], "normal_event")
+            # Check the event was sent normally
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+            self.assertEqual(enqueued_msg["event"], "normal_event")
 
     def test_before_send_callback_pii_scrubbing_example(self):
         """Test a realistic PII scrubbing use case."""
@@ -152,20 +189,30 @@ class TestClient(unittest.TestCase):
 
             return event
 
-        client = Client(
-            FAKE_TEST_API_KEY, on_error=self.set_fail, before_send=scrub_pii
-        )
-        success, msg = client.capture(
-            "user1",
-            "form_submit",
-            {
-                "email": "user@example.com",
-                "credit_card": "1234-5678-9012-3456",
-                "form_name": "contact",
-            },
-        )
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                before_send=scrub_pii,
+                sync_mode=True,
+            )
+            msg_uuid = client.capture(
+                "form_submit",
+                distinct_id="user1",
+                properties={
+                    "email": "user@example.com",
+                    "credit_card": "1234-5678-9012-3456",
+                    "form_name": "contact",
+                },
+            )
 
-        self.assertTrue(success)
-        self.assertEqual(msg["properties"]["email"], "***@example.com")
-        self.assertNotIn("credit_card", msg["properties"])
-        self.assertEqual(msg["properties"]["form_name"], "contact")
+            self.assertIsNotNone(msg_uuid)
+
+            # Check the enqueued message was scrubbed
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            enqueued_msg = batch_data[0]
+
+            self.assertEqual(enqueued_msg["properties"]["email"], "***@example.com")
+            self.assertNotIn("credit_card", enqueued_msg["properties"])
+            self.assertEqual(enqueued_msg["properties"]["form_name"], "contact")

posthog/test/test_contexts.py

@@ -0,0 +1,207 @@
+import unittest
+from unittest.mock import patch
+
+from posthog.contexts import (
+    get_tags,
+    new_context,
+    scoped,
+    tag,
+    identify_context,
+    set_context_session,
+    get_context_session_id,
+    get_context_distinct_id,
+)
+
+
+class TestContexts(unittest.TestCase):
+    def test_tag_and_get_tags(self):
+        with new_context(fresh=True):
+            tag("key1", "value1")
+            tag("key2", 2)
+
+            tags = get_tags()
+            assert tags["key1"] == "value1"
+            assert tags["key2"] == 2
+
+    def test_new_context_isolation(self):
+        with new_context(fresh=True):
+            # Set tag in outer context
+            tag("outer", "value")
+
+            with new_context(fresh=True):
+                # Inner context should start empty
+                assert get_tags() == {}
+
+                # Set tag in inner context
+                tag("inner", "value")
+                assert get_tags()["inner"] == "value"
+
+                # Outer tag should not be visible
+                self.assertNotIn("outer", get_tags())
+
+            with new_context(fresh=False):
+                # Inner context should inherit outer tag
+                assert get_tags() == {"outer": "value"}
+
+            # After exiting context, inner tag should be gone
+            self.assertNotIn("inner", get_tags())
+
+            # Outer tag should still be there
+            assert get_tags()["outer"] == "value"
+
+    def test_nested_contexts(self):
+        with new_context(fresh=True):
+            tag("level1", "value1")
+
+            with new_context(fresh=True):
+                tag("level2", "value2")
+
+                with new_context(fresh=True):
+                    tag("level3", "value3")
+                    assert get_tags() == {"level3": "value3"}
+
+                # Back to level 2
+                assert get_tags() == {"level2": "value2"}
+
+            # Back to level 1
+            assert get_tags() == {"level1": "value1"}
+
+    @patch("posthog.capture_exception")
+    def test_scoped_decorator_success(self, mock_capture):
+        @scoped()
+        def successful_function(x, y):
+            tag("x", x)
+            tag("y", y)
+            return x + y
+
+        result = successful_function(1, 2)
+
+        # Function should execute normally
+        assert result == 3
+
+        # No exception should be captured
+        mock_capture.assert_not_called()
+
+        # Context should be cleared after function execution
+        assert get_tags() == {}
+
+    @patch("posthog.capture_exception")
+    def test_scoped_decorator_exception(self, mock_capture):
+        test_exception = ValueError("Test exception")
+
+        def check_context_on_capture(exception, **kwargs):
+            # Assert tags are available when capture_exception is called
+            current_tags = get_tags()
+            assert current_tags.get("important_context") == "value"
+
+        mock_capture.side_effect = check_context_on_capture
+
+        @scoped()
+        def failing_function():
+            tag("important_context", "value")
+            raise test_exception
+
+        # Function should raise the exception
+        with self.assertRaises(ValueError):
+            failing_function()
+
+        # Verify capture_exception was called
+        mock_capture.assert_called_once_with(test_exception)
+
+        # Context should be cleared after function execution
+        assert get_tags() == {}
+
+    @patch("posthog.capture_exception")
+    def test_new_context_exception_handling(self, mock_capture):
+        test_exception = RuntimeError("Context exception")
+
+        def check_context_on_capture(exception, **kwargs):
+            # Assert inner context tags are available when capture_exception is called
+            current_tags = get_tags()
+            assert current_tags.get("inner_context") == "inner_value"
+
+        mock_capture.side_effect = check_context_on_capture
+
+        # Set up outer context
+        with new_context():
+            tag("outer_context", "outer_value")
+
+            try:
+                with new_context():
+                    tag("inner_context", "inner_value")
+                    raise test_exception
+            except RuntimeError:
+                pass  # Expected exception
+
+            # Outer context should still be intact
+            assert get_tags()["outer_context"] == "outer_value"
+
+        # Verify capture_exception was called
+        mock_capture.assert_called_once_with(test_exception)
+
+    def test_identify_context(self):
+        with new_context(fresh=True):
+            # Initially no distinct ID
+            assert get_context_distinct_id() is None
+
+            # Set distinct ID
+            identify_context("user123")
+            assert get_context_distinct_id() == "user123"
+
+    def test_set_context_session(self):
+        with new_context(fresh=True):
+            # Initially no session ID
+            assert get_context_session_id() is None
+
+            # Set session ID
+            set_context_session("session456")
+            assert get_context_session_id() == "session456"
+
+    def test_context_inheritance_fresh_context(self):
+        with new_context(fresh=True):
+            identify_context("user123")
+            set_context_session("session456")
+
+            with new_context(fresh=True):
+                # Fresh context should not inherit
+                assert get_context_distinct_id() is None
+                assert get_context_session_id() is None
+
+            # Original context should still have values
+            assert get_context_distinct_id() == "user123"
+            assert get_context_session_id() == "session456"
+
+    def test_context_inheritance_non_fresh_context(self):
+        with new_context(fresh=True):
+            identify_context("user123")
+            set_context_session("session456")
+
+            with new_context(fresh=False):
+                # Non-fresh context should inherit
+                assert get_context_distinct_id() == "user123"
+                assert get_context_session_id() == "session456"
+
+                # Override in child context
+                identify_context("user789")
+                set_context_session("session999")
+                assert get_context_distinct_id() == "user789"
+                assert get_context_session_id() == "session999"
+
+            # Original context should still have original values
+            assert get_context_distinct_id() == "user123"
+            assert get_context_session_id() == "session456"
+
+    def test_scoped_decorator_with_context_ids(self):
+        @scoped()
+        def function_with_context():
+            identify_context("user456")
+            set_context_session("session789")
+            return get_context_distinct_id(), get_context_session_id()
+
+        distinct_id, session_id = function_with_context()
+        assert distinct_id == "user456"
+        assert session_id == "session789"
+
+        # Context should be cleared after function execution
+        assert get_context_distinct_id() is None
+        assert get_context_session_id() is None

posthog/test/test_exception_capture.py

@@ -32,32 +32,3 @@ def test_excepthook(tmpdir):
         b'"$exception_list": [{"mechanism": {"type": "generic", "handled": true}, "module": null, "type": "ZeroDivisionError", "value": "division by zero", "stacktrace": {"frames": [{"platform": "python", "filename": "app.py", "abs_path"'
         in output
     )
-
-
-def test_trying_to_use_django_integration(tmpdir):
-    app = tmpdir.join("app.py")
-    app.write(
-        dedent(
-            """
-    from posthog import Posthog, Integrations
-    posthog = Posthog('phc_x', host='https://eu.i.posthog.com', enable_exception_autocapture=True, exception_autocapture_integrations=[Integrations.Django], debug=True, on_error=lambda e, batch: print('error handling batch: ', e, batch))
-
-    # frame_value = "LOL"
-
-    1/0
-    """
-        )
-    )
-
-    with pytest.raises(subprocess.CalledProcessError) as excinfo:
-        subprocess.check_output([sys.executable, str(app)], stderr=subprocess.STDOUT)
-
-    output = excinfo.value.output
-
-    assert b"ZeroDivisionError" in output
-    assert b"LOL" in output
-    assert b"DEBUG:posthog:data uploaded successfully" in output
-    assert (
-        b'"$exception_list": [{"mechanism": {"type": "generic", "handled": true}, "module": null, "type": "ZeroDivisionError", "value": "division by zero", "stacktrace": {"frames": [{"platform": "python", "filename": "app.py", "abs_path"'
-        in output
-    )

posthog/test/test_feature_flag_result.py

@@ -229,9 +229,9 @@ class TestGetFeatureFlagResult(unittest.TestCase):
         self.assertEqual(flag_result.variant, None)
         self.assertEqual(flag_result.payload, 300)
         patch_capture.assert_called_with(
-            "some-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id",
+            properties={
                 "$feature_flag": "person-flag",
                 "$feature_flag_response": True,
                 "locally_evaluated": True,
@@ -283,9 +283,9 @@ class TestGetFeatureFlagResult(unittest.TestCase):
         self.assertEqual(flag_result.payload, {"some": "value"})
 
         patch_capture.assert_called_with(
-            "distinct_id",
             "$feature_flag_called",
-            {
+            distinct_id="distinct_id",
+            properties={
                 "$feature_flag": "person-flag",
                 "$feature_flag_response": "variant-1",
                 "locally_evaluated": True,
@@ -305,9 +305,9 @@ class TestGetFeatureFlagResult(unittest.TestCase):
         self.assertIsNone(another_flag_result.payload)
 
         patch_capture.assert_called_with(
-            "another-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="another-distinct-id",
+            properties={
                 "$feature_flag": "person-flag",
                 "$feature_flag_response": "variant-2",
                 "locally_evaluated": True,
@@ -345,9 +345,9 @@ class TestGetFeatureFlagResult(unittest.TestCase):
         self.assertEqual(flag_result.variant, None)
         self.assertEqual(flag_result.payload, 300)
         patch_capture.assert_called_with(
-            "some-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id",
+            properties={
                 "$feature_flag": "person-flag",
                 "$feature_flag_response": True,
                 "locally_evaluated": False,
@@ -388,9 +388,9 @@ class TestGetFeatureFlagResult(unittest.TestCase):
         self.assertEqual(flag_result.get_value(), "variant-1")
         self.assertEqual(flag_result.payload, [1, 2, 3])
         patch_capture.assert_called_with(
-            "distinct_id",
             "$feature_flag_called",
-            {
+            distinct_id="distinct_id",
+            properties={
                 "$feature_flag": "person-flag",
                 "$feature_flag_response": "variant-1",
                 "locally_evaluated": False,
@@ -431,9 +431,9 @@ class TestGetFeatureFlagResult(unittest.TestCase):
 
         self.assertIsNone(flag_result)
         patch_capture.assert_called_with(
-            "some-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id",
+            properties={
                 "$feature_flag": "no-person-flag",
                 "$feature_flag_response": None,
                 "locally_evaluated": False,

posthog/test/test_feature_flags.py

@@ -2695,9 +2695,9 @@ class TestCaptureCalls(unittest.TestCase):
         )
         self.assertEqual(patch_capture.call_count, 1)
         patch_capture.assert_called_with(
-            "some-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id",
+            properties={
                 "$feature_flag": "complex-flag",
                 "$feature_flag_response": True,
                 "locally_evaluated": True,
@@ -2729,9 +2729,9 @@ class TestCaptureCalls(unittest.TestCase):
         )
         self.assertEqual(patch_capture.call_count, 1)
         patch_capture.assert_called_with(
-            "some-distinct-id2",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id2",
+            properties={
                 "$feature_flag": "complex-flag",
                 "$feature_flag_response": True,
                 "locally_evaluated": True,
@@ -2767,9 +2767,9 @@ class TestCaptureCalls(unittest.TestCase):
         self.assertEqual(patch_flags.call_count, 1)
         self.assertEqual(patch_capture.call_count, 1)
         patch_capture.assert_called_with(
-            "some-distinct-id2",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id2",
+            properties={
                 "$feature_flag": "decide-flag",
                 "$feature_flag_response": "decide-value",
                 "locally_evaluated": False,
@@ -2820,9 +2820,9 @@ class TestCaptureCalls(unittest.TestCase):
         )
         self.assertEqual(patch_capture.call_count, 1)
         patch_capture.assert_called_with(
-            "some-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id",
+            properties={
                 "$feature_flag": "decide-flag",
                 "$feature_flag_response": "decide-variant",
                 "locally_evaluated": False,
@@ -2871,9 +2871,9 @@ class TestCaptureCalls(unittest.TestCase):
         )
         self.assertEqual(patch_capture.call_count, 1)
         patch_capture.assert_called_with(
-            "some-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id",
+            properties={
                 "$feature_flag": "decide-flag-with-payload",
                 "$feature_flag_response": True,
                 "locally_evaluated": False,
@@ -2948,7 +2948,9 @@ class TestCaptureCalls(unittest.TestCase):
             "featureFlags": {"person-flag": True},
             "featureFlagPayloads": {"person-flag": 300},
         }
-        client = Client(api_key=FAKE_TEST_API_KEY, personal_api_key=FAKE_TEST_API_KEY)
+        client = Client(
+            project_api_key=FAKE_TEST_API_KEY, personal_api_key=FAKE_TEST_API_KEY
+        )
 
         client.feature_flags = [
             {
@@ -2977,9 +2979,9 @@ class TestCaptureCalls(unittest.TestCase):
         # Assert that capture was called once, with the correct parameters
         self.assertEqual(patch_capture.call_count, 1)
         patch_capture.assert_called_with(
-            "some-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id",
+            properties={
                 "$feature_flag": "person-flag",
                 "$feature_flag_response": True,
                 "locally_evaluated": True,
@@ -3012,9 +3014,9 @@ class TestCaptureCalls(unittest.TestCase):
 
         self.assertEqual(patch_capture.call_count, 1)
         patch_capture.assert_called_with(
-            "some-distinct-id2",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id2",
+            properties={
                 "$feature_flag": "person-flag",
                 "$feature_flag_response": True,
                 "locally_evaluated": True,
@@ -3058,9 +3060,9 @@ class TestCaptureCalls(unittest.TestCase):
         )
 
         patch_capture.assert_called_with(
-            "some-distinct-id",
             "$feature_flag_called",
-            {
+            distinct_id="some-distinct-id",
+            properties={
                 "$feature_flag": "complex-flag",
                 "$feature_flag_response": True,
                 "locally_evaluated": True,
@@ -3102,9 +3104,9 @@ class TestCaptureCalls(unittest.TestCase):
                 person_properties={"region": "USA", "name": "Aloha"},
             )
             patch_capture.assert_called_with(
-                distinct_id,
                 "$feature_flag_called",
-                {
+                distinct_id=distinct_id,
+                properties={
                     "$feature_flag": "complex-flag",
                     "$feature_flag_response": True,
                     "locally_evaluated": True,
@@ -5229,7 +5231,9 @@ class TestConsistency(unittest.TestCase):
             "featureFlags": {}
         }  # Ensure decide returns empty flags
 
-        client = Client(api_key=FAKE_TEST_API_KEY, personal_api_key=FAKE_TEST_API_KEY)
+        client = Client(
+            project_api_key=FAKE_TEST_API_KEY, personal_api_key=FAKE_TEST_API_KEY
+        )
         client.feature_flags = [
             {
                 "id": 1,
@@ -5253,7 +5257,9 @@ class TestConsistency(unittest.TestCase):
             "featureFlagPayloads": {"Beta-Feature": {"some": "value"}},
         }
 
-        client = Client(api_key=FAKE_TEST_API_KEY, personal_api_key=FAKE_TEST_API_KEY)
+        client = Client(
+            project_api_key=FAKE_TEST_API_KEY, personal_api_key=FAKE_TEST_API_KEY
+        )
         client.feature_flags = [
             {
                 "id": 1,
@@ -5282,7 +5288,9 @@ class TestConsistency(unittest.TestCase):
             "featureFlagPayloads": {"Beta-Feature": {"some": "value"}},
         }
 
-        client = Client(api_key=FAKE_TEST_API_KEY, personal_api_key=FAKE_TEST_API_KEY)
+        client = Client(
+            project_api_key=FAKE_TEST_API_KEY, personal_api_key=FAKE_TEST_API_KEY
+        )
         client.feature_flags = [
             {
                 "id": 1,

posthog/test/test_module.py

@@ -7,8 +7,7 @@ class TestModule(unittest.TestCase):
     posthog = None
 
     def _assert_enqueue_result(self, result):
-        self.assertEqual(type(result[0]), bool)
-        self.assertEqual(type(result[1]), dict)
+        self.assertEqual(type(result[0]), str)
 
     def failed(self):
         self.failed = True
@@ -28,12 +27,7 @@ class TestModule(unittest.TestCase):
         self.assertRaises(Exception, self.posthog.capture)
 
     def test_track(self):
-        res = self.posthog.capture("distinct_id", "python module event")
-        self._assert_enqueue_result(res)
-        self.posthog.flush()
-
-    def test_identify(self):
-        res = self.posthog.identify("distinct_id", {"email": "user@email.com"})
+        res = self.posthog.capture("python module event", distinct_id="distinct_id")
         self._assert_enqueue_result(res)
         self.posthog.flush()
 
@@ -42,9 +36,5 @@ class TestModule(unittest.TestCase):
         self._assert_enqueue_result(res)
         self.posthog.flush()
 
-    def test_page(self):
-        self.posthog.page("distinct_id", "https://posthog.com/contact")
-        self.posthog.flush()
-
     def test_flush(self):
         self.posthog.flush()

posthog/test/test_scopes.py

@@ -1,138 +0,0 @@
-import unittest
-from unittest.mock import patch
-
-from posthog.scopes import clear_tags, get_tags, new_context, scoped, tag
-
-
-class TestScopes(unittest.TestCase):
-    def setUp(self):
-        # Reset any context between tests
-        clear_tags()
-
-    def test_tag_and_get_tags(self):
-        tag("key1", "value1")
-        tag("key2", 2)
-
-        tags = get_tags()
-        assert tags["key1"] == "value1"
-        assert tags["key2"] == 2
-
-    def test_clear_tags(self):
-        tag("key1", "value1")
-        assert get_tags()["key1"] == "value1"
-
-        clear_tags()
-        assert get_tags() == {}
-
-    def test_new_context_isolation(self):
-        # Set tag in outer context
-        tag("outer", "value")
-
-        with new_context(fresh=True):
-            # Inner context should start empty
-            assert get_tags() == {}
-
-            # Set tag in inner context
-            tag("inner", "value")
-            assert get_tags()["inner"] == "value"
-
-            # Outer tag should not be visible
-            self.assertNotIn("outer", get_tags())
-
-        with new_context(fresh=False):
-            # Inner context should start empty
-            assert get_tags() == {"outer": "value"}
-
-        # After exiting context, inner tag should be gone
-        self.assertNotIn("inner", get_tags())
-
-        # Outer tag should still be there
-        assert get_tags()["outer"] == "value"
-
-    def test_nested_contexts(self):
-        tag("level1", "value1")
-
-        with new_context(fresh=True):
-            tag("level2", "value2")
-
-            with new_context(fresh=True):
-                tag("level3", "value3")
-                assert get_tags() == {"level3": "value3"}
-
-            # Back to level 2
-            assert get_tags() == {"level2": "value2"}
-
-        # Back to level 1
-        assert get_tags() == {"level1": "value1"}
-
-    @patch("posthog.capture_exception")
-    def test_scoped_decorator_success(self, mock_capture):
-        @scoped()
-        def successful_function(x, y):
-            tag("x", x)
-            tag("y", y)
-            return x + y
-
-        result = successful_function(1, 2)
-
-        # Function should execute normally
-        assert result == 3
-
-        # No exception should be captured
-        mock_capture.assert_not_called()
-
-        # Context should be cleared after function execution
-        assert get_tags() == {}
-
-    @patch("posthog.capture_exception")
-    def test_scoped_decorator_exception(self, mock_capture):
-        test_exception = ValueError("Test exception")
-
-        def check_context_on_capture(exception, **kwargs):
-            # Assert tags are available when capture_exception is called
-            current_tags = get_tags()
-            assert current_tags.get("important_context") == "value"
-
-        mock_capture.side_effect = check_context_on_capture
-
-        @scoped()
-        def failing_function():
-            tag("important_context", "value")
-            raise test_exception
-
-        # Function should raise the exception
-        with self.assertRaises(ValueError):
-            failing_function()
-
-        # Verify capture_exception was called
-        mock_capture.assert_called_once_with(test_exception)
-
-        # Context should be cleared after function execution
-        assert get_tags() == {}
-
-    @patch("posthog.capture_exception")
-    def test_new_context_exception_handling(self, mock_capture):
-        test_exception = RuntimeError("Context exception")
-
-        def check_context_on_capture(exception, **kwargs):
-            # Assert inner context tags are available when capture_exception is called
-            current_tags = get_tags()
-            assert current_tags.get("inner_context") == "inner_value"
-
-        mock_capture.side_effect = check_context_on_capture
-
-        # Set up outer context
-        tag("outer_context", "outer_value")
-
-        try:
-            with new_context():
-                tag("inner_context", "inner_value")
-                raise test_exception
-        except RuntimeError:
-            pass  # Expected exception
-
-        # Verify capture_exception was called
-        mock_capture.assert_called_once_with(test_exception)
-
-        # Outer context should still be intact
-        assert get_tags()["outer_context"] == "outer_value"

posthog/test/test_utils.py

@@ -1,3 +1,4 @@
+import time
 import unittest
 from dataclasses import dataclass
 from datetime import date, datetime, timedelta
@@ -12,6 +13,7 @@ from pydantic import BaseModel
 from pydantic.v1 import BaseModel as BaseModelV1
 
 from posthog import utils
+from posthog.types import FeatureFlagResult
 
 TEST_API_KEY = "kOOlRy2QlMY9jHZQv0bKz0FZyazBUoY8Arj0lFVNjs4"
 FAKE_TEST_API_KEY = "random_key"
@@ -173,3 +175,124 @@ class TestUtils(unittest.TestCase):
                 "inner_optional": None,
             },
         }
+
+
+class TestFlagCache(unittest.TestCase):
+    def setUp(self):
+        self.cache = utils.FlagCache(max_size=3, default_ttl=1)
+        self.flag_result = FeatureFlagResult.from_value_and_payload(
+            "test-flag", True, None
+        )
+
+    def test_cache_basic_operations(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        flag_version = 1
+
+        # Test cache miss
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is None
+
+        # Test cache set and hit
+        self.cache.set_cached_flag(
+            distinct_id, flag_key, self.flag_result, flag_version
+        )
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is not None
+        assert result.get_value()
+
+    def test_cache_ttl_expiration(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        flag_version = 1
+
+        # Set flag in cache
+        self.cache.set_cached_flag(
+            distinct_id, flag_key, self.flag_result, flag_version
+        )
+
+        # Should be available immediately
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is not None
+
+        # Wait for TTL to expire (1 second + buffer)
+        time.sleep(1.1)
+
+        # Should be expired
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is None
+
+    def test_cache_version_invalidation(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        old_version = 1
+        new_version = 2
+
+        # Set flag with old version
+        self.cache.set_cached_flag(distinct_id, flag_key, self.flag_result, old_version)
+
+        # Should hit with old version
+        result = self.cache.get_cached_flag(distinct_id, flag_key, old_version)
+        assert result is not None
+
+        # Should miss with new version
+        result = self.cache.get_cached_flag(distinct_id, flag_key, new_version)
+        assert result is None
+
+        # Invalidate old version
+        self.cache.invalidate_version(old_version)
+
+        # Should miss even with old version after invalidation
+        result = self.cache.get_cached_flag(distinct_id, flag_key, old_version)
+        assert result is None
+
+    def test_stale_cache_functionality(self):
+        distinct_id = "user123"
+        flag_key = "test-flag"
+        flag_version = 1
+
+        # Set flag in cache
+        self.cache.set_cached_flag(
+            distinct_id, flag_key, self.flag_result, flag_version
+        )
+
+        # Wait for TTL to expire
+        time.sleep(1.1)
+
+        # Should not get fresh cache
+        result = self.cache.get_cached_flag(distinct_id, flag_key, flag_version)
+        assert result is None
+
+        # Should get stale cache (within 1 hour default)
+        stale_result = self.cache.get_stale_cached_flag(distinct_id, flag_key)
+        assert stale_result is not None
+        assert stale_result.get_value()
+
+    def test_lru_eviction(self):
+        # Cache has max_size=3, so adding 4 users should evict the LRU one
+        flag_version = 1
+
+        # Add 3 users
+        for i in range(3):
+            user_id = f"user{i}"
+            self.cache.set_cached_flag(
+                user_id, "test-flag", self.flag_result, flag_version
+            )
+
+        # Access user0 to make it recently used
+        self.cache.get_cached_flag("user0", "test-flag", flag_version)
+
+        # Add 4th user, should evict user1 (least recently used)
+        self.cache.set_cached_flag("user3", "test-flag", self.flag_result, flag_version)
+
+        # user0 should still be there (was recently accessed)
+        result = self.cache.get_cached_flag("user0", "test-flag", flag_version)
+        assert result is not None
+
+        # user2 should still be there (was recently added)
+        result = self.cache.get_cached_flag("user2", "test-flag", flag_version)
+        assert result is not None
+
+        # user3 should be there (just added)
+        result = self.cache.get_cached_flag("user3", "test-flag", flag_version)
+        assert result is not None

posthog/utils.py

@@ -1,12 +1,17 @@
+import json
 import logging
 import numbers
 import re
+import time
 from collections import defaultdict
 from dataclasses import asdict, is_dataclass
 from datetime import date, datetime, timezone
 from decimal import Decimal
 from typing import Any, Optional
 from uuid import UUID
+import sys
+import platform
+import distro  # For Linux OS detection
 
 import six
 from dateutil.tz import tzlocal, tzutc
@@ -154,6 +159,266 @@ class SizeLimitedDict(defaultdict):
         super().__setitem__(key, value)
 
 
+class FlagCacheEntry:
+    def __init__(self, flag_result, flag_definition_version, timestamp=None):
+        self.flag_result = flag_result
+        self.flag_definition_version = flag_definition_version
+        self.timestamp = timestamp or time.time()
+
+    def is_valid(self, current_time, ttl, current_flag_version):
+        time_valid = (current_time - self.timestamp) < ttl
+        version_valid = self.flag_definition_version == current_flag_version
+        return time_valid and version_valid
+
+    def is_stale_but_usable(self, current_time, max_stale_age=3600):
+        return (current_time - self.timestamp) < max_stale_age
+
+
+class FlagCache:
+    def __init__(self, max_size=10000, default_ttl=300):
+        self.cache = {}  # distinct_id -> {flag_key: FlagCacheEntry}
+        self.access_times = {}  # distinct_id -> last_access_time
+        self.max_size = max_size
+        self.default_ttl = default_ttl
+
+    def get_cached_flag(self, distinct_id, flag_key, current_flag_version):
+        current_time = time.time()
+
+        if distinct_id not in self.cache:
+            return None
+
+        user_flags = self.cache[distinct_id]
+        if flag_key not in user_flags:
+            return None
+
+        entry = user_flags[flag_key]
+        if entry.is_valid(current_time, self.default_ttl, current_flag_version):
+            self.access_times[distinct_id] = current_time
+            return entry.flag_result
+
+        return None
+
+    def get_stale_cached_flag(self, distinct_id, flag_key, max_stale_age=3600):
+        current_time = time.time()
+
+        if distinct_id not in self.cache:
+            return None
+
+        user_flags = self.cache[distinct_id]
+        if flag_key not in user_flags:
+            return None
+
+        entry = user_flags[flag_key]
+        if entry.is_stale_but_usable(current_time, max_stale_age):
+            return entry.flag_result
+
+        return None
+
+    def set_cached_flag(
+        self, distinct_id, flag_key, flag_result, flag_definition_version
+    ):
+        current_time = time.time()
+
+        # Evict LRU users if we're at capacity
+        if distinct_id not in self.cache and len(self.cache) >= self.max_size:
+            self._evict_lru()
+
+        # Initialize user cache if needed
+        if distinct_id not in self.cache:
+            self.cache[distinct_id] = {}
+
+        # Store the flag result
+        self.cache[distinct_id][flag_key] = FlagCacheEntry(
+            flag_result, flag_definition_version, current_time
+        )
+        self.access_times[distinct_id] = current_time
+
+    def invalidate_version(self, old_version):
+        users_to_remove = []
+
+        for distinct_id, user_flags in self.cache.items():
+            flags_to_remove = []
+            for flag_key, entry in user_flags.items():
+                if entry.flag_definition_version == old_version:
+                    flags_to_remove.append(flag_key)
+
+            # Remove invalidated flags
+            for flag_key in flags_to_remove:
+                del user_flags[flag_key]
+
+            # Remove user entirely if no flags remain
+            if not user_flags:
+                users_to_remove.append(distinct_id)
+
+        # Clean up empty users
+        for distinct_id in users_to_remove:
+            del self.cache[distinct_id]
+            if distinct_id in self.access_times:
+                del self.access_times[distinct_id]
+
+    def _evict_lru(self):
+        if not self.access_times:
+            return
+
+        # Remove 20% of least recently used entries
+        sorted_users = sorted(self.access_times.items(), key=lambda x: x[1])
+        to_remove = max(1, len(sorted_users) // 5)
+
+        for distinct_id, _ in sorted_users[:to_remove]:
+            if distinct_id in self.cache:
+                del self.cache[distinct_id]
+            if distinct_id in self.access_times:
+                del self.access_times[distinct_id]
+
+    def clear(self):
+        self.cache.clear()
+        self.access_times.clear()
+
+
+class RedisFlagCache:
+    def __init__(
+        self, redis_client, default_ttl=300, stale_ttl=3600, key_prefix="posthog:flags:"
+    ):
+        self.redis = redis_client
+        self.default_ttl = default_ttl
+        self.stale_ttl = stale_ttl
+        self.key_prefix = key_prefix
+        self.version_key = f"{key_prefix}version"
+
+    def _get_cache_key(self, distinct_id, flag_key):
+        return f"{self.key_prefix}{distinct_id}:{flag_key}"
+
+    def _serialize_entry(self, flag_result, flag_definition_version, timestamp=None):
+        if timestamp is None:
+            timestamp = time.time()
+
+        # Use clean to make flag_result JSON-serializable for cross-platform compatibility
+        serialized_result = clean(flag_result)
+
+        entry = {
+            "flag_result": serialized_result,
+            "flag_version": flag_definition_version,
+            "timestamp": timestamp,
+        }
+        return json.dumps(entry)
+
+    def _deserialize_entry(self, data):
+        try:
+            entry = json.loads(data)
+            flag_result = entry["flag_result"]
+            return FlagCacheEntry(
+                flag_result=flag_result,
+                flag_definition_version=entry["flag_version"],
+                timestamp=entry["timestamp"],
+            )
+        except (json.JSONDecodeError, KeyError, ValueError):
+            # If deserialization fails, treat as cache miss
+            return None
+
+    def get_cached_flag(self, distinct_id, flag_key, current_flag_version):
+        try:
+            cache_key = self._get_cache_key(distinct_id, flag_key)
+            data = self.redis.get(cache_key)
+
+            if data:
+                entry = self._deserialize_entry(data)
+                if entry and entry.is_valid(
+                    time.time(), self.default_ttl, current_flag_version
+                ):
+                    return entry.flag_result
+
+            return None
+        except Exception:
+            # Redis error - return None to fall back to normal evaluation
+            return None
+
+    def get_stale_cached_flag(self, distinct_id, flag_key, max_stale_age=None):
+        try:
+            if max_stale_age is None:
+                max_stale_age = self.stale_ttl
+
+            cache_key = self._get_cache_key(distinct_id, flag_key)
+            data = self.redis.get(cache_key)
+
+            if data:
+                entry = self._deserialize_entry(data)
+                if entry and entry.is_stale_but_usable(time.time(), max_stale_age):
+                    return entry.flag_result
+
+            return None
+        except Exception:
+            # Redis error - return None
+            return None
+
+    def set_cached_flag(
+        self, distinct_id, flag_key, flag_result, flag_definition_version
+    ):
+        try:
+            cache_key = self._get_cache_key(distinct_id, flag_key)
+            serialized_entry = self._serialize_entry(
+                flag_result, flag_definition_version
+            )
+
+            # Set with TTL for automatic cleanup (use stale_ttl for total lifetime)
+            self.redis.setex(cache_key, self.stale_ttl, serialized_entry)
+
+            # Update the current version
+            self.redis.set(self.version_key, flag_definition_version)
+
+        except Exception:
+            # Redis error - silently fail, don't break flag evaluation
+            pass
+
+    def invalidate_version(self, old_version):
+        try:
+            # For Redis, we use a simple approach: scan for keys with old version
+            # and delete them. This could be expensive with many keys, but it's
+            # necessary for correctness.
+
+            cursor = 0
+            pattern = f"{self.key_prefix}*"
+
+            while True:
+                cursor, keys = self.redis.scan(cursor, match=pattern, count=100)
+
+                for key in keys:
+                    if key.decode() == self.version_key:
+                        continue
+
+                    try:
+                        data = self.redis.get(key)
+                        if data:
+                            entry_dict = json.loads(data)
+                            if entry_dict.get("flag_version") == old_version:
+                                self.redis.delete(key)
+                    except (json.JSONDecodeError, KeyError):
+                        # If we can't parse the entry, delete it to be safe
+                        self.redis.delete(key)
+
+                if cursor == 0:
+                    break
+
+        except Exception:
+            # Redis error - silently fail
+            pass
+
+    def clear(self):
+        try:
+            # Delete all keys matching our pattern
+            cursor = 0
+            pattern = f"{self.key_prefix}*"
+
+            while True:
+                cursor, keys = self.redis.scan(cursor, match=pattern, count=100)
+                if keys:
+                    self.redis.delete(*keys)
+                if cursor == 0:
+                    break
+        except Exception:
+            # Redis error - silently fail
+            pass
+
+
 def convert_to_datetime_aware(date_obj):
     if date_obj.tzinfo is None:
         date_obj = date_obj.replace(tzinfo=timezone.utc)
@@ -198,3 +463,57 @@ def str_iequals(value, comparand):
         False
     """
     return str(value).casefold() == str(comparand).casefold()
+
+
+def get_os_info():
+    """
+    Returns standardized OS name and version information.
+    Similar to how user agent parsing works in JS.
+    """
+    os_name = ""
+    os_version = ""
+
+    platform_name = sys.platform
+
+    if platform_name.startswith("win"):
+        os_name = "Windows"
+        if hasattr(platform, "win32_ver"):
+            win_version = platform.win32_ver()[0]
+            if win_version:
+                os_version = win_version
+
+    elif platform_name == "darwin":
+        os_name = "Mac OS X"
+        if hasattr(platform, "mac_ver"):
+            mac_version = platform.mac_ver()[0]
+            if mac_version:
+                os_version = mac_version
+
+    elif platform_name.startswith("linux"):
+        os_name = "Linux"
+        linux_info = distro.info()
+        if linux_info["version"]:
+            os_version = linux_info["version"]
+
+    elif platform_name.startswith("freebsd"):
+        os_name = "FreeBSD"
+        if hasattr(platform, "release"):
+            os_version = platform.release()
+
+    else:
+        os_name = platform_name
+        if hasattr(platform, "release"):
+            os_version = platform.release()
+
+    return os_name, os_version
+
+
+def system_context() -> dict[str, Any]:
+    os_name, os_version = get_os_info()
+
+    return {
+        "$python_runtime": platform.python_implementation(),
+        "$python_version": "%s.%s.%s" % (sys.version_info[:3]),
+        "$os": os_name,
+        "$os_version": os_version,
+    }

posthog/version.py

@@ -1,4 +1,4 @@
-VERSION = "4.6.2"
+VERSION = "6.0.3"
 
 if __name__ == "__main__":
     print(VERSION, end="")  # noqa: T201

pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Integrate PostHog into any python application."
 authors = [{ name = "PostHog", email = "hey@posthog.com" }]
 maintainers = [{ name = "PostHog", email = "hey@posthog.com" }]
-license = {text = "MIT"}
+license = { text = "MIT" }
 readme = "README.md"
 requires-python = ">=3.9"
 classifiers = [
@@ -29,6 +29,7 @@ dependencies = [
     "python-dateutil>=2.2",
     "backoff>=1.10.0",
     "distro>=1.5.0",
+    "typing-extensions>=4.2.0",
 ]
 
 [project.urls]
@@ -36,7 +37,6 @@ Homepage = "https://github.com/posthog/posthog-python"
 Repository = "https://github.com/posthog/posthog-python"
 
 [project.optional-dependencies]
-sentry = ["sentry-sdk", "django"]
 langchain = ["langchain>=0.2.0"]
 dev = [
     "django-stubs",
@@ -52,7 +52,7 @@ dev = [
     "pydantic",
     "ruff",
     "setuptools",
-    "packaging", 
+    "packaging",
     "wheel",
     "twine",
     "tomli",
@@ -68,10 +68,11 @@ test = [
     "django",
     "openai",
     "anthropic",
-    "langgraph",
-    "langchain-community>=0.2.0",
-    "langchain-openai>=0.2.0",
-    "langchain-anthropic>=0.2.0",
+    "langgraph>=0.4.8",
+    "langchain-core>=0.3.65",
+    "langchain-community>=0.3.25",
+    "langchain-openai>=0.3.22",
+    "langchain-anthropic>=0.3.15",
     "google-genai",
     "pydantic",
     "parameterized>=0.8.1",
@@ -86,8 +87,7 @@ packages = [
     "posthog.ai.anthropic",
     "posthog.ai.gemini",
     "posthog.test",
-    "posthog.sentry",
-    "posthog.exception_integrations",
+    "posthog.integrations",
 ]
 
 [tool.setuptools.dynamic]

sentry_django_example/manage.py

@@ -1,23 +0,0 @@
-#!/usr/bin/env python
-"""Django's command-line utility for administrative tasks."""
-
-import os
-import sys
-
-
-def main():
-    """Run administrative tasks."""
-    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "sentry_django_example.settings")
-    try:
-        from django.core.management import execute_from_command_line
-    except ImportError as exc:
-        raise ImportError(
-            "Couldn't import Django. Are you sure it's installed and "
-            "available on your PYTHONPATH environment variable? Did you "
-            "forget to activate a virtual environment?"
-        ) from exc
-    execute_from_command_line(sys.argv)
-
-
-if __name__ == "__main__":
-    main()

sentry_django_example/sentry_django_example/asgi.py

@@ -1,16 +0,0 @@
-"""
-ASGI config for sentry_django_example project.
-
-It exposes the ASGI callable as a module-level variable named ``application``.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/3.2/howto/deployment/asgi/
-"""
-
-import os
-
-from django.core.asgi import get_asgi_application
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "sentry_django_example.settings")
-
-application = get_asgi_application()

sentry_django_example/sentry_django_example/settings.py

@@ -1,171 +0,0 @@
-"""
-Django settings for sentry_django_example project.
-
-Generated by 'django-admin startproject' using Django 3.2.2.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/3.2/topics/settings/
-
-For the full list of settings and their values, see
-https://docs.djangoproject.com/en/3.2/ref/settings/
-"""
-
-from pathlib import Path
-from uuid import uuid4
-
-# Build paths inside the project like this: BASE_DIR / 'subdir'.
-BASE_DIR = Path(__file__).resolve().parent.parent
-
-
-# Quick-start development settings - unsuitable for production
-# See https://docs.djangoproject.com/en/3.2/howto/deployment/checklist/
-
-# SECURITY WARNING: keep the secret key used in production secret!
-SECRET_KEY = "django-insecure-4kzfiq7vb(t0+jbl#vq)u=%06ouf)n*=l%730c8=tk(wkm9i9o"
-
-# SECURITY WARNING: don't run with debug turned on in production!
-DEBUG = True
-
-ALLOWED_HOSTS = []
-
-
-# PostHog Setup (can be a separate app)
-import posthog  # noqa: E402
-
-# You can find this key on the /setup page in PostHog
-posthog.api_key = (
-    "LXP6nQXvo-2TCqGVrWvPah8uJIyVykoMmhnEkEBi5PA"  # TODO: replace with your api key
-)
-
-posthog.personal_api_key = ""
-
-# Where you host PostHog, with no trailing /.
-# You can remove this line if you're using posthog.com
-posthog.host = "http://127.0.0.1:8000"
-
-from posthog.sentry.posthog_integration import PostHogIntegration  # noqa: E402
-
-PostHogIntegration.organization = "posthog"  # TODO: your sentry organization
-# PostHogIntegration.prefix = # TODO: your self hosted Sentry url. (default: https://sentry.io/organizations/)
-
-# Since Sentry doesn't allow Integrations configuration (see https://github.com/getsentry/sentry-python/blob/master/sentry_sdk/integrations/__init__.py#L171-L183)
-# we work around this by setting static class variables beforehand
-
-# Sentry Setup
-import sentry_sdk  # noqa: E402
-from sentry_sdk.integrations.django import DjangoIntegration  # noqa: E402
-
-sentry_sdk.init(
-    dsn="https://27ac54f7f4cf484abf1335436b0c52e5@o344752.ingest.sentry.io/5624115",  # TODO: your Sentry DSN here
-    integrations=[DjangoIntegration(), PostHogIntegration()],
-    # Set traces_sample_rate to 1.0 to capture 100%
-    # of transactions for performance monitoring.
-    # We recommend adjusting this value in production.
-    traces_sample_rate=1.0,
-    # If you wish to associate users to errors (assuming you are using
-    # django.contrib.auth) you may enable sending PII data.
-    send_default_pii=True,
-)
-
-POSTHOG_DJANGO = {
-    "distinct_id": lambda request: str(
-        uuid4()
-    )  # TODO: your logic for generating unique ID, given the request object
-}
-
-# Application definition
-
-INSTALLED_APPS = [
-    "django.contrib.admin",
-    "django.contrib.auth",
-    "django.contrib.contenttypes",
-    "django.contrib.sessions",
-    "django.contrib.messages",
-    "django.contrib.staticfiles",
-]
-
-MIDDLEWARE = [
-    "django.middleware.security.SecurityMiddleware",
-    "django.contrib.sessions.middleware.SessionMiddleware",
-    "django.middleware.common.CommonMiddleware",
-    "django.middleware.csrf.CsrfViewMiddleware",
-    "django.contrib.auth.middleware.AuthenticationMiddleware",
-    "django.contrib.messages.middleware.MessageMiddleware",
-    "django.middleware.clickjacking.XFrameOptionsMiddleware",
-    "posthog.sentry.django.PosthogDistinctIdMiddleware",
-]
-
-ROOT_URLCONF = "sentry_django_example.urls"
-
-TEMPLATES = [
-    {
-        "BACKEND": "django.template.backends.django.DjangoTemplates",
-        "DIRS": [],
-        "APP_DIRS": True,
-        "OPTIONS": {
-            "context_processors": [
-                "django.template.context_processors.debug",
-                "django.template.context_processors.request",
-                "django.contrib.auth.context_processors.auth",
-                "django.contrib.messages.context_processors.messages",
-            ],
-        },
-    },
-]
-
-WSGI_APPLICATION = "sentry_django_example.wsgi.application"
-
-
-# Database
-# https://docs.djangoproject.com/en/3.2/ref/settings/#databases
-
-DATABASES = {
-    "default": {
-        "ENGINE": "django.db.backends.sqlite3",
-        "NAME": BASE_DIR / "db.sqlite3",
-    }
-}
-
-
-# Password validation
-# https://docs.djangoproject.com/en/3.2/ref/settings/#auth-password-validators
-
-AUTH_PASSWORD_VALIDATORS = [
-    {
-        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
-    },
-    {
-        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
-    },
-]
-
-
-# Internationalization
-# https://docs.djangoproject.com/en/3.2/topics/i18n/
-
-LANGUAGE_CODE = "en-us"
-
-TIME_ZONE = "UTC"
-
-USE_I18N = True
-
-USE_L10N = True
-
-USE_TZ = True
-
-
-# Static files (CSS, JavaScript, Images)
-# https://docs.djangoproject.com/en/3.2/howto/static-files/
-
-STATIC_URL = "/static/"
-
-# Default primary key field type
-# https://docs.djangoproject.com/en/3.2/ref/settings/#default-auto-field
-
-DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

sentry_django_example/sentry_django_example/urls.py

@@ -1,28 +0,0 @@
-"""sentry_django_example URL Configuration
-
-The `urlpatterns` list routes URLs to views. For more information please see:
-    https://docs.djangoproject.com/en/3.2/topics/http/urls/
-Examples:
-Function views
-    1. Add an import:  from my_app import views
-    2. Add a URL to urlpatterns:  path('', views.home, name='home')
-Class-based views
-    1. Add an import:  from other_app.views import Home
-    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
-Including another URLconf
-    1. Import the include() function: from django.urls import include, path
-    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
-"""
-
-from django.contrib import admin
-from django.urls import path
-
-
-def trigger_error(request):
-    division_by_zero = 1 / 0
-
-
-urlpatterns = [
-    path("admin/", admin.site.urls),
-    path("sentry-debug/", trigger_error),
-]

sentry_django_example/sentry_django_example/wsgi.py

@@ -1,16 +0,0 @@
-"""
-WSGI config for sentry_django_example project.
-
-It exposes the WSGI callable as a module-level variable named ``application``.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/3.2/howto/deployment/wsgi/
-"""
-
-import os
-
-from django.core.wsgi import get_wsgi_application
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "sentry_django_example.settings")
-
-application = get_wsgi_application()

simulator.py

@@ -1,112 +0,0 @@
-import argparse
-import json
-import logging
-
-import posthog
-
-__name__ = "simulator.py"
-__version__ = "0.0.1"
-__description__ = "scripting simulator"
-
-
-def json_hash(str):
-    if str:
-        return json.loads(str)
-
-
-# posthog -method=<method> -posthog-write-key=<posthogWriteKey> [options]
-
-
-parser = argparse.ArgumentParser(description="send a posthog message")
-
-parser.add_argument("--writeKey", help="the posthog writeKey")
-parser.add_argument("--type", help="The posthog message type")
-
-parser.add_argument("--distinct_id", help="the user id to send the event as")
-parser.add_argument("--anonymousId", help="the anonymous user id to send the event as")
-
-parser.add_argument("--event", help="the event name to send with the event")
-parser.add_argument("--properties", help="the event properties to send (JSON-encoded)")
-
-parser.add_argument(
-    "--name", help="name of the screen or page to send with the message"
-)
-
-parser.add_argument("--traits", help="the identify/group traits to send (JSON-encoded)")
-
-parser.add_argument("--groupId", help="the group id")
-
-options = parser.parse_args()
-
-
-def failed(status, msg):
-    raise Exception(msg)
-
-
-def capture():
-    posthog.capture(
-        options.distinct_id,
-        options.event,
-        anonymous_id=options.anonymousId,
-        properties=json_hash(options.properties),
-    )
-
-
-def page():
-    posthog.page(
-        options.distinct_id,
-        name=options.name,
-        anonymous_id=options.anonymousId,
-        properties=json_hash(options.properties),
-    )
-
-
-def identify():
-    posthog.identify(
-        options.distinct_id,
-        anonymous_id=options.anonymousId,
-        traits=json_hash(options.traits),
-    )
-
-
-def set_once():
-    posthog.set_once(
-        options.distinct_id,
-        properties=json_hash(options.traits),
-    )
-
-
-def set():
-    posthog.set(
-        options.distinct_id,
-        properties=json_hash(options.traits),
-    )
-
-
-def unknown():
-    print()
-
-
-posthog.api_key = options.writeKey
-posthog.on_error = failed
-posthog.debug = True
-
-log = logging.getLogger("posthog")
-ch = logging.StreamHandler()
-ch.setLevel(logging.DEBUG)
-log.addHandler(ch)
-
-switcher = {
-    "capture": capture,
-    "page": page,
-    "identify": identify,
-    "set_once": set_once,
-    "set": set,
-}
-
-func = switcher.get(options.type)
-if func:
-    func()
-    posthog.shutdown()
-else:
-    print("Invalid Message Type " + options.type)