sqlrules-sqlite 1.0.1__tar.gz → 2.0.0__tar.gz

sqlrules_sqlite-2.0.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: sqlrules-sqlite
+Version: 2.0.0
+Summary: SQLite dialect plugin for SQLRules (REGEXP, Unicode length, and JSON helpers).
+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: pydantic,sqlalchemy,sqlite,sqlrules
+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-sqlite
+
+SQLite 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-sqlite>=2,<3"
+```
+
+## Use
+
+```python
+from typing import Annotated, Any
+
+from pydantic import Field
+from sqlalchemy import Column, JSON, MetaData, String, Table, create_engine, event
+
+from sqlrules import Compiler, JsonContains, RuleSchema, where
+from sqlrules_sqlite import SQLitePlugin, register_sqlite_functions
+
+rows = Table("rows", MetaData(), Column("name", String), Column("meta", JSON))
+
+
+class RowRules(RuleSchema):
+    name: Annotated[str, Field(pattern=r"^A")]
+    meta: Annotated[dict[str, Any], JsonContains({"active": True})]
+
+
+engine = create_engine("sqlite:///app.db")
+event.listen(
+    engine,
+    "connect",
+    lambda dbapi_connection, _: register_sqlite_functions(dbapi_connection),
+)
+compiled = Compiler(plugins=[SQLitePlugin()]).compile(RowRules, rows)
+statement = rows.select().where(*where(compiled))
+```
+
+## Capabilities
+
+- Runtime `typeof()` checks for SQLite integer, real, and text storage classes
+- Lax text-to-int/float coercion and bool values stored as integer 0 or 1
+- JSON1 helpers that treat malformed documents as non-matches
+- `REGEXP` pattern matching and Unicode-aware string length through
+  `register_sqlite_functions()`
+
+Strict bool, exact Decimal, and SQLAlchemy-emulated date/time/UUID values need
+explicit storage adapters and raise `CapabilityError`. Text coercion, patterns,
+and string length constraints require the registered SQLRules SQLite functions
+on each connection. `register_regexp()` remains as a backward-compatible alias.
+See the
+[type support matrix](https://sqlrules.readthedocs.io/en/latest/TYPE_SUPPORT.html).
+
+## Pattern cost
+
+`register_sqlite_functions()` runs Python's `re.search` for each regex row and
+Python's `len()` for each length-checked string row. Untrusted patterns can
+cause CPU denial of service through catastrophic backtracking. Prefer static
+or allowlisted patterns. See the SQLRules
+[security notes](https://sqlrules.readthedocs.io/en/latest/SECURITY.html).

sqlrules_sqlite-2.0.0/README.md

@@ -0,0 +1,62 @@
+# sqlrules-sqlite
+
+SQLite 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-sqlite>=2,<3"
+```
+
+## Use
+
+```python
+from typing import Annotated, Any
+
+from pydantic import Field
+from sqlalchemy import Column, JSON, MetaData, String, Table, create_engine, event
+
+from sqlrules import Compiler, JsonContains, RuleSchema, where
+from sqlrules_sqlite import SQLitePlugin, register_sqlite_functions
+
+rows = Table("rows", MetaData(), Column("name", String), Column("meta", JSON))
+
+
+class RowRules(RuleSchema):
+    name: Annotated[str, Field(pattern=r"^A")]
+    meta: Annotated[dict[str, Any], JsonContains({"active": True})]
+
+
+engine = create_engine("sqlite:///app.db")
+event.listen(
+    engine,
+    "connect",
+    lambda dbapi_connection, _: register_sqlite_functions(dbapi_connection),
+)
+compiled = Compiler(plugins=[SQLitePlugin()]).compile(RowRules, rows)
+statement = rows.select().where(*where(compiled))
+```
+
+## Capabilities
+
+- Runtime `typeof()` checks for SQLite integer, real, and text storage classes
+- Lax text-to-int/float coercion and bool values stored as integer 0 or 1
+- JSON1 helpers that treat malformed documents as non-matches
+- `REGEXP` pattern matching and Unicode-aware string length through
+  `register_sqlite_functions()`
+
+Strict bool, exact Decimal, and SQLAlchemy-emulated date/time/UUID values need
+explicit storage adapters and raise `CapabilityError`. Text coercion, patterns,
+and string length constraints require the registered SQLRules SQLite functions
+on each connection. `register_regexp()` remains as a backward-compatible alias.
+See the
+[type support matrix](https://sqlrules.readthedocs.io/en/latest/TYPE_SUPPORT.html).
+
+## Pattern cost
+
+`register_sqlite_functions()` runs Python's `re.search` for each regex row and
+Python's `len()` for each length-checked string row. Untrusted patterns can
+cause CPU denial of service through catastrophic backtracking. Prefer static
+or allowlisted patterns. See the SQLRules
+[security notes](https://sqlrules.readthedocs.io/en/latest/SECURITY.html).

{sqlrules_sqlite-1.0.1 → sqlrules_sqlite-2.0.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlrules-sqlite"
-version = "1.0.1"
-description = "SQLite dialect plugin for SQLRules (REGEXP helpers and JSON)."
+version = "2.0.0"
+description = "SQLite dialect plugin for SQLRules (REGEXP, Unicode length, and JSON helpers)."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
@@ -18,7 +18,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-  "sqlrules>=1,<2",
+  "sqlrules>=2,<3",
   "sqlalchemy>=2.0,<3",
 ]
 

sqlrules_sqlite-2.0.0/src/sqlrules_sqlite/__init__.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from sqlrules.backend import prepare_sqlite_scalar
+from sqlrules.ir import CompilationContext, PreparedValue, RuleField
+from sqlrules.plugins import PLUGIN_API_VERSION
+from sqlrules.translators import TranslatorRegistry
+from sqlrules_sqlite.json import translate_json_contains, translate_json_has_key
+from sqlrules_sqlite.length import translate_max_length, translate_min_length
+from sqlrules_sqlite.pattern import translate_pattern
+from sqlrules_sqlite.regexp import register_regexp
+from sqlrules_sqlite.runtime import register_sqlite_functions
+
+__version__ = "2.0.0"
+
+
+class SQLitePlugin:
+    """Register SQLite-specific constraint translators.
+
+    Pattern and text-coercion expressions emit ``column REGEXP pattern``;
+    length constraints use SQLRules' Unicode-aware character counter. Call
+    :func:`register_sqlite_functions` on each SQLite connection before
+    executing SQL that needs these functions. ``register_regexp`` remains as a
+    backward-compatible alias.
+    """
+
+    name = "sqlite"
+    api_version = PLUGIN_API_VERSION
+
+    def __init__(self, *, server_version: tuple[int, ...] | None = None) -> None:
+        self.server_version = tuple(server_version) if server_version is not None else None
+
+    def capabilities(self) -> Mapping[str, Any]:
+        return {
+            "backend": self.name,
+            "server_version": self.server_version,
+            "native_scalar_types": ("bool", "int", "float", "str"),
+            "safe_text_numeric_conversion": True,
+            "safe_text_numeric_targets": ("int", "float"),
+            "assumptions": (
+                "Runtime typeof() storage classes determine bool/int/float/text values.",
+                "Register SQLRules SQLite functions on each connection when using text "
+                "coercion, patterns, or string length constraints.",
+                "Date/time/UUID and exact Decimal checks require "
+                "a future explicit storage adapter.",
+            ),
+        }
+
+    def prepare_value(
+        self,
+        column: Any,
+        field: RuleField,
+        context: CompilationContext,
+    ) -> PreparedValue:
+        return prepare_sqlite_scalar(column, field, context)
+
+    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(
+            "pattern",
+            translate_pattern,
+            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__ = [
+    "SQLitePlugin",
+    "__version__",
+    "register_regexp",
+    "register_sqlite_functions",
+    "translate_json_contains",
+    "translate_json_has_key",
+    "translate_pattern",
+]

sqlrules_sqlite-2.0.0/src/sqlrules_sqlite/json.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from sqlalchemy import String, and_, case, func, literal, select, type_coerce
+from sqlalchemy.sql.elements import ColumnElement
+
+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)
+    escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+    return f'$."{escaped}"'
+
+
+def _compact_dumps(value: Any) -> str:
+    return json.dumps(value, separators=(",", ":"))
+
+
+def _safe_json(column: ColumnElement[Any]) -> ColumnElement[Any]:
+    """Replace malformed documents before any JSON1 function can inspect them."""
+    return case(
+        (func.json_valid(column), type_coerce(column, String)),
+        else_=literal("{}"),
+    )
+
+
+def _json_child_count(
+    document: ColumnElement[Any],
+    path: str,
+) -> ColumnElement[Any]:
+    children = func.json_each(document, path).table_valued("key").alias()
+    return select(func.count()).select_from(children).scalar_subquery()
+
+
+def _join_json_path(parent: str, child: str) -> str:
+    return f"{parent}{child[1:]}"
+
+
+def _json_value_equals(
+    document: ColumnElement[Any],
+    path: str,
+    expected: Any,
+) -> ColumnElement[bool]:
+    """Compare JSON values structurally, independent of object key order."""
+    json_type = func.json_type(document, path)
+    extracted = func.json_extract(document, path)
+    if expected is None:
+        return cast(ColumnElement[bool], json_type == "null")
+    if isinstance(expected, bool):
+        expected_type = "true" if expected else "false"
+        return cast(ColumnElement[bool], json_type == expected_type)
+    if isinstance(expected, dict):
+        parts: list[ColumnElement[bool]] = [
+            cast(ColumnElement[bool], json_type == "object"),
+            cast(ColumnElement[bool], _json_child_count(document, path) == len(expected)),
+        ]
+        parts.extend(
+            _json_value_equals(
+                document,
+                _join_json_path(path, _json_path_for_key(key)),
+                child,
+            )
+            for key, child in expected.items()
+        )
+        return cast(ColumnElement[bool], and_(*parts))
+    if isinstance(expected, list):
+        parts = [
+            cast(ColumnElement[bool], json_type == "array"),
+            cast(ColumnElement[bool], _json_child_count(document, path) == len(expected)),
+        ]
+        parts.extend(
+            _json_value_equals(document, f"{path}[{index}]", child)
+            for index, child in enumerate(expected)
+        )
+        return cast(ColumnElement[bool], and_(*parts))
+    if isinstance(expected, (int, float)):
+        return cast(
+            ColumnElement[bool],
+            json_type.in_(("integer", "real")) & (extracted == expected),
+        )
+    if isinstance(expected, str):
+        return cast(ColumnElement[bool], (json_type == "text") & (extracted == expected))
+    compact = _compact_dumps(expected)
+    return cast(
+        ColumnElement[bool],
+        func.json(extracted) == func.json(literal(compact)),
+    )
+
+
+def translate_json_contains(
+    constraint: Constraint,
+    column: ColumnElement[Any],
+    context: CompilationContext,
+) -> ColumnElement[bool]:
+    """Translate the supported SQLite JSON containment subset safely."""
+    value = constraint.value
+    safe_json = _safe_json(column)
+    valid_document = func.json_valid(column)
+    if isinstance(value, dict):
+        if not value:
+            return cast(
+                ColumnElement[bool],
+                column.is_not(None) & valid_document & (func.json_type(safe_json) == "object"),
+            )
+        parts = [
+            _json_value_equals(safe_json, _json_path_for_key(key), expected)
+            for key, expected in value.items()
+        ]
+        return cast(
+            ColumnElement[bool],
+            valid_document & (func.json_type(safe_json) == "object") & and_(*parts),
+        )
+
+    return cast(
+        ColumnElement[bool],
+        valid_document & _json_value_equals(safe_json, "$", value),
+    )
+
+
+def translate_json_has_key(
+    constraint: Constraint,
+    column: ColumnElement[Any],
+    context: CompilationContext,
+) -> ColumnElement[bool]:
+    """Translate ``json_has_key`` without evaluating JSON1 on malformed input."""
+    path = _json_path_for_key(constraint.value)
+    return cast(
+        ColumnElement[bool],
+        func.json_valid(column) & func.json_type(_safe_json(column), path).is_not(None),
+    )

sqlrules_sqlite-2.0.0/src/sqlrules_sqlite/length.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from sqlalchemy import func
+from sqlalchemy.sql.elements import ColumnElement
+
+from sqlrules.ir import CompilationContext, Constraint
+
+
+def translate_min_length(
+    constraint: Constraint,
+    column: ColumnElement[Any],
+    context: CompilationContext,
+) -> ColumnElement[bool]:
+    """Use the registered Python-compatible code-point counter."""
+    return cast(
+        ColumnElement[bool],
+        func.sqlrules_char_length(column) >= constraint.value,
+    )
+
+
+def translate_max_length(
+    constraint: Constraint,
+    column: ColumnElement[Any],
+    context: CompilationContext,
+) -> ColumnElement[bool]:
+    """Use the registered Python-compatible code-point counter."""
+    return cast(
+        ColumnElement[bool],
+        func.sqlrules_char_length(column) <= constraint.value,
+    )
+
+
+__all__ = ["translate_max_length", "translate_min_length"]

{sqlrules_sqlite-1.0.1 → sqlrules_sqlite-2.0.0}/src/sqlrules_sqlite/pattern.py

@@ -16,7 +16,8 @@ def translate_pattern(
     """Translate ``pattern`` to SQLite ``column REGEXP pattern``.
 
     Case-insensitive patterns are encoded with a ``(?i)`` prefix so
-    :func:`sqlrules_sqlite.register_regexp` can apply ``re.IGNORECASE``.
+    :func:`sqlrules_sqlite.register_sqlite_functions` can apply
+    ``re.IGNORECASE``.
     Callers must enable REGEXP on the SQLite connection before execution.
     """
     pattern, ignore_case = pattern_text(constraint.value)

sqlrules_sqlite-2.0.0/src/sqlrules_sqlite/regexp.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import sqlite3
+
+from sqlrules_sqlite.runtime import register_sqlite_functions
+
+
+def register_regexp(connection: sqlite3.Connection) -> None:
+    """Backward-compatible alias for :func:`register_sqlite_functions`."""
+    register_sqlite_functions(connection)
+
+
+__all__ = ["register_regexp"]

sqlrules_sqlite-2.0.0/src/sqlrules_sqlite/runtime.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import re
+import sqlite3
+from typing import Any
+
+
+def _regexp(pattern: str | None, value: str | None) -> bool:
+    # SQLite may evaluate a REGEXP branch even when a neighboring typeof()
+    # predicate is false. Treat non-text source values as a non-match so
+    # mixed-storage tables cannot raise Python TypeError.
+    if not isinstance(pattern, str) or not isinstance(value, str):
+        return False
+    flags = 0
+    if pattern.startswith("(?i)"):
+        flags |= re.IGNORECASE
+        pattern = pattern[4:]
+    return re.search(pattern, value, flags) is not None
+
+
+def _char_length(value: Any) -> int | None:
+    """Use Python's Unicode code-point count, including text after U+0000."""
+    return len(value) if isinstance(value, str) else None
+
+
+def register_sqlite_functions(connection: sqlite3.Connection) -> None:
+    """Register SQLRules functions needed by SQLite rules on this connection.
+
+    SQLite does not provide REGEXP, and its built-in length(TEXT) stops at the
+    first U+0000. SQLRules uses these callbacks for regex/text coercion and
+    exact Python-compatible string length constraints.
+    """
+    connection.create_function("REGEXP", 2, _regexp)
+    connection.create_function("sqlrules_char_length", 1, _char_length)

sqlrules_sqlite-2.0.0/tests/test_sqlite_plugin.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import sqlite3
+from typing import Annotated, Any
+
+from pydantic import Field
+from sqlalchemy import JSON, Column, Integer, MetaData, String, Table, create_engine, select
+from sqlalchemy.dialects.sqlite import dialect
+from sqlrules_sqlite import SQLitePlugin, __version__, register_regexp
+
+from sqlrules import Compiler, JsonContains, JsonHasKey, RuleSchema
+from sqlrules.conformance import run_basic_conformance
+
+
+def test_version_and_plugin_conformance() -> None:
+    assert __version__ == "2.0.0"
+    run_basic_conformance(SQLitePlugin(), operator="pattern")
+
+
+def test_pattern_and_json_markers_compile() -> None:
+    class Rules(RuleSchema):
+        name: Annotated[str, Field(pattern=r"^A")]
+        meta: Annotated[dict[str, Any], JsonContains({"active": True}), JsonHasKey("active")]
+
+    table = Table(
+        "rows",
+        MetaData(),
+        Column("name", String),
+        Column("meta", JSON),
+    )
+    compiled = Compiler(plugins=[SQLitePlugin()]).compile(Rules, table)
+    sql = str(compiled.predicate.compile(dialect=dialect()))
+    assert "REGEXP" in sql
+    assert "json_type" in sql
+    assert "json_valid" in sql
+
+
+def test_regexp_handles_text_and_non_text_values() -> None:
+    db = sqlite3.connect(":memory:")
+    register_regexp(db)
+    assert db.execute("SELECT 'Ada' REGEXP '^A'").fetchone() == (1,)
+    assert db.execute("SELECT 12 REGEXP '^1'").fetchone() == (0,)
+    assert db.execute("SELECT NULL REGEXP '^1'").fetchone() == (0,)
+    db.close()
+
+
+def test_json_contains_executes_on_sqlite() -> None:
+    class Rules(RuleSchema):
+        meta: Annotated[dict[str, Any], JsonContains({"active": True})]
+
+    table = Table(
+        "rows",
+        MetaData(),
+        Column("id", Integer),
+        Column("meta", JSON),
+    )
+    engine = create_engine("sqlite://")
+    table.create(engine)
+    with engine.begin() as connection:
+        connection.exec_driver_sql(
+            "INSERT INTO rows (id, meta) VALUES (1, '{\"active\": true}'), "
+            "(2, '{\"active\": false}'), (3, 'not json'), (4, NULL)"
+        )
+        compiled = Compiler(plugins=[SQLitePlugin()]).compile(Rules, table)
+        found = connection.execute(select(table.c.id).where(compiled.predicate)).all()
+    assert found == [(1,)]
+    engine.dispose()

sqlrules_sqlite-1.0.1/PKG-INFO

@@ -1,83 +0,0 @@
-Metadata-Version: 2.4
-Name: sqlrules-sqlite
-Version: 1.0.1
-Summary: SQLite dialect plugin for SQLRules (REGEXP helpers and JSON).
-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: pydantic,sqlalchemy,sqlite,sqlrules
-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<2,>=1
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# sqlrules-sqlite
-
-SQLite dialect plugin for [SQLRules](https://github.com/eddiethedean/sqlrules).
-
-## Install
-
-```bash
-pip install sqlrules-sqlite
-```
-
-## Usage
-
-```python
-import sqlite3
-from typing import Annotated, Any
-
-from pydantic import BaseModel, Field
-from sqlalchemy import Column, MetaData, String, Table, create_engine, text
-
-from sqlrules import Compiler, JsonContains, JsonHasKey
-from sqlrules_sqlite import SQLitePlugin, register_regexp
-
-class RowFilter(BaseModel):
-    name: Annotated[str, Field(pattern=r"^A")]
-    meta: Annotated[dict[str, Any], JsonContains({"active": True}), JsonHasKey("active")]
-
-table = Table(
-    "rows",
-    MetaData(),
-    Column("name", String),
-    Column("meta", String),
-)
-
-compiler = Compiler(plugins=[SQLitePlugin()], dialect="sqlite")
-rules = compiler.compile(RowFilter, table)
-
-engine = create_engine("sqlite://")
-with engine.raw_connection() as conn:
-    # SQLAlchemy 2 may wrap the DBAPI connection; unwrap if needed.
-    dbapi = conn.driver_connection if hasattr(conn, "driver_connection") else conn
-    register_regexp(dbapi)
-```
-
-## Operators
-
-| IR operator | Notes |
-|---|---|
-| `pattern` | `column REGEXP pattern`; call `register_regexp(connection)` |
-| `type_check` | `typeof` / `REGEXP` shape checks; text forms need `register_regexp` |
-| `json_contains` | JSON1 `json_extract` equality for object keys |
-| `json_has_key` | `json_type(column, '$.key') IS NOT NULL` |
-
-Case-insensitive patterns (`re.IGNORECASE` / `PatternSpec.ignore_case`) are
-encoded with a `(?i)` prefix understood by `register_regexp`.
-
-## Security note
-
-`register_regexp` installs a Python `re.search` UDF. Untrusted
-`Field(pattern=...)` values can cause **CPU denial of service** (ReDoS) in
-your process — not SQL injection. Prefer static/allowlisted patterns. See
-[SECURITY](https://sqlrules.readthedocs.io/en/latest/SECURITY.html).