Python

The Helion Python SDK allows you to track user behavior in your Python applications.

Looking for a step-by-step tutorial? Check out the Python analytics guide.

Installation

Install dependencies

pip install helion

Initialize

Import and initialize the Helion SDK with your credentials:

from helion import Helion

hl = Helion(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)

Configuration Options

Common options

apiUrl - The url of the helion API or your self-hosted instance
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, the library will not send any events

Additional Python-specific options:

filter — A function called before each event. Return False to suppress the event.
disabled — Set to True to disable all event tracking
global_properties — Dictionary of properties sent with every event

Filter Function Example

def my_filter(event):
    return event.get('name') != 'my_event'

hl = Helion(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    filter=my_filter
)

Usage

Tracking Events

# Track a simple event
hl.track("button_clicked")

# Track with properties
hl.track("purchase_completed", {
    "product_id": "123",
    "price": 99.99,
    "currency": "USD"
})

# Track for a specific user
hl.track("login_successful", {
    "method": "google"
}, profile_id="user_123")

Identifying Users

hl.identify("user123", {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "tier": "premium",
    "company": "Acme Inc"
})

Setting Global Properties

Properties set here are merged into every subsequent track() call.

hl.set_global_properties({
    "app_version": "1.0.2",
    "environment": "production",
    "deployment": "us-east-1"
})

Incrementing Properties

Increment a numeric property on a user profile. Omit value to increment by 1.

hl.increment({
    "profile_id": "1",
    "property": "visits",
    "value": 1  # optional, defaults to 1
})

Decrementing Properties

Decrement a numeric property on a user profile. Omit value to decrement by 1.

hl.decrement({
    "profile_id": "1",
    "property": "credits",
    "value": 1  # optional, defaults to 1
})

Clearing User Data

clear() resets the current user profile, device identity, and session.

hl.clear()

Advanced Usage

Thread Safety

The Helion SDK is thread-safe. A single instance can be shared across multiple threads without additional synchronization.

Error Handling

The SDK includes built-in error handling and will not raise exceptions during normal operation. Wrap SDK calls in try/except for additional safety if needed:

try:
    hl.track("important_event", {"critical": True})
except Exception as e:
    logger.error(f"Failed to track event: {e}")

Disabling Tracking

Disable all tracking for local development or testing — no HTTP calls are made:

# Disable during initialization
hl = Helion(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    disabled=True
)

# Or disable after initialization
hl.disabled = True

Common options

On this page