Skip to main content

flagstone-sdk

Python SDK for Flagstone feature flags.

The client downloads your project's flag configuration once and evaluates flags locally, in your application's process. A flag check is a dictionary lookup and a few comparisons, with no network call, so it is safe to use in hot paths. The client keeps its copy up to date in the background, and keeps working with the last configuration it had if the Flagstone server is unreachable.

Install

pip install flagstone-sdk

Requires Python 3.10 or newer. The only dependency is httpx.

Quickstart

from flagstone_sdk import FlagClient

client = FlagClient(
    sdk_key="fs_...",                      # from your project's "SDK keys" page
    base_url="https://flags.example.com",  # where your Flagstone server runs
)

user = {"id": "user-123", "plan": "pro", "country": "IN"}

if client.is_enabled("new-dashboard", user):
    show_new_dashboard()

# Record that this user converted, for the flag's experiment results.
client.track_conversion("new-dashboard", user)

client.close()  # on shutdown

Create one client when your application starts and share it. Creating a client fetches the configuration and starts a background refresh thread.

Users and targeting

A user is a plain dict. "id" is required: it decides which side of a percentage rollout the user falls on, and the same id always gets the same answer. Any other keys (plan, country, email, ...) are attributes that targeting rules can match on. Rules and rollouts are configured in the Flagstone admin UI.

API

Method Returns
is_enabled(flag_key, user) True if the variation served to this user is truthy. Records an exposure event. Unknown flags return False.
get_variation(flag_key, user) Index of the variation served to this user. Does not record an event. Unknown flags return 0.
track_conversion(flag_key, user) Records a conversion for the variation this user is served.
close() Stops background refreshes and releases the HTTP connection.

Options

Argument Default Meaning
sdk_key required The project's SDK key.
base_url http://localhost:8000 URL of your Flagstone server.
poll_interval 30 Seconds between configuration refreshes when polling.
use_sse False Receive changes over Server-Sent Events instead of polling. Changes arrive within a second, but the connection must be allowed through any proxies in between.
cache_path ~/.flagstone_cache.json Where the last configuration is saved, so the client can start even if the server is down. None disables the cache.
flush_interval 10 Seconds between sending batched events. Events are also sent every 100 events.

Keep SDK keys on the server

The client downloads the full configuration of the key's project, including targeting rules and the values they compare against. Use the SDK only in server-side code. Never put an SDK key in a browser, mobile app or any code your users can read.

Good to know

  • Events are delivered on a best-effort basis: if sending a batch fails, that batch is dropped.
  • close() does not send events that are still buffered; up to flush_interval seconds of events can be lost at shutdown.

License

MIT. The full license text is included in the package.

Metadata

Release files for flagstone-sdk 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flagstone-sdk 0.1.0
File Size Uploaded Provenance Actions
flagstone_sdk-0.1.0.tar.gz 8.4 kB With provenance Details for flagstone_sdk-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flagstone-sdk 0.1.0
File Interpreter ABI Platform Actions
flagstone_sdk-0.1.0-py3-none-any.whl Python 3 none any Details for flagstone_sdk-0.1.0-py3-none-any.whl

Total release size: 16.9 kB

Release files / flagstone_sdk-0.1.0.tar.gz

Download URL flagstone_sdk-0.1.0.tar.gz
Size 8.4 kB
Tags Source
SHA-256 checksum
How to use checksums
df545bafba06880119834bcb56acf571de92bdfe008efae9498d9af874f2b2c3
BLAKE2b-256 checksum
How to use checksums
e3f4f0d9af3310709985a7cd2599f20a1a78aae5efcd9c006c16e1b621eac808
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / flagstone_sdk-0.1.0-py3-none-any.whl

Download URL flagstone_sdk-0.1.0-py3-none-any.whl
Size 8.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d34477f63cbbd79ee04cc4003f7709f05e65f9d56defd7e76f8da02e112ee610
BLAKE2b-256 checksum
How to use checksums
afdcc7b8b54fde5c776aa918c3157ce574cce588df75b05d0ab91255628ceaaa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for flagstone-sdk 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for flagstone_sdk-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page