posthoganalytics 5.3.0__py3-none-any.whl → 6.0.0__py3-none-any.whl

posthoganalytics/__init__.py

@@ -1,17 +1,15 @@
 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 posthoganalytics.args import OptionalCaptureArgs, OptionalSetArgs, ExceptionArg
 from posthoganalytics.client import Client
-from posthoganalytics.exception_capture import Integrations  # noqa: F401
-from posthoganalytics.scopes import (
-    clear_tags,
-    get_tags,
-    new_context,
-    scoped,
-    tag,
-    set_context_session,
-    identify_context,
+from posthoganalytics.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 posthoganalytics.types import FeatureFlag, FlagsAndPayloads
 from posthoganalytics.version import VERSION
@@ -19,13 +17,26 @@ from posthoganalytics.version import VERSION
 __version__ = VERSION
 
 """Context management."""
-new_context = new_context
-tag = tag
-get_tags = get_tags
-clear_tags = clear_tags
-scoped = scoped
-identify_context = identify_context
-set_context_session = set_context_session
+
+
+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."""
@@ -44,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]
@@ -54,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')
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        # Capture an event associated with some other user (overriding the context-level distinct ID)
+        posthog.capture('movie joined', distinct_id='some-other-user')
 
-    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,
-    )
+        # 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'})
 
-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
+        # Adding a tag to the current context will cause it to appear on all subsequent events
+        posthog.tag_context('some-tag', 'some-value')
 
-    For example:
-    ```python
-    posthog.identify('distinct id', {
-        'email': 'dwayne@gmail.com',
-        'name': 'Dwayne Johnson'
-    })
+        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(
-        "identify",
-        distinct_id=distinct_id,
-        properties=properties,
-        context=context,
-        timestamp=timestamp,
-        uuid=uuid,
-        disable_geoip=disable_geoip,
-    )
+    return _proxy("capture", event, **kwargs)
 
 
-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`.
-
-     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`.
      ```
     """
-
-    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
@@ -263,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,
@@ -285,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
@@ -308,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,
@@ -327,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.
 
-    if context is not None:
-        warnings.warn(
-            "The 'context' parameter is deprecated and will be removed in a future version.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+    `capture_exception` takes the same set of optional arguments as `capture`.
+    """
 
-    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(
@@ -565,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")
@@ -594,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,
@@ -602,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,
@@ -613,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

posthoganalytics/ai/langchain/callbacks.py

@@ -84,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]]
@@ -112,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,

posthoganalytics/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 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[
+        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]