Segment Analytics Python

2.3.5 · maintenance · verified Sun Apr 05

The `segment-analytics-python` library provides a hassle-free way to integrate analytics into any Python application. It acts as an official Python client for the Segment REST API, allowing users to send customer behavioral data to Segment, which then routes it to various analytics services and data warehouses. As of version 2.3.5, the library is in maintenance mode, meaning it will continue to send data as intended but will receive no new feature support and only critical maintenance updates from Segment.

Warnings

deprecated The `segment-analytics-python` library is in maintenance mode. This means it will only receive critical bug fixes and security updates, but no new features. Users should be aware that active development has ceased.
Fix: Continue to use the library for existing integrations, but be aware of the lack of new features. For new projects or if advanced features are required, evaluate other Segment SDKs or consider the implications of a maintenance-only library.
gotcha Events are batched and sent asynchronously by default. In development or for scripts that exit quickly, you might not see events sent if `analytics.flush()` or `analytics.shutdown()` are not called, or if `analytics.send = False` is set for testing.
Fix: Always call `analytics.flush()` or `analytics.shutdown()` at the end of your application's lifecycle or script to ensure all queued events are sent. For development, set `analytics.debug = True` and an `on_error` handler to catch issues.
breaking If you were using an older version (1.x) of `analytics-python`, some configurations or imports might have changed in version 2.x. Specifically, the recommended import path is `import segment.analytics as analytics`. Pinning dependencies to `1.X` was recommended to avoid breaking changes in the past.
Fix: Review the official Segment Python library documentation for detailed migration guides if coming from a 1.x version. Ensure imports are updated to `import segment.analytics as analytics` and verify method signatures if you encounter errors.
gotcha Incorrectly setting the `write_key` or not setting it at all will result in analytics events not being sent to Segment. Hardcoding the `write_key` directly in code is also a security risk.
Fix: Always retrieve the Segment `write_key` from a secure environment variable (e.g., `SEGMENT_WRITE_KEY`) and ensure it's correctly assigned to `analytics.write_key`. Validate that the key is present before making analytics calls.

Install

pip install segment-analytics-python Install latest version

Imports

analytics
```
import segment.analytics as analytics
```
The top-level 'analytics' module in `segment-analytics-python` should be imported as `segment.analytics` to avoid potential naming conflicts with other 'analytics' modules or local files.
Client
```
from segment.analytics.client import Client
```
For advanced use cases like sending data to multiple Segment sources, you can initialize a new Client directly with a specific write_key.

Quickstart

This quickstart demonstrates how to initialize the Segment client, identify a user, track an event, record a page view, and associate a user with a group. It includes best practices for handling the `write_key` via environment variables and setting up error handling for development. Remember to replace `YOUR_SEGMENT_WRITE_KEY` or set the `SEGMENT_WRITE_KEY` environment variable.

import os
import segment.analytics as analytics

# It's recommended to set the write_key via an environment variable for security
WRITE_KEY = os.environ.get('SEGMENT_WRITE_KEY', 'YOUR_SEGMENT_WRITE_KEY')

if not WRITE_KEY or WRITE_KEY == 'YOUR_SEGMENT_WRITE_KEY':
    print("WARNING: SEGMENT_WRITE_KEY environment variable not set or using placeholder. Analytics calls will not be sent.")
    analytics.send = False # Disable sending if key is not set
else:
    analytics.write_key = WRITE_KEY
    print(f"Segment write_key set: {analytics.write_key[:4]}...{analytics.write_key[-4:]}")

# Configure for development (optional, but recommended to see errors)
analytics.debug = True
def on_error(error, items):
    print(f"An error occurred with Segment: {error}. Items: {items}")
analytics.on_error = on_error

# Identify a user
analytics.identify('user-123', {
    'name': 'John Doe',
    'email': 'john.doe@example.com',
    'plan': 'premium'
})

# Track an event
analytics.track('Sign Up Completed', {
    'method': 'email',
    'plan': 'premium'
})

# Page view (for server-side apps, typically not directly used for web page views)
analytics.page('App Home', {
    'path': '/home',
    'title': 'Homepage'
})

# Group (associate a user with a group, e.g., a company)
analytics.group('user-123', 'company-456', {
    'name': 'Acme Corp',
    'industry': 'Software'
})

# Flush any remaining events in the queue
analytics.flush()
print("Segment events sent (or queued if SEND_DISABLED is not set).")

view raw JSON →