fast-feature-core 0.0.1__tar.gz

fast_feature_core-0.0.1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: fast-feature-core
+Version: 0.0.1
+Summary: Core domain model for fast-feature: flags, evaluation outcomes, and the storage interface.
+Author: byunjuneseok
+Author-email: byunjuneseok <byunjuneseok@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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: Typing :: Typed
+Requires-Python: >=3.10

fast_feature_core-0.0.1/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "fast-feature-core"
+version = "0.0.1"
+description = "Core domain model for fast-feature: flags, evaluation outcomes, and the storage interface."
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "byunjuneseok", email = "byunjuneseok@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+# Pure-Python domain model with no runtime dependencies.
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fast_feature.core"

fast_feature_core-0.0.1/src/fast_feature/core/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from .errors import (
+    CoreError,
+    FlagAlreadyExistsError,
+    FlagNotFoundError,
+    InvalidFlagError,
+)
+from .evaluation import ErrorCode, EvaluationOutcome, Reason
+from .flag import Flag, FlagState
+from .repository import FlagRepository
+from .types import EvaluationContext, JsonValue
+
+__all__ = [
+    "EvaluationContext",
+    "JsonValue",
+    "Flag",
+    "FlagState",
+    "FlagRepository",
+    "EvaluationOutcome",
+    "Reason",
+    "ErrorCode",
+    "CoreError",
+    "FlagNotFoundError",
+    "FlagAlreadyExistsError",
+    "InvalidFlagError",
+]

fast_feature_core-0.0.1/src/fast_feature/core/errors.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+class CoreError(Exception):
+    """Base class for all fast-feature-core errors.
+
+    Dependents catch this at their boundary and re-raise as their own base
+    error (with chaining) rather than coupling to the concrete subclasses.
+    """
+
+
+class FlagNotFoundError(CoreError):
+    def __init__(self, key: str) -> None:
+        self.key = key
+        super().__init__(f"Flag {key!r} was not found")
+
+
+class FlagAlreadyExistsError(CoreError):
+    def __init__(self, key: str) -> None:
+        self.key = key
+        super().__init__(f"Flag {key!r} already exists")
+
+
+class InvalidFlagError(CoreError):
+    """Raised when a flag definition is structurally invalid."""

fast_feature_core-0.0.1/src/fast_feature/core/evaluation.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from .types import JsonValue
+
+
+class Reason(str, Enum):
+    """OpenFeature resolution reasons.
+
+    OFREP's core enum is a subset of these; the wider set is kept because the
+    OpenFeature specification treats ``reason`` as an open string.
+    """
+
+    STATIC = "STATIC"
+    DEFAULT = "DEFAULT"
+    TARGETING_MATCH = "TARGETING_MATCH"
+    SPLIT = "SPLIT"
+    DISABLED = "DISABLED"
+    CACHED = "CACHED"
+    UNKNOWN = "UNKNOWN"
+    ERROR = "ERROR"
+
+
+class ErrorCode(str, Enum):
+    """OpenFeature error codes used when an evaluation fails."""
+
+    FLAG_NOT_FOUND = "FLAG_NOT_FOUND"
+    PARSE_ERROR = "PARSE_ERROR"
+    TYPE_MISMATCH = "TYPE_MISMATCH"
+    INVALID_CONTEXT = "INVALID_CONTEXT"
+    TARGETING_KEY_MISSING = "TARGETING_KEY_MISSING"
+    PROVIDER_NOT_READY = "PROVIDER_NOT_READY"
+    GENERAL = "GENERAL"
+
+
+@dataclass
+class EvaluationOutcome:
+    """The result of evaluating a single flag against a context."""
+
+    key: str
+    reason: Reason
+    value: JsonValue = None
+    variant: str | None = None
+    metadata: dict[str, JsonValue] | None = None
+    error_code: ErrorCode | None = None
+    error_details: str | None = None
+
+    @property
+    def is_error(self) -> bool:
+        return self.error_code is not None
+
+    @classmethod
+    def error(
+        cls,
+        key: str,
+        error_code: ErrorCode,
+        details: str | None = None,
+    ) -> EvaluationOutcome:
+        return cls(
+            key=key,
+            reason=Reason.ERROR,
+            error_code=error_code,
+            error_details=details,
+        )

fast_feature_core-0.0.1/src/fast_feature/core/flag.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+
+from .errors import InvalidFlagError
+from .types import JsonValue
+
+_KEY_PATTERN = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+class FlagState(str, Enum):
+    ENABLED = "ENABLED"
+    DISABLED = "DISABLED"
+
+
+@dataclass
+class Flag:
+    """A feature flag with named variants and an optional targeting rule.
+
+    A flag holds a set of named ``variants`` and resolves to exactly one of
+    them. Resolution is governed by an optional ``targeting`` rule (JsonLogic);
+    in its absence the ``default_variant`` is used.
+    """
+
+    key: str
+    variants: dict[str, JsonValue]
+    default_variant: str
+    state: FlagState = FlagState.ENABLED
+    targeting: dict[str, JsonValue] | None = None
+    metadata: dict[str, JsonValue] = field(default_factory=dict)
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        if not _KEY_PATTERN.match(self.key):
+            raise InvalidFlagError(
+                f"Invalid flag key {self.key!r}: must match {_KEY_PATTERN.pattern}"
+            )
+        if not self.variants:
+            raise InvalidFlagError(f"Flag {self.key!r} must define at least one variant")
+        if self.default_variant not in self.variants:
+            raise InvalidFlagError(
+                f"Flag {self.key!r} default variant {self.default_variant!r} "
+                "is not among its variants"
+            )
+
+    @property
+    def default_value(self) -> JsonValue:
+        return self.variants[self.default_variant]
+
+    def value_of(self, variant: str) -> JsonValue:
+        return self.variants[variant]
+
+    def has_variant(self, variant: str) -> bool:
+        return variant in self.variants

fast_feature_core-0.0.1/src/fast_feature/core/repository.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .flag import Flag
+
+
+class FlagRepository(ABC):
+    """Storage boundary for flags.
+
+    Implementations live behind optional extras (``inmemory``, ``postgresql``,
+    ``mysql``). The domain and the evaluation engine depend only on this
+    interface, never on a concrete storage technology.
+    """
+
+    @abstractmethod
+    async def get(self, key: str) -> Flag | None:
+        """Return the flag with ``key``, or ``None`` if it does not exist."""
+
+    @abstractmethod
+    async def list_all(self) -> list[Flag]:
+        """Return every flag, ordered by key."""
+
+    @abstractmethod
+    async def create(self, flag: Flag) -> Flag:
+        """Persist a new flag.
+
+        Raises:
+            FlagAlreadyExistsError: if a flag with the same key exists.
+        """
+
+    @abstractmethod
+    async def update(self, flag: Flag) -> Flag:
+        """Replace an existing flag.
+
+        Raises:
+            FlagNotFoundError: if the flag does not exist.
+        """
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """Remove a flag.
+
+        Raises:
+            FlagNotFoundError: if the flag does not exist.
+        """
+
+    async def exists(self, key: str) -> bool:
+        return await self.get(key) is not None

fast_feature_core-0.0.1/src/fast_feature/core/types.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import TypeAlias
+
+JsonValue: TypeAlias = "bool | int | float | str | None | list[JsonValue] | dict[str, JsonValue]"
+"""Any value expressible in JSON. Flag variants resolve to one of these."""
+
+EvaluationContext: TypeAlias = "dict[str, JsonValue]"
+"""Targeting context supplied by a client at evaluation time.
+
+By OpenFeature convention the optional ``targetingKey`` entry identifies the
+subject of the evaluation (a user, account, session, ...).
+"""