From 48b91bda8043fc8765ab0c60667a4d1257e18147 Mon Sep 17 00:00:00 2001 From: mi-vault Date: Sun, 15 Nov 2026 21:21:23 +0530 Subject: [PATCH 1/2] docs: add docstrings to ExceptionCapture public methods MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add class-level docstring and per-method docstrings to ExceptionCapture, covering __init__, close, exception_handler, thread_exception_handler, exception_receiver, and capture_exception. No behaviour changes — documentation only. Signed-off-by: mi-vault --- posthog/exception_capture.py | 77 ++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/posthog/exception_capture.py b/posthog/exception_capture.py index 6dac4057f..cd346d46f 100644 --- a/posthog/exception_capture.py +++ b/posthog/exception_capture.py @@ -20,6 +20,16 @@ class ExceptionCapture: + """Installs process-wide exception hooks that forward uncaught exceptions to PostHog. + + Hooks are installed on :attr:`sys.excepthook` (main-thread unhandled exceptions) and + :attr:`threading.excepthook` (exceptions that escape worker threads). The original + hooks are restored when :meth:`close` is called. + + Optionally enforces client-side rate limiting per exception type so that a sudden + burst of identical errors does not flood the PostHog ingestion pipeline. + """ + log = logging.getLogger("posthog") # more generous defaults than the browser SDK (10, 1, 10) because one @@ -36,6 +46,20 @@ def __init__( refill_rate=DEFAULT_REFILL_RATE, refill_interval_seconds=DEFAULT_REFILL_INTERVAL_SECONDS, ): + """Install exception hooks and configure optional rate limiting. + + Args: + client: The PostHog :class:`~posthog.client.Client` used to send captured exceptions. + rate_limiting_enabled: When ``True``, a :class:`~posthog.bucketed_rate_limiter.BucketedRateLimiter` + is created with the given bucket parameters to suppress excess captures of the same + exception type. + bucket_size: Maximum number of captures allowed per exception type before rate limiting + kicks in. Clamped to ``[0, 100]``. Default is :attr:`DEFAULT_BUCKET_SIZE` (``50``). + refill_rate: Tokens restored per completed ``refill_interval_seconds`` interval. + Clamped to ``[0, bucket_size]``. Default is :attr:`DEFAULT_REFILL_RATE` (``10``). + refill_interval_seconds: Duration of each refill interval in seconds. + Clamped to ``[0, 86400]``. Default is :attr:`DEFAULT_REFILL_INTERVAL_SECONDS` (``10``). + """ self.client = client self._closed = False self.original_excepthook = sys.excepthook @@ -55,6 +79,15 @@ def __init__( ) def close(self): + """Uninstall exception hooks and restore the hooks that were in place at construction time. + + Idempotent: calling :meth:`close` a second time has no effect. After closing, + the rate limiter (if any) is also stopped and its per-key buckets are cleared. + + This method is intentionally not thread-safe with respect to concurrent :meth:`close` + calls; callers that share an :class:`ExceptionCapture` across threads should arrange + external synchronisation if they need to close it concurrently. + """ if self._closed: return @@ -83,6 +116,17 @@ def close(self): self._rate_limiter.stop() def exception_handler(self, exc_type, exc_value, exc_traceback): + """Handle an unhandled exception from :attr:`sys.excepthook`. + + Forwards the exception to PostHog with ``level="fatal"`` and + ``mechanism.type="onuncaughtexception"``, then delegates to the previous + ``sys.excepthook`` so that normal Python crash output is preserved. + + Args: + exc_type: The exception class. + exc_value: The exception instance. + exc_traceback: The traceback object. + """ if not self._closed: capture_metadata: _ExceptionCaptureMetadata = { "level": "fatal", @@ -104,6 +148,16 @@ def exception_handler(self, exc_type, exc_value, exc_traceback): previous_hook(exc_type, exc_value, exc_traceback) def thread_exception_handler(self, args): + """Handle an unhandled exception from :attr:`threading.excepthook`. + + Forwards the exception to PostHog with ``level="error"`` and + ``mechanism.type="onuncaughtexception"``, then delegates to the previous + ``threading.excepthook``. + + Args: + args: The :class:`threading.ExceptHookArgs` object supplied by the threading machinery, + containing ``exc_type``, ``exc_value``, ``exc_traceback``, and ``thread``. + """ if not self._closed: capture_metadata: _ExceptionCaptureMetadata = { "level": "error", @@ -136,6 +190,17 @@ def _resolve_hook(hook, handler_name, previous_hook_name): hook = getattr(owner, previous_hook_name) def exception_receiver(self, exc_info, extra_properties): + """Receive an exception from an external integration and forward it to PostHog. + + This is the integration hook used by middleware and framework wrappers (such as the + Django or Flask integrations) to pass handled exceptions into the capture pipeline + without going through :attr:`sys.excepthook`. + + Args: + exc_info: A three-tuple ``(exc_type, exc_value, exc_traceback)``. + extra_properties: A mapping of extra properties. If it contains a ``"distinct_id"`` + key, that value is used as the PostHog distinct ID for the captured event. + """ if "distinct_id" in extra_properties: metadata = {"distinct_id": extra_properties["distinct_id"]} else: @@ -143,6 +208,18 @@ def exception_receiver(self, exc_info, extra_properties): self.capture_exception((exc_info[0], exc_info[1], exc_info[2]), metadata) def capture_exception(self, exception, metadata=None): + """Capture a single exception and send it to PostHog. + + A convenience wrapper around the internal :meth:`_capture_exception` method intended + for direct call sites that already hold an exception object or ``(type, value, tb)`` + tuple outside of the ``sys.excepthook`` flow. + + Args: + exception: Either an :class:`Exception` instance or a three-tuple + ``(exc_type, exc_value, exc_traceback)`` as returned by :func:`sys.exc_info`. + metadata: Optional mapping with an optional ``"distinct_id"`` key to associate + the event with a specific PostHog person. + """ self._capture_exception(exception, metadata) def _capture_exception( From 5dca71a2f8dc3a2b4032d1f5f3a3d4ae2297d975 Mon Sep 17 00:00:00 2001 From: mi-vault Date: Mon, 16 Nov 2026 15:32:21 +0530 Subject: [PATCH 2/2] docs: clarify bucket_size capacity and exception_receiver caller scope Signed-off-by: mi-vault --- posthog/exception_capture.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/posthog/exception_capture.py b/posthog/exception_capture.py index cd346d46f..db43b65c2 100644 --- a/posthog/exception_capture.py +++ b/posthog/exception_capture.py @@ -53,8 +53,10 @@ def __init__( rate_limiting_enabled: When ``True``, a :class:`~posthog.bucketed_rate_limiter.BucketedRateLimiter` is created with the given bucket parameters to suppress excess captures of the same exception type. - bucket_size: Maximum number of captures allowed per exception type before rate limiting - kicks in. Clamped to ``[0, 100]``. Default is :attr:`DEFAULT_BUCKET_SIZE` (``50``). + bucket_size: Token capacity of the rate-limiting bucket per exception type. + Because the call that empties the bucket is itself treated as rate-limited, + a fresh bucket permits ``bucket_size - 1`` captures before limiting takes + effect. Clamped to ``[0, 100]``. Default is :attr:`DEFAULT_BUCKET_SIZE` (``50``). refill_rate: Tokens restored per completed ``refill_interval_seconds`` interval. Clamped to ``[0, bucket_size]``. Default is :attr:`DEFAULT_REFILL_RATE` (``10``). refill_interval_seconds: Duration of each refill interval in seconds. @@ -190,11 +192,11 @@ def _resolve_hook(hook, handler_name, previous_hook_name): hook = getattr(owner, previous_hook_name) def exception_receiver(self, exc_info, extra_properties): - """Receive an exception from an external integration and forward it to PostHog. + """Receive an exception from an external caller and forward it to PostHog. - This is the integration hook used by middleware and framework wrappers (such as the - Django or Flask integrations) to pass handled exceptions into the capture pipeline - without going through :attr:`sys.excepthook`. + Provides an entry point for external callers to pass an ``exc_info`` tuple + and extra properties (such as ``"distinct_id"``) into the exception capture + pipeline without going through :attr:`sys.excepthook`. Args: exc_info: A three-tuple ``(exc_type, exc_value, exc_traceback)``.