piano-analytics-client 1.0.0

Python SDK for Piano Analytics data collection

Piano Analytics Python Client

A Python SDK for sending analytics events to Piano Analytics.

Installation

uv add piano-analytics-client

Or with pip:

pip install piano-analytics-client

Quick Start

Synchronous Usage

from piano_analytics import PianoAnalytics

# Initialize the client
pa = PianoAnalytics(
    site_id=123456789,
    collect_domain="https://your-domain.pa-cd.com"
)

# Send a page view event
pa.send_event("page.display", {
    "page": "homepage",
    "page_chapter1": "home"
})

# Send a click event
pa.send_event("click.action", {
    "click": "signup_button",
    "click_chapter1": "header"
})

# Close the client when done
pa.close()

Using Context Manager (Recommended)

from piano_analytics import PianoAnalytics

with PianoAnalytics(site_id=123456789, collect_domain="https://...") as pa:
    pa.send_event("page.display", {"page": "checkout"})

Asynchronous Usage

import asyncio
from piano_analytics import AsyncPianoAnalytics

async def main():
    async with AsyncPianoAnalytics(
        site_id=123456789,
        collect_domain="https://your-domain.pa-cd.com"
    ) as pa:
        # Send events asynchronously
        await pa.send_event("page.display", {"page": "product_page"})

        # Send multiple events concurrently
        await asyncio.gather(
            pa.send_event("click.action", {"click": "add_to_cart"}),
            pa.send_event("click.action", {"click": "view_details"})
        )

asyncio.run(main())

Configuration Options

from piano_analytics import PianoAnalytics

pa = PianoAnalytics(
    site_id=123456789,                    # Required: Your site ID
    collect_domain="https://...",          # Required: Collection endpoint
    visitor_id="custom-uuid",              # Optional: Custom visitor ID (auto-generated if not provided)
    timeout=30.0,                          # Optional: Request timeout in seconds (default: 10)
    max_retries=5,                         # Optional: Retry attempts (default: 3)
    user_agent="MyApp/1.0"                 # Optional: Custom User-Agent
)

Using Event Helpers

The SDK provides convenient factory methods for standard events:

from piano_analytics import PianoAnalytics
from piano_analytics.events import Event

with PianoAnalytics(site_id=123, collect_domain="https://...") as pa:
    # Using factory methods
    events = [
        Event.page_display("homepage", page_chapter1="home"),
        Event.click_action("signup", click_chapter1="header"),
        Event.search_display(ise_keyword="python", ise_page=1),
    ]
    pa.send_events(events)

Batch Sending

Send multiple events in a single request:

pa.send_events([
    {"name": "page.display", "data": {"page": "home"}},
    {"name": "click.action", "data": {"click": "menu"}},
    {"name": "click.navigation", "data": {"click": "products"}}
])

Error Handling

from piano_analytics import PianoAnalytics
from piano_analytics.exceptions import (
    ValidationError,
    NetworkError,
    APIError
)

with PianoAnalytics(site_id=123, collect_domain="https://...") as pa:
    try:
        pa.send_event("page.display", {"page": "home"})
    except ValidationError as e:
        print(f"Invalid event data: {e}")
    except NetworkError as e:
        print(f"Network issue: {e}")
    except APIError as e:
        print(f"API error: {e.status_code} - {e.message}")

Standard Events

Event	Description
page.display	Track page views
click.action	Track user interactions
click.navigation	Track navigation clicks
click.download	Track file downloads
click.exit	Track exit links
internal_search_result.display	Track search results
internal_search_result.click	Track search result clicks

Development

# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Run type checking
uv run pyright

License

MIT