docs and fixes

Author: oliverb123

CHANGELOG.md

@@ -6,6 +6,23 @@ This release contains a number of major breaking changes:
 - 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

posthog/__init__.py

@@ -4,7 +4,7 @@
 
 from posthog.args import OptionalCaptureArgs, OptionalSetArgs, ExceptionArg
 from posthog.client import Client
-from posthog.scopes import (
+from posthog.contexts import (
     new_context as inner_new_context,
     scoped as inner_scoped,
     tag as inner_tag,
@@ -64,7 +64,7 @@ def tag(name: str, value: Any):
 default_client = None  # type: Optional[Client]
 
 
-# NOTE - this and following functions take and unpack kwargs because we needed to make
+# 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
@@ -76,17 +76,33 @@ def capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str]:
     - `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
-    - `distinct id` which uniquely identifies your user. This overrides any context-level ID, if set
-    - `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
     ```
     """
 
@@ -96,10 +112,14 @@ def capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str]:
 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
-     - `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
@@ -115,17 +135,9 @@ def set(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
 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`.
-
-     A `set_once` call requires
-     - `distinct id` which uniquely identifies your user
-     - `properties` with a dict with any key: value pairs
+    This will not overwrite previous people property values, unlike `set`.
 
-     For example:
-     ```python
-     posthog.set_once('distinct id', {
-         'referred_by': 'friend',
-     })
+    Otherwise, operates in an identical manner to `set`.
      ```
     """
     return _proxy("set_once", **kwargs)
@@ -146,7 +158,6 @@ def group_identify(
      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
@@ -176,11 +187,10 @@ def alias(
 ):
     # 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
@@ -207,27 +217,26 @@ def capture_exception(
     **kwargs: Unpack[OptionalCaptureArgs],
 ):
     """
-    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.
+
+    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 sending:
-    - `distinct id` which uniquely identifies your user for which this exception happens
+    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`.
     """
 
     return _proxy("capture_exception", exception=exception, **kwargs)

posthog/args.py

@@ -9,19 +9,49 @@
 
 
 class OptionalCaptureArgs(TypedDict):
-    """Optional arguments for the capture method."""
+    """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 True
+        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[bool]
-    disable_geoip: NotRequired[Optional[bool]]
+    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."""
+    """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]]]

posthog/client.py

@@ -12,7 +12,6 @@
 
 from posthog.args import OptionalCaptureArgs, OptionalSetArgs, ID_TYPES, ExceptionArg
 from posthog.consumer import Consumer
-from posthog.scopes import new_context
 from posthog.exception_capture import ExceptionCapture
 from posthog.exception_utils import (
     exc_info_from_error,
@@ -32,10 +31,11 @@
     get,
     remote_config,
 )
-from posthog.scopes import (
+from posthog.contexts import (
     _get_current_context,
     get_context_distinct_id,
     get_context_session_id,
+    new_context,
 )
 from posthog.types import (
     FeatureFlag,
@@ -415,7 +415,7 @@ def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
 
         (distinct_id, personless) = get_identity_state(distinct_id)
 
-        if personless:
+        if personless or not properties:
             return None  # Personless set() does nothing
 
         msg = {
@@ -440,7 +440,7 @@ def set_once(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
 
         (distinct_id, personless) = get_identity_state(distinct_id)
 
-        if personless:
+        if personless or not properties:
             return None  # Personless set_once() does nothing
 
         msg = {

posthog/scopes.py posthog/contexts.pyposthog/scopes.py renamed to posthog/contexts.py

@@ -1,5 +1,5 @@
 from typing import TYPE_CHECKING, cast
-from posthog import scopes
+from posthog import contexts
 
 if TYPE_CHECKING:
     from django.http import HttpRequest, HttpResponse  # noqa: F401
@@ -83,12 +83,12 @@ def extract_tags(self, request):
         # Extract session ID from X-POSTHOG-SESSION-ID header
         session_id = request.headers.get("X-POSTHOG-SESSION-ID")
         if session_id:
-            scopes.set_context_session(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:
-            scopes.identify_context(distinct_id)
+            contexts.identify_context(distinct_id)
 
         # Extract user email
         if user_email:
@@ -153,8 +153,8 @@ def __call__(self, request):
         if self.request_filter and not self.request_filter(request):
             return self.get_response(request)
 
-        with scopes.new_context(self.capture_exceptions):
+        with contexts.new_context(self.capture_exceptions):
             for k, v in self.extract_tags(request).items():
-                scopes.tag(k, v)
+                contexts.tag(k, v)
 
             return self.get_response(request)

posthog/integrations/django.py

@@ -1,4 +1,8 @@
-from posthog.scopes import new_context, get_context_session_id, get_context_distinct_id
+from posthog.contexts import (
+    new_context,
+    get_context_session_id,
+    get_context_distinct_id,
+)
 import unittest
 from unittest.mock import Mock
 

posthog/test/integrations/test_middleware.py

@@ -2,7 +2,7 @@
 import unittest
 from datetime import datetime
 from uuid import uuid4
-from posthog.scopes import get_context_session_id, set_context_session, new_context
+from posthog.contexts import get_context_session_id, set_context_session, new_context
 
 import mock
 import six
@@ -1877,7 +1877,7 @@ def test_set_context_session_with_page_explicit_properties(self):
 
     def test_set_context_session_override_in_capture(self):
         """Test that explicit session ID overrides context session ID in capture"""
-        from posthog.scopes import set_context_session, new_context
+        from posthog.contexts import set_context_session, new_context
 
         with mock.patch("posthog.client.batch_post") as mock_post:
             client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True)

posthog/test/test_client.py

@@ -1,7 +1,7 @@
 import unittest
 from unittest.mock import patch
 
-from posthog.scopes import (
+from posthog.contexts import (
     get_tags,
     new_context,
     scoped,
@@ -13,7 +13,7 @@
 )
 
 
-class TestScopes(unittest.TestCase):
+class TestContexts(unittest.TestCase):
     def test_tag_and_get_tags(self):
         with new_context(fresh=True):
             tag("key1", "value1")