skawr-analytics 0.1.0

Official SKAWR Analytics SDK for Python — server-side event tracking.

skawr-analytics (Python)

Server-side SDK for SKAWR Analytics. Stateless, pluggable HTTP backend, type-hinted, Python 3.9+.

Install

pip install skawr-analytics
# Or with the default `requests` backend bundled:
pip install 'skawr-analytics[requests]'

Quickstart

from skawr_analytics import Skawr

skawr = Skawr(api_key="ska_xxxxxxxxxxxx")

# In your request handler:
skawr.track(
    "order_placed",
    user_id=request.user.id,
    properties={"value": 99.50, "currency": "SAR"},
)

# On login:
skawr.identify(
    user_id="u_42",
    anonymous_id=request.cookies.get("skawr_anon"),
    properties={"plan": "pro"},
)

Configuration

Skawr(
    api_key="ska_...",                                # required
    endpoint="https://analytics-api.skawr.com",        # override
    timeout=5.0,                                       # seconds
    default_properties={"app": "api", "env": "prod"},  # merged into every event
    http_post=my_async_post,                           # plug in httpx, custom transport, mocks
)

API

skawr.track(
    event_name,
    user_id=None,
    anonymous_id=None,
    session_id=None,
    properties=None,
    timestamp=None,                                    # datetime / float / str / None
    page_url=None,
    referrer_url=None,
    utm_source=None,
    utm_medium=None,
    utm_campaign=None,
) -> int  # HTTP status

skawr.identify(user_id, anonymous_id, properties=None) -> int

timestamp accepts datetime (naive treated as UTC), POSIX float, or ISO-8601 string. Defaults to datetime.now(UTC).

Custom HTTP backend

Pass any callable with signature (url, headers, body) -> response_with_status_code. Useful for:

• httpx — for async or HTTP/2:

  import httpx
  client = httpx.Client(timeout=5.0)
  def post(url, headers, body):
      return client.post(url, headers=headers, content=body)
  Skawr(api_key="...", http_post=post)
  

• Tests — record requests, return canned responses.
• Custom retry / queue — wrap a worker that buffers and retries on failure.

Why server-side?

• Trusted user_ids. Browser clients can't be trusted with revenue events; do those server-side.
• Backend-only events. Webhook receipts, payment confirmations, scheduled jobs.
• Defense-in-depth. Send the same event from both browser and server; dedupe later.

Development

pip install -e '.[dev]'
pytest
ruff check src
mypy src

License

MIT.