sqlrules 0.2.0__tar.gz → 0.3.0__tar.gz

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

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

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

@@ -5,6 +5,30 @@ 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.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 +108,6 @@ 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.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.3.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# 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
+pre-commit install
+```
+
+## Checks
+
+```bash
+ruff check .
+ruff format --check .
+mypy src/sqlrules
+pytest tests packages/sqlrules-postgresql/tests packages/sqlrules-sqlite/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
+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
+  plugin API major (`sqlrules>=0.3,<0.4` 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.3.0):
+
+```bash
+git tag -a v0.3.0 -m "sqlrules 0.3.0"
+git push origin v0.3.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.3.0` is on PyPI (they depend on `sqlrules>=0.3,<0.4`):
+
+```bash
+python -m build packages/sqlrules-postgresql
+python -m build packages/sqlrules-sqlite
+twine upload dist-plugins/*   # after building with --outdir dist-plugins
+```

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrules
-Version: 0.2.0
+Version: 0.3.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,22 @@ 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   # pattern → PostgreSQL ~
+pip install sqlrules-sqlite       # pattern → SQLite REGEXP
+```
+
+```python
+from sqlrules import Compiler
+from sqlrules_postgresql import PostgresPlugin
+
+compiler = Compiler(plugins=[PostgresPlugin()], dialect="postgresql")
+rules = compiler.compile(UserFilter, users)
+```
+
+## Supported constraints (0.3)
 
 | Constraint | SQLAlchemy expression |
 |---|---|
@@ -92,6 +107,8 @@ Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 | `Enum` | `column.in_(...)` |
 
 `pattern` is extracted into IR but has no portable core translator.
+Use a custom registry translator or a dialect plugin
+(`sqlrules-postgresql`, `sqlrules-sqlite`).
 
 Unsupported constraints raise `UnsupportedConstraintError` by default.
 Use `on_unsupported="warn"` or `"ignore"` to change that policy for unknown
@@ -103,6 +120,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 +140,15 @@ 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
+pytest tests packages/sqlrules-postgresql/tests packages/sqlrules-sqlite/tests
 ruff check .
 mypy src/sqlrules
 python -m benchmarks.bench_compile

{sqlrules-0.2.0 → sqlrules-0.3.0}/README.md

@@ -41,7 +41,22 @@ 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   # pattern → PostgreSQL ~
+pip install sqlrules-sqlite       # pattern → SQLite REGEXP
+```
+
+```python
+from sqlrules import Compiler
+from sqlrules_postgresql import PostgresPlugin
+
+compiler = Compiler(plugins=[PostgresPlugin()], dialect="postgresql")
+rules = compiler.compile(UserFilter, users)
+```
+
+## Supported constraints (0.3)
 
 | Constraint | SQLAlchemy expression |
 |---|---|
@@ -52,6 +67,8 @@ Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 | `Enum` | `column.in_(...)` |
 
 `pattern` is extracted into IR but has no portable core translator.
+Use a custom registry translator or a dialect plugin
+(`sqlrules-postgresql`, `sqlrules-sqlite`).
 
 Unsupported constraints raise `UnsupportedConstraintError` by default.
 Use `on_unsupported="warn"` or `"ignore"` to change that policy for unknown
@@ -63,6 +80,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 +100,15 @@ 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
+pytest tests packages/sqlrules-postgresql/tests packages/sqlrules-sqlite/tests
 ruff check .
 mypy src/sqlrules
 python -m benchmarks.bench_compile

{sqlrules-0.2.0 → sqlrules-0.3.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,11 +86,34 @@ 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
+
+class MyPlugin:
+    name = "my-plugin"
+    api_version = PLUGIN_API_VERSION
+
+    def register(self, registry):
+        registry.register_constraint(
+            "pattern",
+            lambda c, col, ctx: col.op("~")(c.value),
+            on_conflict="replace",
+        )
+
+compiler = Compiler(plugins=[MyPlugin()])
+```
+
+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)
@@ -93,9 +129,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.3.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.2.0 → sqlrules-0.3.0}/docs/CONSTRAINTS.md

@@ -11,7 +11,7 @@
 | `multiple_of` | `column % value == 0` |
 | `Literal[...]` | `column.in_(...)` |
 | `Enum` | `column.in_(member values)` |
-| `pattern` | IR only in 0.2 (no portable core translator) |
+| `pattern` | IR in core; translators via plugins / custom registry |
 
 Accepted input forms for the same semantics include `Field(...)`,
 `annotated_types` primitives, `Interval`, `Len`, `conint`/`constr`, and
@@ -20,12 +20,23 @@ Accepted input forms for the same semantics include `Field(...)`,
 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`, register a custom translator:
+To translate `pattern`, use a dialect plugin or register a custom translator:
+
+```python
+from sqlrules import Compiler
+from sqlrules_postgresql import PostgresPlugin
+
+compiler = Compiler(plugins=[PostgresPlugin()], dialect="postgresql")
+```
 
 ```python
 from sqlrules.translators import default_registry
 
 registry = default_registry()
-registry.register("pattern", lambda c, col, ctx: col.op("~")(c.value))
+registry.register_constraint(
+    "pattern",
+    lambda c, col, ctx: col.op("~")(c.value),
+    on_conflict="replace",
+)
 compiler = sqlrules.Compiler(registry=registry)
 ```

{sqlrules-0.2.0 → sqlrules-0.3.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`)
 
 ------------------------------------------------------------------------
 

{sqlrules-0.2.0 → sqlrules-0.3.0}/docs/DIALECT_SUPPORT.md

@@ -36,8 +36,8 @@ Core emits portable SQLAlchemy Core expressions. The table below describes
 
   Dialect             Status        Notes
   ------------ -------------------- --------------------------------
-  SQLite             Core (dev)     Primary local/CI smoke target
-  PostgreSQL         Core (planned) Enhanced features via future plugin
+  SQLite             Core + plugin  `sqlrules-sqlite` adds `pattern` (REGEXP)
+  PostgreSQL         Core + plugin  `sqlrules-postgresql` adds `pattern` (`~`)
   MySQL              Core (planned) Enhanced features via future plugin
   MariaDB            Core (planned) Follows MySQL where practical
   SQL Server         Core (planned) Enhanced features via future plugin
@@ -63,31 +63,35 @@ These should compile identically across supported databases:
 
 # PostgreSQL
 
-Potential enhancements:
+Package: `sqlrules-postgresql`
+
+0.3 enhancement:
+
+-   Native regular expressions via `pattern` → `column ~ value`
+
+Potential later enhancements (0.4+):
 
--   Native regular expressions
 -   ARRAY operators
 -   JSONB operators
 -   Range types
 -   Full-text search
 
-Suggested package:
-
-    sqlrules-postgresql
-
 ------------------------------------------------------------------------
 
 # SQLite
 
+Package: `sqlrules-sqlite`
+
 Goals:
 
 -   Reliable test platform
 -   Portable numeric comparisons
 -   Portable string-length operations
+-   `pattern` via `REGEXP` (application must enable REGEXP on the connection)
 
 Limitations:
 
--   REGEXP requires an extension
+-   REGEXP requires an extension / `create_function`
 -   Limited advanced JSON functionality
 
 ------------------------------------------------------------------------

{sqlrules-0.2.0 → sqlrules-0.3.0}/docs/ERRORS.md

@@ -25,10 +25,11 @@ SQLRulesError
 ├── MissingColumnError
 ├── UnsupportedConstraintError
 ├── TranslatorError
-├── InvalidTranslatorError   (reserved in 0.2)
+├── InvalidTranslatorError
 ├── RegistryError
 ├── ConfigurationError
-└── InternalCompilerError    (reserved in 0.2)
+├── PluginError
+└── InternalCompilerError    (reserved)
 ```
 
 All public exceptions inherit from `SQLRulesError`.
@@ -89,8 +90,9 @@ expression (unexpected SQLAlchemy errors wrapped by the registry).
 
 # InvalidTranslatorError
 
-Reserved for future validation of custom translators. Not raised by the
-0.2 compiler path.
+Raised when registering a translator that is not callable or does not
+accept at least three positional parameters (`constraint`, `column`,
+`context`). Variadic `*args` translators are accepted.
 
 ------------------------------------------------------------------------
 
@@ -110,7 +112,14 @@ Missing operators raise `UnsupportedConstraintError`, not `RegistryError`.
 
 Raised when compiler configuration is inconsistent.
 
-In 0.2 this is raised for an invalid `on_unsupported` mode only.
+Raised for an invalid `on_unsupported` or `on_conflict` mode.
+
+------------------------------------------------------------------------
+
+# PluginError
+
+Raised when a plugin fails validation (missing `name` / `register`, or
+`api_version` mismatch with `PLUGIN_API_VERSION`).
 
 ------------------------------------------------------------------------
 
@@ -151,11 +160,17 @@ After `compile` / `bind` / `compile_model`, inspect skipped constraints:
 compiler = sqlrules.Compiler(on_unsupported="warn")
 rules = compiler.compile(Model, table)
 for diag in compiler.diagnostics:
-    print(diag.severity, diag.field, diag.operator, diag.message)
+    print(diag.code, diag.severity, diag.field, diag.operator, diag.message)
 ```
 
 `Diagnostic` fields: `severity` (`"warning"` | `"info"`), `field`,
-`operator`, `value`, `message`.
+`operator`, `value`, `message`, `code`.
+
+Stable diagnostic codes (0.3):
+
+| Code | When |
+|---|---|
+| `unsupported_constraint` | Operator skipped under `warn` / `ignore` |
 
 `compile_model` clears diagnostics. Diagnostics are separate from
 exceptions and do not change the rules dict return type.

{sqlrules-0.2.0 → sqlrules-0.3.0}/docs/INTERNAL_API.md

@@ -145,16 +145,19 @@ Suggested methods:
 
 ``` python
 register(...)
+register_constraint(..., on_conflict=...)
 lookup(...)
 translate(...)
+operators()
+copy()
 ```
 
 Registry responsibilities:
 
 -   operator lookup
--   dialect overrides
--   plugin registration
--   conflict detection
+-   conflict detection (`raise` / `replace` / `ignore`)
+-   translator validation
+-   hosting plugin registrations (via `Compiler(plugins=...)`)
 
 ------------------------------------------------------------------------
 
@@ -189,6 +192,7 @@ Suggested contents:
 
 -   compiler options (`on_unsupported`)
 -   diagnostics collector
+-   optional `dialect` hint (explicit; never auto-detected)
 
 Avoid global state.
 
@@ -202,7 +206,8 @@ Internal diagnostics record:
 -   ignored skips (`severity="info"`)
 
 Exposed after compile via `Compiler.diagnostics`. Diagnostics are
-separate from exceptions.
+separate from exceptions. Each diagnostic may include a stable `code`
+(for example `unsupported_constraint`).
 
 ------------------------------------------------------------------------
 

{sqlrules-0.2.0 → sqlrules-0.3.0}/docs/MILESTONES.md

@@ -93,7 +93,7 @@ Improve correctness and extensibility.
 
 ------------------------------------------------------------------------
 
-# 0.3.0 --- Plugin System
+# 0.3.0 --- Plugin System ✅
 
 ## Goals