switchbox-flags 0.3.0__tar.gz → 0.5.0__tar.gz

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/.github/workflows/publish.yml

@@ -13,9 +13,9 @@ jobs:
     runs-on: ubuntu-latest
     environment: pypi
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.14"
 

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/.github/workflows/test.yml

@@ -13,9 +13,9 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switchbox-flags
-Version: 0.3.0
+Version: 0.5.0
 Summary: Feature flag SDK with zero dependencies
 Project-URL: Homepage, https://github.com/ignat14/switchbox-sdk-python
 Project-URL: Repository, https://github.com/ignat14/switchbox-sdk-python

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "switchbox-flags"
-version = "0.3.0"
+version = "0.5.0"
 description = "Feature flag SDK with zero dependencies"
 readme = "README.md"
 license = "MIT"

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/switchbox/__init__.py

@@ -1,5 +1,5 @@
 from switchbox.client import Switchbox
 from switchbox.exceptions import SwitchboxError
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 __all__ = ["Switchbox", "SwitchboxError"]

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/switchbox/evaluator.py

@@ -7,7 +7,7 @@ import hashlib
 import re
 from typing import Any
 
-from switchbox.models import Flag, Rule
+from switchbox.models import Flag, Rule, RuleGroup
 
 # Leading numeric prefix, matching JS parseFloat (e.g. "25px" -> 25, "1e3" -> 1000).
 _NUMERIC_PREFIX = re.compile(r"[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?")
@@ -65,11 +65,11 @@ def evaluate(flag: Flag, user_context: dict | None = None) -> bool | str | int |
                 return _enabled_value(flag)
             return flag.default_value
 
-        # 3. Check rules (OR logic — any match wins)
-        if flag.rules:
-            for rule in flag.rules:
-                if _match_rule(rule, user_context):
-                    return _enabled_value(flag)
+        # 3. Check rule groups: OR across groups, AND within a group (two-level
+        #    DNF). Any matching group wins.
+        for group in _to_groups(flag.rules):
+            if _match_group(group, user_context):
+                return _enabled_value(flag)
 
         # 4. Rollout. Resolve the id with a null-only fallback (JS `??`, not
         # `or`): an empty-string user_id is a real id, not falsy.
@@ -88,10 +88,38 @@ def evaluate(flag: Flag, user_context: dict | None = None) -> bool | str | int |
 
 
 def _enabled_value(flag: Flag) -> bool | str | int | Any:
-    """Return the appropriate 'enabled' value based on flag type."""
+    """The value served to matched / in-rollout users.
+
+    Boolean flags serve ``True``. Non-boolean flags serve ``enabled_value``
+    (variations, ADR-017), falling back to ``default_value`` when it's unset —
+    so a config without ``enabled_value`` behaves exactly as before. Fallback is
+    at evaluation time (not parse time) so directly-constructed Flags work too,
+    matching the JS SDK's ``?? default_value``."""
     if flag.flag_type == "boolean":
         return True
-    return flag.default_value
+    return flag.enabled_value if flag.enabled_value is not None else flag.default_value
+
+
+def _to_groups(rules: list) -> list[RuleGroup]:
+    """Normalise a flag's rules into RuleGroups. ``from_dict`` already yields
+    RuleGroups; this also tolerates a flat list of ``Rule`` (legacy/direct
+    construction) — each becomes its own single-condition group, preserving the
+    old OR semantics. Idempotent."""
+    groups: list[RuleGroup] = []
+    for r in rules:
+        if isinstance(r, RuleGroup):
+            groups.append(r)
+        elif isinstance(r, Rule):
+            groups.append(RuleGroup(conditions=[r]))
+    return groups
+
+
+def _match_group(group: RuleGroup, user_context: dict) -> bool:
+    """A group matches when ALL its conditions match (AND). An empty group
+    matches no one (never 'match all')."""
+    return bool(group.conditions) and all(
+        _match_rule(c, user_context) for c in group.conditions
+    )
 
 
 def _match_rule(rule: Rule, user_context: dict) -> bool:

switchbox_flags-0.5.0/switchbox/models.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Rule:
+    """A single condition. The atom of targeting."""
+
+    attribute: str
+    operator: str  # equals | not_equals | contains | ends_with | in_list | gt | lt
+    value: Any
+
+
+@dataclass
+class RuleGroup:
+    """An AND-group of conditions. Groups are OR'd by the evaluator — two-level
+    DNF (ADR-015): a flag matches if any group matches; a group matches if all
+    its conditions match."""
+
+    conditions: list[Rule] = field(default_factory=list)
+
+
+@dataclass
+class Flag:
+    key: str
+    enabled: bool
+    rollout_pct: int
+    flag_type: str  # boolean | string | number | json
+    default_value: Any
+    # The "on"/matched value for non-boolean flags (variations, ADR-017). None
+    # means "unset" — the evaluator falls back to default_value, so configs
+    # without this key behave exactly as before. Boolean flags ignore it.
+    enabled_value: Any = None
+    rules: list[RuleGroup] = field(default_factory=list)
+
+
+def _parse_condition(d: dict) -> Rule:
+    return Rule(attribute=d["attribute"], operator=d["operator"], value=d["value"])
+
+
+def _parse_rule_group(entry: dict) -> RuleGroup:
+    """Parse one rules entry, accepting the two-level shape
+    ``{"conditions": [...]}`` and the legacy flat ``{attribute, operator, value}``
+    (a pre-DNF config) — the latter becomes a single-condition group."""
+    if "conditions" in entry:
+        return RuleGroup(conditions=[_parse_condition(c) for c in entry["conditions"]])
+    return RuleGroup(conditions=[_parse_condition(entry)])
+
+
+@dataclass
+class FlagConfig:
+    version: str  # ISO timestamp
+    flags: dict[str, Flag] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FlagConfig:
+        """Parse the CDN JSON into a FlagConfig object."""
+        flags = {}
+        for key, flag_data in data.get("flags", {}).items():
+            rules = [_parse_rule_group(r) for r in flag_data.get("rules", [])]
+            flags[key] = Flag(
+                key=key,
+                enabled=flag_data["enabled"],
+                rollout_pct=flag_data.get("rollout_pct", 0),
+                flag_type=flag_data.get("flag_type", "boolean"),
+                default_value=flag_data.get("default_value"),
+                enabled_value=flag_data.get("enabled_value"),
+                rules=rules,
+            )
+        return cls(version=data.get("version", ""), flags=flags)

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/tests/parity_vectors.json

@@ -28,6 +28,18 @@
     {"name": "has user_id, rollout 0, no match -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "x"}, "expected": false},
     {"name": "user context without id, rollout 100 -> enabled (ADR-008)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"plan": "pro"}, "expected": true},
     {"name": "user context without id, rollout 50 -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 50, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"plan": "pro"}, "expected": false},
-    {"name": "empty-string user_id is treated as present (rollout 100)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "", "id": "ignored"}, "expected": true}
+    {"name": "empty-string user_id is treated as present (rollout 100)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "", "id": "ignored"}, "expected": true},
+    {"name": "DNF: AND-group with all conditions matching -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}, {"attribute": "device", "operator": "equals", "value": "mobile"}]}]}, "user": {"country": "US", "device": "mobile"}, "expected": true},
+    {"name": "DNF: AND-group with one failing condition -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}, {"attribute": "device", "operator": "equals", "value": "mobile"}]}]}, "user": {"country": "US", "device": "desktop"}, "expected": false},
+    {"name": "DNF: second group matches (OR across groups) -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}]}, {"conditions": [{"attribute": "plan", "operator": "equals", "value": "ent"}]}]}, "user": {"plan": "ent"}, "expected": true},
+    {"name": "DNF: no group matches (OR across groups) -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}]}, {"conditions": [{"attribute": "plan", "operator": "equals", "value": "ent"}]}]}, "user": {"plan": "free", "country": "EU"}, "expected": false},
+    {"name": "DNF: empty-conditions group never matches -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": []}]}, "user": {"any": "thing"}, "expected": false},
+    {"name": "DNF back-compat: legacy flat rule still matches -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}, "user": {"plan": "pro"}, "expected": true},
+    {"name": "variation: string flag rule match serves enabled_value", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "string", "default_value": "Shop", "enabled_value": "Buy now", "rules": [{"conditions": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}]}, "user": {"plan": "pro", "user_id": "u1"}, "expected": "Buy now"},
+    {"name": "variation: string flag no match serves default_value", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "string", "default_value": "Shop", "enabled_value": "Buy now", "rules": [{"conditions": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}]}, "user": {"plan": "free", "user_id": "u1"}, "expected": "Shop"},
+    {"name": "variation: absent enabled_value falls back to default on match", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "string", "default_value": "Shop", "rules": [{"conditions": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}]}, "user": {"plan": "pro", "user_id": "u1"}, "expected": "Shop"},
+    {"name": "variation: number flag rollout 100 no context serves enabled_value", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "number", "default_value": 0, "enabled_value": 42, "rules": []}, "user": null, "expected": 42},
+    {"name": "variation: disabled non-boolean serves default_value", "flag_key": "f", "flag": {"enabled": false, "rollout_pct": 100, "flag_type": "string", "default_value": "Shop", "enabled_value": "Buy now", "rules": []}, "user": {"user_id": "u1"}, "expected": "Shop"},
+    {"name": "variation: boolean flag ignores enabled_value (serves true)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "boolean", "default_value": false, "enabled_value": "ignored", "rules": []}, "user": null, "expected": true}
   ]
 }

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/tests/test_models.py

@@ -22,8 +22,9 @@ def test_flag_config_from_dict_valid():
     flag = config.flags["feature_a"]
     assert flag.enabled is True
     assert flag.rollout_pct == 50
+    # Legacy flat rule is parsed into a single-condition group (back-compat).
     assert len(flag.rules) == 1
-    assert flag.rules[0].attribute == "country"
+    assert flag.rules[0].conditions[0].attribute == "country"
 
 
 def test_flag_config_from_dict_missing_fields():
@@ -69,6 +70,31 @@ def test_flag_config_from_dict_with_rules():
     assert len(config.flags["f"].rules) == 2
 
 
+def test_flag_config_from_dict_with_dnf_groups():
+    """The two-level shape: a group with multiple AND'd conditions."""
+    data = {
+        "version": "v1",
+        "flags": {
+            "f": {
+                "enabled": True,
+                "rules": [
+                    {
+                        "conditions": [
+                            {"attribute": "country", "operator": "equals", "value": "US"},
+                            {"attribute": "device", "operator": "equals", "value": "mobile"},
+                        ]
+                    },
+                    {"conditions": [{"attribute": "plan", "operator": "equals", "value": "ent"}]},
+                ],
+            }
+        },
+    }
+    flag = FlagConfig.from_dict(data).flags["f"]
+    assert len(flag.rules) == 2  # two groups (OR)
+    assert len(flag.rules[0].conditions) == 2  # AND within the first group
+    assert flag.rules[1].conditions[0].attribute == "plan"
+
+
 def test_flag_defaults():
     flag = Flag(key="f", enabled=True, rollout_pct=100, flag_type="boolean", default_value=False)
     assert flag.rules == []

{switchbox_flags-0.3.0 → switchbox_flags-0.5.0}/uv.lock

@@ -236,7 +236,7 @@ wheels = [
 
 [[package]]
 name = "switchbox-flags"
-version = "0.3.0"
+version = "0.5.0"
 source = { editable = "." }
 
 [package.optional-dependencies]

switchbox_flags-0.3.0/switchbox/models.py

@@ -1,50 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Any
-
-
-@dataclass
-class Rule:
-    attribute: str
-    operator: str  # equals | not_equals | contains | ends_with | in_list | gt | lt
-    value: Any
-
-
-@dataclass
-class Flag:
-    key: str
-    enabled: bool
-    rollout_pct: int
-    flag_type: str  # boolean | string | number | json
-    default_value: Any
-    rules: list[Rule] = field(default_factory=list)
-
-
-@dataclass
-class FlagConfig:
-    version: str  # ISO timestamp
-    flags: dict[str, Flag] = field(default_factory=dict)
-
-    @classmethod
-    def from_dict(cls, data: dict) -> FlagConfig:
-        """Parse the CDN JSON into a FlagConfig object."""
-        flags = {}
-        for key, flag_data in data.get("flags", {}).items():
-            rules = [
-                Rule(
-                    attribute=r["attribute"],
-                    operator=r["operator"],
-                    value=r["value"],
-                )
-                for r in flag_data.get("rules", [])
-            ]
-            flags[key] = Flag(
-                key=key,
-                enabled=flag_data["enabled"],
-                rollout_pct=flag_data.get("rollout_pct", 0),
-                flag_type=flag_data.get("flag_type", "boolean"),
-                default_value=flag_data.get("default_value"),
-                rules=rules,
-            )
-        return cls(version=data.get("version", ""), flags=flags)