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 toflush_intervalseconds 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.