sqlrules 0.2.0__tar.gz → 0.4.0__tar.gz

{sqlrules-0.2.0 → sqlrules-0.4.0}/.gitignore

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

{sqlrules-0.2.0 → sqlrules-0.4.0}/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
 
+## [0.4.0] - 2026-07-10
+
+### Added
+
+- `ConstraintMarker` protocol and shared markers in `sqlrules.markers`:
+  `JsonContains`, `JsonHasKey`, `ArrayContains`, `ArrayOverlap`,
+  `RangeContains`, `RangeOverlap`, `FullTextMatch`
+- `PatternSpec` IR value for `pattern` (preserves `ignore_case` from
+  `re.Pattern` flags); `pattern_text()` helper for plugins
+- `list` / `dict` annotations for marker-driven fields (portable
+  constraints on containers still raise)
+- Expanded dialect plugins:
+  - `sqlrules-postgresql` — `~` / `~*`, JSONB, ARRAY, range operators
+  - `sqlrules-sqlite` — `register_regexp()`, flag-aware REGEXP, JSON helpers
+  - `sqlrules-mysql` — REGEXP, JSON, `fulltext_match`
+  - `sqlrules-mssql` — JSON helpers, `LEN` overrides for length constraints
+- Conformance helpers accept optional `model` / `table` / `field` for
+  non-`pattern` operators
+
+### Changed
+
+- Package version bumped to 0.4.0
+- Official plugin packages depend on `sqlrules>=0.4,<0.5`
+
+## [0.3.0] - 2026-07-10
+
+### Added
+
+- Versioned plugin API: `SQLRulesPlugin`, `PLUGIN_API_VERSION` (`"1"`),
+  and `PluginError`
+- `Compiler(plugins=..., on_conflict=..., dialect=...)` for explicit
+  plugin registration (no auto-discovery)
+- Expanded registry API: `register_constraint`, conflict policies
+  (`raise` / `replace` / `ignore`), `copy()`, `operators()`, and
+  `__contains__`
+- `InvalidTranslatorError` raised for non-callable or wrong-arity
+  translators at registration time
+- `Diagnostic.code` (e.g. `unsupported_constraint` on warn/ignore skips)
+- Optional `CompilationContext.dialect` hint (never auto-detected)
+- Plugin conformance helpers in `sqlrules.conformance`
+- Official starter dialect packages:
+  - `sqlrules-postgresql` (`pattern` → `~`)
+  - `sqlrules-sqlite` (`pattern` → `REGEXP`)
+
+### Changed
+
+- Package version bumped to 0.3.0
+
 ## [0.2.0] - 2026-07-10
 
 ### Added
@@ -84,5 +132,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Docs clarify that `on_unsupported` does not soften unsupported types;
   plugin / two-phase compile designs are marked as future
 
+[0.4.0]: https://github.com/eddiethedean/sqlrules/releases/tag/v0.4.0
+[0.3.0]: https://github.com/eddiethedean/sqlrules/releases/tag/v0.3.0
 [0.2.0]: https://github.com/eddiethedean/sqlrules/releases/tag/v0.2.0
 [0.1.0]: https://github.com/eddiethedean/sqlrules/releases/tag/v0.1.0

sqlrules-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing
+
+Thanks for helping improve SQLRules.
+
+## Principles
+
+- Keep the public API minimal.
+- Every feature must map directly to SQLAlchemy expressions.
+- Unsupported Pydantic features should not be approximated.
+- Prefer fail-fast behavior over silent semantic changes.
+- Update relevant docs before or alongside implementation.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pip install -e packages/sqlrules-postgresql -e packages/sqlrules-sqlite \
+  -e packages/sqlrules-mysql -e packages/sqlrules-mssql
+pre-commit install
+```
+
+## Checks
+
+```bash
+ruff check .
+ruff format --check .
+mypy src/sqlrules
+pytest tests packages/sqlrules-postgresql/tests packages/sqlrules-sqlite/tests \
+  packages/sqlrules-mysql/tests packages/sqlrules-mssql/tests
+python -m build && twine check dist/*
+python -m build packages/sqlrules-postgresql --outdir dist-plugins
+python -m build packages/sqlrules-sqlite --outdir dist-plugins
+python -m build packages/sqlrules-mysql --outdir dist-plugins
+python -m build packages/sqlrules-mssql --outdir dist-plugins
+twine check dist-plugins/*
+```
+
+CI also verifies `pyproject.toml` / `__version__` sync and that the built
+wheel imports cleanly.
+
+## Plugins
+
+- Declare `name`, `api_version` (`PLUGIN_API_VERSION`), and `register(registry)`.
+- Prefer `register_constraint(..., on_conflict=...)`.
+- Run `sqlrules.conformance.run_basic_conformance(plugin)`.
+- Official dialect packages live under `packages/` and should track the
+  core minor (`sqlrules>=0.4,<0.5` while `PLUGIN_API_VERSION == "1"`).
+
+## Pull requests
+
+- Keep changes focused.
+- Add or update tests for every constraint or error path you touch.
+- Match existing code style and documentation tone.
+
+## Releasing
+
+Releases are published to PyPI by pushing a version tag. Before tagging:
+
+1. Confirm `pyproject.toml` and `sqlrules.__version__` match the changelog.
+2. Run the full check suite (`ruff`, `mypy`, `pytest`).
+3. Ensure CI is green on `main`.
+
+Then create and push the tag (example for 0.4.0):
+
+```bash
+git tag -a v0.4.0 -m "sqlrules 0.4.0"
+git push origin v0.4.0
+```
+
+The [release workflow](.github/workflows/release.yml) runs CI, verifies the
+tag matches `pyproject.toml` / `__version__`, builds the sdist/wheel, and
+publishes **core** `sqlrules` with `PYPI_API_TOKEN`.
+
+Dialect plugin packages under `packages/` are versioned independently and
+are **not** published by the core release workflow. Publish them separately
+after core `0.4.0` is on PyPI (they depend on `sqlrules>=0.4,<0.5`):
+
+```bash
+python -m build packages/sqlrules-postgresql --outdir dist-plugins
+python -m build packages/sqlrules-sqlite --outdir dist-plugins
+python -m build packages/sqlrules-mysql --outdir dist-plugins
+python -m build packages/sqlrules-mssql --outdir dist-plugins
+twine upload dist-plugins/*
+```

{sqlrules-0.2.0 → sqlrules-0.4.0}/PKG-INFO

@@ -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.2.0 → sqlrules-0.4.0}/README.md

@@ -41,7 +41,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 |
 |---|---|
@@ -51,7 +74,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
@@ -63,6 +90,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
@@ -75,13 +110,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.2.0 → sqlrules-0.4.0}/docs/API.md

@@ -31,6 +31,8 @@ binding. Unconstrained fields are omitted and do not require a column.
 
 Unsupported types always raise, regardless of `on_unsupported`.
 
+Module-level `compile` does not accept plugins; use `Compiler` for extensions.
+
 ## `where` / `flatten`
 
 ```python
@@ -49,6 +51,9 @@ Flatten a rule dictionary into a single list of expressions suitable for
 compiler = sqlrules.Compiler(
     on_unsupported="raise",
     registry=None,
+    plugins=None,
+    on_conflict="raise",
+    dialect=None,
     cache=True,
     model_cache=None,  # optional shared ModelIRCache; default is process-wide
 )
@@ -62,8 +67,16 @@ rules = compiler.bind(model_ir, table, column_map=None)
 compiler.diagnostics
 ```
 
+| Parameter | Description |
+|---|---|
+| `plugins` | Optional sequence of `SQLRulesPlugin` objects registered at init |
+| `on_conflict` | Default conflict policy for plugin `register()`: `"raise"`, `"replace"`, or `"ignore"` |
+| `dialect` | Optional string hint stored on `CompilationContext` (never auto-detected) |
+| `registry` | Optional base `TranslatorRegistry`; copied when `plugins` is non-empty |
+
 Reusable compiler instance with a fixed unsupported-constraint policy,
-optional custom translator registry, and optional Phase-1 metadata cache.
+optional plugins, optional custom translator registry, and optional Phase-1
+metadata cache.
 
 `compile_model` / `bind` separate static IR extraction from table binding so
 the same `ModelIR` can be reused across tables.
@@ -73,14 +86,41 @@ on the same `Compiler` instance (diagnostics are per-instance and not locked).
 The shared Phase-1 IR cache is thread-safe for concurrent reads/writes across
 instances.
 
+## Plugins
+
+```python
+from sqlrules import PLUGIN_API_VERSION, Compiler
+from sqlrules.constraints import pattern_text
+
+class MyPlugin:
+    name = "my-plugin"
+    api_version = PLUGIN_API_VERSION
+
+    def register(self, registry):
+        registry.register_constraint(
+            "pattern",
+            lambda c, col, ctx: col.op("~")(pattern_text(c.value)[0]),
+            on_conflict="replace",
+        )
+
+compiler = Compiler(plugins=[MyPlugin()])
+```
+
+Dialect markers (`JsonContains`, `ArrayContains`, …) are extracted into IR
+and translated by official dialect plugins. See [PLUGIN_SYSTEM.md](PLUGIN_SYSTEM.md).
+Conformance helpers live in `sqlrules.conformance`.
+
 ## Other exports
 
 Also exported for advanced use and typing:
 
 - `__version__`
+- `PLUGIN_API_VERSION`, `SQLRulesPlugin`
 - `SQLRulesWarning`
 - `CompilationContext`, `Constraint`, `FieldDescriptor`, `FieldIR`, `ModelIR`,
-  `Diagnostic` (IR helpers)
+  `Diagnostic`, `PatternSpec`
+- Markers: `ConstraintMarker`, `JsonContains`, `JsonHasKey`, `ArrayContains`,
+  `ArrayOverlap`, `RangeContains`, `RangeOverlap`, `FullTextMatch`
 
 `DiagnosticsCollector` and `ModelIRCache` are internal (import from
 `sqlrules.ir` / `sqlrules.cache` only if you accept instability).
@@ -93,9 +133,10 @@ All public exceptions inherit from `SQLRulesError`:
 - `MissingColumnError`
 - `UnsupportedConstraintError`
 - `TranslatorError`
-- `InvalidTranslatorError` (reserved; not raised in 0.2)
+- `InvalidTranslatorError`
 - `RegistryError`
 - `ConfigurationError`
-- `InternalCompilerError` (reserved; not raised in 0.2)
+- `PluginError`
+- `InternalCompilerError` (reserved)
 
 See [ERRORS.md](ERRORS.md) for details.

{sqlrules-0.2.0 → sqlrules-0.4.0}/docs/COMPILER.md

@@ -145,13 +145,14 @@ Translation remains deterministic.
 Available today:
 
 -   Inject a custom `TranslatorRegistry` via `Compiler(registry=...)`
-    (including a `pattern` translator).
+-   Register versioned plugins via `Compiler(plugins=[...])`
+-   Override operators with `register_constraint(..., on_conflict=...)`
+-   Optional `dialect=` hint on `CompilationContext`
 
-Future plugin hooks:
+Reserved for later:
 
--   Register dialect-specific translators via a plugin API.
--   Override built-in mappings through versioned plugins.
--   Add new IR transforms.
+-   Compiler pass plugins
+-   Entry-point / auto-discovery
 
 ## Design Principles
 

sqlrules-0.4.0/docs/CONSTRAINTS.md

@@ -0,0 +1,55 @@
+# Supported Constraint Mapping
+
+| Constraint | SQLAlchemy expression |
+|---|---|
+| `gt` | `column > value` |
+| `ge` | `column >= value` |
+| `lt` | `column < value` |
+| `le` | `column <= value` |
+| `min_length` | `func.length(column) >= value` |
+| `max_length` | `func.length(column) <= value` |
+| `multiple_of` | `column % value == 0` |
+| `Literal[...]` | `column.in_(...)` |
+| `Enum` | `column.in_(member values)` |
+| `pattern` | IR (`PatternSpec`); translators via plugins / custom registry |
+
+## Dialect markers (`sqlrules.markers`)
+
+| Marker | IR operator | Typical plugin translation |
+|---|---|---|
+| `JsonContains` | `json_contains` | JSONB / JSON containment |
+| `JsonHasKey` | `json_has_key` | JSON key existence |
+| `ArrayContains` | `array_contains` | PostgreSQL array containment |
+| `ArrayOverlap` | `array_overlap` | PostgreSQL array overlap |
+| `RangeContains` | `range_contains` | PostgreSQL range `@>` |
+| `RangeOverlap` | `range_overlap` | PostgreSQL range `&&` |
+| `FullTextMatch` | `fulltext_match` | MySQL `MATCH ... AGAINST` |
+
+Accepted input forms for portable constraints include `Field(...)`,
+`annotated_types` primitives, `Interval`, `Len`, `conint`/`constr`, and
+`StringConstraints` (length attributes; `pattern` becomes `PatternSpec` IR).
+
+Constraints without a deterministic SQL equivalent are rejected by default.
+See [TYPE_SUPPORT.md](TYPE_SUPPORT.md) and [ERRORS.md](ERRORS.md).
+
+To translate `pattern` or markers, use a dialect plugin:
+
+```python
+from sqlrules import Compiler, JsonContains
+from sqlrules_postgresql import PostgresPlugin
+
+compiler = Compiler(plugins=[PostgresPlugin()], dialect="postgresql")
+```
+
+```python
+from sqlrules.constraints import pattern_text
+from sqlrules.translators import default_registry
+
+registry = default_registry()
+registry.register_constraint(
+    "pattern",
+    lambda c, col, ctx: col.op("~")(pattern_text(c.value)[0]),
+    on_conflict="replace",
+)
+compiler = sqlrules.Compiler(registry=registry)
+```

{sqlrules-0.2.0 → sqlrules-0.4.0}/docs/DESIGN_DECISIONS.md

@@ -231,16 +231,18 @@ SQL Server, or Oracle plugins.
 
 ------------------------------------------------------------------------
 
-# Decision 9: Plugins Are Explicit (Future)
+# Decision 9: Plugins Are Explicit
 
 ## Decision
 
-SQLRules 0.2 does **not** ship a plugin API. Customization today is limited
-to injecting a `TranslatorRegistry` into `Compiler(registry=...)` (for
-example a custom `pattern` translator).
+SQLRules 0.3 ships an explicit plugin API:
 
-A future release may add explicit plugin registration (for example
-`Compiler(plugins=[...])`) without automatic discovery.
+```python
+Compiler(plugins=[PostgresPlugin()], on_conflict="raise", dialect="postgresql")
+```
+
+There is no automatic discovery. Plugins declare `api_version` matching
+`PLUGIN_API_VERSION`.
 
 ## Rationale
 
@@ -249,8 +251,8 @@ reproducibility, and keeps the compiler deterministic.
 
 ## Consequences
 
-Do not treat plugin examples in design docs as available in 0.2. See
-[PLUGIN_SYSTEM.md](PLUGIN_SYSTEM.md) for the planned design.
+See [PLUGIN_SYSTEM.md](PLUGIN_SYSTEM.md). Official starter packages:
+`sqlrules-postgresql` and `sqlrules-sqlite`.
 
 ------------------------------------------------------------------------
 
@@ -438,12 +440,12 @@ This may improve ergonomics while preserving dictionary output.
 
 ## Should Regex Be Core or Dialect Plugin?
 
-**Decided for 0.2:**
+**Decided for 0.2 / 0.3:**
 
 - IR support in core (`Constraint(operator="pattern", ...)`)
 - No portable core translator
-- Translator support via custom `TranslatorRegistry` today, dialect
-  plugins in 0.3+
+- Translator support via `TranslatorRegistry` and dialect plugins
+  (`sqlrules-postgresql`, `sqlrules-sqlite`)
 
 ------------------------------------------------------------------------