sqlrules 0.1.0__tar.gz

sqlrules-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo

sqlrules-0.1.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+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.1.0] - 2026-07-10
+
+### Added
+
+- Public API: `compile()`, `where()`, `flatten()`, and `Compiler`
+- Constraint support: `gt`, `ge`, `lt`, `le`, `multiple_of`, `min_length`,
+  `max_length`, `Literal`, and `Enum`
+- Equivalent Pydantic forms: `Interval`, `conint`/`constr`, `Len`, and
+  `StringConstraints` (supported attributes only)
+- Fail-fast handling for unsupported metadata (`pattern`, validators,
+  decimal precision) and unsupported types (containers, UUID, time,
+  timedelta)
+- Field alias resolution when binding SQLAlchemy columns (`alias`,
+  `validation_alias`, and `serialization_alias` string forms)
+- Unsupported-constraint policies: `raise` (default), `warn`, and `ignore`
+  for unknown **operators** (unsupported types always raise)
+- Exception hierarchy rooted at `SQLRulesError`
+- Column resolution for SQLAlchemy `Table` objects, ORM attributes, and
+  explicit `column_map`
+- Documentation for the compiler, translators, errors, types, and roadmap
+
+### Fixed
+
+- Column resolution no longer treats non-column `Table` attributes (such as
+  `name` or `is_selectable`) as columns, which previously produced invalid
+  SQL or Python `bool` values in the rules dict
+- `Annotated[T, ...] | None` / `Optional[Annotated[T, ...]]` now unwraps
+  nested metadata correctly
+- String `validation_alias` / `serialization_alias` participate in column
+  binding
+- `multiple_of` values `<= 0` are rejected
+- Length constraints on non-`str` fields and numeric constraints on `str` /
+  `bool` fields are rejected
+
+### Changed
+
+- Alias candidates are preferred over the Python field name when binding
+  columns
+- Unconstrained fields are skipped and no longer require a matching column
+- Packaging URLs point at `eddiethedean/sqlrules`
+- Docs clarify that `on_unsupported` does not soften unsupported types;
+  plugin / two-phase compile designs are marked as future
+
+[0.1.0]: https://github.com/eddiethedean/sqlrules/releases/tag/v0.1.0

sqlrules-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# 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]"
+pre-commit install
+```
+
+## Checks
+
+```bash
+ruff check .
+ruff format .
+mypy src/sqlrules
+pytest
+```
+
+## 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
+
+0.1.x 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.1.0):
+
+```bash
+git tag -a v0.1.0 -m "sqlrules 0.1.0"
+git push origin v0.1.0
+```
+
+The [release workflow](.github/workflows/release.yml) runs CI, builds the
+sdist/wheel, and publishes with `PYPI_API_TOKEN`.

sqlrules-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SQLRules Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sqlrules-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: sqlrules
+Version: 0.1.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
+Project-URL: Repository, https://github.com/eddiethedean/sqlrules
+Project-URL: Changelog, https://github.com/eddiethedean/sqlrules/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/eddiethedean/sqlrules/issues
+Author: SQLRules Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: compiler,constraints,filters,pydantic,sqlalchemy,where
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: annotated-types>=0.6
+Requires-Dist: pydantic>=2.0
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SQLRules
+
+**Compile constrained Pydantic models into SQLAlchemy WHERE-rule dictionaries.**
+
+One package. One job. Deterministic output. Zero database dependency.
+
+```python
+from typing import Annotated
+from pydantic import BaseModel, Field
+from sqlalchemy import Table, Column, Integer, String, MetaData
+
+import sqlrules
+
+metadata = MetaData()
+
+users = Table(
+    "users",
+    metadata,
+    Column("age", Integer),
+    Column("name", String),
+)
+
+class UserFilter(BaseModel):
+    age: Annotated[int, Field(ge=18, le=65)]
+    name: Annotated[str, Field(min_length=2)]
+
+rules = sqlrules.compile(UserFilter, users)
+# {
+#     "age": [users.c.age >= 18, users.c.age <= 65],
+#     "name": [func.length(users.c.name) >= 2],
+# }
+
+stmt = users.select().where(*sqlrules.where(rules))
+```
+
+## Install
+
+```bash
+pip install sqlrules
+```
+
+Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
+
+## Supported constraints (0.1)
+
+| Constraint | SQLAlchemy expression |
+|---|---|
+| `gt` / `ge` / `lt` / `le` | `column > / >= / < / <= value` |
+| `multiple_of` | `column % value == 0` |
+| `min_length` / `max_length` | `func.length(column) >= / <= value` |
+| `Literal[...]` | `column.in_(...)` |
+| `Enum` | `column.in_(...)` |
+
+Unsupported constraints raise `UnsupportedConstraintError` by default.
+Use `on_unsupported="warn"` or `"ignore"` to change that policy for unknown
+constraint operators (unsupported types always raise).
+
+## Public API
+
+```python
+sqlrules.compile(model, table, *, column_map=None, on_unsupported="raise")
+sqlrules.where(rules)    # flatten all expressions
+sqlrules.flatten(rules)  # alias of where()
+```
+
+## Non-goals
+
+SQLRules is not an ORM, validator, query builder, SQL string generator,
+migration tool, or database client. It only compiles supported Pydantic
+constraints into SQLAlchemy expressions.
+
+## Documentation
+
+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).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src/sqlrules
+```
+
+## License
+
+MIT

sqlrules-0.1.0/README.md

@@ -0,0 +1,89 @@
+# SQLRules
+
+**Compile constrained Pydantic models into SQLAlchemy WHERE-rule dictionaries.**
+
+One package. One job. Deterministic output. Zero database dependency.
+
+```python
+from typing import Annotated
+from pydantic import BaseModel, Field
+from sqlalchemy import Table, Column, Integer, String, MetaData
+
+import sqlrules
+
+metadata = MetaData()
+
+users = Table(
+    "users",
+    metadata,
+    Column("age", Integer),
+    Column("name", String),
+)
+
+class UserFilter(BaseModel):
+    age: Annotated[int, Field(ge=18, le=65)]
+    name: Annotated[str, Field(min_length=2)]
+
+rules = sqlrules.compile(UserFilter, users)
+# {
+#     "age": [users.c.age >= 18, users.c.age <= 65],
+#     "name": [func.length(users.c.name) >= 2],
+# }
+
+stmt = users.select().where(*sqlrules.where(rules))
+```
+
+## Install
+
+```bash
+pip install sqlrules
+```
+
+Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
+
+## Supported constraints (0.1)
+
+| Constraint | SQLAlchemy expression |
+|---|---|
+| `gt` / `ge` / `lt` / `le` | `column > / >= / < / <= value` |
+| `multiple_of` | `column % value == 0` |
+| `min_length` / `max_length` | `func.length(column) >= / <= value` |
+| `Literal[...]` | `column.in_(...)` |
+| `Enum` | `column.in_(...)` |
+
+Unsupported constraints raise `UnsupportedConstraintError` by default.
+Use `on_unsupported="warn"` or `"ignore"` to change that policy for unknown
+constraint operators (unsupported types always raise).
+
+## Public API
+
+```python
+sqlrules.compile(model, table, *, column_map=None, on_unsupported="raise")
+sqlrules.where(rules)    # flatten all expressions
+sqlrules.flatten(rules)  # alias of where()
+```
+
+## Non-goals
+
+SQLRules is not an ORM, validator, query builder, SQL string generator,
+migration tool, or database client. It only compiles supported Pydantic
+constraints into SQLAlchemy expressions.
+
+## Documentation
+
+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).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src/sqlrules
+```
+
+## License
+
+MIT

sqlrules-0.1.0/docs/API.md

@@ -0,0 +1,75 @@
+# Public API
+
+SQLRules exposes a deliberately small public surface.
+
+## `compile`
+
+```python
+sqlrules.compile(
+    model,
+    table,
+    *,
+    column_map=None,
+    on_unsupported="raise",
+) -> dict[str, list[ColumnElement[bool]]]
+```
+
+Compile a constrained Pydantic model into a field-keyed rule dictionary.
+
+| Parameter | Description |
+|---|---|
+| `model` | Pydantic `BaseModel` subclass |
+| `table` | SQLAlchemy `Table`, alias, ORM class, or object with `.c` |
+| `column_map` | Optional explicit `field_name` or alias → column mapping |
+| `on_unsupported` | `"raise"` (default), `"warn"`, or `"ignore"` for unknown **operators** only |
+
+Rule dictionary keys are always the Python field names. String field aliases
+(`alias`, `validation_alias`, `serialization_alias`) are used only for column
+binding. Unconstrained fields are omitted and do not require a column.
+
+Unsupported types always raise, regardless of `on_unsupported`.
+
+## `where` / `flatten`
+
+```python
+sqlrules.where(rules) -> list[ColumnElement[bool]]
+sqlrules.flatten(rules) -> list[ColumnElement[bool]]
+```
+
+Flatten a rule dictionary into a single list of expressions suitable for
+`Query.where(*expressions)` or `select(...).where(*expressions)`.
+
+`where` and `flatten` are identical aliases.
+
+## `Compiler`
+
+```python
+compiler = sqlrules.Compiler(on_unsupported="raise", registry=None)
+rules = compiler.compile(model, table, column_map=None)
+```
+
+Reusable compiler instance with a fixed unsupported-constraint policy and
+optional custom translator registry.
+
+## Other exports
+
+Also exported for advanced use and typing:
+
+- `__version__`
+- `SQLRulesWarning`
+- `CompilationContext`, `Constraint`, `FieldDescriptor` (IR helpers)
+
+## Exceptions
+
+All public exceptions inherit from `SQLRulesError`:
+
+- `InvalidModelError`
+- `MissingColumnError`
+- `UnsupportedConstraintError`
+- `TranslatorError`
+- `InvalidTranslatorError` (reserved; not raised in 0.1)
+- `RegistryError`
+- `ConfigurationError`
+- `InternalCompilerError` (reserved; not raised in 0.1)
+
+See [ERRORS.md](ERRORS.md) for details.

sqlrules-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,25 @@
+# Architecture
+
+```text
+Pydantic Model
+    ↓
+Metadata Reader
+    ↓
+Constraint IR
+    ↓
+SQLAlchemy Compiler
+    ↓
+Rule Dictionary
+```
+
+SQLRules is a pure compiler pipeline:
+
+1. **Inspect** the Pydantic model and preserve field declaration order.
+2. **Resolve** each field to a SQLAlchemy column.
+3. **Extract** supported constraints into a dialect-neutral IR.
+4. **Translate** each IR constraint into one SQLAlchemy expression.
+5. **Assemble** expressions into `dict[str, list[ColumnElement[bool]]]`.
+
+The compiler never connects to a database, executes SQL, or renders SQL
+strings. See [COMPILER.md](COMPILER.md) and [INTERNAL_API.md](INTERNAL_API.md)
+for stage-level detail.

sqlrules-0.1.0/docs/COMPILER.md

@@ -0,0 +1,168 @@
+# SQLRules Compiler Architecture
+
+## Purpose
+
+The SQLRules compiler transforms a constrained Pydantic model into a
+dictionary of SQLAlchemy WHERE expressions.
+
+The compiler never connects to a database, executes SQL, or generates
+SQL strings. It only produces SQLAlchemy expression objects.
+
+## Pipeline
+
+``` text
+Pydantic Model
+      │
+      ▼
+Model Introspection
+      │
+      ▼
+Field Extraction
+      │
+      ▼
+Constraint Extraction
+      │
+      ▼
+Intermediate Representation (IR)
+      │
+      ▼
+Constraint Translators
+      │
+      ▼
+SQLAlchemy Expressions
+      │
+      ▼
+Rule Dictionary
+```
+
+## Stage 1 -- Model Introspection
+
+Inputs: - Pydantic BaseModel subclass - SQLAlchemy Table, Alias, ORM
+class, or column mapping
+
+Responsibilities: - Validate the input model. - Enumerate model
+fields. - Preserve declaration order.
+
+Output: - Iterable of field definitions.
+
+## Stage 2 -- Field Extraction
+
+For each field:
+
+-   Python type
+-   Optionality
+-   Metadata
+-   Field name
+-   Alias (optional)
+
+Unsupported field definitions fail fast.
+
+## Stage 3 -- Constraint Extraction
+
+Read only constraints that have deterministic SQL equivalents.
+
+Examples: - gt - ge - lt - le - multiple_of - min_length - max_length -
+Literal - Enum
+
+Constraints without SQL equivalents are delegated to the
+unsupported-constraint policy.
+
+## Stage 4 -- Intermediate Representation
+
+Each constraint becomes a normalized object.
+
+Example:
+
+``` text
+Constraint(
+    field="age",
+    operator="ge",
+    value=18,
+)
+```
+
+The IR isolates compiler logic from both Pydantic and SQLAlchemy APIs.
+
+## Stage 5 -- Translators
+
+Each constraint is translated independently.
+
+Examples:
+
+-   ge → column \>= value
+-   gt → column \> value
+-   min_length → func.length(column) \>= value
+-   Literal → column.in\_(...)
+
+Every translator returns one SQLAlchemy expression.
+
+## Stage 6 -- Rule Assembly
+
+Expressions are grouped by field.
+
+Example:
+
+``` python
+{
+    "age": [
+        users.c.age >= 18,
+        users.c.age <= 65,
+    ]
+}
+```
+
+Ordering is deterministic and follows the source model.
+
+## Error Handling
+
+Modes:
+
+-   raise (default)
+-   warn
+-   ignore
+
+Errors include:
+
+-   UnsupportedConstraintError
+-   MissingColumnError
+-   InvalidModelError
+-   TranslatorError
+
+## Caching
+
+Future versions may cache compiled metadata using the model type as the
+cache key. Translation remains deterministic.
+
+## Extension Points
+
+Future plugin hooks:
+
+-   Register custom translators.
+-   Register dialect-specific translators.
+-   Override built-in mappings.
+-   Add new IR transforms.
+
+## Design Principles
+
+-   Pure function compiler
+-   No database dependency
+-   Deterministic output
+-   SQLAlchemy-first
+-   Easy to test
+-   Easy to extend
+-   Fail fast on unsupported semantics
+
+## Public Contract
+
+``` python
+rules = sqlrules.compile(UserFilter, users)
+```
+
+Returns:
+
+``` python
+dict[str, list]
+```
+
+where each value is a list of SQLAlchemy boolean expressions suitable
+for passing directly to `.where(*expressions)`.

sqlrules-0.1.0/docs/CONSTRAINTS.md

@@ -0,0 +1,20 @@
+# 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)` |
+
+Accepted input forms for the same semantics include `Field(...)`,
+`annotated_types` primitives, `Interval`, `Len`, `conint`/`constr`, and
+`StringConstraints` (length attributes only).
+
+Constraints without a deterministic SQL equivalent are rejected by default.
+See [TYPE_SUPPORT.md](TYPE_SUPPORT.md) and [ERRORS.md](ERRORS.md).

sqlrules-0.1.0/docs/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+See the root [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup,
+checks, and pull-request guidelines.
+
+Key rules:
+
+- Keep the public API minimal.
+- Every feature must map directly to SQLAlchemy expressions.
+- Unsupported Pydantic features should not be approximated.