quonfig 0.0.15

Python SDK for Quonfig — feature flags and configuration management

quonfig

Python SDK for Quonfig.

Install

pip install quonfig

Usage

from quonfig import Quonfig

client = Quonfig(sdk_key="sdk-...")
client.init()

value = client.get_string("my.key", default="fallback")
enabled = client.is_feature_enabled("my.flag")

Context

# Per-call context
result = client.get_string("my.key", contexts={"user": {"plan": "pro"}})

# Bound context (for request handlers etc.)
user_client = client.with_context({"user": {"id": "u123", "plan": "pro"}})
enabled = user_client.is_feature_enabled("my.flag")

# Thread-local scoped context
with client.scoped_context({"user": {"id": "u123"}}):
    enabled = client.is_feature_enabled("my.flag")

Dynamic log levels

from quonfig import Quonfig

client = Quonfig(
    sdk_key="sdk-...",
    logger_key="log-level.my-app",  # config that drives per-logger rules
).init()

# Convenience form — SDK injects { "quonfig-sdk-logging": { "key": "my_app.auth" } }
# into context so a single config can route by logger path.
if client.should_log(logger_path="my_app.auth", desired_level="INFO"):
    print("auth event")

# Primitive form — for callers that want explicit control over the config key.
# No auto-prefixing: pass the full stored key.
if client.should_log(config_key="log-level.my-app", desired_level="DEBUG"):
    print("debug event")

logger_path is passed through verbatim — the SDK does not normalize it, so callers can author config rules against whatever shape their host language prefers (dotted, double-colon, slash, etc.).

Dynamic log levels with stdlib logging

Attach QuonfigLoggerFilter to any logger or handler and the SDK will gate records against logger_key. The record's name flows into context verbatim as quonfig-sdk-logging.key, so a single config can drive per-logger rules.

import logging
from quonfig import Quonfig, QuonfigLoggerFilter

client = Quonfig(sdk_key="sdk-...", logger_key="log-level.my-app").init()

root = logging.getLogger()
root.addFilter(QuonfigLoggerFilter(client))

Dynamic log levels with structlog

QuonfigLoggerProcessor is a structlog processor. Place it after structlog.stdlib.add_log_level so the level is populated on the event dict.

import structlog
from quonfig import Quonfig, QuonfigLoggerProcessor

client = Quonfig(sdk_key="sdk-...", logger_key="log-level.my-app").init()

structlog.configure(
    processors=[
        structlog.stdlib.add_log_level,
        QuonfigLoggerProcessor(client),
        structlog.processors.JSONRenderer(),
    ],
)

structlog is an optional dependency — QuonfigLoggerProcessor raises ImportError with an install hint if it isn't available. The stdlib filter has no optional-dep concern.

Datadir mode (local files)

import os

client = Quonfig(datadir="/path/to/workspace", environment="production")
client.init()

Configuration

Param	Env var	Default
sdk_key	QUONFIG_SDK_KEY	required for API mode
api_urls	-- (derived from QUONFIG_DOMAIN)	["https://primary.quonfig.com", "https://secondary.quonfig.com"]
telemetry_url	-- (derived from QUONFIG_DOMAIN)	https://telemetry.quonfig.com
environment	QUONFIG_ENVIRONMENT	""
datadir	QUONFIG_DIR	None
init_timeout	--	10.0
on_init_failure	--	"raise"
on_no_default	--	"error"
logger_key	--	None

QUONFIG_DOMAIN

A single env var governs the api, sse, and telemetry URL defaults:

Env var	Default	Effect
QUONFIG_DOMAIN	quonfig.com	Sets api_urls to https://primary.${DOMAIN} + https://secondary.${DOMAIN} and telemetry_url to https://telemetry.${DOMAIN}. SSE host is derived by prepending stream. to the api host.

Resolution order (highest wins):

1. Explicit api_urls= / telemetry_url= kwargs (local-dev escape hatch).
2. QUONFIG_DOMAIN env var.
3. Hardcoded default quonfig.com.

The previously-supported QUONFIG_API_URL, QUONFIG_API_URLS, and QUONFIG_TELEMETRY_URL env vars have been removed.

Health primitives

The client exposes two diagnostic getters:

client.last_successful_refresh()  # -> datetime | None
client.connection_state()         # -> "connected" | "disconnected" | "falling_back" | "initializing"

• last_successful_refresh() is the wall-clock time of the most recent installed config envelope. Updated on every install path (datadir load, initial HTTP fetch, SSE event, fallback poll). None before the first install.
• connection_state() reports the SDK's current view of its delivery pipeline. falling_back means SSE is down and the HTTP fallback poller is engaged.

Do not wire last_successful_refresh() or connection_state() directly into a Kubernetes liveness probe. These signals are diagnostic, not pass/fail. A liveness probe based on SDK freshness will amplify transient network blips into restart cascades.

Compose your own threshold (e.g. "alert if stale > 10 minutes AND state is disconnected") rather than treating either primitive as binary health.