Python SDK

The entrolytics package provides server-side analytics tracking for Python applications with first-class support for Django, FastAPI, and Flask.

Installation

pip install entrolytics

pip install entrolytics[django]

pip install entrolytics[fastapi]

pip install entrolytics[flask]

pip install entrolytics[all]

Quick Start

Install the Package

pip install entrolytics

Create a Client

from entrolytics import Entrolytics

client = Entrolytics(api_key="ent_xxx")

Track Events

# Track custom event
client.track(
    website_id="your-website-id",
    event="purchase",
    data={
        "revenue": 99.99,
        "currency": "USD",
        "product": "pro-plan"
    }
)

# Track page view
client.page_view(
    website_id="your-website-id",
    url="/pricing",
    referrer="https://google.com"
)

# Identify user
client.identify(
    website_id="your-website-id",
    user_id="user_456",
    traits={
        "email": "user@example.com",
        "plan": "pro"
    }
)

Async Support

Use AsyncEntrolytics for async/await applications:

from entrolytics import AsyncEntrolytics

async def track_purchase():
    async with AsyncEntrolytics(api_key="ent_xxx") as client:
        await client.track(
            website_id="abc123",
            event="purchase",
            data={"revenue": 99.99, "currency": "USD"}
        )

# Or without context manager
client = AsyncEntrolytics(api_key="ent_xxx")
await client.track(website_id="abc123", event="signup")
await client.close()

Framework Integrations

Django Setup

Configure Settings

Add to your settings.py:

settings.py

INSTALLED_APPS = [
    # ... your apps
]

MIDDLEWARE = [
    'entrolytics.django.EntrolyticsMiddleware',  # Add for auto page tracking
    # ... other middleware
]

ENTROLYTICS = {
    'WEBSITE_ID': 'your-website-id',
    'API_KEY': 'ent_xxx',
    'TRACK_ADMIN': False,  # Skip admin pages
    'EXCLUDED_PATHS': ['/health', '/api/internal/'],
}

Track Events in Views

views.py

from entrolytics.django import track, identify
from django.http import JsonResponse
from django.contrib.auth.decorators import login_required

def purchase_view(request):
    # Process purchase...
    
    # Track event
    track('purchase', {
        'revenue': 99.99,
        'currency': 'USD',
        'product_id': request.POST.get('product_id')
    }, request=request)
    
    return JsonResponse({'status': 'success'})

@login_required
def profile_view(request):
    # Identify user
    identify(str(request.user.pk), {
        'email': request.user.email,
        'username': request.user.username,
        'plan': request.user.profile.subscription_plan
    })
    
    return render(request, 'profile.html')

Class-Based Views

from django.views import View
from entrolytics.django import track

class PurchaseView(View):
    def _post(self, request):
        # Process purchase...
        
        track('purchase', {
            'amount': amount,
            'currency': 'USD'
        }, request=request)
        
        return JsonResponse({'success': True})

FastAPI Setup

Add Middleware

For automatic page view tracking:

main.py

from fastapi import FastAPI
from entrolytics.fastapi import EntrolyticsMiddleware

app = FastAPI()

app.add_middleware(
    EntrolyticsMiddleware,
    website_id="your-website-id",
    api_key="ent_xxx",
    excluded_paths=["/health", "/metrics"]
)

Use Dependency Injection

main.py

from fastapi import FastAPI, Depends, Request
from entrolytics.fastapi import get_entrolytics, EntrolyticsTracker

app = FastAPI()

# Create tracker dependency
tracker = get_entrolytics(
    website_id="your-website-id",
    api_key="ent_xxx"
)

@app.post("/purchase")
async def purchase(
    request: Request,
    tracker: EntrolyticsTracker = Depends(tracker)
):
    # Track purchase event
    await tracker.track("purchase", {
        "revenue": 99.99,
        "currency": "USD"
    })
    
    return {"status": "success"}

@app.post("/login")
async def login(
    user_id: str,
    tracker: EntrolyticsTracker = Depends(tracker)
):
    # Identify user
    await tracker.identify(user_id, {
        "plan": "pro",
        "email": "user@example.com"
    })
    
    return {"status": "success"}

Background Tasks

from fastapi import BackgroundTasks

@app.post("/signup")
async def signup(
    background_tasks: BackgroundTasks,
    tracker: EntrolyticsTracker = Depends(tracker)
):
    # Track in background
    background_tasks.add_task(
        tracker.track,
        "signup",
        {"plan": "free"}
    )
    
    return {"status": "success"}

Flask Setup

Configure Extension

app.py

from flask import Flask
from entrolytics.flask import FlaskEntrolytics

app = Flask(__name__)
app.config['ENTROLYTICS_WEBSITE_ID'] = 'your-website-id'
app.config['ENTROLYTICS_API_KEY'] = 'ent_xxx'
app.config['ENTROLYTICS_AUTO_TRACK'] = True  # Auto page tracking

entrolytics = FlaskEntrolytics(app)

Track in Routes

routes.py

from flask import request, jsonify
from entrolytics.flask import track, identify

@app.route('/purchase', methods=['POST'])
def purchase():
    # Track purchase
    track('purchase', {
        'revenue': 99.99,
        'currency': 'USD'
    })
    
    return jsonify({'status': 'success'})

@app.route('/login', methods=['POST'])
def login():
    # After authentication...
    identify(user.id, {
        'email': user.email,
        'plan': user.subscription
    })
    
    return jsonify({'status': 'success'})

Before/After Request Hooks

@app.before_request
def before_request():
    # Track page view for specific routes
    if request.endpoint in ['product_page', 'pricing']:
        track('page_view', {
            'path': request.path,
            'method': request.method
        })

API Reference

Entrolytics Client

class Entrolytics:
    def __init__(
        self,
        api_key: str,
        host: str = "https://cloud.entrolytics.click",
        timeout: float = 10.0
    )

Methods

track(website_id, event, data=None, **kwargs)

Track a custom event.

Parameter	Type	Required	Description
`website_id`	`str`	Yes	Website ID
`event`	`str`	Yes	Event name
`data`	`dict`	No	Event data
`url`	`str`	No	Page URL
`referrer`	`str`	No	Referrer URL
`user_id`	`str`	No	User ID
`session_id`	`str`	No	Session ID
`user_agent`	`str`	No	User agent
`ip_address`	`str`	No	Client IP

page_view(website_id, url, **kwargs)

Track a page view.

Parameter	Type	Required	Description
`website_id`	`str`	Yes	Website ID
`url`	`str`	Yes	Page URL
`referrer`	`str`	No	Referrer URL
`title`	`str`	No	Page title
`user_id`	`str`	No	User ID

identify(website_id, user_id, traits=None)

Identify a user.

Parameter	Type	Required	Description
`website_id`	`str`	Yes	Website ID
`user_id`	`str`	Yes	User ID
`traits`	`dict`	No	User traits

Advanced Usage

Type Hints

Full type hint support:

from typing import Dict, Optional
from entrolytics import Entrolytics

client: Entrolytics = Entrolytics(api_key="ent_xxx")

event_data: Dict[str, any] = {
    "revenue": 99.99,
    "currency": "USD"
}

client.track(
    website_id="abc123",
    event="purchase",
    data=event_data,
    user_id="user_123"
)

# Type hints for traits
traits: Dict[str, str] = {
    "email": "user@example.com",
    "plan": "pro"
}

client.identify(
    website_id="abc123",
    user_id="user_123",
    traits=traits
)

Requirements

Python >= 3.9
httpx >= 0.25.0

Optional Dependencies

Django >= 4.0 (for Django integration)
FastAPI >= 0.100.0, Starlette >= 0.27.0 (for FastAPI integration)
Flask >= 2.0 (for Flask integration)

Features

✅ Synchronous and async support
✅ Django middleware and helpers
✅ FastAPI middleware and dependency injection
✅ Flask extension
✅ Type hints with mypy support
✅ Comprehensive error handling
✅ Request context extraction
✅ Custom HTTP client support
✅ Self-hosted instance support

Python SDK

Error Handling

Custom HTTP Client

Batch Tracking

Request Context

Self-Hosted Instance

Table of Contents