tessl/pypi-mixpanel

Official Mixpanel library for Python providing server-side analytics tracking

—

Pending

Overview

Eval results

Files

Group Analytics

Name: tessl/pypi-mixpanel
Author: tessl

Group Analytics functionality enables management of group profiles for organization-level analytics. It supports company profiles, team properties, and group-based segmentation, allowing tracking of attributes and behaviors at the organizational level rather than individual user level.

Capabilities

Group Property Management

Set and manage group profile properties with support for conditional updates and comprehensive property manipulation.

def group_set(group_key: str, group_id: str, properties: dict, meta: dict = None):
    """
    Set properties of a group profile.

    Parameters:
    - group_key (str): The group key, e.g. 'company'
    - group_id (str): The group 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 group_set_once(group_key: str, group_id: str, properties: dict, meta: dict = None):
    """
    Set properties of a group profile if they are not already set.

    Parameters:
    - group_key (str): The group key, e.g. 'company'
    - group_id (str): The group 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 company profile properties
mp.group_set("company", "acme_corp", {
    "name": "Acme Corporation",
    "industry": "Technology",
    "size": "Enterprise",
    "founded": 1999,
    "headquarters": "San Francisco, CA",
    "annual_revenue": 50000000,
    "plan": "enterprise"
})

# Set team properties
mp.group_set("team", "engineering", {
    "department": "Engineering",
    "size": 25,
    "manager": "john_doe",
    "budget": 2000000,
    "tech_stack": "Python"
})

# Set properties only if not already set
mp.group_set_once("company", "startup_xyz", {
    "founding_date": "2024-01-01",
    "initial_funding": 1000000,
    "first_product": "mobile_app"
})

List Property Management

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

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

    Parameters:
    - group_key (str): The group key, e.g. 'company'
    - group_id (str): The group 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 group_remove(group_key: str, group_id: str, properties: dict, meta: dict = None):
    """
    Permanently remove a value from the list associated with a property.

    Parameters:
    - group_key (str): The group key, e.g. 'company'
    - group_id (str): The group to update
    - properties (dict): Properties to remove
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None
    """

Usage Example:

# Add multiple technologies to company's tech stack (no duplicates)
mp.group_union("company", "tech_company", {
    "technologies": ["Python", "JavaScript", "React", "PostgreSQL"],
    "certifications": ["ISO27001", "SOC2"],
    "markets": ["North America", "Europe"]
})

# Remove specific technologies or attributes
mp.group_remove("company", "tech_company", {
    "technologies": "Legacy System",
    "former_employees": "john_smith"
})

# Union team skills
mp.group_union("team", "data_science", {
    "skills": ["machine_learning", "statistics", "python"],
    "tools": ["jupyter", "pandas", "tensorflow"]
})

Property Removal

Remove properties entirely from group profiles.

def group_unset(group_key: str, group_id: str, properties: list, meta: dict = None):
    """
    Permanently remove properties from a group profile.

    Parameters:
    - group_key (str): The group key, e.g. 'company'
    - group_id (str): The group to update
    - properties (list): Property names to remove
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None
    """

Usage Example:

# Remove outdated properties from company profile
mp.group_unset("company", "evolving_startup", [
    "old_website",
    "former_ceo",
    "legacy_product",
    "outdated_valuation"
])

# Remove temporary team properties
mp.group_unset("team", "project_alpha", [
    "temp_budget",
    "prototype_url"
])

Group Profile Deletion

Permanently delete group profiles and all associated data.

def group_delete(group_key: str, group_id: str, meta: dict = None):
    """
    Permanently delete a group profile.

    Parameters:
    - group_key (str): The group key, e.g. 'company'
    - group_id (str): The group to delete
    - meta (dict, optional): Overrides Mixpanel special properties

    Returns:
    None

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

Usage Example:

# Delete company profile (acquisition, closure, etc.)
mp.group_delete("company", "closed_company")

# Delete project team after completion
mp.group_delete("team", "project_finished")

Generic Group Updates

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

def group_update(message: dict, meta: dict = None):
    """
    Send a generic group profile update.

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

    Returns:
    None

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

Usage Example:

# Custom group update using the generic method
mp.group_update({
    '$group_key': 'company',
    '$group_id': 'acme_corp',
    '$set': {'custom_field': 'value'},
    '$union': {'tags': ['enterprise', 'verified']}
})

# Advanced usage with multiple operations
mp.group_update({
    '$group_key': 'team',
    '$group_id': 'engineering',
    '$set': {'lead': 'new_manager'},
    '$unset': ['temp_project'],
    '$remove': {'former_members': 'departed_employee'}
})

Group Analytics Patterns

Company Profile Management

Track company-level attributes and organizational changes over time.

from mixpanel import Mixpanel

mp = Mixpanel("YOUR_PROJECT_TOKEN")

# Initial company setup
mp.group_set("company", "tech_startup_123", {
    "name": "Tech Startup Inc",
    "industry": "SaaS",
    "stage": "Series A",
    "employee_count": 50,
    "founded": 2020,
    "primary_market": "SMB",
    "monthly_recurring_revenue": 100000
})

# Update company metrics monthly
mp.group_set("company", "tech_startup_123", {
    "employee_count": 65,
    "monthly_recurring_revenue": 150000,
    "last_updated": "2024-02-01"
})

# Track company growth milestones
mp.group_union("company", "tech_startup_123", {
    "milestones": ["Series A completed", "50 employees", "$1M ARR"],
    "awards": ["Best Startup 2024"]
})

Team and Department Tracking

Manage team-level properties and project assignments.

# Set up engineering team profile
mp.group_set("team", "backend_engineering", {
    "department": "Engineering",
    "focus_area": "Backend Infrastructure",
    "team_lead": "alice_johnson",
    "size": 8,
    "budget_allocated": 800000,
    "primary_technologies": "Python, PostgreSQL, Redis"
})

# Track team projects and responsibilities
mp.group_union("team", "backend_engineering", {
    "current_projects": ["API v2", "Database Migration", "Performance Optimization"],
    "completed_projects": ["Authentication System", "Logging Infrastructure"]
})

# Update team composition
mp.group_set("team", "backend_engineering", {
    "size": 10,
    "new_hires": 2,
    "last_team_update": "2024-01-15"
})

Multi-Level Group Hierarchies

Manage relationships between different group types and levels.

# Company level
mp.group_set("company", "global_corp", {
    "name": "Global Corporation",
    "type": "Enterprise",
    "regions": "Global"
})

# Division level
mp.group_set("division", "north_america", {
    "parent_company": "global_corp",
    "region": "North America",
    "revenue_target": 10000000,
    "employee_count": 200
})

# Department level
mp.group_set("department", "na_engineering", {
    "parent_division": "north_america",
    "department_type": "Engineering",
    "budget": 2000000,
    "headcount": 50
})

Best Practices

Group Key Strategy

Use consistent group_key values across your application ("company", "team", "department")
Choose descriptive group keys that clearly indicate the organizational level
Maintain a standardized taxonomy for group types

Group ID Management

Use stable, unique identifiers for group_id values
Avoid using changing values like company names as group IDs
Consider using UUIDs or internal IDs for permanent group identification

Property Organization

Structure group properties to support analytics and segmentation needs
Use consistent naming conventions across all group types
Include relevant metadata like update timestamps and data sources

Hierarchical Relationships

Use properties to establish relationships between different group levels
Maintain references to parent/child groups when applicable
Consider how group hierarchies will be used in analytics and reporting

Data Maintenance

Regularly update group properties to reflect organizational changes
Remove outdated properties and delete obsolete group profiles
Implement processes for handling organizational restructuring

Error Handling

Group operations may fail due to network issues or API restrictions:

from mixpanel import Mixpanel, MixpanelException

mp = Mixpanel("YOUR_PROJECT_TOKEN")

try:
    mp.group_set("company", "startup_abc", {
        "funding_round": "Series B",
        "valuation": 50000000
    })
except MixpanelException as e:
    print(f"Group update failed: {e}")
    # Implement retry logic or fallback handling

Install with Tessl CLI