flagsmith-sql-flag-engine 0.1.0__tar.gz

flagsmith_sql_flag_engine-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: flagsmith-sql-flag-engine
+Version: 0.1.0
+Summary: SQL translator for Flagsmith segment predicates.
+Author: Flagsmith
+Author-email: Flagsmith <engineering@flagsmith.com>
+License-Expression: BSD-3-Clause
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: SQL
+Classifier: Topic :: Database
+Requires-Dist: flagsmith-flag-engine>=10
+Requires-Dist: jsonpath-rfc9535>=0.2
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/Flagsmith/flagsmith-sql-flag-engine
+Description-Content-Type: text/markdown
+
+# flagsmith-sql-flag-engine
+
+SQL translator for Flagsmith segment predicates.
+
+Where the Python and Rust `flag_engine` implementations evaluate
+`is_context_in_segment` against an in-memory `EvaluationContext`, this
+package takes a `SegmentContext` and emits a SQL `WHERE` expression that
+evaluates the segment against an entire `IDENTITIES` table — one row per
+identity, with the identity's full trait map held in a single column
+the translator path-extracts at query time. `PERCENTAGE_SPLIT` and
+`:semver`-marked comparators compile to inline pure-SQL.
+
+## Quickstart
+
+```python
+from flag_engine.context.types import EvaluationContext, SegmentContext
+
+from flagsmith_sql_flag_engine import TranslateContext, translate_segment
+from flagsmith_sql_flag_engine.dialects import ClickHouseDialect
+
+eval_context: EvaluationContext = {
+    "environment": {"key": "n9fbf9...3ngWhb", "name": "Production"},
+}
+ctx = TranslateContext(evaluation_context=eval_context, dialect=ClickHouseDialect())
+
+segment: SegmentContext = {
+    "key": "growth-cohort",
+    "name": "Growth cohort",
+    "rules": [
+        {
+            "type": "ALL",
+            "conditions": [
+                {"operator": "EQUAL", "property": "plan", "value": "growth"},
+            ],
+        },
+    ],
+}
+where_expr = translate_segment(segment, ctx)
+# where_expr is a SQL string. Drop into:
+#   SELECT COUNT(*) FROM IDENTITIES i
+#   WHERE i.environment_id = 'n9fbf9...3ngWhb' AND ({where_expr})
+```
+
+`environment_id` in the `IDENTITIES` table is a string column holding
+`EnvironmentContext.key` directly — the same identifier the engine uses,
+no separate integer PK.
+
+`translate_segment` returns `None` if the segment uses an operator the
+translator can't handle — typically a REGEX pattern the active dialect's
+regex flavour can't compile. Callers should fall back to
+`flag_engine.is_context_in_segment` for those segments.
+
+## Schema
+
+Each dialect publishes the table layout it expects via a `schema_ddl`
+constant. For ClickHouse:
+
+```sql
+CREATE TABLE IF NOT EXISTS IDENTITIES (
+    environment_id String,
+    id UInt64,
+    identifier String,
+    identity_key String,
+    traits JSON
+)
+ENGINE = MergeTree()
+ORDER BY (environment_id, id);
+```
+
+Traits live in a single `JSON` column (CH 24+, GA in 25.x). Each key is
+stored as a typed subcolumn, so trait reads are direct columnar scans
+rather than per-row JSON parses. Trait keys are *data* — new keys appear
+without schema changes — and the translator only sees the abstract path
+extraction.
+
+ClickHouse Cloud requires `SET allow_experimental_json_type = 1` when
+creating a `JSON`-column table (the type is GA on OSS 25.x); the test
+harness applies this setting automatically.
+
+Programmatic access:
+
+```python
+from flagsmith_sql_flag_engine.dialects.clickhouse import SCHEMA_DDL
+```
+
+## Engine parity
+
+Validated against [Flagsmith/engine-test-data](https://github.com/Flagsmith/engine-test-data),
+the test suite every engine implementation is checked against. The
+engine-parity suite loads each test case's identity into a per-dialect
+scratch table, translates the case's segments, runs the generated SQL,
+and compares to `flag_engine.is_context_in_segment`.
+
+To run the engine-parity suite locally:
+
+```bash
+git submodule update --init                 # pull engine-test-data
+docker compose up --detach --wait clickhouse
+uv run pytest tests/test_engine.py
+```
+
+Adding a new dialect's parity coverage is one harness module — see
+`tests/harnesses/` for the shape.
+
+## Dialects
+
+The translator is dialect-aware: a `Dialect` protocol abstracts the
+SQL fragments that differ across SQL engines — MD5 hex, hex-to-int
+parsing, prefix-anchored regex, padded-version comparison, type-aware
+trait predicates, regex flavour. Today `ClickHouseDialect` is the only
+implementation; adding another engine such as Snowflake, DuckDB or
+Postgres means writing one class.
+
+## Operator coverage
+
+| Operator                                     | Translatable | Notes                                                          |
+| -------------------------------------------- | :----------: | -------------------------------------------------------------- |
+| `EQUAL`, `NOT_EQUAL`, `IN`                   |     yes      |                                                                |
+| `IS_SET`, `IS_NOT_SET`                       |     yes      | trait subcolumn `IS NOT NULL` / `IS NULL`                      |
+| `CONTAINS`, `NOT_CONTAINS`                   |     yes      |                                                                |
+| `GREATER_THAN`, `LESS_THAN` plus `_INCLUSIVE`|     yes      |                                                                |
+| `MODULO`                                     |     yes      |                                                                |
+| `PERCENTAGE_SPLIT`                           |     yes      | inlined MD5-mod-9999; ~0.005% diverge on hash==9998            |
+| `REGEX`                                      |   partial    | dialect-flavour gated; unsupported patterns → caller fallback  |
+| `:semver`-marked comparators                 |     yes      | major.minor.patch only; ignores prerelease                     |
+
+## Development
+
+```bash
+make install                  # uv sync + pre-commit install
+make lint                     # run pre-commit hooks across the tree
+make typecheck                # mypy
+make test                     # unit tests
+```
+
+Ruff (lint + format) runs as a pre-commit hook on every commit. Mypy
+runs as a `make typecheck` hook on staged Python files.

flagsmith_sql_flag_engine-0.1.0/README.md

@@ -0,0 +1,137 @@
+# flagsmith-sql-flag-engine
+
+SQL translator for Flagsmith segment predicates.
+
+Where the Python and Rust `flag_engine` implementations evaluate
+`is_context_in_segment` against an in-memory `EvaluationContext`, this
+package takes a `SegmentContext` and emits a SQL `WHERE` expression that
+evaluates the segment against an entire `IDENTITIES` table — one row per
+identity, with the identity's full trait map held in a single column
+the translator path-extracts at query time. `PERCENTAGE_SPLIT` and
+`:semver`-marked comparators compile to inline pure-SQL.
+
+## Quickstart
+
+```python
+from flag_engine.context.types import EvaluationContext, SegmentContext
+
+from flagsmith_sql_flag_engine import TranslateContext, translate_segment
+from flagsmith_sql_flag_engine.dialects import ClickHouseDialect
+
+eval_context: EvaluationContext = {
+    "environment": {"key": "n9fbf9...3ngWhb", "name": "Production"},
+}
+ctx = TranslateContext(evaluation_context=eval_context, dialect=ClickHouseDialect())
+
+segment: SegmentContext = {
+    "key": "growth-cohort",
+    "name": "Growth cohort",
+    "rules": [
+        {
+            "type": "ALL",
+            "conditions": [
+                {"operator": "EQUAL", "property": "plan", "value": "growth"},
+            ],
+        },
+    ],
+}
+where_expr = translate_segment(segment, ctx)
+# where_expr is a SQL string. Drop into:
+#   SELECT COUNT(*) FROM IDENTITIES i
+#   WHERE i.environment_id = 'n9fbf9...3ngWhb' AND ({where_expr})
+```
+
+`environment_id` in the `IDENTITIES` table is a string column holding
+`EnvironmentContext.key` directly — the same identifier the engine uses,
+no separate integer PK.
+
+`translate_segment` returns `None` if the segment uses an operator the
+translator can't handle — typically a REGEX pattern the active dialect's
+regex flavour can't compile. Callers should fall back to
+`flag_engine.is_context_in_segment` for those segments.
+
+## Schema
+
+Each dialect publishes the table layout it expects via a `schema_ddl`
+constant. For ClickHouse:
+
+```sql
+CREATE TABLE IF NOT EXISTS IDENTITIES (
+    environment_id String,
+    id UInt64,
+    identifier String,
+    identity_key String,
+    traits JSON
+)
+ENGINE = MergeTree()
+ORDER BY (environment_id, id);
+```
+
+Traits live in a single `JSON` column (CH 24+, GA in 25.x). Each key is
+stored as a typed subcolumn, so trait reads are direct columnar scans
+rather than per-row JSON parses. Trait keys are *data* — new keys appear
+without schema changes — and the translator only sees the abstract path
+extraction.
+
+ClickHouse Cloud requires `SET allow_experimental_json_type = 1` when
+creating a `JSON`-column table (the type is GA on OSS 25.x); the test
+harness applies this setting automatically.
+
+Programmatic access:
+
+```python
+from flagsmith_sql_flag_engine.dialects.clickhouse import SCHEMA_DDL
+```
+
+## Engine parity
+
+Validated against [Flagsmith/engine-test-data](https://github.com/Flagsmith/engine-test-data),
+the test suite every engine implementation is checked against. The
+engine-parity suite loads each test case's identity into a per-dialect
+scratch table, translates the case's segments, runs the generated SQL,
+and compares to `flag_engine.is_context_in_segment`.
+
+To run the engine-parity suite locally:
+
+```bash
+git submodule update --init                 # pull engine-test-data
+docker compose up --detach --wait clickhouse
+uv run pytest tests/test_engine.py
+```
+
+Adding a new dialect's parity coverage is one harness module — see
+`tests/harnesses/` for the shape.
+
+## Dialects
+
+The translator is dialect-aware: a `Dialect` protocol abstracts the
+SQL fragments that differ across SQL engines — MD5 hex, hex-to-int
+parsing, prefix-anchored regex, padded-version comparison, type-aware
+trait predicates, regex flavour. Today `ClickHouseDialect` is the only
+implementation; adding another engine such as Snowflake, DuckDB or
+Postgres means writing one class.
+
+## Operator coverage
+
+| Operator                                     | Translatable | Notes                                                          |
+| -------------------------------------------- | :----------: | -------------------------------------------------------------- |
+| `EQUAL`, `NOT_EQUAL`, `IN`                   |     yes      |                                                                |
+| `IS_SET`, `IS_NOT_SET`                       |     yes      | trait subcolumn `IS NOT NULL` / `IS NULL`                      |
+| `CONTAINS`, `NOT_CONTAINS`                   |     yes      |                                                                |
+| `GREATER_THAN`, `LESS_THAN` plus `_INCLUSIVE`|     yes      |                                                                |
+| `MODULO`                                     |     yes      |                                                                |
+| `PERCENTAGE_SPLIT`                           |     yes      | inlined MD5-mod-9999; ~0.005% diverge on hash==9998            |
+| `REGEX`                                      |   partial    | dialect-flavour gated; unsupported patterns → caller fallback  |
+| `:semver`-marked comparators                 |     yes      | major.minor.patch only; ignores prerelease                     |
+
+## Development
+
+```bash
+make install                  # uv sync + pre-commit install
+make lint                     # run pre-commit hooks across the tree
+make typecheck                # mypy
+make test                     # unit tests
+```
+
+Ruff (lint + format) runs as a pre-commit hook on every commit. Mypy
+runs as a `make typecheck` hook on staged Python files.

flagsmith_sql_flag_engine-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "flagsmith-sql-flag-engine"
+version = "0.1.0"
+description = "SQL translator for Flagsmith segment predicates."
+readme = "README.md"
+authors = [{ name = "Flagsmith", email = "engineering@flagsmith.com" }]
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+classifiers = [
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: SQL",
+    "Topic :: Database",
+]
+dependencies = ["flagsmith-flag-engine>=10", "jsonpath-rfc9535>=0.2"]
+
+[project.urls]
+Homepage = "https://github.com/Flagsmith/flagsmith-sql-flag-engine"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-xdist>=3",
+    "mypy>=1.10",
+    "prek>=0.3",
+    "clickhouse-connect>=0.7",
+    "json5>=0.14.0",
+    "pytest-cov>=7.1.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.14,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = [
+    "-ra",
+    "--cov",
+    "src",
+    "--cov-report",
+    "term-missing",
+    "--cov-report",
+    "xml",
+]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+
+[tool.coverage.report]
+# `match` statements exhaustive over a Literal type record a phantom
+# fall-through branch from the last case to function exit; coverage.py
+# can't see the type-system exhaustiveness mypy enforces. Treat any
+# `case` line as a possibly-partial branch so the gate stays at 100%
+# without us littering the source with `# pragma: no branch`.
+partial_branches = [
+    "pragma: no branch",
+    "case .+:",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src/flagsmith_sql_flag_engine", "tests"]
+
+[[tool.mypy.overrides]]
+module = "clickhouse_connect.*"
+ignore_missing_imports = true

flagsmith_sql_flag_engine-0.1.0/src/flagsmith_sql_flag_engine/__init__.py

@@ -0,0 +1,28 @@
+"""SQL translator for Flagsmith segment predicates.
+
+Public API:
+    translate_segment(segment, ctx) -> str | None
+    TranslateContext
+
+See README.md for usage. The translator is dialect-aware via the `Dialect`
+protocol; `flagsmith_sql_flag_engine.dialects.clickhouse.ClickHouseDialect`
+is the only implementation today.
+"""
+
+from flagsmith_sql_flag_engine.dialect import Dialect
+from flagsmith_sql_flag_engine.translator import (
+    TRANSLATABLE_OPERATORS,
+    TranslateContext,
+    translate_condition,
+    translate_rule,
+    translate_segment,
+)
+
+__all__ = [
+    "TRANSLATABLE_OPERATORS",
+    "Dialect",
+    "TranslateContext",
+    "translate_condition",
+    "translate_rule",
+    "translate_segment",
+]

flagsmith_sql_flag_engine-0.1.0/src/flagsmith_sql_flag_engine/dialect.py

@@ -0,0 +1,125 @@
+"""Per-dialect SQL fragments — MD5 hex, hex-to-int parsing, prefix-anchored
+regex, padded-version comparison, type-aware trait predicates, regex flavour."""
+
+from typing import Protocol
+
+
+class Dialect(Protocol):
+    """Per-dialect SQL fragments.
+
+    Methods return SQL string fragments. Inputs are already-formatted SQL
+    strings (column refs, string literals); the dialect only chooses the
+    right syntax for the operation.
+    """
+
+    name: str  # human-readable, used in test ids and error messages
+
+    # --- IDENTITIES schema access ---
+    #
+    # The dialect owns the canonical IDENTITIES schema, see `schema_ddl`,
+    # so it also owns the SQL expression for each logical column. The
+    # translator just hands over an alias.
+
+    def identifier_expr(self, alias: str) -> str:
+        """SQL expression for `$.identity.identifier`."""
+        ...
+
+    def identity_key_expr(self, alias: str) -> str:
+        """SQL expression for `$.identity.key`."""
+        ...
+
+    def trait_path(self, alias: str, trait_key: str) -> str:
+        """Path-extract a trait value from the IDENTITIES traits container.
+
+        The path syntax varies by SQL engine.
+        """
+        ...
+
+    def trait_eq(self, alias: str, trait_key: str, value: object, negate: bool) -> str:
+        """Type-aware EQUAL / NOT_EQUAL predicate on a trait, mirroring
+        `flag_engine`'s per-type coercion: the segment value is cast to
+        the trait's runtime type before compare, and a cast failure
+        means no match for both ops. Implementation is dialect-specific
+        because trait-type discrimination and runtime type-coercion
+        casts both vary by engine.
+        """
+        ...
+
+    def trait_in(self, alias: str, trait_key: str, items: list[str]) -> str:
+        """Type-aware IN predicate on a trait, mirroring engine semantics:
+        string trait does direct lookup; integer trait stringifies and
+        looks up; other trait types never match. `items` is the parsed
+        candidate list per `flag_engine`'s `_get_in_values`.
+        """
+        ...
+
+    # --- string operations ---
+
+    def position(self, needle_lit: str, haystack_expr: str) -> str:
+        """Boolean: does the string literal `needle_lit` appear in
+        `haystack_expr`? Used for CONTAINS / NOT_CONTAINS."""
+        ...
+
+    def lpad(self, expr: str, width: int, pad_lit: str) -> str:
+        """Left-pad `expr` to `width` using `pad_lit`."""
+        ...
+
+    def coalesce(self, *exprs: str) -> str:
+        """COALESCE/NVL-style: first non-null."""
+        ...
+
+    # --- regex ---
+
+    def regex_supports(self, pattern: str) -> bool:
+        """Return True if this dialect's regex engine can compile
+        `pattern`. The translator falls back to `None` for any REGEX
+        condition where this returns False, letting the caller defer
+        to `flag_engine`."""
+        ...
+
+    def regexp_anchored_match(self, value_expr: str, pattern: str) -> str:
+        """Boolean: equivalent to Python `re.match(pattern, value)` —
+        anchored at position 0, may be a prefix of the value, not a
+        full-match.
+
+        `pattern` is the raw Python regex string; the dialect handles
+        its own escaping into a SQL literal, since regex flavours
+        differ in how backslashes are treated."""
+        ...
+
+    def regexp_nth_digit_run(self, value_expr: str, n: int) -> str:
+        """Extract the n-th sequence of digits from `value_expr`. Returns NULL
+        if there are fewer than n digit runs. Used for semver."""
+        ...
+
+    # --- hashing primitives for PERCENTAGE_SPLIT ---
+
+    def md5_hex(self, expr: str) -> str:
+        """SQL fragment producing the lowercase 32-char hex MD5 digest."""
+        ...
+
+    def parse_hex_chunk(self, hex_expr: str, start: int, length: int = 8) -> str:
+        """Parse `length` hex characters of `hex_expr` starting at 1-indexed
+        `start` into a non-negative integer."""
+        ...
+
+    # --- type casts ---
+
+    def cast_string(self, expr: str) -> str:
+        """Cast `expr` to STRING / VARCHAR."""
+        ...
+
+    def cast_float(self, expr: str) -> str:
+        """Cast `expr` to a 64-bit float / DOUBLE."""
+        ...
+
+    def cast_number(self, expr: str) -> str:
+        """Cast `expr` to a NUMBER / BIGINT — the engine-side numeric
+        type used for modulo arithmetic."""
+        ...
+
+    # --- composition ---
+
+    def mod(self, dividend: str, divisor: str) -> str:
+        """`dividend MOD divisor` returning a numeric value."""
+        ...

flagsmith_sql_flag_engine-0.1.0/src/flagsmith_sql_flag_engine/dialects/__init__.py

@@ -0,0 +1,5 @@
+"""Dialect implementations."""
+
+from flagsmith_sql_flag_engine.dialects.clickhouse import ClickHouseDialect
+
+__all__ = ["ClickHouseDialect"]