ripples 0.1.0

Official Python SDK for Ripples.sh — server-side event tracking

Ripples Python SDK

Server-side Python SDK for Ripples.sh analytics.

Install

pip install ripples

Set your secret key:

RIPPLES_SECRET_KEY=priv_your_secret_key

Usage

from ripples import Ripples

ripples = Ripples()

ripples.revenue(49.99, "user_123")
ripples.signup("user_123", email="[e-mail]")
ripples.track("created a budget", "user_123", area="budgets")
ripples.identify("user_123", email="[e-mail]")

That's it. Events are batched and sent automatically when the process exits.

Track product usage

Call track() when a user does something meaningful. Ripples auto-detects activation (first occurrence per user), computes adoption rates, and correlates with retention and payment.

ripples.track("created a budget", "user_123", area="budgets")
ripples.track("shared a list", "user_123", area="sharing", via="link")
ripples.track("exported report", "user_123", area="reports", format="csv")

Use area to group actions into product areas. Use activated=True to mark the specific moment a user activates:

ripples.track("added transaction", "user_123", area="transactions", activated=True)

Track revenue

ripples.revenue(49.99, "user_123")

Any extra keyword argument becomes a custom property:

ripples.revenue(49.99, "user_123",
    email="[e-mail]",
    currency="EUR",
    transaction_id="txn_abc123",
    plan="annual",
    coupon="WELCOME20",
)

Refunds are negative revenue:

ripples.revenue(-29.99, "user_123", transaction_id="txn_abc123")

Track signups

ripples.signup("user_123",
    email="[e-mail]",
    name="Jane Smith",
    referral="twitter",
    plan="free",
)

Identify users

Update user traits at any time:

ripples.identify("user_123",
    email="[e-mail]",
    name="Jane Smith",
    company="Acme Inc",
    role="admin",
)

Error handling

from ripples import RipplesError

try:
    ripples.revenue(49.99, "user_123")
except RipplesError as e:
    print(e)

By default, errors during flush are swallowed so your app is never disrupted. Use on_error to log them:

ripples = Ripples(on_error=lambda e: print(f"Ripples error: {e}"))

Configuration

ripples = Ripples(
    "priv_explicit_key",
    base_url="https://your-domain.com/api",
    timeout=10,
    max_queue_size=50,
)

Or via environment variables:

RIPPLES_SECRET_KEY=priv_your_secret_key
RIPPLES_URL=https://your-domain.com/api

Flush manually

Events are flushed automatically at exit. For long-running processes or CLI scripts, call flush() explicitly:

ripples.flush()

Custom HTTP client

Subclass and override _post():

class MyRipples(Ripples):
    def _post(self, path, data):
        # your custom implementation
        pass

Requirements

• Python 3.9+
• requests

License

MIT