Skip to content

docs: add docstrings to ExceptionCapture public methods - #1257

Open
mi-vault wants to merge 3 commits into
PostHog:mainfrom
mi-vault:docs/add-exception-capture-docstrings
Open

mi-vault wants to merge 3 commits into
PostHog:mainfrom
mi-vault:docs/add-exception-capture-docstrings

Conversation

@mi-vault

@mi-vault mi-vault commented Nov 15, 2026 •

Copy link
Copy Markdown

Motivation and Context

ExceptionCapture is the class responsible for installing and managing process-wide sys.excepthook and threading.excepthook handlers that forward uncaught exceptions to PostHog. Its public methods (__init__, close, exception_handler, thread_exception_handler, exception_receiver, and capture_exception) had no docstrings, making it harder for contributors and integrators to understand the intent, parameters, and behaviour of each method without reading through the implementation.

This PR adds:

  • A class-level docstring describing what ExceptionCapture does and its two optional features (hook chaining and rate limiting)
  • An __init__ docstring covering all five parameters with their clamping constraints and defaults
  • Method docstrings for close, exception_handler, thread_exception_handler, exception_receiver, and capture_exception

No behaviour changes; documentation only.

How did you test it?

Existing test suite (pytest --verbose --timeout=30) passes without modification. No new tests are needed as this is a documentation-only change.

Verified with:

  • ruff format --check . (clean)
  • ruff check . (clean)
  • Manually reviewed the docstrings against the implementation for accuracy

Checklist

  • My code follows the PostHog Engineering guidelines.
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • All commits are signed with GPG (required)

Agent Context

  • Autonomy level: Human-driven (agent-assisted)
  • Tools used: Antigravity (Google DeepMind agent assistant)
  • What was decided by the human: Which file to document, which methods to cover, the wording of each docstring (reviewed and approved before commit)
  • What the agent did: Drafted docstring text based on reading the existing source code and inline comments; ran ruff checks

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 <asmisharma2026@gmail.com>
@mi-vault
mi-vault requested a review from a team as a code owner November 15, 2026 16:09

@marandaneto marandaneto left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent-drafted and reviewed by Manoel.

Comment thread posthog/exception_capture.py Resolved
Comment thread posthog/exception_capture.py Resolved
@marandaneto
marandaneto requested a review from a team November 16, 2026 09:29
Signed-off-by: mi-vault <asmisharma2026@gmail.com>

@marandaneto marandaneto left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent-drafted and reviewed by Manoel.

Thanks for addressing the feedback. The bucket_size docstring now describes it as token capacity, and the exception_receiver docstring no longer claims the Django/Flask integrations use it. LGTM.

@marandaneto
marandaneto enabled auto-merge (squash) November 16, 2026 10:18

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants