Skip to content
Peekbird

Python SDK

Feature flags and "In your code" experiments on your server, decided the same way the browser decides them, and events sent from it. It needs Python 3.9 or newer and nothing else, and works with Django, Flask, FastAPI and any other framework.

Install

pip install https://peekbird.com/sdk/peekbird-python.tar.gz

Then make one client per process, when your server starts, with a key from Site settings → Server keys:

import os
from peekbird import Peekbird

# Once, when your server starts. The key is in Site settings → Server keys.
peekbird = Peekbird(os.environ["PEEKBIRD_KEY"])

The client downloads your flags and experiments in a background thread, then decides locally, checks for changes every 30 seconds and sends events every 5. Until the first download, flags are off and experiments answer None. A script that decides straight away can wait:

peekbird.ready(timeout=5)  # True once the flags and experiments are loaded.

Decide

# In a view: your framework's cookies and headers.
visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=str(request.url))
if peekbird.variation("one-page-checkout", visitor) == "one-page":
    ...  # Show the new version.
# Then, on your response:
for name, value, attrs in visitor.cookies_to_set:
    response.set_cookie(name, value, **attrs)
visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=str(request.url))
if peekbird.flag("new-search", visitor):
    ...  # The new feature.
  • variation(key, visitor) answers the variation's key, or None when the visitor isn't in the test. It counts them in the test the first time: ask where the variations start to differ.
  • flag(key, visitor) answers True or False. A flag that doesn't exist is off. Each answer is noted once per visitor, for the Feature flag filter.

Set the cookies

After deciding, set visitor.cookies_to_set on your response: the visitor's ID when the SDK made it, and their variations, so the snippet in the page shows the same ones. Each is a (name, value, attrs) tuple whose attrs fit Django's, Flask's and Starlette's set_cookie:

for name, value, attrs in visitor.cookies_to_set:
    response.set_cookie(name, value, **attrs)

For a raw WSGI or ASGI response, visitor.set_cookie_headers has them as ready Set-Cookie values. The cookies are Secure unless the page's address is plain http: behind a proxy that ends HTTPS, make sure your framework sees the https address (Django's SECURE_PROXY_SSL_HEADER, Werkzeug's ProxyFix, uvicorn's --proxy-headers).

Send events

peekbird.track(visitor, "purchase", revenue=49.9, currency="USD", order_id="ORDER-123")

revenue is an amount of money with its currency, value any other amount a goal adds up, and an order_id is counted once. Other keyword arguments go in the event's properties: text, numbers or true/false. peekbird.identify(visitor, id=..., email=..., name=...) says who the visitor is.

To count an order that a webhook confirms later, keep the visitor's ID with the order:

# At checkout, keep visitor.id with the order. When the payment webhook confirms it:
visitor = peekbird.visitor(order.peekbird_visitor_id)
peekbird.track(visitor, "purchase", revenue=order.total, currency=order.currency, order_id=order.number)

The visitor

peekbird.visitor(cookies=..., headers=..., url=...) reads a request: cookies as a dict or the Cookie header, headers as any mapping or a WSGI environ, and the page's full address. It reads User-Agent, Accept-Language, Referer, Sec-GPC, and behind Cloudflare CF-IPCountry and CF-Region-Code. Or describe a visitor you know:

visitor = peekbird.visitor(
    "user-42",                                 # your own ID for someone signed in: the same answer on every device
    attributes={"plan": "pro", "ltv": 250},
    country="US",
    region_code="TX",
    time_zone="America/Chicago",
)

Facts you pass win over the headers. What else a server knows, and what it can't, is on Server-side SDKs. On Windows, install the tzdata package for time zones; without it every time zone counts as UTC.

Django

# views.py
from django.shortcuts import render

from .peekbird_client import peekbird  # Peekbird(os.environ["PEEKBIRD_KEY"]), made once


def checkout(request):
    visitor = peekbird.visitor(
        cookies=request.COOKIES,
        headers=request.headers,
        url=request.build_absolute_uri(),
    )
    one_page = peekbird.variation("one-page-checkout", visitor) == "one-page"
    response = render(request, "checkout.html", {"one_page": one_page})
    for name, value, attrs in visitor.cookies_to_set:
        response.set_cookie(name, value, **attrs)
    return response

Flask

@app.route("/checkout")
def checkout():
    visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=request.url)
    one_page = peekbird.variation("one-page-checkout", visitor) == "one-page"
    response = make_response(render_template("checkout.html", one_page=one_page))
    for name, value, attrs in visitor.cookies_to_set:
        response.set_cookie(name, value, **attrs)
    return response

FastAPI

@app.get("/checkout")
def checkout(request: Request, response: Response):
    visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=str(request.url))
    one_page = peekbird.variation("one-page-checkout", visitor) == "one-page"
    for name, value, attrs in visitor.cookies_to_set:
        response.set_cookie(name, value, **attrs)
    return {"one_page": one_page}

Deciding and tracking don't touch the network, so they're fine in async def endpoints too. When an endpoint returns its own response object, set the cookies on that one.

Consent

Where your site waits for consent (see Consent), the SDK follows the same rule as the snippet. For a visitor who hasn't agreed, it sets no cookies and sends no events, and experiments answer None. Flags are still answered, since deciding one stores and sends nothing. Tell it what your own banner knows with consent=True.

Options

peekbird = Peekbird(
    os.environ["PEEKBIRD_KEY"],
    refresh_interval=30,  # seconds between checks for changed flags and experiments; 0: load once
    flush_interval=5,     # seconds between sends of waiting events
    timeout=5,            # seconds a request to Peekbird may take
    on_error=log_it,      # a function that gets a PeekbirdError: never raised
)
  • flush() sends what's waiting now; close() stops the background thread and sends it. The client also works as a context manager.
  • In AWS Lambda or Google Cloud Functions, call peekbird.flush() before the function returns: the process may be frozen afterwards.
  • One client serves every thread. With servers that fork after loading your app (gunicorn --preload, uWSGI), each worker starts its own background thread.
  • Nothing the SDK does raises into your code. Without on_error, each kind of problem is logged once on the peekbird logger.

See what your visitors see.

Start free in a few minutes: one snippet, every feature. Move to a bigger plan when you need more tracked visits.