Overview

Relevant source files

• README.md
• mixpanel/__init__.py

The mixpanel-python library is the official Python SDK for server-side integration with Mixpanel. It provides a comprehensive interface for tracking events, managing user and group profiles, and evaluating feature flags from Python applications running on servers, background workers, or data pipelines.

This document introduces the library's purpose, architecture, and main components. For installation instructions, see Installation. For basic usage patterns, see Quick Start. For detailed API documentation, see API Reference.

Purpose and Capabilities

The library enables server-side applications to:

• Track Events: Record user actions and behaviors with custom properties using the /track and /import endpoints
• Manage User Profiles: Update People Analytics profiles with demographic data, behavioral attributes, and revenue tracking via the /engage endpoint
• Manage Group Profiles: Track organization or account-level properties through the /groups endpoint
• Evaluate Feature Flags: Control feature rollouts using local (client-side) or remote (server-side) evaluation strategies
• Batch Operations: Optimize network usage through configurable message batching

The SDK supports both synchronous and asynchronous programming models and is compatible with Python 3.9+ and PyPy.

Sources: mixpanel/__init__.py1-16 README.md1-49

Core Architecture

The library is organized around three primary subsystems:

Primary Interface: Mixpanel Class

The Mixpanel class (mixpanel/__init__.py51-551) serves as the main entry point. Applications instantiate this class with a project token and optional configuration, then call methods to track events and update profiles.

Sources: mixpanel/__init__.py51-79 mixpanel/__init__.py562-676 mixpanel/__init__.py678-781

Data Transmission: Consumer Pattern

The consumer architecture implements a pluggable strategy for message transmission:

Consumer Type	Class	Location	Behavior
Immediate	Consumer	mixpanel/__init__.py562	Sends each message immediately via HTTP POST
Batched	BufferedConsumer	mixpanel/__init__.py678	Accumulates up to 50 messages before flushing

The Consumer class (mixpanel/__init__.py562-676) configures HTTP behavior including:

• Connection pooling via requests.Session (mixpanel/__init__.py616)
• Automatic retries with exponential backoff via urllib3.Retry (mixpanel/__init__.py601-614)
• TLS certificate verification control (mixpanel/__init__.py597)
• Regional API support via api_host parameter (mixpanel/__init__.py587)

The BufferedConsumer class (mixpanel/__init__.py678-781) wraps Consumer and maintains per-endpoint buffers that flush when they reach capacity or when explicitly requested.

Sources: mixpanel/__init__.py562-676 mixpanel/__init__.py678-781 mixpanel/__init__.py586-618

Feature Flags: Dual Evaluation Strategies

Feature flag support enables controlled feature rollouts with two complementary evaluation approaches:

Local Provider (mixpanel/flags/local_feature_flags.py):

• Background polling fetches flag definitions from /flags/definitions endpoint
• Client-side evaluation using cached rules (test users, rollout percentage, JSON Logic conditions, variant distribution)
• Optimized for high-frequency flag checks with minimal latency
• Requires LocalFlagsConfig during Mixpanel initialization (mixpanel/__init__.py66-75)

Remote Provider (mixpanel/flags/remote_feature_flags.py):

• Each get_variant_value() call makes synchronous API request to /flags endpoint
• Server-side evaluation ensures always-current flag state
• Suitable for infrequent checks or distributed systems requiring consistency
• Requires RemoteFlagsConfig during Mixpanel initialization (mixpanel/__init__.py77-78)

For detailed feature flag documentation, see Feature Flags.

Sources: mixpanel/__init__.py66-78 mixpanel/__init__.py86-98 mixpanel/flags/local_feature_flags.py1 mixpanel/flags/remote_feature_flags.py1

Key Components and Their Roles

Mixpanel Class Methods

The Mixpanel class exposes methods organized by functionality:

Event Tracking:

• track() (mixpanel/__init__.py100-129): Record events with automatic metadata enrichment
• import_data() (mixpanel/__init__.py131-181): Import historical events (>5 days old) requiring API secret

Profile Management (People Analytics):

• people_set() (mixpanel/__init__.py253-265): Set profile properties
• people_increment() (mixpanel/__init__.py282-296): Increment numeric properties
• people_append() (mixpanel/__init__.py298-313): Append to list properties
• people_track_charge() (mixpanel/__init__.py369-386): Track revenue
• Additional methods: people_set_once(), people_union(), people_unset(), people_remove(), people_delete(), people_clear_charges()

Group Analytics:

• group_set() (mixpanel/__init__.py418-432): Set group profile properties
• group_union() (mixpanel/__init__.py451-468): Merge list properties
• group_remove() (mixpanel/__init__.py483-499): Remove list values
• Additional methods: group_set_once(), group_unset(), group_delete()

Identity Management:

• alias() (mixpanel/__init__.py183-213): Create user alias mapping
• merge() (mixpanel/__init__.py215-251): Merge two distinct_ids

For complete API documentation, see API Reference.

Sources: mixpanel/__init__.py100-532

Automatic Metadata Enrichment

All events and profile updates automatically receive metadata:

Property	Purpose	Generated By
token	Project identifier	self._token (mixpanel/__init__.py114)
time / $time	Timestamp	self._now() (mixpanel/__init__.py80-81)
$insert_id	Deduplication UUID	self._make_insert_id() (mixpanel/__init__.py83-84)
mp_lib	Library identifier	Constant "python" (mixpanel/__init__.py118)
$lib_version	Library version	__version__ (mixpanel/__init__.py33 mixpanel/__init__.py119)

The DatetimeSerializer class (mixpanel/__init__.py37-43) extends json.JSONEncoder to handle Python datetime objects by formatting them as ISO 8601 strings.

Sources: mixpanel/__init__.py113-120 mixpanel/__init__.py37-43 mixpanel/__init__.py80-84

Data Flow: Event Tracking Example

The following diagram illustrates the complete flow when tracking an event:

Key Flow Steps:

1. Metadata Enrichment (mixpanel/__init__.py113-120): The Mixpanel.track() method builds an all_properties dictionary containing the project token, current timestamp, UUID for deduplication, and library metadata.

2. Serialization (mixpanel/__init__.py46-48 mixpanel/__init__.py129): The event dictionary is serialized to JSON using json_dumps() with the configured DatetimeSerializer.

3. Consumer Dispatch (mixpanel/__init__.py129): The serialized message is sent to the consumer's send() method with endpoint 'events'.

4. Transmission:

   • Consumer (mixpanel/__init__.py619-636): Immediately posts to the API endpoint
   • BufferedConsumer (mixpanel/__init__.py724-755): Accumulates messages and flushes when buffer reaches max_size (default 50)

5. HTTP Request (mixpanel/__init__.py638-674): The requests.Session posts with retry logic, TLS verification, and timeout control.

Sources: mixpanel/__init__.py100-129 mixpanel/__init__.py619-676 mixpanel/__init__.py724-780

Error Handling

The library raises MixpanelException (mixpanel/__init__.py553-559) in the following scenarios:

• Invalid endpoint name passed to consumer (mixpanel/__init__.py634 mixpanel/__init__.py744)
• Network errors or connection timeouts (mixpanel/__init__.py664-665)
• Invalid JSON response from server (mixpanel/__init__.py669-670)
• API error status from Mixpanel (mixpanel/__init__.py672-673)
• Feature flags provider accessed without configuration (mixpanel/__init__.py90 mixpanel/__init__.py97)

The urllib3.Retry configuration (mixpanel/__init__.py606-614) automatically retries on:

• Connection errors
• HTTP 5xx status codes
• Default retry limit: 4 attempts with exponential backoff (factor 0.25)

Sources: mixpanel/__init__.py553-559 mixpanel/__init__.py606-674

Context Manager Support

The Mixpanel class implements both synchronous and asynchronous context manager protocols:

Synchronous:

• __enter__() (mixpanel/__init__.py534-535): Returns self
• __exit__() (mixpanel/__init__.py537-541): Cleans up feature flag providers

Asynchronous:

• __aenter__() (mixpanel/__init__.py543-544): Returns self
• __aexit__() (mixpanel/__init__.py546-550): Asynchronously cleans up feature flag providers

This enables resource management patterns:

Sources: mixpanel/__init__.py534-550

Version and Dependencies

• Current Version: 5.1.0 (mixpanel/__init__.py33)
• Python Compatibility: 3.9+ and PyPy
• Core Dependencies:
  • requests (mixpanel/__init__.py23): HTTP client with connection pooling
  • urllib3 (mixpanel/__init__.py25): Low-level HTTP library for retry logic

For testing infrastructure, see Testing. For release history, see Release History.

Sources: mixpanel/__init__.py23-25 mixpanel/__init__.py33 README.md1-7