mcpField
I
integration-python

integration-python

github.com/posthogData & databases7692 installsUpdated today
Repository

About integration-python

A skill for adding PostHog analytics to Python applications. It provides a staged integration workflow, example code, and Python-specific guidance for event tracking, user identification, and error capture.

Key features

  1. 01Four-step integration workflow
  2. 02Python and PostHog references
  3. 03Environment-variable key handling
  4. 04Event tracking and user identification
  5. 05Exception capture and shutdown guidance

Use cases

  1. 01Adding PostHog analytics to a Python app
  2. 02Tracking user activity while avoiding PII in events
  3. 03Adding error tracking at API boundaries

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/posthog/skills --skill integration-python

After installing, type/integration-pythonin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
basic-integration-1.0-begin.md
basic-integration-1.1-edit.md
basic-integration-1.2-revise.md
basic-integration-1.3-conclude.md
EXAMPLE.md
identify-users.md
posthog-python.md
python.md

Details

From the project README

PostHog integration for Python

This skill helps you add PostHog analytics to Python applications.

Workflow

Follow these steps in order to complete the integration:

  1. basic-integration-1.0-begin.md - PostHog Setup - Begin ← Start here
  2. basic-integration-1.1-edit.md - PostHog Setup - Edit
  3. basic-integration-1.2-revise.md - PostHog Setup - Revise
  4. basic-integration-1.3-conclude.md - PostHog Setup - Conclusion

Reference files

  • references/EXAMPLE.md - Python example project code
  • references/python.md - Python - docs
  • references/posthog-python.md - PostHog python SDK
  • references/identify-users.md - Identify users - docs
  • references/basic-integration-1.0-begin.md - PostHog setup - begin
  • references/basic-integration-1.1-edit.md - PostHog setup - edit
  • references/basic-integration-1.2-revise.md - PostHog setup - revise
  • references/basic-integration-1.3-conclude.md - PostHog setup - conclusion

The example project shows the target implementation pattern. Consult the documentation for API details.

Key principles

  • Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
  • Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
  • Match the example: Your implementation should follow the example project's patterns as closely as possible.

Framework guidelines

  • Remember that source code is available in the venv/site-packages directory
  • posthog is the Python SDK package name
  • Install dependencies with pip install posthog or pip install -r requirements.txt and do NOT use unquoted version specifiers like >= directly in shell commands
  • In CLIs and scripts: MUST call posthog.shutdown() before exit or all events are lost
  • Always use the Posthog() class constructor (instance-based API) instead of module-level posthog.api_key config
  • Always include enable_exception_autocapture=True in the Posthog() constructor to automatically track exceptions
  • NEVER send PII in capture() event properties — no emails, full names, phone numbers, physical addresses, IP addresses, or user-generated content
  • PII belongs in identify() person properties, NOT in capture() event properties. Safe event properties are metadata like message_length, form_type, boolean flags.
  • Register posthog_client.shutdown with atexit.register() to ensure all events are flushed on exit
  • The Python SDK has NO identify() method — use posthog_client.set(distinct_id=user_id, properties={...}) to set person properties, or use identify_context(user_id) within a context

Identifying users

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers to maintain correlation.

Error tracking

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.

Comments

Markdown supported