tessl/pypi-mixpanel

Official Mixpanel library for Python providing server-side analytics tracking

—

Pending

Overview

Eval results

Files

People Analytics

Name: tessl/pypi-mixpanel
Author: tessl

People Analytics functionality enables comprehensive user profile management with property operations, list management, and revenue tracking. All operations create profiles if they don't exist and support extensive property manipulation.

Capabilities

Profile Property Management

Set and manage user profile properties with support for conditional updates and one-time property setting.

def people_set(distinct_id: str, properties: dict, meta: dict = None):
    """
    Set properties of a people record.

    Parameters:
    - distinct_id (str): The profile to update
    - properties (dict): Properties to set
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

    Note: If the profile does not exist, creates a new profile with these properties.
    """

def people_set_once(distinct_id: str, properties: dict, meta: dict = None):
    """
    Set properties of a people record if they are not already set.

    Parameters:
    - distinct_id (str): The profile to update
    - properties (dict): Properties to set
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

    Note: Properties that already exist will not be overwritten. Creates profile if it doesn't exist.
    """

Usage Example:

from mixpanel import Mixpanel

mp = Mixpanel("YOUR_PROJECT_TOKEN")

# Set user profile properties
mp.people_set("user_123", {
    "$first_name": "John",
    "$last_name": "Doe",
    "$email": "john@example.com",
    "$phone": "+1234567890",
    "plan": "premium",
    "signup_date": "2024-01-15",
    "preferences": "email_notifications"
})

# Set properties only if not already set
mp.people_set_once("user_123", {
    "first_login": "2024-01-15",
    "signup_source": "organic",
    "initial_plan": "free"
})

Numerical Operations

Increment or decrement numerical properties with support for multiple properties in a single operation.

def people_increment(distinct_id: str, properties: dict, meta: dict = None):
    """
    Increment/decrement numerical properties of a people record.

    Parameters:
    - distinct_id (str): The profile to update
    - properties (dict): Properties to increment/decrement; values should be numeric
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

    Note: Nonexistent properties default to zero. Negative values decrement the property.
    """

Usage Example:

# Increment user engagement metrics
mp.people_increment("user_123", {
    "page_views": 1,
    "session_count": 1,
    "total_time_spent": 300,  # seconds
    "feature_usage": 1
})

# Decrement credits or points
mp.people_increment("user_456", {
    "credits_remaining": -10,
    "points_balance": -50
})

List Property Management

Manage list-style properties with append, union, and remove operations for handling collections of values.

def people_append(distinct_id: str, properties: dict, meta: dict = None):
    """
    Append to the list associated with a property.

    Parameters:
    - distinct_id (str): The profile to update
    - properties (dict): Properties to append
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

    Note: Appending to nonexistent properties results in a list with a single element.
    """

def people_union(distinct_id: str, properties: dict, meta: dict = None):
    """
    Merge the values of a list associated with a property.

    Parameters:
    - distinct_id (str): The profile to update
    - properties (dict): Properties to merge
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

    Note: Duplicate values are ignored when merging lists.
    """

def people_remove(distinct_id: str, properties: dict, meta: dict = None):
    """
    Permanently remove a value from the list associated with a property.

    Parameters:
    - distinct_id (str): The profile to update
    - properties (dict): Properties to remove
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None
    """

Usage Example:

# Append items to user's lists
mp.people_append("user_123", {
    "favorite_categories": "electronics",
    "purchased_items": "laptop_pro_001",
    "viewed_pages": "/product/smartphone"
})

# Union multiple values (no duplicates)
mp.people_union("user_123", {
    "interests": ["technology", "gaming", "music"],
    "tags": ["vip", "early_adopter"]
})

# Remove specific values from lists
mp.people_remove("user_123", {
    "cart_items": "item_to_remove",
    "notifications": "promotional_emails"
})

Property Removal

Remove properties entirely from user profiles.

def people_unset(distinct_id: str, properties: list, meta: dict = None):
    """
    Permanently remove properties from a people record.

    Parameters:
    - distinct_id (str): The profile to update
    - properties (list): Property names to remove
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None
    """

Usage Example:

# Remove specific properties from user profile
mp.people_unset("user_123", [
    "temp_property",
    "outdated_preference",
    "old_email"
])

Revenue Tracking

Track revenue and transaction data with comprehensive transaction history management.

def people_track_charge(distinct_id: str, amount: float, properties: dict = None, meta: dict = None):
    """
    Track a charge on a people record.

    Parameters:
    - distinct_id (str): The profile with which to associate the charge
    - amount (float): Number of dollars charged
    - properties (dict, optional): Extra properties related to the transaction
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

    Note: Charges appear in the Mixpanel revenue report.
    """

def people_clear_charges(distinct_id: str, meta: dict = None):
    """
    Permanently clear all charges on a people record.

    Parameters:
    - distinct_id (str): The profile whose charges will be cleared
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None
    """

Usage Example:

# Track a purchase with transaction details
mp.people_track_charge("user_123", 99.99, {
    "product_name": "Premium Plan",
    "plan_duration": "monthly",
    "currency": "USD",
    "payment_method": "credit_card",
    "transaction_id": "txn_abc123"
})

# Track refund (negative amount)
mp.people_track_charge("user_456", -29.99, {
    "refund_reason": "customer_request",
    "original_transaction": "txn_def456"
})

# Clear all transaction history
mp.people_clear_charges("user_789")

Profile Deletion

Permanently delete user profiles and all associated data.

def people_delete(distinct_id: str, meta: dict = None):
    """
    Permanently delete a people record.

    Parameters:
    - distinct_id (str): The profile to delete
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

    Note: This action is irreversible and will remove all profile data.
    """

Usage Example:

# Delete user profile (GDPR compliance, account deletion, etc.)
mp.people_delete("user_to_delete")

Generic Profile Updates

Send custom profile update messages for advanced use cases or new Mixpanel features.

def people_update(message: dict, meta: dict = None):
    """
    Send a generic update to Mixpanel people analytics.

    Parameters:
    - message (dict): The message to send, must include '$distinct_id' and operation keys like '$set', '$add', etc.
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

    Note: Callers are responsible for formatting the message according to Mixpanel's user profiles documentation.
    The message should follow the structure: {'$distinct_id': 'user_id', '$set': {...}, '$token': 'auto-added', '$time': 'auto-added'}
    """

Usage Example:

# Custom profile update using the generic method
mp.people_update({
    '$distinct_id': 'user_123',
    '$set': {'custom_field': 'value'},
    '$add': {'score': 10}
})

# Advanced usage with multiple operations
mp.people_update({
    '$distinct_id': 'user_456',
    '$set': {'status': 'premium'},
    '$unset': ['temp_field'],
    '$append': {'actions': 'upgraded'}
})

Best Practices

Profile Management

Use consistent distinct_id values across events and profile updates
Leverage Mixpanel's special properties (prefixed with $) for enhanced functionality
Set meaningful profile properties that aid in user segmentation and analysis