quonfig 0.0.1__tar.gz

quonfig-0.0.1/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.1
+Name: quonfig
+Version: 0.0.1
+Summary: Python SDK for Quonfig — feature flags and configuration management
+License: MIT
+Author: Quonfig
+Author-email: hello@quonfig.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: cryptography (>=42.0.0)
+Requires-Dist: isodate (>=0.6.1,<0.7.0)
+Requires-Dist: mmh3 (>=3.0.0,<5.0.0)
+Requires-Dist: packaging (>=21.0)
+Requires-Dist: requests (>=2.30.0)
+Requires-Dist: sseclient-py (>=1.7.2,<2.0.0)
+Requires-Dist: tenacity (>=8.0.0)

quonfig-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[tool.poetry]
+name = "quonfig"
+version = "0.0.1"
+description = "Python SDK for Quonfig — feature flags and configuration management"
+license = "MIT"
+authors = ["Quonfig <hello@quonfig.com>"]
+packages = [{include = "quonfig"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+requests = ">=2.30.0"
+sseclient-py = "^1.7.2"
+mmh3 = ">=3.0.0,<5.0.0"
+cryptography = ">=42.0.0"
+tenacity = ">=8.0.0"
+isodate = "^0.6.1"
+packaging = ">=21.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-mock = "^3.0"
+pytest-cov = "^5.0"
+mypy = "^1.0"
+ruff = "^0.4"
+responses = "^0.25"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["E501"]
+"quonfig/operators.py" = ["E501"]

quonfig-0.0.1/quonfig/__init__.py

@@ -0,0 +1,23 @@
+from .bound_client import BoundQuonfig
+from .client import Quonfig
+from .exceptions import (
+    QuonfigDecryptionError,
+    QuonfigEnvVarNotSetError,
+    QuonfigError,
+    QuonfigInitTimeoutError,
+    QuonfigKeyNotFoundError,
+    QuonfigNotInitializedError,
+)
+from .types import Contexts
+
+__all__ = [
+    "Quonfig",
+    "BoundQuonfig",
+    "QuonfigError",
+    "QuonfigKeyNotFoundError",
+    "QuonfigInitTimeoutError",
+    "QuonfigNotInitializedError",
+    "QuonfigEnvVarNotSetError",
+    "QuonfigDecryptionError",
+    "Contexts",
+]

quonfig-0.0.1/quonfig/bound_client.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .client import _NO_DEFAULT, Quonfig
+from .context import merge_contexts
+from .types import Contexts
+
+
+class BoundQuonfig:
+    """
+    A Quonfig client bound to a specific context.
+
+    All getters automatically merge the bound contexts with any additional
+    per-call contexts.
+    """
+
+    def __init__(self, client: Quonfig, contexts: Contexts) -> None:
+        self._client = client
+        self._contexts = contexts
+
+    def with_context(self, contexts: Contexts) -> "BoundQuonfig":
+        """Return a new BoundQuonfig with additional contexts merged in."""
+        return BoundQuonfig(self._client, merge_contexts(self._contexts, contexts))
+
+    def get(self, key: str, default: Any = _NO_DEFAULT) -> Any:
+        return self._client.get(key, default=default, contexts=self._contexts)
+
+    def get_string(self, key: str, default: Any = _NO_DEFAULT) -> Optional[str]:
+        return self._client.get_string(key, default=default, contexts=self._contexts)
+
+    def get_int(self, key: str, default: Any = _NO_DEFAULT) -> Optional[int]:
+        return self._client.get_int(key, default=default, contexts=self._contexts)
+
+    def get_float(self, key: str, default: Any = _NO_DEFAULT) -> Optional[float]:
+        return self._client.get_float(key, default=default, contexts=self._contexts)
+
+    def get_bool(self, key: str, default: Any = _NO_DEFAULT) -> Optional[bool]:
+        return self._client.get_bool(key, default=default, contexts=self._contexts)
+
+    def get_string_list(self, key: str, default: Any = _NO_DEFAULT) -> Optional[List[str]]:
+        return self._client.get_string_list(key, default=default, contexts=self._contexts)
+
+    def get_json(self, key: str, default: Any = _NO_DEFAULT) -> Any:
+        return self._client.get_json(key, default=default, contexts=self._contexts)
+
+    def get_duration(self, key: str, default: Any = _NO_DEFAULT) -> Optional[float]:
+        return self._client.get_duration(key, default=default, contexts=self._contexts)
+
+    def is_feature_enabled(self, key: str, default: bool = False) -> bool:
+        return self._client.is_feature_enabled(key, default=default, contexts=self._contexts)
+
+    def should_log(self, logger_name: str, desired_level: str) -> bool:
+        return self._client.should_log(logger_name, desired_level, contexts=self._contexts)
+
+    def keys(self) -> List[str]:
+        return self._client.keys()

quonfig-0.0.1/quonfig/client.py

@@ -0,0 +1,458 @@
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import threading
+from typing import TYPE_CHECKING, Any, List, Optional
+
+if TYPE_CHECKING:
+    from .bound_client import BoundQuonfig
+
+from .context import (
+    clear_thread_context,
+    get_thread_context,
+    merge_contexts,
+    set_thread_context,
+)
+from .evaluator import Evaluator
+from .exceptions import (
+    QuonfigDecryptionError,
+    QuonfigEnvVarNotSetError,
+    QuonfigInitTimeoutError,
+    QuonfigKeyNotFoundError,
+)
+from .resolver import LOG_LEVEL_ORDER, Resolver
+from .store import ConfigStore
+from .transport import Transport
+from .types import Contexts
+
+logger = logging.getLogger(__name__)
+
+_NO_DEFAULT = object()
+
+# Default API URL
+_DEFAULT_API_URL = "https://api.quonfig.com"
+
+
+class Quonfig:
+    """
+    Main Quonfig SDK client.
+
+    Usage:
+        client = Quonfig(sdk_key="sdk-...")
+        client.init()
+        value = client.get_string("my.key", default="fallback")
+        enabled = client.is_feature_enabled("my.flag")
+    """
+
+    def __init__(
+        self,
+        sdk_key: Optional[str] = None,
+        *,
+        api_urls: Optional[List[str]] = None,
+        init_timeout: float = 10.0,
+        on_init_failure: str = "raise",  # "raise" | "return_zero_value"
+        global_context: Optional[Contexts] = None,
+        environment: Optional[str] = None,
+        telemetry_url: Optional[str] = None,
+        collect_evaluation_summaries: bool = True,
+        context_upload_mode: str = "shapes_only",  # "none" | "shapes_only" | "periodic_example"
+        on_no_default: str = "error",  # "error" | "warn" | "ignore"
+        datadir: Optional[str] = None,
+    ) -> None:
+        # Resolve configuration from params or env vars
+        self._sdk_key = sdk_key or os.environ.get("QUONFIG_SDK_KEY", "")
+        self._environment = environment or os.environ.get("QUONFIG_ENVIRONMENT", "")
+        self._datadir = datadir or os.environ.get("QUONFIG_DIR")
+
+        if api_urls:
+            self._api_urls = api_urls
+        else:
+            env_url = os.environ.get("QUONFIG_API_URL", "")
+            if env_url:
+                self._api_urls = [u.strip() for u in env_url.split(",") if u.strip()]
+            else:
+                self._api_urls = [_DEFAULT_API_URL]
+
+        self._telemetry_url = telemetry_url or os.environ.get(
+            "QUONFIG_TELEMETRY_URL", _DEFAULT_API_URL
+        )
+        self._init_timeout = init_timeout
+        self._on_init_failure = on_init_failure
+        self._on_no_default = on_no_default
+        self._global_context: Contexts = global_context or {}
+
+        self._store = ConfigStore()
+        self._shutdown = threading.Event()
+        self._initialized = threading.Event()
+        self._init_error: Optional[Exception] = None
+
+        # Will be set after init
+        self._evaluator: Optional[Evaluator] = None
+        self._resolver = Resolver(self._store)
+
+        # Telemetry (optional)
+        self._telemetry = None
+        if collect_evaluation_summaries or context_upload_mode != "none":
+            try:
+                from .telemetry import TelemetryReporter
+
+                self._telemetry = TelemetryReporter(
+                    telemetry_url=self._telemetry_url,
+                    sdk_key=self._sdk_key,
+                    collect_evaluation_summaries=collect_evaluation_summaries,
+                    collect_context_shapes=(context_upload_mode != "none"),
+                )
+            except Exception:
+                pass  # Telemetry is optional
+
+        # Transport (only if not datadir mode)
+        self._transport: Optional[Transport] = None
+        if not self._datadir and self._sdk_key:
+            self._transport = Transport(
+                api_urls=self._api_urls,
+                sdk_key=self._sdk_key,
+            )
+
+    # ------------------------------------------------------------------
+    # Initialization
+    # ------------------------------------------------------------------
+
+    def init(self) -> "Quonfig":
+        """
+        Block until first config load completes (or timeout).
+
+        Raises QuonfigInitTimeoutError if init_timeout exceeded and
+        on_init_failure="raise".
+        """
+        if self._datadir:
+            self._load_from_datadir()
+        elif self._transport:
+            self._load_from_api()
+        else:
+            # No data source configured — mark initialized with empty store
+            self._finish_init()
+
+        return self
+
+    def _load_from_datadir(self) -> None:
+        from .datadir import load_datadir
+
+        try:
+            envelope = load_datadir(self._datadir or "", self._environment)
+            self._store.update(envelope)
+        except Exception as e:
+            self._init_error = e
+            logger.error("Failed to load datadir: %s", e)
+            self._finish_init()
+            raise
+        else:
+            self._finish_init()
+
+    def _load_from_api(self) -> None:
+        """Start background SSE thread; initial load done via polling thread."""
+        assert self._transport is not None
+
+        # Do an initial blocking fetch to populate the store
+        try:
+            envelope = self._transport.fetch()
+            if envelope is not None:
+                self._store.update(envelope)
+            self._finish_init()
+        except Exception as e:
+            logger.warning("Initial fetch failed: %s — starting SSE anyway", e)
+            self._finish_init()
+
+        # Start SSE for live updates
+        from .sse import SSEClient
+
+        sse = SSEClient(self._transport, self._store, self._shutdown)
+        sse.start()
+
+        # Start polling as fallback
+        self._transport.start_polling(self._store, self._shutdown)
+
+        # Start telemetry
+        if self._telemetry is not None:
+            self._telemetry.start()
+
+    def _finish_init(self) -> None:
+        self._evaluator = Evaluator(self._store, self._environment)
+        self._initialized.set()
+
+    def _wait_initialized(self) -> None:
+        if not self._initialized.is_set():
+            ok = self._initialized.wait(timeout=self._init_timeout)
+            if not ok:
+                if self._on_init_failure == "raise":
+                    raise QuonfigInitTimeoutError(
+                        f"Quonfig did not initialize within {self._init_timeout}s"
+                    )
+                # return_zero_value: best effort with partial data
+                self._finish_init()
+
+    # ------------------------------------------------------------------
+    # Context helpers
+    # ------------------------------------------------------------------
+
+    def _effective_contexts(self, contexts: Optional[Contexts]) -> Contexts:
+        """Merge global, thread-local, and per-call contexts."""
+        parts = [self._global_context]
+        thread_ctx = get_thread_context()
+        if thread_ctx:
+            parts.append(thread_ctx)
+        if contexts:
+            parts.append(contexts)
+        return merge_contexts(*[p for p in parts if p])
+
+    # ------------------------------------------------------------------
+    # Core evaluate + resolve
+    # ------------------------------------------------------------------
+
+    def _get(self, key: str, contexts: Optional[Contexts] = None) -> Any:
+        self._wait_initialized()
+        assert self._evaluator is not None
+        merged = self._effective_contexts(contexts)
+        result = self._evaluator.evaluate(key, merged)
+
+        # Record telemetry
+        if self._telemetry is not None:
+            self._telemetry.record_evaluation(result)
+            if merged:
+                self._telemetry.record_context(merged)
+
+        if result.reason == "MISSING" or result.value is None:
+            return _NO_DEFAULT
+
+        try:
+            return self._resolver.resolve(result.value, merged, config_key=key)
+        except (QuonfigEnvVarNotSetError, QuonfigDecryptionError):
+            # These are semantic errors that callers need to handle — re-raise
+            raise
+        except Exception as e:
+            logger.warning("Error resolving value for key '%s': %s", key, e)
+            return _NO_DEFAULT
+
+    def _handle_missing(self, key: str, default: Any) -> Any:
+        if default is not _NO_DEFAULT:
+            return default
+        if self._on_no_default == "error":
+            raise QuonfigKeyNotFoundError(
+                f"No value found for key '{key}' and no default was provided"
+            )
+        elif self._on_no_default == "warn":
+            logger.warning("No value found for key '%s'", key)
+        return None
+
+    # ------------------------------------------------------------------
+    # Typed getters
+    # ------------------------------------------------------------------
+
+    def get(
+        self,
+        key: str,
+        default: Any = _NO_DEFAULT,
+        contexts: Optional[Contexts] = None,
+    ) -> Any:
+        """Get any config value by key, returning raw Python type."""
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            return self._handle_missing(key, default)
+        return result
+
+    def get_string(
+        self,
+        key: str,
+        default: Any = _NO_DEFAULT,
+        contexts: Optional[Contexts] = None,
+    ) -> Optional[str]:
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            val = self._handle_missing(key, default)
+            return str(val) if val is not None else None
+        return str(result) if result is not None else None
+
+    def get_int(
+        self,
+        key: str,
+        default: Any = _NO_DEFAULT,
+        contexts: Optional[Contexts] = None,
+    ) -> Optional[int]:
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            val = self._handle_missing(key, default)
+            return int(val) if val is not None else None
+        try:
+            return int(result)
+        except (TypeError, ValueError):
+            # Coercion failed (e.g. env-var-provided value is not a valid int)
+            return self._handle_missing(key, default)
+
+    def get_float(
+        self,
+        key: str,
+        default: Any = _NO_DEFAULT,
+        contexts: Optional[Contexts] = None,
+    ) -> Optional[float]:
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            val = self._handle_missing(key, default)
+            return float(val) if val is not None else None
+        try:
+            return float(result)
+        except (TypeError, ValueError):
+            return None
+
+    def get_bool(
+        self,
+        key: str,
+        default: Any = _NO_DEFAULT,
+        contexts: Optional[Contexts] = None,
+    ) -> Optional[bool]:
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            val = self._handle_missing(key, default)
+            return bool(val) if val is not None else None
+        return bool(result)
+
+    def get_string_list(
+        self,
+        key: str,
+        default: Any = _NO_DEFAULT,
+        contexts: Optional[Contexts] = None,
+    ) -> Optional[List[str]]:
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            val = self._handle_missing(key, default)
+            if val is None:
+                return None
+            if isinstance(val, list):
+                return [str(x) for x in val]
+            return [str(val)]
+        if isinstance(result, list):
+            return [str(x) for x in result]
+        return [str(result)] if result is not None else None
+
+    def get_json(
+        self,
+        key: str,
+        default: Any = _NO_DEFAULT,
+        contexts: Optional[Contexts] = None,
+    ) -> Any:
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            return self._handle_missing(key, default)
+        return result
+
+    def get_duration(
+        self,
+        key: str,
+        default: Any = _NO_DEFAULT,
+        contexts: Optional[Contexts] = None,
+    ) -> Optional[float]:
+        """Get a duration value in seconds."""
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            val = self._handle_missing(key, default)
+            return float(val) if val is not None else None
+        try:
+            return float(result)
+        except (TypeError, ValueError):
+            return None
+
+    def is_feature_enabled(
+        self,
+        key: str,
+        default: bool = False,
+        contexts: Optional[Contexts] = None,
+    ) -> bool:
+        """Returns True only if the config is a boolean True value.
+        Returns False for missing keys, non-boolean types, or boolean False."""
+        result = self._get(key, contexts)
+        if result is _NO_DEFAULT:
+            return default
+        if isinstance(result, bool):
+            return result
+        if isinstance(result, str):
+            if result.lower() == "true":
+                return True
+            if result.lower() == "false":
+                return False
+        # Non-boolean types (int, float, list, dict, etc.) return False
+        return False
+
+    def should_log(
+        self,
+        logger_name: str,
+        desired_level: str,
+        contexts: Optional[Contexts] = None,
+    ) -> bool:
+        """
+        Return True if the given logger_name should log at desired_level.
+
+        Walks the hierarchy from specific to general:
+            log-levels.app.auth -> log-levels.app -> log-levels
+        """
+        desired_order = LOG_LEVEL_ORDER.get(desired_level.upper())
+        if desired_order is None:
+            return True  # Unknown level — log it
+
+        # Build hierarchy of keys to check
+        parts = logger_name.split(".")
+        keys_to_check = []
+        for i in range(len(parts), 0, -1):
+            keys_to_check.append("log-levels." + ".".join(parts[:i]))
+        keys_to_check.append("log-levels")
+
+        for key in keys_to_check:
+            result = self._get(key, contexts)
+            if result is not _NO_DEFAULT and result is not None:
+                configured_order = LOG_LEVEL_ORDER.get(str(result).upper())
+                if configured_order is not None:
+                    return desired_order >= configured_order
+        # No config found — default to logging everything
+        return True
+
+    # ------------------------------------------------------------------
+    # Context scoping
+    # ------------------------------------------------------------------
+
+    def with_context(self, contexts: Contexts) -> "BoundQuonfig":
+        from .bound_client import BoundQuonfig
+
+        return BoundQuonfig(self, contexts)
+
+    @contextlib.contextmanager
+    def scoped_context(self, contexts: Contexts):
+        """Context manager that sets thread-local context for the duration."""
+        old = get_thread_context()
+        try:
+            set_thread_context(contexts)
+            yield self
+        finally:
+            if old is None:
+                clear_thread_context()
+            else:
+                set_thread_context(old)
+
+    # ------------------------------------------------------------------
+    # Misc
+    # ------------------------------------------------------------------
+
+    def keys(self) -> List[str]:
+        return self._store.keys()
+
+    def close(self) -> None:
+        self._shutdown.set()
+        if self._telemetry is not None:
+            try:
+                self._telemetry.stop()
+            except Exception:
+                pass
+
+    def __enter__(self) -> "Quonfig":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

quonfig-0.0.1/quonfig/context.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Optional, Tuple
+
+from .types import Contexts
+
+_thread_local = threading.local()
+
+# Magic property names that resolve to current time in milliseconds
+_MAGIC_TIME_PROPS = frozenset(
+    ["prefab.current-time", "quonfig.current-time", "reforge.current-time"]
+)
+
+
+def merge_contexts(*contexts_list: Contexts) -> Contexts:
+    """Shallow merge per namespace; later wins."""
+    result: Contexts = {}
+    for ctx in contexts_list:
+        if not ctx:
+            continue
+        for namespace, values in ctx.items():
+            result[namespace] = dict(values)
+    return result
+
+
+def get_context_value(contexts: Contexts, property_name: str) -> Tuple[Any, bool]:
+    """
+    Dotted-path lookup: "user.email" -> contexts["user"]["email"].
+
+    Magic properties are resolved before normal lookup:
+      - "prefab.current-time", "quonfig.current-time", "reforge.current-time"
+        -> current Unix time in ms
+
+    Returns (value, found: bool).
+    """
+    if property_name in _MAGIC_TIME_PROPS:
+        return int(time.time() * 1000), True
+
+    if not property_name:
+        return None, False
+
+    parts = property_name.split(".", maxsplit=1)
+    if len(parts) == 1:
+        # No namespace — look in "" namespace
+        namespace = ""
+        key = property_name
+    else:
+        namespace, key = parts
+
+    ns_data = contexts.get(namespace)
+    if ns_data is None:
+        return None, False
+
+    if key in ns_data:
+        return ns_data[key], True
+    return None, False
+
+
+def set_thread_context(contexts: Contexts) -> None:
+    """Store contexts in thread-local storage."""
+    _thread_local.quonfig_context = contexts
+
+
+def get_thread_context() -> Optional[Contexts]:
+    """Retrieve contexts from thread-local storage."""
+    return getattr(_thread_local, "quonfig_context", None)
+
+
+def clear_thread_context() -> None:
+    """Remove contexts from thread-local storage."""
+    if hasattr(_thread_local, "quonfig_context"):
+        del _thread_local.quonfig_context