Application API (autodoc)

Generated members most application code needs. For narrative docs, see Public API. Plugin and IR symbols: Plugin and IR API (autodoc).

class sqlrules.ArrayContains(value)

Require array containment (array_contains).

Parameters:

value (Any)

class sqlrules.ArrayOverlap(value)

Require array overlap (array_overlap).

Parameters:

value (Any)

class sqlrules.Compiler(*, registry=None, plugins=None, on_conflict='raise', on_unsupported='raise', dialect=None, cache=True, model_cache=None, emit_type_checks=False)

Compile constrained Pydantic models into SQLAlchemy rule dictionaries.

dialect is an optional hint stored on CompilationContext for custom translators. It does not load dialect plugins or change built-in translations — pass plugins=[...] explicitly.

emit_type_checks (default False) extracts type_check IR from supported scalar annotations. Translation requires a dialect plugin or custom translator (same pattern as pattern).

Do not mutate registry after construction; registration belongs in plugins / register_constraint during init. Do not call compile / bind / compile_model concurrently on the same instance.

Parameters:

• registry (TranslatorRegistry | None)

• plugins (Sequence[SQLRulesPlugin] | None)

• on_conflict (OnConflict)

• on_unsupported (OnUnsupported)

• dialect (str | None)

• cache (bool)

• model_cache (ModelIRCache | None)

• emit_type_checks (bool)

bind(model_ir, table, *, column_map=None)

Phase 2: resolve columns and translate IR into SQLAlchemy expressions.

Parameters:

• model_ir (ModelIR)

• table (Any)

• column_map (Mapping[str, ColumnElement[Any]] | None)

Return type:

dict[str, list[ColumnElement[bool]]]

compile(model, table, *, column_map=None)

Compile model constraints and bind them to table columns.

Parameters:

• model (type[BaseModel]) – Pydantic BaseModel subclass whose Field metadata is compiled (instance values are never applied).

• table (Any) – SQLAlchemy Table, selectable, ORM class, or object with .c.

• column_map (Mapping[str, ColumnElement[Any]] | None) – Optional field-name or alias → column mapping.

Returns:

Mapping of Python field names to lists of boolean ColumnElement expressions. Unconstrained supported-type fields are omitted.

Raises:

• InvalidModelError – model is not a usable Pydantic model.

• MissingColumnError – A constrained field could not bind.

• UnsupportedConstraintError – No translator for an operator/type, or emit_type_checks / pattern without a translator.

• TranslatorError – A registered translator failed at bind time.

• ConfigurationError – Invalid compiler configuration.

Return type:

dict[str, list[ColumnElement[bool]]]

compile_model(model)

Phase 1: inspect the model and extract constraint IR (no table binding).

Parameters:

model (type[BaseModel])

Return type:

ModelIR

property diagnostics: tuple[Diagnostic, ...]

Diagnostics from the most recent compile / bind call.

exception sqlrules.ConfigurationError(option: 'str', value: 'Any')

Parameters:

• option (str)

• value (Any)

Return type:

None

class sqlrules.ConstraintMarker(*args, **kwargs)

Protocol for Annotated metadata that becomes a SQLRules IR constraint.

class sqlrules.FullTextMatch(value)

Require a full-text match (fulltext_match).

Parameters:

value (Any)

exception sqlrules.InvalidModelError(model: 'Any')

Parameters:

model (Any)

Return type:

None

class sqlrules.JsonContains(value)

Require JSON/JSONB containment (json_contains).

Parameters:

value (Any)

class sqlrules.JsonHasKey(value)

Require a JSON object key (json_has_key).

Parameters:

value (Any)

exception sqlrules.MissingColumnError(field: 'str')

Parameters:

field (str)

Return type:

None

class sqlrules.RangeContains(value)

Require range containment (range_contains).

Parameters:

value (Any)

class sqlrules.RangeOverlap(value)

Require range overlap (range_overlap).

Parameters:

value (Any)

exception sqlrules.SQLRulesError

Base class for all public SQLRules exceptions.

exception sqlrules.SQLRulesWarning

Warning emitted when an unsupported constraint is skipped.

exception sqlrules.UnsupportedConstraintError(field: 'str', operator: 'str', value: 'Any' = None, suggestion: 'str | None' = None)

Parameters:

• field (str)

• operator (str)

• value (Any)

• suggestion (str | None)

Return type:

None

sqlrules.clear_model_cache()

Clear the process-wide default Phase-1 ModelIR cache.

Use this when creating many ephemeral models (for example pydantic.create_model) so cached IR does not grow without bound. Compilers that were given a custom model_cache are unaffected.

Return type:

None

sqlrules.compile(model, table, *, column_map=None, on_unsupported='raise', cache=True, emit_type_checks=False)

One-shot Application API compile (no plugins).

Compiles Field constraint metadata into SQLAlchemy expressions. Does not apply model instance / request values.

Creates a fresh Compiler per call so concurrent module-level compile() invocations do not share mutable diagnostics state. Phase-1 IR still uses the process-wide cache when cache=True.

Parameters:

• model (type[BaseModel]) – Pydantic BaseModel subclass.

• table (Any) – SQLAlchemy Table, selectable, ORM class, or object with .c.

• column_map (Mapping[str, ColumnElement[Any]] | None) – Optional field-name or alias → column mapping.

• on_unsupported (Literal['raise', 'warn', 'ignore']) – Policy for unknown operators ("raise", "warn", or "ignore"). Unsupported types always raise.

• cache (bool) – Cache Phase-1 model IR (default True).

• emit_type_checks (bool) – Emit type_check IR for supported scalars (requires a plugin translator — use Compiler(plugins=...)).

Returns:

Mapping of Python field names to lists of boolean ColumnElement expressions.

Raises:

• InvalidModelError – model is not a usable Pydantic model.

• MissingColumnError – A constrained field could not bind.

• UnsupportedConstraintError – No translator for an operator/type.

• TranslatorError – A registered translator failed at bind time.

• ConfigurationError – Invalid on_unsupported value.

Return type:

dict[str, list[ColumnElement[bool]]]

Note

For plugins, construct Compiler(plugins=[...]) explicitly.

sqlrules.flatten(rules)

Flatten a rules dict into a single list of expressions.

Parameters:

rules (dict[str, list[ColumnElement[bool]]]) – Mapping of field name to lists of boolean column elements, as returned by compile / Compiler.compile.

Returns:

Concatenated list suitable for spreading into a SQLAlchemy where clause.

Return type:

list[ColumnElement[bool]]

sqlrules.where(rules)

Flatten a rules dict for a SQLAlchemy where clause.

Identical to flatten(). Prefer this name at call sites.

Parameters:

rules (dict[str, list[ColumnElement[bool]]]) – Mapping of field name to lists of boolean column elements.

Returns:

Concatenated list of expressions.

Return type:

list[ColumnElement[bool]]