sqlrules-mssql 1.0.0__tar.gz → 2.0.0__tar.gz

{sqlrules_mssql-1.0.0 → sqlrules_mssql-2.0.0}/.gitignore

@@ -11,6 +11,7 @@ __pycache__/
 htmlcov/
 dist/
 dist-plugins/
+dist-missing/
 build/
 *.egg-info/
 .DS_Store

sqlrules_mssql-2.0.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: sqlrules-mssql
+Version: 2.0.0
+Summary: SQL Server dialect plugin for SQLRules (JSON and LEN string ops).
+Project-URL: Homepage, https://github.com/eddiethedean/sqlrules
+Project-URL: Repository, https://github.com/eddiethedean/sqlrules
+Project-URL: Issues, https://github.com/eddiethedean/sqlrules/issues
+Author: SQLRules Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mssql,pydantic,sqlalchemy,sqlrules,sqlserver
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: sqlalchemy<3,>=2.0
+Requires-Dist: sqlrules<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sqlrules-mssql
+
+SQL Server backend provider for [SQLRules](https://github.com/eddiethedean/sqlrules).
+The package version follows the core 2.x line.
+
+## Install
+
+```bash
+pip install "sqlrules>=2,<3" "sqlrules-mssql>=2,<3"
+```
+
+## Use
+
+```python
+from typing import Annotated, Any
+
+from pydantic import Field
+from sqlalchemy import Column, MetaData, String, Table
+
+from sqlrules import Compiler, JsonContains, JsonHasKey, RuleSchema, where
+from sqlrules_mssql import MssqlPlugin
+
+rows = Table(
+    "rows",
+    MetaData(),
+    Column("name", String),
+    Column("meta", String),  # SQL Server stores JSON documents in text columns.
+)
+
+
+class RowRules(RuleSchema):
+    name: Annotated[str, Field(min_length=2, max_length=40)]
+    meta: Annotated[dict[str, Any], JsonContains({"active": True}), JsonHasKey("active")]
+
+
+provider = MssqlPlugin(server_version=(16, 0), compatibility_level=160)
+compiled = Compiler(plugins=[provider]).compile(RowRules, rows)
+statement = rows.select().where(*where(compiled))
+```
+
+## Capabilities
+
+- SQL Server `LEN` length constraints
+- Guarded JSON helpers for text columns validated with `ISJSON` (`server_version` >= 13 and explicit `compatibility_level` >= 130)
+- `JsonContains` supports null, boolean, and string values; nested objects and arrays compare structurally, while numeric JSON values raise `CapabilityError` because exact numeric equality cannot be guaranteed from `OPENJSON` text values
+- Safe lax text-to-int/float conversions on SQL Server 2012+
+- No built-in regex translator
+- Text-to-Decimal is a compile-time capability error
+
+String Literal and Enum fields require an explicit binary or
+case-sensitive collation. See the [type support matrix](https://sqlrules.readthedocs.io/en/latest/TYPE_SUPPORT.html).

sqlrules_mssql-2.0.0/README.md

@@ -0,0 +1,51 @@
+# sqlrules-mssql
+
+SQL Server backend provider for [SQLRules](https://github.com/eddiethedean/sqlrules).
+The package version follows the core 2.x line.
+
+## Install
+
+```bash
+pip install "sqlrules>=2,<3" "sqlrules-mssql>=2,<3"
+```
+
+## Use
+
+```python
+from typing import Annotated, Any
+
+from pydantic import Field
+from sqlalchemy import Column, MetaData, String, Table
+
+from sqlrules import Compiler, JsonContains, JsonHasKey, RuleSchema, where
+from sqlrules_mssql import MssqlPlugin
+
+rows = Table(
+    "rows",
+    MetaData(),
+    Column("name", String),
+    Column("meta", String),  # SQL Server stores JSON documents in text columns.
+)
+
+
+class RowRules(RuleSchema):
+    name: Annotated[str, Field(min_length=2, max_length=40)]
+    meta: Annotated[dict[str, Any], JsonContains({"active": True}), JsonHasKey("active")]
+
+
+provider = MssqlPlugin(server_version=(16, 0), compatibility_level=160)
+compiled = Compiler(plugins=[provider]).compile(RowRules, rows)
+statement = rows.select().where(*where(compiled))
+```
+
+## Capabilities
+
+- SQL Server `LEN` length constraints
+- Guarded JSON helpers for text columns validated with `ISJSON` (`server_version` >= 13 and explicit `compatibility_level` >= 130)
+- `JsonContains` supports null, boolean, and string values; nested objects and arrays compare structurally, while numeric JSON values raise `CapabilityError` because exact numeric equality cannot be guaranteed from `OPENJSON` text values
+- Safe lax text-to-int/float conversions on SQL Server 2012+
+- No built-in regex translator
+- Text-to-Decimal is a compile-time capability error
+
+String Literal and Enum fields require an explicit binary or
+case-sensitive collation. See the [type support matrix](https://sqlrules.readthedocs.io/en/latest/TYPE_SUPPORT.html).

{sqlrules_mssql-1.0.0 → sqlrules_mssql-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlrules-mssql"
-version = "1.0.0"
+version = "2.0.0"
 description = "SQL Server dialect plugin for SQLRules (JSON and LEN string ops)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -18,7 +18,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "sqlrules>=1,<2",
+  "sqlrules>=2,<3",
   "sqlalchemy>=2.0,<3",
 ]
 

sqlrules_mssql-2.0.0/src/sqlrules_mssql/__init__.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+from sqlalchemy import String, case, func, literal
+from sqlalchemy.sql.elements import ColumnElement
+
+from sqlrules.backend import prepare_scalar, total_predicate
+from sqlrules.errors import CapabilityError
+from sqlrules.ir import CompilationContext, PreparedValue, RuleField
+from sqlrules.plugins import PLUGIN_API_VERSION
+from sqlrules.translators import TranslatorRegistry
+from sqlrules_mssql.json import translate_json_contains, translate_json_has_key
+from sqlrules_mssql.length import translate_max_length, translate_min_length
+
+__version__ = "2.0.0"
+
+
+class MssqlPlugin:
+    """Register SQL Server constraint translators.
+
+    Does not register ``pattern`` — SQL Server has no portable regex operator
+    that SQLRules can emit deterministically. Provide a custom translator if
+    needed. Scalar types are prepared by the backend provider.
+    """
+
+    name = "mssql"
+    api_version = PLUGIN_API_VERSION
+
+    def __init__(
+        self,
+        *,
+        server_version: tuple[int, ...] | None = None,
+        compatibility_level: int | None = None,
+    ) -> None:
+        self.server_version = tuple(server_version) if server_version is not None else None
+        self.compatibility_level = compatibility_level
+
+    def capabilities(self) -> Mapping[str, Any]:
+        return {
+            "backend": self.name,
+            "server_version": self.server_version,
+            "compatibility_level": self.compatibility_level,
+            "json_markers_supported": self.server_version is not None
+            and self.server_version >= (13, 0)
+            and self.compatibility_level is not None
+            and self.compatibility_level >= 130,
+            "native_scalar_types": (
+                "bool",
+                "int",
+                "float",
+                "decimal",
+                "str",
+                "date",
+                "datetime",
+                "time",
+                "uuid",
+            ),
+            "safe_text_numeric_conversion": self.server_version is not None
+            and self.server_version >= (11, 0),
+            "safe_text_numeric_targets": (
+                ("int", "float")
+                if self.server_version is not None and self.server_version >= (11, 0)
+                else ()
+            ),
+            "assumptions": (
+                "TRY_CAST provides safe numeric conversion on SQL Server 2012 and newer.",
+                "Text-to-numeric conversion is accepted only when TRY_CAST succeeds.",
+            ),
+        }
+
+    def prepare_value(
+        self,
+        column: Any,
+        field: RuleField,
+        context: CompilationContext,
+    ) -> PreparedValue:
+        if field.python_type is dict and any(
+            item.operator in {"json_contains", "json_has_key"} for item in field.constraints
+        ):
+            if self.server_version is None or self.server_version < (13, 0):
+                raise CapabilityError(
+                    self.name,
+                    field.name,
+                    "json",
+                    type(column.type).__name__,
+                    "SQL Server JSON markers require SQL Server 2016 or newer; "
+                    "pass server_version explicitly.",
+                )
+            if self.compatibility_level is None or self.compatibility_level < 130:
+                raise CapabilityError(
+                    self.name,
+                    field.name,
+                    "json",
+                    type(column.type).__name__,
+                    "OPENJSON requires database compatibility level 130 or higher; "
+                    "pass compatibility_level explicitly.",
+                )
+            source_name = type(column.type).__name__.lower()
+            if not isinstance(column.type, String) and "json" not in source_name:
+                raise CapabilityError(
+                    self.name,
+                    field.name,
+                    "json",
+                    source_name,
+                    "SQL Server JSON markers require a text or JSON column.",
+                )
+            valid = total_predicate(func.isjson(column) == 1)
+            safe_json = case((valid, column), else_=literal("{}"))
+            return PreparedValue(
+                source=column,
+                value=cast(ColumnElement[Any], safe_json),
+                valid=valid,
+                is_null=cast(ColumnElement[bool], column.is_(None)),
+                logical_type="json",
+                coercion="validated-json-text",
+                capability="isjson-guarded",
+            )
+        return prepare_scalar(column, field, context, backend=self.name)
+
+    def register(self, registry: TranslatorRegistry) -> None:
+        registry.register_constraint(
+            "min_length",
+            translate_min_length,
+            on_conflict="replace",
+        )
+        registry.register_constraint(
+            "max_length",
+            translate_max_length,
+            on_conflict="replace",
+        )
+        registry.register_constraint(
+            "json_contains",
+            translate_json_contains,
+            on_conflict="replace",
+        )
+        registry.register_constraint(
+            "json_has_key",
+            translate_json_has_key,
+            on_conflict="replace",
+        )
+
+
+__all__ = [
+    "MssqlPlugin",
+    "__version__",
+    "translate_json_contains",
+    "translate_json_has_key",
+    "translate_max_length",
+    "translate_min_length",
+]

sqlrules_mssql-2.0.0/src/sqlrules_mssql/json.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from sqlalchemy import Integer, String, Unicode, and_, exists, func, literal, select
+from sqlalchemy import cast as sa_cast
+from sqlalchemy import column as sa_column
+from sqlalchemy.sql.elements import ColumnElement
+
+from sqlrules.errors import CapabilityError
+from sqlrules.ir import CompilationContext, Constraint
+
+
+def _json_path_for_key(key: Any) -> str:
+    """Build a JSONPath for a single object key (never a full-path escape hatch)."""
+    text = str(key)
+    # SQL Server JSON path quotes use doubled double-quotes inside the name.
+    escaped = text.replace('"', '""')
+    return f'$."{escaped}"'
+
+
+def _json_path_for_array_index(index: int) -> str:
+    """Build a JSONPath for one zero-based array element."""
+    return f"$[{index}]"
+
+
+def _exact_text_equals(
+    left: ColumnElement[Any],
+    right: ColumnElement[Any],
+) -> ColumnElement[bool]:
+    """Compare text ordinally and distinguish trailing spaces on SQL Server."""
+    left_text = sa_cast(left, Unicode()).collate("Latin1_General_100_BIN2")
+    right_text = sa_cast(right, Unicode()).collate("Latin1_General_100_BIN2")
+    return cast(
+        ColumnElement[bool],
+        (left_text == right_text) & (func.datalength(left_text) == func.datalength(right_text)),
+    )
+
+
+def _openjson_key_exists(
+    column: ColumnElement[Any],
+    key: str,
+    *,
+    json_type: int | None = None,
+) -> ColumnElement[bool]:
+    """True when OPENJSON lists ``key`` (optionally with a specific JSON type)."""
+    return _openjson_key_matches(column, key, json_type=json_type)
+
+
+def _openjson_key_matches(
+    column: ColumnElement[Any],
+    key: str,
+    *,
+    json_type: int | None = None,
+    expected_value: str | None = None,
+) -> ColumnElement[bool]:
+    """True when a top-level JSON key has the requested type and value."""
+    oj = (
+        func.openjson(column)
+        .table_valued(
+            sa_column("key", String),
+            sa_column("value", Unicode),
+            sa_column("type", Integer),
+        )
+        .alias("oj")
+    )
+    predicate = _exact_text_equals(
+        oj.c.key,
+        literal(key, type_=Unicode()),
+    )
+    if json_type is not None:
+        predicate = predicate & (oj.c.type == json_type)
+    if expected_value is not None:
+        predicate = predicate & _exact_text_equals(
+            oj.c.value,
+            literal(expected_value, type_=Unicode()),
+        )
+    return cast(ColumnElement[bool], exists(select(1).select_from(oj).where(predicate)))
+
+
+def _openjson_child_count(document: ColumnElement[Any]) -> ColumnElement[Any]:
+    children = func.openjson(document).table_valued(sa_column("key", String)).alias("children")
+    return select(func.count()).select_from(children).scalar_subquery()
+
+
+def _openjson_object_equals(
+    document: ColumnElement[Any],
+    expected: dict[Any, Any],
+    field: str,
+) -> ColumnElement[bool]:
+    parts: list[ColumnElement[bool]] = [
+        cast(ColumnElement[bool], _openjson_child_count(document) == len(expected))
+    ]
+    parts.extend(
+        _openjson_value_equals(document, str(key), value, field) for key, value in expected.items()
+    )
+    return cast(ColumnElement[bool], and_(*parts))
+
+
+def _openjson_array_equals(
+    document: ColumnElement[Any],
+    expected: list[Any],
+    field: str,
+) -> ColumnElement[bool]:
+    parts: list[ColumnElement[bool]] = [
+        cast(ColumnElement[bool], _openjson_child_count(document) == len(expected))
+    ]
+    parts.extend(
+        _openjson_value_equals(
+            document,
+            str(index),
+            value,
+            field,
+            nested_path=_json_path_for_array_index(index),
+        )
+        for index, value in enumerate(expected)
+    )
+    return cast(ColumnElement[bool], and_(*parts))
+
+
+def _openjson_value_equals(
+    document: ColumnElement[Any],
+    key: str,
+    expected: Any,
+    field: str,
+    *,
+    nested_path: str | None = None,
+) -> ColumnElement[bool]:
+    if expected is None:
+        return _openjson_key_exists(document, key, json_type=0)
+    if isinstance(expected, bool):
+        return _openjson_key_matches(
+            document,
+            key,
+            json_type=3,
+            expected_value="true" if expected else "false",
+        )
+    if isinstance(expected, str):
+        return _openjson_key_matches(
+            document,
+            key,
+            json_type=1,
+            expected_value=expected,
+        )
+    if isinstance(expected, dict):
+        nested = func.json_query(document, nested_path or _json_path_for_key(key))
+        return cast(
+            ColumnElement[bool],
+            _openjson_key_exists(document, key, json_type=5)
+            & _openjson_object_equals(nested, expected, field),
+        )
+    if isinstance(expected, list):
+        nested = func.json_query(document, nested_path or _json_path_for_key(key))
+        return cast(
+            ColumnElement[bool],
+            _openjson_key_exists(document, key, json_type=4)
+            & _openjson_array_equals(nested, expected, field),
+        )
+    if isinstance(expected, (int, float)):
+        raise CapabilityError(
+            "mssql",
+            field,
+            "exact JSON numeric equality",
+            "OPENJSON.value text",
+            "SQL Server exposes JSON numbers as text, and the provider cannot "
+            "guarantee exact numeric equivalence without lossy conversion.",
+        )
+    raise CapabilityError(
+        "mssql",
+        field,
+        "JSON scalar equality",
+        type(expected).__name__,
+        "Only null, boolean, string, object, and array values are supported by "
+        "the SQL Server JSON containment translator.",
+    )
+
+
+def _is_json_root(
+    document: ColumnElement[Any],
+    root_marker: str,
+) -> ColumnElement[bool]:
+    """Check the root shape using functions available since SQL Server 2016."""
+    text: ColumnElement[Any] = sa_cast(document, Unicode())
+    # LTRIM on supported SQL Server versions removes spaces only. Normalize
+    # the other JSON whitespace characters first so valid pretty-printed
+    # documents receive the same root-shape check.
+    for whitespace in ("\t", "\n", "\r"):
+        text = cast(
+            ColumnElement[Any],
+            func.replace(
+                text,
+                literal(whitespace, type_=Unicode()),
+                literal(" ", type_=Unicode()),
+            ),
+        )
+    return cast(
+        ColumnElement[bool],
+        (func.isjson(document) == 1)
+        & (func.left(func.ltrim(text), 1) == literal(root_marker, type_=Unicode())),
+    )
+
+
+def _is_json_object(document: ColumnElement[Any]) -> ColumnElement[bool]:
+    return _is_json_root(document, "{")
+
+
+def _is_json_array(document: ColumnElement[Any]) -> ColumnElement[bool]:
+    return _is_json_root(document, "[")
+
+
+def translate_json_contains(
+    constraint: Constraint,
+    column: ColumnElement[Any],
+    context: CompilationContext,
+) -> ColumnElement[bool]:
+    """Translate ``json_contains`` using SQL Server JSON functions.
+
+    Object payloads contain their requested top-level keys. Nested objects and
+    arrays are matched exactly by structure, independent of whitespace and
+    object key order. Numeric comparisons are rejected because ``OPENJSON``
+    exposes numbers as text and SQL Server cannot guarantee exact equality
+    without a potentially lossy conversion.
+    """
+    value = constraint.value
+    if isinstance(value, dict):
+        if not value:
+            return _is_json_object(column)
+        parts: list[ColumnElement[bool]] = []
+        for key, expected in value.items():
+            parts.append(_openjson_value_equals(column, str(key), expected, constraint.field))
+        expression = parts[0]
+        for part in parts[1:]:
+            expression = expression & part
+        return cast(ColumnElement[bool], _is_json_object(column) & expression)
+    if isinstance(value, list):
+        return cast(
+            ColumnElement[bool],
+            _is_json_array(column) & _openjson_array_equals(column, value, constraint.field),
+        )
+    raise CapabilityError(
+        "mssql",
+        constraint.field,
+        "JSON scalar containment",
+        type(value).__name__,
+        "SQL Server's JSON containment translator supports object and array payloads; "
+        "top-level scalar payloads cannot be compared reliably.",
+    )
+
+
+def translate_json_has_key(
+    constraint: Constraint,
+    column: ColumnElement[Any],
+    context: CompilationContext,
+) -> ColumnElement[bool]:
+    """Translate ``json_has_key`` via ``OPENJSON`` key presence (includes JSON null)."""
+    return cast(
+        ColumnElement[bool],
+        _is_json_object(column) & _openjson_key_exists(column, str(constraint.value)),
+    )

{sqlrules_mssql-1.0.0 → sqlrules_mssql-2.0.0}/src/sqlrules_mssql/length.py

@@ -2,15 +2,24 @@ from __future__ import annotations
 
 from typing import Any, cast
 
-from sqlalchemy import func, literal
+from sqlalchemy import Unicode, func, literal
+from sqlalchemy import cast as sa_cast
 from sqlalchemy.sql.elements import ColumnElement
 
 from sqlrules.ir import CompilationContext, Constraint
 
 
 def _char_length(column: ColumnElement[Any]) -> ColumnElement[Any]:
-    """Character length including trailing spaces (``LEN`` alone strips them)."""
-    return func.len(column.concat(literal("."))) - 1
+    """Count Unicode code points and trailing spaces on supported SQL Server.
+
+    SQL Server ``LEN`` counts a UTF-16 surrogate pair as two under ordinary
+    collations. Convert to an unbounded Unicode expression with an SC-aware
+    collation before measuring; the appended character keeps trailing spaces
+    in the count.
+    """
+    unicode_column = sa_cast(column, Unicode()).collate("Latin1_General_100_CI_AS_SC")
+    sentinel = literal(".", type_=Unicode())
+    return func.len(unicode_column.concat(sentinel)) - 1
 
 
 def translate_min_length(