sqlrules 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

sqlrules/__init__.py

@@ -5,6 +5,7 @@ from sqlrules.errors import (
     InvalidModelError,
     InvalidTranslatorError,
     MissingColumnError,
+    PluginError,
     RegistryError,
     SQLRulesError,
     TranslatorError,
@@ -17,26 +18,50 @@ from sqlrules.ir import (
     FieldDescriptor,
     FieldIR,
     ModelIR,
+    PatternSpec,
 )
+from sqlrules.markers import (
+    ArrayContains,
+    ArrayOverlap,
+    ConstraintMarker,
+    FullTextMatch,
+    JsonContains,
+    JsonHasKey,
+    RangeContains,
+    RangeOverlap,
+)
+from sqlrules.plugins import PLUGIN_API_VERSION, SQLRulesPlugin
 from sqlrules.translators import SQLRulesWarning
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 __all__ = [
+    "PLUGIN_API_VERSION",
+    "ArrayContains",
+    "ArrayOverlap",
     "CompilationContext",
     "Compiler",
     "ConfigurationError",
     "Constraint",
+    "ConstraintMarker",
     "Diagnostic",
     "FieldDescriptor",
     "FieldIR",
+    "FullTextMatch",
     "InternalCompilerError",
     "InvalidModelError",
     "InvalidTranslatorError",
+    "JsonContains",
+    "JsonHasKey",
     "MissingColumnError",
     "ModelIR",
+    "PatternSpec",
+    "PluginError",
+    "RangeContains",
+    "RangeOverlap",
     "RegistryError",
     "SQLRulesError",
+    "SQLRulesPlugin",
     "SQLRulesWarning",
     "TranslatorError",
     "UnsupportedConstraintError",

sqlrules/compiler.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from itertools import chain
 from typing import Any
 
@@ -18,8 +18,10 @@ from sqlrules.ir import (
     DiagnosticsCollector,
     FieldIR,
     ModelIR,
+    OnConflict,
     OnUnsupported,
 )
+from sqlrules.plugins import SQLRulesPlugin, validate_plugin
 from sqlrules.translators import TranslatorRegistry, default_registry
 
 RulesDict = dict[str, list[ColumnElement[bool]]]
@@ -30,20 +32,45 @@ class Compiler:
         self,
         *,
         registry: TranslatorRegistry | None = None,
+        plugins: Sequence[SQLRulesPlugin] | None = None,
+        on_conflict: OnConflict = "raise",
         on_unsupported: OnUnsupported = "raise",
+        dialect: str | None = None,
         cache: bool = True,
         model_cache: ModelIRCache | None = None,
     ) -> None:
         if on_unsupported not in {"raise", "warn", "ignore"}:
             raise ConfigurationError(option="on_unsupported", value=on_unsupported)
-        self.registry = registry or default_registry()
+        if on_conflict not in {"raise", "replace", "ignore"}:
+            raise ConfigurationError(option="on_conflict", value=on_conflict)
+
+        base = registry if registry is not None else default_registry()
+        plugin_list = list(plugins or ())
+        resolved: TranslatorRegistry
+        if plugin_list:
+            # Copy so plugins cannot mutate a caller-owned or shared registry.
+            aware = _PluginAwareRegistry(
+                base.copy(),
+                default_on_conflict=on_conflict,
+            )
+            for plugin in plugin_list:
+                validate_plugin(plugin).register(aware)
+            # Freeze to a plain registry after registration.
+            resolved = aware.copy()
+        else:
+            resolved = base
+        self.registry = resolved
+
         self.on_unsupported = on_unsupported
+        self.on_conflict = on_conflict
+        self.dialect = dialect
         self.cache_enabled = cache
         self._model_cache = model_cache if model_cache is not None else default_cache()
         self._collector = DiagnosticsCollector()
         self.context = CompilationContext(
             on_unsupported=on_unsupported,
             collector=self._collector,
+            dialect=dialect,
         )
 
     @property
@@ -83,6 +110,7 @@ class Compiler:
         self.context = CompilationContext(
             on_unsupported=self.on_unsupported,
             collector=self._collector,
+            dialect=self.dialect,
         )
 
         rules: RulesDict = {}
@@ -120,6 +148,43 @@ class Compiler:
         return self.bind(self.compile_model(model), table, column_map=column_map)
 
 
+class _PluginAwareRegistry(TranslatorRegistry):
+    """Registry that applies Compiler.on_conflict as the default for register()."""
+
+    def __init__(
+        self,
+        base: TranslatorRegistry,
+        *,
+        default_on_conflict: OnConflict,
+    ) -> None:
+        super().__init__()
+        self._translators = dict(base._translators)
+        self._default_on_conflict = default_on_conflict
+
+    def register(
+        self,
+        operator_name: str,
+        translator: Any,
+        *,
+        replace: bool = False,
+    ) -> None:
+        on_conflict: OnConflict = "replace" if replace else self._default_on_conflict
+        self.register_constraint(operator_name, translator, on_conflict=on_conflict)
+
+    def register_constraint(
+        self,
+        operator_name: str,
+        translator: Any,
+        *,
+        on_conflict: OnConflict | None = None,
+    ) -> None:
+        super().register_constraint(
+            operator_name,
+            translator,
+            on_conflict=on_conflict if on_conflict is not None else self._default_on_conflict,
+        )
+
+
 def compile(
     model: type[BaseModel],
     table: Any,

sqlrules/conformance.py

@@ -0,0 +1,160 @@
+"""Plugin conformance helpers for official and third-party plugins."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field
+from sqlalchemy import Column, MetaData, String, Table
+from sqlalchemy.sql.elements import ColumnElement
+
+from sqlrules.compiler import Compiler
+from sqlrules.errors import PluginError, RegistryError
+from sqlrules.plugins import PLUGIN_API_VERSION, SQLRulesPlugin, validate_plugin
+from sqlrules.translators import TranslatorRegistry, default_registry
+
+
+def assert_plugin_api_compatible(plugin: SQLRulesPlugin) -> None:
+    """Raise PluginError if the plugin does not match the current plugin API."""
+    validate_plugin(plugin)
+
+
+def assert_register_conflict_raise(plugin: SQLRulesPlugin) -> None:
+    """Registering the same plugin twice with on_conflict='raise' must fail.
+
+    Plugins that only add new operators (not in the default registry) are
+    registered twice against a fresh default registry; the second pass must
+    raise RegistryError for any overlapping operator.
+    """
+    validate_plugin(plugin)
+    registry = default_registry()
+    plugin.register(registry)
+    try:
+        plugin.register(registry)
+    except RegistryError:
+        return
+    raise AssertionError(
+        f"Plugin {plugin.name!r} did not raise RegistryError on duplicate registration"
+    )
+
+
+def assert_register_idempotent_ignore(plugin: SQLRulesPlugin) -> None:
+    """Registering twice with on_conflict='ignore' must succeed and keep builtins."""
+    validate_plugin(plugin)
+    builtins = default_registry().operators()
+    compiler = Compiler(plugins=[plugin], on_conflict="ignore", cache=False)
+    first_ops = compiler.registry.operators()
+    # Re-apply via a second compiler with the same plugin.
+    compiler2 = Compiler(
+        registry=compiler.registry.copy(),
+        plugins=[plugin],
+        on_conflict="ignore",
+        cache=False,
+    )
+    assert compiler2.registry.operators() == first_ops
+    assert builtins <= compiler2.registry.operators()
+
+
+def assert_builtins_preserved(
+    plugin: SQLRulesPlugin,
+    *,
+    on_conflict: str = "raise",
+) -> None:
+    """Plugins must not drop built-in operators."""
+    validate_plugin(plugin)
+    builtins = default_registry().operators()
+    compiler = Compiler(plugins=[plugin], on_conflict=on_conflict, cache=False)  # type: ignore[arg-type]
+    missing = builtins - compiler.registry.operators()
+    if missing:
+        raise AssertionError(
+            f"Plugin {plugin.name!r} removed built-in operators: {sorted(missing)}"
+        )
+
+
+def assert_translates_operator(
+    plugin: SQLRulesPlugin,
+    *,
+    operator: str,
+    model: type[BaseModel] | None = None,
+    table: Any | None = None,
+    field: str = "name",
+) -> ColumnElement[bool]:
+    """Compile with the plugin and assert ``operator`` yields a ColumnElement."""
+    validate_plugin(plugin)
+
+    if model is None:
+
+        class PatternFilter(BaseModel):
+            name: Annotated[str, Field(pattern=r"^a")]
+
+        model = PatternFilter
+
+    if table is None:
+        table = Table("items", MetaData(), Column("name", String))
+
+    compiler = Compiler(plugins=[plugin], on_conflict="replace", cache=False)
+    if operator not in compiler.registry:
+        raise AssertionError(f"Plugin {plugin.name!r} did not register operator {operator!r}")
+
+    rules = compiler.compile(model, table)
+    if field not in rules or not rules[field]:
+        raise AssertionError(f"Plugin {plugin.name!r}: expected expressions for field {field!r}")
+
+    expression = rules[field][0]
+    if not isinstance(expression, ColumnElement):
+        raise AssertionError(
+            f"Plugin {plugin.name!r}: translator for {operator!r} "
+            f"returned {type(expression)!r}, expected ColumnElement"
+        )
+
+    # Deterministic compile smoke check (avoid literal_binds; values may be
+    # structured IR objects such as PatternSpec).
+    compiled_a = str(expression.compile())
+    compiled_b = str(expression.compile())
+    if compiled_a != compiled_b:
+        raise AssertionError(f"Plugin {plugin.name!r}: non-deterministic compile for {operator!r}")
+    return expression
+
+
+def run_basic_conformance(
+    plugin: SQLRulesPlugin,
+    *,
+    operator: str = "pattern",
+    model: type[BaseModel] | None = None,
+    table: Any | None = None,
+    field: str = "name",
+) -> None:
+    """Run the standard conformance checks for a dialect/translator plugin."""
+    if getattr(plugin, "api_version", None) != PLUGIN_API_VERSION:
+        raise PluginError(
+            message=(
+                f"Plugin {getattr(plugin, 'name', plugin)!r} api_version mismatch "
+                f"(expected {PLUGIN_API_VERSION!r})."
+            ),
+            plugin=plugin,
+        )
+    assert_plugin_api_compatible(plugin)
+    assert_builtins_preserved(plugin, on_conflict="replace")
+    assert_register_idempotent_ignore(plugin)
+    assert_translates_operator(
+        plugin,
+        operator=operator,
+        model=model,
+        table=table,
+        field=field,
+    )
+
+    # Conflict under raise: only meaningful if the plugin re-registers an op
+    # already present after the first registration.
+    registry = default_registry()
+    plugin.register(registry)
+    with contextlib.suppress(RegistryError):
+        # If the plugin uses on_conflict="replace" internally, duplicate
+        # registration may succeed; that is acceptable for dialect overrides.
+        plugin.register(registry)
+
+
+def registry_without_builtins() -> TranslatorRegistry:
+    """Empty registry for isolated translator unit tests."""
+    return TranslatorRegistry()

sqlrules/constraints.py

@@ -22,15 +22,18 @@ from annotated_types import (
 from pydantic.fields import FieldInfo
 
 from sqlrules.errors import UnsupportedConstraintError
-from sqlrules.ir import Constraint, FieldDescriptor
+from sqlrules.ir import Constraint, FieldDescriptor, PatternSpec
+from sqlrules.markers import ConstraintMarker
 
 _SUPPORTED_TYPES: frozenset[type[Any]] = frozenset(
     {bool, int, float, Decimal, str, date, datetime, time, UUID}
 )
+_SUPPORTED_CONTAINER_ORIGINS: frozenset[Any] = frozenset({list, dict})
 _UNSUPPORTED_TYPES: frozenset[type[Any]] = frozenset({timedelta})
-_UNSUPPORTED_ORIGINS: frozenset[Any] = frozenset({list, dict, tuple, set, frozenset})
+_UNSUPPORTED_ORIGINS: frozenset[Any] = frozenset({tuple, set, frozenset})
 _LENGTH_OPERATORS: frozenset[str] = frozenset({"min_length", "max_length"})
 _NUMERIC_OPERATORS: frozenset[str] = frozenset({"gt", "ge", "lt", "le", "multiple_of"})
+_PORTABLE_OPERATORS: frozenset[str] = _LENGTH_OPERATORS | _NUMERIC_OPERATORS | {"pattern"}
 _TEMPORAL_TYPES: frozenset[type[Any]] = frozenset({date, datetime, time})
 _VALIDATOR_TYPE_NAMES = frozenset(
     {
@@ -126,6 +129,13 @@ def _concrete_type(field: FieldDescriptor) -> Any:
     return annotation
 
 
+def _is_container_type(annotation: Any) -> bool:
+    origin = get_origin(annotation)
+    if origin in _SUPPORTED_CONTAINER_ORIGINS:
+        return True
+    return annotation in _SUPPORTED_CONTAINER_ORIGINS
+
+
 def ensure_supported_type(field: FieldDescriptor) -> None:
     """Raise when a field annotation is outside the support matrix."""
     annotation = _concrete_type(field)
@@ -134,16 +144,20 @@ def ensure_supported_type(field: FieldDescriptor) -> None:
     if origin is Literal:
         return
 
-    if origin in _UNSUPPORTED_ORIGINS:
+    if origin in _UNSUPPORTED_ORIGINS or annotation in _UNSUPPORTED_ORIGINS:
         raise UnsupportedConstraintError(
             field=field.name,
-            operator=getattr(origin, "__name__", str(origin)),
+            operator=getattr(origin or annotation, "__name__", str(origin or annotation)),
             value=annotation,
             suggestion=(
-                "Remove the field or wait for a future SQLRules release with container support."
+                "Remove the field or wait for a future SQLRules release with "
+                f"{getattr(origin or annotation, '__name__', origin or annotation)!r} support."
             ),
         )
 
+    if _is_container_type(annotation):
+        return
+
     if isinstance(annotation, type) and issubclass(annotation, Enum):
         return
 
@@ -171,11 +185,16 @@ def ensure_supported_type(field: FieldDescriptor) -> None:
     )
 
 
-def _normalize_pattern(field_name: str, pattern: Any) -> str:
-    if isinstance(pattern, str):
+def _normalize_pattern(field_name: str, pattern: Any) -> PatternSpec:
+    if isinstance(pattern, PatternSpec):
         return pattern
+    if isinstance(pattern, str):
+        return PatternSpec(pattern=pattern, ignore_case=False)
     if isinstance(pattern, re.Pattern):
-        return str(pattern.pattern)
+        return PatternSpec(
+            pattern=str(pattern.pattern),
+            ignore_case=bool(pattern.flags & re.IGNORECASE),
+        )
     raise UnsupportedConstraintError(
         field=field_name,
         operator="pattern",
@@ -184,6 +203,15 @@ def _normalize_pattern(field_name: str, pattern: Any) -> str:
     )
 
 
+def pattern_text(value: Any) -> tuple[str, bool]:
+    """Return ``(pattern, ignore_case)`` from a ``pattern`` constraint value."""
+    if isinstance(value, PatternSpec):
+        return value.pattern, value.ignore_case
+    if isinstance(value, str):
+        return value, False
+    raise TypeError(f"pattern value must be str or PatternSpec, got {type(value)!r}")
+
+
 def _constraints_from_mapping(field_name: str, data: dict[str, Any]) -> list[Constraint]:
     """Map whitelisted metadata keys into IR; ignore validation-only flags."""
     constraints: list[Constraint] = []
@@ -202,7 +230,16 @@ def _constraints_from_mapping(field_name: str, data: dict[str, Any]) -> list[Con
     return constraints
 
 
+def _is_constraint_marker(item: Any) -> bool:
+    if isinstance(item, type):
+        return False
+    return isinstance(item, ConstraintMarker)
+
+
 def _unsupported_constraints(field_name: str, item: Any) -> list[Constraint]:
+    if _is_constraint_marker(item):
+        return [Constraint(field_name, item.operator, item.value)]
+
     if isinstance(item, Predicate):
         return [Constraint(field_name, "predicate", item.func)]
 
@@ -218,7 +255,7 @@ def _unsupported_constraints(field_name: str, item: Any) -> list[Constraint]:
 
     # First-class pattern attribute (e.g. _PydanticGeneralMetadata(pattern=...)).
     pattern = getattr(item, "pattern", None)
-    if pattern is not None and isinstance(pattern, (str, re.Pattern)):
+    if pattern is not None and isinstance(pattern, (str, re.Pattern, PatternSpec)):
         constraints = _constraints_from_mapping(
             field_name,
             {
@@ -243,6 +280,17 @@ def _reject_type_operator_mismatch(field: FieldDescriptor, constraint: Constrain
     annotation = _concrete_type(field)
     origin = get_origin(annotation)
 
+    if _is_container_type(annotation) and constraint.operator in _PORTABLE_OPERATORS:
+        raise UnsupportedConstraintError(
+            field=field.name,
+            operator=constraint.operator,
+            value=constraint.value,
+            suggestion=(
+                "Portable constraints are not valid on list/dict fields; "
+                "use sqlrules.markers (e.g. JsonContains, ArrayContains) instead."
+            ),
+        )
+
     if origin is Literal:
         if (
             constraint.operator not in {"literal", "enum"}
@@ -322,7 +370,9 @@ def extract_constraints(field: FieldDescriptor) -> list[Constraint]:
     constraints: list[Constraint] = []
 
     for item in _iter_metadata(_field_metadata(field)):
-        if isinstance(item, Gt):
+        if _is_constraint_marker(item):
+            constraints.append(Constraint(field.name, item.operator, item.value))
+        elif isinstance(item, Gt):
             constraints.append(Constraint(field.name, "gt", item.gt))
         elif isinstance(item, Ge):
             constraints.append(Constraint(field.name, "ge", item.ge))
@@ -351,7 +401,7 @@ def extract_constraints(field: FieldDescriptor) -> list[Constraint]:
         constraints.append(Constraint(field.name, "enum", values))
 
     for constraint in constraints:
-        if constraint.operator in _LENGTH_OPERATORS | _NUMERIC_OPERATORS | {"pattern"}:
+        if constraint.operator in _PORTABLE_OPERATORS:
             _reject_type_operator_mismatch(field, constraint)
 
     return constraints

sqlrules/errors.py

@@ -85,12 +85,28 @@ class ConfigurationError(SQLRulesError):
     value: Any
 
     def __str__(self) -> str:
-        return (
-            f"Invalid configuration value for {self.option!r}: {self.value!r}. "
-            "Use one of: 'raise', 'warn', 'ignore'."
-            if self.option == "on_unsupported"
-            else f"Invalid configuration value for {self.option!r}: {self.value!r}."
-        )
+        if self.option == "on_unsupported":
+            return (
+                f"Invalid configuration value for {self.option!r}: {self.value!r}. "
+                "Use one of: 'raise', 'warn', 'ignore'."
+            )
+        if self.option == "on_conflict":
+            return (
+                f"Invalid configuration value for {self.option!r}: {self.value!r}. "
+                "Use one of: 'raise', 'replace', 'ignore'."
+            )
+        return f"Invalid configuration value for {self.option!r}: {self.value!r}."
+
+
+@dataclass(slots=True)
+class PluginError(SQLRulesError):
+    """Raised when a plugin fails validation or registration."""
+
+    message: str
+    plugin: Any = None
+
+    def __str__(self) -> str:
+        return self.message
 
 
 class InternalCompilerError(SQLRulesError):

sqlrules/ir.py

@@ -4,9 +4,18 @@ from dataclasses import dataclass, field
 from typing import Any, Literal
 
 OnUnsupported = Literal["raise", "warn", "ignore"]
+OnConflict = Literal["raise", "replace", "ignore"]
 DiagnosticSeverity = Literal["warning", "info"]
 
 
+@dataclass(frozen=True, slots=True)
+class PatternSpec:
+    """Normalized ``pattern`` constraint value (preserves case-folding intent)."""
+
+    pattern: str
+    ignore_case: bool = False
+
+
 @dataclass(frozen=True, slots=True)
 class Constraint:
     field: str
@@ -30,6 +39,7 @@ class Diagnostic:
     operator: str
     value: Any = None
     message: str = ""
+    code: str = ""
 
 
 @dataclass(slots=True)
@@ -52,6 +62,7 @@ class DiagnosticsCollector:
 class CompilationContext:
     on_unsupported: OnUnsupported = "raise"
     collector: DiagnosticsCollector | None = None
+    dialect: str | None = None
 
     def record(
         self,
@@ -61,6 +72,7 @@ class CompilationContext:
         operator: str,
         value: Any = None,
         message: str = "",
+        code: str = "",
     ) -> None:
         if self.collector is None:
             return
@@ -71,6 +83,7 @@ class CompilationContext:
                 operator=operator,
                 value=value,
                 message=message,
+                code=code,
             )
         )
 

sqlrules/markers.py

@@ -0,0 +1,86 @@
+"""Dialect-oriented constraint markers for Annotated metadata.
+
+Markers are extracted into IR as ``Constraint(field, marker.operator, marker.value)``.
+Core does not translate these operators; dialect plugins register translators.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ConstraintMarker(Protocol):
+    """Protocol for Annotated metadata that becomes a SQLRules IR constraint."""
+
+    operator: str
+    value: Any
+
+
+@dataclass(frozen=True, slots=True)
+class JsonContains:
+    """Require JSON/JSONB containment (``json_contains``)."""
+
+    value: Any
+    operator: str = field(default="json_contains", init=False, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class JsonHasKey:
+    """Require a JSON object key (``json_has_key``)."""
+
+    value: Any
+    operator: str = field(default="json_has_key", init=False, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayContains:
+    """Require array containment (``array_contains``)."""
+
+    value: Any
+    operator: str = field(default="array_contains", init=False, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ArrayOverlap:
+    """Require array overlap (``array_overlap``)."""
+
+    value: Any
+    operator: str = field(default="array_overlap", init=False, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class RangeContains:
+    """Require range containment (``range_contains``)."""
+
+    value: Any
+    operator: str = field(default="range_contains", init=False, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class RangeOverlap:
+    """Require range overlap (``range_overlap``)."""
+
+    value: Any
+    operator: str = field(default="range_overlap", init=False, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class FullTextMatch:
+    """Require a full-text match (``fulltext_match``)."""
+
+    value: Any
+    operator: str = field(default="fulltext_match", init=False, repr=False)
+
+
+__all__ = [
+    "ArrayContains",
+    "ArrayOverlap",
+    "ConstraintMarker",
+    "FullTextMatch",
+    "JsonContains",
+    "JsonHasKey",
+    "RangeContains",
+    "RangeOverlap",
+]

sqlrules/plugins.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from sqlrules.errors import PluginError
+from sqlrules.translators import TranslatorRegistry
+
+PLUGIN_API_VERSION = "1"
+
+
+@runtime_checkable
+class SQLRulesPlugin(Protocol):
+    """Explicit extension that registers translators onto a registry."""
+
+    name: str
+    api_version: str
+
+    def register(self, registry: TranslatorRegistry) -> None:
+        """Register constraint translators on ``registry``."""
+
+
+def validate_plugin(plugin: Any) -> SQLRulesPlugin:
+    """Validate a plugin object against the versioned plugin API."""
+    if not isinstance(plugin, SQLRulesPlugin):
+        raise PluginError(
+            message=(
+                f"Plugin {plugin!r} does not implement SQLRulesPlugin "
+                "(requires name, api_version, and register(registry))."
+            ),
+            plugin=plugin,
+        )
+
+    name = getattr(plugin, "name", None)
+    if not isinstance(name, str) or not name:
+        raise PluginError(
+            message=f"Plugin {plugin!r} must declare a non-empty string name.",
+            plugin=plugin,
+        )
+
+    api_version = getattr(plugin, "api_version", None)
+    if api_version != PLUGIN_API_VERSION:
+        raise PluginError(
+            message=(
+                f"Plugin {name!r} declares api_version={api_version!r}, "
+                f"but SQLRules plugin API is {PLUGIN_API_VERSION!r}."
+            ),
+            plugin=plugin,
+        )
+
+    register = getattr(plugin, "register", None)
+    if not callable(register):
+        raise PluginError(
+            message=f"Plugin {name!r} must provide a callable register(registry) method.",
+            plugin=plugin,
+        )
+
+    return plugin

sqlrules/translators.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import inspect
 import operator
 import sys
 import types
@@ -10,8 +11,13 @@ from typing import Any, cast
 from sqlalchemy import func
 from sqlalchemy.sql.elements import ColumnElement
 
-from sqlrules.errors import RegistryError, TranslatorError, UnsupportedConstraintError
-from sqlrules.ir import CompilationContext, Constraint
+from sqlrules.errors import (
+    InvalidTranslatorError,
+    RegistryError,
+    TranslatorError,
+    UnsupportedConstraintError,
+)
+from sqlrules.ir import CompilationContext, Constraint, OnConflict
 
 Translator = Callable[[Constraint, ColumnElement[Any], CompilationContext], ColumnElement[bool]]
 
@@ -93,6 +99,32 @@ def _in_values(
     return cast(ColumnElement[bool], column.in_(constraint.value))
 
 
+def _validate_translator(operator_name: str, translator: Any) -> Translator:
+    if not callable(translator):
+        raise InvalidTranslatorError(operator=operator_name, translator=translator)
+    try:
+        signature = inspect.signature(translator)
+    except (TypeError, ValueError):
+        return cast(Translator, translator)
+
+    params = list(signature.parameters.values())
+    if any(p.kind == inspect.Parameter.VAR_POSITIONAL for p in params):
+        return cast(Translator, translator)
+
+    positional = [
+        p
+        for p in params
+        if p.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        )
+    ]
+    if len(positional) < 3:
+        raise InvalidTranslatorError(operator=operator_name, translator=translator)
+    return cast(Translator, translator)
+
+
 class TranslatorRegistry:
     def __init__(self) -> None:
         self._translators: dict[str, Translator] = {}
@@ -104,13 +136,46 @@ class TranslatorRegistry:
         *,
         replace: bool = False,
     ) -> None:
-        if not replace and operator_name in self._translators:
-            raise RegistryError(f"Translator for {operator_name!r} is already registered.")
-        self._translators[operator_name] = translator
+        self.register_constraint(
+            operator_name,
+            translator,
+            on_conflict="replace" if replace else "raise",
+        )
+
+    def register_constraint(
+        self,
+        operator_name: str,
+        translator: Translator,
+        *,
+        on_conflict: OnConflict = "raise",
+    ) -> None:
+        if on_conflict not in {"raise", "replace", "ignore"}:
+            raise RegistryError(
+                f"Invalid on_conflict value {on_conflict!r}. "
+                "Use one of: 'raise', 'replace', 'ignore'."
+            )
+        validated = _validate_translator(operator_name, translator)
+        if operator_name in self._translators:
+            if on_conflict == "raise":
+                raise RegistryError(f"Translator for {operator_name!r} is already registered.")
+            if on_conflict == "ignore":
+                return
+        self._translators[operator_name] = validated
 
     def lookup(self, operator_name: str) -> Translator | None:
         return self._translators.get(operator_name)
 
+    def operators(self) -> frozenset[str]:
+        return frozenset(self._translators)
+
+    def __contains__(self, operator_name: object) -> bool:
+        return isinstance(operator_name, str) and operator_name in self._translators
+
+    def copy(self) -> TranslatorRegistry:
+        clone = TranslatorRegistry()
+        clone._translators = dict(self._translators)
+        return clone
+
     def translate(
         self,
         constraint: Constraint,
@@ -137,6 +202,7 @@ class TranslatorRegistry:
                     operator=constraint.operator,
                     value=constraint.value,
                     message=message,
+                    code="unsupported_constraint",
                 )
                 warnings.warn(message, SQLRulesWarning, stacklevel=_warning_stacklevel())
             else:
@@ -146,6 +212,7 @@ class TranslatorRegistry:
                     operator=constraint.operator,
                     value=constraint.value,
                     message=message,
+                    code="unsupported_constraint",
                 )
             return None
 

{sqlrules-0.2.0.dist-info → sqlrules-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrules
-Version: 0.2.0
+Version: 0.4.0
 Summary: Compile constrained Pydantic models into SQLAlchemy WHERE-rule dictionaries.
 Project-URL: Homepage, https://github.com/eddiethedean/sqlrules
 Project-URL: Documentation, https://github.com/eddiethedean/sqlrules#readme
@@ -81,7 +81,30 @@ pip install sqlrules
 
 Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 
-## Supported constraints (0.2)
+Optional dialect plugins:
+
+```bash
+pip install sqlrules-postgresql   # ~ / ~*, JSONB, ARRAY, range
+pip install sqlrules-sqlite       # REGEXP helper + JSON
+pip install sqlrules-mysql        # REGEXP, JSON, full-text
+pip install sqlrules-mssql        # JSON + LEN string ops
+```
+
+```python
+from typing import Annotated, Any
+from pydantic import BaseModel, Field
+from sqlrules import Compiler, JsonContains
+from sqlrules_postgresql import PostgresPlugin
+
+class RowFilter(BaseModel):
+    name: Annotated[str, Field(pattern=r"^A")]
+    meta: Annotated[dict[str, Any], JsonContains({"active": True})]
+
+compiler = Compiler(plugins=[PostgresPlugin()], dialect="postgresql")
+rules = compiler.compile(RowFilter, table)
+```
+
+## Supported constraints (0.4)
 
 | Constraint | SQLAlchemy expression |
 |---|---|
@@ -91,7 +114,11 @@ Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 | `Literal[...]` | `column.in_(...)` |
 | `Enum` | `column.in_(...)` |
 
-`pattern` is extracted into IR but has no portable core translator.
+`pattern` is extracted into IR (`PatternSpec`) but has no portable core
+translator. Use a dialect plugin or a custom registry translator.
+
+Dialect markers (`JsonContains`, `ArrayContains`, `RangeContains`,
+`FullTextMatch`, …) live in `sqlrules.markers` and require a dialect plugin.
 
 Unsupported constraints raise `UnsupportedConstraintError` by default.
 Use `on_unsupported="warn"` or `"ignore"` to change that policy for unknown
@@ -103,6 +130,14 @@ constraint operators (unsupported types always raise).
 sqlrules.compile(model, table, *, column_map=None, on_unsupported="raise", cache=True)
 sqlrules.where(rules)    # flatten all expressions
 sqlrules.flatten(rules)  # alias of where()
+
+compiler = sqlrules.Compiler(
+    plugins=[...],           # optional SQLRulesPlugin instances
+    on_conflict="raise",     # raise | replace | ignore
+    dialect=None,            # optional hint for translators
+    on_unsupported="raise",
+    cache=True,
+)
 ```
 
 ## Non-goals
@@ -115,13 +150,17 @@ constraints into SQLAlchemy expressions.
 
 See [`docs/index.md`](docs/index.md) for the full documentation set,
 including the [spec](docs/SPEC.md), [API](docs/API.md),
-[architecture](docs/ARCHITECTURE.md), and [roadmap](docs/ROADMAP.md).
+[plugin system](docs/PLUGIN_SYSTEM.md), [architecture](docs/ARCHITECTURE.md),
+and [roadmap](docs/ROADMAP.md).
 
 ## Development
 
 ```bash
 pip install -e ".[dev]"
-pytest
+pip install -e packages/sqlrules-postgresql -e packages/sqlrules-sqlite \
+  -e packages/sqlrules-mysql -e packages/sqlrules-mssql
+pytest tests packages/sqlrules-postgresql/tests packages/sqlrules-sqlite/tests \
+  packages/sqlrules-mysql/tests packages/sqlrules-mssql/tests
 ruff check .
 mypy src/sqlrules
 python -m benchmarks.bench_compile

sqlrules-0.4.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+sqlrules/__init__.py,sha256=60Wwpv204ZOs36qCHvRWD8r8ZYLvAS3qunLvB3qSWNY,1513
+sqlrules/cache.py,sha256=9NBDunUMvQR3bsx9QxIiO8L8JNbpI1tdLlFNapUZMj8,1051
+sqlrules/columns.py,sha256=TcDhFG8wxgKC3-kwXhOBP27Ekrlfncm-WWrUkMLCplo,2428
+sqlrules/compiler.py,sha256=sVlpcP5qv-BUjKSNwd4Q6I3aQvqVOgDo89EAwxTqo5I,6799
+sqlrules/conformance.py,sha256=WZfjnv3JfQZ2J93VE3kBD8AFlrz0DX6XjuZ7Z_0D0I0,5646
+sqlrules/constraints.py,sha256=nHuX2xuoSnyx-l6D6hk8Ncb946r_IkehtQ2iumbmbzs,14346
+sqlrules/errors.py,sha256=qcSCcnL19kvfzAd1eMN1pVVNbV3cg1WLb94uGna8w-M,2989
+sqlrules/inspectors.py,sha256=mEi7ixA1aQe7lyZtcFvLHVqVsAXt_tm60YNgJrYbrp8,1700
+sqlrules/ir.py,sha256=jUw8BjZeTBHt5o0KcwBfbUfC7VlcEl4McQahTfZ0DAA,2285
+sqlrules/markers.py,sha256=mAFlZYn050wCKCungONWawIvnYlXTF7aG_VzZ7Hz5GQ,2159
+sqlrules/plugins.py,sha256=ClXVdISpgNzVQkQCJk9ptgnXxqWLwi99EBcNP9wYXyI,1740
+sqlrules/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlrules/translators.py,sha256=aw8Q8hgfNUqdUEosUXgMW4IqTTBNUtSA-Yc2aCiPKNs,7949
+sqlrules-0.4.0.dist-info/METADATA,sha256=icGrZdcSygSpxjeX-rYsDJvRYy6xGA0owVvXQf0yy2Y,5485
+sqlrules-0.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+sqlrules-0.4.0.dist-info/licenses/LICENSE,sha256=cLMlkCH6RhjWAkXBWR7LazV98TOG0WkPtCKB5zqqkAs,1078
+sqlrules-0.4.0.dist-info/RECORD,,

sqlrules-0.2.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-sqlrules/__init__.py,sha256=33UBpq4vkVgxLh6m9EU4RNM1gFRdnnZwXtYuZHJjvY4,982
-sqlrules/cache.py,sha256=9NBDunUMvQR3bsx9QxIiO8L8JNbpI1tdLlFNapUZMj8,1051
-sqlrules/columns.py,sha256=TcDhFG8wxgKC3-kwXhOBP27Ekrlfncm-WWrUkMLCplo,2428
-sqlrules/compiler.py,sha256=UgtZfhCGFyt1bMu25koGaCkcd-Z9Lcer5KDF6JIe-bM,4621
-sqlrules/constraints.py,sha256=YcI2TstNoW9GGR4TfoWBzMlmKKNPsqNjTdUr3Cd3rk8,12349
-sqlrules/errors.py,sha256=SOfRXfhwb9wIyrPjukVP_alKEV83hlORyngN0NuCD_8,2533
-sqlrules/inspectors.py,sha256=mEi7ixA1aQe7lyZtcFvLHVqVsAXt_tm60YNgJrYbrp8,1700
-sqlrules/ir.py,sha256=Lq53l4ELGzrYZ0ZqM_fqeLau1kSrod91zjEUIO7_JE4,1945
-sqlrules/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sqlrules/translators.py,sha256=f21pBuDk6r5xKstnEgRiL8ZubFjo5QvbeHJDzOY10nU,5818
-sqlrules-0.2.0.dist-info/METADATA,sha256=28Q8NuNDJLpREon9qGQruaR66_34QQtbTsy4Pr-2kIE,3988
-sqlrules-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-sqlrules-0.2.0.dist-info/licenses/LICENSE,sha256=cLMlkCH6RhjWAkXBWR7LazV98TOG0WkPtCKB5zqqkAs,1078
-sqlrules-0.2.0.dist-info/RECORD,,