configdirector-server-sdk 0.2.0__tar.gz

configdirector_server_sdk-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+build/
+dist/
+
+.venv/
+venv/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Sample apps and the profiling harness resolve the SDK from a local path, so their locks are
+# not portable.
+samples/*/uv.lock
+profiling/uv.lock
+.env
+
+.DS_Store
+.idea/
+*.swp
+.claude
+.vscode

configdirector_server_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ConfigDirector
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

configdirector_server_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: configdirector-server-sdk
+Version: 0.2.0
+Summary: Python server SDK for ConfigDirector. ConfigDirector is a remote configuration and feature flag service.
+Project-URL: Homepage, https://www.configdirector.com
+Project-URL: Documentation, https://docs.configdirector.com/sdks/server/python
+Project-URL: Repository, https://github.com/ConfigDirector/python-server-sdk
+Project-URL: Support, https://www.configdirector.com/support
+Author: ConfigDirector
+License-Expression: MIT
+License-File: LICENSE
+Keywords: config,configdirector,configuration,feature flag,feature switch,feature toggle,remote config,remote configuration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: urllib3<3,>=2.7
+Description-Content-Type: text/markdown
+
+# ConfigDirector Python SDK
+
+This is the Python server SDK for [ConfigDirector](https://www.configdirector.com).
+
+## Documentation
+
+Refer to the [official documentation for the Python SDK](https://docs.configdirector.com/sdks/server/python).
+
+There is also [a quickstart guide for ConfigDirector and any of our SDKs](https://docs.configdirector.com/getting-started/quickstart).
+
+## Sample apps
+
+[`samples/`](samples/) holds small, runnable applications built on this SDK, one per web
+framework. Start with [`samples/flask`](samples/flask/):
+
+```bash
+cd samples/flask
+uv run flask --app app run --port 3600
+```
+
+## Getting Help
+
+Reach out to us via https://www.configdirector.com/support

configdirector_server_sdk-0.2.0/README.md

@@ -0,0 +1,23 @@
+# ConfigDirector Python SDK
+
+This is the Python server SDK for [ConfigDirector](https://www.configdirector.com).
+
+## Documentation
+
+Refer to the [official documentation for the Python SDK](https://docs.configdirector.com/sdks/server/python).
+
+There is also [a quickstart guide for ConfigDirector and any of our SDKs](https://docs.configdirector.com/getting-started/quickstart).
+
+## Sample apps
+
+[`samples/`](samples/) holds small, runnable applications built on this SDK, one per web
+framework. Start with [`samples/flask`](samples/flask/):
+
+```bash
+cd samples/flask
+uv run flask --app app run --port 3600
+```
+
+## Getting Help
+
+Reach out to us via https://www.configdirector.com/support

configdirector_server_sdk-0.2.0/profiling/README.md

@@ -0,0 +1,126 @@
+# Profiling
+
+Exploratory load profiling for the SDK: drive the [Flask sample](../samples/flask) at a chosen
+request rate for a chosen length of time, record the app process's CPU and memory the whole way
+through, and write the result out in a form you can graph and compare.
+
+This is a measurement tool, not a check. It is not part of `make check-all` — it needs a real
+server SDK key, takes minutes, and its numbers depend on the machine it ran on.
+
+```bash
+make profile                                    # 25 rps for 60s, the default
+make profile ARGS="--rps 100 --duration 300"    # anything the CLI takes
+```
+
+Or directly, which is what the make target does:
+
+```bash
+cd profiling
+uv run python run.py --rps 100 --duration 300 --label hundred-rps
+```
+
+Results land in `profiling/results/<timestamp>-<label>/` (gitignored). Start with `summary.md`,
+graph `metrics.csv`, open `chart.html` if you would rather not.
+
+## What one run does
+
+| Phase | Why it exists |
+| --- | --- |
+| **baseline** (`--baseline`, 5s) | The app is up and idle. Resting RSS and CPU, which every later number is read against. |
+| **warmup** (`--warmup-requests`, 50) | Imports, connection setup, and the SDK's first evaluation of each config all cost something once. Excluded from the report so they do not look like a startup spike. |
+| **load** (`--rps`, `--duration`) | The measurement. |
+| **cooldown** (`--cooldown`, 20s) | Traffic stops, sampling does not. Memory that does not come back down here is the interesting kind. Raise it past 30s to catch a telemetry flush at its default interval. |
+
+Then the app gets SIGTERM — the sample's `atexit` hook closes the client and flushes telemetry,
+the same as a real shutdown — and the report is written.
+
+## The knobs
+
+| Flag | Default | What it changes |
+| --- | --- | --- |
+| `--rps` | 25 | Requests per second. Anything from 1 to ~100 is comfortable on a laptop. |
+| `--duration` | 60 | Seconds to hold that rate. |
+| `--distinct-users` | 500 | How many distinct user ids the traffic cycles through. Raise it to grow the SDK's per-context telemetry; drop it to 1 to take context cardinality out of the picture. |
+| `--mode` | `streaming` | SDK connection mode: `streaming`, `polling`, or `one-time`. |
+| `--offline` | off | Point the SDK at an address nothing answers on. Every config resolves to its default, so this profiles the fallback path — and gives a network-free comparison run. |
+| `--sample-interval` | 0.25 | Seconds between CPU/memory samples. |
+| `--max-in-flight` | `max(50, 4×rps)` | Concurrency cap. Requests over the cap are recorded as skipped rather than queued. |
+| `--cpu-profile` | off | Also run under cProfile. **Serves requests serially and inflates every timing** — a separate investigation, not an addition to a normal run. |
+| `--tracemalloc` | off | Also track allocations, to attribute memory growth to source lines. Significant overhead. POSIX only. |
+| `--label` | — | Suffix for the results directory, so runs are tellable apart. |
+
+## What you get
+
+| File | What it is |
+| --- | --- |
+| `metrics.csv` | **One row per second**, with CPU, memory and request statistics already on the same clock. This is the file to graph — every column is numeric, `t_seconds` is the x-axis. |
+| `chart.html` | Memory, CPU, throughput and latency plotted over time. Self-contained; open it in a browser. |
+| `summary.md` | The headline numbers, laid out to read. |
+| `summary.json` | The same numbers, for diffing two runs mechanically. |
+| `samples.csv` | Raw CPU/memory samples at the sampler's interval — finer than one second. |
+| `requests.csv` | One row per request: offset, latency, status. |
+| `run.json` | Settings, phase boundaries, Python/SDK versions, commit. |
+| `server.log` | The app's own output. |
+| `cprofile.pstats`, `cprofile.txt` | Function-level CPU, with `--cpu-profile`. Browse the raw stats with `uv run python -m pstats results/<run>/cprofile.pstats`. |
+| `tracemalloc.txt`, `tracemalloc.json` | Allocation growth by source line, with `--tracemalloc`. |
+
+The two numbers worth watching:
+
+* **`retained_after_cooldown_mb`** — memory still held once the traffic stopped. Growth *during*
+  load is ordinary; growth that does not come back is what a leak looks like.
+* **`cpu_ms_per_request`** — CPU seconds burned under load, divided by requests served. Derived
+  from the process's monotonic user+system counters, so it is exact rather than an average of
+  sampled percentages. It covers the whole request, Flask and Werkzeug included, not just the
+  SDK — compare runs against each other rather than reading it as the cost of `get_value`.
+
+## Reading the results honestly
+
+**Check `client_ready` first.** `summary.md` says whether the SDK client ever became ready.
+Without a working key in `samples/flask/.env` it never does, every config resolves to its default,
+and the run measures the fallback path rather than real evaluation. The report says so in its
+warnings; it does not stop you, because that path is worth profiling too.
+
+**The dev server is not your production server.** The app is served by Werkzeug in one process
+with a thread per request. That is the right shape for watching the SDK's own cost and completely
+the wrong shape for a throughput benchmark — Gunicorn with several workers would look different in
+every respect except the per-request SDK work.
+
+**The harness changes two things about the sample**, both to keep the measurement honest, and both
+in [`server.py`](server.py): Werkzeug's per-request log line is silenced, and the SDK's logger is
+forced to WARNING. `samples/flask/.env` may ask for DEBUG, which logs every single evaluation and
+would cost more than the evaluation being measured.
+
+**Load is generated in a separate process** from the app, so the generator's own CPU and memory
+never land in the numbers. The pacing is open-loop: request *i* goes out at `start + i/rps`
+whether or not earlier ones have come back, so the offered rate stays at the target when the app
+slows down. Back-pressure shows up as rising latency, and past `--max-in-flight` as skipped
+requests, instead of the generator quietly throttling itself and hiding the problem.
+
+## Working on it
+
+```bash
+cd profiling
+uv sync
+uv run mypy            # this harness only; `make lint` at the root covers its style
+uv run python report.py results/<run>    # rebuild a report without re-running the load
+```
+
+`report.py` is a separate entry point on purpose: regenerating a report is free, so a change to
+the aggregation or the chart does not cost another load test.
+
+The pieces, in the order the run uses them: [`run.py`](run.py) orchestrates,
+[`server.py`](server.py) is the app under measurement, [`sampler.py`](sampler.py) reads CPU and
+memory from outside the app process, [`load.py`](load.py) generates traffic,
+[`report.py`](report.py) aggregates, [`chart.py`](chart.py) draws.
+
+## Things worth trying
+
+* **`--offline` against a live run.** The difference is what evaluation and telemetry actually
+  cost, with Flask's own overhead cancelled out on both sides.
+* **`--distinct-users 1` against the default 500.** Isolates what context cardinality costs in
+  telemetry.
+* **A long run with a long `--cooldown`.** Telemetry flushes every 30s by default; a 5-minute run
+  with a 60s cooldown shows several flushes and whether anything accumulates between them.
+* **`--mode one-time` against `--mode streaming`.** Separates the streaming connection's standing
+  cost from the evaluation path.
+* **`--cpu-profile` once you have a suspect**, to find which functions the time is actually in.

configdirector_server_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,118 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "configdirector-server-sdk"
+dynamic = ["version"]
+description = "Python server SDK for ConfigDirector. ConfigDirector is a remote configuration and feature flag service."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "ConfigDirector" }]
+keywords = [
+  "configdirector",
+  "config",
+  "configuration",
+  "remote config",
+  "remote configuration",
+  "feature flag",
+  "feature toggle",
+  "feature switch",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+
+dependencies = ["urllib3>=2.7,<3"]
+
+[project.urls]
+Homepage = "https://www.configdirector.com"
+Documentation = "https://docs.configdirector.com/sdks/server/python"
+Repository = "https://github.com/ConfigDirector/python-server-sdk"
+Support = "https://www.configdirector.com/support"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.14",
+  "pytest>=8.3",
+  "pytest-cov>=6.0",
+  "pytest-timeout>=2.3",
+  "ruff>=0.9",
+]
+
+[tool.hatch.version]
+path = "src/configdirector/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/configdirector"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/configdirector", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+src = ["src", "."]
+
+[tool.ruff.lint]
+select = [
+  "E",    # pycodestyle errors
+  "W",    # pycodestyle warnings
+  "F",    # pyflakes
+  "I",    # isort
+  "N",    # pep8-naming
+  "UP",   # pyupgrade
+  "B",    # flake8-bugbear
+  "A",    # flake8-builtins
+  "C4",   # flake8-comprehensions
+  "SIM",  # flake8-simplify
+  "PT",   # flake8-pytest-style
+  "RUF",  # ruff-specific
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Test builders mirror the dataclass fields they construct, including `id` and `type`.
+"tests/*" = ["S101", "A002"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src", "tests"]
+strict = true
+warn_unreachable = true
+enable_error_code = ["redundant-expr", "possibly-undefined", "truthy-bool"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# The timeout covers setup, call and teardown, and is generous next to the longest deliberate
+# wait in the suite (~10s). Several tests park a reader on a real socket, so a threading bug
+# surfaces as a suite that never finishes rather than as a failure; this turns that back into a
+# failure. The thread method is the one that works here: it dumps every thread's stack, and it
+# can end a run that is wedged on a lock held across a blocking read, which SIGALRM cannot.
+addopts = "-ra --strict-markers --strict-config --timeout=60 --timeout-method=thread"
+xfail_strict = true
+
+[tool.coverage.run]
+source = ["src/configdirector"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "raise NotImplementedError",
+  "if TYPE_CHECKING:",
+  "\\.\\.\\.",
+]

configdirector_server_sdk-0.2.0/samples/README.md

@@ -0,0 +1,23 @@
+# Sample apps
+
+Small, self-contained applications showing how to use the ConfigDirector Python server SDK with
+different web frameworks.
+
+| Sample | Framework | Description |
+|---|---|---|
+| [flask/](flask/) | [Flask](https://flask.palletsprojects.com/) | Minimal WSGI app: client lifecycle, per-request evaluation, SSR hydration |
+
+Each sample is an independent project with its own `pyproject.toml`. They depend on the SDK
+through a local path (`configdirector-server-sdk = { path = "../.." }`) so that they always run
+against the working copy in this repository rather than a published release.
+
+To run one:
+
+```bash
+cd samples/flask
+uv run flask --app app run --port 3600
+```
+
+> The samples need a real server SDK key to resolve configs. Without one the client stays
+> unready and every config falls back to the default the sample passes in, which is also what
+> a production app sees when it cannot reach ConfigDirector.

configdirector_server_sdk-0.2.0/samples/flask/README.md

@@ -0,0 +1,115 @@
+# Flask sample
+
+A minimal [Flask](https://flask.palletsprojects.com/) app using the ConfigDirector Python
+server SDK. It mirrors the `openfeature-server` sample in the JavaScript SDKs: a single
+`/configs` endpoint that evaluates a handful of configs and returns them as JSON.
+
+## Running it
+
+```bash
+cd samples/flask
+cp .env.example .env      # optional — the sample runs without a real key
+uv run flask --app app run --port 3600
+```
+
+Then:
+
+```bash
+curl 'http://localhost:3600/configs?id=user-123&plan=pro'
+```
+
+```json
+{
+  "day-of-the-week-config": "Friday",
+  "integer-config": 10,
+  "json-value-config": {},
+  "permanent-kill-switch": false,
+  "temporary-feature-flag": true
+}
+```
+
+Query parameters double as the evaluation context — `id`, `name`, and `anonymous` map to the
+matching `Context` fields, and anything else becomes a trait:
+
+```
+/configs?id=user-123&name=Ada&plan=pro&region=eu
+```
+
+Run the smoke tests with `uv run pytest`.
+
+## The client is a singleton
+
+This is the single most important thing the sample shows, so it lives in its own module:
+[`configdirector_client.py`](configdirector_client.py). Create one client when the server
+starts, share it for the whole lifetime of the process, and close it on shutdown.
+
+```python
+# configdirector_client.py — runs exactly once per process
+client = create_client(os.environ["CONFIGDIRECTOR_SERVER_KEY"], ...)
+client.initialize()
+atexit.register(client.close)
+```
+
+```python
+# app.py — every request handler shares that one instance
+from configdirector_client import client
+```
+
+Importing the module is what creates it: Python caches modules in `sys.modules`, so the code
+runs once no matter how many places import `client`. Never call `create_client()` inside a
+request handler — each client opens its own connection, blocks on `initialize()`, starts
+out not-ready (so it serves defaults), and drops its batched telemetry when it is discarded.
+
+Concurrency is not a reason to make more of them: the client is thread-safe, so every worker
+thread shares this one safely. Process-based servers (Gunicorn workers, or `flask run --debug`'s
+reloader) get one client per process, which is correct — a client cannot be shared across
+processes.
+
+Evaluation itself is cheap. `get_value()` reads config state the client already holds in memory,
+with no network call on the request path, which is what makes it safe to call several times per
+request.
+
+## What else it demonstrates
+
+**Initialization is explicit and non-fatal.** `initialize()` blocks until the initial config
+state arrives or the timeout elapses, and never raises on connection failure. The sample checks
+`is_ready`, logs a warning, and carries on serving defaults.
+
+**Defaults are the fallback.** Every `get_value()` call passes the value to serve when
+ConfigDirector is unreachable, so it should be the safe choice. Its type also decides how the
+config value is parsed.
+
+**Context is per-request; the client is not.** `context_from_request()` maps query parameters
+onto a `Context`; a real app would build this from the authenticated session.
+
+**Logging is yours to configure.** The sample passes its own logger to the client, so SDK output
+lands in the application's logging namespace rather than the SDK's:
+
+```python
+sdk_logger = logging.getLogger("flask_sample.configdirector")
+sdk_logger.setLevel(os.environ.get("CONFIGDIRECTOR_LOG_LEVEL", "INFO"))
+
+client = create_client(..., logger=sdk_logger)
+```
+
+```
+flask_sample.configdirector DEBUG No config state found for 'integer-config', returning default value 10
+```
+
+Any object with `debug`/`info`/`warning`/`error` methods works, and a stdlib `Logger` satisfies
+that. Omit `logger=` entirely and the SDK falls back to the standard library logger named
+`configdirector`, leaving the level to your application — or pass `log_level=` if you would
+rather not configure the `logging` module at all. Set `CONFIGDIRECTOR_LOG_LEVEL=DEBUG` to watch
+every evaluation as it happens.
+
+**Shutdown is clean.** `atexit` closes the client, dropping connections and flushing pending
+telemetry. A production deployment would also hook its server's worker-exit signal.
+
+The SDK also supports watching configs for changes and subscribing to client events; see the
+[SDK README](../../README.md) for `watch()` and `on()`.
+
+## Running without a server SDK key
+
+Without a valid key the client stays unready and every config falls back to the default this
+app passes in. That is the same path a production app takes when it cannot reach ConfigDirector,
+so it is worth seeing: the app keeps serving, on the defaults you chose.

configdirector_server_sdk-0.2.0/src/configdirector/__init__.py

@@ -0,0 +1,83 @@
+"""ConfigDirector Python server SDK.
+
+ConfigDirector is a remote configuration and feature flag service.
+
+Example::
+
+    from configdirector import Context, Metadata, create_client
+
+    client = create_client(
+        "YOUR-SERVER-SDK-KEY",
+        metadata=Metadata(app_name="my-awesome-app", app_version="1.0.0"),
+    )
+    client.initialize()
+
+    if client.get_value("new-checkout", False, Context(id="user-123")):
+        ...
+"""
+
+from ._version import __version__
+from .client import create_client
+from .errors import (
+    ConfigDirectorConnectionError,
+    ConfigDirectorError,
+    ConfigDirectorInitializationError,
+    ConfigDirectorTypeError,
+    ConfigDirectorValidationError,
+)
+from .types import (
+    ClientEvent,
+    ClientHooks,
+    ClientReadyEvent,
+    ClientReadyHandler,
+    ConfigDirectorClient,
+    ConfigDirectorLogger,
+    ConfigEvaluatedEvent,
+    ConfigEvaluatedHandler,
+    ConfigEvaluation,
+    ConfigState,
+    ConfigsUpdatedEvent,
+    ConfigsUpdatedHandler,
+    ConfigType,
+    ConfigValue,
+    ConnectionMode,
+    ConnectionOptions,
+    Context,
+    EvaluationReason,
+    Metadata,
+    Subscription,
+    TelemetryOptions,
+    WatchHandler,
+)
+
+__all__ = [
+    "ClientEvent",
+    "ClientHooks",
+    "ClientReadyEvent",
+    "ClientReadyHandler",
+    "ConfigDirectorClient",
+    "ConfigDirectorConnectionError",
+    "ConfigDirectorError",
+    "ConfigDirectorInitializationError",
+    "ConfigDirectorLogger",
+    "ConfigDirectorTypeError",
+    "ConfigDirectorValidationError",
+    "ConfigEvaluatedEvent",
+    "ConfigEvaluatedHandler",
+    "ConfigEvaluation",
+    "ConfigState",
+    "ConfigType",
+    "ConfigValue",
+    "ConfigsUpdatedEvent",
+    "ConfigsUpdatedHandler",
+    "ConnectionMode",
+    "ConnectionOptions",
+    "Context",
+    "EvaluationReason",
+    "Metadata",
+    "Subscription",
+    "TelemetryOptions",
+    "WatchHandler",
+    "__version__",
+    "create_client",
+]