integration-python

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog integration for Python

Python应用的PostHog集成

This skill helps you add PostHog analytics to Python applications.

本技能可帮助你为Python应用添加PostHog分析功能。

Workflow

工作流程

Follow these steps in order to complete the integration:

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

按照以下步骤完成集成：

```
basic-integration-1.0-begin.md
```
- PostHog设置 - 开始 ← 从此处启动
```
basic-integration-1.1-edit.md
```
- PostHog设置 - 编辑
```
basic-integration-1.2-revise.md
```
- PostHog设置 - 修改
```
basic-integration-1.3-conclude.md
```
- PostHog设置 - 总结

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.

```
references/EXAMPLE.md
```
- Python示例项目代码
```
references/python.md
```
- Python相关文档
```
references/posthog-python.md
```
- PostHog Python SDK文档
```
references/identify-users.md
```
- 用户身份识别文档

references/basic-integration-1.0-begin.md

- PostHog设置-开始文档

references/basic-integration-1.1-edit.md

- PostHog设置-编辑文档

references/basic-integration-1.2-revise.md

- PostHog设置-修改文档

references/basic-integration-1.3-conclude.md

- PostHog设置-总结文档

示例项目展示了目标实现模式。如需了解API详情，请查阅相关文档。

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.

环境变量：始终使用环境变量存储PostHog密钥，绝对不要硬编码。
最小改动：在现有集成代码旁添加PostHog代码，不要替换或重构现有代码。
匹配示例：你的实现应尽可能贴近示例项目的模式。

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

请记住，源代码位于venv/site-packages目录中
posthog是Python SDK的包名称
使用
```
pip install posthog
```
或
```
pip install -r requirements.txt
```
安装依赖，不要在shell命令中直接使用
```
>=
```
这类无引号的版本指定符
在CLI和脚本中：退出前必须调用posthog.shutdown()，否则所有事件都会丢失
始终使用Posthog()类构造函数（基于实例的API），而非模块级别的posthog.api_key配置
在Posthog()构造函数中始终包含enable_exception_autocapture=True，以自动追踪异常
绝对不要在capture()事件属性中发送PII（个人可识别信息）——禁止包含邮箱、全名、电话号码、物理地址、IP地址或用户生成内容
PII应放在identify()用户属性中，而非capture()事件属性中。安全的事件属性包括message_length、form_type、布尔标记等元数据。
使用atexit.register()注册posthog_client.shutdown，确保退出时所有事件都能被刷新
Python SDK没有identify()方法——使用posthog_client.set(distinct_id=user_id, properties={...})设置用户属性，或在上下文内使用identify_context(user_id)

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.

在登录和注册事件中识别用户。请参考示例代码和文档，了解适用于此框架的正确身份识别模式。如果同时存在前端和后端代码，请使用

X-POSTHOG-DISTINCT-ID

和

X-POSTHOG-SESSION-ID

标头传递客户端会话和唯一ID，以保持关联。

Error tracking

错误追踪

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

为相关文件添加PostHog错误追踪，尤其是关键用户流程和API边界相关的文件。