Subchapter 47.55

PostHog Python

references/posthog-python.mdMarkdown43 KBView on GitHub

PostHog Python SDK

SDK Version: 7.17.0

Integrate PostHog into any python application.

Categories

PostHog Python · Instrument Integration · PostHog/skills · Skills Docs

project_api_key? (str) - PostHog project API key/token.
host (any) - PostHog host. Defaults to the US ingestion endpoint when not set. App hosts such as https://us.posthog.com are mapped to the corresponding ingestion host.
debug (bool) - Enable verbose SDK logging and re-raise errors from public API methods.
max_queue_size (int) - Maximum number of events buffered before upload.
send (bool) - If False, queueing succeeds but events are not sent.
on_error (any) - Optional callback invoked by background consumers when an upload fails.
flush_at (int) - Number of queued events that triggers a batch upload.
flush_interval (float) - Maximum seconds a background consumer waits before flushing a partial batch.
gzip (bool) - Whether to gzip event upload payloads.
max_retries (int) - Number of upload retries for background consumers.
sync_mode (bool) - If True, send each event synchronously instead of using background worker threads.
timeout (int) - HTTP request timeout in seconds for event uploads.
thread (int) - Number of background consumer threads.
poll_interval (int) - Seconds between local feature flag definition refreshes.
personal_api_key (any) - Personal API key used for local feature flag evaluation and remote config payloads.
disabled (bool) - If True, disable captures and API requests. Useful in tests.
disable_geoip (bool) - Whether to disable server-side GeoIP enrichment. Defaults to True.
is_server (bool) - Whether events are emitted from a server-side runtime. Defaults to True; set to False when using the SDK as a client/CLI so the device OS is attributed to the person normally.
historical_migration (bool) - Mark events as historical migration imports.
feature_flags_request_timeout_seconds (int) - Timeout in seconds for feature flag and remote config requests.
super_properties (any) - Properties merged into every captured event.
enable_exception_autocapture (bool) - Automatically capture uncaught exceptions.
log_captured_exceptions (bool) - Also log exceptions captured by error tracking.
project_root (any) - Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.
privacy_mode (bool) - For AI observability, capture usage metadata without prompt inputs or outputs.
before_send (any) - Optional callback that can modify or drop events before upload. Return None to drop an event.
flag_fallback_cache_url (any) - Optional feature flag fallback cache URL, such as memory://local/?ttl=300&size=10000 or a Redis URL.
enable_local_evaluation (bool) - Whether to poll feature flag definitions for local evaluation when a personal API key is configured.
flag_definition_cache_provider? (FlagDefinitionCacheProvider) - Optional external cache provider for sharing feature flag definitions across workers.
capture_exception_code_variables (bool) - Capture local variable values on exception stack frames.
code_variables_mask_patterns (any) - Variable-name patterns to mask when capturing code variables.
code_variables_ignore_patterns (any) - Variable-name patterns to omit when capturing code variables.
in_app_modules (UnionType[list[str], any]) - Module/package prefixes treated as in-app frames in captured exceptions.

# Context usage
from posthog import identify_context, new_context
with new_context():
    identify_context('distinct_id_of_the_user')
    posthog.capture('user_signed_up')
    posthog.capture('user_logged_in')
    posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')

# Set event properties
posthog.capture(
    "user_signed_up",
    distinct_id="distinct_id_of_the_user",
    properties={
        "login_type": "email",
        "is_free_trial": "true"
    }
)

flags = posthog.evaluate_flags(
    "user_123",
    person_properties={"plan": "enterprise"},
)
if flags.is_enabled("new-dashboard"):
    render_new_dashboard()
posthog.capture("page_viewed", distinct_id="user_123", flags=flags)

is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')
if is_my_flag_enabled:
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')
if enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')

if is_my_flag_enabled:
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')
if flag_result and flag_result.get_value() == 'variant-key':
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = flag_result.payload

# Context and capture usage
from posthog import new_context, identify_context, tag_context, capture
# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)
with new_context():
    # Associate this context with some user, by distinct_id
    identify_context('some user')

    # Capture an event, associated with the context-level distinct ID ('some user')
    capture('movie started')

    # Capture an event associated with some other user (overriding the context-level distinct ID)
    capture('movie joined', distinct_id='some-other-user')

    # Capture an event with some properties
    capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})

    # Capture an event with some properties
    capture('purchase', properties={'product_id': '123', 'category': 'romcom'})
    # Capture an event with some associated group
    capture('purchase', groups={'company': 'id:5'})

    # Adding a tag to the current context will cause it to appear on all subsequent events
    tag_context('some-tag', 'some-value')

    capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict

# Set event properties
from posthog import capture
capture(
    "user_signed_up",
    distinct_id="distinct_id_of_the_user",
    properties={
        "login_type": "email",
        "is_free_trial": "true"
    }
)

from posthog import evaluate_flags, capture
flags = evaluate_flags("user_123", person_properties={"plan": "enterprise"})
if flags.is_enabled("new-dashboard"):
    render_new_dashboard()
capture("page_viewed", distinct_id="user_123", flags=flags)

# Boolean feature flag
from posthog import feature_enabled, get_feature_flag_payload
is_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')
if is_my_flag_enabled:
    matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

# Multivariate feature flag
from posthog import get_feature_flag, get_feature_flag_payload
enabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')
if enabled_variant == 'variant-key':
    matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')