diff --git a/.claude/plan-2026-09-14/formatter-signature-normalization.md b/.claude/plan-2026-09-14/formatter-signature-normalization.md deleted file mode 100644 index d2734a6c4..000000000 --- a/.claude/plan-2026-09-14/formatter-signature-normalization.md +++ /dev/null @@ -1,246 +0,0 @@ -# 格式化函数签名规范化改造计划 - -> 目标：所有 `format_*` 格式化函数统一为 `(self, expr: SomeExpression) -> Tuple[str, tuple]`，消除 isinstance 判断，补齐类型提示。 - -## 一、返回类型不是 Tuple[str, tuple] 的方法 - -### 1.1 返回 `str` 的方法 - -| 方法 | 文件 | 当前签名 | 改造方案 | -|------|------|---------|---------| -| `format_pk_constraint` | `mixins/ddl_column.py:231` | `(self, t_const: "TableConstraint") -> str` | 改返回类型为 `Tuple[str, tuple]`，返回 `(sql, ())` | -| `format_unique_constraint` | `mixins/ddl_column.py:248` | `(self, t_const: "TableConstraint") -> str` | 同上 | -| `format_xml_name` | `mixins/xml.py:164` | `(self, name: str) -> str` | 这是内部辅助函数，非表达式格式化，可保留。但需确认是否可改为接收 expr | - -### 1.2 返回类型大小写不一致 - -所有使用 `-> Tuple[str, Tuple]` 的方法统一改为 `-> Tuple[str, tuple]`（小写 tuple）。 - -涉及文件：`mixins/expression.py`、`mixins/function.py`、`mixins/predicate.py` 中约 52 个方法。 - -## 二、参数不是 expr 的方法 - -### 2.1 `format_storage_options` - -- **当前签名**: `(self, storage_options: Dict[str, Any]) -> Tuple[str, Tuple]` -- **改造方案**: - 1. 在 `expression/statements/ddl_table.py` 中，`CreateTableExpression` 已有 `storage_options: Dict[str, Any]` 字段 - 2. 新建 `StorageOptionsExpression` 表达式类（或直接让 `format_storage_options` 接收 `expr: "CreateTableExpression"`，从 `expr.storage_options` 取值） - 3. **推荐方案**: 创建 `StorageOptionsExpression` 表达式类，持有 `options: Dict[str, Any]`，调用方改为 `self.format_storage_options(StorageOptionsExpression(dialect, expr.storage_options))` - 4. 去掉 isinstance 判断，值直接用 `inline_sql_literal` 渲染 - -### 2.2 `format_alias` - -- **当前签名**: `(self, expression_sql: str, alias: str, expression_params: tuple) -> Tuple[str, Tuple]` -- **改造方案**: 这是内部辅助方法，接收已格式化的 SQL 片段，非表达式格式化。可保留但改为 `-> Tuple[str, tuple]` - -### 2.3 `format_limit_offset` - -- **当前签名**: `(self, limit=None, offset=None) -> Tuple[str, List]` -- **改造方案**: 此方法是低级辅助，`format_limit_offset_clause` 才是接收 clause 的版本。保留此方法但返回类型改为 `Tuple[str, tuple]` - -### 2.4 `format_data_type` - -- **当前签名**: `(self, data_type: DataType) -> SQLQueryAndParams` -- **改造方案**: `SQLQueryAndParams` 等价于 `Tuple[str, tuple]`，可保留。参数名 `data_type` 是合理的（不是表达式格式化，是类型格式化） - -## 三、参数缺少类型提示的方法 - -### 3.1 `expression.py` — 缺少类型提示的方法 - -| 方法 | 当前 | 补齐为 | -|------|------|--------| -| `format_identifier_expression` | `(self, expr)` | `(self, expr: "IdentifierExpression")` | -| `format_wildcard` | `(self, expr)` | `(self, expr: "WildcardExpression")` | -| `format_qualified_identifier` | `(self, expr)` | `(self, expr: "QualifiedIdentifierExpression")` | -| `format_cast_expression` | `(self, expr)` | `(self, expr: "CastExpression")` | -| `format_sql_operation` | `(self, expr)` | `(self, expr: "SQLOperation")` | -| `format_binary_operator` | `(self, expr)` | `(self, expr: "BinaryExpression")` | -| `format_unary_operator` | `(self, expr)` | `(self, expr: "UnaryExpression")` | -| `format_binary_arithmetic_expression` | `(self, expr)` | `(self, expr: "BinaryArithmeticExpression")` | -| `format_raw_sql` | `(self, expr)` | `(self, expr: "RawSQLExpression")` | -| `format_subquery` | `(self, expr)` | `(self, expr: "Subquery")` | - -### 3.2 `predicate.py` — 全部 10 个方法缺少类型提示 - -| 方法 | 补齐为 | -|------|--------| -| `format_comparison_predicate` | `(self, expr: "ComparisonPredicate")` | -| `format_logical_predicate` | `(self, expr: "LogicalPredicate")` | -| `format_in_predicate` | `(self, expr: "InPredicate")` | -| `format_between_predicate` | `(self, expr: "BetweenPredicate")` | -| `format_is_null_predicate` | `(self, expr: "IsNullPredicate")` | -| `format_is_boolean_predicate` | `(self, expr: "IsBooleanPredicate")` | -| `format_exists_expression` | `(self, expr: "ExistsExpression")` | -| `format_any_expression` | `(self, expr: "AnyExpression")` | -| `format_all_expression` | `(self, expr: "AllExpression")` | -| `format_like_predicate` | `(self, expr: "LikePredicate")` | - -### 3.3 `dql.py` — 4 个方法缺少类型提示 - -| 方法 | 补齐为 | -|------|--------| -| `format_limit_offset_clause` | `(self, clause: "LimitOffsetClause")` | -| `format_where_clause` | `(self, clause: "WhereClause")` | -| `format_order_by_clause` | `(self, clause: "OrderByClause")` | -| `format_group_by_having_clause` | `(self, clause: "GroupByHavingClause")` | - -### 3.4 `ddl_table.py` - -| 方法 | 补齐为 | -|------|--------| -| `format_table` | `(self, expr: "TableExpression")` | - -### 3.5 `join.py` - -| 方法 | 补齐为 | -|------|--------| -| `format_lateral_expression` | `(self, expr: "LateralExpression")` | - -## 四、消除 isinstance 判断 - -### 4.1 `format_binary_arithmetic_expression` — `_needs_parens` - -- **isinstance**: `isinstance(operand, BinaryArithmeticExpression)` -- **改造**: 让 `BinaryArithmeticExpression` 实现 `precedence` 属性，通过 duck-typing 或 Protocol 检查 `hasattr(operand, 'OPERATOR_PRECEDENCE')` - -### 4.2 `format_comparison_predicate` - -- **isinstance**: `isinstance(expr.right, QueryExpression)` -- **改造**: 让所有表达式实现统一的 `needs_parenthesization()` 方法，或在 `ComparisonPredicate` 的 `right` 字段上通过 `to_sql()` 返回的 SQL 自动判断（子查询的 `to_sql()` 已自带括号） - -### 4.3 `format_in_predicate` - -- **isinstance**: `isinstance(expr.values, Literal) and isinstance(expr.values.value, (list, tuple, set))` -- **改造**: `InPredicate` 应在构造时区分 `values_list` 和 `subquery` 两种模式，格式化函数只调用 `expr.values.to_sql()` 或 `expr.values_list`，不做 isinstance - -### 4.4 `format_any_expression` / `format_all_expression` - -- **isinstance**: `isinstance(array_expr.value, (list, tuple))` -- **改造**: `AnyExpression`/`AllExpression` 应在构造时将集合值封装为表达式对象，格式化时统一调用 `to_sql()` - -### 4.5 `format_limit_offset_clause` - -- **isinstance**: `isinstance(clause.limit, ToSQLProtocol)` / `isinstance(clause.offset, ToSQLProtocol)` -- **改造**: `LimitOffsetClause` 的 `limit`/`offset` 字段应统一为表达式对象（构造时将原始值包装为 `Literal`） - -### 4.6 `format_order_by_clause` - -- **isinstance**: `isinstance(item, tuple)` -- **改造**: `OrderByClause` 的 items 应统一为 `OrderByItem` 表达式对象（包含 `expression` 和 `direction` 属性） - -### 4.7 `format_query_statement` — FROM 子句 - -- **isinstance**: `isinstance(expr.from_, str)` / `isinstance(expr.from_, list)` / `isinstance(source, str)` -- **改造**: `QueryExpression.from_` 应统一为表达式对象列表（构造时将字符串包装为 `TableExpression`） - -### 4.8 `format_insert_statement` — 数据源 - -- **isinstance**: `isinstance(expr.source, DefaultValuesSource/ValuesSource/SelectSource)` -- **改造**: 保留。这三种 Source 类型是 **不同的表达式类型**，各自的 `to_sql()` 逻辑完全不同。isinstance 分发是合理的（多态分发），不是在判断"同一字段的多种原始类型" - -### 4.9 `format_update_statement` / `format_delete_statement` — FROM/USING - -- **isinstance**: `isinstance(source, str)` / `isinstance(source, QueryExpression)` / `isinstance(source, BaseExpression)` -- **改造**: FROM/USING 的 source 列表应统一为表达式对象（构造时将字符串包装为 `TableExpression`） - -### 4.10 `format_function_call` — COUNT(*) - -- **isinstance**: `isinstance(expr, aggregates.AggregateFunctionCall)` + `isinstance(expr.args[0], operators.RawSQLExpression)` + `isinstance(expr.args[0], core.WildcardExpression)` -- **改造**: 保留对 `AggregateFunctionCall` 的判断（这是多态分发）。但 COUNT(*) 的特殊化应由 `WildcardExpression` 的 `to_sql()` 自然产生 `*`，不需要在 format_function_call 中特殊判断。确认 `WildcardExpression.to_sql()` 返回 `("*", ())` 即可 - -### 4.11 `format_function_call` — FILTER 子句协议探测 - -- **isinstance**: `isinstance(self, FilterClauseSupport) and isinstance(self, FilterClauseMixin)` -- **改造**: 保留。这是 dialect 的能力探测，判断当前 dialect 是否支持 FILTER 子句 - -### 4.12 `format_cte_expression` - -- **isinstance**: `isinstance(query, BaseExpression)` / `isinstance(query, tuple)` / `isinstance(params_input, list)` -- **改造**: CTE 的 query 应统一为表达式对象（构造时将 tuple/string 包装为表达式） - -### 4.13 `format_window_function_call` - -- **isinstance**: `isinstance(arg, bases.BaseExpression)` / `isinstance(call.window_spec, str)` -- **改造**: - - 参数应统一为表达式对象（构造时将字面值包装为 `Literal`） - - `window_spec` 应统一为表达式对象（字符串包装为 `WindowSpecification` 或 `NamedWindowReference`） - -### 4.14 `format_window_specification` - -- **isinstance**: `isinstance(part, bases.BaseExpression)` -- **改造**: PARTITION BY 项应统一为表达式对象 - -### 4.15 `format_join_clause` - -- **isinstance**: `isinstance(join_expr.left_table, (QueryExpression, JoinClause))` / 同 right_table -- **改造**: 保留。JOIN 的左右表可以是表名（`TableExpression`）、子查询或嵌套 JOIN，这是合法的多态 - -### 4.16 `format_on_conflict_clause` - -- **isinstance**: `isinstance(target, str)` / `isinstance(target, ToSQLProtocol)` -- **改造**: ON CONFLICT 目标应统一为表达式对象（构造时将字符串包装为 `ColumnExpression`） - -### 4.17 `format_ilike_expression` - -- **isinstance**: `isinstance(column, str)` / `isinstance(column, ToSQLProtocol)` -- **改造**: 列应统一为表达式对象 - -### 4.18 `format_json_*` - -- **isinstance**: `isinstance(expr.column, bases.BaseExpression)` -- **改造**: JSON 表达式的 `column` 字段应统一为表达式对象 - -### 4.19 `format_default_constraint` - -- **isinstance**: `isinstance(constraint.default_value, BaseExpression/Literal/str)` -- **改造**: DEFAULT 值在 DDL 上下文中必须内联。保留 isinstance 但简化：统一用 `inline_sql_literal` 渲染，让 `Literal` 的 `inline_literals=True` 模式自然产生内联值 - -### 4.20 `format_foreign_key_constraint` - -- **isinstance**: `isinstance(t_const, ForeignKeyConstraint)` -- **改造**: 保留。`ForeignKeyConstraint` 是 `TableConstraint` 的子类，需要额外属性 - -### 4.21 `format_alter_column_action` - -- **isinstance**: `isinstance(action.new_value, str/ToSQLProtocol/Literal)` -- **改造**: `new_value` 应统一为表达式对象 - -### 4.22 `format_for_update_clause` - -- **isinstance**: `isinstance(col, str)` / `isinstance(col, ToSQLProtocol)` -- **改造**: FOR UPDATE OF 列应统一为表达式对象 - -### 4.23 `format_create_index_statement` - -- **isinstance**: `isinstance(col, ToSQLProtocol)` -- **改造**: 索引列应统一为表达式对象 - -### 4.24 `format_add_table_constraint_action` - -- **isinstance**: `isinstance(action.constraint, ForeignKeyConstraint)` -- **改造**: 保留（同 4.20） - -## 五、优先级排序 - -### P0 — 返回类型修复（阻塞性） -1. `format_pk_constraint` → `Tuple[str, tuple]` -2. `format_unique_constraint` → `Tuple[str, tuple]` - -### P1 — 参数签名统一 -3. `format_storage_options` → 接收 expr -4. `format_alias` → 返回类型统一 -5. `format_limit_offset` → 返回类型统一 - -### P2 — 类型提示补齐 -6. `expression.py` 10 个方法 -7. `predicate.py` 10 个方法 -8. `dql.py` 4 个方法 -9. `ddl_table.py` 1 个方法 -10. `join.py` 1 个方法 - -### P3 — isinstance 消除 -11. 各方法按上述方案逐一改造 - -### P4 — 返回类型大小写统一 -12. `Tuple[str, Tuple]` → `Tuple[str, tuple]` 全局替换 diff --git a/.claude/rules/README.md b/.claude/rules/README.md new file mode 100644 index 000000000..4364105d6 --- /dev/null +++ b/.claude/rules/README.md @@ -0,0 +1,27 @@ +# Rules + +How this codebase is built, and what has been tried and rejected. Each file +stands alone; read the one that concerns the change in front of you. + +| Rule | Covers | +|---|---| +| [expression-direction.md](expression-direction.md) | `expr -> format` and why the reverse direction is where injection and unreviewable inference live. What a factory signature may accept. | +| [column-and-result-types.md](column-and-result-types.md) | Designing column classes; the core / backend / user layering; stating a result type the source cannot settle, and why it is a mixin rather than a keyword. | +| [operation-contracts.md](operation-contracts.md) | What each operation promises once the ten-backend survey measured it: the string boundary refusals, the rendering-name contracts, the temporal result types, the value-layer echo, and where version gates refuse. | +| [static-analysis.md](static-analysis.md) | Making a checker actually check: `py.typed`, a configuration that loads, and the defects that opt out of checking silently. | +| [anti-patterns.md](anti-patterns.md) | The catalogue, with what each one cost. Read this before adding a runtime lookup, a coercion helper, or a `__getattr__`. | + +Two rules decide most of the rest: + +1. **Information flows one way**, from a typed object to SQL text. A formatter + needs an expression to have anything to format, so nothing may manufacture + the expression it is about to render. +2. **A backend is entirely static.** An IDE and a type checker give a definite + answer. Nothing is worked out at run time, and nothing is left for the + caller to assert in a form a checker cannot read. + +A third applies to the checks themselves, and it is the one most often skipped: +**a check that was not run cannot have passed.** The defects CI found in one +afternoon — four version gates that could not say no, an argument inserted into +the wrong call — were all in files that had been edited and not tested. Run the +directory. diff --git a/.claude/rules/anti-patterns.md b/.claude/rules/anti-patterns.md new file mode 100644 index 000000000..ce8233944 --- /dev/null +++ b/.claude/rules/anti-patterns.md @@ -0,0 +1,152 @@ +# Catalogue: confirmed anti-patterns + +Each of these was in the codebase. Each is listed with what it cost, so the +next one is recognised rather than reinvented. + +## Runtime inference where a type would do + +| Anti-pattern | Why it is wrong | +|---|---| +| `result_type="string"` on a factory | A claim, not a type. The return stays `FunctionCall`, so nothing downstream is checked. | +| A family string on the object (`VALUE_FAMILY`) | The only thing it bought was chaining on a function result, and `wrap_as` had to *infer* the family from the input to do it -- the same inference as above, under another name. | +| `family_for_sql_type_name("bigint")` | A table mapping type-name prefixes to meaning, duplicating what the class already knows and inferable only by parsing text. | +| `column_class_for(annotation)` used from a backend | A model-layer runtime table consulted by the dialect layer; the layering alone is wrong. | +| A `str` parameter on a factory | Leaves the decision to a downstream `isinstance`. | + +## Coercion in the wrong direction + +| Anti-pattern | Why it is wrong | +|---|---| +| `_convert_to_expression(dialect, value)` | Manufactures the expression the formatter is about to format. 59 copies existed. | +| `expr if isinstance(expr, X) else Literal(dialect, y)` inlined at every call site | Where the helper was literal-only this is behaviour-preserving, but at scale it duplicates the same chain dozens of times. Use it where it is genuinely small; do not spread it. | +| Parsing a type name to validate it (`type_name.py`) | Needed only because a string could reach the type position. 201 lines and a grammar, all downstream of that decision. | + +## Things that disable checking rather than satisfy it + +| Anti-pattern | Why it is wrong | +|---|---| +| `__getattr__` forwarding on an expression class | A checker stops there; every attribute looks valid. Nine of them. | +| `py.typed` absent | The installed package is skipped, so the annotations are invisible. | +| A checker config that does not load | The run continues far enough to look like it passed. | + +## A gate with no lower bound is not a gate + +`supports_data_type_x()` returning `True` unconditionally tells the dialect it +can render a type on any server. The server disagrees, later, by executing the +statement: + +```python +def supports_data_type_postgres_jsonpath(self) -> bool: + return True # every server, including 9.4 +``` + +`CREATE TABLE t (p jsonpath)` comes back `type "jsonpath" does not exist`. The +failure arrives at execution naming a table, when the cause was a version gap +decided at import time. + +Four of these shipped at once and CI found them one per run, on one version +each — which is the worst order to find them in, because each run looks like a +new problem: + +| Type | Floor | Found on | +|---|---|---| +| `macaddr8` | 10 | python 3.8 / postgres 9 | +| `jsonpath` | 12 | python 3.10 / postgres 12 and below | +| `xid8` | 13 | python 3.11 / postgres 13 | +| the six multiranges | 14 | python 3.8 / postgres 9 through 13 | + +Three things made this take a run each rather than one pass: + +**The floors were taken from the release notes, and the notes are wrong.** +jsonpath is documented as PostgreSQL 13. It is in 12. Asking the servers is a +loop over a scenario matrix that already exists; reading the notes is a guess +that has to be repeated per type. + +**The failures only appear on the oldest combinations.** Everything from Python +3.12 on was green throughout, because the matrix pairs newer Pythons with newer +servers. A change can be entirely correct on the versions CI happens to run. + +**A refusal that is correct still looks like a failure.** The dialect knew +multiranges were 14+ and said so — `requires PostgreSQL 14+` — and the tests +reported that refusal as a fault, so five combinations stayed red while the code +underneath was right. + +The general form: a version gate answers `True` for every version when the +answer should be "everything from *n*". `is_extension_installed` is the same +question about an extension, and answered wrongly it produces the same shape of +failure. + +What to do about the ones that are `True` on purpose — and there are many, +because `text`, `integer` and `varchar` predate the oldest server anyone tests — +is nothing. The distinction is not the count of unconditional gates, it is +whether the type arrived after the floor. So the check is one-directional: for +the types that have a floor, assert the floor. Not that all gates have one. + +## A regex is not an editor + +Adding one keyword to six call sites went wrong twice on the same file, in two +different ways, and both were caught by CI rather than by reading the diff: + +``` +Case("macaddr8", lambda d: PostgresMacAddr8Type(d, type_name="..."), ...) +``` + +placed the argument inside the factory instead of on `Case`'s own argument list. +And an earlier pass put the same keyword inside five others the same way, then a +`git checkout` during a later edit removed the code that read the field while +leaving the field and its six assignments behind — so the feature looked present +and did nothing. + +The general problem is that a regex matches text, and a call is not text. It +does not know that `lambda d: T(d)` is one argument, that a multi-line call has +its closing paren three lines down, or that a neighbouring call already got the +same edit. So: + +- Locate with `ast`, not with a pattern. `ast.parse` and then read + `node.lineno`, `node.end_lineno`, `node.args` — a function's parameter list is + a node, not a comma-split string. +- After any bulk edit, `ast.parse` the file. A syntax error is loud; a misplaced + keyword argument is not, it is a `TypeError` three layers away at runtime. +- Then run the directory. See "Run the directory, not the files you edited" in + `static-analysis.md` — the mistake survived because only the edited files were + tested, and neither contained the error. + +Bulk edits that are worth doing are the ones where a mistake is impossible to +confuse with success. A misplaced keyword argument is not. + +## Inlining that only moves the problem + +Converting a domain object to a typed literal is real work and belongs +somewhere explicit: + +```python +Literal(dialect, value.to_postgres_string()).cast(PostgresHstoreType(dialect)) +``` + +Written at every call site, it grew one file by 872 lines with byte-identical +SQL. That removed the helper's name and left its body copied everywhere, where +the copies drift. When a module needs this many, the conversion wants to be a +named construction, not a repeated branch chain. + +## Verification discipline + +- Rendering is not validation. `(end - start) * 1` renders happily on a + dialect that cannot execute it. Test against a real database. +- Semantic expectations come from the server, not from intuition. Several + first expectations in the range and address suites were wrong and the database + corrected them: `[1,5)` and `[5,9)` are adjacent but do not overlap, `~cidr` + is not a host mask, `range_union` refuses a gap. +- A byte-identical SQL diff before and after is the evidence that a refactor + changed nothing. Capture it first, then compare. +- Run the whole check the change needs, not the one that happens to be fast. + Full test suites are not run locally; targeted files, `--collect-only`, and + lint are. +- A refusal is not a failure. `UnsupportedFeatureError: requires PostgreSQL + 14+` is the code working: the dialect declined to render a type the server + does not have. A test that reports that refusal as a fault is asking the + wrong question — it should ask the dialect what the server supports and skip. + Five Python/PostgreSQL combinations stayed red for this reason while the code + underneath was correct. +- Version-dependent behaviour is a fact about servers, and the servers are + reachable. Ask them in a loop over the scenario matrix rather than reading + release notes: the notes put jsonpath in 13, and 12 has it. diff --git a/.claude/rules/column-and-result-types.md b/.claude/rules/column-and-result-types.md new file mode 100644 index 000000000..b4fe2c2fd --- /dev/null +++ b/.claude/rules/column-and-result-types.md @@ -0,0 +1,97 @@ +# Column classes and result types + +## Column classes are designed, not inferred + +A column class says what a value of that kind **can do**. Define what exists; +do not add what might. Operations are methods on the class, so what a column +offers is a property of its type, visible to a reader and to a checker. + +Users reach a column through their model's annotation, never through a registry +or a lookup by name: + +```python +class Post(Model): + title: str # -> StringColumn + views: int # -> NumericColumn + body: dict # -> JSONColumn + +Model.c.title.upper() +``` + +What decides this is a plain mapping from annotation to column class. It is a +closed table in the model layer, and it is read at class-definition time, so +the choice is static. + +## Layering + +Three layers, each adding to the one above: + +1. **Core** -- what the SQL standard defines and what is widely shared. + `StringColumn`, `NumericColumn`, `TimestampColumn`, `BooleanColumn`, + `BinaryColumn`, `JSONColumn`, `ArrayColumn`, `UUIDColumn`. +2. **A backend overrides** what genuinely differs for it. An override replaces a + method or a rendering; it does not accumulate into a growing subclass. +3. **A backend adds its own** for what only it has. PostgreSQL has no peers for + `citext`, `ltree`, `hstore`, `int4range`, `inet` or `geometry`, so those are + defined there and nowhere else. + +Between them the coverage is meant to be complete: every operation the backend +supports has somewhere to call it from. + +## A user's own column type + +PostgreSQL lets a user define a column type. They own it the same way, and the +mechanism is open rather than closed: + +```python +class MyTypeMixin: + def as_mytype(self) -> MyTypeValueExpression: + ... + +class MyColumn(MyTypeMixin, ColumnBase): + ... +``` + +Nobody has to register it, and the core does not need to know it exists. + +## Result types the source cannot settle + +Most operations know what they yield and say so by returning that class. A few +cannot: `NULLIF(x, y)` yields `x` when they differ and NULL when they do not, so +whether the result is text or an integer depends on the data. The standard +gives this example itself. + +For those, the caller states it. **Never infer, and never accept a free-form +claim.** The statement has to be something a checker can read, which means it +has to be a function or method with a declared return type: + +```python +NULLIF(name, blank).as_text().upper() # fine +NULLIF(name, blank).as_text().sqrt() # error: text has no sqrt +``` + +`ResultTypeMixin` provides this on the node whose result type is genuinely not +in the source -- a bare `FunctionCall`. It is a **mixin, not free functions**, +for three reasons: + +- the dialect is already on the node, so there is nothing to pass; +- chaining reads as one expression rather than an argument in the middle; +- `dir()` finds it, so the way to say it is discoverable. + +Because it is a mixin, a user composes it the same way: do not mix it in and +the operations are simply absent; find it short and subclass it, overriding one +method and keeping the rest. + +## Anti-pattern, for contrast + +```python +f(dialect, expr, result_type="string") # a claim, not a type +``` + +The declared return stays `FunctionCall`. A checker learns nothing, the wrong +continuation is still unchecked, and the error surfaces as a server complaint +minutes later. It reads as if it solves the problem and does not. + +The same objection applies to a runtime lookup keyed on a type name, and to a +family string carried on the object: both move a decision that could be a type +into run-time data. If the answer is knowable, make it a return type. diff --git a/.claude/rules/expression-direction.md b/.claude/rules/expression-direction.md new file mode 100644 index 000000000..0d4e35a35 --- /dev/null +++ b/.claude/rules/expression-direction.md @@ -0,0 +1,67 @@ +# Expression direction: expr -> format, never the reverse + +## The rule + +Information flows one way: from a typed object to SQL text. + +``` +caller builds an expression -> factory composes expressions -> dialect renders + Column / Literal / ... FunctionCall format_* +``` + +A formatter's subject is an expression. Without one it has nothing to render, +so **no formatting function may manufacture the expression it is about to +format**. That includes guessing, coercing, and parsing. + +## Why the reverse direction is not a style preference + +The type position of a cast cannot take a bound parameter, so whatever lands +there is SQL code. That is why `cast()` takes a `DataType` and refuses a +string, and why `CustomType` validates its name: the reverse direction is where +injection lives. + +The same shape appears wherever a loose value is turned into a node. A helper +that accepts `str` and decides whether it is a column name or a string value is +inferring SQL semantics at run time, and the decision is invisible at the call +site -- the reader sees `f(dialect, x)` and cannot tell what will be rendered. +It is also unreviewable, because the branch that decides is in the wrong place. + +## Formatters + +- Each expression declares which formatter it needs; `to_sql()` looks it up. + A node never formats itself. +- A formatter takes an expression. It does not accept a string and validate it + afterwards -- `format_cast_expression` used to check the target with a regex + and reject a bad name at render time, which meant the check sat three steps + from where the value entered. +- A type renders itself through `to_sql()`, so the type and its spelling + cannot disagree. + +## What this forbids + +- A coercion helper that turns a loose value into an expression. +- A factory parameter typed `Any` or `Union[str, BaseExpression]`, because that + signature invites a loose value and leaves something downstream to guess. +- Parsing rendered SQL back into a domain object. If a type name has to be + understood, that is a parser for a grammar nobody needed. + +## Where the difficulty actually is + +Deleting a coercion helper is only mechanical when it coerces in one direction +for every input. Measured across the function factories, most do, but some map a +string to a `Column` -- a different convention, not a variant -- and a few turn +a domain object into a typed literal, which is real work: + +```python +# Antisymmetric: this one is worthless, the behaviour is unchanged by removing it. +x = x if isinstance(x, BaseExpression) else Literal(dialect, x) + +# Real: the object becomes a value of a known type, and the cast is the point. +Literal(dialect, value.to_postgres_string()).cast(PostgresHstoreType(dialect)) +``` + +Inlining the second at every call site writes the same six-branch chain dozens +of times; one such attempt grew a file by 872 lines while keeping the SQL +byte-identical. It removed the helper's name and left its body copied everywhere. +That is not a resolution. Turn the conversion into an explicit construction +instead, or leave the module for its own pass. diff --git a/.claude/rules/operation-contracts.md b/.claude/rules/operation-contracts.md new file mode 100644 index 000000000..9828e76c0 --- /dev/null +++ b/.claude/rules/operation-contracts.md @@ -0,0 +1,121 @@ +# Operation contracts + +The capability declaration baseline for the ten-backend operation survey +(`.claude/plan/2026-10-09/operation-groups-matrix.md`, sections A-F; measured +2026-10-09, per-backend records and probe outputs in the same directory and +its `backends/`). This file is the document the core factory docstrings and +the backend rendering overrides implement; when a new measurement disagrees +with it, this file changes first and the code follows. + +## 1. String boundary contracts + +Every one of these was measured on ten backends before it was written down. +Where the backends agree, the edge renders; where they do not, it is refused at +construction rather than rendered into whatever the dialect happens to do. + +| Operation | Contract | What was measured, and why the other edges are not offered | +|---|---|---| +| `left` / `right` | `n >= 0` | 0 is `''` and `n > len` is the whole string on every backend. Below 0: PostgreSQL and ClickHouse drop the trailing/leading `\|n\|` characters, MySQL, MariaDB and Snowflake return `''`, SQL Server and Firebird raise, BigQuery raises, Oracle (via SUBSTR) yields NULL. | +| `repeat` | `n >= 0`; `n < 0` is `''` | The native answer on PostgreSQL, MySQL, MariaDB and ClickHouse alike. SQL Server's REPLICATE answers NULL; Oracle, Firebird and SQLite have no such function. Settled once, in the core, instead of once per backend. | +| `lpad` / `rpad` | `n >= 0`, pad non-empty, omitted pad means one space and is spelled out | The pad is passed explicitly because MySQL raises 1582 without it while MariaDB fills with spaces. Empty pad: untouched string on PostgreSQL/Firebird/Snowflake, `''` on MySQL 8.0, untouched on MySQL 26 (same server, two answers), NULL on MariaDB/Oracle, spaces on ClickHouse. | +| `substring` | `start >= 1`, `length >= 0` | Out-of-range positions: consumed by the length on PostgreSQL/SQL Server/Firebird/SQLite, empty string on MySQL/MariaDB/ClickHouse, read as 1 on Oracle. Negative length: an error on PostgreSQL/SQL Server/Firebird/BigQuery, `''` on MySQL/MariaDB, NULL on Oracle, something unrelated on ClickHouse. | +| `trim` | trim set is exactly **one** character | SQL:2016 feature E021-09. A longer set is a character set on PostgreSQL/SQL Server/ClickHouse/Snowflake, a whole string repeated on MySQL/MariaDB/Firebird (proved with `TRIM(BOTH 'xy' FROM 'xyxab')` = `'xab'`), and ORA-30001 on Oracle. | + +## 2. Rendering-name contracts + +The core name is the meaning; the rendered spelling is the backend's. A dialect +override renames or reorders, never reinterprets. + +| Core call | Core meaning | Per-backend spelling (measured 2026-10-09) | +|---|---|---| +| `log(x)` | natural logarithm | native on MySQL, MariaDB, ClickHouse, SQL Server, BigQuery, Firebird, SQLite; `LN(x)` needed on PostgreSQL (where `log(x)` is base 10) and Oracle and Snowflake | +| `log(x, base)` | base second | native order on SQL Server, ClickHouse, BigQuery; `(base, x)` order on PostgreSQL, MySQL, MariaDB, Oracle, Firebird, Snowflake | +| `truncate(x[, n])` | truncation toward zero, distinct from `round` on negatives | `TRUNC` on PostgreSQL, Oracle, Firebird, BigQuery, SQLite, ClickHouse; `TRUNCATE` on MySQL, MariaDB, Snowflake; SQL Server has no scalar truncate and spells it `ROUND(x, n, 1)`. MariaDB's own `TRUNC` returns NULL for numerics (12.2+, absent before), so its gate keys on the rendered name | +| `position(substring, expr)` / `strpos(expr, substring)` | two spellings, one operation, needle-first for `position` and haystack-first for `strpos`, each matching the standard/native form | PostgreSQL takes only `POSITION(sub IN s)` (its comma form is a syntax error); SQL Server `CHARINDEX`; ClickHouse and BigQuery put the haystack first; MySQL/MariaDB `LOCATE`/`INSTR`; Oracle and Firebird `INSTR` | + +## 3. Temporal contracts + +- **temporal − temporal** is a duration whose **type is the backend's**, not a + single interpolated one: integer days (PostgreSQL), decimal days (Firebird), + seconds (ClickHouse), interval (Snowflake, BigQuery), timedelta-shaped + (Oracle), silent numeric difference on MySQL and MariaDB. Only + `timestamp − timestamp` is an interval nearly everywhere. `TemporalArithmeticMixin` + no longer claims one result type. +- **date_diff** takes a unit enum (`YEAR MONTH WEEK DAY HOUR MINUTE SECOND`) + and the counting rule is per unit: calendar units count boundaries crossed, + exact-span units measure the span. Backends mix the two natively + (PostgreSQL: YEAR/MONTH are year-month differences but DAY is an epoch + difference), so the mix is declared per unit rather than promised away. + +## 4. Value-layer echo (ResultTypeMixin) + +| Conversion | Honest statement | +|---|---| +| `sign` | The value is -1/0/1, but the result is **numeric**, not integer: PostgreSQL answers an integer argument with `double precision` and a numeric argument with `numeric` | +| `round` | Halves are a function of (backend, version, column type): decimal half-away-from-zero on MySQL/MariaDB/PostgreSQL/Firebird/Oracle/SQL Server, half-to-even on ClickHouse; float half-to-even on MySQL 8.0/MariaDB/PostgreSQL/ClickHouse and half-away on Oracle/Firebird/SQL Server. SQL Server **raises 22003** on `ROUND(±0.5, 0)`; MySQL 5.6/5.7 reject `CAST(x AS DOUBLE)` | +| `cast` to integer | Truncation toward zero on SQLite, PostgreSQL, SQL Server, Firebird, ClickHouse; half-away from zero on Oracle, BigQuery | +| UUID / BLOB / JSON reads | Equality is portable for all three; ordering is not (UUID and BLOB are not orderable on most backends); JSON equality is not (PostgreSQL `json` has none, use `jsonb`) | + +## 5. Boolean and pattern declaration + +- **Boolean literals** come in three tiers: TRUE/FALSE keyword backends + (PostgreSQL, SQLite, MySQL, MariaDB, ClickHouse, BigQuery, Snowflake), + 0/1 backends where the framework renders the 0/1 form (SQL Server `bit`), + and backends with no boolean type at all (Oracle below 23ai). The framework + renders the portable form rather than the native spelling. +- **LIKE sensitivity is the backend's**: case-insensitive on SQLite, MySQL, + MariaDB and SQL Server (following collation), case-sensitive on PostgreSQL, + ClickHouse, Oracle and BigQuery, collation-dependent on Firebird and + Snowflake. `ilike` is the only spelling that *means* case-insensitive; no + `COLLATE` clause on the predicate changes a CI default. +- **Length units** are three: characters (PostgreSQL, Oracle, Firebird), + bytes (MySQL, MariaDB, ClickHouse) and UTF-16 code units (SQL Server, which + maps both LENGTH and CHAR_LENGTH to LEN). + +## 6. Version gates + +A gate belongs to the dialect that has the limit and refuses below it -- +never a silent substitution of a different question: + +- **`IS [NOT] DISTINCT FROM`**: native on PostgreSQL, Firebird, Snowflake, + BigQuery, SQL Server (2022+), SQLite (3.39+). Below the gate, or where the + spelling is missing, the framework raises `UnsupportedFeatureError` naming + the version. Oracle answers `NOT LNNVL(a = b)` / `LNNVL(a = b)` (its + `IS NOT DISTINCT FROM` is ORA-00908), which is exact and therefore a + rendering override rather than a downgrade. +- SQLite's function table carries the rest of its gates (math functions + 3.35+ with the build flag, `unhex` 3.45+, `json_array_insert` 3.53+, + `concat` 3.44+, `jsonb` 3.45+); PostgreSQL's `regexp_like` gate corrects to + 15 (live-verified on 14 and 15). +- A recorded floor is **enforced**, not merely reported. `FunctionCallMixin.format_function_call` + calls `SQLDialectBase.check_function_version` before it renders, and the + floor for a name comes from the dialect's `function_version_floors` table + (SQLite's is the min column of `_SQLITE_FUNCTION_VERSIONS`, so + `supports_functions()` and the gate cannot disagree). Below the floor the + render raises `UnsupportedFeatureError` naming the function, the floor and + the version in force — the same refusal the `IS [NOT] DISTINCT FROM` gate + makes. The base reads the table through `getattr`, and the table is declared + on the backend's mixin as **data, not as a method override**: the dialect + base sits ahead of every mixin in the MRO, so a method overriding the base + here would be shadowed by it. Recorded *ceilings* are not floors — they say + the spelling does not exist on the backend at all — and stay with the query + surface. A dialect with no recorded floor for a name renders it unchanged, + and an un-adapted dialect (no version yet) keeps rendering: the gate needs a + version to compare against. + +## 7. Where each is enforced + +- Construction-time refusal: the core factory that builds the node + (`functions/string.py`, `functions/math.py`), so every caller meets the same + error before SQL exists. +- Rendering overrides: the dialect's `format_*` hook. **A factory that needs a + dialect's help builds a node, never a SQL string**: `raw SQL` is text by the + time anyone could vote on it, so no hook can reach it. The worked example is + `TrimExpression` -- the core factory builds the node, `TrimMixin` renders the + standard form, and SQLite overrides `format_trim_expression` because it parses + no `trim(... from ...)` syntax at all. `ILIKEExpression` and `ArrayExpression` + follow the same shape. A factory reaching for `RawSQLExpression` (or a + `WildcardExpression` standing in for `COUNT(*)`'s star) is a bug in review + terms, not a shortcut. +- Capability statements: this file, plus the docstring of the method that + makes the statement. diff --git a/.claude/rules/static-analysis.md b/.claude/rules/static-analysis.md new file mode 100644 index 000000000..a0e356b72 --- /dev/null +++ b/.claude/rules/static-analysis.md @@ -0,0 +1,96 @@ +# Static checking has to actually check + +A checker that silently skips your code is worse than no checker, because it +lets a claim stand. Every rule here exists because something got past one. + +## Ship the marker + +`py.typed` (PEP 561) tells a checker the package carries inline annotations. +Without it the installed package is treated as untyped and **skipped +entirely** -- so the annotations are present but invisible to every consumer. +It also has to be declared as package data or it never reaches the wheel: + +```toml +[tool.setuptools.package-data] +rhosocial = ["py.typed"] +``` + +## The configuration has to run + +`[mypy] python_version = "3.8"` was set while the project's interpreter is +3.14, and mypy no longer accepts 3.8 -- so every run printed a configuration +error and the run continued far enough to look successful. A checker whose +configuration does not load is not a checker. + +Verify the configuration actually loaded before believing any of its output: + +```bash +mypy --version && mypy --show-config 2>&1 | head +``` + +## A class with `__getattr__` opts out of checking entirely + +Nine value-expression classes forwarded unknown attributes to a wrapped node: + +```python +def __getattr__(self, name): + call = self.__dict__.get("call") + if call is None: + raise AttributeError(name) + return getattr(call, name) +``` + +A checker reads `__getattr__` and stops. On those classes every attribute +looked valid, so the property the type system was supposed to provide -- a +wrong continuation caught on the line you wrote it -- was not being delivered +at all. Every experiment run against those classes had been passing for that +reason. + +Do not add `__getattr__` to an expression class. If attribute forwarding is +genuinely needed, forward the specific attributes explicitly. + +## Know what the checker cannot see + +Syntax validity is not style, and neither is a partial rule set: + +- Indentation inside brackets is not a syntax error, so `ast.parse` passes on a + misindented base-class list. `ruff`'s `E1xx` rules are preview-only and do not + cover bracket alignment either. +- The project's `select = ["E", "F", "B"]` does not include `E1`/`W1`. Running + `ruff check ` proves less than it appears to. + +When reporting that a check passed, say which rules ran and what they cover. + +## Confirm the tool is looking at the right thing + +Two failures of this kind, both mine: + +- A scan that found nothing because its glob matched no files reports zero + findings forever. +- A test that counts violations against a recorded baseline can be silenced by + editing the baseline. Assert that the recorded number still corresponds to + something real. + +A check that has not been shown to fail on a known defect has not been shown +to work. Break the thing on purpose, watch the checker catch it, then put it +back. + +## Run the directory, not the files you edited + +The check that would have caught the last regression was not run, because the +edit was in a file and the error was in the argument that file passes to another: + +```python +Case("macaddr8", lambda d: PostgresMacAddr8Type(d, type_name="..."), ...) +``` + +Every case raised `TypeError` on a keyword the type constructor does not take, +and all eleven PostgreSQL versions went red — including 18, which is far past +every version floor involved. That asymmetry is the tell: a version problem +cannot affect a server eight versions above the boundary it is about. + +Two files were edited and two files were tested, so the failure lived in neither. +The tests that would have caught it were in the same directory. + +A signature error has no version to it. When CI is red across every version at +once, suspect an argument or an import before suspecting a gate. diff --git a/.claude/skills/dev-expression-lineage/SKILL.md b/.claude/skills/dev-expression-lineage/SKILL.md index 34bc7d4e3..9dc869241 100644 --- a/.claude/skills/dev-expression-lineage/SKILL.md +++ b/.claude/skills/dev-expression-lineage/SKILL.md @@ -169,9 +169,11 @@ attribute cannot be resolved from the import's source module. Resolution is atte against the **source module**, not the class inventory, because dialect classes such as `SQLDialectBase` are not exported by expression modules and that is normal, not a defect. Only a module that imports cleanly while the attribute is missing is genuinely dangling. -These are runtime-inert but break mypy, IDE resolution and any static tool. Firebird's -`mixins/window.py` imports `WindowFunctionCallExpression` while core defines -`WindowFunctionCall`. +These are runtime-inert but break mypy, IDE resolution and any static tool. The case +that motivated the check — Firebird's `mixins/window.py` importing +`WindowFunctionCallExpression` while core defined `WindowFunctionCall` — is gone: the +node was unified into `FunctionCall` and the stale importer deleted, so the check +currently reports nothing. It is kept because the same shape recurs with every rename. > Relative-import resolution must go through `importlib.util.resolve_name` with the > module's `__package__`. Hand-rolled level arithmetic is wrong: level 0 is already diff --git a/.claude/skills/dev-expression-lineage/scripts/expression_lineage.py b/.claude/skills/dev-expression-lineage/scripts/expression_lineage.py index fd0f0ed0f..0332357c9 100644 --- a/.claude/skills/dev-expression-lineage/scripts/expression_lineage.py +++ b/.claude/skills/dev-expression-lineage/scripts/expression_lineage.py @@ -32,9 +32,10 @@ report zero, and no exemption list exists. 6. **Weak references are not inheritance.** Module-level ``if TYPE_CHECKING:`` - imports exist only for annotations, are not lineage edges, and rot silently: - Firebird's ``mixins/window.py`` imports ``WindowFunctionCallExpression`` while - the core defines ``WindowFunctionCall``. They live in + imports exist only for annotations, are not lineage edges, and rot silently — + the historical case being Firebird's ``mixins/window.py`` importing + ``WindowFunctionCallExpression`` while the core defined + ``WindowFunctionCall``, both since unified into ``FunctionCall``. They live in :attr:`LineageGraph.typecheck_imports`, parallel to the DAG. Layering of concerns @@ -180,10 +181,10 @@ class TypecheckImport: """A module-level ``if TYPE_CHECKING:`` import, i.e. an annotation-only reference. These are not inheritance edges. They are tracked separately because they rot - silently: Firebird's ``mixins/window.py`` imports - ``WindowFunctionCallExpression`` while the core defines - ``WindowFunctionCall``. The source location is retained so a fixer can rewrite - the offending line without re-deriving it. + silently — Firebird's ``mixins/window.py`` used to import + ``WindowFunctionCallExpression`` while the core defined ``WindowFunctionCall``, + until both were unified into ``FunctionCall``. The source location is retained + so a fixer can rewrite the offending line without re-deriving it. Attributes: project: Project label the importing module belongs to. diff --git a/.claude/skills/dev-expression-lineage/scripts/fix_dangling_typecheck.py b/.claude/skills/dev-expression-lineage/scripts/fix_dangling_typecheck.py index 8b873f62b..240f933f0 100644 --- a/.claude/skills/dev-expression-lineage/scripts/fix_dangling_typecheck.py +++ b/.claude/skills/dev-expression-lineage/scripts/fix_dangling_typecheck.py @@ -62,8 +62,10 @@ #: - the import needs a deeper tail than the author wrote #: (``async_backend`` -> ``backend.async_backend``, and #: ``expression.partition`` -> ``expression.partition_lifecycle``); -#: - the name itself was renamed (``WindowFunctionCallExpression`` -> -#: ``WindowFunctionCall``). +#: - the name itself was renamed. The last entry of this kind +#: (``WindowFunctionCallExpression`` -> ``WindowFunctionCall``) is gone: the +#: node was unified into ``FunctionCall`` and Firebird's stale importer was +#: deleted with it. #: #: One case needed a **split** rather than a redirect and therefore has no entry #: here: ``impl.mysql.mixins.partition`` imported 25 names from @@ -88,10 +90,6 @@ "from rhosocial.activerecord.backend.expression.transaction import", None, ), - ("impl.firebird.mixins.window", "WindowFunctionCallExpression"): ( - "from rhosocial.activerecord.backend.expression.advanced_functions import", - "WindowFunctionCall", - ), ("impl.mysql.async_transaction", "AsyncMySQLBackend"): ( "from .async_backend import", None, diff --git a/.claude/version_control.md b/.claude/version_control.md index 96572871d..ced3f43f0 100644 --- a/.claude/version_control.md +++ b/.claude/version_control.md @@ -20,10 +20,15 @@ Three package kinds with distinct versioning: ### Python Version Support - **requires-python**: `>=3.8` (`[project]` in `pyproject.toml`). -- **Supported (1.0.x)**: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 (+ 3.15 in CI/classifiers). -- **Free-threaded builds**: 3.13t, 3.14t. +- **Supported (1.0.x)**: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15. +- **Free-threaded builds**: 3.13t, 3.14t, 3.15t. +- **Upstream EOL** (CPython: ~5-year life — bugfix, then security-only): 3.8 (2024-10), + 3.9 (2025-10) and 3.10 (2026-10) are past upstream end-of-life yet remain supported + in 1.0.x; 3.11–3.15 are still within their window. Past EOL a version receives no upstream + security patches, so supporting it is a deliberate risk this project accepts during 1.0.x. - **Pydantic**: `==2.10.6` for Python 3.8 (last 3.8-compatible line); `>=2.12.0` for 3.9+. -- `1.1.x` will likely drop 3.8/3.9 (min Python 3.10+); announced ≥6 months before. +- `1.1.x` will likely raise the floor to 3.11+ (dropping the EOL 3.8/3.9/3.10); announced + ≥6 months before. Use `requirements-3.8.txt` for Python 3.8 environments. diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 95e0bd958..f5aa866f7 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -55,7 +55,7 @@ jobs: pip install -r requirements-dev.txt pip install codecov build - pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/expression-schema-object-refactor" + pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@test/typed-column-contracts" - name: Run tests with coverage env: @@ -75,8 +75,8 @@ jobs: name: codecov-umbrella-3.14 fail_ci_if_error: false - benchmark-python-314: - name: Run benchmarks with Python 3.14 + benchmark-python-315: + name: Run benchmarks with Python 3.15 runs-on: ubuntu-latest permissions: contents: read @@ -96,10 +96,10 @@ jobs: - name: Check out the repository uses: actions/checkout@v6 - - name: Set up Python 3.14 + - name: Set up Python 3.15 uses: actions/setup-python@v6 with: - python-version: "3.14" + python-version: "3.15" cache: 'pip' cache-dependency-path: | requirements.txt @@ -112,7 +112,7 @@ jobs: pip install -r requirements.txt pip install -r requirements-dev.txt - pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/expression-schema-object-refactor" + pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@test/typed-column-contracts" - name: Run benchmark suite env: @@ -193,9 +193,9 @@ jobs: if: always() run: | { - echo "## Python 3.14 Benchmark Conclusion" + echo "## Python 3.15 Benchmark Conclusion" echo - echo "- Python: 3.14" + echo "- Python: 3.15" echo "- Scope: testsuite generic benchmarks + SQLite backend direct benchmarks" echo "- Size: small" echo "- Result: benchmark job fails only when benchmark execution or correctness checks fail." @@ -209,9 +209,9 @@ jobs: if: always() run: | { - echo "## Python 3.14 FastAPI Benchmark Conclusion" + echo "## Python 3.15 FastAPI Benchmark Conclusion" echo - echo "- Python: 3.14" + echo "- Python: 3.15" echo "- Scope: testsuite FastAPI database benchmarks" echo "- Size: small" echo "- Result: benchmark job fails only when FastAPI benchmark execution or correctness checks fail." @@ -279,7 +279,7 @@ jobs: pip install -r requirements-dev.txt fi - pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/expression-schema-object-refactor" + pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@test/typed-column-contracts" - name: Run tests env: @@ -340,7 +340,7 @@ jobs: pip install -r requirements-dev.txt fi - pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/expression-schema-object-refactor" + pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@test/typed-column-contracts" - name: Run tests env: @@ -351,19 +351,18 @@ jobs: export PYTHONPATH=src:tests python -m pytest tests/ -n auto --dist=loadgroup -p rhosocial.activerecord.testsuite.conftest - test-python-315-experimental: - name: Run tests with Python ${{ matrix.python-version }}${{ matrix.freethreaded && ' free-threaded' || '' }} (experimental) + test-python-315: + name: Run tests with Python ${{ matrix.python-version }}${{ matrix.freethreaded && 't free-threaded' || '' }} runs-on: ubuntu-26.04 permissions: contents: read - continue-on-error: true strategy: matrix: include: - - python-version: "3.15.0-rc.2" + - python-version: "3.15" redis-version: "8.8" freethreaded: false - - python-version: "3.15.0-rc.2" + - python-version: "3.15" redis-version: "8.8" freethreaded: true @@ -398,7 +397,7 @@ jobs: run: | pip install -r requirements.txt pip install -r requirements-dev.txt - pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/expression-schema-object-refactor" + pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@test/typed-column-contracts" - name: Run tests env: diff --git a/README.md b/README.md index 003e5c717..40700dbdf 100644 --- a/README.md +++ b/README.md @@ -308,13 +308,30 @@ Source: [rhosocial/python-activerecord](https://github.com/rhosocial/python-acti * **Python**: 3.8+ for the core library and the SQLite backend. Individual backends raise this floor — see the Backend Support table above. -* **Core Dependency**: Pydantic 2.10+ (Python 3.8) or 2.12+ (Python 3.9+) * **SQLite**: 3.25+ (for the built-in backend) +**The Pydantic pair follows the interpreter.** Where the newest release cannot +be installed the core pins an exact pair, and where it can it leaves the range +open — so the version you get is decided by your Python, not by a guess: + +| Python | pydantic | pydantic-core | Why | +|---|---|---|---| +| 3.8 | `==2.10.6` | `==2.27.2` | The last pair installable on 3.8 | +| 3.9 – 3.12 | `>=2.12.0` | `>=2.41.0` | Open; major stays 2.x | +| 3.13 **and** 3.13t | `==2.12.2` | `==2.41.4` | pydantic-core has **no cp313t wheel after 2.41.4**, and the newer sdists cannot be built there (PyO3 0.29 refuses a free-threaded CPython below 3.14). 2.12.2 is the last pydantic paired with 2.41.4 | +| 3.14, 3.15 | `>=2.12.0` | `>=2.41.0` | Open; major stays 2.x | + +`python_version` markers distinguish release *lines*, not GIL configuration, so +the 3.13 row pins both the GIL and the free-threaded build — installing on 3.13t +resolves to the same exact pair, which is what keeps that interpreter installable +at all. + Free-threaded builds: the core library and the SQLite backend are tested on 3.13t/3.14t. Per-backend status differs — Snowflake is **not** supported on -3.13t (`cryptography` → `cffi` has no free-threaded 3.13 build), and -ClickHouse caps at `<3.15`. +3.13t (`cryptography` → `cffi` has no free-threaded 3.13 build), ClickHouse caps +at `<3.15`, and PostgreSQL runs the GIL leg only because its driver, psycopg, +does not support free-threaded builds. Backends whose driver ships no cp315 +wheel at all are capped below 3.15 — see the Backend Support table. ## Get Started with AI Code Agents diff --git a/changelog.d/126.added.md b/changelog.d/126.added.md new file mode 100644 index 000000000..24befdb58 --- /dev/null +++ b/changelog.d/126.added.md @@ -0,0 +1 @@ +Add the typed column classes and their capability surfaces -- StringColumn, NumericColumn, IntegerColumn, TimestampColumn, BooleanColumn, BinaryColumn, UUIDColumn, JSONColumn, ArrayColumn and XMLColumn -- so which operations a column offers is decided by its class rather than by a universal base. Add the ColumnTypeSupport protocol (suggested_column_types / suggested_extra_column_types) as the single place a dialect answers that question, the node-and-hook pairs for TRIM, LPAD, RPAD and REPEAT so each is rendered by exactly one formatter, and the column_data_type() / columns_data_type() accessors that carry a field's SQL-type declaration. diff --git a/changelog.d/126.changed.md b/changelog.d/126.changed.md new file mode 100644 index 000000000..9c10c450b --- /dev/null +++ b/changelog.d/126.changed.md @@ -0,0 +1 @@ +Make the bare Column a reference that renders an identifier and keeps only the shared surface (aliasing, null tests, casting): operations are reached through a typed column or built explicitly as ComparisonPredicate, InPredicate, BetweenPredicate or BinaryArithmeticExpression, which is what the query and AR layers now do. Redefine DDLSource.column_type() as a declaration accessor that presents the field's UseColumnType marker as-is and answers None when there is none, leaving the SQL type to column_data_type(). diff --git a/changelog.d/126.docs.md b/changelog.d/126.docs.md new file mode 100644 index 000000000..0d1a71067 --- /dev/null +++ b/changelog.d/126.docs.md @@ -0,0 +1 @@ +Document the column-class and value-class pairing in the README, including the Python-3-to-Pydantic version table (an exact pair on 3.8 and on 3.13/3.13t where no newer release can be installed, open ranges elsewhere), the supported Python range and the per-backend caps that their database drivers impose. diff --git a/changelog.d/126.fixed.md b/changelog.d/126.fixed.md new file mode 100644 index 000000000..49b221863 --- /dev/null +++ b/changelog.d/126.fixed.md @@ -0,0 +1 @@ +Fix four predicates that silently evaluated to a Python bool instead of a predicate: the scalar primary-key path of find_one, the optimistic-lock check in the version field, restore() in the soft-delete field, and the foreign-key conditions of the relation query methods. Each fell through to object.__eq__ because the bare Column carries no comparison mixin, and each is now built as an explicit ComparisonPredicate. Enforce the recorded function version floors at render time, so calling a function whose floor exceeds the connected server's version now refuses with the function, the floor and the version instead of emitting SQL the server rejects. diff --git a/changelog.d/126.internal.md b/changelog.d/126.internal.md new file mode 100644 index 000000000..acd209387 --- /dev/null +++ b/changelog.d/126.internal.md @@ -0,0 +1 @@ +Rebuild the expression layer around explicit nodes: gate temporal arithmetic by operand with a dedicated mixin, split the string-to-integer surface out of the string value mixin, add the boundary and comparison contracts the operation survey measured, retire the dead supports_data_type_* probes by deriving supports_data_types() from formatter presence, annotate the format_* expr parameters with their concrete expression types, and add the round-trip enumeration and boundary tests that keep a missing dialect formatter from staying silent. diff --git a/changelog.d/126.removed.md b/changelog.d/126.removed.md new file mode 100644 index 000000000..c7000c1c2 --- /dev/null +++ b/changelog.d/126.removed.md @@ -0,0 +1 @@ +Remove the universal operator surface of the bare Column (it offered comparison, arithmetic and pattern operations on every value family), the DateTimeColumn name in favour of TimestampColumn, the columns_type bulk accessor in favour of columns_data_type, the supports_data_type_* probe family, and the DateTimeSupport protocol name in favour of TimestampSupport. Attribute access on an undeclared column now raises KeyError rather than answering None for a name that exists. diff --git a/docs/en_US/backend/custom_backend.md b/docs/en_US/backend/custom_backend.md index 14c94b5b2..21f8844fd 100644 --- a/docs/en_US/backend/custom_backend.md +++ b/docs/en_US/backend/custom_backend.md @@ -280,7 +280,7 @@ JSONTableExpression( - **Type Safety**: Type checkers can verify the interface signature - **Backward Compatible**: Adding options doesn't break existing implementations -After mixing in a protocol, verify the corresponding formatting methods. For example, if you mix in `WindowFunctionMixin`, check `format_window_function_call` in the mixin/base class. +After mixing in a protocol, verify the corresponding formatting methods. For example, if you mix in `WindowFunctionMixin`, check `format_window_specification` in the mixin/base class; the `OVER (...)` clause itself is assembled by `format_function_call`, which every function call goes through. * If your database follows standard SQL (e.g., `OVER (...)`), the default implementation works. * If it differs, override that specific method. diff --git a/docs/en_US/backend/expression/advanced.md b/docs/en_US/backend/expression/advanced.md index 78582c931..3985aea1e 100644 --- a/docs/en_US/backend/expression/advanced.md +++ b/docs/en_US/backend/expression/advanced.md @@ -113,12 +113,13 @@ The PostgreSQL dialect automatically uses the `::` syntax to generate more conci Window functions perform calculations across a set of table rows that are somehow related to the current row. -### WindowFunctionCall +### FunctionCall with OVER -Represents a call to a window function (e.g., `ROW_NUMBER() OVER (...)`). +A window function call is a `FunctionCall` carrying a `window_spec`: attach +it fluently with `.over(...)`, or pass `window_spec=` at construction. ```python -from rhosocial.activerecord.backend.expression import WindowFunctionCall, WindowSpecification, Column, Literal +from rhosocial.activerecord.backend.expression import FunctionCall, WindowSpecification, Column, Literal from rhosocial.activerecord.backend.expression.query_parts import OrderByClause # Define Window Specification @@ -128,13 +129,8 @@ window_spec = WindowSpecification( order_by=OrderByClause(dialect, [(Column(dialect, "salary"), "DESC")]) ) -# Create Window Function Call -window_func = WindowFunctionCall( - dialect, - function_name="ROW_NUMBER", - window_spec=window_spec, - alias="row_num" -) +# Create Window Function Call and attach the window specification +window_func = FunctionCall(dialect, "ROW_NUMBER").over(window_spec).as_("row_num") sql, params = window_func.to_sql() # sql: 'ROW_NUMBER() OVER (PARTITION BY "department" ORDER BY "salary" DESC) AS "row_num"' @@ -231,16 +227,26 @@ sql, params = intersect_op.to_sql() Expressions for working with JSON data. -### JSONExpression +### JSONDocumentExpression / JSONTextExpression -Represents JSON path extraction or operations. +Represents JSON path extraction. The operator picks the class: ``->`` +yields a document and is a ``JSONDocumentExpression``, ``->>`` yields text and +is a ``JSONTextExpression``. Two classes rather than one class with a spelling +parameter, because the two results are different kinds of value -- a document +can be indexed into again, text cannot. ```python -from rhosocial.activerecord.backend.expression import JSONExpression, Column +from rhosocial.activerecord.backend.expression import ( + JSONDocumentExpression, + JSONTextExpression, +) col = Column(dialect, "data") -# Extract value from JSON path -json_extract = JSONExpression(dialect, col, "$.user.name", operation="->>") +# Extract value from JSON path as text +json_extract = JSONTextExpression(dialect, col, "$.user.name", operation="->>") + +# A nested path is still a document, so it can be walked further +nested = JSONDocumentExpression(dialect, col, "$.user", operation="->") sql, params = json_extract.to_sql() # sql: '"data"->>?', or dialect-specific equivalent like 'JSON_EXTRACT("data", ?)' diff --git a/docs/en_US/backend/expression/extending.md b/docs/en_US/backend/expression/extending.md index d1a5f6f09..964221c68 100644 --- a/docs/en_US/backend/expression/extending.md +++ b/docs/en_US/backend/expression/extending.md @@ -1,6 +1,6 @@ # Extending Guide: Implementing Serializable Expressions -This document is for backend developers, explaining how to implement serialization for custom expressions. +This document is for backend developers, explaining how to make custom expressions serializable. ## Basic Requirements @@ -8,15 +8,15 @@ Expression classes must meet the following requirements to be correctly handled 1. Inherit from `BaseExpression` 2. `__init__` parameter names must correspond to attribute names (using `_` prefix for private attributes or same-named attributes) -3. Use `get_params()` to return serializable parameters +3. Do not implement `get_params()` — the generic implementation is the single serialization path, so `__init__` must store its state under the name the constructor received it as ## get_params() Convention -The default `get_params()` implementation automatically infers using `inspect.signature`: +The generic `get_params()` implementation automatically infers using `inspect.signature`: - Parameter `foo` → attribute `self._foo` or `self.foo` - `VAR_POSITIONAL (*args)` → list -- `VAR_KEYWORD (**kwargs)` → skipped (requires manual override) +- `VAR_KEYWORD (**kwargs)` → the extras, collected into a dict stored on an attribute named after the parameter (e.g. `self.collation_options`) and merged into the top level of `params`, so reconstruction re-expands them ```python class MyExpression(BaseExpression): @@ -27,17 +27,23 @@ class MyExpression(BaseExpression): # No need to manually implement get_params(), default implementation auto-extracts ``` -### Custom get_params() +`CollateExpression` is the `**kwargs` case in core: it collects `**collation_options` into `self.collation_options: dict`, so `get_params()` returns `binary`, `pad` and the rest as top-level parameters and reconstruction passes them back as keywords. -Override this method when default inference doesn't apply: +A parameter the convention cannot resolve is skipped with a warning. That warning is the diagnostic — it means `__init__` stores state under a name `get_params()` cannot see — and the repair is always in `__init__`. -```python -def get_params(self) -> dict: - params = super().get_params() - # Add or modify parameters - params["custom_key"] = self._custom_value - return params -``` +### Why There Is No Custom get_params() + +`get_params()` is not an extension point: an override is a defect, not a customization. Core enforces this with no exceptions in `tests/.../dummy2/test_expression_contract.py::test_no_get_params_override` — every registered expression class must leave the generic implementation alone. (The single exemption the test allows, a `VAR_POSITIONAL` class doing genuine raw-vs-normalized round-trip rewriting, has no instance in the core registry.) + +The reason is structural rather than stylistic. A round-trip is rebuilt by calling the constructor with whatever `get_params()` returned, so those two halves have to agree. An override is exactly where they drift: the class emits a key the constructor renames, merges or refuses, `_reconstruct()` wraps the resulting `TypeError` as `ExpressionDeserializationError`, and the state is silently gone. The backend packages accumulated their own overrides, every one of them written because `__init__` renamed or merged what the caller passed — and every one of them became unnecessary once the state was stored under the name it was given. + +When the generic result is not what you wanted, the repair is always in `__init__`, and it is one of three shapes: + +| The problem | The repair | +|---|---| +| You renamed or merged what the caller passed | Store it under the name the parameter has | +| Two constructor spellings mean one thing | Keep both slots; put the value in the one the caller used and leave the other `None` | +| The value cannot be serialized as it stands | Convert it in `__init__` and store the converted value | ## Registration Mechanism @@ -57,22 +63,30 @@ ExpressionRegistry.register(MyExpression) ## Four Special Cases +The four cases below are the usual reasons a developer reaches for a custom `get_params()`. None of them needs one: each is solved in `__init__`. + ### 1. Dialect-Specific Enum Parameters -Some dialects have specific enum values (e.g., PostgreSQL's `IsolationLevel`): +Some dialects have specific enum values (e.g., PostgreSQL's `IsolationLevel`). Accept whichever spelling the caller has and store the value the spec can carry: ```python class MyTransactionExpression(BaseExpression): - def __init__(self, dialect, isolation_level: str = "READ COMMITTED"): + def __init__(self, dialect, isolation_level="READ COMMITTED"): super().__init__(dialect) - self._isolation_level = isolation_level # Accept string, not enum - -# get_params() returns string, dialect-independent + # Accept the dialect's enum or its string; store the normalized string + self._isolation_level = ( + isolation_level.value + if isinstance(isolation_level, Enum) + else str(isolation_level) + ) + +# get_params() returns {"isolation_level": "SERIALIZABLE"} — a string, dialect-independent +# and reconstruction passes that string back into a constructor that accepts one ``` ### 2. State Set via Fluent API -State modified via fluent API must be synced to `__init__` parameters: +State modified via fluent API must be synced to `__init__` parameters — the setter and the parameter have to read and write the *same* attribute, because that attribute is all `get_params()` ever sees: ```python class MyExpression(BaseExpression): @@ -85,73 +99,89 @@ class MyExpression(BaseExpression): return self ``` +A setter that writes a second attribute alongside the parameter's own is writing state the round-trip cannot see. + ### 3. set Type Parameters -`set` type cannot be directly JSON serialized; convert to list in `get_params()`: +A `set` is a poor carrier for expression state: it has no order, and the codec encodes it as a flat list whose members never receive the nested-expression markers they would need, so a `set` of expressions does not survive a JSON round-trip. Convert in `__init__` and store the converted value — the generic path then emits exactly what the constructor accepts: ```python -def get_params(self) -> dict: - params = super().get_params() - params["columns"] = list(self._columns) # set -> list - return params +class ColumnSetExpression(BaseExpression): + def __init__(self, dialect, columns): + super().__init__(dialect) + self._columns = list(columns) # set or any iterable in, list stored + +# get_params() returns {"columns": [...]}; reconstruction passes the list back +# into the same constructor, which accepts a list just as happily ``` ### 4. Circular References -The current framework doesn't detect circular references. If self-reference is possible, truncate in `get_params()`: +The framework does not detect cycles, and a self-reference cannot be serialized — the serializer would recurse until Python's recursion limit. Store the link by identity rather than by object: the parameter is the id, and the object, if it is needed at all, lives on an attribute the constructor does not take, which `get_params()` never reads. ```python -def get_params(self) -> dict: - params = {"id": self._id, "name": self._name} - if self._parent is not None: - params["parent_id"] = self._parent._id # Only store ID, not object - return params +class TreeNodeExpression(BaseExpression): + def __init__(self, dialect, name, parent_id=None): + super().__init__(dialect) + self._name = name + self._parent_id = parent_id # identity, not the object + # Resolved by the tree walker; no matching parameter, so never serialized + self._parent = None ``` -## IntrospectionExpression Convention +When the parent genuinely has to travel with the node, make it an ordinary nested-expression parameter: that is what `{"__expr__": ...}` exists for. The tree is then simply finite. -`IntrospectionExpression` subclasses (like `TableListExpression`) have a `None` filtering rule: +## IntrospectionExpression Convention -- Optional parameters with value `None` should not appear in `params` +`IntrospectionExpression` subclasses (like `TableListExpression`) combine a constructor with fluent setters that share the parameter names. Both halves of the generic path already account for this: ```python class TableListExpression(IntrospectionExpression): - def get_params(self) -> dict: - params = {} - if self._schema is not None: - params["schema"] = self._schema - # include_views defaults to True, always included - params["include_views"] = self._include_views - return params + def __init__(self, dialect, schema=None, include_views=True, include_system=False, table_type=None): + super().__init__(dialect, schema) + self._include_views = include_views + self._include_system = include_system + self._table_type = table_type + + def include_views(self, value: bool = True): + self._include_views = value # the same attribute the parameter is read from + return self ``` +- **When both spellings exist, the callable one is not the state.** If a parameter has both `self.foo` and `self._foo` and the public attribute is a fluent method, the private attribute is taken as the value. +- **An optional parameter left unset is emitted as `null`, not omitted.** That is safe: the deserializer passes it back and the constructor's default applies. What is *not* safe is dropping a parameter whose value differs from its default — that is state the round-trip loses. + ## Error Contract All paths through `_reconstruct()`, `TypeError` is wrapped as `ExpressionDeserializationError`. This ensures callers only need to catch one exception type. ## Serialization Format Convention (Reserved Key Names) -When implementing `get_params()` for custom expressions, **do not** use the following reserved key names in the returned dictionary, otherwise deserialization behavior is undefined: +The **values** `get_params()` returns must not contain the following reserved keys at any depth, otherwise deserialization behavior is undefined — the deserializer reads them as framework markers: - `__expr__`: Used to mark nested expressions - `__tuple__`: Used to mark tuples +- `__value__` / `__vdc__`: Used to mark codec-encoded scalars and dataclass values + +Your own top-level keys come from your `__init__` parameter names (plus whatever `**kwargs` extras were merged in), so never name a parameter after a reserved key. For an opaque payload whose keys you do not control, the hazard is inside the payload: those keys are copied into the spec verbatim, and renaming the parameter does nothing about them. Validate at construction time, or store the payload as text. ```python -# Incorrect - may cause data corruption +_RESERVED = ("__expr__", "__tuple__", "__value__", "__vdc__") + +# Incorrect - a payload containing "__expr__" is read back as a nested expression class RawJsonStorageExpr(BaseExpression): def __init__(self, dialect, data: dict): + super().__init__(dialect) self._data = data - def get_params(self): - return {"data": self._data} # If data = {"__expr__": "..."}, round-trip fails - -# Correct - avoid using reserved key names +# Correct - the payload is rejected before it can reach a spec class SafeJsonStorageExpr(BaseExpression): def __init__(self, dialect, json_data: dict): + super().__init__(dialect) + for key in json_data: + if key in _RESERVED: + raise ValueError(f"{key!r} is a reserved serialization key") self._json_data = json_data - - def get_params(self): - return {"json_data": self._json_data} # Does not use __expr__ etc. ``` ## Related Documents diff --git a/docs/en_US/backend/expression/format-reference.md b/docs/en_US/backend/expression/format-reference.md index 60a08b248..78afe6725 100644 --- a/docs/en_US/backend/expression/format-reference.md +++ b/docs/en_US/backend/expression/format-reference.md @@ -80,7 +80,7 @@ Tuples use `__tuple__` marker: | `tuple` | object | Use `__tuple__` marker | | `BaseExpression` | object | Use `__expr__` marker | | `set` | - | Not supported, convert to list | -| Other custom objects | - | Must handle in `get_params()` | +| Other custom objects | object | Via a registered `__value__` codec, or converted in `__init__` | ## Serialization Flow diff --git a/docs/en_US/backend/expression/functions.md b/docs/en_US/backend/expression/functions.md index 80a274a69..ae72c5968 100644 --- a/docs/en_US/backend/expression/functions.md +++ b/docs/en_US/backend/expression/functions.md @@ -4,21 +4,31 @@ This document describes the factory functions defined in `src/rhosocial/activere ## Overview -The `functions` module provides factory functions that simplify the creation of SQL function calls. Instead of manually instantiating `FunctionCall` or `AggregateFunctionCall` objects, you can use these helpers which handle type conversion and provide a more Pythonic interface. +The `functions` module provides factory functions that simplify the creation of SQL function calls. Instead of manually instantiating `FunctionCall` objects, you can use these helpers which handle type conversion and provide a more Pythonic interface. ## Aggregate Functions -### AggregateFunctionCall +### FunctionCall (aggregate use) -Represents a call to a SQL aggregate function. Supports `FILTER` (WHERE) clauses. +An aggregate call is a `FunctionCall`; aggregate factories set its +construction-time `is_aggregate` fact. It supports `FILTER (WHERE ...)` +clauses and `OVER (...)` window clauses. ```python -class AggregateFunctionCall(mixins.AliasableMixin, mixins.ArithmeticMixin, mixins.ComparisonMixin, bases.SQLValueExpression): - def __init__(self, dialect: "SQLDialectBase", func_name: str, *args, is_distinct: bool = False, alias: Optional[str] = None): ... +class FunctionCall(mixins.AliasableMixin, mixins.ArithmeticMixin, mixins.ComparisonMixin, mixins.StringPatternPredicateMixin, mixins.TypeCastingMixin, mixins.ResultTypeMixin, bases.SQLValueExpression): + def __init__(self, dialect: "SQLDialectBase", func_name: str, *args, + is_distinct: bool = False, alias: Optional[str] = None, + niladic: bool = False, filter_predicate: "SQLPredicate" = None, + window_spec: Union["WindowSpecification", str] = None, + is_aggregate: bool = False): ... - def filter(self, predicate: "SQLPredicate") -> 'AggregateFunctionCall': + def filter(self, predicate: "SQLPredicate") -> 'FunctionCall': """Applies a FILTER (WHERE ...) clause to the aggregate expression.""" ... + + def over(self, window_spec: Union["WindowSpecification", str]) -> 'FunctionCall': + """Attaches an OVER (...) clause to the call.""" + ... ``` **Example:** @@ -47,7 +57,7 @@ sql, params = high_value_sum.to_sql() Creates a `COUNT` aggregate function call. ```python -def count(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"] = "*", is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def count(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"] = "*", is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **Usage Rules:** @@ -75,7 +85,7 @@ sql, params = c2.to_sql() Creates a `SUM` aggregate function call. Note the trailing underscore to avoid conflict with Python's built-in `sum`. ```python -def sum_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def sum_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **Example:** @@ -91,7 +101,7 @@ sql, params = s.to_sql() Creates an `AVG` aggregate function call. ```python -def avg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def avg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **Example:** @@ -107,7 +117,7 @@ sql, params = a.to_sql() Creates a `MIN` aggregate function call. Note the trailing underscore. ```python -def min_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def min_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **Example:** @@ -123,7 +133,7 @@ sql, params = m.to_sql() Creates a `MAX` aggregate function call. Note the trailing underscore. ```python -def max_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def max_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **Example:** @@ -713,7 +723,7 @@ sql, params = l.to_sql() Creates a `ROW_NUMBER` window function call. ```python -def row_number(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... +def row_number(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **Example:** @@ -729,8 +739,8 @@ sql, params = r.to_sql() Creates `RANK` and `DENSE_RANK` window function calls. ```python -def rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... -def dense_rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... +def rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "core.FunctionCall": ... +def dense_rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ### lag, lead @@ -738,8 +748,8 @@ def dense_rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "advan Creates `LAG` and `LEAD` window function calls. ```python -def lag(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], offset: Optional[int] = 1, default: Optional[Union[str, "bases.BaseExpression"]] = None, alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... -def lead(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], offset: Optional[int] = 1, default: Optional[Union[str, "bases.BaseExpression"]] = None, alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... +def lag(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], offset: Optional[int] = 1, default: Optional[Union[str, "bases.BaseExpression"]] = None, alias: Optional[str] = None) -> "core.FunctionCall": ... +def lead(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], offset: Optional[int] = 1, default: Optional[Union[str, "bases.BaseExpression"]] = None, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ### first_value, last_value, nth_value @@ -747,9 +757,9 @@ def lead(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], of Creates value window function calls. ```python -def first_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... -def last_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... -def nth_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], n: int, alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... +def first_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "core.FunctionCall": ... +def last_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "core.FunctionCall": ... +def nth_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], n: int, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ## JSON Functions @@ -791,8 +801,8 @@ def json_array_elements(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseE Creates JSON aggregate function calls. ```python -def json_objectagg(dialect: "SQLDialectBase", key_expr: Union[str, "bases.BaseExpression"], value_expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... -def json_arrayagg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def json_objectagg(dialect: "SQLDialectBase", key_expr: Union[str, "bases.BaseExpression"], value_expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... +def json_arrayagg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ## Array Functions @@ -802,7 +812,7 @@ def json_arrayagg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpress Creates an `ARRAY_AGG` aggregate function call. ```python -def array_agg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def array_agg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ### unnest diff --git a/docs/en_US/backend/expression/types.md b/docs/en_US/backend/expression/types.md index d70cde2a8..743c7e075 100644 --- a/docs/en_US/backend/expression/types.md +++ b/docs/en_US/backend/expression/types.md @@ -54,7 +54,7 @@ Model classes define their field type annotations at **import time**, when the m ## Value-Object Semantics -`DataType` instances are **value objects**: two instances of the same class with the same logical parameters are **equal and hash-equal**, regardless of whether they carry a dialect reference. Equality compares the type's logical parameters (`_type_params()`) plus its `dialect_options`; the hash covers type identity and type params only. The bound dialect is ignored by both — binding (or re-binding) a dialect never affects `==` or `hash`. +`DataType` instances are **value objects**: two instances of the same class with the same logical parameters are **equal and hash-equal**, regardless of whether they carry a dialect reference. Equality compares the type's **declared identity** — the attributes listed in the class constant `PARAMETERS` — and the hash covers the type's class plus those same attributes. The bound dialect is ignored by both — binding (or re-binding) a dialect never affects `==` or `hash`. ```python a = IntegerType() @@ -63,26 +63,54 @@ assert a == b # value object: equal (dialect ignored) assert hash(a) == hash(b) ``` -`dialect_options` is the dict of **backend-specific exotic parameters** (e.g. `{'unsigned': True}`, charset, length semantics) that travels with the type instance and is consumed by the backend's formatters. It participates in **equality** but deliberately **not** in the hash, so mutable option mappings cannot break hashing. +There is no separate bag of "backend-specific options" hanging off a data type. Anything a backend needs beyond the concept's own parameters is a **declared field** on the class — `CharType.length`, `DecimalType.precision`/`scale`, `EnumType.values`, `ArrayType.element_type`/`dimensions`, and `unsigned: bool` on the four integer classes — and it is listed in the class's `PARAMETERS`, hence in both `==` and `hash`. + +## Spellings + +Several concepts have more than one legitimate written form. Those are **spellings of one class**, not separate classes: the class carries a closed `SPELLINGS` tuple and a `spelling` keyword, and the *first* entry is the default. + +```python +IntegerType() # spelling "integer" +IntegerType(spelling="int") # the same class, the other word +assert IntegerType() == IntegerType(spelling="int") # the same value +``` + +Why one class rather than two: `INT` and `INTEGER` are the same type, so code that has to ask "is this an integer column?" must not have to enumerate the spellings. + +**Why the spelling is *not* part of `==`.** The tempting argument is that it was part of what was declared, so a difference in it is a difference worth reporting. But the schema differ does not compare two DDL scripts — it compares **what the database reports now** against **what was declared**, and a database reports its own house spelling no matter which word was typed. PostgreSQL reports `character varying(30)` for every `varchar(30)` column that exists, and SQL Server reports `DECIMAL` for a column declared as `NUMERIC`. Counting the spelling would therefore report a change on every such column that was never touched: a false positive on the one comparison that has to be right. + +Nothing is lost. The spelling still reaches the rendered SQL — that is where the difference is real and visible: + +```python +IntegerType() # renders INTEGER +IntegerType(spelling="int") # renders INT +``` + +and it still round-trips through `get_params()` for serialization, because serialization asks a different question — not "what is this value" but "what is needed to rebuild this object" — and that answer is the constructor signature. `get_params()` is the single serialization path for all expressions and is not overridden on any of them. + +Which spellings a *particular backend* renders is the backend's business, and it is checked in the backend's formatter: a dialect that does not write `CLOB` raises rather than silently emitting `TEXT` for a caller who asked for `CLOB`. The default spelling always renders — a backend may normalise it to its own word, never refuse it. ## Core Types -Core types are defined in `rhosocial.activerecord.backend.expression.types` and cover the SQL types shared by most databases: - -| Category | Type classes | -|----------|--------------| -| Integer | `TinyIntType`, `SmallIntType`, `IntType`, `IntegerType`, `BigIntType` | -| Numeric | `FloatType`, `RealType`, `DoubleType`, `DecimalType` | -| String | `CharType`, `VarCharType`, `TextType` | -| Boolean | `BooleanType` | -| Binary | `BlobType`, `BinaryType`, `VarBinaryType` | -| Enum | `EnumType` (values required) | -| Date/time | `DateType`, `TimeType`, `TimeTzType`, `DateTimeType`, `TimestampType`, `TimestampTzType`, `IntervalType` | -| JSON | `JsonType`, `JsonBType` | -| Network | `InetType`, `CidrType`, `MacAddrType` | -| UUID | `UUIDType` | -| Array | `ArrayType` | -| Custom | `CustomType` | +Core types are defined in `rhosocial.activerecord.backend.expression.types` and cover the SQL types shared by most databases. A concept with several spellings lists them; a concept with one has no `spelling` argument at all. + +| Category | Type classes | Spellings | +|----------|--------------|-----------| +| Integer | `TinyIntType`, `SmallIntType`, `IntegerType`, `BigIntType` | `tinyint`/`int1`, `smallint`/`int2`, `integer`/`int`, `bigint`/`int8` | +| Numeric | `FloatType`, `RealType`, `DoubleType`, `DecimalType` | `double`/`double precision`, —, —, `decimal`/`numeric`/`dec` | +| String | `CharType`, `VarCharType`, `TextType` | `char`/`character`, `varchar`/`character varying`, `text`/`clob` | +| Boolean | `BooleanType` | `boolean`/`bool` | +| Binary | `BlobType`, `BinaryType`, `VarBinaryType` | `blob`/`bytea`, —, — | +| Enum | `EnumType` (values required) | — | +| Date/time | `DateType`, `TimeType`, `TimeTzType`, `DateTimeType`, `TimestampType`, `TimestampTzType`, `IntervalType` | — | +| JSON | `JsonType`, `JsonBType`, `XmlType` | — | +| UUID | `UUIDType` | — | +| Array | `ArrayType` | — | +| Custom | `CustomType` | — | + +`TinyIntType`, `SmallIntType`, `IntegerType` and `BigIntType` each take `unsigned: bool`. Signed and unsigned are the *same class* — the range is what the parameter carries — because a linear inheritance chain cannot hold a (width × signedness) grid, and because a backend that has no unsigned integers widens rather than inventing a class. + +`RealType`, `DoubleType` and `FloatType` are three classes on purpose. They have different ranges and different storage, and a schema diff must see the difference; `DateTimeType` and `TimestampType` likewise. `JsonType` and `XmlType` are separate because SQL/JSON and SQL/XML have different operations and different standards, and the backends that implement one do not reliably implement the other. Core types can be instantiated without a dialect (deferred binding), but cannot render until one is bound. @@ -92,11 +120,13 @@ Each backend defines its own subtypes on top of the core types, **named with the | Backend | Examples | |---------|----------| -| SQLite | `SQLiteIntegerType(IntegerType)`, `SQLiteTextType(TextType)`, `SQLiteBlobType(BlobType)` | -| MySQL | `MySQLIntType(IntegerType)`, `MySQLTinyIntType(TinyIntType)`, `MySQLEnumType(DataType)`, `MySQLSetType(DataType)`, `MySQLGeometryType(DataType)` | -| PostgreSQL | `PostgresSerialType(DataType)`, `PostgresUUIDType(DataType)`, `PostgresTSVectorType(DataType)`, `PostgresJsonPathType(DataType)` | +| SQLite | `SQLiteIntegerType(IntegerType)`, `SQLiteTextType(TextType)`, `SQLiteBlobType(BlobType)`, `SQLiteNumericType(DataType)` | +| MySQL | `MySQLIntType(IntegerType)`, `MySQLTinyIntType(TinyIntType)`, `MySQLEnumType(EnumType)`, `MySQLSetType(DataType)`, `MySQLGeometryType(DataType)` | +| PostgreSQL | `PostgresSerialType(IntegerType)`, `PostgresUUIDType(UUIDType)`, `PostgresXMLType(XmlType)`, `PostgresTSVectorType(DataType)`, `PostgresJsonPathType(DataType)` | + +A backend type **derives from the core type of the concept it is**, whenever there is one — that is what makes `isinstance(col.data_type, IntegerType)` true for a PostgreSQL `SERIAL` column instead of forcing every caller to know each backend's private class list. It inherits `DataType` directly only when the concept is genuinely backend-exclusive, and then its docstring must say *why* there is no core concept. -Backend-specific types usually inherit the corresponding core type; they inherit `DataType` directly only when the type is backend-exclusive (e.g. MySQL `ENUM`, PostgreSQL `SERIAL`). +Inheritance means **identity** — "this class *is* that SQL type". It is not used to group types into families: SQL's data-type categories (numeric, string, date/time) are membership, not subtyping, and nothing in this framework asks "is this numeric". The chain is linear: no multiple inheritance, no diamond edges. Each backend-defined type declares a **namespaced generic type name** — the backend slug as prefix (e.g. `SQLiteIntegerType.name == "sqlite_integer"`). This prefix is enforced at class-definition time (`__init_subclass__`): a type defined outside the core types package whose name lacks the backend prefix is rejected, keeping the dispatch keys of different backends isolated. @@ -156,7 +186,7 @@ for name, dt_cls in dialect.supports_data_types().items(): ### Integration with Model Fields -A plain Python annotation is not converted into a `DataType` by `DDLSourceMixin`. Without `UseSqlType`, `column_type()` returns `None`. Use `UseSqlType` for an explicit declaration; it preserves candidates in declaration order: +A plain Python annotation is not converted into a `DataType` by `DDLSourceMixin`. Without `UseSqlType`, `column_data_type()` returns `None`. Use `UseSqlType` for an explicit declaration; it preserves candidates in declaration order: ```python from typing import Annotated @@ -174,14 +204,28 @@ class Product(ActiveRecord): When a dialect implements `parse_type(raw)` (the `DataTypeSupport` protocol), it can parse a raw type string returned by the database back into a `DataType` object for schema introspection and comparison. Dialects without this interface fall back to `CustomType(raw=raw)`. The former names `DDLTypeSupport` and `DDLTypeMixin` remain deprecated compatibility aliases for `DataTypeSupport` and `DataTypeMixin`. -## Equivalence and Synonyms +A `parse_type` answer has to be **canonical**, and both halves of that are enforced by `tests/.../dummy2/test_type_spelling_parse.py`: + +- **Coverage** — every entry of every core `SPELLINGS` tuple reaches a type. `CustomType` is the honest answer only for a name the framework has no concept for; used on `INT1`, `CHARACTER`, `DEC` or `BOOL` it would report a type the framework itself declares as a vendor-specific one, and write the raw text back. +- **One concept in, one class out** — all spellings of one concept reach the same class, and `character varying` (variable length) never reaches the fixed-length `CharType`. Two classes per synonym is what the `spelling` parameter exists to prevent, and a parser that conflated the two would report a schema change that is not there. + +Which class is the dialect's answer, not the spelling's: a backend whose storage cannot tell two concepts apart may answer with the class that stands for that shared storage. SQLite is the case in core — `TINYINT` and `BIGINT` are one INTEGER-affinity cell, and reporting them apart would report a distinction the database does not make. + +## Comparing Two Declared Types -`synonyms()` and `is_equivalent()` are used **only** for intra-dialect schema-comparison normalization (e.g. SQLite affinity collapse). **Never** register cross-dialect equivalences — rendering stays strictly faithful and dialect differences must remain explicit. +`==` is the whole comparison. Two declarations are the same type when they are the same class with the same logical content, which is what a value object's `==` already means. ```python -# Only for schema-comparison scenarios within the same backend -if type_a.is_equivalent(type_b): - ... +if old_type != new_type: + ... # the schema really did change +``` + +There is no looser "are these equivalent" question to ask, and that is deliberate. The old `synonyms()`/`is_equivalent()` pair existed to paper over synonym *classes*, which is what this design removes: with synonyms expressed as a `spelling` parameter, two spellings are one class, so there is nothing left for an equivalence table to reconcile. Measured across 9 dialects × 11 synonym pairs (99 comparisons), `is_equivalent()` and `==` never disagreed — it was a mechanism with no remaining work to do. + +One question `==` genuinely cannot answer is "does this array column store the same kind of thing as that one", where the answer should ignore how many axes the array has. That is a different question, it has its own name, and it is spelled `is_element_type_equivalent`: + +```python +two_d.is_element_type_equivalent(one_d) # True — both hold integers ``` ## Related Documentation diff --git a/docs/en_US/backend/template/backend_specific_features/dialect.md b/docs/en_US/backend/template/backend_specific_features/dialect.md index a72912dda..d231f6e81 100644 --- a/docs/en_US/backend/template/backend_specific_features/dialect.md +++ b/docs/en_US/backend/template/backend_specific_features/dialect.md @@ -143,7 +143,7 @@ The following expression classes are shared across all backends. They live in `r |-------|---------| | `Column` | Column reference | | `Literal` | Parameter placeholder (e.g., `?`, `%s`, `$1`) | -| `FunctionCall` | Function invocation (`FUNC(args)`) | +| `FunctionCall` | Function invocation (`FUNC(args)`), aggregate `FILTER (WHERE ...)` and window `OVER (...)` | | `Subquery` | Subquery as expression | | `TableExpression` | Table reference with temporal options | | `WildcardExpression` | `*` wildcard | @@ -156,8 +156,8 @@ The following expression classes are shared across all backends. They live in `r | `BinaryExpression` | Binary operators | | `BinaryArithmeticExpression` | `+`, `-`, `*`, `/`, `%` | | `CaseExpression` | `CASE WHEN ... THEN ... END` | -| `WindowFunctionCall` | Window functions (`OVER (...)`) | -| `JSONExpression` | JSON operators | +| `JSONDocumentExpression` | JSON path, yielding a document (`->`) | +| `JSONTextExpression` | JSON path, yielding text (`->>`) | | `ArrayExpression` | Array operators | ### Mixin Classes (Operator Overloading) diff --git a/docs/en_US/backend/template/backend_specific_features/field_types.md b/docs/en_US/backend/template/backend_specific_features/field_types.md index 9babf0540..6bdee9b9b 100644 --- a/docs/en_US/backend/template/backend_specific_features/field_types.md +++ b/docs/en_US/backend/template/backend_specific_features/field_types.md @@ -4,7 +4,7 @@ rhosocial-activerecord's type system has two layers: -1. **Core DataType hierarchy** — Generic type classes (`IntegerType`, `VarCharType`, `BooleanType`, etc.) in `rhosocial.activerecord.backend.expression.types` define common behavior. When you declare a field as `str`, `int`, or `bool` on a model, the framework maps it to the appropriate core DataType. +1. **Core DataType hierarchy** — Generic type classes (`IntegerType`, `VarCharType`, `BooleanType`, etc.) in `rhosocial.activerecord.backend.expression.types` define common behavior. A field's Python annotation does **not** select one for you: without an explicit `UseSqlType(...)`, `column_data_type()` returns `None` and nothing is inferred. The "Python Type" column below is the type you would annotate a field with, not a mapping the framework performs. 2. **Backend-specific DataType subclasses** — Each backend extends core types with database-specific behavior. For example, `MySQLIntType` adds AUTO_INCREMENT support, and `PostgresUUIDType` maps to PostgreSQL's native UUID type. Backend types are in `rhosocial.activerecord.backend.impl.{backend}.expression.types`. @@ -90,7 +90,7 @@ email_type = VarCharType() | `DateTimeType` | `datetime` | `precision: Optional[int]` | Date + time (MySQL/SQLite) | | `TimestampType` | `datetime` | `precision: Optional[int]` | Timestamp (SQL standard) | | `TimestampTzType` | `datetime` | `precision: Optional[int]` | Timestamp with timezone | -| `IntervalType` | — | `fields: Optional[str]` | Time span (e.g., `'YEAR'`, `'DAY TO SECOND'`) | +| `IntervalType` | — | `fields: Optional[IntervalQualifier]` | Time span; `fields` is the resolution, from a closed vocabulary | The `precision` parameter on time types controls sub-second precision (0-9 digits): @@ -108,6 +108,31 @@ ts_type = TimestampType(precision=0) ts_micro_type = TimestampType(precision=6) ``` +`IntervalType.fields` is a **closed vocabulary**, not a free string, because it +reaches DDL in a position that cannot take a bound parameter: + +```python +from rhosocial.activerecord.backend.expression.types import ( + INTERVAL_QUALIFIERS, + IntervalQualifier, + IntervalType, +) + +# The thirteen SQL:2016 qualifiers: one field, or one field TO a later one, +# each optionally with a leading precision. +IntervalType(dialect, fields="YEAR TO MONTH") # INTERVAL YEAR TO MONTH +IntervalType(dialect, fields="DAY(2) TO SECOND(6)") # INTERVAL DAY(2) TO SECOND(6) +IntervalType(dialect) # unqualified INTERVAL + +# Anything else is refused, and the message names both the value and the set. +IntervalType(dialect, fields="DAY TO SECOND); DROP TABLE t--") +# InvalidIntervalQualifierError: 'DAY TO SECOND); DROP TABLE t--' is not a SQL +# interval qualifier. ... DAY TO SECOND, DAY TO HOUR, ... + +# ``fields`` holds an IntervalQualifier, a ``str``, so it still renders as itself. +isinstance(IntervalQualifier("YEAR TO MONTH"), str) # True +``` + ### Binary Types | Core Type | Python Type | Parameters | Description | diff --git a/docs/en_US/backend/template/customization/custom_types.md b/docs/en_US/backend/template/customization/custom_types.md index cfefc62a1..c00f13dc0 100644 --- a/docs/en_US/backend/template/customization/custom_types.md +++ b/docs/en_US/backend/template/customization/custom_types.md @@ -49,43 +49,62 @@ class MySQLVectorType(DataType): super().__init__(dialect) self.dim = dim - def _type_params(self) -> tuple: - return (self.dim,) + #: The attributes that make two of these different columns. Read by + #: ``__eq__``, ``__hash__`` and ``repr`` -- declare it, do not override a + #: method to compute it. + PARAMETERS = ("dim",) ``` -**Important**: Do **not** hand-write `__eq__`/`__hash__`. The `DataType` base provides unified value-object semantics: equality compares the logical parameters returned by `_type_params()` plus `dialect_options`; the hash covers type identity and `_type_params()` only. The bound dialect is ignored by both. Override `_type_params()` so the base comparisons see your logical content. +**Important**: Do **not** hand-write `__eq__`/`__hash__`, and do not override a method to compute identity. The `DataType` base provides unified value-object semantics: equality compares the attributes named in the class constant `PARAMETERS`, and the hash covers the type's class plus those same attributes. The bound dialect is ignored by both. Declare `PARAMETERS` so the base comparisons see your logical content — and make sure it names *everything* that distinguishes two instances, because whatever it omits is invisible to `==`. + +One field is deliberately **not** identity: `spelling`. It is how the instance is written, not what it is. The same column introspects as `character varying(30)` whichever word created it, so counting the spelling would make every introspected type unequal to its own declaration. The spelling still reaches the rendered SQL, and still round-trips through `get_params()`. + +There is no bag of "backend-specific options" on a data type. Anything your type needs beyond the concept's own parameters is a **declared field** on the class, named in its `PARAMETERS`. Backend-defined types must also declare a **backend-prefixed** generic `name` (e.g. `mysql_vector`) — the prefix is enforced at class-definition time, keeping dispatch keys isolated per backend. ## Extending a Core Type -To create a backend-specific variant of an existing type: +Deriving from a core type is how a backend says "this is that concept, stored my way", and it is what makes `isinstance(col.data_type, IntegerType)` hold for the backend's own integer column. Inherit the core class **whenever there is one**; sit on `DataType` only when the concept is genuinely backend-exclusive, and then say why in the docstring. + +Inheritance means identity only — "this class *is* that SQL type" — not membership in a family, and the chain stays linear (no multiple inheritance, no diamond edges). + +Often you need no subclass at all. For a signedness variant of an existing concept, use the parameter the concept already has: + +```python +from rhosocial.activerecord.backend.expression.types import IntegerType + +IntegerType(unsigned=True) # UNSIGNED INTEGER — same class, one flag +``` + +The four core integer classes take `unsigned: bool` precisely so that "signed vs unsigned" does not become a class per backend. Width, by contrast, *is* a class (`TinyIntType` … `BigIntType`), because a linear chain cannot hold a (width × signedness) grid. + +If you genuinely need a subclass — the backend's storage differs, not just its spelling: ```python from rhosocial.activerecord.backend.expression.types import IntegerType class MySQLUnsignedIntType(IntegerType): - """MySQL INTEGER UNSIGNED.""" + """MySQL ``INT UNSIGNED``. + + The same concept as ``INTEGER`` with a different range, so it derives from + the core class rather than sitting on ``DataType``. It re-declares + ``PARAMETERS`` so ``unsigned`` still participates in ``==`` and ``hash`` — + inheriting the base's declaration without naming the field would make two + different ranges compare equal. + """ name = "mysql_int_unsigned" - def __init__(self, dialect=None, *, unsigned: bool = True, - dialect_options=None): - super().__init__(dialect, dialect_options=dialect_options) - self.unsigned = unsigned - - def _type_params(self) -> tuple: - return (self.unsigned,) + def __init__(self, dialect=None, *, unsigned: bool = True): + super().__init__(dialect, unsigned=unsigned) - @classmethod - def synonyms(cls) -> set: - """Mark as equivalent to IntegerType for schema comparison.""" - return {'IntegerType'} + PARAMETERS = ("unsigned",) ``` -The `synonyms()` method marks types as structurally equivalent for schema comparison purposes. +There is no `synonyms()` classmethod and no `is_equivalent()` method any more. A synonym of a concept is a *spelling* on the concept's own class, so there is never a second class for `==` to disagree with — see [Types](../expression/types.md) for the spelling mechanism. -Backend-specific exotic parameters can also travel in `dialect_options` (e.g. `{'unsigned': True}`) — a dict consumed by the backend formatters; it participates in equality but not in the hash. +If your concept has several legitimate written forms, extend that class's `SPELLINGS` rather than adding a class, and check the spelling in your formatter: a dialect that does not write `CLOB` should raise, not silently emit something else. The concept's default spelling (the first entry) must always render. ## Registering a Type Formatter diff --git a/docs/en_US/backend/template/type_adapters/README.md b/docs/en_US/backend/template/type_adapters/README.md index 8257c7a53..f3228d84c 100644 --- a/docs/en_US/backend/template/type_adapters/README.md +++ b/docs/en_US/backend/template/type_adapters/README.md @@ -22,7 +22,20 @@ from rhosocial.activerecord.backend.expression.types import ( ) ``` -These core types are **backend-agnostic** — they define the logical type without specifying exact SQL syntax. When you declare a field as `str`, `int`, or `bool` on a model, the framework maps it to the appropriate core DataType. +These core types are **backend-agnostic** — they define the logical type without specifying exact SQL syntax. + +A plain Python annotation is **not** turned into a core `DataType` for you. Declaring a field as `str`, `int` or `bool` says nothing about the column's SQL type; without an explicit `UseSqlType(...)` the collector's `column_data_type()` returns `None`, and it is the later dialect consumer that decides what to do about it. To state a type, say so: + +```python +from typing import Annotated +from rhosocial.activerecord.base import UseSqlType +from rhosocial.activerecord.backend.expression.types import IntegerType + +class Order(ActiveRecord): + quantity: Annotated[int, UseSqlType(IntegerType())] +``` + +See [DDLSource Declarations](../../../modeling/ddl_source.md) for what the collector does and does not decide. ### Layer 2: Backend-Specific DataType Subclasses diff --git a/docs/en_US/modeling/ddl_source.md b/docs/en_US/modeling/ddl_source.md index ff633beeb..f4472dd60 100644 --- a/docs/en_US/modeling/ddl_source.md +++ b/docs/en_US/modeling/ddl_source.md @@ -32,7 +32,7 @@ model class definition Returned values may be `UseSqlType`, `ColumnConstraint`, `IndexDefinition`, `TableConstraint`, or backend-owned expression instances. They are normally unbound while they are being collected. Candidate selection, dialect binding, capability checks, and expression construction belong to an external DDL consumer and the backend dialect. -The current implementation does not infer a `DataType` from a plain Python annotation. Without `UseSqlType`, `column_type()` returns `None`. With `UseSqlType`, it returns the complete marker; ordered candidates are available in `marker.data_types`. +The current implementation does not infer a `DataType` from a plain Python annotation. Without `UseSqlType`, `column_data_type()` returns `None`. With `UseSqlType`, it returns the complete marker; ordered candidates are available in `marker.data_types`. ## How Declarations Enter the Collector @@ -55,7 +55,7 @@ Field declarations use `typing.Annotated`. The collector reads both `Annotated` | Marker | Collected result | Ordering rule | |--------|------------------|---------------| -| `UseSqlType(*types)` | `column_type()` returns the `UseSqlType` marker | Candidates keep declaration order and are deduplicated; only the first marker is used. | +| `UseSqlType(*types)` | `column_data_type()` returns the `UseSqlType` marker | Candidates keep declaration order and are deduplicated; only the first marker is used. | | `UseConstraint(...)` | `column_constraints()` returns `ColumnConstraint` objects | All markers are expanded in declaration order. | | `UseIndex(...)` | `column_indexes()` returns newly built `IndexDefinition` objects | One definition is built per marker, using the physical column name. | | `UseColumnAttributes(...)` | `column_attributes()` returns `ColumnAttribute` objects | Markers are expanded in order; each marker is internally deduplicated. | @@ -106,7 +106,8 @@ The table below describes the default `DDLSourceMixin` implementation. A custom | `field_python_type(field)` | `type` | Reads field metadata and unwraps `Optional[T]` to `T`; unknown fields raise `KeyError`. | | `field_is_optional(field)` | `bool` | True for `Optional[T]` or a default of `None`. | | `column_name(field)` | `str` | Uses `ColumnNameMixin`; returns the physical name for `UseColumn`, otherwise the field name. | -| `column_type(field)` | `Optional[UseSqlType]` | Returns the first `UseSqlType` marker, or `None`; candidate selection does not happen here. | +| `column_data_type(field)` | `Optional[UseSqlType]` | Returns the first `UseSqlType` marker, or `None`; candidate selection does not happen here. | +| `column_type(field)` | `Optional[UseColumnType, class, or class sequence]` | Presents the column-type declaration as written — a `UseColumnType` marker (candidates included), a `ColumnBase` subclass, or a sequence — or `None`; dialect-free, so the backend that selects the class is the field accessor's concern. | | `column_constraints(field)` | `Sequence[ColumnConstraint]` | Starts with explicit constraints, then applies primary-key and nullability rules. | | `column_attributes(field)` | `Sequence[ColumnAttribute]` | Expands markers in order without dialect filtering. | | `column_indexes(field)` | `Sequence[IndexDefinition]` | Builds one definition per `UseIndex` and substitutes the physical column name. | @@ -122,6 +123,10 @@ The table below describes the default `DDLSourceMixin` implementation. A custom | `table_inherits()` | `Optional[List[str]]` | `None` by default; an override is returned unchanged. | | `table_tablespace()` | `Optional[str]` | `None` by default; an override is returned unchanged. | +`column_type()` and `column_data_type()` are **dialect-free** declaration accessors: neither infers nor falls back. Selecting the column class a backend answers happens in the field accessor (`Model.c.`), never in the source. + +Every accessor that takes a field name refuses a name the model does not have with `KeyError`; `None` (or an empty collection) always means "the field exists and declares nothing". The batch accessors (`columns_*`) raise the same way when an explicitly named field is unknown. `column_name()` is a name mapping rather than a declaration reader, so it keeps returning the given name when no `UseColumn` applies. + ### `column_constraints()` composition The collector does not store one final constraint list at class creation time. It composes the list when the method is called: @@ -140,7 +145,7 @@ The collector does not store one final constraint list at class creation time. I These methods are convenience wrappers, not additional DDL source interfaces: - `columns_name()` -- `columns_type()` +- `columns_data_type()` - `columns_constraints()` - `columns_attributes()` - `columns_indexes()` @@ -248,7 +253,7 @@ class Account(ActiveRecord): print(Account.table_name()) print(Account.ddl_field_names()) print(Account.column_name("account_id")) -print(Account.column_type("display_name").data_types) +print(Account.column_data_type("display_name").data_types) print(Account.column_indexes("display_name")) print(Account.column_comment("display_name")) print(Account.table_indexes()) diff --git a/docs/en_US/modeling/ddl_source_examples.md b/docs/en_US/modeling/ddl_source_examples.md index fbd376171..b23b0359d 100644 --- a/docs/en_US/modeling/ddl_source_examples.md +++ b/docs/en_US/modeling/ddl_source_examples.md @@ -68,7 +68,7 @@ PlainAccount.primary_key_columns() PlainAccount.ddl_field_names() # ('id', 'name', 'note') -PlainAccount.column_type("id") +PlainAccount.column_data_type("id") # None PlainAccount.column_options("id") @@ -99,20 +99,20 @@ PlainAccount.column_constraints("note") # [] ``` -The absence of `UseSqlType` means that `column_type()` is `None`. The source still composes the primary-key and non-null constraints for required fields. +The absence of `UseSqlType` means that `column_data_type()` is `None`. The source still composes the primary-key and non-null constraints for required fields. A consumer cannot construct a typed column from `None`: ```python from rhosocial.activerecord.backend.expression.statements import ColumnDefinition -ColumnDefinition(dialect, "id", PlainAccount.column_type("id")) +ColumnDefinition(dialect, "id", PlainAccount.column_data_type("id")) # TypeError: data_type must be a DataType instance, got NoneType ``` The same source-level result applies to every backend: -| Backend | `column_type("name")` | Default table declarations | Consumer responsibility | +| Backend | `column_data_type("name")` | Default table declarations | Consumer responsibility | |---------|------------------------|----------------------------|-------------------------| | SQLite | `None` | `None` / empty sequences | Choose an explicit core type such as `INTEGER` or `TEXT`. | | MySQL | `None` | `None` / empty sequences | MySQL does not invent `INT` or `VARCHAR` for the source. | @@ -169,7 +169,7 @@ The source preserves the declared objects and order: CoreDeclared.column_name("id") # 'record_id' -CoreDeclared.column_type("name").data_types +CoreDeclared.column_data_type("name").data_types # (VarCharType(length=64),) CoreDeclared.column_indexes("name")[0].columns @@ -506,7 +506,7 @@ class ForeignOnly(ActiveRecord): value: Annotated[str, UseSqlType(ForeignType())] ``` -The class definition and `column_type("value")` can succeed. The failure appears only when a consumer binds the candidate to the active dialect and renders it. The following table records the foreign type used in each probe: +The class definition and `column_data_type("value")` can succeed. The failure appears only when a consumer binds the candidate to the active dialect and renders it. The following table records the foreign type used in each probe: | Active dialect | Only declared expression | Collection phase | Render phase | |----------------|---------------------------|------------------|--------------| diff --git a/docs/en_US/modeling/fields.md b/docs/en_US/modeling/fields.md index 1bf7a678e..af2e2e988 100644 --- a/docs/en_US/modeling/fields.md +++ b/docs/en_US/modeling/fields.md @@ -47,7 +47,7 @@ class LegacyUser(ActiveRecord): ## Specifying SQL Column Types (UseSqlType) -`ActiveRecord` does not generate a DDL `DataType` from a plain Python annotation. `DDLSourceMixin.column_type()` returns `None` when `UseSqlType` is absent; use `UseSqlType` when a SQL type must be declared explicitly. See [DDLSource Declarations](ddl_source.md) for the complete collection rules. +`ActiveRecord` does not generate a DDL `DataType` from a plain Python annotation. `DDLSourceMixin.column_data_type()` returns `None` when `UseSqlType` is absent; use `UseSqlType` when a SQL type must be declared explicitly. See [DDLSource Declarations](ddl_source.md) for the complete collection rules. `UseSqlType` accepts one or more `DataType` instances: diff --git a/docs/en_US/querying/active_query.md b/docs/en_US/querying/active_query.md index 2c401813c..f6839e3b6 100644 --- a/docs/en_US/querying/active_query.md +++ b/docs/en_US/querying/active_query.md @@ -239,18 +239,17 @@ window_spec = WindowSpecification( order_by=OrderByClause(Post.backend().dialect, [(Post.c.views, "DESC")]) ) -# Create window function call -rank_col = rank(Post.backend().dialect).as_('rank') -rank_col.window_spec = window_spec +# Create window function call and attach the window specification +rank_col = rank(Post.backend().dialect).over(window_spec).as_('rank') results = Post.query().select(Post.c.title, rank_col).aggregate() ``` * **Notes**: * Window functions should be imported from `rhosocial.activerecord.backend.expression`, not from the old `window` submodule. -* Functions like `rank`, `row_number`, `dense_rank`, etc. return `WindowFunctionCall` objects. +* Functions like `rank`, `row_number`, `dense_rank`, etc. return typed value expressions wrapping a `FunctionCall`. * Window specifications are created using the `WindowSpecification` class, requiring `dialect`, `partition_by`, and `order_by` parameters. -* To set the window specification, assign it directly: `rank_col.window_spec = window_spec`. +* To attach the window specification, use `.over(window_spec)`. Assigning `rank_col.window_spec = window_spec` directly is a silent no-op: the typed wrapper swallows the write while rendering reads the call it holds. ## JoinQueryMixin (Join Query) diff --git a/docs/zh_CN/backend/custom_backend.md b/docs/zh_CN/backend/custom_backend.md index 4d0fc6559..85a7216b3 100644 --- a/docs/zh_CN/backend/custom_backend.md +++ b/docs/zh_CN/backend/custom_backend.md @@ -282,7 +282,7 @@ JSONTableExpression( ### 关注格式化函数 -混入协议后，请验证相应的格式化方法。例如，如果您混入了 `WindowFunctionMixin`，请检查 Mixin/基类中的 `format_window_function_call`。 +混入协议后，请验证相应的格式化方法。例如，如果您混入了 `WindowFunctionMixin`，请检查 Mixin/基类中的 `format_window_specification`；`OVER (...)` 子句本身由所有函数调用共用的 `format_function_call` 组装。 * 如果您的数据库遵循标准 SQL（例如 `OVER (...)`），默认实现即可工作。 * 如果有差异，请覆盖该特定方法。 diff --git a/docs/zh_CN/backend/expression/advanced.md b/docs/zh_CN/backend/expression/advanced.md index 0bfbd1af7..5c4eccf13 100644 --- a/docs/zh_CN/backend/expression/advanced.md +++ b/docs/zh_CN/backend/expression/advanced.md @@ -113,12 +113,13 @@ PostgreSQL dialect 会自动使用 `::` 语法生成更简洁的 SQL。 窗口函数对与当前行相关的表行集执行计算。 -### WindowFunctionCall +### 带 OVER 的 FunctionCall -表示对窗口函数的调用（例如 `ROW_NUMBER() OVER (...)`）。 +窗口函数调用就是携带 `window_spec` 的 `FunctionCall`：用 `.over(...)` +流式附加窗口规范，或在构造时传入 `window_spec=`。 ```python -from rhosocial.activerecord.backend.expression import WindowFunctionCall, WindowSpecification, Column, Literal +from rhosocial.activerecord.backend.expression import FunctionCall, WindowSpecification, Column, Literal from rhosocial.activerecord.backend.expression.query_parts import OrderByClause # 定义窗口规范 @@ -128,13 +129,8 @@ window_spec = WindowSpecification( order_by=OrderByClause(dialect, [(Column(dialect, "salary"), "DESC")]) ) -# 创建窗口函数调用 -window_func = WindowFunctionCall( - dialect, - function_name="ROW_NUMBER", - window_spec=window_spec, - alias="row_num" -) +# 创建窗口函数调用并附加窗口规范 +window_func = FunctionCall(dialect, "ROW_NUMBER").over(window_spec).as_("row_num") sql, params = window_func.to_sql() # sql: 'ROW_NUMBER() OVER (PARTITION BY "department" ORDER BY "salary" DESC) AS "row_num"' @@ -231,16 +227,25 @@ sql, params = intersect_op.to_sql() 用于处理 JSON 数据的表达式。 -### JSONExpression +### JSONDocumentExpression / JSONTextExpression -表示 JSON 路径提取或操作。 +表示 JSON 路径提取。运算符决定用哪个类：`->` 得到文档，是 +`JSONDocumentExpression`；`->>` 得到文本，是 `JSONTextExpression`。 +之所以是两个类而不是一个类加一个拼写参数，是因为两者得到的值是不同的 +种类 —— 文档可以继续向下索引，文本不行。 ```python -from rhosocial.activerecord.backend.expression import JSONExpression, Column +from rhosocial.activerecord.backend.expression import ( + JSONDocumentExpression, + JSONTextExpression, +) col = Column(dialect, "data") -# 从 JSON 路径提取值 -json_extract = JSONExpression(dialect, col, "$.user.name", operation="->>") +# 从 JSON 路径提取值（文本） +json_extract = JSONTextExpression(dialect, col, "$.user.name", operation="->>") + +# 嵌套路径仍然是文档，可以继续往下走 +nested = JSONDocumentExpression(dialect, col, "$.user", operation="->") sql, params = json_extract.to_sql() # sql: '"data"->>?', 或特定方言的等价形式，如 'JSON_EXTRACT("data", ?)' diff --git a/docs/zh_CN/backend/expression/extending.md b/docs/zh_CN/backend/expression/extending.md index eed26b8ae..ac6b385ca 100644 --- a/docs/zh_CN/backend/expression/extending.md +++ b/docs/zh_CN/backend/expression/extending.md @@ -1,6 +1,6 @@ # 扩展指南：实现可序列化表达式 -本文档面向后端开发者，介绍如何为自定义表达式实现序列化能力。 +本文档面向后端开发者，介绍如何让自定义表达式可序列化。 ## 基本要求 @@ -8,15 +8,15 @@ 1. 继承自 `BaseExpression` 2. `__init__` 参数名与属性名对应（使用 `_` 前缀私有属性或同名属性） -3. 使用 `get_params()` 返回可序列化参数 +3. 不要实现 `get_params()`——通用实现是唯一的序列化路径，`__init__` 必须以构造参数收到的名字保存状态 ## get_params() 约定 -默认的 `get_params()` 实现基于 `inspect.signature` 自动推断： +通用 `get_params()` 实现基于 `inspect.signature` 自动推断： - 参数 `foo` → 属性 `self._foo` 或 `self.foo` - `VAR_POSITIONAL (*args)` → 列表 -- `VAR_KEYWORD (**kwargs)` → 跳过（需手动覆盖） +- `VAR_KEYWORD (**kwargs)` → 收集到的额外参数存入与该参数同名的属性上的 dict（如 `self.collation_options`），并合并进 `params` 的顶层，这样重建时会重新展开成关键字参数 ```python class MyExpression(BaseExpression): @@ -27,17 +27,23 @@ class MyExpression(BaseExpression): # 无需手动实现 get_params()，默认实现会自动提取 ``` -### 自定义 get_params() +核心中的 `CollateExpression` 就是 `**kwargs` 的例子：它把 `**collation_options` 收集进 `self.collation_options: dict`，于是 `get_params()` 会把 `binary`、`pad` 等作为顶层参数返回，重建时再把它们当关键字参数传回。 -当默认推断不适用时，重写该方法： +若某个参数按约定无法解析，会跳过并发出警告。这条警告就是诊断信号——它意味着 `__init__` 把状态存在了 `get_params()` 看不到的名字上，而修复永远在 `__init__` 里。 -```python -def get_params(self) -> dict: - params = super().get_params() - # 添加或修改参数 - params["custom_key"] = self._custom_value - return params -``` +### 为什么没有"自定义 get_params()" + +`get_params()` 不是扩展点：重写它是缺陷，不是定制。核心在 `tests/.../dummy2/test_expression_contract.py::test_no_get_params_override` 里无例外地强制这一点——每个已注册的表达式类都必须沿用通用实现。（该测试允许的唯一例外，是做真正的"原始值 ↔ 归一化值"往返改写的 `VAR_POSITIONAL` 类，而核心注册表里没有任何一个属于这种情况。） + +原因是结构性的，不是风格问题。往返是靠"用 `get_params()` 返回的内容去调用构造函数"重建的，所以这两半必须彼此吻合。而重写恰恰是它们开始走偏的地方：这个类发出的键会被构造函数改名、合并或拒绝，`_reconstruct()` 再把由此产生的 `TypeError` 包装成 `ExpressionDeserializationError`，状态就悄悄丢了。各后端包曾各自积累过重写实现，而它们存在的理由全都是同一个：`__init__` 把调用方传进来的东西改了名或合并了——而一旦按收到的名字原样保存，这些重写就全都不再必要。 + +当通用实现的结果不是你想要的时，修复始终在 `__init__` 里，且只有三种形态： + +| 问题 | 修复 | +|---|---| +| 你把调用方传进来的值改了名或合并了 | 按参数本来的名字保存 | +| 构造函数的两种写法含义相同 | 两个槽位都留着；值放在调用方用的那个槽位，另一个留 `None` | +| 该值按原样无法序列化 | 在 `__init__` 里转换，保存转换后的值 | ## 注册机制 @@ -57,22 +63,30 @@ ExpressionRegistry.register(MyExpression) ## 四类特殊情况 +下面这四种情况，就是开发者会去写自定义 `get_params()` 的常见理由。它们没有一个需要重写：每一种都在 `__init__` 里解决。 + ### 1. 方言专属枚举参数 -某些方言有专属枚举值（如 PostgreSQL 的 `IsolationLevel`）： +某些方言有专属枚举值（如 PostgreSQL 的 `IsolationLevel`）。调用方给哪种写法都可以，保存 spec 能承载的那个值： ```python class MyTransactionExpression(BaseExpression): - def __init__(self, dialect, isolation_level: str = "READ COMMITTED"): + def __init__(self, dialect, isolation_level="READ COMMITTED"): super().__init__(dialect) - self._isolation_level = isolation_level # 接受字符串而非枚举 - -# get_params() 返回字符串，对方言无依赖 + # 接受方言的枚举或其字符串；保存归一化后的字符串 + self._isolation_level = ( + isolation_level.value + if isinstance(isolation_level, Enum) + else str(isolation_level) + ) + +# get_params() 返回 {"isolation_level": "SERIALIZABLE"}——字符串，与方言无关 +# 重建时把这个字符串传回同一个接受字符串的构造函数 ``` ### 2. 通过 fluent API 设置的状态 -Fluent API 修改的状态必须同步到 `__init__` 参数： +Fluent API 修改的状态必须同步到 `__init__` 参数——setter 与参数必须读写**同一个**属性，因为 `get_params()` 能看到的只有那个属性： ```python class MyExpression(BaseExpression): @@ -85,73 +99,89 @@ class MyExpression(BaseExpression): return self ``` +如果 setter 在参数自己的属性之外另写一份，那份状态往返时就丢了。 + ### 3. set 类型参数 -`set` 类型无法直接 JSON 序列化，在 `get_params()` 中转为 list： +`set` 不适合承载表达式状态：它没有顺序，而且 codec 会把它编码成一个扁平列表，其中的成员拿不到本应属于它们的嵌套表达式标记，因此装着表达式的 `set` 过不了 JSON 往返。在 `__init__` 里转换、保存转换后的值——通用路径于是发出的正是构造函数能接受的东西： ```python -def get_params(self) -> dict: - params = super().get_params() - params["columns"] = list(self._columns) # set -> list - return params +class ColumnSetExpression(BaseExpression): + def __init__(self, dialect, columns): + super().__init__(dialect) + self._columns = list(columns) # 传进来可以是 set 或任意可迭代对象，保存为 list + +# get_params() 返回 {"columns": [...]}；重建时把这个 list 传回同一个构造函数， +# 它接受 list 和接受 set 一样自然 ``` ### 4. 循环引用 -当前框架不检测循环引用。如有自引用可能，在 `get_params()` 中截断： +框架不检测环，自引用也无法序列化——序列化器会一路递归到 Python 的递归上限。要按**标识**而不是按对象来保存这条链接：参数是 id，对象（如果确实需要）放在构造函数不接收的属性上，`get_params()` 根本不会读它。 ```python -def get_params(self) -> dict: - params = {"id": self._id, "name": self._name} - if self._parent is not None: - params["parent_id"] = self._parent._id # 只存 ID，不存对象 - return params +class TreeNodeExpression(BaseExpression): + def __init__(self, dialect, name, parent_id=None): + super().__init__(dialect) + self._name = name + self._parent_id = parent_id # 标识，而非对象 + # 由树遍历器解析；没有同名参数，因此永不进入序列化 + self._parent = None ``` -## IntrospectionExpression 约定 +如果父节点确实必须随节点一起传递，就把它做成普通的嵌套表达式参数——`{"__expr__": ...}` 正是为此存在的。这样一来，树自然就是有限的。 -`IntrospectionExpression` 子类（如 `TableListExpression`）的 `None` 过滤规则： +## IntrospectionExpression 约定 -- 可选参数为 `None` 时，不应出现在 `params` 中 +`IntrospectionExpression` 子类（如 `TableListExpression`）把构造函数与同名 fluent setter 结合在一起。通用路径的两处机制已经考虑到了这一点： ```python class TableListExpression(IntrospectionExpression): - def get_params(self) -> dict: - params = {} - if self._schema is not None: - params["schema"] = self._schema - # include_views 默认 True，始终包含 - params["include_views"] = self._include_views - return params + def __init__(self, dialect, schema=None, include_views=True, include_system=False, table_type=None): + super().__init__(dialect, schema) + self._include_views = include_views + self._include_system = include_system + self._table_type = table_type + + def include_views(self, value: bool = True): + self._include_views = value # 与读取参数同一个属性 + return self ``` +- **两种写法都存在时，可调用的那个不是状态。** 若某参数同时存在 `self.foo` 与 `self._foo`，且公开属性是个 fluent 方法，则取私有属性的值。 +- **未赋值的可选参数会输出为 `null`，而不是被省略。** 这是安全的：反序列化会把它传回去，构造函数的默认值随之生效。真正不安全的是丢掉一个取值与其默认值不同的参数——那才是往返丢掉的状态。 + ## 错误契约 所有经过 `_reconstruct()` 的路径，`TypeError` 都会被包装为 `ExpressionDeserializationError`。这确保调用方只需捕获一种异常类型。 ## 序列化格式约定（键名保留） -自定义表达式的 `get_params()` 返回值中，**不得**使用以下保留键名，否则反序列化行为未定义： +`get_params()` 返回的**值**在任何深度上都不得包含以下保留键名，否则反序列化行为未定义——反序列化会把它们当作框架标记来读： - `__expr__`：用于标记嵌套表达式 - `__tuple__`：用于标记元组 +- `__value__` / `__vdc__`：用于标记 codec 编码的标量值与 dataclass 值 + +你自己的顶层键来自 `__init__` 的参数名（以及合并进来的 `**kwargs` 额外参数），所以绝不要把参数命名为保留键。对于键不由你控制的不透明载荷，危险在载荷内部：那些键会被原样复制进 spec，给参数换个名字对此毫无帮助。要么在构造时校验，要么把载荷存成文本。 ```python -# 错误示例 - 可能导致数据损坏 +_RESERVED = ("__expr__", "__tuple__", "__value__", "__vdc__") + +# 错误示例 - 含有 "__expr__" 的载荷会被当成嵌套表达式读回来 class RawJsonStorageExpr(BaseExpression): def __init__(self, dialect, data: dict): + super().__init__(dialect) self._data = data - def get_params(self): - return {"data": self._data} # 若 data = {"__expr__": "..."}，round-trip 失败 - -# 正确示例 - 避免使用保留键名 +# 正确示例 - 载荷在进入 spec 之前就被拒绝 class SafeJsonStorageExpr(BaseExpression): def __init__(self, dialect, json_data: dict): + super().__init__(dialect) + for key in json_data: + if key in _RESERVED: + raise ValueError(f"{key!r} is a reserved serialization key") self._json_data = json_data - - def get_params(self): - return {"json_data": self._json_data} # 不使用 __expr__ 等保留键 ``` ## 相关文档 diff --git a/docs/zh_CN/backend/expression/format-reference.md b/docs/zh_CN/backend/expression/format-reference.md index 58cef6b1b..b54aed316 100644 --- a/docs/zh_CN/backend/expression/format-reference.md +++ b/docs/zh_CN/backend/expression/format-reference.md @@ -80,7 +80,7 @@ | `tuple` | object | 使用 `__tuple__` 标记 | | `BaseExpression` | object | 使用 `__expr__` 标记 | | `set` | - | 不支持，需转为 list | -| 其他自定义对象 | - | 需在 `get_params()` 中处理 | +| 其他自定义对象 | object | 通过已注册的 `__value__` codec 编码，或在 `__init__` 中转换 | ## 序列化流程 diff --git a/docs/zh_CN/backend/expression/functions.md b/docs/zh_CN/backend/expression/functions.md index ea69b35bc..e453e4daf 100644 --- a/docs/zh_CN/backend/expression/functions.md +++ b/docs/zh_CN/backend/expression/functions.md @@ -4,21 +4,29 @@ ## 概述 -`functions` 模块提供了简化 SQL 函数调用创建的工厂函数。您可以使用这些助手函数来代替手动实例化 `FunctionCall` 或 `AggregateFunctionCall` 对象，它们处理类型转换并提供更符合 Python 习惯的接口。 +`functions` 模块提供了简化 SQL 函数调用创建的工厂函数。您可以使用这些助手函数来代替手动实例化 `FunctionCall` 对象，它们处理类型转换并提供更符合 Python 习惯的接口。 ## 聚合函数 (Aggregate Functions) -### AggregateFunctionCall +### FunctionCall（聚合用法） -表示 SQL 聚合函数调用。支持 `FILTER` (WHERE) 子句。 +聚合调用就是 `FunctionCall`；聚合工厂会在构造时设置其 `is_aggregate` 事实。它支持 `FILTER` (WHERE) 子句和 `OVER (...)` 窗口子句。 ```python -class AggregateFunctionCall(mixins.AliasableMixin, mixins.ArithmeticMixin, mixins.ComparisonMixin, bases.SQLValueExpression): - def __init__(self, dialect: "SQLDialectBase", func_name: str, *args, is_distinct: bool = False, alias: Optional[str] = None): ... +class FunctionCall(mixins.AliasableMixin, mixins.ArithmeticMixin, mixins.ComparisonMixin, mixins.StringPatternPredicateMixin, mixins.TypeCastingMixin, mixins.ResultTypeMixin, bases.SQLValueExpression): + def __init__(self, dialect: "SQLDialectBase", func_name: str, *args, + is_distinct: bool = False, alias: Optional[str] = None, + niladic: bool = False, filter_predicate: "SQLPredicate" = None, + window_spec: Union["WindowSpecification", str] = None, + is_aggregate: bool = False): ... - def filter(self, predicate: "SQLPredicate") -> 'AggregateFunctionCall': + def filter(self, predicate: "SQLPredicate") -> 'FunctionCall': """应用 FILTER (WHERE ...) 子句到聚合表达式。""" ... + + def over(self, window_spec: Union["WindowSpecification", str]) -> 'FunctionCall': + """为调用附加 OVER (...) 子句。""" + ... ``` **示例:** @@ -47,7 +55,7 @@ sql, params = high_value_sum.to_sql() 创建 `COUNT` 聚合函数调用。 ```python -def count(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"] = "*", is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def count(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"] = "*", is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **使用规则:** @@ -75,7 +83,7 @@ sql, params = c2.to_sql() 创建 `SUM` 聚合函数调用。注意尾随下划线以避免与 Python 内置的 `sum` 冲突。 ```python -def sum_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def sum_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **示例:** @@ -91,7 +99,7 @@ sql, params = s.to_sql() 创建 `AVG` 聚合函数调用。 ```python -def avg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def avg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **示例:** @@ -107,7 +115,7 @@ sql, params = a.to_sql() 创建 `MIN` 聚合函数调用。注意尾随下划线。 ```python -def min_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def min_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **示例:** @@ -123,7 +131,7 @@ sql, params = m.to_sql() 创建 `MAX` 聚合函数调用。注意尾随下划线。 ```python -def max_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def max_(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **示例:** @@ -713,7 +721,7 @@ sql, params = l.to_sql() 创建 `ROW_NUMBER` 窗口函数调用。 ```python -def row_number(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... +def row_number(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "core.FunctionCall": ... ``` **示例:** @@ -729,8 +737,8 @@ sql, params = r.to_sql() 创建 `RANK` 和 `DENSE_RANK` 窗口函数调用。 ```python -def rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... -def dense_rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... +def rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "core.FunctionCall": ... +def dense_rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ### lag, lead @@ -738,8 +746,8 @@ def dense_rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "advan 创建 `LAG` 和 `LEAD` 窗口函数调用。 ```python -def lag(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], offset: Optional[int] = 1, default: Optional[Union[str, "bases.BaseExpression"]] = None, alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... -def lead(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], offset: Optional[int] = 1, default: Optional[Union[str, "bases.BaseExpression"]] = None, alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... +def lag(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], offset: Optional[int] = 1, default: Optional[Union[str, "bases.BaseExpression"]] = None, alias: Optional[str] = None) -> "core.FunctionCall": ... +def lead(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], offset: Optional[int] = 1, default: Optional[Union[str, "bases.BaseExpression"]] = None, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ### first_value, last_value, nth_value @@ -747,9 +755,9 @@ def lead(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], of 创建值窗口函数调用。 ```python -def first_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... -def last_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... -def nth_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], n: int, alias: Optional[str] = None) -> "advanced_functions.WindowFunctionCall": ... +def first_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "core.FunctionCall": ... +def last_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], alias: Optional[str] = None) -> "core.FunctionCall": ... +def nth_value(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], n: int, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ## JSON 函数 (JSON Functions) @@ -791,8 +799,8 @@ def json_array_elements(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseE 创建 JSON 聚合函数调用。 ```python -def json_objectagg(dialect: "SQLDialectBase", key_expr: Union[str, "bases.BaseExpression"], value_expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... -def json_arrayagg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def json_objectagg(dialect: "SQLDialectBase", key_expr: Union[str, "bases.BaseExpression"], value_expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... +def json_arrayagg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ## 数组函数 (Array Functions) @@ -802,7 +810,7 @@ def json_arrayagg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpress 创建 `ARRAY_AGG` 聚合函数调用。 ```python -def array_agg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "aggregates.AggregateFunctionCall": ... +def array_agg(dialect: "SQLDialectBase", expr: Union[str, "bases.BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None) -> "core.FunctionCall": ... ``` ### unnest diff --git a/docs/zh_CN/backend/expression/types.md b/docs/zh_CN/backend/expression/types.md index 06aab4461..5908b8269 100644 --- a/docs/zh_CN/backend/expression/types.md +++ b/docs/zh_CN/backend/expression/types.md @@ -54,7 +54,7 @@ class Product(ActiveRecord): ## 值对象语义 -`DataType` 实例是**值对象**：同一类的两个实例只要逻辑参数相同就**相等且哈希相同**，与是否携带方言引用无关。相等性比较类型的逻辑参数（`_type_params()`）加上 `dialect_options`；哈希只覆盖类型标识与类型参数。绑定的方言对二者都不产生影响——绑定（或重新绑定）方言绝不会改变 `==` 与 `hash` 的结果。 +`DataType` 实例是**值对象**：同一类的两个实例只要逻辑参数相同就**相等且哈希相同**，与是否携带方言引用无关。相等性比较类型**声明过的身份**——即类常量 `PARAMETERS` 里列出的那些属性；哈希覆盖类型的类本身加上同一组属性。绑定的方言对二者都不产生影响——绑定（或重新绑定）方言绝不会改变 `==` 与 `hash` 的结果。 ```python a = IntegerType() @@ -63,23 +63,56 @@ assert a == b # 值对象：相等（忽略方言） assert hash(a) == hash(b) ``` -`dialect_options` 是随类型实例携带、由后端格式化器消费的**后端专属特殊参数**字典（如 `{'unsigned': True}`、字符集、长度语义等）。它参与**相等性**比较，但刻意**不参与**哈希——可变的选项映射因此不会破坏哈希。 +数据类型的**类上并不存在**所谓的"后端专属选项字典"。后端在该概念自身参数之外需要的一切，都是类上**声明过的字段**——`CharType.length`、`DecimalType.precision`/`scale`、`EnumType.values`、`ArrayType.element_type`/`dimensions`，以及四个整数类上的 `unsigned: bool`——它们都列在该类的 `PARAMETERS` 里，因而同时参与 `==` 与 `hash`。 + +## 拼写 (Spellings) + +有些概念存在不止一种合法写法。这些是**同一个类的拼写**，不是各自的类：该类带一个封闭的 `SPELLINGS` 元组与 `spelling` 关键字参数，其中**第一项**是默认值。 + +```python +IntegerType() # 拼写 "integer" +IntegerType(spelling="int") # 同一个类，另一个词 +assert IntegerType() != IntegerType(spelling="int") # 两种不同的声明 +``` + +为什么是一个类而不是两个：`INT` 与 `INTEGER` 是同一个类型，所以需要判断"这是不是整数列"的代码不该去枚举拼写，schema diff 也不该把两者报成差异。 + +**为什么拼写不参与 `==`。** 看似站得住的说法是：拼写属于当初声明的内容，所以它有差别就该报出来。但 schema diff 比较的**不是两份 DDL 脚本**，而是**数据库现在报什么** 对 **当初声明了什么**；而无论你当初写的是哪个词，数据库都只报它自己那一个词。PostgreSQL 对每一个 `varchar(30)` 列都报 `character varying(30)`，SQL Server 对声明为 `NUMERIC` 的列也报 `DECIMAL`。把拼写算进身份，就会在**唯一必须判对的那次比较**上，为每一个这类列报出一个根本没发生过的变更。 + +拼写的差异并没有丢：它仍然进渲染 SQL——差别真正存在且看得见的地方就是那里： + +```python +IntegerType() # 渲染为 INTEGER +IntegerType(spelling="int") # 渲染为 INT +``` + +它也仍然通过 `get_params()` 完成序列化往返，因为序列化问的是另一个问题——不是"这个值是什么"，而是"重建这个对象需要什么"——答案是构造签名。`get_params()` 是所有表达式唯一的序列化路径，任何类都不得覆写它。 + +某个**具体后端**接受哪些拼写是后端自己的事，并在后端的 formatter 里检查：不写 `CLOB` 的方言会抛错，而不是把调用方要求的 `CLOB` 悄悄改写成 `TEXT`。默认拼写始终可渲染——后端可以把它归一化成自己的写法，但绝不拒绝它。 ## 通用类型 (Core Types) -通用类型定义在 `rhosocial.activerecord.backend.expression.types`，覆盖绝大多数数据库共有的 SQL 类型： - -| 分类 | 类型类 | -|------|--------| -| 整数 | `TinyIntType`、`SmallIntType`、`IntType`、`IntegerType`、`BigIntType` | -| 数值 | `FloatType`、`RealType`、`DoubleType`、`DecimalType` | -| 字符串 | `CharType`、`VarCharType`、`TextType` | -| 布尔 | `BooleanType` | -| 二进制 | `BlobType`、`BinaryType`、`VarBinaryType` | -| 枚举 | `EnumType`（values 必填） | -| 日期时间 | `DateType`、`TimeType`、`TimeTzType`、`DateTimeType`、`TimestampType`、`TimestampTzType`、`IntervalType` | -| JSON | `JsonType`、`JsonBType` | -| 网络 | `InetType`、`CidrType`、`MacAddrType` | +通用类型定义在 `rhosocial.activerecord.backend.expression.types`，覆盖绝大多数数据库共有的 SQL 类型。有多种拼写的概念列出拼写；只有一种拼写的概念**根本没有** `spelling` 参数。 + +| 分类 | 类型类 | 拼写 | +|------|--------|------| +| 整数 | `TinyIntType`、`SmallIntType`、`IntegerType`、`BigIntType` | `tinyint`/`int1`、`smallint`/`int2`、`integer`/`int`、`bigint`/`int8` | +| 数值 | `FloatType`、`RealType`、`DoubleType`、`DecimalType` | `double`/`double precision`、—、—、`decimal`/`numeric`/`dec` | +| 字符串 | `CharType`、`VarCharType`、`TextType` | `char`/`character`、`varchar`/`character varying`、`text`/`clob` | +| 布尔 | `BooleanType` | `boolean`/`bool` | +| 二进制 | `BlobType`、`BinaryType`、`VarBinaryType` | `blob`/`bytea`、—、— | +| 枚举 | `EnumType`（values 必填） | — | +| 日期时间 | `DateType`、`TimeType`、`TimeTzType`、`DateTimeType`、`TimestampType`、`TimestampTzType`、`IntervalType` | — | +| JSON | `JsonType`、`JsonBType`、`XmlType` | — | +| UUID | `UUIDType` | — | +| 数组 | `ArrayType` | — | +| 自定义 | `CustomType` | — | + +`TinyIntType`、`SmallIntType`、`IntegerType`、`BigIntType` 各自接受 `unsigned: bool`。有符号与无符号是**同一个类**——范围由参数携带——原因有二：线性的继承链装不下（宽度 × 符号性）这张网格；而且没有无符号整数的后端会选择加宽，而不是凭空造一个类。 + +`RealType`、`DoubleType`、`FloatType` 刻意是三个类：它们的取值范围与存储都不同，schema diff 必须看出这个差别；`DateTimeType` 与 `TimestampType` 同理。`JsonType` 与 `XmlType` 分开，是因为 SQL/JSON 与 SQL/XML 的操作集不同、标准不同，实现了其中一个的后端并不都实现另一个。 + +通用类型可以不带方言构造（延迟绑定），但绑定之前无法渲染。 | UUID | `UUIDType` | | 数组 | `ArrayType` | | 自定义 | `CustomType` | @@ -92,11 +125,13 @@ assert hash(a) == hash(b) | 后端 | 示例 | |------|------| -| SQLite | `SQLiteIntegerType(IntegerType)`、`SQLiteTextType(TextType)`、`SQLiteBlobType(BlobType)` | -| MySQL | `MySQLIntType(IntegerType)`、`MySQLTinyIntType(TinyIntType)`、`MySQLEnumType(DataType)`、`MySQLSetType(DataType)`、`MySQLGeometryType(DataType)` | -| PostgreSQL | `PostgresSerialType(DataType)`、`PostgresUUIDType(DataType)`、`PostgresTSVectorType(DataType)`、`PostgresJsonPathType(DataType)` | +| SQLite | `SQLiteIntegerType(IntegerType)`、`SQLiteTextType(TextType)`、`SQLiteBlobType(BlobType)`、`SQLiteNumericType(DataType)` | +| MySQL | `MySQLIntType(IntegerType)`、`MySQLTinyIntType(TinyIntType)`、`MySQLEnumType(EnumType)`、`MySQLSetType(DataType)`、`MySQLGeometryType(DataType)` | +| PostgreSQL | `PostgresSerialType(IntegerType)`、`PostgresUUIDType(UUIDType)`、`PostgresXMLType(XmlType)`、`PostgresTSVectorType(DataType)`、`PostgresJsonPathType(DataType)` | + +只要存在对应的通用概念，后端类型就**继承该概念的核心类型**——正是这一点让 `isinstance(col.data_type, IntegerType)` 对 PostgreSQL 的 `SERIAL` 列为真，而不必让每个调用方都记住各后端的私有类名。只有当概念确实是后端专属时才直接继承 `DataType`，此时 docstring 必须写清**为什么**没有对应的核心概念。 -后端特定类型通常继承对应的通用类型，仅当该类型是后端独有时（如 MySQL `ENUM`、PostgreSQL `SERIAL`）才直接继承 `DataType`。 +继承表达的是**同一性**——"这个类**就是**那个 SQL 类型"。它不用于把类型归入族系：SQL 的类型*分类*（数值、字符串、日期时间）是归属关系而非子类型关系，本框架没有任何地方会问"这是不是数值类型"。继承链是线性的：没有多继承，没有菱形边。 每个后端定义的类型都声明**带命名空间前缀的通用类型名**——以后端标识作为前缀（如 `SQLiteIntegerType.name == "sqlite_integer"`）。该前缀在类定义时（`__init_subclass__`）被强制校验：定义在核心 types 包之外、名称缺少后端前缀的类型会被直接拒绝，从而保证不同后端的分发键互不冲突。 @@ -154,7 +189,7 @@ for name, dt_cls in dialect.supports_data_types().items(): ### 与模型字段的集成 -普通 Python 注解不会由 `DDLSourceMixin` 自动转换为 `DataType`。没有 `UseSqlType` 时，`column_type()` 返回 `None`。显式声明使用 `UseSqlType`，它会按声明顺序保留候选： +普通 Python 注解不会由 `DDLSourceMixin` 自动转换为 `DataType`。没有 `UseSqlType` 时，`column_data_type()` 返回 `None`。显式声明使用 `UseSqlType`，它会按声明顺序保留候选： ```python from typing import Annotated @@ -172,14 +207,28 @@ class Product(ActiveRecord): 方言实现 `parse_type(raw)`（`DataTypeSupport` 协议）时，可将数据库返回的原始类型字符串解析回 `DataType` 对象，用于 schema 内省与比对。未实现该接口的方言回退为 `CustomType(raw=raw)`。旧名 `DDLTypeSupport` / `DDLTypeMixin` 仅作为对应新名的 deprecated 兼容别名保留。 -## 等价性与同义词 +`parse_type` 的结果必须是**规范**的，其两半都由 `tests/.../dummy2/test_type_spelling_parse.py` 强制： + +- **覆盖** —— 核心 `SPELLINGS` 中的每一个拼写都必须解析成某个类型。`CustomType` 只对框架根本没有概念的名字才是诚实答案；若用在 `INT1`、`CHARACTER`、`DEC`、`BOOL` 上，就会把框架自己声明的类型报成厂商类型，并把原文写回 DDL。 +- **一个概念进、一个类出** —— 同一概念的所有拼写解析到同一个类，且 `character varying`（变长）绝不解析到定长的 `CharType`。每个同义词一个类正是 `spelling` 参数要消除的东西，而把两者混为一谈的解析器会报出并不存在的 schema 变更。 + +解析成哪个类由方言决定，而不是由拼写决定：存储层无法区分两个概念的后端，可以用代表该共享存储的类作答。core 内的例子就是 SQLite —— `TINYINT` 与 `BIGINT` 同属 INTEGER affinity 这一格，把它们区分开来反而会报出数据库本身并不做的区分。 + +## 比较两个声明 -`synonyms()` 与 `is_equivalent()` 仅用于**方言内**的 schema 比较归一化（例如 SQLite 的亲和性折叠），**绝不**注册跨方言等价关系——渲染保持严格忠实，方言差异必须显式存在。 +`==` 就是全部。两份声明是同一个类型，当且仅当它们是同一个类且逻辑内容相同 —— 这正是值对象的 `==` 已经表达的含义。 ```python -# 仅在同一后端的 schema 比对场景使用 -if type_a.is_equivalent(type_b): - ... +if old_type != new_type: + ... # schema 确实变了 +``` + +不存在更宽松的"它们等价吗"这个问题，而且这是刻意的。原来的 `synonyms()` / `is_equivalent()` 一对机制存在的目的，是为**同义词类**兜底；而同义词现在由 `spelling` 参数表达，两个拼写就是同一个类，于是等价表已经没有工作可做了。在 9 个方言 × 11 组同义词（共 99 次比较）上实测，`is_equivalent()` 与 `==` 从未出现分歧 —— 它是一个不再承担任何职责的机制。 + +`==` 确实回答不了的一个问题是"这个数组列存的东西和那个是不是同一种"，而这个答案**应当**忽略数组有几个维度。那是另一个问题，有它自己的名字：`is_element_type_equivalent`。 + +```python +two_d.is_element_type_equivalent(one_d) # True —— 两者存的都是整数 ``` ## 相关文档 diff --git a/docs/zh_CN/modeling/ddl_source.md b/docs/zh_CN/modeling/ddl_source.md index 742560580..62e5d0105 100644 --- a/docs/zh_CN/modeling/ddl_source.md +++ b/docs/zh_CN/modeling/ddl_source.md @@ -32,7 +32,7 @@ assert isinstance(User, DDLSource) `DDLSourceMixin` 的返回值可能是 `UseSqlType`、`ColumnConstraint`、`IndexDefinition`、`TableConstraint` 或后端自己的表达式类实例。它们在收集阶段通常不绑定方言；后续如何选择候选类型、绑定方言、检查能力并构造可渲染表达式，属于外部 DDL 消费者和后端方言的职责。 -当前实现不会根据普通 Python 类型自动生成 `DataType`。没有 `UseSqlType` 时，`column_type()` 返回 `None`；有 `UseSqlType` 时，它返回完整的 `UseSqlType` 标记，候选类型位于 `marker.data_types` 中，声明顺序保持不变。 +当前实现不会根据普通 Python 类型自动生成 `DataType`。没有 `UseSqlType` 时，`column_data_type()` 返回 `None`；有 `UseSqlType` 时，它返回完整的 `UseSqlType` 标记，候选类型位于 `marker.data_types` 中，声明顺序保持不变。 ## 声明如何进入收集器 @@ -55,7 +55,7 @@ assert isinstance(User, DDLSource) | 标记 | 收集结果 | 顺序规则 | |------|----------|----------| -| `UseSqlType(*types)` | `column_type()` 返回 `UseSqlType` 标记 | 标记内部候选类型按声明顺序保存并去重；多个标记只取第一个。 | +| `UseSqlType(*types)` | `column_data_type()` 返回 `UseSqlType` 标记 | 标记内部候选类型按声明顺序保存并去重；多个标记只取第一个。 | | `UseConstraint(...)` | `column_constraints()` 返回 `ColumnConstraint` 序列 | 所有标记按声明顺序展开。 | | `UseIndex(...)` | `column_indexes()` 返回新建的 `IndexDefinition` 序列 | 每个标记生成一个定义，并把 Python 字段名换成物理列名。 | | `UseColumnAttributes(...)` | `column_attributes()` 返回 `ColumnAttribute` 序列 | 标记按声明顺序展开；单个标记内部先去重。 | @@ -106,7 +106,8 @@ class Report(ActiveRecord): | `field_python_type(field)` | `type` | 读取字段元数据；`Optional[T]` 解包为 `T`。未知字段抛出 `KeyError`。 | | `field_is_optional(field)` | `bool` | `Optional[T]` 或默认值为 `None` 时为 `True`。 | | `column_name(field)` | `str` | 使用 `ColumnNameMixin`；有 `UseColumn` 时返回物理列名，否则返回字段名。 | -| `column_type(field)` | `Optional[UseSqlType]` | 返回第一个 `UseSqlType` 标记；没有标记时为 `None`。不在此处选择候选类型。 | +| `column_data_type(field)` | `Optional[UseSqlType]` | 返回第一个 `UseSqlType` 标记；没有标记时为 `None`。不在此处选择候选类型。 | +| `column_type(field)` | `Optional[UseColumnType、列类或其序列]` | 原样呈现列类型声明：`UseColumnType` 标记（含候选）、单个列类或类序列；未声明为 `None`；**方言无关**，选型由字段代理完成。 | | `column_constraints(field)` | `Sequence[ColumnConstraint]` | 先放显式约束，再应用主键和非空规则。 | | `column_attributes(field)` | `Sequence[ColumnAttribute]` | 按标记顺序展开属性；不做方言筛选。 | | `column_indexes(field)` | `Sequence[IndexDefinition]` | 为每个 `UseIndex` 建立定义，并使用物理列名。 | @@ -122,6 +123,10 @@ class Report(ActiveRecord): | `table_inherits()` | `Optional[List[str]]` | 默认 `None`；覆盖方法的结果原样返回。 | | `table_tablespace()` | `Optional[str]` | 默认 `None`；覆盖方法的结果原样返回。 | +`column_type()` 与 `column_data_type()` 都是**方言无关**的声明访问器：不做推断、不回退。后端所答的列类选型发生在字段代理（`Model.c.`），不在 source 中。 + +所有接受字段名的访问器，对模型中不存在的字段一律以 `KeyError` 拒绝；`None`（或空集合）始终表示“字段存在、但未声明相应内容”。批量访问器（`columns_*`）在显式传入未知字段时同样报错。`column_name()` 是名字映射而非声明读取器，在没有 `UseColumn` 时仍返回传入的名字。 + ### `column_constraints()` 的组合规则 收集器不是在模型类创建时预先写入一个完整约束列表，而是在读取时组合结果： @@ -140,7 +145,7 @@ class Report(ActiveRecord): 以下方法不是独立的 DDL source 接口，而是对模型字段的便捷包装： - `columns_name()` -- `columns_type()` +- `columns_data_type()` - `columns_constraints()` - `columns_attributes()` - `columns_indexes()` @@ -248,7 +253,7 @@ class Account(ActiveRecord): print(Account.table_name()) print(Account.ddl_field_names()) print(Account.column_name("account_id")) -print(Account.column_type("display_name").data_types) +print(Account.column_data_type("display_name").data_types) print(Account.column_indexes("display_name")) print(Account.column_comment("display_name")) print(Account.table_indexes()) diff --git a/docs/zh_CN/modeling/ddl_source_examples.md b/docs/zh_CN/modeling/ddl_source_examples.md index e65b89bc0..e0dfe04ce 100644 --- a/docs/zh_CN/modeling/ddl_source_examples.md +++ b/docs/zh_CN/modeling/ddl_source_examples.md @@ -70,7 +70,7 @@ PlainAccount.primary_key_columns() PlainAccount.ddl_field_names() # ('id', 'name', 'note') -PlainAccount.column_type("id") +PlainAccount.column_data_type("id") # None PlainAccount.column_options("id") @@ -101,14 +101,14 @@ PlainAccount.column_constraints("note") # [] ``` -这里没有 `UseSqlType`，所以 `column_type()` 是 `None`。`id` 和必填的 `name` 仍然会得到自动组合的主键/非空约束；Optional 字段 `note` 不会自动得到 `NOT_NULL`。 +这里没有 `UseSqlType`，所以 `column_data_type()` 是 `None`。`id` 和必填的 `name` 仍然会得到自动组合的主键/非空约束；Optional 字段 `note` 不会自动得到 `NOT_NULL`。 如果消费者在没有类型的情况下直接构造列定义： ```python from rhosocial.activerecord.backend.expression.statements import ColumnDefinition -ColumnDefinition(dialect, "id", PlainAccount.column_type("id")) +ColumnDefinition(dialect, "id", PlainAccount.column_data_type("id")) # TypeError: data_type must be a DataType instance, got NoneType ``` @@ -116,7 +116,7 @@ ColumnDefinition(dialect, "id", PlainAccount.column_type("id")) ### 各后端的默认结果 -| 后端 | `column_type("name")` | `table_options()` | 消费者必须注意 | +| 后端 | `column_data_type("name")` | `table_options()` | 消费者必须注意 | |------|------------------------|-------------------|----------------| | SQLite | `None` | `None` | 只能由后续消费者决定 `INTEGER`、`TEXT` 等核心类型。 | | MySQL | `None` | `None` | MySQL 不会替 source 自动补 `INT` 或 `VARCHAR`。 | @@ -173,7 +173,7 @@ class CoreDeclared(ActiveRecord): CoreDeclared.column_name("id") # 'record_id' -CoreDeclared.column_type("name").data_types +CoreDeclared.column_data_type("name").data_types # (VarCharType(length=64),) CoreDeclared.column_indexes("name")[0].columns @@ -510,7 +510,7 @@ class ForeignOnly(ActiveRecord): value: Annotated[str, UseSqlType(ForeignType())] ``` -类定义和 `column_type("value")` 都可以成功；只有消费者把候选绑定到当前方言并渲染时才失败。下面的 `ForeignType` 和错误摘要是各后端实测结果： +类定义和 `column_data_type("value")` 都可以成功；只有消费者把候选绑定到当前方言并渲染时才失败。下面的 `ForeignType` 和错误摘要是各后端实测结果： | 当前方言 | 声明的唯一表达式 | 收集阶段 | 渲染阶段 | |----------|------------------|----------|----------| diff --git a/docs/zh_CN/modeling/fields.md b/docs/zh_CN/modeling/fields.md index 9b67a5007..ba2f8ce1c 100644 --- a/docs/zh_CN/modeling/fields.md +++ b/docs/zh_CN/modeling/fields.md @@ -47,7 +47,7 @@ class LegacyUser(ActiveRecord): ## 指定 SQL 列类型 (UseSqlType) -`ActiveRecord` 不会因为 Python 字段类型而自动生成 DDL `DataType`。`DDLSourceMixin.column_type()` 在没有 `UseSqlType` 时返回 `None`；需要声明 SQL 类型时，请显式使用 `UseSqlType`。完整的收集规则见 [DDLSource 声明收集](ddl_source.md)。 +`ActiveRecord` 不会因为 Python 字段类型而自动生成 DDL `DataType`。`DDLSourceMixin.column_data_type()` 在没有 `UseSqlType` 时返回 `None`；需要声明 SQL 类型时，请显式使用 `UseSqlType`。完整的收集规则见 [DDLSource 声明收集](ddl_source.md)。 `UseSqlType` 接受一个或多个 `DataType` 实例： diff --git a/docs/zh_CN/querying/active_query.md b/docs/zh_CN/querying/active_query.md index 93ade8e47..6050a04c7 100644 --- a/docs/zh_CN/querying/active_query.md +++ b/docs/zh_CN/querying/active_query.md @@ -239,18 +239,17 @@ window_spec = WindowSpecification( order_by=OrderByClause(Post.backend().dialect, [(Post.c.views, "DESC")]) ) -# 创建窗口函数调用 -rank_col = rank(Post.backend().dialect).as_('rank') -rank_col.window_spec = window_spec +# 创建窗口函数调用并附加窗口规范 +rank_col = rank(Post.backend().dialect).over(window_spec).as_('rank') results = Post.query().select(Post.c.title, rank_col).aggregate() ``` * **注意事项**： * 窗口函数需要从 `rhosocial.activerecord.backend.expression` 导入，而不是旧的 `window` 子模块。 -* `rank`、`row_number`、`dense_rank` 等函数返回 `WindowFunctionCall` 对象。 +* `rank`、`row_number`、`dense_rank` 等函数返回包装了 `FunctionCall` 的带类型值表达式。 * 窗口规范通过 `WindowSpecification` 类创建，需要传入 `dialect`、`partition_by` 和 `order_by` 参数。 -* 设置窗口规范的方法是直接赋值：`rank_col.window_spec = window_spec`。 +* 附加窗口规范请使用 `.over(window_spec)`。直接赋值 `rank_col.window_spec = window_spec` 是静默无效的：带类型的包装器会吞掉这次写入，而渲染读取的是它持有的调用节点。 ## JoinQueryMixin (连接查询) diff --git a/pyproject.toml b/pyproject.toml index 358312f42..3cfade9fa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -62,6 +62,14 @@ dependencies = [ "pydantic>=2.12.0; python_version >= '3.9'", "pydantic-core>=2.41.0; python_version >= '3.9'", + # Python 3.13, including the free-threaded 3.13t build. The python_version + # marker distinguishes release lines, not GIL configuration, so this pins + # both 3.13 builds. pydantic-core has no cp313t wheel after 2.41.4, and the + # newer sdists cannot build there (PyO3 0.29 refuses the free-threaded + # build of CPython < 3.14); 2.12.2 is the last pydantic paired with 2.41.4. + "pydantic==2.12.2; python_version == '3.13'", + "pydantic-core==2.41.4; python_version == '3.13'", + # Type extension utilities # Provides additional typing features for older Python versions "typing-extensions>=4.12.0; python_version < '3.9'", @@ -209,6 +217,13 @@ Issues = "https://github.com/rhosocial/python-activerecord/issues" where = ["src"] namespaces = true +[tool.setuptools.package-data] +# PEP 561 marker. Without this file shipped, a type checker treats the +# installed package as untyped and skips it entirely -- so the annotations +# would be invisible to every consumer even though they are all present. +# Inline types, not stub files: the annotations live in the .py files. +rhosocial = ["py.typed"] + # Build configuration @@ -339,7 +354,11 @@ select = ["E", "F", "B"] ignore = ["B024"] # Abstract base classes without abstract methods are intentional [tool.mypy] -python_version = "3.8" +# The oldest version this mypy can check. It refuses anything below 3.9, so +# the 3.8 floor declared in classifiers and in the pydantic pins is no longer +# machine-checked -- the two have drifted apart and this records it rather than +# leaving a config that fails to load and looks like it ran. +python_version = "3.10" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true diff --git a/requirements.txt b/requirements.txt index 12c59f89d..474f2b40b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,4 +12,13 @@ pydantic>=2.12.0 # No upper limit on minor versions as long as major version remains 2.x # This includes Python 3.14 and any future Python versions pydantic-core>=2.41.0 + +# Python 3.13, including the free-threaded 3.13t build: the python_version +# marker distinguishes release lines, not GIL configuration, so this pins +# both 3.13 builds. pydantic-core stopped shipping cp313t wheels after +# 2.41.4, and the newer sdists cannot compile there (PyO3 0.29 refuses the +# free-threaded build of CPython < 3.14); 2.12.2 is the last pydantic whose +# core (2.41.4) has a cp313t wheel. +pydantic==2.12.2; python_version == "3.13" +pydantic-core==2.41.4; python_version == "3.13" typing-extensions \ No newline at end of file diff --git a/src/rhosocial/activerecord/backend/README.md b/src/rhosocial/activerecord/backend/README.md index e9efeba22..6cf2f1e5c 100644 --- a/src/rhosocial/activerecord/backend/README.md +++ b/src/rhosocial/activerecord/backend/README.md @@ -64,7 +64,6 @@ backend/ │ ├── operators.py # Operator expressions │ ├── core.py # Core expressions (Column, FunctionCall, etc.) │ ├── predicates.py # Predicate expressions -│ ├── aggregates.py # Aggregate functions │ ├── advanced_functions.py # Advanced functions (window, JSON, array, etc.) │ ├── functions.py # Function factories │ ├── query_parts.py # Query components @@ -277,7 +276,7 @@ SQL expression building blocks, following the Expression-Dialect separation patt from rhosocial.activerecord.backend.expression import ( Column, Literal, FunctionCall, QueryExpression, InsertExpression, UpdateExpression, - WindowFunctionCall, CTEExpression, + CTEExpression, # Function factories count, sum_, avg, row_number, rank, json_extract, array_agg, diff --git a/src/rhosocial/activerecord/backend/dialect/__init__.py b/src/rhosocial/activerecord/backend/dialect/__init__.py index bb70b58f8..62361dd6f 100644 --- a/src/rhosocial/activerecord/backend/dialect/__init__.py +++ b/src/rhosocial/activerecord/backend/dialect/__init__.py @@ -61,6 +61,7 @@ LateralJoinSupport, ArraySupport, JSONSupport, + UUIDSupport, ExplainSupport, FilterClauseSupport, OrderedSetAggregationSupport, @@ -109,7 +110,12 @@ UpsertMixin, LateralJoinMixin, ArrayMixin, + TrimMixin, + LpadMixin, + RepeatMixin, + RpadMixin, JSONMixin, + UUIDMixin, ExplainMixin, MergeMixin, TemporalTableMixin, @@ -134,6 +140,7 @@ AutoIncrementMixin, IdentityColumnMixin, DataTypeMixin, + ColumnTypeMixin, DDLTypeMixin, UserDefinedTypeMixin, DomainMixin, @@ -159,6 +166,7 @@ "LateralJoinSupport", "ArraySupport", "JSONSupport", + "UUIDSupport", "ExplainSupport", "FilterClauseSupport", "OrderedSetAggregationSupport", @@ -214,7 +222,12 @@ "UpsertMixin", "LateralJoinMixin", "ArrayMixin", + "TrimMixin", + "LpadMixin", + "RepeatMixin", + "RpadMixin", "JSONMixin", + "UUIDMixin", "ExplainMixin", "MergeMixin", "TemporalTableMixin", @@ -239,6 +252,7 @@ "AutoIncrementMixin", "IdentityColumnMixin", "DataTypeMixin", + "ColumnTypeMixin", "DDLTypeMixin", "UserDefinedTypeMixin", "DomainMixin", diff --git a/src/rhosocial/activerecord/backend/dialect/base.py b/src/rhosocial/activerecord/backend/dialect/base.py index 66e04561c..f1891f6eb 100644 --- a/src/rhosocial/activerecord/backend/dialect/base.py +++ b/src/rhosocial/activerecord/backend/dialect/base.py @@ -8,15 +8,27 @@ import re import warnings as _warnings -from typing import Any, FrozenSet, Optional, Tuple, TYPE_CHECKING +from typing import Any, ClassVar, Dict, FrozenSet, Optional, Tuple, Union, TYPE_CHECKING -from .exceptions import ProtocolNotImplementedError, UnsupportedFeatureError +from .exceptions import DialectNotAdaptedException, ProtocolNotImplementedError, UnsupportedFeatureError from ..warnings import IdentifierQuotingWarning if TYPE_CHECKING: + import datetime as _dt + from decimal import Decimal + from ..schema.differ import SchemaDiffer +def _version_text(version: Tuple[int, int, int]) -> str: + """Render a ``(major, minor, patch)`` tuple the way a server reports it. + + Used by messages that tell a caller which version a feature arrived in and + which one is in force, so both read the same way. + """ + return ".".join(str(part) for part in version) + + class SQLDialectBase: """ Minimal base class for SQL dialects. @@ -131,6 +143,98 @@ def check_feature_support(self, check_method: str, feature_name: str, suggestion if not is_supported: raise UnsupportedFeatureError(dialect_name=self.name, feature_name=feature_name, suggestion=suggestion) + # ------------------------------------------------------------------ + # Version floors for named features (functions above all) + # ------------------------------------------------------------------ + + #: Function name -> earliest ``(major, minor, patch)`` version of this + #: dialect that spells it. A backend declares the table; the base reads it + #: in :meth:`function_version_floor` and enforces it in + #: :meth:`check_function_version`. + #: + #: Annotated and deliberately *not* assigned here. ``SQLDialectBase`` sits + #: ahead of every mixin in a dialect's MRO, so a default assigned on the + #: base would shadow the table a backend's mixin declares -- the same + #: reason the base declares no ``supports_functions``. A backend that + #: computes its floors rather than tabulating them overrides + #: :meth:`function_version_floor` on its dialect class, which *does* + #: precede the base. + function_version_floors: ClassVar[Dict[str, Tuple[int, int, int]]] + + def function_version_floor(self, func_name: str) -> Optional[Tuple[int, int, int]]: + """Return the earliest version of this dialect that knows *func_name*. + + The query half of a version gate: the version a backend started + spelling a function at, read from :attr:`function_version_floors`. + ``None`` means no floor is recorded, which is not the same as + "unsupported" -- a name nobody has measured is simply not gated here. + Rendering consults it through :meth:`check_function_version`, so a + recorded floor is a refusal rather than a documented observation. + + Names match case-insensitively: the core and backend factories spell + them lower-case, the renderer spells them upper, and a caller may hand + either to a :class:`~...expression.core.FunctionCall`. + + Args: + func_name: The function name as the expression carries it. + + Returns: + The floor as a ``(major, minor, patch)`` tuple, or ``None`` when + this dialect records no floor for *func_name*. + """ + floors: Optional[Dict[str, Tuple[int, int, int]]] = getattr(self, "function_version_floors", None) + if not floors: + return None + floor = floors.get(func_name) + if floor is None: + floor = floors.get(func_name.lower()) + return floor + + def check_function_version(self, func_name: str) -> None: + """Refuse a function call this dialect's version predates. + + Reads :meth:`function_version_floor` and refuses when the version in + force is below it. This is what turns a declared floor into a gate: + the alternative is a renderer that emits SQL the server will reject, + which is the failure the floor was recorded to prevent. + + :class:`~.mixins.function.FunctionCallMixin` calls it while rendering a + call, so the gate holds for every dialect that composes that mixin and + for every caller. + + Args: + func_name: The function name as the expression carries it. + + Raises: + UnsupportedFeatureError: A floor is recorded for *func_name* and + this dialect's version is below it. The message names the + function, the floor and the version in force. + + Note: + A dialect that has not been adapted has no version to compare + against, so there is nothing to refuse: adaptation + (``backend.introspect_and_adapt()``) is what makes the gate bite, + and rendering an un-adapted dialect keeps its old permissiveness. + """ + floor = self.function_version_floor(func_name) + if floor is None: + return + try: + version = self.version + except DialectNotAdaptedException: + return + if version >= floor: + return + name = func_name.upper() + raise UnsupportedFeatureError( + dialect_name=self.name, + feature_name=f"the {name} function on {self.name} {_version_text(version)}", + suggestion=( + f"{name} arrived in {self.name} {_version_text(floor)}; connect to a " + f"server that has it, or spell the operation another way" + ), + ) + @property def reserved_words(self) -> FrozenSet[str]: """Return the reserved word set for this dialect. @@ -181,7 +285,9 @@ def format_identifier(self, identifier: str, need_quote: bool = True) -> str: escaped = identifier.replace('"', '""') return f'"{escaped}"' - def format_literal(self, value: Any) -> str: + def format_literal( + self, value: "Optional[Union[bool, int, float, Decimal, _dt.datetime, _dt.date]]" + ) -> str: """Render a Python scalar as a safe inline SQL literal. Used by DDL clauses (CHECK / DEFAULT / partition boundaries / diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/__init__.py b/src/rhosocial/activerecord/backend/dialect/mixins/__init__.py index 7c9d28563..6d89ec0cf 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/__init__.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/__init__.py @@ -20,7 +20,10 @@ from .upsert import UpsertMixin from .join import LateralJoinMixin, JoinMixin from .array import ArrayMixin +from .trim import TrimMixin +from .string_ops import LpadMixin, RepeatMixin, RpadMixin from .json import JSONMixin +from .uuid import UUIDMixin from .explain import ExplainMixin from .graph import GraphMixin, GraphTableMixin from .merge import MergeMixin @@ -65,6 +68,7 @@ from .dml import DMLMixin from .ddl_column import DDLColumnMixin from .data_type import DataTypeMixin +from .column_type import ColumnTypeMixin from .ddl_type import DDLTypeMixin from .user_defined_type import UserDefinedTypeMixin from .ddl_domain import DomainMixin @@ -75,8 +79,7 @@ "SQLXMLParsingMixin", "SQLXMLSerializationMixin", "SQLXMLConstructionMixin", - "SQLXMLAggregationMixin", - "SQLXMLQueryingMixin", + "SQLXMLAggregationMixin", "SQLXMLQueryingMixin", "SQLXMLMixin", "CollationMixin", "WindowFunctionMixin", @@ -86,6 +89,7 @@ "JoinMixin", "ArrayMixin", "JSONMixin", + "UUIDMixin", "ExplainMixin", "GraphMixin", "GraphTableMixin", @@ -135,9 +139,15 @@ "DMLMixin", "DDLColumnMixin", "DataTypeMixin", + "ColumnTypeMixin", "DDLTypeMixin", "UserDefinedTypeMixin", "DomainMixin", "DatabaseMixin", "TransactionControlMixin", + "ArrayMixin", + "TrimMixin", + "LpadMixin", + "RepeatMixin", + "RpadMixin", ] diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/column_type.py b/src/rhosocial/activerecord/backend/dialect/mixins/column_type.py new file mode 100644 index 000000000..638a8b470 --- /dev/null +++ b/src/rhosocial/activerecord/backend/dialect/mixins/column_type.py @@ -0,0 +1,49 @@ +# src/rhosocial/activerecord/backend/dialect/mixins/column_type.py +"""Baseline plumbing for the ColumnTypeSupport protocol. + +A dialect implements the protocol by answering two tables; this mixin supplies +the parts that are the same everywhere and deliberately withholds the part +that is not. + +There is **no inherited common-type table**. A table in core would be a guess +about a server core has never seen — and a wrong guess is worse than an +omission here, because resolution would accept it silently. A dialect that +does not answer is told so when a field is resolved, by an error naming the +missing entry. +""" + +from typing import Any, Dict, Optional, Type, TYPE_CHECKING + +if TYPE_CHECKING: # pragma: no cover + from ...expression.column_types import ColumnBase + + +class ColumnTypeMixin: + """Default implementation of the suggested-tables half of the protocol. + + ``suggested_extra_column_types()`` defaults to no extras, which is the + honest answer for most backends. ``suggested_column_types()`` has no + default and must be overridden. + """ + + def suggested_column_types(self) -> Dict[Any, Optional[Type["ColumnBase"]]]: + """The column class this dialect suggests for each common Python type. + + Must be overridden. Every key of the framework's common types has to + be answered -- with a column class, or with ``None`` when the dialect + genuinely has no workaround for that value family. + """ + raise NotImplementedError( + f"{type(self).__name__} does not answer the column-type table. " + f"Implement suggested_column_types() with a class (or None, as a " + f"last resort) for every common Python type; there is no " + f"inherited default." + ) + + def suggested_extra_column_types(self) -> Dict[Any, Type["ColumnBase"]]: + """Extra Python types this dialect offers beyond the common ones. + + Empty by default: a backend with nothing of its own has nothing to + report, and a type it does not offer is simply absent from the table. + """ + return {} diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/data_type.py b/src/rhosocial/activerecord/backend/dialect/mixins/data_type.py index c080ec6b6..18a6ef9ff 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/data_type.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/data_type.py @@ -4,7 +4,9 @@ from __future__ import annotations import re -from typing import cast, Dict, Optional, Tuple, TYPE_CHECKING +import typing +from functools import lru_cache +from typing import Any, Callable, cast, Dict, Optional, Tuple, TYPE_CHECKING if TYPE_CHECKING: from ...expression.types._base import DataType @@ -15,10 +17,74 @@ class DataTypeMixin: - """Mixin providing naming-convention ``format_data_type`` dispatch.""" + """Mixin providing naming-convention ``format_data_type`` dispatch. + + A ``DataType`` declares its concept in a class attribute ``name``; the + dialect renders it with ``format_data_type_``. The correspondence + is by naming convention, not by inheritance: the dialect does not know + in advance which types exist, and a backend that introduces one needs + no change here. + + Expression ⇔ dialect correspondence + ---------------------------------- + Every concept the framework models must be **declared** by every dialect, + in one of two ways: + + * rendered — ``format_data_type_`` exists, which is the support + declaration itself. A dialect that owns a ``supports_data_type_`` + probe may answer ``False`` there to opt a rendered name out (a + version-gated feature); without such a probe, rendering *is* support. + + * substituted — ``suggested_data_types()[name]`` names what this backend + stores instead, for concepts it genuinely cannot spell (XML on SQLite, + arrays on Snowflake, …). + + Silence is the one answer that is not allowed: a caller who asks for an + undeclared concept is told "unsupported" and nothing more, which is + indistinguishable from the concept never having been considered. The + ``suggested_data_types`` hook exists so that a backend *can* answer without + faking a type it does not have, and the error text in + :meth:`_suggested_type_advice` puts the answer in front of the caller. + + The two are disjoint by contract: a type the dialect renders needs no + substitute. Both properties — completeness over core types, and the + renderability of every suggested substitute — are enforced by + ``tests/.../dummy2/test_type_protocol_contracts.py`` rather than by a + ``Protocol``, because the set of concepts is open: a backend may add one + (that is how ``Enum8``/``Enum16`` in ClickHouse, ``GEOMETRY`` in + PostgreSQL, or the three SQL Server GUID spellings exist), and requiring + the dialect protocol to enumerate every core type would turn each addition + into an edit to an unrelated file. A backend that owns a whole family of + its own types additionally declares a ``XxxTypeSupport(Protocol)`` for + them, so the family has one stated shape rather than being merely implied + by a naming pattern. + + No registry + ----------- + There is deliberately no table mapping a generic name to a class. The naming + family *is* the registry, and :meth:`_type_class_for` says where the class + comes from — the formatter's own annotation first, then the backend's type + module, then the live subclass tree. That last step is why + ``tests/.../dummy2/test_type_dispatch_registry.py`` asks in a **fresh + interpreter**: a test that imports the type classes in its own preamble has + already loaded them, and a bug that only shows up before they are loaded is + invisible to it. + """ def format_data_type(self, data_type: DataType) -> SQLQueryAndParams: - """Render a :class:`DataType` through the dialect's type family.""" + """Render a :class:`DataType` through the dialect's type family. + + The **total dispatcher**: routes by ``data_type.name`` to the + ``format_data_type_`` member. When no member exists the + raise appends :meth:`substitute_advice`'s text, so a concept this + dialect does not render still comes back as a ``TypeError`` that + tells the caller what to declare instead — provided the dialect + listed the concept in :meth:`suggested_data_types`. A concept + that is neither rendered nor suggested raises with **no advice**: + that silent hole is exactly what the concept-coverage rule (D9, + see the protocol) forbids, which is why the suggested map is a + contract rather than politeness. + """ from ...expression.types._base import DataType if not isinstance(data_type, DataType): @@ -36,30 +102,128 @@ def format_data_type(self, data_type: DataType) -> SQLQueryAndParams: if formatter is None: raise TypeError( f"{type(self).__name__} does not support the generic type " - f"{name!r} (no format_data_type_{name}). Use a type this " - f"backend supports." + f"{name!r} (no format_data_type_{name})." + + self._suggested_type_advice(name) ) return cast(SQLQueryAndParams, formatter(data_type)) + def substitute_advice(self, name: str) -> str: + """Extra caveat for a substituted concept, empty by default. + + A substitute is not always the same meaning. Firebird's ``TIMETZ`` + concept has no generic rendering there, and its stand-in ``TimeType`` + stores a local time with the zone **dropped** — which is a different + value, not a different spelling of one value. The default advice text + cannot say that, because whether a substitution loses something is a + fact about the backend, not about the mechanism. + + So a backend whose substitution is lossy returns the sentence here, and + the caller sees it in the error it is already reading. Returning ``""`` + means "no caveat", which is the right answer whenever the substitute + really does hold the same meaning — most of them do. + """ + return "" + + def _suggested_type_advice(self, name: str) -> str: + """Name this dialect's substitute for *name*, if it declares one. + + A backend that cannot render a generic type says what to use instead + through ``suggested_data_types()``, and that is where the answer is + written down. Without it in the message the caller is told the type is + unsupported and nothing else, which is the same as not knowing. + + The wording deliberately does **not** claim the substitute holds the + same meaning. That claim is true for most entries and false for a + lossy one, and a message that is usually right is worse than one that + never says it: the caller reads "stores the same meaning" and stops + looking. A backend with something to add says it through + :meth:`substitute_advice`, which lands in the same error. + """ + substitute = self.suggested_data_types().get(name) + if substitute is None: + return " Use a type this backend supports." + caveat = self.substitute_advice(name).strip() + message = f" It suggests {substitute.__name__} instead, which is what this backend uses." + return f"{message} {caveat}" if caveat else message + def supports_data_types(self) -> Dict[str, type]: - """Return the generic type names and concrete classes this dialect renders.""" + """Return the generic type names and concrete classes this dialect renders. + + Derived from the ``format_data_type_`` family: **a formatter + is the declaration of support**, so the mapping covers every name + the dialect can render. A ``supports_data_type_`` probe, + where a dialect still owns one, is the only thing that can opt a + rendered name out — that is how a backend gates a feature by + version (a number of backends' ``_*`` probes do). Its + absence is not an answer of "no": a dialect that declares no + probe at all supports everything it renders. + """ result = {} for member_name in dir(type(self)): match = re.match(r"^format_data_type_([a-z][a-z0-9_]*)$", member_name) if not match: continue name = match.group(1) - supports = getattr(self, f"supports_data_type_{name}", None) - if supports is not None and supports(): - data_type_class = self._type_class_for(name) - if data_type_class is not None: - result[name] = data_type_class + probe = getattr(self, f"supports_data_type_{name}", None) + if probe is not None and not probe(): + continue + data_type_class = self._type_class_for(name) + if data_type_class is not None: + result[name] = data_type_class return result def _type_class_for(self, name: str) -> Optional[type]: - """Resolve the concrete ``DataType`` class for a generic name.""" + """Resolve the concrete ``DataType`` class for a generic name. + + Three answers are available and any two of them agree wherever more than + one exists; the first one available is used. + + **The formatter's own annotation.** ``format_data_type_`` names + the concept it renders twice — in the method name and in the declared type + of its argument — so the class is named in the same place the dispatch key + is. That makes the annotation the authoritative statement, and reading it + first means the answer no longer depends on which class a subclass walk + happened to reach first if two ever share a ``name``. + + The annotation is trusted only when the class it names declares that + *same* ``name`` — the 1:1 correspondence this whole mixin is built on. + A formatter annotated with a different concept's class is describing what + it accepts, not which dispatch key it serves (PostgreSQL's + ``format_data_type_postgres_array`` takes the core ``ArrayType``), and the + next step answers for it instead. + + **This backend's own type module.** What is left over is a + *backend-prefixed* name whose class nobody has imported — the one case + where a lookup can silently come back empty-handed, because the answer + depends on what else happens to be loaded. The namespace rule that core + already enforces is what makes the module derivable: a backend type is + named ``_<...>`` and lives under ``...impl....``, so + the slug in the name and the slug in the dialect's own module path agree + and ``impl//expression/types.py`` follows. Importing it is what + the SQL Server dialect now does by hand in its registration hook; doing it + here means a backend that forgets does not lose the name from its + supported-types mapping, which is the whole of the bug. + + **The live subclass tree**, for a name that is neither of the above. + + A backend that keeps its types somewhere else, or that annotates a name + only under ``TYPE_CHECKING`` so the annotation is a string with nothing + behind it, still resolves here *if* something imported the class — and if + nothing did, this returns ``None`` as it always did. That residual is why + ``tests/.../dummy2/test_type_dispatch_registry.py`` checks the mapping + from a **fresh interpreter**, which is the only way a load-order bug can be + seen: a test that imports the type classes in its own preamble has already + made the bug invisible. + """ from ...expression.types._base import DataType + formatter = getattr(type(self), f"format_data_type_{name}", None) + declared = _annotated_data_type(formatter) + if declared is not None and declared.name == name: + return declared + + _load_backend_type_module(type(self), name) + seen = set() stack = [DataType] while stack: @@ -73,8 +237,177 @@ def _type_class_for(self, name: str) -> Optional[type]: return None def suggested_data_types(self) -> Dict[str, type]: - """Return cross-backend type suggestions, empty by default.""" + """Return cross-backend type suggestions, empty by default. + + One half of the **concept coverage** rule (D9 — see + :class:`~...dialect.protocols.query.data_type.DataTypeSupport` for + the full statement): every core concept must be either rendered by + this dialect or listed here, and silence is not an answer — a + concept that is neither reaches the caller as a bare ``TypeError`` + with no route forward. + + Keys are the **concept names** (the same dispatch keys as + ``format_data_type_``); values are the class this dialect + really stores for the concept. The map and ``supports_data_types()`` + are disjoint — a concept that renders needs no substitute — and an + empty return means "this dialect renders every core concept it was + asked about", not "not yet filled in". + + Coverage is deliberately **not audited from core**: backends differ + too much for one shared shape. Each backend's own tests walk the + core concepts (discovered, not listed), assert the coverage, the + disjointness, that every substitute renders, and that every key + still names an existing concept — BigQuery's + ``test_every_core_concept_is_declared`` is the pattern to copy. + """ + return {} + + def type_parameter_defaults(self) -> Dict[str, Dict[str, Any]]: + """The values this server supplies for parameters a type leaves undeclared. + + Keys are **concept names** — the same ``format_data_type_`` dispatch + keys, and the same ``name`` attribute the type class carries, so a backend + type reached through its own entry point declares under its own name and + a concept that uses ``None`` to mean *unbounded* rather than *undeclared* + simply does not appear. The inner mapping is keyed by parameter name + (``length``, and ``precision`` for a concept that has one), because the + question being asked is always "what does this server put here when the + caller named nothing", and it is a different question for a length than + for a precision. + + Empty by default, and empty is the **correct answer for most servers**, + not an unfinished one. A backend declares nothing here to say that the + bare form of a concept carries no width on this server: PostgreSQL + renders ``VARCHAR`` and parses it back with no length, because the + catalog reports ``atttypmod = -1`` and a bare ``character varying`` there + really does mean unbounded. Deciding that centrally is not available — + ``None`` means "no limit at all" on PostgreSQL and "the default, 4000" + on Oracle, and there is no value that is honest for both — so the default + has to be the empty statement and each server writes down its own. + + There is deliberately no list here of which concepts a backend may be + silent about: silence is what every backend starts from, so a list could + only ever be a list of permissions, and an empty one of those has already + been deleted from this codebase once for inviting the next. + + A declaration here is a statement about **what this dialect writes and + reads back**, so its justification belongs with the vendor's own words + for the type, and it is worth being precise about which of the two it + is: PostgreSQL's ``VARCHAR`` has no limit because the server has none, + whereas SQL Server's ``VARCHAR`` has a documented default of 1 that this + dialect deliberately does not use. A backend that widens past its + server's own default says so in that backend, in that backend's words. + """ return {} + def _check_spelling(self, data_type, accepted) -> None: + """Raise unless *data_type* carries a spelling this dialect renders. + + A ``DataType`` with several spellings (one class, several ways to write + it — ``INTEGER``/``INT``, ``DECIMAL``/``NUMERIC``/``DEC``) carries the + chosen one in ``spelling``. Which of them a *backend* accepts is a fact + about the backend, not about the concept, so the check belongs here in + the formatter rather than in the expression: SQL Server has ``INT`` but + no ``INT4``, PostgreSQL has no ``TINYINT`` at all, and a silent fallback + to the default spelling would turn a caller's explicit request into a + different type without saying so. + + ``accepted`` is either the class that declares ``SPELLINGS`` — normally + the formatter's own parameter type — or an explicit tuple, for the + common case where a backend supports only some of a concept's spellings + and naming the rest would be false advertising (``format_data_type_text`` + below accepts ``"text"`` and not ``"clob"``, because PostgreSQL has no + CLOB). + + The closed list is what makes this injection-safe: an unknown spelling + is a ``TypeError`` naming the accepted set, never a value interpolated + into SQL. The same argument as + :meth:`~...types.custom.CustomType.validate_type_name` and + ``type_name.validate_type_name``. + """ + spellings = accepted if isinstance(accepted, tuple) else accepted.SPELLINGS + spelling = data_type.spelling + if spelling not in spellings: + raise TypeError( + f"{type(self).__name__} does not spell this type " + f"{spelling!r}; it renders " + f"{', '.join(repr(s) for s in spellings)}." + ) + + +@lru_cache(maxsize=None) +def _annotated_data_type(formatter: Optional[Callable]) -> Optional[type]: + """The ``DataType`` class a formatter declares for its argument, if any. + + ``None`` when the formatter has no argument annotation, when the annotation + is not a class, or when ``typing`` cannot resolve it — which is the ordinary + outcome for a module that annotates under ``TYPE_CHECKING``, where the name + is a string and the module namespace it would be resolved against does not + carry it. That is a lookup miss, not an error: the caller falls back to the + subclass walk. + + Cached because ``supports_data_types()`` is called per dialect and resolves + the same formatter every time, and because an annotation does not change + after the function is defined. + """ + if formatter is None: + return None + from ...expression.types._base import DataType + + try: + hints = typing.get_type_hints(formatter) + except Exception: + # NameError when the annotation names something the defining module only + # imported under TYPE_CHECKING; TypeError/AttributeError for a shape + # get_type_hints cannot read. All of them mean "no usable annotation". + return None + # Every parameter is considered rather than only ``data_type``: dialects + # name it whatever reads best at the call site (``data_type`` in core, + # ``expr`` in Snowflake), and what is being asked is which ``DataType`` the + # formatter serves, not what the argument is called. + for parameter, declared in hints.items(): + if parameter == "return": + continue + if isinstance(declared, type) and issubclass(declared, DataType): + return declared + return None + + +#: Where a backend keeps the ``DataType`` subclasses its dispatch names refer to. +#: Every backend that defines backend-named types keeps them in exactly this +#: module; one that does not is simply left alone (see +#: :func:`_load_backend_type_module`). +_BACKEND_TYPE_MODULE = "rhosocial.activerecord.backend.impl.{backend}.expression.types" + + +@lru_cache(maxsize=None) +def _load_backend_type_module(dialect_class: type, name: str) -> None: + """Import the module a backend keeps its own ``DataType`` classes in. + + A no-op unless the dispatch name is backend-prefixed and its prefix is the + dialect's *own* backend slug. That double condition is what keeps this + narrow: core types have pure names and never reach here, a core dialect never + imports a backend package, and one backend never imports another's. + + ``ImportError`` is swallowed on purpose and means only that this backend keeps + its types somewhere else — the lookup then proceeds exactly as it did before. + Anything else the module raises while importing is a real error and is left to + propagate; a broken type module must not look like a missing one. + """ + from ...expression.types._base import DataType + + backend, separator, _ = name.partition("_") + if not separator: + return + match = DataType._BACKEND_MODULE_RE.search(dialect_class.__module__ or "") + if match is None or match.group(1) != backend: + return + import importlib + + try: + importlib.import_module(_BACKEND_TYPE_MODULE.format(backend=backend)) + except ImportError: + return + __all__ = ["DataTypeMixin"] diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/ddl_column.py b/src/rhosocial/activerecord/backend/dialect/mixins/ddl_column.py index 469725b8a..83c8a893e 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/ddl_column.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/ddl_column.py @@ -11,6 +11,7 @@ from .ddl_table import normalize_column_constraint_type, normalize_table_constraint_type if TYPE_CHECKING: # pragma: no cover + from ....base.ddl import ColumnAttribute from ...expression.core import Column from ...expression.statements.ddl_alter import ( AddColumn, @@ -28,9 +29,11 @@ ValidateConstraint, ) from ...expression.statements.ddl_table import ( + ColumnCommentClause, ColumnConstraint, ColumnDefinition, DefaultValueClause, + GeneratedColumnExpression, IndexDefinition, ReferencesClause, StorageOptionsExpression, @@ -57,7 +60,7 @@ def supports_column_comment(self) -> bool: """Whether COLUMN COMMENT is supported (defaults to False).""" return False - def format_column_comment_clause(self, clause) -> Tuple[str, tuple]: + def format_column_comment_clause(self, clause: "ColumnCommentClause") -> Tuple[str, tuple]: """Render the inline ``COMMENT ''`` column clause. Generic reusable implementation: ``COMMENT ''`` with a @@ -105,7 +108,7 @@ def supports_column_character_set(self) -> bool: """ return False - def format_column_attribute(self, attr: "Any") -> Tuple[str, Tuple]: + def format_column_attribute(self, attr: "ColumnAttribute") -> Tuple[str, Tuple]: """Render one selected column attribute as a definition fragment. Identity reuses :meth:`IdentityColumnMixin.format_identity_clause` @@ -256,7 +259,7 @@ def format_column_definition(self, col_def: "ColumnDefinition") -> Tuple[str, Tu all_params.extend(comment_params) return col_sql, tuple(all_params) - def format_generated_column_expression(self, expr) -> Tuple[str, Tuple]: + def format_generated_column_expression(self, expr: "GeneratedColumnExpression") -> Tuple[str, Tuple]: """Format a :class:`~...statements.ddl_table.GeneratedColumnExpression`. Renders ``GENERATED ALWAYS AS () STORED|VIRTUAL`` and delegates diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/ddl_table.py b/src/rhosocial/activerecord/backend/dialect/mixins/ddl_table.py index ea57918b9..2a3d13e27 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/ddl_table.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/ddl_table.py @@ -55,6 +55,7 @@ def normalize_table_constraint_type(constraint_type: Any) -> Any: CreateTableFromTemplateExpression, CreateTableOptions, DropTableExpression, + TableCommentClause, AlterTableExpression, ) @@ -327,7 +328,7 @@ def format_table_comment(self, comment: str) -> Tuple[str, tuple]: escaped = self._escape_sql_string(comment) return f"COMMENT '{escaped}'", () - def format_table_comment_clause(self, clause) -> Tuple[str, tuple]: + def format_table_comment_clause(self, clause: "TableCommentClause") -> Tuple[str, tuple]: """Render the inline table-comment clause of ``CREATE TABLE``. Returns the fragment **with a leading space** so the statement diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/dml.py b/src/rhosocial/activerecord/backend/dialect/mixins/dml.py index 38acf21df..bdf5e4c67 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/dml.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/dml.py @@ -12,9 +12,12 @@ if TYPE_CHECKING: from ...expression.statements.dml import ( + DefaultValuesSource, DeleteExpression, InsertExpression, + SelectSource, UpdateExpression, + ValuesSource, ) from ...expression.statements import ReturningClause @@ -93,14 +96,18 @@ def format_returning_clause(self, clause: "ReturningClause") -> Tuple[str, Tuple UnsupportedFeatureError: If a requested RETURNING feature is not supported by this dialect. """ - from ...expression.core import Column, Subquery, WildcardExpression - from ...expression.aggregates import AggregateFunctionCall + from ...expression.column_types import ColumnBase + from ...expression.core import Subquery, WildcardExpression from ...expression.operators import RawSQLExpression all_params: List[Any] = [] expr_parts: List[str] = [] for expr in clause.expressions: - if isinstance(expr, (AggregateFunctionCall, Subquery)): + # ``is_aggregate`` is set by the aggregate factories and forwarded + # by the typed wrapper they return, so reading the attribute catches + # both the node and the wrapper. A plain isinstance test against the + # node class would miss every factory-built aggregate. + if getattr(expr, "is_aggregate", False) or isinstance(expr, Subquery): raise UnsupportedFeatureError( self.name, "aggregate/subquery in RETURNING", @@ -115,7 +122,7 @@ def format_returning_clause(self, clause: "ReturningClause") -> Tuple[str, Tuple "This dialect does not support '*' in a RETURNING clause; " "list the columns explicitly.", ) - elif isinstance(expr, Column): + elif isinstance(expr, ColumnBase): if expr.table and expr.table.upper() in ("OLD", "NEW"): if not self.supports_returning_old_new(): raise UnsupportedFeatureError( @@ -209,7 +216,7 @@ def format_insert_statement(self, expr: "InsertExpression") -> Tuple[str, tuple] all_params.extend(returning_params) return sql, tuple(all_params) - def format_insert_values_source(self, expr) -> Tuple[str, tuple]: + def format_insert_values_source(self, expr: "ValuesSource") -> Tuple[str, tuple]: """Render a ``VALUES`` list as an INSERT's data source. Args: @@ -231,7 +238,7 @@ def format_insert_values_source(self, expr) -> Tuple[str, tuple]: all_params.extend(cell_params) return "VALUES " + ", ".join(rows_sql), tuple(all_params) - def format_insert_select_source(self, expr) -> Tuple[str, tuple]: + def format_insert_select_source(self, expr: "SelectSource") -> Tuple[str, tuple]: """Render the query an INSERT selects its rows from. Args: @@ -242,7 +249,7 @@ def format_insert_select_source(self, expr) -> Tuple[str, tuple]: """ return expr.select_query.to_sql() - def format_insert_default_values_source(self, expr) -> Tuple[str, tuple]: + def format_insert_default_values_source(self, expr: "DefaultValuesSource") -> Tuple[str, tuple]: """Render the ``DEFAULT VALUES`` keyword. Args: diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/dql.py b/src/rhosocial/activerecord/backend/dialect/mixins/dql.py index 5db805961..f099f9662 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/dql.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/dql.py @@ -10,6 +10,7 @@ from ...expression.bases import ToSQLProtocol if TYPE_CHECKING: + from ...expression import bases from ...expression.statements.dql import QueryExpression from ...expression.query_parts import ( ForUpdateClause, @@ -468,7 +469,7 @@ def supports_grouping_sets(self) -> bool: """Whether GROUPING SETS are supported. Defaults to False.""" return False - def format_grouping_clause(self, expr: Any) -> Tuple[str, tuple]: + def format_grouping_clause(self, expr: "bases.BaseExpression") -> Tuple[str, tuple]: """Format a grouping expression (ROLLUP, CUBE, or GROUPING SETS). Args: diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/expression.py b/src/rhosocial/activerecord/backend/dialect/mixins/expression.py index 37ba4ecb4..ac9586276 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/expression.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/expression.py @@ -5,7 +5,7 @@ casts, CASE, subqueries, VALUES and aliases - to ``(sql, params)`` pairs. Function-call rendering is inherited from :class:`FunctionCallMixin`. """ -from typing import Any, List, Tuple +from typing import Any, List, Optional, Tuple from ...expression import bases from ...expression.core import ( @@ -20,6 +20,7 @@ BinaryExpression, RawSQLExpression, SQLOperation, + StringConcatExpression, UnaryExpression, ) from .function import FunctionCallMixin @@ -117,19 +118,16 @@ def format_cast_expression(self, expr: CastExpression) -> Tuple[str, tuple]: A ``(sql, params)`` tuple carrying the wrapped expression's parameters. - Raises: - ValueError: If ``target_type`` contains unsupported characters. - ``CAST(expr AS type)`` is a unary tree node; the wrapped expression - renders through its own ``to_sql()``. + renders through its own ``to_sql()`` and the target through + its own ``to_sql()``. """ expr_sql, params = expr.expression.to_sql() - if not self._validate_data_type(expr.target_type): - raise ValueError( - f"Invalid target type '{expr.target_type}': " - "must contain only alphanumeric characters, spaces, parentheses, and commas." - ) - sql = f"CAST({expr_sql} AS {expr.target_type})" + # The target is an expression, so it renders itself and this + # concatenates. Interpolating it would have produced + # `col::IntegerType()` instead of `col::INTEGER`. + type_sql, _ = expr.target_type.to_sql() + sql = f"CAST({expr_sql} AS {type_sql})" if expr.alias: sql = f"{sql} AS {self.format_identifier(expr.alias)}" return sql, params @@ -157,15 +155,70 @@ def format_sql_operation(self, expr: SQLOperation) -> Tuple[str, tuple]: def format_binary_operator(self, expr: BinaryExpression) -> Tuple[str, tuple]: """Format a :class:`~...expression.operators.BinaryExpression`. + String concatenation is routed to + :meth:`format_string_concatenation` rather than inlined, because the + operator token does not determine the meaning: ``||`` concatenates on + most backends but is logical OR on MySQL, MariaDB and SQL Server. + Args: expr: Binary expression exposing ``left``, ``op`` and ``right``. Returns: A ``(sql, params)`` tuple of ``left op right``. """ + if isinstance(expr, StringConcatExpression): + return self.format_string_concatenation(expr) + + left_sql, left_params = expr.left.to_sql() + right_sql, right_params = expr.right.to_sql() + sql = f"{left_sql} {expr.op} {right_sql}" + alias = getattr(expr, "alias", None) + if alias: + sql = f"{sql} AS {self.format_identifier(alias)}" + return sql, left_params + right_params + + def format_string_concatenation( + self, expr: "StringConcatExpression" + ) -> Tuple[str, tuple]: + """Render a string concatenation using this dialect's spelling. + + Args: + expr: The concatenation node exposing ``left`` and ``right``. + + Returns: + A ``(sql, params)`` tuple. + """ left_sql, left_params = expr.left.to_sql() right_sql, right_params = expr.right.to_sql() - return f"{left_sql} {expr.op} {right_sql}", left_params + right_params + function = self.string_concatenation_function() + if function is None: + sql = f"{left_sql} || {right_sql}" + else: + sql = f"{function}({left_sql}, {right_sql})" + alias = getattr(expr, "alias", None) + if alias: + sql = f"{sql} AS {self.format_identifier(alias)}" + return sql, left_params + right_params + + def string_concatenation_function(self) -> Optional[str]: + """Return the function name this dialect uses for concatenation. + + A dialect where ``||`` means something else declares its own by + overriding this: MySQL, MariaDB and SQL Server read ``||`` as logical + OR, and BigQuery does not accept it as concatenation at all. + + The lookup is by name through ``getattr`` rather than by inheriting a + base implementation, because MRO order decides which definition wins + and the core mixin's position depends on how many generic mixins a + given dialect happens to inherit — which a backend author cannot see or + control. Looking the name up on the instance finds the dialect's own + declaration wherever it sits. + + Returns: + The function name, or ``None`` to use the standard's ``||``. + """ + declaration = getattr(self, "STRING_CONCATENATION", None) + return declaration if isinstance(declaration, str) else None def format_unary_operator(self, expr: UnaryExpression) -> Tuple[str, tuple]: """Format a :class:`~...expression.operators.UnaryExpression`. diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/function.py b/src/rhosocial/activerecord/backend/dialect/mixins/function.py index 793885756..ffb2126b3 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/function.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/function.py @@ -28,12 +28,22 @@ class FunctionCallMixin: """ def format_function_call(self, expr: "bases.BaseExpression") -> Tuple[str, tuple]: - """Format a scalar or aggregate function call expression. - - Renders ``NAME(args)`` with optional ``DISTINCT`` and a trailing - ``FILTER (WHERE ...)`` clause. ``COUNT(*)`` is special-cased so that - a wildcard argument renders as ``*``. Niladic functions with no - arguments and no ``DISTINCT`` omit the parentheses. + """Format a function call expression, scalar or aggregate. + + Renders ``NAME(args)`` with optional ``DISTINCT``, a trailing + ``FILTER (WHERE ...)`` clause and a trailing ``OVER (...)`` window + clause, in that order, followed by ``AS alias``. ``COUNT(*)`` is + special-cased so that a wildcard argument renders as ``*``. Niladic + functions with no arguments and no ``DISTINCT`` omit the parentheses. + Every argument must be an expression: a bare value fails to render + rather than being turned into a bind parameter here, because the + renderer does not decide what a caller meant. A value goes through + :class:`~...expression.core.Literal` at the call site. + + The first thing it does is refuse a call this dialect's version + predates (:meth:`~.base.SQLDialectBase.check_function_version`), so a + backend that records a floor for the name gets the refusal instead of + SQL the server will reject. Args: expr: The function call expression to render. @@ -43,14 +53,18 @@ def format_function_call(self, expr: "bases.BaseExpression") -> Tuple[str, tuple Raises: UnsupportedFeatureError: If a ``FILTER`` clause is requested on a - dialect that does not support it. + dialect that does not support it, an ``OVER`` clause is + requested on a dialect that does not support window + functions, or the dialect records a version floor for this + function that its version is below. """ - from ...expression import aggregates, core, operators + from ...expression import core, operators from ..protocols import FilterClauseSupport + self.check_function_version(expr.func_name) + if ( - isinstance(expr, aggregates.AggregateFunctionCall) - and expr.func_name.upper() == "COUNT" + expr.func_name.upper() == "COUNT" and len(expr.args) == 1 and ( (isinstance(expr.args[0], operators.RawSQLExpression) and expr.args[0].expression == "*") @@ -63,6 +77,9 @@ def format_function_call(self, expr: "bases.BaseExpression") -> Tuple[str, tuple args_sql = [] args_params = [] for arg in expr.args: + # A factory that accepts a bare value is deciding what it + # meant; the renderer refuses instead of manufacturing the + # Literal the caller should have written (see the docstring). sql_part, params_part = arg.to_sql() args_sql.append(sql_part) args_params.append(params_part) @@ -81,20 +98,12 @@ def format_function_call(self, expr: "bases.BaseExpression") -> Tuple[str, tuple filter_predicate = getattr(expr, "filter_predicate", None) if filter_predicate: - if isinstance(self, FilterClauseSupport): - if self.supports_filter_clause(): - from ...expression.statements.filter_clause import FilterClauseExpression - filter_expr = FilterClauseExpression(self, condition=filter_predicate) - filter_clause_sql, filter_clause_params = self.format_filter_clause(filter_expr) - func_call_sql += f" {filter_clause_sql}" - all_params.extend(filter_clause_params) - else: - from ..exceptions import UnsupportedFeatureError - raise UnsupportedFeatureError( - self.name, - "FILTER clause in aggregate functions", - "Use a CASE expression inside the aggregate function instead.", - ) + if isinstance(self, FilterClauseSupport) and self.supports_filter_clause(): + from ...expression.statements.filter_clause import FilterClauseExpression + filter_expr = FilterClauseExpression(self, condition=filter_predicate) + filter_clause_sql, filter_clause_params = self.format_filter_clause(filter_expr) + func_call_sql += f" {filter_clause_sql}" + all_params.extend(filter_clause_params) else: from ..exceptions import UnsupportedFeatureError raise UnsupportedFeatureError( @@ -103,6 +112,24 @@ def format_function_call(self, expr: "bases.BaseExpression") -> Tuple[str, tuple "Use a CASE expression inside the aggregate function instead.", ) + window_spec = getattr(expr, "window_spec", None) + if window_spec is not None: + # Guarded through getattr(): a dialect that does not compose + # WindowFunctionMixin has neither the probe nor the formatter, and + # must refuse the clause rather than fail resolving a method. + supports_window_functions = getattr(self, "supports_window_functions", None) + if supports_window_functions is None or not supports_window_functions(): + from ..exceptions import UnsupportedFeatureError + raise UnsupportedFeatureError(self.name, "window functions") + if isinstance(window_spec, str): + # Reference to a named window definition. + window_part = self.format_identifier(window_spec) + else: + window_spec_sql, window_spec_params = self.format_window_specification(window_spec) + window_part = f"({window_spec_sql})" if window_spec_sql else "()" + all_params.extend(window_spec_params) + func_call_sql = f"{func_call_sql} OVER {window_part}" + if expr.alias: func_call_sql = f"{func_call_sql} AS {self.format_identifier(expr.alias)}" diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/json.py b/src/rhosocial/activerecord/backend/dialect/mixins/json.py index ba7ffa663..deae37566 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/json.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/json.py @@ -10,7 +10,7 @@ from ...expression import bases if TYPE_CHECKING: # pragma: no cover - from ...expression.advanced_functions import JSONExpression + from ...expression.advanced_functions import JSONDocumentExpression class JSONMixin: @@ -25,6 +25,25 @@ def supports_json_type(self) -> bool: """Whether JSON type is supported. Defaults to False.""" return False + def supports_json_path(self) -> bool: + """Whether a JSON path can be rendered at all. + + Separate from :meth:`supports_json_type` on purpose. A dialect can + have the functions that read a path without having a native JSON type + — MySQL 5.7.0 has JSON_EXTRACT, and the JSON *type* arrived in 5.7.8 — + and it can have a JSON type with no way to read a path, which is + Firebird's situation with JSON_ARRAY and JSON_OBJECT. + + Conflating the two makes a backend refuse a query its server would + have answered, and the refusal looks like a missing feature rather + than a wrong gate. + + Defaults to True because a dialect that says nothing is expected to + render paths; a dialect whose server has no such function should + override this to False and refuse with a suggestion. + """ + return True + def supports_json_arrow_operators(self) -> bool: """Whether JSON arrow operators (-> and ->>) are supported. @@ -53,14 +72,14 @@ def supports_json_table(self) -> bool: # Arrow-operator formatting (-> / ->>) # ------------------------------------------------------------------ - def format_json_arrow_expression(self, expr: "JSONExpression") -> Tuple[str, Tuple]: + def format_json_arrow_expression(self, expr: "JSONDocumentExpression") -> Tuple[str, Tuple]: """Format JSON expression using arrow operators (-> / ->>). This method always uses arrow operator syntax. If the dialect does not support arrow operators, it raises UnsupportedFeatureError. Args: - expr: The JSONExpression node with column, path, operation, and + expr: The JSONDocumentExpression node with column, path, operation, and optional alias. Returns: @@ -95,7 +114,7 @@ def format_json_arrow_expression(self, expr: "JSONExpression") -> Tuple[str, Tup # Function-based formatting (JSON_EXTRACT / JSON_UNQUOTE etc.) # ------------------------------------------------------------------ - def format_json_function_expression(self, expr: "JSONExpression") -> Tuple[str, Tuple]: + def format_json_function_expression(self, expr: "JSONDocumentExpression") -> Tuple[str, Tuple]: """Format JSON expression using function-based equivalents. Default implementation uses JSON_EXTRACT for -> and @@ -105,7 +124,7 @@ def format_json_function_expression(self, expr: "JSONExpression") -> Tuple[str, method to provide the correct function-based SQL. Args: - expr: The JSONExpression node with column, path, operation, and + expr: The JSONDocumentExpression node with column, path, operation, and optional alias. Returns: @@ -137,7 +156,7 @@ def format_json_function_expression(self, expr: "JSONExpression") -> Tuple[str, # Dispatch entry point # ------------------------------------------------------------------ - def format_json_expression(self, expr: "JSONExpression") -> Tuple[str, Tuple]: + def format_json_expression(self, expr: "JSONDocumentExpression") -> Tuple[str, Tuple]: """Format JSON expression, dispatching on mode and capability. Dispatches to arrow-operator or function-based formatting depending @@ -150,17 +169,53 @@ def format_json_expression(self, expr: "JSONExpression") -> Tuple[str, Tuple]: The default mode is ``JSONPathMode.AUTO``. Args: - expr: The JSONExpression node to format. + expr: The JSONDocumentExpression node to format. Returns: Tuple of (SQL string, parameters tuple) for the expression. Raises: - UnsupportedFeatureError: If arrow mode is requested but arrow - operators are not supported. + UnsupportedFeatureError: If the dialect declares no JSON support + at all, or if arrow mode is requested but arrow operators are + not supported. """ from ...expression.advanced_functions import JSONPathMode + # A dialect whose server has no way to read a JSON path must not be + # handed JSON SQL. The docstring below has always promised this + # refusal and the code did not keep it: rendering went straight to the + # function-based fallback, which is MySQL's shape, so Snowflake and + # BigQuery answered a JSON path with JSON_EXTRACT — a function neither + # has. + # + # The gate is supports_json_path, not supports_json_type: those are two + # capabilities, and MySQL 5.7.0 reads paths through JSON_EXTRACT while + # having no native JSON type until 5.7.8. Gating on the type would + # refuse queries the server answers. + if not self.supports_json_path(): + raise UnsupportedFeatureError( + dialect_name=type(self).__name__, + feature_name="JSON path expressions", + suggestion=( + "This dialect has no function for reading a JSON path on " + "this server version. Store the value as text and parse it " + "in Python, or use a backend that declares " + "supports_json_path()." + ), + ) + + # Dispatch note: the function-based fallback below emits JSON_EXTRACT / + # JSON_UNQUOTE(JSON_EXTRACT(...)), which is MySQL's shape. It is + # nonetheless the documented default for any dialect without arrow + # operators, and the core does not second-guess that here: a dialect + # whose server has no such functions must override + # format_json_function_expression with its own syntax (JSON_VALUE, + # GET_PATH, ...). Refusing in the core instead would break every + # dialect that legitimately relies on the default, which is a + # documented and tested behaviour. + # + # A dialect that forces ARROW on a backend without arrows still gets an + # error, from format_json_arrow_expression below. mode: JSONPathMode = getattr(expr, "mode", JSONPathMode.AUTO) if mode is JSONPathMode.ARROW: diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/pivot.py b/src/rhosocial/activerecord/backend/dialect/mixins/pivot.py index 2922a740c..7b4f68f10 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/pivot.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/pivot.py @@ -6,9 +6,10 @@ :meth:`format_pivot_value` and/or the whole formatter when their value semantics or extensions differ. """ -from typing import Any, List, Tuple, TYPE_CHECKING +from typing import Any, List, Tuple, Union, TYPE_CHECKING if TYPE_CHECKING: # pragma: no cover + from ...expression.bases import BaseExpression from ...expression.pivot import PivotExpression, UnpivotExpression @@ -27,7 +28,7 @@ def supports_unpivot(self) -> bool: """Whether the UNPIVOT clause is supported. Defaults to False.""" return False - def format_pivot_value(self, value: Any) -> Tuple[str, tuple]: + def format_pivot_value(self, value: "Union[BaseExpression, str, int, float]") -> Tuple[str, tuple]: """Render a single value in a PIVOT ``IN (...)`` list. Strings/numbers are rendered as inline SQL literals; expression diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/predicate.py b/src/rhosocial/activerecord/backend/dialect/mixins/predicate.py index 7f7eb076b..3128c56d9 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/predicate.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/predicate.py @@ -10,6 +10,7 @@ from ...expression.predicates import ( BetweenPredicate, ComparisonPredicate, + DistinctFromPredicate, InPredicate, IsBooleanPredicate, IsNullPredicate, @@ -26,8 +27,31 @@ class PredicateMixin: Formatting functions receive the expression instance only; every value they need was collected at expression construction time. + + Every formatter routes its result through :meth:`_with_alias`. A predicate + is not confined to a WHERE clause — ``LIKE`` also appears in a SELECT list, + inside ``CASE WHEN``, in a ``JOIN ... ON`` condition, and in DDL as a + ``CHECK`` constraint or a partial-index predicate — and in the projection + case the boolean needs a name like any other column. None of these + formatters did that before, so an aliased predicate silently lost its + alias and rendered a bare boolean. """ + def _with_alias(self, sql: str, expr: Any) -> str: + """Append ``AS `` when *expr* carries one. + + Args: + sql: The rendered predicate. + expr: The expression node, which may carry an alias. + + Returns: + The SQL, with the alias appended when present. + """ + alias = getattr(expr, "alias", None) + if not alias: + return sql + return f"{sql} AS {self.format_identifier(alias)}" + def format_comparison_predicate(self, expr: ComparisonPredicate) -> Tuple[str, tuple]: """Format a comparison predicate (``left right``). @@ -44,7 +68,7 @@ def format_comparison_predicate(self, expr: ComparisonPredicate) -> Tuple[str, t right_sql, right_params = expr.right.to_sql() if isinstance(expr.right, QueryExpression): right_sql = f"({right_sql})" - return f"{left_sql} {expr.op} {right_sql}", left_params + right_params + return self._with_alias(f"{left_sql} {expr.op} {right_sql}", expr), left_params + right_params def format_logical_predicate(self, expr: LogicalPredicate) -> Tuple[str, tuple]: """Format a logical predicate (AND/OR/NOT). @@ -57,14 +81,14 @@ def format_logical_predicate(self, expr: LogicalPredicate) -> Tuple[str, tuple]: """ if expr.op.upper() == "NOT" and len(expr.predicates) == 1: sql, params = expr.predicates[0].to_sql() - return f"NOT ({sql})", params + return self._with_alias(f"NOT ({sql})", expr), params parts = [] all_params: List[Any] = [] for predicate in expr.predicates: sql, params = predicate.to_sql() parts.append(sql) all_params.extend(params) - return f" {expr.op} ".join(parts), tuple(all_params) + return self._with_alias(f" {expr.op} ".join(parts), expr), tuple(all_params) def format_in_predicate(self, expr: InPredicate) -> Tuple[str, tuple]: """Format an ``IN`` predicate. @@ -81,11 +105,13 @@ def format_in_predicate(self, expr: InPredicate) -> Tuple[str, tuple]: # A Literal wrapping a collection renders as a value list; anything # else (e.g. a subquery) renders through its own to_sql(). if isinstance(expr.values, Literal) and isinstance(expr.values.value, (list, tuple, set)): - return self._format_in_value_list(expr_sql, expr_params, expr.values) + return self._format_in_value_list(expr, expr_sql, expr_params, expr.values) values_sql, values_params = expr.values.to_sql() - return f"{expr_sql} IN {values_sql}", expr_params + values_params + return self._with_alias(f"{expr_sql} IN {values_sql}", expr), expr_params + values_params - def _format_in_value_list(self, expr_sql: str, expr_params: tuple, literal) -> Tuple[str, Tuple]: + def _format_in_value_list( + self, expr: InPredicate, expr_sql: str, expr_params: tuple, literal + ) -> Tuple[str, Tuple]: """Render ``IN (…)`` for a :class:`Literal` wrapping a collection. The whole ``Literal`` is passed in rather than just its ``value`` @@ -98,12 +124,12 @@ def _format_in_value_list(self, expr_sql: str, expr_params: tuple, literal) -> T """ values = literal.value if not values: - return f"{expr_sql} IN ()", expr_params + return self._with_alias(f"{expr_sql} IN ()", expr), expr_params if literal.inline_literals: rendered = ", ".join(self.format_literal(value) for value in values) - return f"{expr_sql} IN ({rendered})", expr_params + return self._with_alias(f"{expr_sql} IN ({rendered})", expr), expr_params placeholders = ", ".join([self.get_parameter_placeholder()] * len(values)) - return f"{expr_sql} IN ({placeholders})", expr_params + tuple(values) + return self._with_alias(f"{expr_sql} IN ({placeholders})", expr), expr_params + tuple(values) def format_between_predicate(self, expr: BetweenPredicate) -> Tuple[str, tuple]: """Format a ``BETWEEN`` predicate. @@ -117,7 +143,9 @@ def format_between_predicate(self, expr: BetweenPredicate) -> Tuple[str, tuple]: expr_sql, expr_params = expr.expr.to_sql() low_sql, low_params = expr.low.to_sql() high_sql, high_params = expr.high.to_sql() - return f"{expr_sql} BETWEEN {low_sql} AND {high_sql}", expr_params + low_params + high_params + return self._with_alias( + f"{expr_sql} BETWEEN {low_sql} AND {high_sql}", expr + ), expr_params + low_params + high_params def format_is_null_predicate(self, expr: IsNullPredicate) -> Tuple[str, tuple]: """Format an ``IS [NOT] NULL`` predicate. @@ -130,7 +158,28 @@ def format_is_null_predicate(self, expr: IsNullPredicate) -> Tuple[str, tuple]: """ expr_sql, expr_params = expr.expr.to_sql() not_str = " NOT" if expr.is_not else "" - return f"{expr_sql} IS{not_str} NULL", expr_params + return self._with_alias(f"{expr_sql} IS{not_str} NULL", expr), expr_params + + def format_distinct_from_predicate(self, expr: DistinctFromPredicate) -> Tuple[str, tuple]: + """Format a NULL-safe ``IS [NOT] DISTINCT FROM`` predicate. + + The default is the standard spelling, which the backends that have it + (PostgreSQL, Firebird, Snowflake, BigQuery, SQL Server 2022+, SQLite + 3.39+) take as-is. A dialect that spells it differently overrides this + -- Oracle answers ``NOT LNNVL(a = b)``, because ``IS NOT DISTINCT FROM`` + is ``ORA-00908`` there -- and a dialect that has no such operator at all + is expected to **refuse** rather than substitute a different question. + + Args: + expr: Distinctness check exposing ``left``, ``right`` and ``is_not``. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + left_sql, left_params = expr.left.to_sql() + right_sql, right_params = expr.right.to_sql() + not_str = " NOT" if expr.is_not else "" + return self._with_alias(f"{left_sql} IS{not_str} DISTINCT FROM {right_sql}", expr), left_params + right_params def format_is_boolean_predicate(self, expr: IsBooleanPredicate) -> Tuple[str, tuple]: """Format an ``IS [NOT] TRUE/FALSE`` predicate. @@ -145,7 +194,7 @@ def format_is_boolean_predicate(self, expr: IsBooleanPredicate) -> Tuple[str, tu expr_sql, expr_params = expr.expr.to_sql() not_str = " NOT" if expr.is_not else "" bool_str = "TRUE" if expr.value else "FALSE" - return f"{expr_sql} IS{not_str} {bool_str}", expr_params + return self._with_alias(f"{expr_sql} IS{not_str} {bool_str}", expr), expr_params def format_exists_expression(self, expr: ExistsExpression) -> Tuple[str, tuple]: """Format an ``[NOT] EXISTS`` expression. @@ -158,7 +207,7 @@ def format_exists_expression(self, expr: ExistsExpression) -> Tuple[str, tuple]: """ subquery_sql, subquery_params = expr.subquery.to_sql() exists_clause = "NOT EXISTS" if expr.is_not else "EXISTS" - return f"{exists_clause} {subquery_sql}", subquery_params + return self._with_alias(f"{exists_clause} {subquery_sql}", expr), subquery_params def format_any_expression(self, expr: AnyExpression) -> Tuple[str, tuple]: """Format a quantified ``ANY`` comparison expression. @@ -177,7 +226,9 @@ def format_any_expression(self, expr: AnyExpression) -> Tuple[str, tuple]: array_params = (tuple(array_expr.value),) else: array_sql, array_params = array_expr.to_sql() - return f"({expr_sql} {expr.op} ANY{array_sql})", tuple(list(expr_params) + list(array_params)) + return self._with_alias( + f"({expr_sql} {expr.op} ANY{array_sql})", expr + ), tuple(list(expr_params) + list(array_params)) def format_all_expression(self, expr: AllExpression) -> Tuple[str, tuple]: """Format a quantified ``ALL`` comparison expression. @@ -196,7 +247,9 @@ def format_all_expression(self, expr: AllExpression) -> Tuple[str, tuple]: array_params = (tuple(array_expr.value),) else: array_sql, array_params = array_expr.to_sql() - return f"({expr_sql} {expr.op} ALL{array_sql})", tuple(list(expr_params) + list(array_params)) + return self._with_alias( + f"({expr_sql} {expr.op} ALL{array_sql})", expr + ), tuple(list(expr_params) + list(array_params)) def format_like_predicate(self, expr: LikePredicate) -> Tuple[str, tuple]: """Format a ``LIKE`` predicate. @@ -210,4 +263,6 @@ def format_like_predicate(self, expr: LikePredicate) -> Tuple[str, tuple]: """ expr_sql, expr_params = expr.expr.to_sql() pattern_sql, pattern_params = expr.pattern.to_sql() - return f"{expr_sql} {expr.op} {pattern_sql}", expr_params + pattern_params + return self._with_alias( + f"{expr_sql} {expr.op} {pattern_sql}", expr + ), expr_params + pattern_params diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/relation_source.py b/src/rhosocial/activerecord/backend/dialect/mixins/relation_source.py index c0b2ad8ea..ca40039ce 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/relation_source.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/relation_source.py @@ -23,7 +23,7 @@ are engine-specific and default to unsupported. """ -from typing import Any, List, Tuple, TYPE_CHECKING +from typing import Any, List, Tuple, Union, TYPE_CHECKING from ...expression.bases import BaseExpression from ...expression.objects import RelationObject @@ -148,7 +148,7 @@ def format_source_alias(self, sql: str, source: "TableSource") -> str: f"{self.format_identifier(source.alias, source.alias_need_quote)}" ) - def format_source_document(self, document: Any) -> Tuple[str, tuple]: + def format_source_document(self, document: Union[BaseExpression, str]) -> Tuple[str, tuple]: """Render the document a projection row source reads. ``JSON_TABLE`` and ``XMLTABLE`` are handed either an expression @@ -310,7 +310,7 @@ def format_json_table(self, source: "JsonTableSource") -> Tuple[str, tuple]: sql = f"JSON_TABLE({document_sql}, '{path}' COLUMNS({columns_sql}))" return self.format_source_alias(sql, source), params - def format_source_columns(self, columns: Any, render_column: Any) -> Tuple[str, tuple]: + def format_source_columns(self, columns: List[Any], render_column: Any) -> Tuple[str, tuple]: """Render a projection source's whole ``COLUMNS`` list. ``JSON_TABLE`` and ``XMLTABLE`` both take a list of column projections diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/string_ops.py b/src/rhosocial/activerecord/backend/dialect/mixins/string_ops.py new file mode 100644 index 000000000..2eff646a6 --- /dev/null +++ b/src/rhosocial/activerecord/backend/dialect/mixins/string_ops.py @@ -0,0 +1,83 @@ +# src/rhosocial/activerecord/backend/dialect/mixins/string_ops.py +"""Dialect mixins for the string operations that are nodes rather than calls. + +One node, one formatter, and the default is the spelling the majority of +backends share natively (measured 2026-10-09): ``REPEAT`` on PostgreSQL, MySQL, +MariaDB, ClickHouse and BigQuery, ``LPAD``/``RPAD`` on all of those plus +Oracle, Firebird and Snowflake. A dialect that lacks the function overrides the +formatter with an emulation **composed from ordinary nodes** -- SQLite does +exactly that -- rather than the factory assembling a SQL string no hook could +ever reach. +""" +from typing import Tuple, TYPE_CHECKING + +if TYPE_CHECKING: # pragma: no cover + from ...expression.advanced_functions import ( + LpadExpression, + RepeatExpression, + RpadExpression, + ) + + +class RepeatMixin: + """Mixin rendering ``REPEAT(expr, count)`` in the common spelling.""" + + def format_repeat_expression(self, expr: "RepeatExpression") -> Tuple[str, tuple]: + """Format a repeat node as ``REPEAT(expr, count)``. + + Args: + expr: Repeat expression exposing ``expr``, ``count`` and ``alias``. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + expr_sql, expr_params = expr.expr.to_sql() + count_sql, count_params = expr.count.to_sql() + sql = f"REPEAT({expr_sql}, {count_sql})" + if expr.alias: + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, tuple(expr_params) + tuple(count_params) + + +class LpadMixin: + """Mixin rendering ``LPAD(expr, length, pad)`` in the common spelling.""" + + def format_lpad_expression(self, expr: "LpadExpression") -> Tuple[str, tuple]: + """Format a left-pad node as ``LPAD(expr, length, pad)``. + + Args: + expr: Pad expression exposing ``expr``, ``length``, ``pad`` and + ``alias``. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + expr_sql, expr_params = expr.expr.to_sql() + length_sql, length_params = expr.length.to_sql() + pad_sql, pad_params = expr.pad.to_sql() + sql = f"LPAD({expr_sql}, {length_sql}, {pad_sql})" + if expr.alias: + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, tuple(expr_params) + tuple(length_params) + tuple(pad_params) + + +class RpadMixin: + """Mixin rendering ``RPAD(expr, length, pad)`` in the common spelling.""" + + def format_rpad_expression(self, expr: "RpadExpression") -> Tuple[str, tuple]: + """Format a right-pad node as ``RPAD(expr, length, pad)``. + + Args: + expr: Pad expression exposing ``expr``, ``length``, ``pad`` and + ``alias``. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + expr_sql, expr_params = expr.expr.to_sql() + length_sql, length_params = expr.length.to_sql() + pad_sql, pad_params = expr.pad.to_sql() + sql = f"RPAD({expr_sql}, {length_sql}, {pad_sql})" + if expr.alias: + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, tuple(expr_params) + tuple(length_params) + tuple(pad_params) diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/trim.py b/src/rhosocial/activerecord/backend/dialect/mixins/trim.py new file mode 100644 index 000000000..06572d1ea --- /dev/null +++ b/src/rhosocial/activerecord/backend/dialect/mixins/trim.py @@ -0,0 +1,41 @@ +# src/rhosocial/activerecord/backend/dialect/mixins/trim.py +"""Dialect mixin for the TRIM family of string expressions. + +One node, one formatter: :class:`~...expression.advanced_functions.TrimExpression` +renders through :meth:`format_trim_expression`, and the default is the standard +``TRIM([BOTH|LEADING|TRAILING] [chars] FROM expr)`` form. A dialect that spells +it differently overrides the formatter rather than assembling SQL by hand -- +SQLite does exactly that, because it parses no ``trim(... from ...)`` syntax +at all. +""" +from typing import Tuple, TYPE_CHECKING + +if TYPE_CHECKING: # pragma: no cover + from ...expression.advanced_functions import TrimExpression + + +class TrimMixin: + """Mixin rendering the standard TRIM expression.""" + + def format_trim_expression(self, expr: "TrimExpression") -> Tuple[str, Tuple]: + """Format a ``TRIM`` node in the standard SQL form. + + Args: + expr: Trim expression exposing ``expr``, ``chars``, ``direction`` + and an optional ``alias``. + + Returns: + Tuple of (SQL string, parameters tuple), carrying the operands' + parameters in order. + """ + target_sql, target_params = expr.expr.to_sql() + if expr.chars is not None: + chars_sql, chars_params = expr.chars.to_sql() + sql = f"TRIM({expr.direction} {chars_sql} FROM {target_sql})" + params = tuple(target_params) + tuple(chars_params) + else: + sql = f"TRIM({expr.direction} FROM {target_sql})" + params = tuple(target_params) + if expr.alias: + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, params diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/uuid.py b/src/rhosocial/activerecord/backend/dialect/mixins/uuid.py new file mode 100644 index 000000000..a4d36c4bc --- /dev/null +++ b/src/rhosocial/activerecord/backend/dialect/mixins/uuid.py @@ -0,0 +1,148 @@ +# src/rhosocial/activerecord/backend/dialect/mixins/uuid.py +"""Generic dialect mixin for UUID value expressions. + +Backends spell UUID generation, constants and casting differently, so this +mixin implements the three ``format_uuid_*`` methods in terms of a +``UUID_FUNCTION`` table that each dialect fills in. A dialect with no native +way to perform an operation leaves its entry out and reports the capability +as unsupported, which turns a render into an +:class:`~...dialect.exceptions.UnsupportedFeatureError` carrying a usable +suggestion rather than another backend's SQL. +""" + +from typing import Any, Dict, Tuple, TYPE_CHECKING + +from ..exceptions import UnsupportedFeatureError + +if TYPE_CHECKING: # pragma: no cover + from ...expression.uuid import ( + UUIDCastExpression, + UUIDConstantExpression, + UUIDGenerationExpression, + ) + + +class UUIDMixin: + """UUID value support: generation, constants and casting. + + A dialect opts in per operation. The default is honest absence: nothing is + claimed, and rendering raises with a suggestion pointing at the field + mixin, which generates UUIDs in Python and needs no database function. + """ + + #: SQL text for each operation. ``generation`` and ``cast`` map to a + #: format string (``{inner}`` is the operand for a cast); ``constant`` + #: maps to a per-constant mapping, e.g. + #: ``{"constant": {"nil": "...", "max": "..."}}``. An operation absent + #: from this mapping is unsupported. Subclasses override the attribute + #: rather than the methods. + UUID_SQL: Dict[str, Any] = {} + + #: How to phrase the failure for each operation. + UUID_SUGGESTIONS: Dict[str, str] = { + "generation": ( + "Generate the value in Python instead — `field/uuid.py` " + "(`UUIDMixin`) already does this with `uuid.uuid4()` and needs no " + "database function." + ), + "constant": ( + "Compare against a literal instead — the nil UUID is " + "'00000000-0000-0000-0000-000000000000' and the max UUID is " + "'ffffffff-ffff-ffff-ffff-ffffffffffff'." + ), + "cast": ( + "Cast in Python instead — `uuid.UUID(value)` validates the " + "text and raises ValueError on malformed input." + ), + } + + # ------------------------------------------------------------------ + # Capability probes + # ------------------------------------------------------------------ + + def supports_uuid_generation(self) -> bool: + """Whether the database can produce a UUID on its own.""" + return "generation" in self.UUID_SQL + + def supports_uuid_constant(self) -> bool: + """Whether the nil / max UUID constants are available as SQL.""" + return "constant" in self.UUID_SQL + + def supports_uuid_cast(self) -> bool: + """Whether text can be converted to a UUID in SQL.""" + return "cast" in self.UUID_SQL + + def _require_uuid(self, operation: str, feature: str) -> Any: + """Return the SQL declaration for *operation*, or raise. + + The declaration is a format string for ``generation`` and ``cast``, and + a per-constant mapping for ``constant``. + """ + sql = self.UUID_SQL.get(operation) + if sql is None: + raise UnsupportedFeatureError( + self.name, + feature, + self.UUID_SUGGESTIONS.get(operation, ""), + ) + return sql + + # ------------------------------------------------------------------ + # Formatters + # ------------------------------------------------------------------ + + def format_uuid_generation( + self, expr: "UUIDGenerationExpression" + ) -> Tuple[str, Tuple]: + """Render a fresh-UUID expression. + + Args: + expr: The UUIDGenerationExpression node. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + sql = self._require_uuid("generation", "UUID generation") + if getattr(expr, "alias", None): + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, () + + def format_uuid_constant(self, expr: "UUIDConstantExpression") -> Tuple[str, Tuple]: + """Render the nil or max UUID constant. + + Args: + expr: The UUIDConstantExpression node. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + constants = self._require_uuid("constant", "UUID constants") + sql = constants.get(expr.which) if isinstance(constants, dict) else None + if sql is None: + raise UnsupportedFeatureError( + self.name, + f"UUID {expr.which} constant", + self.UUID_SUGGESTIONS.get("constant", ""), + ) + if getattr(expr, "alias", None): + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, () + + def format_uuid_cast(self, expr: "UUIDCastExpression") -> Tuple[str, Tuple]: + """Render a text-to-UUID conversion. + + Args: + expr: The UUIDCastExpression node. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + template = self._require_uuid("cast", "UUID cast") + inner_sql, inner_params = expr.expression.to_sql() + sql = template.format(inner=inner_sql) + if getattr(expr, "alias", None): + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, inner_params + + +__all__ = ["UUIDMixin"] diff --git a/src/rhosocial/activerecord/backend/dialect/mixins/window.py b/src/rhosocial/activerecord/backend/dialect/mixins/window.py index e07785ef1..84fb64a4a 100644 --- a/src/rhosocial/activerecord/backend/dialect/mixins/window.py +++ b/src/rhosocial/activerecord/backend/dialect/mixins/window.py @@ -1,8 +1,11 @@ # src/rhosocial/activerecord/backend/dialect/mixins/window.py """Window function and WINDOW clause formatting for the dialect layer. -Provides capability probes and SQL rendering for window function calls, -window specifications, frames, and named window definitions. +Provides capability probes and SQL rendering for window specifications, +frames, and named window definitions. Function *calls* with an ``OVER`` +clause are rendered by :meth:`FunctionCallMixin.format_function_call`, which +composes this module's specification formatters; there is no separate +window-call formatter. """ from typing import Tuple, TYPE_CHECKING @@ -11,7 +14,6 @@ if TYPE_CHECKING: # pragma: no cover from ...expression.advanced_functions import ( - WindowFunctionCall, WindowSpecification, WindowFrameSpecification, WindowClause, @@ -36,58 +38,6 @@ def supports_window_frame_clause(self) -> bool: """ return False - def format_window_function_call(self, call: "WindowFunctionCall") -> Tuple[str, tuple]: - """Format a window function call. - - Args: - call: WindowFunctionCall exposing ``args``, ``function_name``, - ``window_spec``, and ``alias``. - - Returns: - Tuple of (SQL string, parameters tuple). - - Raises: - UnsupportedFeatureError: If window functions are unsupported. - """ - if not self.supports_window_functions(): - raise UnsupportedFeatureError(self.name, "window functions") - - all_params = [] - - # Format function arguments - arg_parts = [] - for arg in call.args: - if isinstance(arg, bases.BaseExpression): - arg_sql, arg_params = arg.to_sql() - arg_parts.append(arg_sql) - all_params.extend(arg_params) - else: - # Literal value - arg_parts.append(self.get_parameter_placeholder()) - all_params.append(arg) - - func_sql = f"{call.function_name}({', '.join(arg_parts)})" - - if call.window_spec is None: - # No window specification - sql = func_sql - else: - if isinstance(call.window_spec, str): - # Reference to named window - window_part = self.format_identifier(call.window_spec) - else: - # Inline window specification - window_spec_sql, window_spec_params = self.format_window_specification(call.window_spec) - window_part = f"({window_spec_sql})" if window_spec_sql else "()" - all_params.extend(window_spec_params) - - sql = f"{func_sql} OVER {window_part}" - - if call.alias: - sql = f"{sql} AS {self.format_identifier(call.alias)}" - - return sql, tuple(all_params) - def format_window_specification(self, spec: "WindowSpecification") -> Tuple[str, tuple]: """Format a window specification (PARTITION BY / ORDER BY / frame). diff --git a/src/rhosocial/activerecord/backend/dialect/protocols/__init__.py b/src/rhosocial/activerecord/backend/dialect/protocols/__init__.py index a4db03595..979d2d6bb 100644 --- a/src/rhosocial/activerecord/backend/dialect/protocols/__init__.py +++ b/src/rhosocial/activerecord/backend/dialect/protocols/__init__.py @@ -78,12 +78,13 @@ from .ddl.view.materialized_view import MaterializedViewSupport # --- Query features --- -from .query.datetime import DateTimeSupport +from .query.timestamp import TimestampSupport from .query.pivot import PivotSupport from .query.dql_order import DqlOrderSupport from .query.advanced_grouping import AdvancedGroupingSupport from .query.array import ArraySupport from .query.collation import CollationSupport +from .query.column_type import ColumnTypeSupport from .query.cte import CTESupport from .query.data_type import DataTypeSupport from .query.explain import ExplainSupport @@ -103,6 +104,7 @@ from .query.sql_function import SQLFunctionSupport from .query.temporal import TemporalTableSupport from .query.upsert import UpsertSupport +from .query.uuid import UUIDSupport from .query.wildcard import WildcardSupport from .query.window import WindowFunctionSupport @@ -153,8 +155,9 @@ "CreateTypeSupport", "CreateViewSupport", "DDLTypeSupport", + "ColumnTypeSupport", "DataTypeSupport", - "DateTimeSupport", + "TimestampSupport", "DqlOrderSupport", "DropDatabaseSupport", "DropDomainSupport", @@ -208,6 +211,7 @@ "TruncateSupport", "TypeObjectSupport", "UpsertSupport", + "UUIDSupport", "ViewObjectSupport", "WildcardSupport", "WindowFunctionSupport", diff --git a/src/rhosocial/activerecord/backend/dialect/protocols/query/__init__.py b/src/rhosocial/activerecord/backend/dialect/protocols/query/__init__.py index ee60b09c7..b3c69d658 100644 --- a/src/rhosocial/activerecord/backend/dialect/protocols/query/__init__.py +++ b/src/rhosocial/activerecord/backend/dialect/protocols/query/__init__.py @@ -10,6 +10,7 @@ """ from .collation import CollationSupport +from .column_type import ColumnTypeSupport from .data_type import DataTypeSupport from .cte import CTESupport from .window import WindowFunctionSupport @@ -21,6 +22,7 @@ from .join import JoinSupport from .array import ArraySupport from .json import JSONSupport +from .uuid import UUIDSupport from .explain import ExplainSupport from .graph import GraphSupport from .graph_table import GraphTableSupport @@ -39,6 +41,7 @@ "ArraySupport", "CTESupport", "CollationSupport", + "ColumnTypeSupport", "DataTypeSupport", "ExplainSupport", "FilterClauseSupport", @@ -57,6 +60,7 @@ "SetOperationSupport", "TemporalTableSupport", "UpsertSupport", + "UUIDSupport", "WildcardSupport", "WindowFunctionSupport", ] diff --git a/src/rhosocial/activerecord/backend/dialect/protocols/query/column_type.py b/src/rhosocial/activerecord/backend/dialect/protocols/query/column_type.py new file mode 100644 index 000000000..55f8aeeed --- /dev/null +++ b/src/rhosocial/activerecord/backend/dialect/protocols/query/column_type.py @@ -0,0 +1,50 @@ +# src/rhosocial/activerecord/backend/dialect/protocols/query/column_type.py +"""ColumnTypeSupport protocol. + +Re-exported from :mod:`rhosocial.activerecord.backend.dialect.protocols`; +see that package for the full protocol surface and the rules the conformance +tests enforce. +""" + +from typing import Any, Dict, Optional, Protocol, Type, TYPE_CHECKING, runtime_checkable + +if TYPE_CHECKING: # pragma: no cover + from ....expression.column_types import ColumnBase + + +@runtime_checkable +class ColumnTypeSupport(Protocol): + """Which column class each common Python type means on this dialect. + + The protocol answers two questions and chooses nothing. Choosing a class + for a field's annotation is the model layer's lookup: it normalises the + annotation against the keys of these tables and fails, naming the field, + when neither table answers. + + ``suggested_column_types()`` + The table the model layer reads when a field does not declare its own + column class. Keys are the common Python types the framework defines: + ``bool``, ``int``, ``float``, ``decimal.Decimal``, ``str``, ``bytes``, + ``bytearray``, ``datetime.date``, ``datetime.time``, + ``datetime.datetime``, ``datetime.timedelta``, ``uuid.UUID``, + ``dict``, ``list``, ``tuple``, ``set``, ``frozenset``, ``enum.Enum``. + **Every key must be answered.** A value is a + :class:`~...expression.column_types.ColumnBase` subclass, or ``None`` + for "this backend genuinely has no column class for it" — the last + resort, for a value no workaround can express, never a first answer. + A missing key is an omission, not a decision. + + ``suggested_extra_column_types()`` + The backend's own vocabulary. Keys are Python types the framework does + not model (a ``Point``, a ``complex``); values are ``ColumnBase`` + subclasses. A type the backend does not offer is simply absent. + + Both are methods, not class attributes, so the answer may depend on the + server version or build; both return fresh dicts so a caller cannot mutate + what later lookups will read. There is no inherited default: a table in + core would be a guess about a server core has never seen. + """ + + def suggested_column_types(self) -> Dict[Any, Optional[Type["ColumnBase"]]]: ... + + def suggested_extra_column_types(self) -> Dict[Any, Type["ColumnBase"]]: ... diff --git a/src/rhosocial/activerecord/backend/dialect/protocols/query/data_type.py b/src/rhosocial/activerecord/backend/dialect/protocols/query/data_type.py index 66d53ca2b..d5ad236d4 100644 --- a/src/rhosocial/activerecord/backend/dialect/protocols/query/data_type.py +++ b/src/rhosocial/activerecord/backend/dialect/protocols/query/data_type.py @@ -37,21 +37,28 @@ class DataTypeSupport(Protocol): ``format_data_type_(data_type)`` / ``supports_data_type_()`` **Naming-family contracts.** These per-type members cannot be enumerated in the Protocol — they are discovered by convention - from the type's generic ``name``. The two families must correspond - **1:1**: for every ``format_data_type_X`` a dialect implements it - MUST also implement ``supports_data_type_X() -> bool``, and vice - versa. The supported-type surface of a dialect is exactly the set - of these method pairs — there is no registry. + from the type's generic ``name``. The formatter is the declaration + of support: ``supports_data_types()`` derives the mapping from the + formatter family, and a ``supports_data_type_X() -> bool`` probe, + where a dialect owns one, is the only thing that may opt a rendered + name **out** (a version-gated feature — a number of backends' + ``_*`` probes do exactly that). Backends that keep the + pair keep the **1:1** discipline: for every ``format_data_type_X`` + a ``supports_data_type_X()``, and no probe without a formatter to + promise delivery. The supported-type surface of a dialect has no + registry beyond these members. Honesty principle (D10) ----------------------- A dialect that does not support a type simply does **not** implement - its ``format_data_type_X`` / ``supports_data_type_X`` pair — it never - fakes a formatter or hard-codes ``supports_data_type_X() -> False`` - for an unimplemented type. Dispatch on an unsupported type raises + its ``format_data_type_X`` — it never fakes a formatter, and never + hard-codes a ``supports_data_type_X() -> False`` probe for a type it + cannot render at all. Dispatch on an unsupported type raises ``TypeError`` (there is no ``format_data_type_`` to route to), - which is the honest "unsupported here" signal. + which is the honest "unsupported here" signal. Rendering a declaration + the formatter cannot express raises at render time, which is also a + legitimate state. Backend-specific protocol layering (D8) --------------------------------------- @@ -70,6 +77,44 @@ class DataTypeSupport(Protocol): Core never enumerates backend families; it only fixes the shape of the dispatch and the merge. + + Concept coverage (D9) + --------------------- + + The honesty principle above governs *how* a dialect says + "unsupported"; this rule governs *whether it has said anything at + all*. Every concrete concept in + :mod:`rhosocial.activerecord.backend.expression.types` must receive + one of two explicit answers from every dialect that implements this + protocol: + + * the concept is **rendered** — its ``format_data_type_`` + exists. (The formatter may still refuse *particular declarations* + with ``UnsupportedFeatureError`` plus a ``suggestion`` — a concept + the dialect models but cannot express every declaration of; that is + a refusal answer, not an absence.) + * the concept is **substituted** — an entry in + :meth:`suggested_data_types` names the class this dialect really + stores for it, so the caller reads the substitution instead of a + bare ``TypeError``. + + The two sets are disjoint: a rendered concept needs no substitute. + **Silence is not an answer.** A concept that is neither rendered nor + substituted reaches the caller as a ``TypeError`` with no route + forward, and the hole is invisible until someone happens to declare + that concept. + + This completeness is **per dialect and deliberately not audited by + core**: backends differ too much for one shared shape (a closed + short type list, a wide list with substitutes, semantic refusals). + Each backend's own test file should walk the core concepts — + **discovered, not listed**, so a concept added to core later cannot + slip past a stale list — and assert: the coverage above; that + rendered and substituted keys are disjoint; that every substitute + actually renders on the dialect; and that every suggested key still + names an existing concept, so a core rename cannot leave dead + entries. BigQuery's ``test_every_core_concept_is_declared`` is the + pattern to copy. """ @@ -138,8 +183,16 @@ def suggested_data_types(self) -> "Dict[str, type]": Contract: suggested keys and supported keys are **disjoint** — a type this dialect renders needs no suggestion. Suggestions only — - the user layer (ActiveRecord) decides whether to adopt them. Return - an empty dict when there is nothing to suggest (honesty principle). + the user layer (ActiveRecord) decides whether to adopt them. + + This map is one half of the **concept coverage** rule (D9, see the + class docstring): every core concept must be rendered or listed + here, and silence is not an answer. It is therefore **not** + optional politeness — an entry here is how a caller who declares a + concept this dialect stores some other way learns what to declare + instead. Return an empty dict when there is nothing to suggest — + which, under D9, says "this dialect renders every core concept it + was asked about", not "not yet filled in". """ ... # pragma: no cover diff --git a/src/rhosocial/activerecord/backend/dialect/protocols/query/datetime.py b/src/rhosocial/activerecord/backend/dialect/protocols/query/datetime.py deleted file mode 100644 index c3d67dc81..000000000 --- a/src/rhosocial/activerecord/backend/dialect/protocols/query/datetime.py +++ /dev/null @@ -1,22 +0,0 @@ -# src/rhosocial/activerecord/backend/dialect/protocols/query/datetime.py -"""Date and time arithmetic and extraction. - -The switches here are about precision rather than about whether date and time -functions exist at all: a fraction of a second is stored differently -depending on the engine, and only some of them keep it to microseconds. -""" - -from typing import Protocol, runtime_checkable - -@runtime_checkable -class DateTimeSupport(Protocol): - """Date and time expression support.""" - - def supports_microsecond_timestamp(self) -> bool: - """Whether a timestamp keeps microseconds. - - Engines differ: PostgreSQL does, MySQL only in some types, SQL Server - rounds to 100ns increments. An engine that rounds needs the fraction - formatted to match, so the value is declared rather than assumed. - """ - ... # pragma: no cover diff --git a/src/rhosocial/activerecord/backend/dialect/protocols/query/json.py b/src/rhosocial/activerecord/backend/dialect/protocols/query/json.py index 28dce0bd3..0c24b6281 100644 --- a/src/rhosocial/activerecord/backend/dialect/protocols/query/json.py +++ b/src/rhosocial/activerecord/backend/dialect/protocols/query/json.py @@ -11,7 +11,7 @@ from ....expression import bases if TYPE_CHECKING: # pragma: no cover - from ....expression import JSONExpression + from ....expression import JSONDocumentExpression @runtime_checkable @@ -48,7 +48,7 @@ def supports_json_table(self, dialect_options: Optional[Dict[str, Any]] = None) """ ... # pragma: no cover - def format_json_expression(self, expr: "JSONExpression") -> Tuple[str, Tuple]: + def format_json_expression(self, expr: "JSONDocumentExpression") -> Tuple[str, Tuple]: """ Format JSON expression. @@ -60,14 +60,14 @@ def format_json_expression(self, expr: "JSONExpression") -> Tuple[str, Tuple]: - ``JSONPathMode.AUTO``: use arrow if supported, else function-based Args: - expr: JSONExpression node carrying column, path, and operation info. + expr: JSONDocumentExpression node carrying column, path, and operation info. Returns: Tuple of (SQL string, parameters tuple) for the formatted expression. """ ... # pragma: no cover - def format_json_arrow_expression(self, expr: "JSONExpression") -> Tuple[str, Tuple]: + def format_json_arrow_expression(self, expr: "JSONDocumentExpression") -> Tuple[str, Tuple]: """ Force-arrow JSON path formatting. @@ -77,7 +77,7 @@ def format_json_arrow_expression(self, expr: "JSONExpression") -> Tuple[str, Tup """ ... # pragma: no cover - def format_json_function_expression(self, expr: "JSONExpression") -> Tuple[str, Tuple]: + def format_json_function_expression(self, expr: "JSONDocumentExpression") -> Tuple[str, Tuple]: """ Force-function JSON path formatting. diff --git a/src/rhosocial/activerecord/backend/dialect/protocols/query/timestamp.py b/src/rhosocial/activerecord/backend/dialect/protocols/query/timestamp.py new file mode 100644 index 000000000..31deba830 --- /dev/null +++ b/src/rhosocial/activerecord/backend/dialect/protocols/query/timestamp.py @@ -0,0 +1,30 @@ +# src/rhosocial/activerecord/backend/dialect/protocols/query/timestamp.py +"""Timestamp precision, and nothing else. + +The switch here is about precision rather than about whether date and time +functions exist at all: a fraction of a second is stored differently depending +on the engine, and only some of them keep it to microseconds. + +The date/time *operations* -- arithmetic, extraction, truncation -- live +elsewhere, in ``DateTimeMixin`` on the column side and in each dialect's own +formatters, so nothing about them belongs in this protocol. + +It is named for what it declares. It used to be ``DateTimeSupport``, which read +as "this dialect supports date-time operations" and so invited exactly the +wrong additions; ``TimestampSupport`` names the precision question it asks. +""" +from typing import Protocol, runtime_checkable + + +@runtime_checkable +class TimestampSupport(Protocol): + """Whether an engine's timestamp keeps microseconds.""" + + def supports_microsecond_timestamp(self) -> bool: + """Whether a timestamp keeps microseconds. + + Engines differ: PostgreSQL does, MySQL only in some types, SQL Server + rounds to 100ns increments. An engine that rounds needs the fraction + formatted to match, so the value is declared rather than assumed. + """ + ... # pragma: no cover diff --git a/src/rhosocial/activerecord/backend/dialect/protocols/query/uuid.py b/src/rhosocial/activerecord/backend/dialect/protocols/query/uuid.py new file mode 100644 index 000000000..8c0c75ddb --- /dev/null +++ b/src/rhosocial/activerecord/backend/dialect/protocols/query/uuid.py @@ -0,0 +1,84 @@ +# src/rhosocial/activerecord/backend/dialect/protocols/query/uuid.py +"""UUIDSupport protocol. + +Re-exported from :mod:`rhosocial.activerecord.backend.dialect.protocols`; +see that package for the full protocol surface and the rules the conformance +tests enforce. +""" + +from typing import Protocol, TYPE_CHECKING, Tuple, runtime_checkable + +if TYPE_CHECKING: # pragma: no cover + from ....expression.uuid import ( + UUIDCastExpression, + UUIDConstantExpression, + UUIDGenerationExpression, + ) + + +@runtime_checkable +class UUIDSupport(Protocol): + """Protocol for UUID value operations. + + Storage of a UUID is a separate concern: it belongs to ``DataType`` and + ``format_data_type_*``, and no member of this protocol reads it. A dialect + may support generation without a native UUID type, and vice versa. + + Each operation is reported independently, because backends differ + sharply — a handful have all three, some have generation only, and SQLite + has none of them (it generates UUIDs in Python). + """ + + def supports_uuid_generation(self) -> bool: + """Whether the database can produce a UUID on its own. + + False means :class:`UUIDGenerationExpression` raises + ``UnsupportedFeatureError`` at render time, with a suggestion to + generate the value in Python. + """ + ... # pragma: no cover + + def supports_uuid_constant(self) -> bool: + """Whether the nil / max UUID constants are available as SQL.""" + ... # pragma: no cover + + def supports_uuid_cast(self) -> bool: + """Whether text can be converted to a UUID in SQL. + + Backends disagree on whether malformed input raises, so a dialect that + implements this must document its behaviour. + """ + ... # pragma: no cover + + def format_uuid_generation(self, expr: "UUIDGenerationExpression") -> Tuple[str, Tuple]: + """Render a fresh-UUID expression. + + Args: + expr: UUIDGenerationExpression node. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + ... # pragma: no cover + + def format_uuid_constant(self, expr: "UUIDConstantExpression") -> Tuple[str, Tuple]: + """Render the nil or max UUID constant. + + Args: + expr: UUIDConstantExpression node. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + ... # pragma: no cover + + def format_uuid_cast(self, expr: "UUIDCastExpression") -> Tuple[str, Tuple]: + """Render a text-to-UUID conversion. + + Args: + expr: UUIDCastExpression node. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + ... # pragma: no cover \ No newline at end of file diff --git a/src/rhosocial/activerecord/backend/expression/__init__.py b/src/rhosocial/activerecord/backend/expression/__init__.py index 8227d2468..6dbef63a1 100644 --- a/src/rhosocial/activerecord/backend/expression/__init__.py +++ b/src/rhosocial/activerecord/backend/expression/__init__.py @@ -20,7 +20,18 @@ is_sql_query_and_params, ) from .executable import Executable -from .mixins import AliasableMixin +from .mixins import ( + AliasableMixin, + ArrayMixin, + DateTimeMixin, + StringToIntegerMixin, + JSONAccessorMixin, + StringPatternPredicateMixin, + StringValueMixin, + TemporalArithmeticMixin, + TranscendentalMixin, + build_json_path, +) from .literals import ( Identifier, ) @@ -32,9 +43,30 @@ RawSQLPredicate, BinaryArithmeticExpression, ) +from .column_types import ( + ColumnBase, + StringColumn, + IntegerColumn, + NumericColumn, + TimestampColumn, + BooleanColumn, + BinaryColumn, + UUIDColumn, + JSONColumn, + ArrayColumn, + XMLColumn, +) +from .uuid import ( + UUIDGenerationExpression, + UUIDConstantExpression, + UUIDCastExpression, +) from .core import ( Column, FunctionCall, + IntegerValueExpression, + StringValueExpression, + XMLValueExpression, Subquery, Literal, WildcardExpression, @@ -82,6 +114,7 @@ ) from .predicates import ( ComparisonPredicate, + DistinctFromPredicate, LogicalPredicate, LikePredicate, ILIKEExpression, @@ -90,20 +123,21 @@ IsNullPredicate, IsBooleanPredicate, ) -from .aggregates import ( - AggregateFunctionCall, -) from .advanced_functions import ( CaseExpression, ExistsExpression, + TrimExpression, + RepeatExpression, + LpadExpression, + RpadExpression, AnyExpression, AllExpression, WindowFrameSpecification, WindowSpecification, WindowDefinition, WindowClause, - WindowFunctionCall, - JSONExpression, + JSONDocumentExpression, + JSONTextExpression, JSONPathMode, ArrayExpression, OrderedSetAggregation, @@ -422,6 +456,15 @@ "Executable", # Mixins "AliasableMixin", + "ArrayMixin", + "StringPatternPredicateMixin", + "StringValueMixin", + "TemporalArithmeticMixin", + "TranscendentalMixin", + "StringToIntegerMixin", + "DateTimeMixin", + "JSONAccessorMixin", + "build_json_path", # Literals "Identifier", # Operators @@ -433,9 +476,28 @@ "BinaryArithmeticExpression", # Core expressions "Column", + # UUID value expressions + "UUIDGenerationExpression", + "UUIDConstantExpression", + "UUIDCastExpression", + # Type-narrowed column expressions + "ColumnBase", + "StringColumn", + "IntegerColumn", + "NumericColumn", + "TimestampColumn", + "BooleanColumn", + "BinaryColumn", + "UUIDColumn", + "JSONColumn", + "ArrayColumn", + "XMLColumn", "FunctionCall", "Subquery", "Literal", + "StringValueExpression", + "IntegerValueExpression", + "XMLValueExpression", "WildcardExpression", "QualifiedIdentifierExpression", # Collation expressions @@ -477,6 +539,7 @@ "XMLWhitespaceOption", # Predicates "ComparisonPredicate", + "DistinctFromPredicate", "LogicalPredicate", "LikePredicate", "ILIKEExpression", @@ -484,19 +547,22 @@ "BetweenPredicate", "IsNullPredicate", "IsBooleanPredicate", - # Aggregates - "AggregateFunctionCall", + # Aggregates and windows are FunctionCall; see core. # Advanced functions "CaseExpression", "ExistsExpression", + "TrimExpression", + "RepeatExpression", + "LpadExpression", + "RpadExpression", "AnyExpression", "AllExpression", "WindowFrameSpecification", "WindowSpecification", "WindowDefinition", "WindowClause", - "WindowFunctionCall", - "JSONExpression", + "JSONDocumentExpression", + "JSONTextExpression", "JSONPathMode", "ArrayExpression", "OrderedSetAggregation", diff --git a/src/rhosocial/activerecord/backend/expression/advanced_functions.py b/src/rhosocial/activerecord/backend/expression/advanced_functions.py index 3a25ba8f0..3d9d0b50a 100644 --- a/src/rhosocial/activerecord/backend/expression/advanced_functions.py +++ b/src/rhosocial/activerecord/backend/expression/advanced_functions.py @@ -4,23 +4,59 @@ JSON operations, and Array operations. """ from enum import Enum -from typing import Any, List, Optional, Union, TYPE_CHECKING +from typing import List, Optional, Union, TYPE_CHECKING -from .bases import BaseExpression, SQLPredicate, SQLValueExpression -from .core import Column, Subquery from .mixins import ( AliasableMixin, ArithmeticMixin, ComparisonMixin, - StringMixin, + JSONAccessorMixin, + NotANumberMixin, + StringPatternPredicateMixin, + StringToIntegerMixin, + StringValueMixin, TypeCastingMixin, ) + +from .bases import BaseExpression, SQLPredicate, SQLValueExpression +from .core import ( + Column, + JSONValueExpression, + StringValueExpression, + Subquery, +) + from .query_parts import OrderByClause if TYPE_CHECKING: # pragma: no cover from ..dialect import SQLDialectBase +class DeclaredValueType: + """Render this node itself rather than the call a value class would wrap. + + The typed value classes in :mod:`..core` are *wrappers*: they hold a node + and delegate ``to_sql`` to it, which is what lets one class stand for + ``length(x)``, ``min(name)`` and ``CURRENT_USER`` alike. The nodes here are + not wrappers -- ``EXTRACT``, ``col->'$.a'`` and ``CASE`` each have their own + formatter and their own fields -- so when such a node class declares the + value type it *is*, it needs the base implementation back rather than the + wrapper's delegation to a node it does not hold. + + Inheriting the value class is what makes the result readable off the + object: ``isinstance(expr, TimestampValueExpression)`` holds because the + class says so, not because a tag was attached after construction. + """ + + def to_sql(self): + """Render through this node's own ``format_method``. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + return BaseExpression.to_sql(self) + + class JSONPathMode(Enum): """How a JSON path expression should be rendered by the dialect. @@ -44,8 +80,102 @@ def from_value(cls, value) -> "JSONPathMode": raise TypeError(f"mode must be None, str, or JSONPathMode; got {type(value).__name__}") -class CaseExpression(ArithmeticMixin, ComparisonMixin, SQLValueExpression): - """Represents a CASE expression (e.g., CASE WHEN condition THEN result ELSE result END).""" +#: Value class -> the class standing for both a CASE and that value class. +#: Populated on first use by :meth:`CaseExpression._class_for`; see there for +#: why it is built at all and why it is kept. +_CASE_VALUE_CLASSES = {} + + +class CaseExpression( + DeclaredValueType, + ArithmeticMixin, + ComparisonMixin, + SQLValueExpression, +): + """Represents a CASE expression (e.g., CASE WHEN condition THEN result ELSE result END). + + A CASE answers with whatever its branches answer with, so the branches + decide it -- not the factory, which is handed the whole list rather than the + individual results. What each branch is is read off its own class, so + :func:`~...expression.column_types.value_class_of` is the question asked of + each one. + + **Agreement is over the branches, and a branch that says nothing is not a + contradiction.** ``CASE WHEN i THEN literal ELSE i`` is still an integer: + a ``Literal`` declares no kind, so it neither agrees nor disagrees, and what + matters is that the branches which *do* declare a kind declare the same one. + + When they agree, the node is built as an instance of the agreed value class + so the answer is readable off the object. When they disagree -- integer here + and float there -- the CASE is legal SQL that answers with neither kind, so + no typed wrapper is offered and the bare class stands for it. Guessing the + first branch or the widest would promise a surface the database does not + have, and "unknown" is a result the caller can handle. + + That is why this class declares no single value type of its own: the answer + is per-instance, and :class:`DeclaredValueType` keeps it rendering itself + whichever it turns out to be. + """ + + def __new__(cls, dialect=None, value=None, cases=None, else_result=None, alias=None): + """Build as the agreed value class, when the branches declare one. + + Returns an instance of a class that *is* both this CASE and the agreed + value class, or of ``cls`` alone when the branches disagree or none of + them declares a kind. :meth:`__init__` then runs against whichever came + back, so the state is set the same way either way. + + ``dialect`` is optional and the branches are optional because + ``copy.copy`` reconstructs through this: ``as_()`` returns a copy, and + that copy must not re-run the consensus check on branches it already + agreed about. Reconstruction passes no branches, so the copy keeps the + class it was made from -- which is the correct answer anyway, since + nothing about it changed. + """ + if cases is None and else_result is None and value is None: + return super().__new__(cls) + + from .column_types import value_class_of + + branches = [result for _condition, result in cases] + [else_result] + declared = {value_class_of(branch) for branch in branches} - {None} + if len(declared) != 1: + return super().__new__(cls) + agreed = declared.pop() + combined = cls._class_for(agreed) + # object.__new__, not combined.__new__: `combined` inherits this very + # __new__, which would recurse back through the consensus check. + return object.__new__(combined) + + @classmethod + def _class_for(cls, value_class): + """The class standing for both this CASE and *value_class*. + + Built once per value class and kept, because building it per expression + would make ``type(x)`` differ between two CASE expressions that answer + with the same thing -- which is the thing being fixed. + + The bases are ordered so that ``CaseExpression`` supplies the CASE + state and ``format_method``, :class:`DeclaredValueType` supplies the + rendering, and *value_class* supplies the operations and the value type. + The value class's own ``to_sql`` is deliberately *not* reached: it is a + wrapper delegating to a node this does not hold. + """ + try: + return _CASE_VALUE_CLASSES[value_class] + except KeyError: + combined = type( + f"Case{value_class.__name__}", + (cls, DeclaredValueType, value_class), + { + "__doc__": ( + f"A CASE whose branches agree the answer is a " + f"{value_class.__name__}, so it is one." + ) + }, + ) + _CASE_VALUE_CLASSES[value_class] = combined + return combined def __init__( self, @@ -55,7 +185,9 @@ def __init__( else_result: Optional["BaseExpression"] = None, alias: Optional[str] = None, ): - super().__init__(dialect) + # BaseExpression rather than super(): the agreed value class, when there + # is one, is a wrapper and would want a node to hold -- this is the node. + BaseExpression.__init__(self, dialect) self.value = value self.cases = cases or [] self.else_result = else_result @@ -207,53 +339,32 @@ def format_method(self) -> str: return "format_window_clause" -class WindowFunctionCall( - AliasableMixin, +class JSONDocumentExpression( + DeclaredValueType, + JSONValueExpression, ArithmeticMixin, - ComparisonMixin, - TypeCastingMixin, + JSONAccessorMixin, SQLValueExpression, ): - """ - Window function call, supporting inline window specification or named window reference - """ + """A JSON document reached by path -- ``->``. - def __init__( - self, - dialect: "SQLDialectBase", - function_name: str, - args: Optional[List[Union["BaseExpression", Any]]] = None, - window_spec: Optional[Union[WindowSpecification, str]] = None, - alias: Optional[str] = None, - ): - super().__init__(dialect) - self.function_name = function_name - self.args = args or [] - self.window_spec = window_spec - self.alias = alias + :meth:`~...expression.mixins.JSONAccessorMixin.json_value` returns one of + these and ``.json_value("b")`` must work on it, so the accessor mixin is + here as well as on :class:`~...expression.column_types.JSONColumn`. - @property - def format_method(self) -> str: - """The dialect formatting method that renders this expression.""" - return "format_window_function_call" + Not available: ``like`` / ``ilike``. Those apply to the text a scalar path + access returns, not to the document it navigated. Use + :meth:`~...expression.mixins.JSONAccessorMixin.json_path` for the text + form, which arrives as :class:`JSONTextExpression`. + Split from that sibling rather than sharing one class: the two operations + yield different types, and a single class could only offer the union of + their operations to both. -class JSONExpression( - AliasableMixin, - ArithmeticMixin, - ComparisonMixin, - StringMixin, - TypeCastingMixin, - SQLValueExpression, -): - """Represents JSON operations like json->, json->>. - - The *mode* parameter controls how the expression is rendered: - - ``JSONPathMode.AUTO`` (default / None): use arrow operators if the - dialect supports them, otherwise fall back to function-based formatting. - - ``JSONPathMode.ARROW``: force arrow operators (-> / ->>); raises - UnsupportedFeatureError if the dialect does not support them. - - ``JSONPathMode.FUNCTION``: force function-based formatting (e.g. JSON_EXTRACT). + It is a :class:`~...expression.core.JSONValueExpression` because that is what + a document is. It is not a *wrapper* holding one -- it has its own formatter + and its own fields -- so it says so with + :class:`DeclaredValueType` rather than inheriting the delegation. """ def __init__( @@ -265,7 +376,9 @@ def __init__( alias: Optional[str] = None, mode: Union[None, str, "JSONPathMode"] = None, ): - super().__init__(dialect) + # BaseExpression rather than super(): the value class this inherits is a + # wrapper and wants a node to hold, and this class is the node. + BaseExpression.__init__(self, dialect) self.column = column self.path = path self.operation = operation @@ -278,6 +391,32 @@ def format_method(self) -> str: return "format_json_expression" +class JSONTextExpression( + JSONDocumentExpression, + StringValueExpression, +): + """A JSON path access that yielded **text** -- ``->>``. + + The sibling of :class:`JSONDocumentExpression`, and the reason that one is + split from this: ``->`` hands back a document and ``->>`` hands back a + scalar, and they are different types with different operations. It used to + be one class whose ``operation`` decided the answer at construction, which + meant the operations on offer could not be read off the class -- a JSON + document would offer ``like``, because the one class could be either. + + Text is the narrower of the two, so chaining continues: ``->>`` yields a + scalar and a scalar cannot be navigated further. ``->`` yields a document + and can be, which is why this is the class that gains + :class:`~...expression.core.StringValueExpression` and its operations. + + One consequence of inheriting the document class is that the JSON accessors + stay reachable here too: ``DeclaredValueType`` renders the node and this + class does not hold one, so it cannot drop the mixin without also losing + ``json_value``. That is a known over-offer -- a scalar is not navigable -- + and it is stated in the test that covers it rather than papered over. + """ + + class ArrayExpression( AliasableMixin, ArithmeticMixin, @@ -309,6 +448,184 @@ def format_method(self) -> str: return "format_array_expression" +class TrimExpression( + AliasableMixin, + ComparisonMixin, + StringToIntegerMixin, + StringPatternPredicateMixin, + StringValueMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """Represents a ``TRIM`` expression as a node, not as assembled SQL. + + The node exists for one reason: the standard form is a syntax error on + SQLite, so the spelling has to be a dialect decision. When the factory + built a raw SQL string instead, no dialect hook could reach it -- the + string was already text by the time anyone could vote. As a node, the + standard form is the default rendering and SQLite overrides + ``format_trim_expression`` with its function forms. + + Attributes: + expr: The string expression to trim. + chars: Optional trim set; the core contract allows exactly one + character, and ``None`` means spaces. + direction: ``BOTH`` (default), ``LEADING`` or ``TRAILING``. + + Example: + >>> TrimExpression(dialect, Column(dialect, "name"), Literal(dialect, "x")).to_sql() + ("TRIM(BOTH ? FROM \"name\")", ('x',)) + """ + + def __init__( + self, + dialect: "SQLDialectBase", + expr: "BaseExpression", + chars: Optional["BaseExpression"] = None, + direction: str = "BOTH", + alias: Optional[str] = None, + ): + super().__init__(dialect) + self.expr = expr + self.chars = chars + self.direction = direction + self.alias = alias + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_trim_expression" + + +class RepeatExpression( + AliasableMixin, + ComparisonMixin, + StringToIntegerMixin, + StringPatternPredicateMixin, + StringValueMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """``REPEAT(expr, count)`` as a node, so the backends without the function + can emulate it structurally. + + Measured 2026-10-09: the function exists on PostgreSQL, MySQL, MariaDB, + ClickHouse and BigQuery, and on none of Oracle, Firebird or SQLite. The + emulation SQLite uses is ``REPLACE(HEX(ZEROBLOB(n)), '00', x)`` -- each + two-character ``00`` pair is one copy slot -- which the dialect formatter + composes from ordinary nodes. See :meth:`format_repeat_expression`. + + Attributes: + expr: The string to repeat. + count: Repetition count; negative means the empty string, which the + factory settles before a node exists. + """ + + def __init__( + self, + dialect: "SQLDialectBase", + expr: "BaseExpression", + count: "BaseExpression", + alias: Optional[str] = None, + ): + super().__init__(dialect) + self.expr = expr + self.count = count + self.alias = alias + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_repeat_expression" + + +class LpadExpression( + AliasableMixin, + ComparisonMixin, + StringToIntegerMixin, + StringPatternPredicateMixin, + StringValueMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """``LPAD(expr, length, pad)`` as a node, for the backends that lack it. + + Measured 2026-10-09: native on PostgreSQL, MySQL, MariaDB, Oracle, Firebird, + ClickHouse, Snowflake and BigQuery; absent on SQL Server and SQLite. The + SQLite emulation is a two-branch ``CASE`` (truncate when the string is + already long enough, otherwise append the padding and take the last + ``length`` characters), composed from ordinary nodes by the formatter -- see + :meth:`format_lpad_expression`. + + Attributes: + expr: The string to pad. + length: Target length; the input is truncated to it when longer. + pad: Non-empty padding string; an omitted pad is spelled out as one + space by the factory, because MySQL refuses the two-argument form + while MariaDB fills with spaces. + """ + + def __init__( + self, + dialect: "SQLDialectBase", + expr: "BaseExpression", + length: "BaseExpression", + pad: "BaseExpression", + alias: Optional[str] = None, + ): + super().__init__(dialect) + self.expr = expr + self.length = length + self.pad = pad + self.alias = alias + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_lpad_expression" + + +class RpadExpression( + AliasableMixin, + ComparisonMixin, + StringToIntegerMixin, + StringPatternPredicateMixin, + StringValueMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """``RPAD(expr, length, pad)`` as a node, for the backends that lack it. + + The mirror of :class:`LpadExpression`, and the cheaper one to emulate: a + single ``SUBSTR(expr || pad, 1, length)`` covers both padding and + truncation, because the pad repeats ``length`` times and the substring + takes at most that many characters. See :meth:`format_rpad_expression`. + """ + + def __init__( + self, + dialect: "SQLDialectBase", + expr: "BaseExpression", + length: "BaseExpression", + pad: "BaseExpression", + alias: Optional[str] = None, + ): + super().__init__(dialect) + self.expr = expr + self.length = length + self.pad = pad + self.alias = alias + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_rpad_expression" + + class OrderedSetAggregation( AliasableMixin, ArithmeticMixin, diff --git a/src/rhosocial/activerecord/backend/expression/aggregates.py b/src/rhosocial/activerecord/backend/expression/aggregates.py deleted file mode 100644 index 5475645a0..000000000 --- a/src/rhosocial/activerecord/backend/expression/aggregates.py +++ /dev/null @@ -1,64 +0,0 @@ -# src/rhosocial/activerecord/backend/expression/aggregates.py -""" -Expressions related to SQL aggregation, including aggregate function calls -and the base class for expressions that support filtering. -""" - -from typing import Optional, TYPE_CHECKING - -from .bases import SQLValueExpression -from .mixins import ( - AliasableMixin, - ArithmeticMixin, - ComparisonMixin, - TypeCastingMixin, -) - -if TYPE_CHECKING: # pragma: no cover - from .bases import SQLPredicate - from ..dialect import SQLDialectBase - - -class AggregateFunctionCall( - AliasableMixin, - ArithmeticMixin, - ComparisonMixin, - TypeCastingMixin, - SQLValueExpression, -): - """ - Represents a call to a SQL aggregate function, such as COUNT, SUM, AVG. - This class supports attaching a FILTER clause. - """ - - @property - def format_method(self) -> str: - """The dialect formatting method that renders this expression.""" - return "format_function_call" - - def __init__( - self, - dialect: "SQLDialectBase", - func_name: str, - *args, - is_distinct: bool = False, - alias: Optional[str] = None, - filter_predicate: Optional["SQLPredicate"] = None, - ): - super().__init__(dialect) - self.func_name = func_name - self.args = list(args) - self.is_distinct = is_distinct - self.alias = alias - self.filter_predicate: Optional["SQLPredicate"] = filter_predicate - - def filter(self, predicate: "SQLPredicate") -> "AggregateFunctionCall": - """ - Applies a FILTER (WHERE ...) clause to the aggregate expression. - If a filter already exists, it will be combined with the new one using AND. - """ - if self.filter_predicate: - self.filter_predicate = self.filter_predicate & predicate - else: - self.filter_predicate = predicate - return self diff --git a/src/rhosocial/activerecord/backend/expression/bases.py b/src/rhosocial/activerecord/backend/expression/bases.py index f073aa1dc..6a9402b61 100644 --- a/src/rhosocial/activerecord/backend/expression/bases.py +++ b/src/rhosocial/activerecord/backend/expression/bases.py @@ -19,7 +19,7 @@ else: from typing_extensions import TypeAlias # pragma: no cover -from .mixins import LogicalMixin +from .mixins import AliasableMixin, LogicalMixin # Type alias for the return type of to_sql() method # This alias represents the standard return format for all SQL expression objects: @@ -353,7 +353,9 @@ def get_params(self) -> Dict[str, Any]: warnings.warn( f"{self.__class__.__name__}.get_params(): cannot find attribute " f"'_{name}' or '{name}' for parameter '{name}'. " - "Override get_params() if the naming convention differs.", + "Store it under the parameter's name in __init__ - " + "get_params() is the single serialization path and is not " + "meant to be overridden.", stacklevel=2, ) continue @@ -381,9 +383,15 @@ def get_params(self) -> Dict[str, Any]: return params -class SQLPredicate(LogicalMixin, BaseExpression): - """ - Abstract base class for SQL expressions that return a boolean value (predicates). +class SQLPredicate(LogicalMixin, AliasableMixin, BaseExpression): + """Base class for SQL expressions that return a boolean value. + + Carries :class:`AliasableMixin` because a predicate is not confined to a + WHERE clause. ``LIKE`` and its relatives also appear in a SELECT list + (``SELECT name LIKE 'a%' AS is_apple``), inside ``CASE WHEN``, in a + ``JOIN ... ON`` condition, and in DDL as a ``CHECK`` constraint or a + partial-index predicate. In the projection case the result needs a name + like any other column, so the alias has to survive to the formatter. """ pass diff --git a/src/rhosocial/activerecord/backend/expression/collation.py b/src/rhosocial/activerecord/backend/expression/collation.py index f7b59e35e..e9ec164d7 100644 --- a/src/rhosocial/activerecord/backend/expression/collation.py +++ b/src/rhosocial/activerecord/backend/expression/collation.py @@ -11,7 +11,7 @@ AliasableMixin, ArithmeticMixin, ComparisonMixin, - StringMixin, + StringPatternPredicateMixin, TypeCastingMixin, ) @@ -23,7 +23,7 @@ class CollateExpression( AliasableMixin, ArithmeticMixin, ComparisonMixin, - StringMixin, + StringPatternPredicateMixin, TypeCastingMixin, SQLValueExpression, ): diff --git a/src/rhosocial/activerecord/backend/expression/column_types.py b/src/rhosocial/activerecord/backend/expression/column_types.py new file mode 100644 index 000000000..0533b49fd --- /dev/null +++ b/src/rhosocial/activerecord/backend/expression/column_types.py @@ -0,0 +1,430 @@ +# src/rhosocial/activerecord/backend/expression/column_types.py +"""Type-narrowed column expressions. + +A column reference is a value, and the operations a value supports depend on +what it holds. A numeric column can be added to; a text column can be +``LIKE``-matched; a JSON column can be navigated by path. Before this module +every :class:`~...expression.core.Column` carried every one of those +operations, so ``User.c.age.like('%x%')`` rendered happily against an integer +column and only failed at the database. + +The narrowing +------------- +Python cannot *remove* a mixin from a base class, so the families here are +**siblings** of each other under :class:`ColumnBase`, not subclasses of one +another. ``StringColumn(ColumnBase)`` and ``NumericColumn(ColumnBase)`` each +compose only the mixins their value type supports; there is no permissive +parent in between that they would inherit from. :class:`~...expression.core.Column` +is a sibling too — it keeps the full mixin set as the escape hatch for +columns whose type is not known (see its docstring). + +Nothing about the *storage* type appears here. A ``UUIDColumn`` is a +``UUIDColumn`` on every backend; how the value is stored is the DDL layer's +business (``DataType`` / ``format_data_type_*``), and the two never read each +other. See ``expression/types/__init__.py`` for the DDL-side boundary. +""" + +from typing import Optional, TYPE_CHECKING + +from .bases import SQLValueExpression +from .mixins import ( + AliasableMixin, + ArithmeticMixin, + BooleanLogicMixin, + NumericValueMixin, + TranscendentalMixin, + TemporalArithmeticMixin, + ArrayMixin, + ComparisonMixin, + DateTimeMixin, + JSONAccessorMixin, + NotANumberMixin, + NotComparableMixin, + NullTestMixin, + StringPatternPredicateMixin, + StringToIntegerMixin, + StringValueMixin, + TypeCastingMixin, +) + +from abc import ABCMeta, abstractmethod + +if TYPE_CHECKING: # pragma: no cover + from ..dialect import SQLDialectBase + + +class ColumnBase( + AliasableMixin, + NullTestMixin, + TypeCastingMixin, + SQLValueExpression, + metaclass=ABCMeta, +): + """Common base for every column expression. + + Carries only the operations that make sense for *any* value — aliasing, + null tests, casting and collation — plus the eight attributes + :meth:`SQLDialectBase.format_column` reads (``name`` / ``table`` / + ``schema_name`` / ``alias`` and their four ``*_need_quote`` flags). + + Comparison is deliberately **not** here. It used to be, which made + ``xml_col = xml_col`` an identity comparison in Python and a refused + predicate at the database. Every family that can be compared names + :class:`ComparisonMixin` for itself, and the XML family names + :class:`NotComparableMixin` instead. + + The rendering method is **abstract here**. A column class exists to say + what it holds, and the spelling it renders as is part of that statement, + so each concrete class answers :attr:`format_method` with its one line — + a subclass that forgets is a construction-time error rather than a column + that silently renders as nothing. + + A column's value type is the class itself. There is no tag, no label and + no per-instance override: ``StringColumn`` holds text, ``IntegerColumn`` + holds a whole number, and an operation is offered because the class mixes + in the mixin that provides it. Two classes that offer the same operations + are still two classes when they hold different things, and one class that + held two different things would be the bug. + """ + + def __init__( + self, + dialect: "SQLDialectBase", + name: str, + table: Optional[str] = None, + alias: Optional[str] = None, + schema_name: Optional[str] = None, + name_need_quote: bool = True, + alias_need_quote: bool = True, + schema_need_quote: bool = True, + table_need_quote: bool = True, + ): + super().__init__(dialect) + self.name_need_quote = name_need_quote + self.alias_need_quote = alias_need_quote + self.schema_need_quote = schema_need_quote + self.table_need_quote = table_need_quote + self.name = name + self.table = table + self.alias = alias + self.schema_name = schema_name + + @property + @abstractmethod + def format_method(self) -> str: + """The dialect formatting method that renders this expression. + + Abstract on the base: each concrete column class answers the + spelling for itself, next to the family it names. + """ + + def __repr__(self) -> str: + parts = [repr(self.name)] + if self.table: + parts.insert(0, f"{self.table}.") + return f"<{type(self).__name__} {''.join(parts)}>" + + +class StringColumn(ComparisonMixin, StringValueMixin, StringPatternPredicateMixin, StringToIntegerMixin, ColumnBase): + """A column holding text: comparison, ``LIKE`` / ``ILIKE``, casting. + + Not available: arithmetic. ``LIKE`` against a numeric column is a + database-side type error, so the framework no longer offers it. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + + +class NumericColumn(ComparisonMixin, ArithmeticMixin, NumericValueMixin, TranscendentalMixin, ColumnBase): + """A column holding a number: comparison and arithmetic. + + One class for every numeric width and precision: the operations are the + same whatever the value was declared as, and the difference between a + ``NUMERIC(18,4)`` and a ``DOUBLE PRECISION`` belongs to the DDL layer's + ``DataType``, which is a separate concern and never read from here. A + backend that models a numeric type of its own — a monetary amount, an + unsigned width — derives from this and inherits what it agrees with. + + Not available: ``LIKE`` / ``ILIKE``. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + + +class IntegerColumn(NumericColumn): + """A column holding a whole number. + + A subclass rather than a sibling of :class:`NumericColumn`: arithmetic on a + whole number is arithmetic, so there is nothing to redeclare. What differs + is the *result* — SQL keeps ``CEIL`` of a whole number a whole number, while + ``SQRT`` of one generally is not — and the result type is settled by the + operation's own declaration at run time (the math factories tag their + results through ``value_class_of``), not by a mixin arranged in the MRO. + + ``TranscendentalMixin`` is inherited and not withheld: ``log(2)`` is a legal + query the database will answer, and an integer behaving differently from the + float it widens to would be a difference the caller cannot see or explain. + A monetary column is different in kind rather than in width, and is the case + that leaves this mixin out. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + +class TimestampColumn(ComparisonMixin, TemporalArithmeticMixin, DateTimeMixin, ColumnBase): + + """A column holding a date/time. + + Adds the temporal surface — :meth:`~...mixins.DateTimeMixin.date_trunc`, + :meth:`~...mixins.DateTimeMixin.extract`, :meth:`~...mixins.DateTimeMixin.date_add` + and friends — so ``User.c.created_at.date_trunc("month")`` no longer + requires threading the dialect into a free function by hand. + + Arithmetic is interval-based: ``created_at + one_day`` is allowed, while + ``created_at + created_at`` is refused at construction (see + :class:`~...mixins.TemporalArithmeticMixin`). + + Not available: ``LIKE`` / ``ILIKE``. + + Renamed from ``DateTimeColumn``: the column layer models *values*, and the + value a ``DATETIME``/``TIMESTAMP`` column hands back is a point in time — + ``TimestampValueExpression``'s family. ``datetime`` is one vendor's spelling + for it (and the name of the Python type); the four storage flavours the + vendors really offer — civil date, civil time, instant, instant with zone — + are the DDL layer's ``DataType`` distinction and never read from here. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + +class BooleanColumn(BooleanLogicMixin, ComparisonMixin, ColumnBase): + + """A column holding a truth value: boolean algebra, comparison, casting. + + The boolean-domain surface a ``bool`` field is guaranteed: ``is_true()`` / + ``is_false()`` (three-valued-logic-correct, and spelled ``IS TRUE`` / + ``IS FALSE`` rather than ``= 1`` / ``= 0`` -- PostgreSQL rejects + ``boolean = integer`` outright), plus ``&`` / ``|`` / ``~`` for combining + and negating them. + + :class:`BooleanLogicMixin` is the reason the class is not just + ``ComparisonMixin``: those three operators are the same connectives + :class:`~...mixins.LogicalMixin` gives a *predicate*, applied here to a + value that is itself a truth value. The mixin is composed rather than + inherited for the reason every family here is -- a string column has no + ``AND``, and giving it one would be the guess the narrow classes exist to + avoid. + + Aggregates (``SUM`` / ``BOOL_AND``) are deliberately **not** here. Four + backends split on them -- PostgreSQL has no ``sum(boolean)`` while SQLite + has no ``BOOL_AND`` -- so there is no single expression that means "any" or + "all" everywhere; a caller that needs one states the backend-specific + spelling explicitly. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + +class BinaryColumn(ComparisonMixin, ColumnBase): + + """A column holding raw bytes: comparison, casting, collation.""" + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + +class UUIDColumn(ComparisonMixin, ColumnBase): + + """A column holding a UUID. + + Carries no UUID-specific operator, because portable SQL has none — a UUID + column supports exactly what any other value column does. The class + exists so the value family is visible (in reprs, in tests) and so a + backend that *does* have an operation for it has an + unambiguous home. Storage is the DDL layer's concern. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + +class JSONColumn(ComparisonMixin, JSONAccessorMixin, ColumnBase): + + """A column holding JSON: comparison, casting, and path access. + + Adds :meth:`~...mixins.JSONAccessorMixin.json_path` (scalar, terminal) + and :meth:`~...mixins.JSONAccessorMixin.json_value` (JSON, chainable). + + Not available: ``LIKE`` / ``ILIKE`` and arithmetic — those apply to the + text a path access *returns*, not to the document. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + +class ArrayColumn(ComparisonMixin, ArrayMixin, ColumnBase): + + """A column holding an array: :meth:`~...mixins.ArrayMixin.array_length` + and :meth:`~...mixins.ArrayMixin.unnest`.""" + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + +class XMLColumn(NotComparableMixin, NotANumberMixin, ColumnBase): + """A column holding an XML document: alias, null tests, casting — no comparison. + + The XML value surface is *not* the general value surface with a few + operations missing; it is a different shape. Every backend that has an XML + type refuses comparison on it: + + * PostgreSQL: ``SELECT ''::xml = ''::xml`` is + ``ERROR: operator does not exist: xml = xml``. Ordering and ``IN`` are + refused the same way; ``IS NULL`` / ``IS NOT NULL`` are accepted. + * SQL Server: "the xml data type cannot be compared or sorted" — its + documented limitation, and the reason ``xml`` columns reject ``=``, + ``<``, ``ORDER BY`` and ``GROUP BY``. + * Oracle: ``XMLType`` has no comparison operators either; equality is + expressed by SQL/XML functions (``XMLExists``, ``existsNode``), not by + ``=``. + + So this class carries what remains: aliasing, the null tests (the one test + those backends all accept), casting, and an explicit refusal of arithmetic + and comparison — the latter via :class:`NotComparableMixin`, because + Python resolves ``==`` / ``<`` on the type and a class that merely omitted + them would silently fall back to identity equality. + + **No Python annotation maps to this class yet.** A field annotated ``str`` + is a :class:`StringColumn`, even when its DDL type is ``XML``: the model + layer classifies by the Python value and this package deliberately models + no Python XML document type. The class exists + for the lattice — an operation that hands back an XML value from a column + has something to be typed as, casts to :class:`~...types.XmlType` land + here, and a backend that models its own XML column has a correct parent + to derive from. A future annotation is possible but is not this change: + the options are a third-party document class, bytes-as-document, or a + dedicated wrapper type, and choosing one is a modelling decision rather + than a mapping entry. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + + +def value_class_of(expr: object): + """The value class an operation handing *expr* back should be typed as. + + ``MIN`` of an integer column is an integer; ``MIN`` of a string column is a + string, and can still be compared and matched. ``LAG`` over a name is a + name. So when an operation answers with the thing it was given, this is + what it asks. It is read off the column *class* because that is where the + type already lives -- there is no tag to read and no attribute that + duplicates the class. + + Resolution walks the MRO, so a column class that narrows an existing one + (``IntegerColumn`` under ``NumericColumn``) is found under its own name and + a backend's own column class resolves through whichever core class it + derives from. + + ``None`` is a real answer rather than a failure. A ``Literal`` and an + untyped ``Column`` say nothing about what a database would hand back, so an + operation over them stays untyped instead of guessing: the caller who needs + a specific type says so with ``cast()``. + + The table is built on first use and kept. This module is imported by + :mod:`..core`, so building it at import time would need the value classes + from the module that imports this one. + """ + global _COLUMN_VALUE_CLASSES + if _COLUMN_VALUE_CLASSES is None: + _COLUMN_VALUE_CLASSES = _value_classes() + + for klass in type(expr).__mro__: + value_class = _COLUMN_VALUE_CLASSES.get(klass) + if value_class is not None: + return value_class + return None + + +#: Column class -> the value class an operation handing that column back is +#: typed as. Resolution walks the MRO, so a column class that narrows an +#: existing one is found under its own name: an ``IntegerColumn`` is a whole +#: number even though it is also a ``NumericColumn``. +#: +#: Every concrete column class this module declares is in here. The test that +#: says so lives beside the map and is why a class added without an entry is a +#: test failure rather than a silently untyped operation. +#: +#: ``TimestampColumn`` is the one judgement call: a column declared +#: ``DATETIME`` or ``TIMESTAMP`` holds a date and a time together, which is +#: what ``TimestampValueExpression`` is. A ``DATE`` or ``TIME`` column is a +#: different storage type in DDL and this module has no column class for +#: either -- the distinction between the four temporal types is made where +#: the value is known (see :class:`~...expression.datetime.ExtractExpression`), +#: not by guessing here. +def _value_classes(): + from . import core + + return { + IntegerColumn: core.IntegerValueExpression, + NumericColumn: core.NumericValueExpression, + StringColumn: core.StringValueExpression, + JSONColumn: core.JSONValueExpression, + ArrayColumn: core.ArrayValueExpression, + BooleanColumn: core.BooleanValueExpression, + BinaryColumn: core.BinaryValueExpression, + UUIDColumn: core.UUIDValueExpression, + TimestampColumn: core.TimestampValueExpression, + # XML is a value like the rest: the operations that hand one back (a + # column, xmlagg, a cast to XmlType) are typed, they just offer the + # surface an XML value has -- see XMLColumn. + XMLColumn: core.XMLValueExpression, + } + + +_COLUMN_VALUE_CLASSES = None + + +__all__ = [ + "ColumnBase", + "StringColumn", + "NumericColumn", + "IntegerColumn", + "TimestampColumn", + "BooleanColumn", + "BinaryColumn", + "UUIDColumn", + "JSONColumn", + "ArrayColumn", + "XMLColumn", + "value_class_of", +] diff --git a/src/rhosocial/activerecord/backend/expression/core.py b/src/rhosocial/activerecord/backend/expression/core.py index cf3f2d066..f495b1a3a 100644 --- a/src/rhosocial/activerecord/backend/expression/core.py +++ b/src/rhosocial/activerecord/backend/expression/core.py @@ -3,26 +3,44 @@ Core SQL expression components like columns, literals, function calls, and subqueries. """ -from typing import Any, Tuple, Optional, TYPE_CHECKING, Union +import copy +from typing import Any, Optional, Tuple, TYPE_CHECKING, Union -from .bases import BaseExpression, SQLQueryAndParams, SQLValueExpression, is_sql_query_and_params +from .bases import BaseExpression, SQLPredicate, SQLQueryAndParams, SQLValueExpression, is_sql_query_and_params +from .column_types import ColumnBase from .mixins import ( AliasableMixin, ArithmeticMixin, + BooleanLogicMixin, ComparisonMixin, - StringMixin, + ArrayMixin, + DateTimeMixin, + StringToIntegerMixin, + JSONAccessorMixin, + NotANumberMixin, + NotComparableMixin, + NullTestMixin, + NumericValueMixin, + ResultTypeMixin, + StringPatternPredicateMixin, + StringValueMixin, + TemporalArithmeticMixin, + TranscendentalMixin, TypeCastingMixin, + WrappedCallMixin, ) if TYPE_CHECKING: # pragma: no cover from ..dialect import SQLDialectBase + from .advanced_functions import WindowSpecification + from .types._base import DataType class Literal( AliasableMixin, ArithmeticMixin, ComparisonMixin, - StringMixin, + StringPatternPredicateMixin, TypeCastingMixin, SQLValueExpression, ): @@ -58,59 +76,618 @@ def __repr__(self) -> str: return f"Literal({self.value!r}, inline_literals={self.inline_literals!r})" -class Column( +class Column(ColumnBase): + """A column reference whose type is not known: it renders, and that is all. + + This is the **bare** column. Nothing established what it holds, so it + offers no operation at all — not comparison, not ``LIKE``, not arithmetic. + The previous shape (the whole operation set, on the theory that offering + less would be guessing) had the failure the typed classes exist to + prevent: a caller compared two of them and got Python's *identity* + answer, silently, instead of SQL. A bare reference that cannot say what + it holds cannot promise an operation the database will accept either, so + it promises nothing and the query layer builds its predicates + explicitly — :class:`~...expression.predicates.ComparisonPredicate`, + ``InPredicate``, ``IsNullPredicate`` — which work on any column because + they ask the *dialect*, not the column, for the SQL. + + Two things lead here: + + * **A string at a public entry point.** ``order_by("name")``, + ``count("price")`` and ``select("id")`` accept a column name as text. + The framework has no annotation to consult, so it cannot know what the + column holds. Pass the model proxy instead, ``order_by(User.c.name)``, + and the column arrives typed. + * **A model field whose annotation cannot be classified** (``Any``, an + unresolvable ``Union``) — the field's operations are unknown, and a + class that guessed them would be the bug the narrow classes prevent. + + An explicit ``UseColumnType(Column)`` declaration reaches this class too; + what it says is "render the reference and build predicates elsewhere". + When the type *is* known, + :class:`FieldProxy` + returns the narrow class instead, so ``User.c.age`` is an + :class:`~...expression.column_types.IntegerColumn` and offers no + ``.like()``. The class identity of a typed column does not vary by + backend; only its storage does. + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_column" + + +class TemporalValueExpression( + WrappedCallMixin, AliasableMixin, - ArithmeticMixin, ComparisonMixin, - StringMixin, + DateTimeMixin, + TemporalArithmeticMixin, TypeCastingMixin, SQLValueExpression, ): - """Represents a column in a SQL query. + """Shared base for the four temporal value types. + + A date, a time, a timestamp and an interval offer the same operations -- + ``date_add``, ``date_sub``, ``date_diff``, ``date_part``, ``extract`` -- and + none of them supports ``upper``, so the operations live here and the + subclasses say only which kind of temporal value they are. The arithmetic + they share is interval-based (:class:`TemporalArithmeticMixin`): a point in + time moves by an interval, two points subtract to an interval, and a plain + number never enters. + + They are four classes rather than one because they are four types. A + timestamp added to an interval is a timestamp; a span minus a span is a + span; and a year cannot be extracted from a span the way it is from a + point in time. With one class and a label those differences would have had + to be spelled as data, and the operations a caller could reach would be the + union of four unrelated ones. + + Subclasses exist so that ``current_date()`` and ``current_timestamp()`` + arrive already typed. Neither carries ``StringPatternPredicateMixin``: + a temporal value is not text. + """ - Per-role quoting properties (all default to ``True``): - - ``name_need_quote`` ↔ ``name`` - - ``table_need_quote`` ↔ ``table`` - - ``schema_need_quote`` ↔ ``schema_name`` - - ``alias_need_quote`` ↔ ``alias`` + def __init__( + self, + dialect: "SQLDialectBase", + call: "FunctionCall", + ): + super().__init__(dialect) + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + + +class DateValueExpression(TemporalValueExpression): + """A date with no time component. ``CURRENT_DATE`` answers with one.""" + + +class TimeValueExpression(TemporalValueExpression): + """A time of day. ``CURRENT_TIME`` answers with one.""" + + +class TimestampValueExpression(TemporalValueExpression): + """A date and a time together. ``NOW()`` and ``CURRENT_TIMESTAMP`` answer + with one, and adding an interval to it gives another.""" + + +class IntervalValueExpression(TemporalValueExpression): + """A span of time rather than a point in it. + + An interval is not a timestamp, which is why it is its own type here and + not a ``date_add`` argument that happens to be special. Its arithmetic is + the span's own: :class:`TemporalArithmeticMixin` adds and subtracts spans + into spans and scales one by a number, while a temporal value moves by a + span and two temporal values subtract into one. """ + +class JSONValueExpression( + WrappedCallMixin, + AliasableMixin, + ComparisonMixin, + JSONAccessorMixin, + TypeCastingMixin, + SQLValueExpression, +): + """A JSON document that is not a column reference. + + The result of json_build_object, json_array_elements and the aggregate that + assembles documents. Carries the JSON accessors, so a built document can + be walked the same way a column can — json_path is scalar and terminal, + json_value keeps a document to chain on.""" + + + def __init__( + self, + dialect: "SQLDialectBase", + call: "FunctionCall", + ): + super().__init__(dialect) + self.call = call + @property def format_method(self) -> str: - return "format_column" + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + + +class ArrayValueExpression( + WrappedCallMixin, + AliasableMixin, + ComparisonMixin, + ArrayMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """A sequence that is not a column reference. + + The result of unnest and of the aggregate that collects into one. Carries + the array operations, so a collected sequence can be measured or expanded + the same way a column can.""" + def __init__( self, dialect: "SQLDialectBase", - name: str, - table: Optional[str] = None, - alias: Optional[str] = None, - schema_name: Optional[str] = None, - name_need_quote: bool = True, - alias_need_quote: bool = True, - schema_need_quote: bool = True, - table_need_quote: bool = True, - ): + call: "FunctionCall", + ): super().__init__(dialect) - self.name_need_quote = name_need_quote - self.alias_need_quote = alias_need_quote - self.schema_need_quote = schema_need_quote - self.table_need_quote = table_need_quote - self.name = name - self.table = table - self.alias = alias - self.schema_name = schema_name + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + + +class BooleanValueExpression( + WrappedCallMixin, + AliasableMixin, + ComparisonMixin, + BooleanLogicMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """A true/false value that is not a column reference. + A boolean is a value, not a predicate, so it can be aliased, projected and + compared. Its connectives keep the value type + (:class:`BooleanLogicExpression`), so ``(a & b)`` is still selectable; + its comparisons yield predicates.""" + + + def __init__( + self, + dialect: "SQLDialectBase", + call: "FunctionCall", + ): + super().__init__(dialect) + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + + +class BooleanLogicExpression( + AliasableMixin, + ComparisonMixin, + BooleanLogicMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """``a AND b`` / ``a OR b`` / ``NOT a`` as a boolean **value**. + + A predicate and this expression render the same SQL; what differs is what + the caller may do with the result. Combining predicates stays a predicate + -- that is how ``WHERE`` clauses are built -- while a truth value keeps + its value type: ``(a & b)`` can be aliased into a ``SELECT`` list, + compared, cast, and combined further. The class carries the same ``op`` + and ``predicates`` shape + :class:`~...predicates.LogicalPredicate` does, so both go through the one + dialect entry point (``format_logical_predicate``). + """ + + def __init__(self, dialect: Any, op: str, *predicates: Any): + super().__init__(dialect) + self.op = op + # The names are the renderer's: the dialect formatter reads ``op`` and + # ``predicates`` whatever class carried them in, and the expression + # contract stores every ``__init__`` parameter under its own name. + self.predicates = list(predicates) + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_logical_predicate" + + +class BinaryValueExpression( + WrappedCallMixin, + AliasableMixin, + ComparisonMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """Raw bytes that are not a column reference. + + There is no byte operation to offer, so this carries comparisons and + casting. It exists so a function that returns bytes says so instead of being + unknown.""" + + + def __init__( + self, + dialect: "SQLDialectBase", + call: "FunctionCall", + ): + super().__init__(dialect) + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + + +class XMLValueExpression( + WrappedCallMixin, + AliasableMixin, + NotComparableMixin, + NullTestMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """An XML document that is not a column reference. + + Returned by the SQL/XML constructors, by the XML access operations, and by + a cast to :class:`~...types.XmlType`. Same wrapper shape as + :class:`BinaryValueExpression` -- it holds the call it was built from and + forwards its alias -- with one difference: an XML value cannot be compared. + + That is the whole surface of XML on the backends that have it. PostgreSQL + refuses ``xml = xml`` ("operator does not exist: xml = xml") along with + ordering and ``IN``; SQL Server documents that "the xml data type cannot + be compared or sorted"; Oracle's ``XMLType`` has no comparison operators + either. What they all accept is ``IS NULL``, which is why the null tests + :class:`NullTestMixin` provides stay while :class:`NotComparableMixin` + refuses the rest. Casting stays too: the way to ask a question of an XML + value is to cast it or to use a SQL/XML function, not to compare it. + """ + + + def __init__( + self, + dialect: "SQLDialectBase", + call: "FunctionCall", + ): + super().__init__(dialect) + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + + +class UUIDValueExpression( + WrappedCallMixin, + AliasableMixin, + ComparisonMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + """A UUID that is not a column reference. + + Same shape as the binary wrapper: comparisons and casting, and nothing to + extend with. A backend that cannot generate one raises at the factory rather + than returning an untyped node.""" + + + def __init__( + self, + dialect: "SQLDialectBase", + call: "FunctionCall", + ): + super().__init__(dialect) + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + + +class NumericValueExpression( + WrappedCallMixin, + AliasableMixin, + ArithmeticMixin, + ComparisonMixin, + NumericValueMixin, + TranscendentalMixin, + TypeCastingMixin, + SQLValueExpression, +): + """A fractional-valued expression that is not a column reference. + + The result of ``sqrt``, ``log``, ``abs`` on a fractional operand, ``avg``, + ``percent_rank`` and the other math functions. Carries arithmetic, so + numeric expressions compose, and comparisons, which every value can do. + Not the pattern predicates: ``LIKE`` is text matching, and a fraction is not + text, so ``sqrt(x).like('1%')`` fails here rather than at the database. + + ``ceil``, ``floor`` and ``truncate`` do *not* land here when the operand is + integral — a whole number rounded to a whole number is an integer, and + saying otherwise would offer ``bit_length`` on the result of ``ceil``. + """ + + + def __init__(self, dialect: "SQLDialectBase", call: "FunctionCall"): + super().__init__(dialect) + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + # as_() sets the alias on this wrapper, but the rendering happens in + # the wrapped call, which has its own alias and knows nothing about + # this one. Handing the alias down is what keeps `length().as_("n")` + # from silently rendering as a bare LENGTH(x). + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + +class IntegerValueExpression( + WrappedCallMixin, + AliasableMixin, + ArithmeticMixin, + ComparisonMixin, + NumericValueMixin, + TranscendentalMixin, + TypeCastingMixin, + SQLValueExpression, +): + + """An integer-valued expression that is not a column reference. + + Returned by the string operations whose result is a number — ``length``, + ``ascii``, ``strpos``, ``position``, ``octet_length``, ``bit_length`` — so + that ``col.length() > 5`` reads naturally and ``col.length().upper()`` + fails, which it should: there is no such thing as an upper-cased length. + + It carries :class:`ArithmeticMixin`, so integer arithmetic is available + and stays an integer. It carries comparisons, which every value can do, and + not the pattern predicates: ``LIKE`` is text matching, and a whole number is + not text. That absence is the point of the class — ``length().like("1%")`` + has to fail at the call, naming the operation, rather than be accepted here + and rejected by the server minutes later. + """ + + def __init__(self, dialect: "SQLDialectBase", call: "FunctionCall"): + super().__init__(dialect) + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + # as_() sets the alias on this wrapper, but the rendering happens in + # the wrapped call, which has its own alias and knows nothing about + # this one. Handing the alias down is what keeps `length().as_("n")` + # from silently rendering as a bare LENGTH(x). + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() + +class StringValueExpression( + WrappedCallMixin, + AliasableMixin, + ComparisonMixin, + StringToIntegerMixin, + StringPatternPredicateMixin, + StringValueMixin, + TypeCastingMixin, + NotANumberMixin, + SQLValueExpression, +): + + """A string-valued expression that is not a column reference. + + This is what makes the string value operations chain. ``col.upper()`` + returns one of these rather than a bare ``FunctionCall``, so the next + operation in the chain is available: ``col.upper().substr(0, 3)`` is + ``SUBSTRING(UPPER("name"), 1, 3)`` and the result is still a string. + + It is deliberately **not** a :class:`StringColumn`. A column names a field + and ``format_column`` reads ``name`` / ``table`` / ``schema_name``; a + derived value has none of those, so claiming to be a column would be a lie + about the object. What it shares with a string column is the *value type*, + which is what decides which operations are offered. + + The class mirrors :class:`~...expression.advanced_functions.JSONDocumentExpression`, + which plays the same role for the JSON family. + """ + + def __init__(self, dialect: "SQLDialectBase", call: "FunctionCall"): + super().__init__(dialect) + self.call = call + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_function_call" + + def to_sql(self): + """Render the wrapped function call. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + # as_() sets the alias on this wrapper, but the rendering happens in + # the wrapped call, which has its own alias and knows nothing about + # this one. Handing the alias down is what keeps `length().as_("n")` + # from silently rendering as a bare LENGTH(x). + alias = self.__dict__.get("alias") + if alias and getattr(self.call, "alias", None) != alias: + call = copy.copy(self.call) + call.alias = alias + return call.to_sql() + return self.call.to_sql() class FunctionCall( AliasableMixin, ArithmeticMixin, ComparisonMixin, - StringMixin, + StringPatternPredicateMixin, TypeCastingMixin, + ResultTypeMixin, SQLValueExpression, ): - """Represents a scalar SQL function call, such as LOWER, CONCAT, etc. + """Represents a SQL function call, scalar or aggregate, such as LOWER, CONCAT, COUNT, SUM. + + One node covers both because the grammar is one grammar: ``NAME(args)`` + gains ``DISTINCT``, a ``FILTER (WHERE ...)`` clause, an ``OVER (...)`` + window clause and an alias, in that order. What distinguishes an aggregate + is a fact about the call, not a shape of the SQL, and it is stated at + construction time by the aggregate factories (``is_aggregate=True``) + rather than inferred from the name. That fact is read only by RETURNING + validation, which must refuse an aggregate because a RETURNING clause is + evaluated per row; it is not a type and says nothing about what the call + yields. + + The typed result is said by the wrapper the factories return, not by this + node. + + Carries :class:`ResultTypeMixin` because this is the node that does *not* + know what it yields. Most functions state their own result by returning the + matching value class; the ones that cannot -- ``NULLIF`` and the + ``COALESCE``-shaped family -- come back as this, and the caller says what + they produce with ``.as_text()`` and friends. When niladic=True and no arguments are provided, the function call generates SQL without parentheses (e.g., CURRENT_TIMESTAMP instead of @@ -134,6 +711,9 @@ def __init__( is_distinct: bool = False, alias: Optional[str] = None, niladic: bool = False, + filter_predicate: Optional["SQLPredicate"] = None, + window_spec: Optional[Union["WindowSpecification", str]] = None, + is_aggregate: bool = False, ): super().__init__(dialect) self.func_name = func_name @@ -141,13 +721,47 @@ def __init__( self.is_distinct = is_distinct self.alias = alias self.niladic = niladic + self.filter_predicate = filter_predicate + self.window_spec = window_spec + self.is_aggregate = is_aggregate + + def filter(self, predicate: "SQLPredicate") -> "FunctionCall": + """Apply a ``FILTER (WHERE ...)`` clause to this call. + + A second call AND-combines with the filter already attached, so + ``call.filter(a).filter(b)`` states both conditions. Returns this + node, which is what the fluent chain continues on; note that a typed + wrapper around this node forwards the call and hands the node back, + so the result is untyped -- filtering does not re-type anything. + """ + if self.filter_predicate: + self.filter_predicate = self.filter_predicate & predicate + else: + self.filter_predicate = predicate + return self + + def over(self, window_spec: Union["WindowSpecification", str]) -> "FunctionCall": + """Attach an ``OVER (...)`` clause to this call. + + The working replacement for assigning ``window_spec`` on the object: + a typed wrapper stores an assignment on itself while rendering reads + the node it holds, so the assignment is a silent no-op there. This + method lives on the node, where the renderer looks. Returns this + node, so the fluent chain continues on it. + + *window_spec* is an inline :class:`WindowSpecification` or the name + of a window defined elsewhere in the query, which renders as an + identifier. + """ + self.window_spec = window_spec + return self class CastExpression( AliasableMixin, ArithmeticMixin, ComparisonMixin, - StringMixin, + StringPatternPredicateMixin, TypeCastingMixin, SQLValueExpression, ): @@ -159,11 +773,11 @@ class CastExpression( ``format_cast_expression``. Chained ``cast()`` calls therefore nest like any other expression — - ``expr.cast("A").cast("B")`` renders ``CAST(CAST(expr AS A) AS B)``. + ``expr.cast(A).cast(B)`` renders ``CAST(CAST(expr AS A) AS B)``. When the wrapped expression carries an alias, ``cast()`` hoists the alias onto the new node (the alias decorates the outermost rendered - form), so ``col.cast("INTEGER").as_("v")`` and - ``col.as_("v").cast("INTEGER")`` both render + form), so ``col.cast(IntegerType(dialect)).as_("v")`` and + ``col.as_("v").cast(IntegerType(dialect))`` both render ``CAST(col AS INTEGER) AS v``. """ @@ -176,11 +790,26 @@ def __init__( self, dialect: "SQLDialectBase", expression: "SQLValueExpression", - target_type: str, + target_type: "DataType", *, alias: Optional[str] = None, ): super().__init__(dialect) + from .types._base import DataType as _DataType + + if not isinstance(target_type, _DataType): + # The type position of CAST(expr AS type) is a grammar production, + # not an expression, so no bound parameter can be used there and a + # free-form string would be rendered straight into the statement. + # Requiring a DataType makes that impossible by construction rather + # than by validating a string that someone else can widen later. + raise TypeError( + f"cast() takes a DataType instance, not " + f"{type(target_type).__name__}. Use IntegerType(dialect) rather " + f"than a string: the type position cannot be bound, so a string " + f"is rendered into the SQL. A user-defined type is a DataType " + f"subclass, registered so dialects can render it." + ) self.expression = expression self.target_type = target_type self.alias = alias diff --git a/src/rhosocial/activerecord/backend/expression/datetime.py b/src/rhosocial/activerecord/backend/expression/datetime.py index 911e9bae4..f1868e62f 100644 --- a/src/rhosocial/activerecord/backend/expression/datetime.py +++ b/src/rhosocial/activerecord/backend/expression/datetime.py @@ -5,8 +5,20 @@ from enum import Enum from typing import Any, Dict, TYPE_CHECKING, Union -from .bases import BaseExpression, SQLValueExpression -from .mixins import AliasableMixin, ArithmeticMixin, ComparisonMixin, StringMixin, TypeCastingMixin +from .mixins import ( + AliasableMixin, + ComparisonMixin, + TypeCastingMixin, +) + +from .advanced_functions import DeclaredValueType +from .bases import BaseExpression, SQLQueryAndParams, SQLValueExpression +from .core import ( + IntegerValueExpression, + IntervalValueExpression, + NumericValueExpression, + TimestampValueExpression, +) if TYPE_CHECKING: # pragma: no cover from ..dialect import SQLDialectBase @@ -126,17 +138,49 @@ def validate_interval_value(value: Union[int, float]) -> Union[int, float]: class _TemporalValueExpression( AliasableMixin, - ArithmeticMixin, ComparisonMixin, - StringMixin, TypeCastingMixin, SQLValueExpression, ): - pass - - -class ExtractExpression(_TemporalValueExpression): - """Represents extraction of a datetime field from an expression.""" + """Shared base for the temporal operation nodes. + + No ``StringPatternPredicateMixin``: a date, a time, a timestamp and a span + are not text, so ``like`` is not an operation any of them offers. The same + goes for arithmetic here — these nodes render, they do not compose — so the + surface is what every value can do and nothing more. + + Each node below also names the value type it *produces*, by inheriting that + type's class alongside this one. Two consequences, both wanted: + + * What the operation yields is readable off the object — ``EXTRACT`` is a + :class:`~...expression.core.NumericValueExpression` because it derives + from one, not because a tag said so and a tag could disagree with the + class it sat on. + * The operations follow from it. ``extract("year") + 1`` composes because a + number composes, and ``date_trunc`` results can be truncated again because + a timestamp is a timestamp. + + Being a value class is not the same as being a *wrapper* of one. The value + classes hold a node and delegate rendering to it; these nodes are the nodes, + with their own formatters and their own fields, so each carries + :class:`~...expression.advanced_functions.DeclaredValueType` to keep the base + rendering and each binds its dialect through + :meth:`BaseExpression.__init__` rather than through ``super()``. + """ + + +class ExtractExpression(_TemporalValueExpression, DeclaredValueType, NumericValueExpression): + """``EXTRACT(field FROM source)`` -- a number. + + Numeric rather than integral because ``EXTRACT(EPOCH FROM ts)`` is + fractional. Widening here is deliberate: claiming a whole number would offer + ``bit_length`` on a value that may be a million and a half. + + It is a :class:`~...expression.core.NumericValueExpression` because that is + what it is, and that is why ``extract("year") + 1`` composes. The class + declares the type rather than a tag recording it, so ``isinstance`` answers + from the class alone. + """ def __init__( self, @@ -145,7 +189,7 @@ def __init__( source: BaseExpression, alias: str = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.field = normalize_datetime_field(field) self.source = source self.alias = alias @@ -156,8 +200,14 @@ def format_method(self) -> str: return "format_extract_expression" -class DatePartExpression(_TemporalValueExpression): - """Represents backend-specific date part extraction.""" +class DatePartExpression(_TemporalValueExpression, DeclaredValueType, NumericValueExpression): + """The SQL-standard spelling of :class:`ExtractExpression`, and a number too. + + Separate because a backend may render it differently, and because a caller + writing standard SQL should say so. Same answer, same class family: some + parts of a timestamp are whole numbers, but the unit decides, and a unit + this cannot rule out being fractional exists. + """ def __init__( self, @@ -166,7 +216,7 @@ def __init__( source: BaseExpression, alias: str = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.field = normalize_datetime_field(field) self.source = source self.alias = alias @@ -177,8 +227,13 @@ def format_method(self) -> str: return "format_date_part_expression" -class DateTruncExpression(_TemporalValueExpression): - """Represents truncating a datetime expression to a field.""" +class DateTruncExpression(_TemporalValueExpression, DeclaredValueType, TimestampValueExpression): + """Truncating a timestamp to a field gives a timestamp. + + Not an integer: the parts are dropped, not rounded away, so what comes back + is still a point in time and can still be compared, truncated again, or + added to. + """ def __init__( self, @@ -187,7 +242,7 @@ def __init__( source: BaseExpression, alias: str = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.field = normalize_datetime_field(field) self.source = source self.alias = alias @@ -198,8 +253,14 @@ def format_method(self) -> str: return "format_date_trunc_expression" -class IntervalExpression(_TemporalValueExpression): - """Represents a structured interval value.""" +class IntervalExpression(_TemporalValueExpression, DeclaredValueType, IntervalValueExpression): + """A structured interval value -- a span of time, its own type. + + Not a timestamp and not a number: ` +ow() + INTERVAL '1 day'`` is a + timestamp, and that is the operation the span exists to take part in. Its + own class is what says so, which is why ``date_add`` takes one. + """ def __init__( self, @@ -208,7 +269,7 @@ def __init__( unit: Union[str, IntervalUnit], alias: str = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.value = validate_interval_value(value) self.unit = normalize_interval_unit(unit) self.alias = alias @@ -219,8 +280,14 @@ def format_method(self) -> str: return "format_interval_expression" -class DateTimeAddExpression(_TemporalValueExpression): - """Represents adding an interval to a datetime expression.""" +class DateTimeAddExpression(_TemporalValueExpression, DeclaredValueType, TimestampValueExpression): + """Adding an interval to a timestamp gives a timestamp. + + Shifting time keeps it time. The result is a point in time, not a count of + anything, so it takes the same class the operand did -- which is what makes + ` +ow().date_add(1, "day").date_trunc("day")`` chain. + """ def __init__( self, @@ -229,7 +296,7 @@ def __init__( interval: IntervalExpression, alias: str = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.source = source self.interval = interval self.alias = alias @@ -240,8 +307,12 @@ def format_method(self) -> str: return "format_datetime_add_expression" -class DateTimeSubtractExpression(_TemporalValueExpression): - """Represents subtracting an interval from a datetime expression.""" +class DateTimeSubtractExpression(_TemporalValueExpression, DeclaredValueType, TimestampValueExpression): + """Subtracting an interval from a timestamp gives a timestamp. + + The mirror of :class:`DateTimeAddExpression`, and the same answer: going back + in time leaves you at a point in time. + """ def __init__( self, @@ -250,7 +321,7 @@ def __init__( interval: IntervalExpression, alias: str = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.source = source self.interval = interval self.alias = alias @@ -261,8 +332,16 @@ def format_method(self) -> str: return "format_datetime_subtract_expression" -class DateTimeDiffExpression(_TemporalValueExpression): - """Represents the difference between two datetime expressions.""" +class DateTimeDiffExpression(_TemporalValueExpression, DeclaredValueType, IntegerValueExpression): + """The difference between two timestamps, counted in whole units. + + This is the one temporal operation that is not a temporal value: ` +ow() - + now()`` is a count, not a point in time. Whole rather than fractional + because the unit is named -- ``DATEDIFF(day, a, b)`` counts days crossed, so + there is nothing here to be half of. The class is what says so, rather than a + tag distinguishing it from the operations that stay time. + """ def __init__( self, @@ -272,7 +351,7 @@ def __init__( end: BaseExpression, alias: str = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.unit = normalize_interval_unit(unit) self.start = start self.end = end diff --git a/src/rhosocial/activerecord/backend/expression/functions/_utils.py b/src/rhosocial/activerecord/backend/expression/functions/_utils.py deleted file mode 100644 index 6ac521b43..000000000 --- a/src/rhosocial/activerecord/backend/expression/functions/_utils.py +++ /dev/null @@ -1,32 +0,0 @@ -# src/rhosocial/activerecord/backend/expression/functions/_utils.py -"""Private utility functions for the functions package.""" - -from typing import Union, TYPE_CHECKING - -from ..bases import BaseExpression -from ..core import Column, Literal - -if TYPE_CHECKING: # pragma: no cover - from ...dialect import SQLDialectBase - - -def _convert_to_expression( - dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], handle_numeric_literals: bool = True -) -> "BaseExpression": - """ - Helper function to convert an input value to an appropriate BaseExpression. - - Args: - dialect: The SQL dialect instance - expr: The expression to convert. Can be a BaseExpression, string, or numeric value - handle_numeric_literals: Whether to treat numeric values as literals (True) or as column names (False) - - Returns: - A BaseExpression instance (BaseExpression, Literal, or Column) - """ - if isinstance(expr, BaseExpression): - return expr - elif handle_numeric_literals and isinstance(expr, (int, float)): - return Literal(dialect, expr) - else: - return Column(dialect, expr) diff --git a/src/rhosocial/activerecord/backend/expression/functions/aggregate.py b/src/rhosocial/activerecord/backend/expression/functions/aggregate.py index aa8814267..89b77a5bf 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/aggregate.py +++ b/src/rhosocial/activerecord/backend/expression/functions/aggregate.py @@ -4,20 +4,51 @@ from typing import Union, Optional, TYPE_CHECKING from ..bases import BaseExpression -from ..aggregates import AggregateFunctionCall -from ..core import Column, WildcardExpression -from ..operators import RawSQLExpression +from ..column_types import value_class_of +from ..core import ( + Column, + WildcardExpression, + FunctionCall, + IntegerValueExpression, + NumericValueExpression, +) if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase +def _typed(call: FunctionCall, target: BaseExpression): + """Wrap *call* in the value class matching *target*, when there is one. + + A reduction answers with the kind of thing it was given: the minimum of an + integer is an integer, the minimum of a float is a number, the minimum of a + string is a string and can still be compared and matched. The column class + already says which that is, so it is read off the class rather than off an + attribute duplicating it -- see + :func:`~...expression.column_types.value_class_of`. + + ``COUNT`` is the exception and always wraps in + :class:`IntegerValueExpression`, because a count is a count however wide the + thing counted. So is ``AVG``, which always wraps in + :class:`NumericValueExpression` because averaging whole numbers gives a + fraction; neither of those two goes through here. + + A target that says nothing -- a ``Literal``, an untyped ``Column`` -- leaves + the call untyped. That is the honest answer: the database decides, and the + caller who needs a specific type says so with ``cast()``. + """ + value_class = value_class_of(target) + if value_class is not None: + return value_class(call._dialect, call) + return call + + def count( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"] = "*", is_distinct: bool = False, alias: Optional[str] = None, -) -> "AggregateFunctionCall": +) -> "FunctionCall": """ Creates a COUNT aggregate function call. @@ -36,17 +67,20 @@ def count( alias: Optional alias for the result Returns: - An AggregateFunctionCall instance representing the COUNT function + A FunctionCall instance representing the COUNT function """ # Check if the passed expression is the string "*" if expr == "*" and isinstance(expr, str): - target_expr = RawSQLExpression(dialect, "*") + target_expr = WildcardExpression(dialect) # Check if the passed expression is a WildcardExpression elif isinstance(expr, WildcardExpression): target_expr = expr else: target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return AggregateFunctionCall(dialect, "COUNT", target_expr, is_distinct=is_distinct, alias=alias) + return IntegerValueExpression( + dialect, + FunctionCall(dialect, "COUNT", target_expr, is_distinct=is_distinct, alias=alias, is_aggregate=True), + ) def sum_( @@ -54,7 +88,7 @@ def sum_( expr: Union[str, "BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None, -) -> "AggregateFunctionCall": +) -> "FunctionCall": """ Creates a SUM aggregate function call. @@ -70,10 +104,20 @@ def sum_( alias: Optional alias for the result Returns: - An AggregateFunctionCall instance representing the SUM function + A FunctionCall instance representing the SUM function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return AggregateFunctionCall(dialect, "SUM", target_expr, is_distinct=is_distinct, alias=alias) + return _typed( + FunctionCall( + dialect, + "SUM", + target_expr, + is_distinct=is_distinct, + alias=alias, + is_aggregate=True, + ), + target_expr, + ) def avg( @@ -81,7 +125,7 @@ def avg( expr: Union[str, "BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None, -) -> "AggregateFunctionCall": +) -> "FunctionCall": """ Creates an AVG aggregate function call. @@ -97,15 +141,18 @@ def avg( alias: Optional alias for the result Returns: - An AggregateFunctionCall instance representing the AVG function + A FunctionCall instance representing the AVG function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return AggregateFunctionCall(dialect, "AVG", target_expr, is_distinct=is_distinct, alias=alias) + return NumericValueExpression( + dialect, + FunctionCall(dialect, "AVG", target_expr, is_distinct=is_distinct, alias=alias, is_aggregate=True), + ) def min_( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], alias: Optional[str] = None -) -> "AggregateFunctionCall": +) -> "FunctionCall": """ Creates a MIN aggregate function call. @@ -120,15 +167,15 @@ def min_( alias: Optional alias for the result Returns: - An AggregateFunctionCall instance representing the MIN function + A FunctionCall instance representing the MIN function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return AggregateFunctionCall(dialect, "MIN", target_expr, alias=alias) + return _typed(FunctionCall(dialect, "MIN", target_expr, alias=alias, is_aggregate=True), target_expr) def max_( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], alias: Optional[str] = None -) -> "AggregateFunctionCall": +) -> "FunctionCall": """ Creates a MAX aggregate function call. @@ -143,7 +190,7 @@ def max_( alias: Optional alias for the result Returns: - An AggregateFunctionCall instance representing the MAX function + A FunctionCall instance representing the MAX function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return AggregateFunctionCall(dialect, "MAX", target_expr, alias=alias) + return _typed(FunctionCall(dialect, "MAX", target_expr, alias=alias, is_aggregate=True), target_expr) diff --git a/src/rhosocial/activerecord/backend/expression/functions/array.py b/src/rhosocial/activerecord/backend/expression/functions/array.py index d6f25271c..32e32f920 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/array.py +++ b/src/rhosocial/activerecord/backend/expression/functions/array.py @@ -4,8 +4,13 @@ from typing import Union, Optional, TYPE_CHECKING from ..bases import BaseExpression -from ..aggregates import AggregateFunctionCall -from ..core import Column, FunctionCall, Literal +from ..core import ( + Column, + ArrayValueExpression, + IntegerValueExpression, + FunctionCall, + Literal, +) if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase @@ -16,20 +21,30 @@ def array_agg( expr: Union[str, "BaseExpression"], is_distinct: bool = False, alias: Optional[str] = None, -) -> "AggregateFunctionCall": - """Creates an ARRAY_AGG aggregate function call.""" +) -> "FunctionCall": + """Creates an ARRAY_AGG aggregate function call. + + The result is always an array -- gathering values produces a list of them, + whatever the gathered type was -- so this wraps in + :class:`ArrayValueExpression` rather than reading a type off the argument. + """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return AggregateFunctionCall(dialect, "ARRAY_AGG", target_expr, is_distinct=is_distinct, alias=alias) + return ArrayValueExpression( + dialect, + FunctionCall(dialect, "ARRAY_AGG", target_expr, is_distinct=is_distinct, alias=alias, is_aggregate=True), + ) -def unnest(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def unnest(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "ArrayValueExpression": """Creates an UNNEST function call.""" target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return FunctionCall(dialect, "UNNEST", target_expr) + return ArrayValueExpression(dialect, FunctionCall(dialect, 'UNNEST', target_expr)) -def array_length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], dimension: int = 1) -> "FunctionCall": +def array_length( + dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], dimension: int = 1 +) -> "IntegerValueExpression": """Creates an ARRAY_LENGTH function call.""" target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) dimension_expr = Literal(dialect, dimension) - return FunctionCall(dialect, "ARRAY_LENGTH", target_expr, dimension_expr) + return IntegerValueExpression(dialect, FunctionCall(dialect, 'ARRAY_LENGTH', target_expr, dimension_expr)) diff --git a/src/rhosocial/activerecord/backend/expression/functions/conditional.py b/src/rhosocial/activerecord/backend/expression/functions/conditional.py index 1834146db..b2f68dbc6 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/conditional.py +++ b/src/rhosocial/activerecord/backend/expression/functions/conditional.py @@ -1,16 +1,69 @@ # src/rhosocial/activerecord/backend/expression/functions/conditional.py """Conditional function factories.""" -from typing import Union, Optional, TYPE_CHECKING - -from ..bases import BaseExpression -from ..core import FunctionCall, Literal +from typing import Any, Union, Optional, TYPE_CHECKING, overload + +from ..bases import BaseExpression, SQLValueExpression +from ..column_types import ( + ArrayColumn, + BooleanColumn, + TimestampColumn, + IntegerColumn, + JSONColumn, + NumericColumn, + StringColumn, +) +from ..core import ( + ArrayValueExpression, + BooleanValueExpression, + TimestampValueExpression, + FunctionCall, + IntegerValueExpression, + JSONValueExpression, + Literal, + NumericValueExpression, + StringValueExpression, +) from ..advanced_functions import CaseExpression if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase +def _result_class_for(expr: object): + """The value class an operation over *expr* hands back, or ``None``. + + This is the answer to one question asked inside this module: *GREATEST* and + *NULLIF* both answer with the kind of thing they were given. Nothing in the + expression tree records that — it is what the *column class* already says, + so it is read off the class rather than off an attribute that duplicates it. + + ``None`` is a real answer, not a failure: a ``Literal`` and an + ``Column`` say nothing about what a database would hand back, so an + operation over them stays untyped rather than guessing. + + The checks are ordered narrowest-first because the numeric classes derive + from one another, and ``isinstance`` walks the MRO: an ``IntegerColumn`` + is a ``NumericColumn``, and it must be recognised as an integer before the + numeric branch sees it. + """ + if isinstance(expr, IntegerColumn): + return IntegerValueExpression + if isinstance(expr, StringColumn): + return StringValueExpression + if isinstance(expr, TimestampColumn): + return TimestampValueExpression + if isinstance(expr, JSONColumn): + return JSONValueExpression + if isinstance(expr, ArrayColumn): + return ArrayValueExpression + if isinstance(expr, BooleanColumn): + return BooleanValueExpression + if isinstance(expr, NumericColumn): + return NumericValueExpression + return None + + def case( dialect: "SQLDialectBase", value: Optional["BaseExpression"] = None, alias: Optional[str] = None ) -> "CaseExpression": @@ -28,16 +81,53 @@ def case( return CaseExpression(dialect, value=value, alias=alias) +def _widest(dialect: "SQLDialectBase", call: "FunctionCall", exprs: list) -> "SQLValueExpression": + """Give GREATEST/LEAST the type of its arguments when they agree on one. + + Every argument is a candidate for the result, so when they all answer with + the same kind the answer is that kind. When they disagree the operation is + legal SQL with no single answer -- GREATEST of an integer and a string is + neither -- and the call stays generic rather than guessing the first + argument or the widest, either of which would promise a surface the + database does not. + """ + classes = {_result_class_for(e) for e in exprs} + if len(classes) == 1 and None not in classes: + return classes.pop()(dialect, call) + return call + + +#: NULLIF gives back its first argument, or NULL when the two match, so the +#: result takes the type of the value rather than of the comparison. Overloads +#: say which one a caller passed; the third covers everything else. +@overload +def nullif( + dialect: "SQLDialectBase", value: IntegerColumn, null_value: Any +) -> "IntegerValueExpression": ... + + +@overload +def nullif( + dialect: "SQLDialectBase", value: NumericColumn, null_value: Any +) -> "NumericValueExpression": ... + + +@overload +def nullif( + dialect: "SQLDialectBase", value: Any, null_value: Any +) -> "SQLValueExpression": ... + + def nullif( - dialect: "SQLDialectBase", value: Union[str, "BaseExpression"], null_value: Union[str, "BaseExpression"] -) -> "FunctionCall": + dialect: "SQLDialectBase", value: Any, null_value: Any +) -> "SQLValueExpression": """ Creates a NULLIF scalar function call. Usage rules: - To generate NULLIF(column, null_val), pass Column objects: nullif(dialect, Column(dialect, "col1"), Column(dialect, "col2")) - - To generate NULLIF(?, ?), pass literal values + - To generate NULLIF(?, ?), pass literal values: nullif(dialect, "value", "null_value") Args: @@ -48,14 +138,21 @@ def nullif( If a BaseExpression is passed, it's used as-is. Returns: - A FunctionCall instance representing the NULLIF function + The type of *value*, since NULLIF returns it unless it matches. A literal + says nothing about its own type, so that case stays generic. """ value_expr = value if isinstance(value, BaseExpression) else Literal(dialect, value) null_expr = null_value if isinstance(null_value, BaseExpression) else Literal(dialect, null_value) - return FunctionCall(dialect, "NULLIF", value_expr, null_expr) + call = FunctionCall(dialect, "NULLIF", value_expr, null_expr) + result = _result_class_for(value_expr) + if result is not None: + return result(dialect, call) + return call -def greatest(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> "FunctionCall": +def greatest( + dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"] +) -> "SQLValueExpression": """ Creates a GREATEST scalar function call. @@ -71,13 +168,15 @@ def greatest(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> If BaseExpressions are passed, they're used as-is. Returns: - A FunctionCall instance representing the GREATEST function + The type its arguments agree on, or a generic FunctionCall if they do not """ target_exprs = [e if isinstance(e, BaseExpression) else Literal(dialect, e) for e in exprs] - return FunctionCall(dialect, "GREATEST", *target_exprs) + return _widest(dialect, FunctionCall(dialect, "GREATEST", *target_exprs), target_exprs) -def least(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> "FunctionCall": +def least( + dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"] +) -> "SQLValueExpression": """ Creates a LEAST scalar function call. @@ -93,7 +192,7 @@ def least(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> "F If BaseExpressions are passed, they're used as-is. Returns: - A FunctionCall instance representing the LEAST function + The type its arguments agree on, or a generic FunctionCall if they do not """ target_exprs = [e if isinstance(e, BaseExpression) else Literal(dialect, e) for e in exprs] - return FunctionCall(dialect, "LEAST", *target_exprs) + return _widest(dialect, FunctionCall(dialect, "LEAST", *target_exprs), target_exprs) diff --git a/src/rhosocial/activerecord/backend/expression/functions/datetime.py b/src/rhosocial/activerecord/backend/expression/functions/datetime.py index 1b0bd1e65..849a57217 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/datetime.py +++ b/src/rhosocial/activerecord/backend/expression/functions/datetime.py @@ -4,7 +4,16 @@ from typing import Union, Optional, TYPE_CHECKING from ..bases import BaseExpression -from ..core import Column, FunctionCall, Literal +from ..core import ( + Column, + DateValueExpression, + TemporalValueExpression, + TimeValueExpression, + TimestampValueExpression, + FunctionCall, + IntegerValueExpression, + Literal, +) from ..datetime import ( DatePartExpression, DateTimeAddExpression, @@ -14,13 +23,12 @@ ExtractExpression, IntervalExpression, ) -from ._utils import _convert_to_expression if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase -def now(dialect: "SQLDialectBase") -> "FunctionCall": +def now(dialect: "SQLDialectBase") -> "TemporalValueExpression": """ Creates a NOW scalar function call. @@ -28,12 +36,12 @@ def now(dialect: "SQLDialectBase") -> "FunctionCall": dialect: The SQL dialect instance Returns: - A FunctionCall instance representing the NOW function + A TimestampValueExpression wrapping NOW """ - return FunctionCall(dialect, "NOW") + return TimestampValueExpression(dialect, FunctionCall(dialect, 'NOW')) -def current_date(dialect: "SQLDialectBase") -> "FunctionCall": +def current_date(dialect: "SQLDialectBase") -> "TemporalValueExpression": """ Creates a CURRENT_DATE niladic value function. @@ -44,12 +52,12 @@ def current_date(dialect: "SQLDialectBase") -> "FunctionCall": dialect: The SQL dialect instance Returns: - A FunctionCall instance representing the CURRENT_DATE value function + A DateValueExpression wrapping CURRENT_DATE """ - return FunctionCall(dialect, "CURRENT_DATE", niladic=True) + return DateValueExpression(dialect, FunctionCall(dialect, 'CURRENT_DATE', niladic=True)) -def current_time(dialect: "SQLDialectBase") -> "FunctionCall": +def current_time(dialect: "SQLDialectBase") -> "TemporalValueExpression": """ Creates a CURRENT_TIME niladic value function. @@ -60,12 +68,12 @@ def current_time(dialect: "SQLDialectBase") -> "FunctionCall": dialect: The SQL dialect instance Returns: - A FunctionCall instance representing the CURRENT_TIME value function + A TimeValueExpression wrapping CURRENT_TIME """ - return FunctionCall(dialect, "CURRENT_TIME", niladic=True) + return TimeValueExpression(dialect, FunctionCall(dialect, 'CURRENT_TIME', niladic=True)) -def year(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def year(dialect: "SQLDialectBase", expr: "BaseExpression") -> "IntegerValueExpression": """ Creates a YEAR scalar function call. @@ -79,13 +87,13 @@ def year(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Func it's treated as a literal value. If a BaseExpression is passed, it's used as-is. Returns: - A FunctionCall instance representing the YEAR function + An IntegerValueExpression wrapping YEAR """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "YEAR", target_expr) + target_expr = expr + return IntegerValueExpression(dialect, FunctionCall(dialect, 'YEAR', target_expr)) -def month(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def month(dialect: "SQLDialectBase", expr: "BaseExpression") -> "IntegerValueExpression": """ Creates a MONTH scalar function call. @@ -100,13 +108,13 @@ def month(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Fun is passed, it's used as-is. Returns: - A FunctionCall instance representing the MONTH function + An IntegerValueExpression wrapping MONTH """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "MONTH", target_expr) + target_expr = expr + return IntegerValueExpression(dialect, FunctionCall(dialect, 'MONTH', target_expr)) -def day(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def day(dialect: "SQLDialectBase", expr: "BaseExpression") -> "IntegerValueExpression": """ Creates a DAY scalar function call. @@ -120,13 +128,13 @@ def day(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Funct it's treated as a literal value. If a BaseExpression is passed, it's used as-is. Returns: - A FunctionCall instance representing the DAY function + An IntegerValueExpression wrapping DAY """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "DAY", target_expr) + target_expr = expr + return IntegerValueExpression(dialect, FunctionCall(dialect, 'DAY', target_expr)) -def hour(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def hour(dialect: "SQLDialectBase", expr: "BaseExpression") -> "IntegerValueExpression": """ Creates an HOUR scalar function call. @@ -140,13 +148,13 @@ def hour(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Func it's treated as a literal value. If a BaseExpression is passed, it's used as-is. Returns: - A FunctionCall instance representing the HOUR function + An IntegerValueExpression wrapping HOUR """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "HOUR", target_expr) + target_expr = expr + return IntegerValueExpression(dialect, FunctionCall(dialect, 'HOUR', target_expr)) -def minute(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def minute(dialect: "SQLDialectBase", expr: "BaseExpression") -> "IntegerValueExpression": """ Creates a MINUTE scalar function call. @@ -160,13 +168,13 @@ def minute(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Fu it's treated as a literal value. If a BaseExpression is passed, it's used as-is. Returns: - A FunctionCall instance representing the MINUTE function + An IntegerValueExpression wrapping MINUTE """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "MINUTE", target_expr) + target_expr = expr + return IntegerValueExpression(dialect, FunctionCall(dialect, 'MINUTE', target_expr)) -def second(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def second(dialect: "SQLDialectBase", expr: "BaseExpression") -> "IntegerValueExpression": """ Creates a SECOND scalar function call. @@ -181,25 +189,27 @@ def second(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Fu If a BaseExpression is passed, it's used as-is. Returns: - A FunctionCall instance representing the SECOND function + An IntegerValueExpression wrapping SECOND """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "SECOND", target_expr) + target_expr = expr + return IntegerValueExpression(dialect, FunctionCall(dialect, 'SECOND', target_expr)) -def date_part(dialect: "SQLDialectBase", field: str, expr: Union[str, "BaseExpression"]) -> "DatePartExpression": +def date_part(dialect: "SQLDialectBase", field: str, expr: "BaseExpression") -> "DatePartExpression": """Creates a DATE_PART expression.""" - target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) + target_expr = expr return DatePartExpression(dialect, field, target_expr) -def date_trunc(dialect: "SQLDialectBase", field: str, expr: Union[str, "BaseExpression"]) -> "DateTruncExpression": +def date_trunc(dialect: "SQLDialectBase", field: str, expr: "BaseExpression") -> "DateTruncExpression": """Creates a DATE_TRUNC expression.""" - target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) + target_expr = expr return DateTruncExpression(dialect, field, target_expr) -def current_timestamp(dialect: "SQLDialectBase", precision: Optional[int] = None) -> "FunctionCall": +def current_timestamp( + dialect: "SQLDialectBase", precision: Optional[int] = None +) -> "TemporalValueExpression": """ Creates a CURRENT_TIMESTAMP niladic value function. @@ -216,14 +226,16 @@ def current_timestamp(dialect: "SQLDialectBase", precision: Optional[int] = None precision: Optional fractional seconds precision Returns: - A FunctionCall instance representing the CURRENT_TIMESTAMP value function + A TimeValueExpression wrapping CURRENT_TIMESTAMP """ if precision is not None: return FunctionCall(dialect, "CURRENT_TIMESTAMP", Literal(dialect, precision)) - return FunctionCall(dialect, "CURRENT_TIMESTAMP", niladic=True) + return TimestampValueExpression(dialect, FunctionCall(dialect, 'CURRENT_TIMESTAMP', niladic=True)) -def localtimestamp(dialect: "SQLDialectBase", precision: Optional[int] = None) -> "FunctionCall": +def localtimestamp( + dialect: "SQLDialectBase", precision: Optional[int] = None +) -> "TemporalValueExpression": """ Creates a LOCALTIMESTAMP niladic value function. @@ -240,16 +252,16 @@ def localtimestamp(dialect: "SQLDialectBase", precision: Optional[int] = None) - precision: Optional fractional seconds precision Returns: - A FunctionCall instance representing the LOCALTIMESTAMP value function + A TimestampValueExpression wrapping LOCALTIMESTAMP """ if precision is not None: return FunctionCall(dialect, "LOCALTIMESTAMP", Literal(dialect, precision)) - return FunctionCall(dialect, "LOCALTIMESTAMP", niladic=True) + return TimestampValueExpression(dialect, FunctionCall(dialect, 'LOCALTIMESTAMP', niladic=True)) -def extract(dialect: "SQLDialectBase", field: str, expr: Union[str, "BaseExpression"]) -> "ExtractExpression": +def extract(dialect: "SQLDialectBase", field: str, expr: "BaseExpression") -> "ExtractExpression": """Creates an EXTRACT expression.""" - target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) + target_expr = expr return ExtractExpression(dialect, field, target_expr) @@ -274,24 +286,24 @@ def _ensure_interval( def date_add( dialect: "SQLDialectBase", - expr: Union[str, "BaseExpression"], + expr: "BaseExpression", value_or_interval: Union[int, float, "IntervalExpression"], unit: Optional[str] = None, ) -> "DateTimeAddExpression": """Creates an expression that adds an interval to a datetime expression.""" - target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) + target_expr = expr interval_expr = _ensure_interval(dialect, value_or_interval, unit) return DateTimeAddExpression(dialect, target_expr, interval_expr) def date_sub( dialect: "SQLDialectBase", - expr: Union[str, "BaseExpression"], + expr: "BaseExpression", value_or_interval: Union[int, float, "IntervalExpression"], unit: Optional[str] = None, ) -> "DateTimeSubtractExpression": """Creates an expression that subtracts an interval from a datetime expression.""" - target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) + target_expr = expr interval_expr = _ensure_interval(dialect, value_or_interval, unit) return DateTimeSubtractExpression(dialect, target_expr, interval_expr) @@ -299,8 +311,8 @@ def date_sub( def date_diff( dialect: "SQLDialectBase", unit: str, - start_expr: Union[str, "BaseExpression"], - end_expr: Union[str, "BaseExpression"], + start_expr: "BaseExpression", + end_expr: "BaseExpression", ) -> "DateTimeDiffExpression": """Creates an expression for the difference between two datetime expressions.""" start = start_expr if isinstance(start_expr, BaseExpression) else Column(dialect, start_expr) diff --git a/src/rhosocial/activerecord/backend/expression/functions/json.py b/src/rhosocial/activerecord/backend/expression/functions/json.py index 63c24ac35..81326f4b2 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/json.py +++ b/src/rhosocial/activerecord/backend/expression/functions/json.py @@ -1,18 +1,22 @@ # src/rhosocial/activerecord/backend/expression/functions/json.py """JSON function factories.""" -from typing import Union, Optional, TYPE_CHECKING +from typing import Optional, TYPE_CHECKING from ..bases import BaseExpression -from ..aggregates import AggregateFunctionCall -from ..core import Column, FunctionCall, Literal -from ..advanced_functions import JSONExpression +from ..core import ( + Column, + JSONValueExpression, + FunctionCall, + Literal, +) +from ..advanced_functions import JSONDocumentExpression, JSONTextExpression if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase -def json_extract(dialect: "SQLDialectBase", column: Union[str, "BaseExpression"], path: str) -> "JSONExpression": +def json_extract(dialect: "SQLDialectBase", column: "BaseExpression", path: str) -> "JSONDocumentExpression": """ Creates a JSON extract operation (e.g., column->path). @@ -21,18 +25,18 @@ def json_extract(dialect: "SQLDialectBase", column: Union[str, "BaseExpression"] Args: dialect: The SQL dialect instance - column: The JSON column to extract from. If a string is passed, it's treated as a column name. - If a BaseExpression is passed, it's used as-is. + column: The JSON column to extract from, as an expression. A bare string is no + longer part of the contract; it is still coerced to a column at runtime. path: The JSON path to extract. Returns: - A JSONExpression instance representing the JSON extract operation + A JSONDocumentExpression instance representing the JSON extract operation """ target_column = column if isinstance(column, BaseExpression) else Column(dialect, column) - return JSONExpression(dialect, target_column, path, operation="->") + return JSONDocumentExpression(dialect, target_column, path, operation="->") -def json_extract_text(dialect: "SQLDialectBase", column: Union[str, "BaseExpression"], path: str) -> "JSONExpression": +def json_extract_text(dialect: "SQLDialectBase", column: "BaseExpression", path: str) -> "JSONTextExpression": """ Creates a JSON extract text operation (e.g., column->>path). @@ -42,18 +46,23 @@ def json_extract_text(dialect: "SQLDialectBase", column: Union[str, "BaseExpress Args: dialect: The SQL dialect instance - column: The JSON column to extract from. If a string is passed, it's treated as a column name. - If a BaseExpression is passed, it's used as-is. + column: The JSON column to extract from, as an expression. A bare string is no + longer part of the contract; it is still coerced to a column at runtime. path: The JSON path to extract as text. Returns: - A JSONExpression instance representing the JSON extract text operation + A JSONTextExpression instance representing the JSON extract text operation """ target_column = column if isinstance(column, BaseExpression) else Column(dialect, column) - return JSONExpression(dialect, target_column, path, operation="->>") + # `->>` yields text, so it arrives as JSONTextExpression and carries the + # string operations. It used to be built as a JSONDocumentExpression and described + # as a string by a tag, which meant the JSON accessors it was meant to end + # the chain with stayed reachable -- the node class served both arrow + # directions and could not drop them per instance. + return JSONTextExpression(dialect, target_column, path, operation="->>") -def json_build_object(dialect: "SQLDialectBase", *key_value_pairs: Union[str, "BaseExpression"]) -> "FunctionCall": +def json_build_object(dialect: "SQLDialectBase", *key_value_pairs: "BaseExpression") -> "JSONValueExpression": """ Creates a JSON_BUILD_OBJECT function call. @@ -64,19 +73,20 @@ def json_build_object(dialect: "SQLDialectBase", *key_value_pairs: Union[str, "B Args: dialect: The SQL dialect instance *key_value_pairs: Alternating sequence of key-value expressions. - Keys and values can be strings (literal) or BaseExpression. + Keys and values are expressions. A bare string is no longer part of the + contract; it is still bound as a literal at runtime. Returns: - A FunctionCall instance representing the JSON_BUILD_OBJECT function + A JSONValueExpression wrapping JSON_BUILD_OBJECT """ # Expect alternating sequence of key-value expressions processed_args = [] for arg in key_value_pairs: processed_args.append(arg if isinstance(arg, BaseExpression) else Literal(dialect, arg)) - return FunctionCall(dialect, "JSON_BUILD_OBJECT", *processed_args) + return JSONValueExpression(dialect, FunctionCall(dialect, 'JSON_BUILD_OBJECT', *processed_args)) -def json_array_elements(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def json_array_elements(dialect: "SQLDialectBase", expr: "BaseExpression") -> "JSONValueExpression": """ Creates a JSON_ARRAY_ELEMENTS function call. @@ -86,33 +96,46 @@ def json_array_elements(dialect: "SQLDialectBase", expr: Union[str, "BaseExpress Args: dialect: The SQL dialect instance - expr: The JSON array expression. If a string is passed, it's treated as a column name. - If a BaseExpression is passed, it's used as-is. + expr: The JSON array expression, as an expression. A bare string is no longer part + of the contract; it is still coerced to a column at runtime. Returns: - A FunctionCall instance representing the JSON_ARRAY_ELEMENTS function + A JSONValueExpression wrapping JSON_ARRAY_ELEMENTS """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return FunctionCall(dialect, "JSON_ARRAY_ELEMENTS", target_expr) + return JSONValueExpression(dialect, FunctionCall(dialect, 'JSON_ARRAY_ELEMENTS', target_expr)) def json_objectagg( dialect: "SQLDialectBase", - key_expr: Union[str, "BaseExpression"], - value_expr: Union[str, "BaseExpression"], -) -> "AggregateFunctionCall": + key_expr: "BaseExpression", + value_expr: "BaseExpression", +) -> "FunctionCall": """Creates a JSON_OBJECTAGG aggregate function call.""" key_target = key_expr if isinstance(key_expr, BaseExpression) else Column(dialect, key_expr) value_target = value_expr if isinstance(value_expr, BaseExpression) else Column(dialect, value_expr) - return AggregateFunctionCall(dialect, "JSON_OBJECTAGG", key_target, value_target) + return JSONValueExpression( + dialect, + FunctionCall(dialect, "JSON_OBJECTAGG", key_target, value_target, is_aggregate=True), + ) def json_arrayagg( dialect: "SQLDialectBase", - expr: Union[str, "BaseExpression"], + expr: "BaseExpression", is_distinct: bool = False, alias: Optional[str] = None, -) -> "AggregateFunctionCall": +) -> "FunctionCall": """Creates a JSON_ARRAYAGG aggregate function call.""" target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return AggregateFunctionCall(dialect, "JSON_ARRAYAGG", target_expr, is_distinct=is_distinct, alias=alias) + return JSONValueExpression( + dialect, + FunctionCall( + dialect, + "JSON_ARRAYAGG", + target_expr, + is_distinct=is_distinct, + alias=alias, + is_aggregate=True, + ), + ) \ No newline at end of file diff --git a/src/rhosocial/activerecord/backend/expression/functions/math.py b/src/rhosocial/activerecord/backend/expression/functions/math.py index 83052a03b..b195b9b3e 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/math.py +++ b/src/rhosocial/activerecord/backend/expression/functions/math.py @@ -1,17 +1,38 @@ # src/rhosocial/activerecord/backend/expression/functions/math.py """Math function factories.""" -from typing import Union, Optional, TYPE_CHECKING +from typing import Union, Optional, TYPE_CHECKING, overload from ..bases import BaseExpression +from ..column_types import IntegerColumn, NumericColumn from ..core import FunctionCall, Literal -from ._utils import _convert_to_expression if TYPE_CHECKING: # pragma: no cover + from ..core import IntegerValueExpression, NumericValueExpression from ...dialect import SQLDialectBase -def abs_(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +#: ABS, ROUND, CEIL, FLOOR and TRUNCATE keep a whole number whole, so their +#: result depends on the input: the same call is an integer for an int column +#: and possibly a fraction for a float one. Overloads say so in the type rather +#: than leaving the caller to read an attribute back off the instance. +@overload +def abs_(dialect: "SQLDialectBase", expr: IntegerColumn) -> "IntegerValueExpression": ... + + +@overload +def abs_(dialect: "SQLDialectBase", expr: NumericColumn) -> "NumericValueExpression": ... + + +@overload +def abs_(dialect: "SQLDialectBase", expr: "BaseExpression") -> Union[ + "IntegerValueExpression", "NumericValueExpression" +]: ... + + +def abs_(dialect: "SQLDialectBase", expr: "BaseExpression") -> Union[ + "IntegerValueExpression", "NumericValueExpression" +]: """ Creates an ABS scalar function call. @@ -28,12 +49,41 @@ def abs_(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Func Returns: A FunctionCall instance representing the ABS function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "ABS", target_expr) + from ..core import IntegerValueExpression, NumericValueExpression + + target_expr = expr + call = FunctionCall(dialect, "ABS", target_expr) + # ABS of a whole number is a whole number, and of a fraction may not be. + # The column says which before anything runs, so this is a question about + # the type rather than about an attribute read back from the instance. + if isinstance(expr, IntegerColumn): + return IntegerValueExpression(dialect, call) + return NumericValueExpression(dialect, call) + + +#: ABS, ROUND, CEIL, FLOOR and TRUNCATE keep a whole number whole, so their +#: result depends on the input: the same call is an integer for an int column +#: and possibly a fraction for a float one. Overloads say so in the type rather +#: than leaving the caller to read an attribute back off the instance. +@overload +def round_(dialect: "SQLDialectBase", expr: IntegerColumn, + decimals: Optional[int] = ...) -> "IntegerValueExpression": ... + + +@overload +def round_(dialect: "SQLDialectBase", expr: NumericColumn, + decimals: Optional[int] = ...) -> "NumericValueExpression": ... + + +@overload +def round_(dialect: "SQLDialectBase", expr: "BaseExpression", + decimals: Optional[int] = ...) -> Union[ + "IntegerValueExpression", "NumericValueExpression" +]: ... def round_( - dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], decimals: Optional[int] = None + dialect: "SQLDialectBase", expr: "BaseExpression", decimals: Optional[int] = None ) -> "FunctionCall": """ Creates a ROUND scalar function call. @@ -51,14 +101,37 @@ def round_( Returns: A FunctionCall instance representing the ROUND function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) + from ..core import IntegerValueExpression, NumericValueExpression + + target_expr = expr + args = [target_expr] if decimals is not None: - decimals_expr = Literal(dialect, decimals) - return FunctionCall(dialect, "ROUND", target_expr, decimals_expr) - return FunctionCall(dialect, "ROUND", target_expr) + args.append(Literal(dialect, decimals)) + call = FunctionCall(dialect, "ROUND", *args) + if isinstance(expr, IntegerColumn): + return IntegerValueExpression(dialect, call) + return NumericValueExpression(dialect, call) + + +#: ABS, ROUND, CEIL, FLOOR and TRUNCATE keep a whole number whole, so their +#: result depends on the input: the same call is an integer for an int column +#: and possibly a fraction for a float one. Overloads say so in the type rather +#: than leaving the caller to read an attribute back off the instance. +@overload +def ceil(dialect: "SQLDialectBase", expr: IntegerColumn) -> "IntegerValueExpression": ... + + +@overload +def ceil(dialect: "SQLDialectBase", expr: NumericColumn) -> "NumericValueExpression": ... + +@overload +def ceil(dialect: "SQLDialectBase", expr: "BaseExpression") -> Union[ + "IntegerValueExpression", "NumericValueExpression" +]: ... -def ceil(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": + +def ceil(dialect: "SQLDialectBase", expr: "BaseExpression") -> "FunctionCall": """ Creates a CEIL scalar function call. @@ -74,11 +147,34 @@ def ceil(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Func Returns: A FunctionCall instance representing the CEIL function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "CEIL", target_expr) + target_expr = expr + from ..core import IntegerValueExpression, NumericValueExpression + + call = FunctionCall(dialect, "CEIL", target_expr) + if isinstance(expr, IntegerColumn): + return IntegerValueExpression(dialect, call) + return NumericValueExpression(dialect, call) + + +#: ABS, ROUND, CEIL, FLOOR and TRUNCATE keep a whole number whole, so their +#: result depends on the input: the same call is an integer for an int column +#: and possibly a fraction for a float one. Overloads say so in the type rather +#: than leaving the caller to read an attribute back off the instance. +@overload +def floor(dialect: "SQLDialectBase", expr: IntegerColumn) -> "IntegerValueExpression": ... + + +@overload +def floor(dialect: "SQLDialectBase", expr: NumericColumn) -> "NumericValueExpression": ... -def floor(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +@overload +def floor(dialect: "SQLDialectBase", expr: "BaseExpression") -> Union[ + "IntegerValueExpression", "NumericValueExpression" +]: ... + + +def floor(dialect: "SQLDialectBase", expr: "BaseExpression") -> "FunctionCall": """ Creates a FLOOR scalar function call. @@ -94,11 +190,16 @@ def floor(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Fun Returns: A FunctionCall instance representing the FLOOR function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "FLOOR", target_expr) + target_expr = expr + from ..core import IntegerValueExpression, NumericValueExpression + call = FunctionCall(dialect, "FLOOR", target_expr) + if isinstance(expr, IntegerColumn): + return IntegerValueExpression(dialect, call) + return NumericValueExpression(dialect, call) -def sqrt(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": + +def sqrt(dialect: "SQLDialectBase", expr: "BaseExpression") -> "NumericValueExpression": """ Creates a SQRT scalar function call. @@ -114,13 +215,16 @@ def sqrt(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Func Returns: A FunctionCall instance representing the SQRT function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "SQRT", target_expr) + target_expr = expr + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "SQRT", target_expr)) def power( - dialect: "SQLDialectBase", base: Union[str, "BaseExpression"], exponent: Union[str, "BaseExpression"] -) -> "FunctionCall": + dialect: "SQLDialectBase", base: "BaseExpression", exponent: "BaseExpression" +) -> "NumericValueExpression": """ Creates a POWER scalar function call. @@ -139,12 +243,15 @@ def power( Returns: A FunctionCall instance representing the POWER function """ - base_expr = _convert_to_expression(dialect, base, handle_numeric_literals=True) - exp_expr = _convert_to_expression(dialect, exponent, handle_numeric_literals=True) - return FunctionCall(dialect, "POWER", base_expr, exp_expr) + base_expr = base + exp_expr = exponent + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "POWER", base_expr, exp_expr)) -def exp(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def exp(dialect: "SQLDialectBase", expr: "BaseExpression") -> "NumericValueExpression": """ Creates an EXP scalar function call. @@ -160,15 +267,18 @@ def exp(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Funct Returns: A FunctionCall instance representing the EXP function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "EXP", target_expr) + target_expr = expr + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "EXP", target_expr)) def log( dialect: "SQLDialectBase", - expr: Union[str, "BaseExpression"], - base: Optional[Union[str, "BaseExpression"]] = None, -) -> "FunctionCall": + expr: "BaseExpression", + base: Optional["BaseExpression"] = None, +) -> "NumericValueExpression": """ Creates a LOG scalar function call. @@ -184,15 +294,32 @@ def log( Returns: A FunctionCall instance representing the LOG function + + Contract: + ``LOG(expr)`` is the **natural** logarithm and ``LOG(expr, base)`` takes + the base second. Measured 2026-10-09, the backends split on both edges: + the one-argument ``log`` is base 10 on PostgreSQL and natural on + MySQL, MariaDB, ClickHouse, SQL Server, BigQuery, Firebird and SQLite, + and the two-argument order is ``(base, expr)`` on PostgreSQL, MySQL, + MariaDB, Oracle, Firebird and Snowflake while this order matches SQL + Server, ClickHouse and BigQuery. Backends override the rendering; the + meaning is fixed here so the override stays a spelling difference and + never a semantic one. """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) + target_expr = expr if base is not None: - base_expr = _convert_to_expression(dialect, base, handle_numeric_literals=True) - return FunctionCall(dialect, "LOG", target_expr, base_expr) - return FunctionCall(dialect, "LOG", target_expr) + base_expr = base + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "LOG", target_expr, base_expr)) + from ..core import NumericValueExpression + return NumericValueExpression( + dialect, FunctionCall(dialect, "LOG", target_expr)) -def sin(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": + +def sin(dialect: "SQLDialectBase", expr: "BaseExpression") -> "NumericValueExpression": """ Creates a SIN scalar function call. @@ -208,11 +335,14 @@ def sin(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Funct Returns: A FunctionCall instance representing the SIN function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "SIN", target_expr) + target_expr = expr + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "SIN", target_expr)) -def cos(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def cos(dialect: "SQLDialectBase", expr: "BaseExpression") -> "NumericValueExpression": """ Creates a COS scalar function call. @@ -228,11 +358,14 @@ def cos(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Funct Returns: A FunctionCall instance representing the COS function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "COS", target_expr) + target_expr = expr + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "COS", target_expr)) -def tan(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def tan(dialect: "SQLDialectBase", expr: "BaseExpression") -> "NumericValueExpression": """ Creates a TAN scalar function call. @@ -248,15 +381,18 @@ def tan(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Funct Returns: A FunctionCall instance representing the TAN function """ - target_expr = _convert_to_expression(dialect, expr, handle_numeric_literals=True) - return FunctionCall(dialect, "TAN", target_expr) + target_expr = expr + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "TAN", target_expr)) def mod( dialect: "SQLDialectBase", - dividend: Union[int, float, "BaseExpression"], - divisor: Union[int, float, "BaseExpression"], -) -> "FunctionCall": + dividend: "BaseExpression", + divisor: "BaseExpression", +) -> "NumericValueExpression": """ Creates a MOD function call (modulo operation). @@ -274,16 +410,22 @@ def mod( Returns: A FunctionCall instance representing the MOD function """ - dividend_expr = dividend if isinstance(dividend, BaseExpression) else Literal(dialect, dividend) - divisor_expr = divisor if isinstance(divisor, BaseExpression) else Literal(dialect, divisor) - return FunctionCall(dialect, "MOD", dividend_expr, divisor_expr) + dividend_expr = dividend + divisor_expr = divisor + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "MOD", dividend_expr, divisor_expr)) -def sign(dialect: "SQLDialectBase", expr: Union[int, float, "BaseExpression"]) -> "FunctionCall": +def sign(dialect: "SQLDialectBase", expr: "BaseExpression") -> "NumericValueExpression": """ Creates a SIGN function call. - SQL:2003 standard function returning -1, 0, or 1. + The value is -1, 0 or 1, but the **result type follows the backend** + (measured 2026-10-09): PostgreSQL answers an integer argument with + ``double precision`` and a numeric one with ``numeric``, so the node is + tagged numeric rather than integer. Usage rules: - To generate SIGN(column): sign(dialect, Column(dialect, "column")) @@ -296,12 +438,36 @@ def sign(dialect: "SQLDialectBase", expr: Union[int, float, "BaseExpression"]) - Returns: A FunctionCall instance representing the SIGN function """ - target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "SIGN", target_expr) + target_expr = expr + from ..core import NumericValueExpression + + return NumericValueExpression( + dialect, FunctionCall(dialect, "SIGN", target_expr)) + + +#: ABS, ROUND, CEIL, FLOOR and TRUNCATE keep a whole number whole, so their +#: result depends on the input: the same call is an integer for an int column +#: and possibly a fraction for a float one. Overloads say so in the type rather +#: than leaving the caller to read an attribute back off the instance. +@overload +def truncate(dialect: "SQLDialectBase", expr: IntegerColumn, + precision: Optional[int] = ...) -> "IntegerValueExpression": ... + + +@overload +def truncate(dialect: "SQLDialectBase", expr: NumericColumn, + precision: Optional[int] = ...) -> "NumericValueExpression": ... + + +@overload +def truncate(dialect: "SQLDialectBase", expr: "BaseExpression", + precision: Optional[int] = ...) -> Union[ + "IntegerValueExpression", "NumericValueExpression" +]: ... def truncate( - dialect: "SQLDialectBase", expr: Union[int, float, "BaseExpression"], precision: Optional[int] = None + dialect: "SQLDialectBase", expr: "BaseExpression", precision: Optional[int] = None ) -> "FunctionCall": """ Creates a TRUNCATE function call. @@ -319,9 +485,24 @@ def truncate( Returns: A FunctionCall instance representing the TRUNCATE function + + Contract: + Truncation toward zero, distinct from :func:`round` on a negative + value. The core name stays ``TRUNCATE``; the rendered name is the + backend's (measured 2026-10-09): ``TRUNC`` on PostgreSQL, Oracle, + Firebird, BigQuery, SQLite and ClickHouse, ``TRUNCATE`` on MySQL, + MariaDB and Snowflake, and SQL Server has no scalar truncate at all, + spelling it ``ROUND(x, n, 1)``. MariaDB's own ``TRUNC`` returns NULL for + a numeric call -- present from 12.2, absent before -- so a gate there + has to key on the rendered name rather than the function name. """ - target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) + from ..core import IntegerValueExpression, NumericValueExpression + + target_expr = expr + args = [target_expr] if precision is not None: - precision_expr = Literal(dialect, precision) - return FunctionCall(dialect, "TRUNCATE", target_expr, precision_expr) - return FunctionCall(dialect, "TRUNCATE", target_expr) + args.append(Literal(dialect, precision)) + call = FunctionCall(dialect, "TRUNCATE", *args) + if isinstance(expr, IntegerColumn): + return IntegerValueExpression(dialect, call) + return NumericValueExpression(dialect, call) diff --git a/src/rhosocial/activerecord/backend/expression/functions/string.py b/src/rhosocial/activerecord/backend/expression/functions/string.py index e63654f47..41647e040 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/string.py +++ b/src/rhosocial/activerecord/backend/expression/functions/string.py @@ -4,14 +4,25 @@ from typing import Union, Optional, TYPE_CHECKING from ..bases import BaseExpression -from ..core import FunctionCall, Literal -from ..operators import BinaryExpression, RawSQLExpression +from ..core import ( + FunctionCall, + IntegerValueExpression, + Literal, + StringValueExpression, +) +from ..operators import BinaryExpression, StringConcatExpression if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase + from ..advanced_functions import ( + LpadExpression, + RepeatExpression, + RpadExpression, + TrimExpression, + ) -def concat(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> "FunctionCall": +def concat(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> "StringValueExpression": """ Creates a CONCAT scalar function call. @@ -28,10 +39,10 @@ def concat(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> " A FunctionCall instance representing the CONCAT function """ target_exprs = [e if isinstance(e, BaseExpression) else Literal(dialect, e) for e in exprs] - return FunctionCall(dialect, "CONCAT", *target_exprs) + return StringValueExpression(dialect, FunctionCall(dialect, "CONCAT", *target_exprs)) -def coalesce(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> "FunctionCall": +def coalesce(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> "StringValueExpression": """ Creates a COALESCE scalar function call. @@ -48,10 +59,10 @@ def coalesce(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> A FunctionCall instance representing the COALESCE function """ target_exprs = [e if isinstance(e, BaseExpression) else Literal(dialect, e) for e in exprs] - return FunctionCall(dialect, "COALESCE", *target_exprs) + return StringValueExpression(dialect, FunctionCall(dialect, "COALESCE", *target_exprs)) -def length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "IntegerValueExpression": """ Creates a LENGTH scalar function call. @@ -68,7 +79,7 @@ def length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Fu A FunctionCall instance representing the LENGTH function """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "LENGTH", target_expr) + return IntegerValueExpression(dialect, FunctionCall(dialect, "LENGTH", target_expr)) def substring( @@ -94,13 +105,33 @@ def substring( Returns: A FunctionCall instance representing the SUBSTRING function - """ + + Raises: + ValueError: A literal *start* below 1, or a literal *length* below 0. + + Contract: + ``start`` is 1-based and ``length`` counts forward. Both edges were + measured across the ten backends (2026-10-09) and are refused here + rather than rendered, because the backends do not agree on what an + out-of-range argument means: a position below 1 is consumed by the + length on PostgreSQL, SQL Server, Firebird and SQLite, yields an empty + string on MySQL, MariaDB and ClickHouse, and is read as 1 on Oracle; a + negative length is an error on some backends, an empty string on + MySQL/MariaDB, NULL on Oracle and something unrelated again on + ClickHouse. + """ + if isinstance(start, int) and start < 1: + raise ValueError( + f"substring(): start must be >= 1 (positions are 1-based), got {start!r}" + ) + if isinstance(length, int) and length < 0: + raise ValueError(f"substring(): length must be >= 0, got {length!r}") target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) start_expr = start if isinstance(start, BaseExpression) else Literal(dialect, start) if length is not None: length_expr = length if isinstance(length, BaseExpression) else Literal(dialect, length) - return FunctionCall(dialect, "SUBSTRING", target_expr, start_expr, length_expr) - return FunctionCall(dialect, "SUBSTRING", target_expr, start_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "SUBSTRING", target_expr, start_expr, length_expr)) + return StringValueExpression(dialect, FunctionCall(dialect, "SUBSTRING", target_expr, start_expr)) def trim( @@ -108,9 +139,9 @@ def trim( expr: Union[str, "BaseExpression"], chars: Optional[Union[str, "BaseExpression"]] = None, direction: str = "BOTH", -) -> "RawSQLExpression": +) -> "TrimExpression": """ - Creates a TRIM scalar function call. + Creates a TRIM node. Usage rules: - To generate TRIM(BOTH FROM column), pass a Column object: trim(dialect, Column(dialect, "column_name")) @@ -120,31 +151,48 @@ def trim( dialect: The SQL dialect instance expr: The expression to trim. If a string is passed, it's treated as a literal value. If a BaseExpression is passed, it's used as-is. - chars: Optional characters to trim. If provided, treated as literal value if string. + chars: Optional single character to trim. If provided, treated as + literal value if string. direction: Direction of trim operation (BOTH, LEADING, TRAILING). Default is BOTH. Returns: - A RawSQLExpression instance representing the TRIM function + A :class:`~...expression.advanced_functions.TrimExpression` node, which + the dialect renders through its ``format_trim_expression`` hook. + + Raises: + ValueError: An unknown *direction*, or a trim set that is not exactly + one character. + + Contract: + The trim set is **one character**, which is what SQL:2016 feature + E021-09 (``trim( from ...)``) defines and what every backend + agrees on. A multi-character set means three different things in the + wild -- a character set on PostgreSQL, SQL Server, ClickHouse and + Snowflake, a whole string repeated on MySQL, MariaDB and Firebird, and + ``ORA-30001`` on Oracle -- so it is refused at construction instead of + rendered into whichever of the three the backend happens to implement. + The node, not a raw SQL string, is what makes the dialect's spelling a + formatter's decision: SQLite overrides the hook because it parses no + ``trim(... from ...)`` syntax at all. """ # Validate direction: only allow known trim directions. valid_directions = frozenset({"BOTH", "LEADING", "TRAILING"}) if direction not in valid_directions: raise ValueError(f"Invalid trim direction '{direction}': must be one of {valid_directions}") + if isinstance(chars, str) and len(chars) != 1: + raise ValueError( + f"Invalid trim set {chars!r}: must be exactly one character -- SQL:2016 " + "feature E021-09 defines trim( from ...), and a multi-character " + "set means three different things across the backends" + ) - target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - target_sql, target_params = target_expr.to_sql() + from ..advanced_functions import TrimExpression + target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) + chars_expr: Optional[BaseExpression] = None if chars is not None: chars_expr = chars if isinstance(chars, BaseExpression) else Literal(dialect, chars) - chars_sql, chars_params = chars_expr.to_sql() - formatted_sql = f"TRIM({direction} {chars_sql} FROM {target_sql})" - # Combine parameters - all_params = target_params + chars_params - # For now, return a RawSQLExpression; in a real implementation, the dialect would handle this - return RawSQLExpression(dialect, formatted_sql, all_params) - else: - formatted_sql = f"TRIM({direction} FROM {target_sql})" - return RawSQLExpression(dialect, formatted_sql, target_params) + return TrimExpression(dialect, target_expr, chars_expr, direction) def replace( @@ -173,7 +221,7 @@ def replace( target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) pattern_expr = pattern if isinstance(pattern, BaseExpression) else Literal(dialect, pattern) replacement_expr = replacement if isinstance(replacement, BaseExpression) else Literal(dialect, replacement) - return FunctionCall(dialect, "REPLACE", target_expr, pattern_expr, replacement_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "REPLACE", target_expr, pattern_expr, replacement_expr)) def upper(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": @@ -193,7 +241,7 @@ def upper(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Fun A FunctionCall instance representing the UPPER function """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "UPPER", target_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "UPPER", target_expr)) def lower(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": @@ -213,7 +261,7 @@ def lower(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Fun A FunctionCall instance representing the LOWER function """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "LOWER", target_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "LOWER", target_expr)) def initcap(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": @@ -233,7 +281,7 @@ def initcap(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "F A FunctionCall instance representing the INITCAP function """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "INITCAP", target_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "INITCAP", target_expr)) def left(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], n: int) -> "FunctionCall": @@ -252,10 +300,23 @@ def left(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], n: int) Returns: A FunctionCall instance representing the LEFT function + + Raises: + ValueError: If *n* is negative. + + Contract: + ``n >= 0``, and everything above it is portable: 0 is the empty string + and more than the length is the whole string on every backend. Below 0 + the backends answer four different ways -- PostgreSQL and ClickHouse + drop the trailing ``|n|`` characters, MySQL, MariaDB and Snowflake + return an empty string, SQL Server and Firebird raise, and BigQuery + raises -- so a negative count is refused rather than rendered. """ + if isinstance(n, int) and n < 0: + raise ValueError(f"left(): n must be >= 0, got {n!r}") target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) n_expr = Literal(dialect, n) - return FunctionCall(dialect, "LEFT", target_expr, n_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "LEFT", target_expr, n_expr)) def right(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], n: int) -> "FunctionCall": @@ -274,17 +335,27 @@ def right(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], n: int) Returns: A FunctionCall instance representing the RIGHT function + + Raises: + ValueError: If *n* is negative. + + Contract: + The mirror of :func:`left` -- ``n >= 0``, 0 is the empty string, more + than the length is the whole string, and a negative count is refused + because no two backends agree on it (see :func:`left`). """ + if isinstance(n, int) and n < 0: + raise ValueError(f"right(): n must be >= 0, got {n!r}") target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) n_expr = Literal(dialect, n) - return FunctionCall(dialect, "RIGHT", target_expr, n_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "RIGHT", target_expr, n_expr)) def lpad( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], length: int, pad: Optional[str] = None -) -> "FunctionCall": +) -> "LpadExpression": """ - Creates an LPAD scalar function call. + Creates a left-padding node. Usage rules: - To generate LPAD(column, length, pad), pass a Column object: @@ -296,24 +367,48 @@ def lpad( expr: The expression to pad. If a string is passed, it's treated as a literal value. If a BaseExpression is passed, it's used as-is. length: Total length after padding. - pad: Optional padding character/string. If provided, treated as literal value. + pad: Optional padding string, non-empty. Defaults to a single space. Returns: - A FunctionCall instance representing the LPAD function - """ + A :class:`~...expression.advanced_functions.LpadExpression` node, which + the dialect renders through ``format_lpad_expression`` -- a spelling + where the function exists (PostgreSQL, MySQL, MariaDB, Oracle, + Firebird, ClickHouse, Snowflake, BigQuery) and an emulation composed + from ordinary nodes where it does not (SQLite). + + Raises: + ValueError: A negative *length*, or an empty *pad*. + + Contract: + ``length >= 0`` and the pad is non-empty; an omitted pad means one + space, and it is always passed explicitly because the backends differ + on whether the argument is optional at all (MySQL raises 1582 without + it, MariaDB fills with spaces). An empty pad is refused: measured + 2026-10-09, it leaves the string alone on PostgreSQL/Firebird/Snowflake, + returns an empty string on MySQL 8.0, the untouched string on MySQL 26 + (the same server, two answers), NULL on MariaDB/Oracle and pads with + spaces on ClickHouse. + """ + if isinstance(length, int) and length < 0: + raise ValueError(f"lpad(): length must be >= 0, got {length!r}") + if isinstance(pad, str) and pad == "": + raise ValueError( + "lpad(): empty pad string is refused -- backends disagree on what it " + "means (untouched string, empty string or NULL)" + ) target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - length_expr = Literal(dialect, length) - if pad is not None: - pad_expr = Literal(dialect, pad) - return FunctionCall(dialect, "LPAD", target_expr, length_expr, pad_expr) - return FunctionCall(dialect, "LPAD", target_expr, length_expr) + length_expr = length if isinstance(length, BaseExpression) else Literal(dialect, length) + pad_expr = pad if isinstance(pad, BaseExpression) else Literal(dialect, " " if pad is None else pad) + from ..advanced_functions import LpadExpression + + return LpadExpression(dialect, target_expr, length_expr, pad_expr) def rpad( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], length: int, pad: Optional[str] = None -) -> "FunctionCall": +) -> "RpadExpression": """ - Creates an RPAD scalar function call. + Creates a right-padding node. Usage rules: - To generate RPAD(column, length, pad), pass a Column object: @@ -325,17 +420,33 @@ def rpad( expr: The expression to pad. If a string is passed, it's treated as a literal value. If a BaseExpression is passed, it's used as-is. length: Total length after padding. - pad: Optional padding character/string. If provided, treated as literal value. + pad: Optional padding string, non-empty. Defaults to a single space. Returns: - A FunctionCall instance representing the RPAD function - """ + A :class:`~...expression.advanced_functions.RpadExpression` node, + rendered through ``format_rpad_expression`` -- a spelling where the + function exists and a one-branch emulation where it does not. + + Raises: + ValueError: A negative *length*, or an empty *pad*. + + Contract: + The mirror of :func:`lpad`: ``length >= 0``, a non-empty pad, an + omitted pad spelled out as one space, and an empty pad refused. + """ + if isinstance(length, int) and length < 0: + raise ValueError(f"rpad(): length must be >= 0, got {length!r}") + if isinstance(pad, str) and pad == "": + raise ValueError( + "rpad(): empty pad string is refused -- backends disagree on what it " + "means (untouched string, empty string or NULL)" + ) target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - length_expr = Literal(dialect, length) - if pad is not None: - pad_expr = Literal(dialect, pad) - return FunctionCall(dialect, "RPAD", target_expr, length_expr, pad_expr) - return FunctionCall(dialect, "RPAD", target_expr, length_expr) + length_expr = length if isinstance(length, BaseExpression) else Literal(dialect, length) + pad_expr = pad if isinstance(pad, BaseExpression) else Literal(dialect, " " if pad is None else pad) + from ..advanced_functions import RpadExpression + + return RpadExpression(dialect, target_expr, length_expr, pad_expr) def reverse(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": @@ -355,12 +466,12 @@ def reverse(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "F A FunctionCall instance representing the REVERSE function """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "REVERSE", target_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "REVERSE", target_expr)) def strpos( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], substring: Union[str, "BaseExpression"] -) -> "FunctionCall": +) -> "IntegerValueExpression": """ Creates a STRPOS scalar function call (position of substring). @@ -380,12 +491,19 @@ def strpos( """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) substr_expr = substring if isinstance(substring, BaseExpression) else Literal(dialect, substring) - return FunctionCall(dialect, "STRPOS", target_expr, substr_expr) + return IntegerValueExpression(dialect, FunctionCall(dialect, "STRPOS", target_expr, substr_expr)) -def concat_op(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) -> "BinaryExpression": - """ - Creates a string concatenation operation using the || operator (SQL standard). +def concat_op( + dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"] +) -> "BinaryExpression": + """Creates a string concatenation using the ``||`` operator. + + Deliberately not offered as a ``StringValueMixin`` method. ``||`` does not + mean concatenation everywhere — in MySQL it is logical OR by default — so + an operation reachable from a string column would silently produce a + boolean on some backends. Use :func:`concat`, whose meaning is the same + everywhere. Usage rules: - To generate column1 || column2, pass Column objects: @@ -407,11 +525,11 @@ def concat_op(dialect: "SQLDialectBase", *exprs: Union[str, "BaseExpression"]) - target_exprs = [e if isinstance(e, BaseExpression) else Literal(dialect, e) for e in exprs] # Start with the first two expressions - result = BinaryExpression(dialect, "||", target_exprs[0], target_exprs[1]) + result = StringConcatExpression(dialect, target_exprs[0], target_exprs[1]) - # Chain additional expressions using the || operator + # Chain additional expressions for i in range(2, len(target_exprs)): - result = BinaryExpression(dialect, "||", result, target_exprs[i]) + result = StringConcatExpression(dialect, result, target_exprs[i]) return result @@ -434,10 +552,10 @@ def chr_(dialect: "SQLDialectBase", code: Union[int, "BaseExpression"]) -> "Func A FunctionCall instance representing the CHR function """ code_expr = code if isinstance(code, BaseExpression) else Literal(dialect, code) - return FunctionCall(dialect, "CHR", code_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "CHR", code_expr)) -def ascii(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def ascii(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "IntegerValueExpression": """ Creates an ASCII function call. @@ -455,10 +573,10 @@ def ascii(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "Fun A FunctionCall instance representing the ASCII function """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "ASCII", target_expr) + return IntegerValueExpression(dialect, FunctionCall(dialect, "ASCII", target_expr)) -def octet_length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def octet_length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "IntegerValueExpression": """ Creates an OCTET_LENGTH function call. @@ -476,10 +594,10 @@ def octet_length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) A FunctionCall instance representing the OCTET_LENGTH function """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "OCTET_LENGTH", target_expr) + return IntegerValueExpression(dialect, FunctionCall(dialect, "OCTET_LENGTH", target_expr)) -def bit_length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "FunctionCall": +def bit_length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> "IntegerValueExpression": """ Creates a BIT_LENGTH function call. @@ -497,12 +615,12 @@ def bit_length(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"]) -> A FunctionCall instance representing the BIT_LENGTH function """ target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "BIT_LENGTH", target_expr) + return IntegerValueExpression(dialect, FunctionCall(dialect, "BIT_LENGTH", target_expr)) def position( dialect: "SQLDialectBase", substring: Union[str, "BaseExpression"], expr: Union[str, "BaseExpression"] -) -> "FunctionCall": +) -> "IntegerValueExpression": """ Creates a POSITION function call. @@ -522,7 +640,7 @@ def position( """ substr_expr = substring if isinstance(substring, BaseExpression) else Literal(dialect, substring) target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - return FunctionCall(dialect, "POSITION", substr_expr, target_expr) + return IntegerValueExpression(dialect, FunctionCall(dialect, "POSITION", substr_expr, target_expr)) def overlay( @@ -556,8 +674,13 @@ def overlay( start_expr = Literal(dialect, start) if length is not None: length_expr = Literal(dialect, length) - return FunctionCall(dialect, "OVERLAY", target_expr, replace_expr, start_expr, length_expr) - return FunctionCall(dialect, "OVERLAY", target_expr, replace_expr, start_expr) + return StringValueExpression( + dialect, + FunctionCall(dialect, "OVERLAY", target_expr, replace_expr, start_expr, length_expr), + ) + return StringValueExpression( + dialect, FunctionCall(dialect, "OVERLAY", target_expr, replace_expr, start_expr) + ) def translate( @@ -584,14 +707,12 @@ def translate( target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) from_expr = Literal(dialect, from_chars) to_expr = Literal(dialect, to_chars) - return FunctionCall(dialect, "TRANSLATE", target_expr, from_expr, to_expr) + return StringValueExpression(dialect, FunctionCall(dialect, "TRANSLATE", target_expr, from_expr, to_expr)) -def repeat(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], count: int) -> "FunctionCall": +def repeat(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], count: int) -> "RepeatExpression": """ - Creates a REPEAT function call. - - SQL:2003 standard function repeating a string. + Creates a repetition node. Usage rules: - To generate REPEAT(column, 3): repeat(dialect, Column("text"), 3) @@ -603,11 +724,27 @@ def repeat(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], count: count: Number of repetitions Returns: - A FunctionCall instance representing the REPEAT function - """ + A :class:`~...expression.advanced_functions.RepeatExpression` node, + rendered through ``format_repeat_expression`` -- a spelling where the + function exists (PostgreSQL, MySQL, MariaDB, ClickHouse, BigQuery) and + an emulation composed from ordinary nodes where it does not (SQLite, + Oracle, Firebird). + + Contract: + ``count >= 0`` repeats, and a negative count is the **empty string** + rather than a refusal -- the native answer on PostgreSQL, MySQL, + MariaDB and ClickHouse alike, measured 2026-10-09. SQL Server's + ``REPLICATE`` answers NULL for a negative count and Oracle, Firebird + and SQLite have no such function at all, so the meaning is settled + once here instead of once per backend. + """ + if isinstance(count, int) and count < 0: + return StringValueExpression(dialect, Literal(dialect, "")) target_expr = expr if isinstance(expr, BaseExpression) else Literal(dialect, expr) - count_expr = Literal(dialect, count) - return FunctionCall(dialect, "REPEAT", target_expr, count_expr) + count_expr = count if isinstance(count, BaseExpression) else Literal(dialect, count) + from ..advanced_functions import RepeatExpression + + return RepeatExpression(dialect, target_expr, count_expr) def space(dialect: "SQLDialectBase", count: int) -> "FunctionCall": @@ -626,4 +763,4 @@ def space(dialect: "SQLDialectBase", count: int) -> "FunctionCall": Returns: A FunctionCall instance representing the SPACE function """ - return FunctionCall(dialect, "SPACE", Literal(dialect, count)) + return StringValueExpression(dialect, FunctionCall(dialect, "SPACE", Literal(dialect, count))) diff --git a/src/rhosocial/activerecord/backend/expression/functions/system.py b/src/rhosocial/activerecord/backend/expression/functions/system.py index 5e363eb0b..ead29b7cc 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/system.py +++ b/src/rhosocial/activerecord/backend/expression/functions/system.py @@ -3,13 +3,16 @@ from typing import TYPE_CHECKING -from ..core import FunctionCall +from ..core import ( + StringValueExpression, + FunctionCall, +) if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase -def current_user(dialect: "SQLDialectBase") -> "FunctionCall": +def current_user(dialect: "SQLDialectBase") -> "StringValueExpression": """ Creates a CURRENT_USER niladic value function. @@ -22,10 +25,10 @@ def current_user(dialect: "SQLDialectBase") -> "FunctionCall": Returns: A FunctionCall instance representing the CURRENT_USER value function """ - return FunctionCall(dialect, "CURRENT_USER", niladic=True) + return StringValueExpression(dialect, FunctionCall(dialect, 'CURRENT_USER', niladic=True)) -def session_user(dialect: "SQLDialectBase") -> "FunctionCall": +def session_user(dialect: "SQLDialectBase") -> "StringValueExpression": """ Creates a SESSION_USER niladic value function. @@ -38,10 +41,10 @@ def session_user(dialect: "SQLDialectBase") -> "FunctionCall": Returns: A FunctionCall instance representing the SESSION_USER value function """ - return FunctionCall(dialect, "SESSION_USER", niladic=True) + return StringValueExpression(dialect, FunctionCall(dialect, 'SESSION_USER', niladic=True)) -def system_user(dialect: "SQLDialectBase") -> "FunctionCall": +def system_user(dialect: "SQLDialectBase") -> "StringValueExpression": """ Creates a SYSTEM_USER niladic value function. @@ -54,4 +57,4 @@ def system_user(dialect: "SQLDialectBase") -> "FunctionCall": Returns: A FunctionCall instance representing the SYSTEM_USER value function """ - return FunctionCall(dialect, "SYSTEM_USER", niladic=True) + return StringValueExpression(dialect, FunctionCall(dialect, 'SYSTEM_USER', niladic=True)) diff --git a/src/rhosocial/activerecord/backend/expression/functions/type_conversion.py b/src/rhosocial/activerecord/backend/expression/functions/type_conversion.py index eefcc5fb3..5e4472467 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/type_conversion.py +++ b/src/rhosocial/activerecord/backend/expression/functions/type_conversion.py @@ -4,13 +4,174 @@ from typing import Union, Optional, TYPE_CHECKING from ..bases import BaseExpression, SQLValueExpression -from ..core import Column, FunctionCall, Literal +from ..core import ( + Column, + TimestampValueExpression, + NumericValueExpression, + StringValueExpression, + FunctionCall, + Literal, +) if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase + from ..types._base import DataType -def cast(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], target_type: str) -> "SQLValueExpression": +#: Value class -> the class standing for both a CAST and that value class. +#: Populated on first use by :func:`_cast_class_for`. +_CAST_VALUE_CLASSES = {} + + +def _cast_class_for(value_class): + """The class standing for both a CAST and *value_class*. + + Built once per value class and kept, so ``type(x)`` does not differ between + two casts that produce the same thing. + + ``CastExpression`` comes first: it supplies the node's own state and + ``format_method``. ``DeclaredValueType`` supplies the rendering, because the + value class's own ``to_sql`` is a wrapper delegating to a node this does not + hold. + """ + from ..advanced_functions import DeclaredValueType + from ..core import CastExpression + + try: + return _CAST_VALUE_CLASSES[value_class] + except KeyError: + combined = type( + f"Cast{value_class.__name__}", + (CastExpression, DeclaredValueType, value_class), + { + "__doc__": ( + f"A CAST to a type this value class represents, so it is " + f"a {value_class.__name__}." + ) + }, + ) + _CAST_VALUE_CLASSES[value_class] = combined + return combined + + +def _value_class_for(target_type): + """The value class *target_type* casts to, or ``None`` if it has none. + + A cast takes its answer from the target type, which is the only place it can + come from: ``CAST(x AS t)`` is a ``t`` whatever ``x`` held. There is no + lookup from a type *name* any more -- the name carries no type of its own to + be right about, and a ``DataType`` instance is what identifies the type. + + Resolution walks the MRO, so ``IntegerType`` and the three narrower integer + widths resolve as whole numbers through the class they share, and a backend's + own type resolves through whichever core type it derives from. + + ``None`` is a real answer. A user-defined type has no value class to offer: + promising JSON navigation on a type nobody here has heard of would be worse + than saying nothing, so the cast comes back untyped and the caller says what + they meant with ``as_*``. + """ + global _TYPE_VALUE_CLASSES + if _TYPE_VALUE_CLASSES is None: + _TYPE_VALUE_CLASSES = _type_value_classes() + + for klass in type(target_type).__mro__: + value_class = _TYPE_VALUE_CLASSES.get(klass) + if value_class is not None: + return value_class + return None + + +def _type_value_classes(): + """The ``DataType`` class -> value class table, built on first use. + + Deferred because :mod:`..types` and :mod:`..core` both import from this + package's expression module, so neither can be imported at module scope here. + """ + from .. import core + from ..types import ( + ArrayType, + BigIntType, + BinaryType, + BlobType, + BooleanType, + CharType, + CustomType, + DateTimeType, + DateType, + DecimalType, + DoubleType, + EnumType, + FloatType, + IntegerType, + IntervalType, + JsonBType, + JsonType, + RealType, + SmallIntType, + TextType, + TimeType, + TimeTzType, + TimestampType, + TimestampTzType, + TinyIntType, + UUIDType, + VarBinaryType, + VarCharType, + XmlType, + ) + + return { + # Whole numbers, whatever the width. + IntegerType: core.IntegerValueExpression, + TinyIntType: core.IntegerValueExpression, + SmallIntType: core.IntegerValueExpression, + BigIntType: core.IntegerValueExpression, + # Fractional numbers. + DecimalType: core.NumericValueExpression, + FloatType: core.NumericValueExpression, + RealType: core.NumericValueExpression, + DoubleType: core.NumericValueExpression, + # Text. An enum is text: its values are labels. + CharType: core.StringValueExpression, + VarCharType: core.StringValueExpression, + TextType: core.StringValueExpression, + EnumType: core.StringValueExpression, + # Bytes. + BinaryType: core.BinaryValueExpression, + VarBinaryType: core.BinaryValueExpression, + BlobType: core.BinaryValueExpression, + BooleanType: core.BooleanValueExpression, + # Documents. + JsonType: core.JSONValueExpression, + JsonBType: core.JSONValueExpression, + # An XML document: a value with its own surface, not a string. + XmlType: core.XMLValueExpression, + # Sequences. + ArrayType: core.ArrayValueExpression, + # A UUID is a UUID. + UUIDType: core.UUIDValueExpression, + # Temporal. Each gets its own class because they are four types; a + # timestamp is not a date, and CURRENT_DATE() is not + # CURRENT_TIMESTAMP(). + DateType: core.DateValueExpression, + DateTimeType: core.TimestampValueExpression, + TimestampType: core.TimestampValueExpression, + TimestampTzType: core.TimestampValueExpression, + TimeType: core.TimeValueExpression, + TimeTzType: core.TimeValueExpression, + IntervalType: core.IntervalValueExpression, + } + + +_TYPE_VALUE_CLASSES = None + + +def cast( + dialect: "SQLDialectBase", + expr: Union[str, "BaseExpression"], + target_type: "DataType", +) -> "SQLValueExpression": """ Creates a type cast around an expression. @@ -19,27 +180,47 @@ def cast(dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], target_t exactly this node. Usage rules: - - To generate CAST(column AS type), pass a Column object: cast(dialect, Column(dialect, "column_name"), "INTEGER") - - To generate CAST("col" AS type), pass a string: cast(dialect, "column_name", "INTEGER") + - To generate CAST(column AS type), pass a Column object and a type: + cast(dialect, Column(dialect, "column_name"), IntegerType(dialect)) + - To generate CAST("col" AS type), pass the column name as a string. Args: dialect: The SQL dialect instance expr: The expression to cast. If a string is passed, it's treated as a column name. If a BaseExpression is passed, it's used as-is. - target_type: The target data type to cast to. + target_type: The type to cast to, as a DataType instance. A string is + refused: the type position of a cast cannot take a bound + parameter, so a string there is SQL code rather than SQL data. Returns: - A new CastExpression node wrapping the given expression + A new CastExpression node wrapping the given expression, typed by the + target type -- see below. + + Raises: + TypeError: If target_type is not a DataType. """ + from ..advanced_functions import DeclaredValueType from ..core import CastExpression, Column target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return CastExpression(dialect, target_expr, target_type) + node = CastExpression(dialect, target_expr, target_type) + value_class = _value_class_for(target_type) + if value_class is None: + return node + # A cast is the one place a result's type is stated by something other than + # the input: CAST(x AS t) is a t by definition, whatever x was. So the node + # is built as an instance of that class -- it is not a wrapper holding one, + # hence DeclaredValueType's rendering rather than the wrapper's delegation. + combined = _cast_class_for(value_class) + # The state is already set by CastExpression.__init__ above; re-point the + # instance's class rather than rebuilding it, so nothing is re-validated. + node.__class__ = combined + return node def to_char( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], format: Optional[str] = None -) -> "FunctionCall": +) -> "StringValueExpression": """ Creates a TO_CHAR function call. @@ -56,18 +237,18 @@ def to_char( format: Optional format string for conversion. Returns: - A FunctionCall instance representing the TO_CHAR function + A StringValueExpression wrapping TO_CHAR """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) if format is not None: format_expr = Literal(dialect, format) - return FunctionCall(dialect, "TO_CHAR", target_expr, format_expr) - return FunctionCall(dialect, "TO_CHAR", target_expr) + return StringValueExpression(dialect, FunctionCall(dialect, 'TO_CHAR', target_expr, format_expr)) + return StringValueExpression(dialect, FunctionCall(dialect, 'TO_CHAR', target_expr)) def to_number( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], format: Optional[str] = None -) -> "FunctionCall": +) -> "NumericValueExpression": """ Creates a TO_NUMBER function call. @@ -84,18 +265,18 @@ def to_number( format: Optional format string for conversion. Returns: - A FunctionCall instance representing the TO_NUMBER function + A NumericValueExpression wrapping TO_NUMBER """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) if format is not None: format_expr = Literal(dialect, format) - return FunctionCall(dialect, "TO_NUMBER", target_expr, format_expr) - return FunctionCall(dialect, "TO_NUMBER", target_expr) + return NumericValueExpression(dialect, FunctionCall(dialect, 'TO_NUMBER', target_expr, format_expr)) + return NumericValueExpression(dialect, FunctionCall(dialect, 'TO_NUMBER', target_expr)) def to_date( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], format: Optional[str] = None -) -> "FunctionCall": +) -> "TimestampValueExpression": """ Creates a TO_DATE function call. @@ -112,10 +293,10 @@ def to_date( format: Optional format string for conversion. Returns: - A FunctionCall instance representing the TO_DATE function + A TimestampValueExpression wrapping TO_DATE """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) if format is not None: format_expr = Literal(dialect, format) - return FunctionCall(dialect, "TO_DATE", target_expr, format_expr) - return FunctionCall(dialect, "TO_DATE", target_expr) + return TimestampValueExpression(dialect, FunctionCall(dialect, 'TO_DATE', target_expr, format_expr)) + return TimestampValueExpression(dialect, FunctionCall(dialect, 'TO_DATE', target_expr)) diff --git a/src/rhosocial/activerecord/backend/expression/functions/window.py b/src/rhosocial/activerecord/backend/expression/functions/window.py index beee9e5b3..edbbf6fe1 100644 --- a/src/rhosocial/activerecord/backend/expression/functions/window.py +++ b/src/rhosocial/activerecord/backend/expression/functions/window.py @@ -4,26 +4,52 @@ from typing import Union, Optional, Any, TYPE_CHECKING from ..bases import BaseExpression -from ..core import Column, Literal -from ..advanced_functions import WindowFunctionCall +from ..column_types import value_class_of +from ..core import Column, FunctionCall, Literal, IntegerValueExpression if TYPE_CHECKING: # pragma: no cover from ...dialect import SQLDialectBase -def row_number(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "WindowFunctionCall": +def _typed(call: FunctionCall, target: BaseExpression): + """Wrap *call* in the value class matching *target*, when there is one. + + A window function that borrows a value hands that value back: ``LAG`` over a + string answers with a string, over a float with a number. The column class + already says which, so it is read off the class rather than off an attribute + duplicating it -- see + :func:`~...expression.column_types.value_class_of`. + + ``ROW_NUMBER``, ``RANK`` and ``DENSE_RANK`` are the exception -- they count + or place rows rather than borrow a value, and are always whole numbers -- so + they always wrap in :class:`IntegerValueExpression` and never come here. + + A target that says nothing -- a ``Literal``, an untyped ``Column`` -- leaves + the call untyped, which is the honest answer: the database decides. + """ + value_class = value_class_of(target) + if value_class is not None: + return value_class(call._dialect, call) + return call + + +def row_number(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "FunctionCall": """Creates a ROW_NUMBER window function call.""" - return WindowFunctionCall(dialect, "ROW_NUMBER", alias=alias) + return IntegerValueExpression( + dialect, FunctionCall(dialect, "ROW_NUMBER", alias=alias) + ) -def rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "WindowFunctionCall": +def rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "FunctionCall": """Creates a RANK window function call.""" - return WindowFunctionCall(dialect, "RANK", alias=alias) + return IntegerValueExpression(dialect, FunctionCall(dialect, "RANK", alias=alias)) -def dense_rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "WindowFunctionCall": +def dense_rank(dialect: "SQLDialectBase", alias: Optional[str] = None) -> "FunctionCall": """Creates a DENSE_RANK window function call.""" - return WindowFunctionCall(dialect, "DENSE_RANK", alias=alias) + return IntegerValueExpression( + dialect, FunctionCall(dialect, "DENSE_RANK", alias=alias) + ) def lag( @@ -32,7 +58,7 @@ def lag( offset: int = 1, default: Optional[Any] = None, alias: Optional[str] = None, -) -> "WindowFunctionCall": +) -> "FunctionCall": """ Creates a LAG window function call. @@ -48,13 +74,13 @@ def lag( alias: Optional alias for the result. Returns: - A WindowFunctionCall instance representing the LAG function + A FunctionCall instance representing the LAG function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) args = [target_expr, Literal(dialect, offset)] if default is not None: args.append(Literal(dialect, default)) - return WindowFunctionCall(dialect, "LAG", args=args, alias=alias) + return _typed(FunctionCall(dialect, "LAG", *args, alias=alias), target_expr) def lead( @@ -63,7 +89,7 @@ def lead( offset: int = 1, default: Optional[Any] = None, alias: Optional[str] = None, -) -> "WindowFunctionCall": +) -> "FunctionCall": """ Creates a LEAD window function call. @@ -80,18 +106,18 @@ def lead( alias: Optional alias for the result. Returns: - A WindowFunctionCall instance representing the LEAD function + A FunctionCall instance representing the LEAD function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) args = [target_expr, Literal(dialect, offset)] if default is not None: args.append(Literal(dialect, default)) - return WindowFunctionCall(dialect, "LEAD", args=args, alias=alias) + return _typed(FunctionCall(dialect, "LEAD", *args, alias=alias), target_expr) def first_value( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], alias: Optional[str] = None -) -> "WindowFunctionCall": +) -> "FunctionCall": """ Creates a FIRST_VALUE window function call. @@ -105,15 +131,18 @@ def first_value( alias: Optional alias for the result. Returns: - A WindowFunctionCall instance representing the FIRST_VALUE function + A FunctionCall instance representing the FIRST_VALUE function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return WindowFunctionCall(dialect, "FIRST_VALUE", args=[target_expr], alias=alias) + return _typed( + FunctionCall(dialect, "FIRST_VALUE", target_expr, alias=alias), + target_expr, + ) def last_value( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], alias: Optional[str] = None -) -> "WindowFunctionCall": +) -> "FunctionCall": """ Creates a LAST_VALUE window function call. @@ -127,15 +156,18 @@ def last_value( alias: Optional alias for the result. Returns: - A WindowFunctionCall instance representing the LAST_VALUE function + A FunctionCall instance representing the LAST_VALUE function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) - return WindowFunctionCall(dialect, "LAST_VALUE", args=[target_expr], alias=alias) + return _typed( + FunctionCall(dialect, "LAST_VALUE", target_expr, alias=alias), + target_expr, + ) def nth_value( dialect: "SQLDialectBase", expr: Union[str, "BaseExpression"], n: int, alias: Optional[str] = None -) -> "WindowFunctionCall": +) -> "FunctionCall": """ Creates an NTH_VALUE window function call. @@ -150,8 +182,11 @@ def nth_value( alias: Optional alias for the result. Returns: - A WindowFunctionCall instance representing the NTH_VALUE function + A FunctionCall instance representing the NTH_VALUE function """ target_expr = expr if isinstance(expr, BaseExpression) else Column(dialect, expr) n_expr = Literal(dialect, n) - return WindowFunctionCall(dialect, "NTH_VALUE", args=[target_expr, n_expr], alias=alias) + return _typed( + FunctionCall(dialect, "NTH_VALUE", target_expr, n_expr, alias=alias), + target_expr, + ) diff --git a/src/rhosocial/activerecord/backend/expression/mixins.py b/src/rhosocial/activerecord/backend/expression/mixins.py index cd948c763..8290bdad2 100644 --- a/src/rhosocial/activerecord/backend/expression/mixins.py +++ b/src/rhosocial/activerecord/backend/expression/mixins.py @@ -27,12 +27,165 @@ """ import copy -from typing import Any, Union, List, TYPE_CHECKING, TypeVar +import datetime +import decimal +import functools +from typing import ( + Any, + List, + Optional, + Protocol, + TYPE_CHECKING, + TypeVar, + Union, +) if TYPE_CHECKING: # pragma: no cover - from .bases import SQLValueExpression, SQLPredicate + from ..dialect import SQLDialectBase + from .bases import BaseExpression, SQLValueExpression, SQLPredicate + # Annotations only. The classes themselves are imported inside the methods + # that need them, because core imports this module. + from .core import ( + ArrayValueExpression, + BinaryValueExpression, + BooleanValueExpression, + TimestampValueExpression, + IntegerValueExpression, + JSONValueExpression, + NumericValueExpression, + StringValueExpression, + UUIDValueExpression, + XMLValueExpression, + ) + from .core import CastExpression, FunctionCall + from .datetime import ( + DatePartExpression, + DateTimeAddExpression, + DateTimeDiffExpression, + DateTimeSubtractExpression, + DateTruncExpression, + ExtractExpression, + ) + from .advanced_functions import JSONDocumentExpression, JSONTextExpression T = TypeVar("T") +_ResultT = TypeVar("_ResultT") + + +class _ValueExpression(Protocol[_ResultT]): + """How a value expression class is built, as far as ``_retype`` cares. + + Not ``type[BaseExpression]``: the value classes are built from a dialect + and the call they wrap, while ``BaseExpression`` takes only a dialect, so + bounding to it makes the two-argument construction an error. What every + ``as_*`` method needs is exactly this. + + The wrapped node is typed loosely on purpose. A mixin cannot say what class + it is mixed into, so naming FunctionCall here would need ``self`` annotated + as one, which mypy only allows if this class subclasses it. The return type + is what the chain is checked against, and that is exact; the node being + passed is the one already in hand. + """ + + def __call__(self, dialect: "SQLDialectBase", call: Any) -> _ResultT: ... + + +class WrappedCallMixin: + """Forwards what the node says that the wrapper's type does not. + + A typed value wraps the call it was built from -- ``min(name)`` is a + ``StringValueExpression`` holding a ``FunctionCall`` -- so that + the result says what it is rather than what produced it. The wrapper offers + the operations its *type* supports, and those are the ones a caller reaches + for. + + Some things are not operations at all. ``count(x).filter(pred)`` is a filter + on the aggregate, not an operation on an integer; ``window_spec`` belongs to + the call; ``alias`` is state both share. Those belong to the node, and the + only one that knows how to attach a filter is the aggregate. Rather than + restate every node-specific member on every value type, an attribute the + wrapper has no answer for is looked up on the node it holds. + + **Where that lookup stops is the whole of this class.** The two + hierarchies meet: the node is built from the same base classes and the same + mixins, and a wrapper's bases say exactly what it kept. So the lookup walks + the node's MRO and stops at the first class the wrapper also carries. + Above that point is the node's own contribution -- its state and its own + grammar -- and it is forwarded. From that point down is either something + the wrapper already has, or a capability its type deliberately left off: + ``StringPatternPredicateMixin`` and ``ResultTypeMixin`` reach a + ``FunctionCall`` that a ``StringValueExpression`` or an + ``IntegerValueExpression`` never claimed, and handing those back would undo + the typing that made the class worth having: ``length().like("1%")`` would + be offered again, and the mistake would travel to the database. + + The boundary is found by comparing the two MROs, so there is no set of + names to keep current: a method added to a capability mixin stops being + forwarded the moment it is declared, and a method added to a node class + becomes forwardable without anything being edited here. What the wrapper + withholds is what the wrapper's own bases withhold, which is the one + statement this class has to make. + + The wrapper keeps the type either way: a forwarded call that returns the + node hands back a node, so ``count(x).filter(...)`` is an untyped + ``FunctionCall`` again -- which is honest, because that is what the + filter produces and nothing about adding one re-types the result. + + Example: + >>> agg = count(dialect, "price") + >>> type(agg).__name__ # IntegerValueExpression + >>> type(agg.filter(pred)).__name__# FunctionCall + >>> hasattr(agg, "like") # False: a count is not text + """ + + def __getattr__(self, name): + # Only reached for attributes this class does not define, so `call` + # itself is already set here. Going through the instance dict rather + # than `getattr` keeps a missing `call` from recursing into itself -- + # and a class that mixes this in without holding a node (the CASE whose + # branches agree the answer) refuses everything, which is what a node + # it does not have can honestly say. + try: + node = object.__getattribute__(self, "call") + except AttributeError: + raise AttributeError( + f"{type(self).__name__} has no attribute {name!r}" + ) from None + if name in _ruled_on(type(self), type(node)): + raise AttributeError( + f"{type(self).__name__} has no attribute {name!r}. The " + f"{type(node).__name__} it wraps does, and a typed value offers " + f"the operations its own type supports rather than the " + f"operations of the node that happens to produce it." + ) from None + try: + return getattr(node, name) + except AttributeError: + raise AttributeError( + f"{type(self).__name__} has no attribute {name!r}" + ) from None + + +@functools.lru_cache(maxsize=None) +def _ruled_on(wrapper_cls: type, node_cls: type) -> frozenset: + """What *node_cls* offers that *wrapper_cls*'s own bases already answer for. + + The two hierarchies meet at the first class of the node's MRO that the + wrapper also carries, and from there down the node is either repeating the + wrapper or offering a capability the wrapper's type declined. Both are + names the wrapper has already spoken for, so forwarding either would give + back what the typing withheld. + + Cached on the two classes because it is asked on every attribute miss, and + it depends on nothing but the two MROs. + """ + node_mro = node_cls.__mro__ + wrapper_mro = frozenset(wrapper_cls.__mro__) + meet = next((i for i, k in enumerate(node_mro) if k in wrapper_mro), len(node_mro)) + ruled_on = set() + for klass in node_mro[meet:]: + ruled_on.update(vars(klass)) + return frozenset(ruled_on) class AliasableMixin: @@ -68,7 +221,60 @@ def as_(self: T, alias: str) -> T: return new -class ComparisonMixin: +class NullTestMixin: + """``IS NULL`` / ``IS NOT NULL``: the test that works when comparison does not. + + A null test asks whether a value is present, not what it equals, so it is + available wherever a value is — including where comparison is refused. + PostgreSQL refuses ``xml = xml`` outright ("operator does not exist: xml = + xml"), SQL Server documents that "the xml data type cannot be compared or + sorted", and Oracle's ``XMLType`` has no comparison operators either; every + one of the three accepts ``IS NULL``. Splitting this out of + :class:`ComparisonMixin` is what lets an XML value keep the test while + refusing the comparisons. + + This is the part of the comparison surface that every value type shares, so + :class:`~...expression.column_types.ColumnBase` carries it directly and the + comparable families take :class:`ComparisonMixin` (which inherits it) as + well. + + Example: + >>> col = Column(dialect, "email") + >>> predicate = col.is_null() # Generates: "email IS NULL" + """ + + def is_null(self: "SQLValueExpression") -> "SQLPredicate": + """ + Generate an IS NULL predicate for this expression. + + Returns: + SQLPredicate representing the IS NULL check + + Example: + >>> col = Column(dialect, "email") + >>> predicate = col.is_null() # Generates: "email IS NULL" + """ + from .predicates import IsNullPredicate + + return IsNullPredicate(self._dialect, self) + + def is_not_null(self: "SQLValueExpression") -> "SQLPredicate": + """ + Generate an IS NOT NULL predicate for this expression. + + Returns: + SQLPredicate representing the IS NOT NULL check + + Example: + >>> col = Column(dialect, "email") + >>> predicate = col.is_not_null() # Generates: "email IS NOT NULL" + """ + from .predicates import IsNullPredicate + + return IsNullPredicate(self._dialect, self, is_not=True) + + +class ComparisonMixin(NullTestMixin): """ Provides comparison operators (==, !=, >, <, etc.) and other boolean-producing methods. @@ -79,6 +285,11 @@ class ComparisonMixin: The mixin handles both expression-to-expression comparisons and expression-to-value comparisons by automatically wrapping non-expression values in Literal objects. + The null tests (``is_null`` / ``is_not_null``) come from + :class:`NullTestMixin`, which every value class carries. This mixin adds the + ordering and equality comparisons on top; a value that cannot be compared — + an XML document — keeps :class:`NullTestMixin` without this one. + Example: >>> # Expression-to-expression comparison >>> col1 = Column(dialect, "age") @@ -91,8 +302,64 @@ class ComparisonMixin: >>> # Method-based comparisons >>> col1.is_null() # Generates "age IS NULL" >>> col1.in_([1, 2, 3]) # Generates "age IN (?, ?, ?)" + >>> col1.is_distinct_from(0) # NULL-safe: "age IS DISTINCT FROM ?" """ + def is_distinct_from(self: "SQLValueExpression", other: Union["SQLValueExpression", Any]) -> "SQLPredicate": + """NULL-safe inequality: true when the two differ, NULL included. + + ``a != b`` answers NULL when either side is NULL, so a query filtering + for "not equal" silently drops every NULL row -- the row the caller was + most likely looking for. ``IS DISTINCT FROM`` is the NULL-safe spelling + and is what :meth:`is_not_distinct_from` negates. + + The renderer is a dialect hook, because the spelling is not universal: + PostgreSQL, Firebird, Snowflake, BigQuery, SQL Server (2022+) and + SQLite (3.39+) have it, while Oracle answers ``NOT LNNVL(a = b)``, + ``IS NOT DISTINCT FROM`` is ``ORA-00908`` there, and an older SQL Server + or SQLite has neither. The gate lives with the dialect that has the + limit and **refuses** rather than substituting a different question. + + Args: + other: Right operand, wrapped as a literal when not an expression. + + Returns: + A predicate rendering `` IS DISTINCT FROM ``. + + Example: + >>> Column(dialect, "name").is_distinct_from("root").to_sql() + ('"name" IS DISTINCT FROM ?', ('root',)) + """ + from .core import Literal + from .predicates import DistinctFromPredicate + from .bases import SQLValueExpression + + other_expr = other if isinstance(other, SQLValueExpression) else Literal(self._dialect, other) + return DistinctFromPredicate(self._dialect, self, other_expr, is_not=False) + + def is_not_distinct_from(self: "SQLValueExpression", other: Union["SQLValueExpression", Any]) -> "SQLPredicate": + """NULL-safe equality: true when the two match, two NULLs included. + + The counterpart of :meth:`is_distinct_from` -- ``IS NOT DISTINCT FROM`` + is true for two NULLs, where ``=`` is not. + + Args: + other: Right operand, wrapped as a literal when not an expression. + + Returns: + A predicate rendering `` IS NOT DISTINCT FROM ``. + + Example: + >>> Column(dialect, "name").is_not_distinct_from("root").to_sql() + ('"name" IS NOT DISTINCT FROM ?', ('root',)) + """ + from .core import Literal + from .predicates import DistinctFromPredicate + from .bases import SQLValueExpression + + other_expr = other if isinstance(other, SQLValueExpression) else Literal(self._dialect, other) + return DistinctFromPredicate(self._dialect, self, other_expr, is_not=True) + def __eq__(self: "SQLValueExpression", other: Union["SQLValueExpression", Any]) -> "SQLPredicate": """ Implement the equality operator (==) to generate SQL equality predicate. @@ -202,36 +469,6 @@ def __le__(self: "SQLValueExpression", other: Union["SQLValueExpression", Any]) other_expr = other if isinstance(other, SQLValueExpression) else Literal(self._dialect, other) return ComparisonPredicate(self._dialect, "<=", self, other_expr) - def is_null(self: "SQLValueExpression") -> "SQLPredicate": - """ - Generate an IS NULL predicate for this expression. - - Returns: - SQLPredicate representing the IS NULL check - - Example: - >>> col = Column(dialect, "email") - >>> predicate = col.is_null() # Generates: "email IS NULL" - """ - from .predicates import IsNullPredicate - - return IsNullPredicate(self._dialect, self) - - def is_not_null(self: "SQLValueExpression") -> "SQLPredicate": - """ - Generate an IS NOT NULL predicate for this expression. - - Returns: - SQLPredicate representing the IS NOT NULL check - - Example: - >>> col = Column(dialect, "email") - >>> predicate = col.is_not_null() # Generates: "email IS NOT NULL" - """ - from .predicates import IsNullPredicate - - return IsNullPredicate(self._dialect, self, is_not=True) - def is_true(self: "SQLValueExpression") -> "SQLPredicate": """ Generate an IS TRUE predicate for this expression. @@ -465,14 +702,34 @@ def __mul__(self: "SQLValueExpression", other: Union["SQLValueExpression", Any]) return BinaryArithmeticExpression(self._dialect, "*", self, other_expr) def __truediv__(self: "SQLValueExpression", other: Union["SQLValueExpression", Any]) -> "SQLValueExpression": - """ - Implement the division operator (/) to generate SQL arithmetic expression. - - Args: - other: Right operand, can be another expression or a literal value - - Returns: - SQLValueExpression representing the division operation + """Division, rendered as the portable ``/`` — and what ``/`` means is + **the backend's**, not this operator's. + + Measured on four backends, ``SELECT 7 / 2``: + + * MySQL, MariaDB — ``Decimal('3.5000')``. True division, with scale 4, + on *integer* operands: ``7 / 2`` is not an integer expression at all; + * PostgreSQL, Firebird — ``3``. Integer division, truncating toward + zero, because both operands are integers and that is what ``/`` means + for them; + * SQLite — ``3`` for the same reason (``suggested-mappings.md`` §8.3 + records it as one of the silent-wrong entries: the *literal* ``3`` + and the truncating ``7 / 2`` are indistinguishable in the result). + + So the same model code, unchanged, yields ``3.5`` on MySQL and ``3`` on + PostgreSQL. Nothing here detects that, and that is deliberate: the + alternative — a framework that rewrites ``/`` per dialect — would be + choosing a semantics, and which semantics is the caller's question. A + caller who wants one can make it one by making an operand a decimal + (``7.0 / 2`` is true division on every backend measured, PostgreSQL + included) or by casting explicitly. + + What is *not* deliberate is a caller discovering this from a wrong + number. The plan's open question (``suggested-mappings.md`` §8.6 item 1) + is whether ``/`` on a numeric column should stay portable or move behind + a capability gate; until that is decided, this operator renders the + portable spelling and the difference stays a documented property of the + backends rather than a silent property of the model. """ from .core import Literal from .operators import BinaryArithmeticExpression @@ -499,10 +756,328 @@ def __mod__(self: "SQLValueExpression", other: Union["SQLValueExpression", Any]) return BinaryArithmeticExpression(self._dialect, "%", self, other_expr) -class LogicalMixin: +class NotANumberMixin: + """The statement that a value is not a number, in the only form Python allows. + + Every refusal about a *missing operation* elsewhere in this package is an + :class:`AttributeError`, because that is what a missing attribute raises and + therefore what a caller already knows how to catch. Arithmetic is the one + operation Python looks up on the *type* for the interpreter, never through + the instance, so a class without ``__add__`` does not reach ``__getattr__`` + and does not get to speak: CPython raises + ``TypeError: unsupported operand type(s) for +`` itself. + + That message names neither the operation nor the reason, and it arrives from + machinery the caller cannot inspect -- which is the wrong failure for a + branch whose whole claim is that a mistake is caught *at the call*, by the + type, saying what is missing. ``min(str_col) + 1`` is not SQL; it is a + mistake about what a string is, and the answer should say so the same way + ``min(str_col).like("a%")`` does. + + So the refusal is declared rather than left to happen. These methods exist + only to raise, and that is the point: mixing this in says "this value is not + a number", and the arithmetic operators are where that claim has to be + checkable. The alternative -- inheriting nothing and accepting the + interpreter's ``TypeError`` -- is the same decision with the message thrown + away. + + Why ``AttributeError`` and not ``TypeError``: the object genuinely has no + such operation, which is exactly what ``AttributeError`` means, and a caller + handling "this value does not offer that" handles one exception type + everywhere in the package rather than learning a second vocabulary for the + operator forms alone. + + Example: + >>> min_(dialect, name) + 1 # AttributeError, naming '+' + >>> min_(dialect, name).like("a%") # works: it is a string + """ + + def _not_a_number(self, symbol: str, dunder: str) -> "AttributeError": + """Build the refusal for *symbol*, to be raised by the operator named.""" + return AttributeError( + f"{type(self).__name__} has no attribute {dunder!r}: it does not " + f"support {symbol!r}. It is a {type(self).__name__}, not a number, " + f"and a typed value offers the operations its type supports." + ) + + def __add__(self, other): + raise self._not_a_number("+", "__add__") + + def __radd__(self, other): + raise self._not_a_number("+", "__radd__") + + def __sub__(self, other): + raise self._not_a_number("-", "__sub__") + + def __rsub__(self, other): + raise self._not_a_number("-", "__rsub__") + + def __mul__(self, other): + raise self._not_a_number("*", "__mul__") + + def __rmul__(self, other): + raise self._not_a_number("*", "__rmul__") + + def __truediv__(self, other): + raise self._not_a_number("/", "__truediv__") + + def __rtruediv__(self, other): + raise self._not_a_number("/", "__rtruediv__") + + def __mod__(self, other): + raise self._not_a_number("%", "__mod__") + + def __rmod__(self, other): + raise self._not_a_number("%", "__rmod__") + + +class TemporalArithmeticMixin(NotANumberMixin): + """Arithmetic for date, time, timestamp and interval values, gated by operand. + + What temporal arithmetic defines, and the only things this mixin performs: + + * a temporal value ± an interval is that kind of temporal value + (``created_at + one_day``, ``now() - one_hour``); + * a temporal value − a temporal value is a **duration**, and the framework + does not pretend its type is one thing: measured 2026-10-09, PostgreSQL + answers a whole number of days, Firebird a decimal number of days, + ClickHouse a number of seconds, Snowflake and BigQuery an interval, + Oracle a ``timedelta``-shaped value and MySQL/MariaDB a silent numeric + difference. The node keeps the temporal family here and lets each + dialect declare what its subtraction yields; only ``timestamp − + timestamp`` is an interval nearly everywhere (``finished - started``); + * an interval ± an interval is an interval; + * an interval × a number is an interval. + + Everything else is refused at construction, in the package's refusal + vocabulary (``AttributeError``; see :class:`NotANumberMixin`). The + combination this class exists for is ``created_at + created_at``: two + points in time have no sum, and without the gate it rendered + ``"created_at" + "created_at"`` -- SQL only the database rejected. The + failure belongs at the call, where the mistake was made. + + :class:`NotANumberMixin` is inherited for the refusals Python cannot + express by omission -- the reflected operators, ``/`` and ``%`` -- so the + vocabulary stays one exception type; this class adds the operations that + do exist, each checking its operands first. + """ + + def __add__(self, other): + return self._temporal_binary("+", other, subtracting=False) + + def __sub__(self, other): + return self._temporal_binary("-", other, subtracting=True) + + def __mul__(self, other): + if not self._is_interval_value() or not self._is_number_operand(other): + raise self._temporal_refusal( + "*", other, "only an interval scales, and only by a number" + ) + return self._build("*", other) + + # -- classification ------------------------------------------------------ + + def _is_interval_value(self) -> bool: + from .core import IntervalValueExpression + + return isinstance(self, IntervalValueExpression) + + def _is_interval_operand(self, other) -> bool: + from .bases import SQLValueExpression + from .core import IntervalValueExpression + + if isinstance(other, IntervalValueExpression): + return True + if isinstance(other, SQLValueExpression): + return False + return isinstance(other, datetime.timedelta) + + def _is_temporal_operand(self, other) -> bool: + from .bases import SQLValueExpression + from .core import IntervalValueExpression + + if isinstance(other, SQLValueExpression): + # Both a temporal *column* and a temporal *value* carry + # DateTimeMixin; an interval does too, and is excluded first. + return isinstance(other, DateTimeMixin) and not isinstance( + other, IntervalValueExpression + ) + return isinstance(other, (datetime.date, datetime.time, datetime.datetime)) + + def _is_number_operand(self, other) -> bool: + from .bases import SQLValueExpression + + if isinstance(other, bool): + return False + if isinstance(other, (int, float, decimal.Decimal)): + return True + if isinstance(other, SQLValueExpression): + return not self._is_temporal_operand(other) and not self._is_interval_operand(other) + return False + + # -- building and refusing ----------------------------------------------- + + def _temporal_binary(self, symbol: str, other, subtracting: bool): + if self._is_interval_value(): + if self._is_interval_operand(other): + return self._build(symbol, other) + if subtracting and self._is_temporal_operand(other): + reason = ( + "an interval cannot have a point in time subtracted from " + "it; subtract the interval from the temporal value instead" + ) + else: + reason = "an interval combines with another interval, or scales by a number" + raise self._temporal_refusal(symbol, other, reason) + + if self._is_interval_operand(other): + return self._build(symbol, other) + + if self._is_temporal_operand(other): + if subtracting: + return self._build(symbol, other) + raise self._temporal_refusal( + symbol, + other, + "two points in time have no sum; subtract one from the other " + "for an interval, or move it with an interval", + ) + + raise self._temporal_refusal( + symbol, other, "a temporal value combines with an interval, not with a number" + ) + + def _build(self, symbol: str, other): + from .bases import SQLValueExpression + from .core import Literal + from .operators import BinaryArithmeticExpression + + other_expr = other if isinstance(other, SQLValueExpression) else Literal(self._dialect, other) + return BinaryArithmeticExpression(self._dialect, symbol, self, other_expr) + + def _temporal_refusal(self, symbol: str, other, reason: str) -> AttributeError: + return AttributeError( + f"{type(self).__name__} has no attribute {symbol!r} for " + f"{type(other).__name__}: {reason}. Temporal arithmetic is " + f"interval-based, so the combination is not declared." + ) + + +class NotComparableMixin: + """The statement that a value cannot be compared, in the only form Python allows. + + The same problem :class:`NotANumberMixin` solves, for the comparison + operators. Python looks ``__eq__``, ``__lt__`` and the rest up on the + *type*, never through ``__getattr__``, so a class that simply does not + declare them is not silent — it silently gets ``object``'s identity + semantics, and ``xml_col == other`` answers ``False`` instead of refusing. + A call that should have been caught at the call site would instead travel + as an always-false predicate (or, for ``<``, raise the interpreter's bare + ``TypeError`` whose message names neither the operation nor the reason). + + So the refusal is declared. These methods exist only to raise, and that is + the point: mixing this in says "this value cannot be compared", which is + true of every backend that has an XML type. PostgreSQL refuses ``xml = + xml`` with "operator does not exist", SQL Server documents that "the xml + data type cannot be compared or sorted", and Oracle's ``XMLType`` has no + comparison operators. What those backends *do* accept — ``IS NULL`` — comes + from :class:`NullTestMixin` and is kept separately. + + Why ``AttributeError``: the object genuinely has no such operation, which + is exactly what ``AttributeError`` means, and a caller handling "this value + does not offer that" handles one exception type everywhere in the package + rather than learning a second vocabulary for the operator forms alone. + + ``__hash__`` is re-stated because defining ``__eq__`` sets it to ``None`` + in Python; an XML expression still goes in sets and dictionaries (it is a + value object like any other), it just cannot be ordered or compared. + + Example: + >>> xml_col == other # AttributeError, naming '__eq__' + >>> xml_col.is_null() # works: a null test is not a comparison + """ + + def _not_comparable(self, symbol: str, dunder: str) -> "AttributeError": + """Build the refusal for *symbol*, to be raised by the operator named.""" + return AttributeError( + f"{type(self).__name__} has no attribute {dunder!r}: it does not " + f"support {symbol!r}. An XML value cannot be compared on any " + f"backend that has an XML type, and a typed value offers the " + f"operations its type supports." + ) + + def __eq__(self, other): + raise self._not_comparable("==", "__eq__") + + def __ne__(self, other): + raise self._not_comparable("!=", "__ne__") + + def __lt__(self, other): + raise self._not_comparable("<", "__lt__") + + def __le__(self, other): + raise self._not_comparable("<=", "__le__") + + def __gt__(self, other): + raise self._not_comparable(">", "__gt__") + + def __ge__(self, other): + raise self._not_comparable(">=", "__ge__") + + __hash__ = object.__hash__ + + +class _LogicalOperators: + """The three connectives (``&``, ``|``, ``~``), shared by both receivers. + + The receiver decides the result class, and that is the whole difference: a + predicate stays a predicate -- combining predicates is how ``WHERE`` + clauses are built -- while a truth *value* keeps its value type + (:class:`~...core.BooleanLogicExpression`), so the result can be aliased + into a ``SELECT`` list, compared, cast, and combined further. Both render + through the same dialect entry point (``format_logical_predicate``). + + Deliberately private: the two public mixins below are the vocabulary + (predicate receivers / value receivers), and neither is a kind of the + other -- a truth value is not a predicate. + """ + + def __and__(self, other): + return self._logical_operation("AND", other) + + def __or__(self, other): + return self._logical_operation("OR", other) + + def __invert__(self): + return self._logical_operation("NOT") + + def _logical_operation(self, op: str, *others): + from .bases import SQLPredicate, SQLValueExpression + from .core import Literal + from .predicates import LogicalPredicate + + operands = [ + other + if isinstance(other, (SQLValueExpression, SQLPredicate)) + else Literal(self._dialect, other) + for other in others + ] + if isinstance(self, SQLPredicate): + return LogicalPredicate(self._dialect, op, self, *operands) + + from .core import BooleanLogicExpression + + return BooleanLogicExpression(self._dialect, op, self, *operands) + + +class LogicalMixin(_LogicalOperators): """ Provides logical operators (&, |, ~) for SQL predicates. + The result stays a predicate: this is the receiver for ``WHERE``-building + combinations. A truth *value* carries :class:`BooleanLogicMixin` instead, + and the two share one implementation (:class:`_LogicalOperators`). + This mixin enables Python's logical operators to generate SQL logical expressions. When using these operators, the left operand's dialect is used for the resulting expression, ensuring consistent SQL generation across the expression tree. @@ -522,83 +1097,767 @@ class LogicalMixin: >>> negated = ~p1 # Uses p1's dialect, generates: "NOT (status = ?)" """ - def __and__(self: "SQLPredicate", other: "SQLPredicate") -> "SQLPredicate": +class BooleanLogicMixin(_LogicalOperators): + """Boolean algebra over a value that is itself a truth value: ``&``/``|``/``~``. + + :class:`LogicalMixin` gives the same three operators to a **predicate**, + because ``p1 & p2`` is how two predicates are combined. A boolean column + needs the same three because ``IS TRUE`` / ``IS FALSE`` is a predicate in + SQL but the column is what the caller has in hand:: + + Model.c.flag.is_true() & Model.c.other.is_true() # renders AND + ~Model.c.flag.is_true() # renders NOT + + Neither mixin extends the other: a value expression is not a predicate, + and giving every value expression boolean operators would hand ``str`` an + ``AND`` it has no meaning for. Both share the private + :class:`_LogicalOperators` implementation and differ only in the result + class -- this one keeps the value type + (:class:`~...core.BooleanLogicExpression`), so ``(a & b)`` can be aliased + into a ``SELECT`` list, while :class:`LogicalMixin` keeps the predicate. + + ``is_true`` / ``is_false`` are **not** redeclared here. They already come + from :class:`ComparisonMixin`, which every comparable family carries, and + they render through the same ``IsBooleanPredicate`` a comparison uses -- + ``IS TRUE`` / ``IS FALSE``, three-valued-logic-correct, and with the boolean + literal spelled as the keyword rather than ``1``/``0``. Declaring them again + would be a second source of truth for a rendering that already exists, and + the keyword discipline that keeps ``flag = 1`` from exploding on PostgreSQL + would then be maintained in two places. + + Example: + >>> # AND / OR / NOT over boolean columns + >>> (col.is_true() & other.is_true()).to_sql() # '"flag" IS TRUE AND ...' + """ + +class ResultTypeMixin: + """Stating a result type that the source cannot settle. + + Most operations know what they yield and say so by returning the matching + expression class: ``sqrt`` of a numeric is a numeric, and it returns one. + A few cannot, and the standard gives the example itself -- ``NULLIF(x, y)`` + yields ``x`` when the two differ and NULL when they do not, so whether the + result is a string or an integer depends on the data. + + For those, the caller states it. Each method here is one statement, and + each has a return type a checker can read, so the next call in the chain is + checked too:: + + NULLIF(name, blank).as_text().upper() # fine + NULLIF(name, blank).as_text().sqrt() # error: text has no sqrt + + The alternative -- a ``result_type=`` keyword -- reads as if it did the same + thing and does not. It is a claim rather than a type: the declared return + stays ``FunctionCall``, the checker learns nothing, and the wrong + continuation is still unchecked when the server rejects it minutes later. + + A method rather than a free function for three reasons. The dialect is + already on the node, so there is nothing to pass. Chaining reads as one + expression instead of an argument in the middle of one. And ``dir()`` finds + it, so the way to say it is discoverable rather than something to be told. + + This is mixed into the nodes whose result type genuinely is not in the + source. Anything that knows its own result type returns the class for it and + never reaches this mixin. + """ + + if TYPE_CHECKING: + from ..dialect import SQLDialectBase + from .core import FunctionCall + + #: Declared here because a mixin is not a BaseExpression, so the + #: attribute arrives with the class it is mixed into. ``dialect`` + #: rather than ``_dialect``: reading it validates that one is bound. + dialect: "SQLDialectBase" + + def _retype(self, cls: _ValueExpression[_ResultT]) -> _ResultT: + """Re-wrap this expression as a value expression of *cls*. + + Only the Python class changes. The node, and therefore the SQL, is left + exactly as it was -- the statement was already correct; what was missing + was the knowledge of what it yields. + + Generic in the class rather than returning BaseExpression, so the + declared return type of each ``as_*`` method is the class it names. + Returning the base type would leave the checker unable to tell that + ``as_text()`` is text, which is the whole point of the method. + + Returns the class it is given, not a base type, so each ``as_*`` method + declares what the chain continues as. + + Args: + cls: The expression class that carries those operations. + + Returns: + A value expression of *cls*. + """ + return cls(self.dialect, self) + + def as_text(self) -> "StringValueExpression": + """This yields text, whatever the data turns out to be.""" + from .core import StringValueExpression + + return self._retype(StringValueExpression) + + def as_number(self) -> "NumericValueExpression": + """This yields a fractional number.""" + from .core import NumericValueExpression + + return self._retype(NumericValueExpression) + + def as_integer(self) -> "IntegerValueExpression": + """This yields a whole number.""" + from .core import IntegerValueExpression + + return self._retype(IntegerValueExpression) + + def as_datetime(self) -> "TimestampValueExpression": + """This yields a date or a time.""" + from .core import TimestampValueExpression + + return self._retype(TimestampValueExpression) + + def as_boolean(self) -> "BooleanValueExpression": + """This yields a truth value. + + This names the value, not a projection. SQL Server has no boolean scalar + type at all, so a predicate cannot appear in a select list there; where + one is needed, the dialect has to produce a zero-or-one column. """ - Implement the logical AND operator (&) to generate SQL logical predicate. + from .core import BooleanValueExpression + + return self._retype(BooleanValueExpression) + + def as_array(self) -> "ArrayValueExpression": + """This yields a sequence.""" + from .core import ArrayValueExpression + + return self._retype(ArrayValueExpression) + + def as_json(self) -> "JSONValueExpression": + """This yields a JSON document.""" + from .core import JSONValueExpression + + return self._retype(JSONValueExpression) + + def as_uuid(self) -> "UUIDValueExpression": + """This yields a UUID.""" + from .core import UUIDValueExpression + + return self._retype(UUIDValueExpression) + + def as_binary(self) -> "BinaryValueExpression": + """This yields bytes.""" + from .core import BinaryValueExpression + + return self._retype(BinaryValueExpression) + + def as_xml(self) -> "XMLValueExpression": + """This yields an XML document.""" + from .core import XMLValueExpression + + return self._retype(XMLValueExpression) + + +def _literal(dialect, value): + """Wrap a bare number as the Literal the factories now require. + + The factories take expressions, so a caller who writes ``col.power(3)`` has + to end up with an expression somewhere. Doing it here keeps the arithmetic + methods taking plain numbers, which is what a caller means by them, and puts + the construction in one place instead of at every call site. + """ + from .bases import BaseExpression + from .core import Literal + + return value if isinstance(value, BaseExpression) else Literal(dialect, value) + + +class NumericValueMixin: + """Operations on a **fractional**-valued expression. - This method enables expressions like: `predicate1 & predicate2` - The resulting LogicalPredicate uses the left operand's dialect for SQL generation. + Distinct from the integer value family (:class:`IntegerValueExpression`) + because ``ceil``/``floor``/``truncate`` of a whole number is a whole + number, while ``sqrt``/``log``/``abs`` of one may not be. SQL makes the + same distinction: a backend + returns ``numeric`` for ``ABS(numeric)`` and ``double precision`` for + ``ABS(double precision)``, so the family depends on the operand. + + Which one applies is decided per factory, not here — see + :func:`...functions.math.abs_`, which preserves the operand's family. This + mixin holds the operations whose result is fractional regardless. + + The SQL already existed as free functions in + :mod:`...expression.functions.math`; this mixin makes them reachable from + a numeric column. Each factory already tags its result with the right + family, so ``col.sqrt()`` is a number and ``col.sign()`` is an integer + without this mixin having to restate either. + + Example: + >>> col.abs() # ABS("price") + >>> col.round(2) # ROUND("price", 2) + >>> col.power(2) # POWER("price", 2) + >>> col.mod(3) # MOD("price", 3) + """ + + def _numeric_op(self, factory_name: str, *args, **kwargs): + """Call a math factory, which tags its own result type. Args: - other: Right operand, must be another SQLPredicate + factory_name: Name of the function in ``functions.math``. + args: Positional arguments forwarded to the factory. + kwargs: Keyword arguments forwarded to the factory. Returns: - SQLPredicate representing the logical AND operation + A numeric- or integer-valued expression, depending on what the + operation returns. + """ + from . import functions as _functions - Example: - >>> p1 = Column(dialect, "status") == "active" - >>> p2 = Column(dialect, "age") >= 18 - >>> combined = p1 & p2 # Generates: "(status = ?) AND (age >= ?)" + factory = getattr(_functions, factory_name) + return factory(self._dialect, self, *args, **kwargs) + + # --- sign-preserving --- + + def abs(self) -> "NumericValueMixin": + """Absolute value. ``ABS(col)`` + + Keeps the operand's family: absolute value of an integer is an + integer, and of a double is a double. """ - from .predicates import LogicalPredicate + return self._numeric_op("abs_") + + def sign(self) -> "NumericValueMixin": + """Sign of the value: -1, 0 or 1. ``SIGN(col)`` + + The three answers are whole numbers, but the **result is not declared + an integer**, because the backends do not return integers: measured + 2026-10-09 on PostgreSQL, an integer argument comes back + ``double precision`` and a numeric one comes back ``numeric``. A value + that carries the numeric surface stays usable for the arithmetic that + follows it, which an integer-tagged result would forbid. + """ + return self._numeric_op("sign") + + # --- rounding --- + + def round(self, decimals: Optional[int] = None) -> "NumericValueMixin": + """Round to *decimals* places, or to a whole number. ``ROUND(col[, n])`` + + Whether a **half** rounds up or to even is the backend's, and no two of + the answers line up on both axes — measured across MySQL 8.0/5.7/5.6, + MariaDB 11.7, PostgreSQL 18.6, Firebird 5.0.4, Oracle 23c, ClickHouse + 26.7 and SQL Server 2025: + + * on a **decimal/numeric**, half is **away from zero** on MySQL (all + three versions), MariaDB, PostgreSQL, Firebird, Oracle and SQL Server + (``ROUND(2.5)`` is 3, ``ROUND(3.5)`` is 4, ``ROUND(-2.5)`` is -3), and + half to **even** on **ClickHouse** (2.5 is 2.0, 0.5 is 0.0). One + server disagrees on this axis; + * on a **double/float**, half to **even** on MySQL 8.0, MariaDB, + PostgreSQL and ClickHouse, and half **away from zero** on Oracle, + Firebird and SQL Server. Four against three, and *not the same split* + as the decimal one — Oracle rounds a decimal away from zero and a + float away from zero while ClickHouse rounds its decimal to even and + its float to even, so the two axes realign there, while MySQL rounds + its decimal away and its float to even. + + Two further facts that are not about halves and matter more: + + * SQL Server **raises** on some halves: ``ROUND(0.5, 0)`` and + ``ROUND(-0.5, 0)`` are ``22003: arithmetic overflow``, where 2.5, 3.5 + and -2.5 round normally. So a half is not merely rounded differently + here, it can fail; + * MySQL 5.6 and 5.7 do not accept ``CAST(x AS DOUBLE)`` at all (a syntax + error), where 8.0 does — the same model, different answer by *server + version*, on top of the type. + + So "rounding" is a function of *(backend, backend version, column type)*, + and a caller comparing a rounded value against an unrounded one — or the + same expression on another backend — is relying on something no SQL here + promises. The portable way to state a rule is to not be at a half: + rounding is well-defined for every value that is not exactly ``.5``, and + a caller who cares should decide the tie-break in the model rather than + inherit whichever one the server, its version and the column type happen + to give. + """ + return self._numeric_op("round_", decimals) + + def ceil(self) -> "NumericValueMixin": + """Smallest integer not below the value. ``CEIL(col)``""" + return self._numeric_op("ceil") + + def floor(self) -> "NumericValueMixin": + """Largest integer not above the value. ``FLOOR(col)``""" + return self._numeric_op("floor") + + def truncate(self, precision: Optional[int] = None) -> "NumericValueMixin": + """Truncate toward zero. ``TRUNCATE(col[, n])`` + + Not the same as ``round`` for a negative value: truncation drops the + digits, rounding moves them. + + The core name is ``TRUNCATE``; the rendered one is the backend's, and + the backends are not even spelling-compatible among themselves -- + measured 2026-10-09: ``TRUNC`` on PostgreSQL, Oracle, Firebird, + BigQuery, SQLite and ClickHouse, ``TRUNCATE`` on MySQL, MariaDB and + Snowflake, and SQL Server has no scalar truncate at all, spelling it + ``ROUND(x, n, 1)``. A dialect override therefore renames rather than + re-implements. + """ + return self._numeric_op("truncate", precision) + + # --- roots, powers, logarithms --- + + def mod(self, divisor: Union[int, float, "BaseExpression"]) -> "NumericValueMixin": + """Remainder of division by *divisor*. ``MOD(col, n)``""" + return self._numeric_op("mod", _literal(self._dialect, divisor)) + + def sqrt(self) -> "NumericValueMixin": + """Square root. ``SQRT(col)`` + + Kept here rather than in :class:`TranscendentalMixin`: a square root is + an algebraic operation, and a monetary amount has a meaningful one + (an interest factor), which is why this mixin is the part a money + column can reuse. + """ + return self._numeric_op("sqrt") - return LogicalPredicate(self._dialect, "AND", self, other) + def power(self, exponent: Union[int, float, "BaseExpression"]) -> "NumericValueMixin": + """Raise to *exponent*. ``POWER(col, n)`` - def __or__(self: "SQLPredicate", other: "SQLPredicate") -> "SQLPredicate": + Compound interest makes this meaningful for a monetary amount, so it + belongs with the algebraic operations rather than the transcendental + ones. """ - Implement the logical OR operator (|) to generate SQL logical predicate. + return self._numeric_op("power", _literal(self._dialect, exponent)) + + +class TranscendentalMixin: + """Operations whose result falls outside the numeric domain. + + Split from :class:`NumericValueMixin` by *what the result is*, not by which + family the operand belongs to. ``exp``, ``log``, ``sin``, ``cos`` and + ``tan`` answer with a real number whatever they are handed: ``log(2)`` is + not a whole number even though 2 is, and ``sin(0)`` happens to be0 for a + reason that has nothing to do with the operand being whole. A caller that + wants a whole number back asks an operation that returns one — the + rounding rungs keep the operand's family, and these five are not among + them — rather than one that happens to land on an integer. + + ``sqrt`` and ``power`` are *not* here. They are algebraic, and a monetary + amount has a meaningful square root and a meaningful power — compound + interest is the obvious one — so a money column reuses those. What it does + not have is a logarithm, which is why this is the mixin it leaves out. + + A whole-number column still mixes this in. ``log(2)`` is a legal query that + the database will answer, and refusing to offer it would make an integer + behave differently from the float it widens to for no reason the caller can + see. A money column is different in kind, not in width: an interest rate is + a logarithm taken somewhere else, and none of these belong to the amount. + + Example: + >>> col.exp() # EXP("x") + >>> col.log() # LOG("x") + >>> col.sin() # SIN("x") + """ + + def _transcendental_op(self, factory_name: str, *args, **kwargs): + """Call a math factory, which tags its own result type. Args: - other: Right operand, must be another SQLPredicate + factory_name: Name of the function in ``functions.math``. + args: Positional arguments forwarded to the factory. + kwargs: Keyword arguments forwarded to the factory. Returns: - SQLPredicate representing the logical OR operation + A real-valued expression; none of these preserves the operand's + family. """ - from .predicates import LogicalPredicate + from . import functions as _functions + + factory = getattr(_functions, factory_name) + return factory(self._dialect, self, *args, **kwargs) + + # --- roots, powers, logarithms --- + # + # sqrt and power live in NumericValueMixin; only the logarithm is here. + + def exp(self) -> "NumericValueMixin": + """e raised to the power of the value. ``EXP(col)``""" + return self._transcendental_op("exp") + + def log(self, base: Optional[Union[int, float, "BaseExpression"]] = None) -> "NumericValueMixin": + """Natural logarithm, or logarithm to *base*. ``LOG(col[, base])`` + + Two spellings, two settled meanings (measured 2026-10-09 across the ten + backends): the one-argument form is the **natural** logarithm -- the one + exception is PostgreSQL, where ``log(x)`` is base 10 and ``ln(x)`` is + the natural one -- and the two-argument form takes the **base second**, + which is the order SQL Server, ClickHouse and BigQuery use natively and + the reverse of PostgreSQL's, MySQL's, MariaDB's, Oracle's, Firebird's + and Snowflake's. The meaning is fixed here; a dialect override swaps the + spelling or the argument order, never the semantics. + """ + base_expr = None if base is None else _literal(self._dialect, base) + return self._transcendental_op("log", base_expr) + + # --- trigonometry --- + + def sin(self) -> "NumericValueMixin": + """Sine. ``SIN(col)``""" + return self._transcendental_op("sin") + + def cos(self) -> "NumericValueMixin": + """Cosine. ``COS(col)``""" + return self._transcendental_op("cos") - return LogicalPredicate(self._dialect, "OR", self, other) + def tan(self) -> "NumericValueMixin": + """Tangent. ``TAN(col)``""" + return self._transcendental_op("tan") - def __invert__(self: "SQLPredicate") -> "SQLPredicate": + +class StringToIntegerMixin: + """Operations that read a **string** and produce an integer. + + Named for both ends of the direction: these accept a string and *return* a + number. ``"name".length()`` is a legal string operation whose result is a + number, and that number must not carry string operations — + ``LENGTH(name).upper()`` is a type error in every backend; putting the + result in its own family (:class:`IntegerValueExpression`) is what makes + the rule checkable instead of a convention. Because the receiver is a + string, the mixin is attached to the string classes only: an integer never + grows these methods, so ``LENGTH(name).length()`` cannot be constructed. + + Members are the SQL integer functions that read a string and produce a + count or a code. Arithmetic on the result comes from + :class:`ArithmeticMixin`, which the integer value expression also carries. + """ + + if TYPE_CHECKING: # pragma: no cover + from .core import IntegerValueExpression + + def position(self, substring: str) -> "IntegerValueExpression": + """1-based position of *substring*. ``POSITION(substring IN expr)`` + + The needle comes first here, matching the standard spelling, while + :meth:`strpos` takes the haystack first like its native function. Both + are one operation with two spellings, and each backend renders whichever + of them it has: PostgreSQL takes only ``POSITION(sub IN s)`` -- its + comma form is a syntax error -- SQL Server spells it ``CHARINDEX``, + ClickHouse and BigQuery put the haystack first, MySQL and MariaDB + ``LOCATE``, Oracle and Firebird ``INSTR``. """ - Implement the logical NOT operator (~) to generate SQL logical predicate. + from .functions import string as _string + + return _string.position(self._dialect, substring, self) + + # --- operations that read a string and produce a number --- + + def _integer_op(self, factory_name: str, *args): + """Call a string factory whose result is an integer. Args: - self: The predicate to negate + factory_name: Name of the function in ``functions.string``. + args: Positional arguments forwarded to the factory. Returns: - SQLPredicate representing the logical NOT operation + An :class:`IntegerValueExpression`. + """ + from . import functions as _functions + + factory = getattr(_functions, factory_name) + return factory(self._dialect, self, *args) + + def length(self) -> "IntegerValueExpression": + """Length of the string, in **whatever unit the backend's ``LENGTH`` uses**. + + ``LENGTH(expr)`` — and that unit is not characters everywhere, which is + the discipline this docstring exists to state rather than leave to be + discovered from a wrong answer. + + Measured per backend (``suggested-pairing-string-enum.md``, the S-length + row): + + * PostgreSQL, Oracle, Firebird — **characters**, so a 5-character string + reports 5 whatever its encoding; + * MySQL, MariaDB, ClickHouse — **bytes**, so the same string reports its + encoded length and a multi-byte character counts for more than one; + * SQL Server — **UTF-16 code units**, so a 5-character string holding + astral characters reports 10. There is no portable fix here: this + backend maps both ``LENGTH`` and ``CHAR_LENGTH`` to ``LEN``, and + ``LEN`` is what counts code units. + + Only the first group agrees with what this method's old one-line + docstring promised. A caller who needs a *character* count on every + backend therefore cannot use ``length`` alone; :meth:`octet_length` is + the honest byte count where the backend distinguishes them, and a + character count on MySQL-family backends needs the backend's own + ``CHAR_LENGTH`` spelled out through the function layer rather than + assumed here. + + What this method does **not** do is pick a unit and pretend it is + portable. The word ``LENGTH`` is the one every backend here has, so it + is the one written, and the difference is a property of the backends + rather than of the operation — the same shape as the ``= 1`` boolean + literal, where the framework refuses the non-portable spelling instead + of rendering it and hoping. + """ + return self._integer_op("length") - Example: - >>> p = Column(dialect, "status") == "active" - >>> negated = ~p # Generates: "NOT (status = ?)" + def ascii(self) -> "IntegerValueExpression": + """Code of the first character. ``ASCII(expr)``""" + return self._integer_op("ascii") + + def octet_length(self) -> "IntegerValueExpression": + """Length in bytes. ``OCTET_LENGTH(expr)``""" + return self._integer_op("octet_length") + + def bit_length(self) -> "IntegerValueExpression": + """Length in bits. ``BIT_LENGTH(expr)``""" + return self._integer_op("bit_length") + + def strpos(self, substring: str) -> "IntegerValueExpression": + """1-based position of *substring*, or 0. ``STRPOS(expr, substring)`` + + The mirror spelling of :meth:`position`: haystack first, as every + native ``STRPOS``/``LOCATE``/``INSTR``/``CHARINDEX`` takes it. On + backends with no such function a dialect renders the other spelling. """ - from .predicates import LogicalPredicate + return self._integer_op("strpos", substring) - return LogicalPredicate(self._dialect, "NOT", self) +class StringValueMixin: + """String **value** operations: each returns a new string-valued expression. -class StringMixin: + Distinct from :class:`StringPatternPredicateMixin`, which answers questions + about a string instead of deriving one. These operations derive, so they + chain: ``col.upper().substr(0, 3).length()`` stays a string until the last + step, which is numeric. + + The SQL itself comes from :mod:`...expression.functions.string`, where all + of these already existed as free functions; this mixin only makes them + reachable from a column and gives the result a string type so the next call + in the chain is available. Result types are honest about SQL semantics: + ``length``, ``ascii``, ``strpos``, ``octet_length`` and ``bit_length`` + return numbers, and they are not on this mixin. + + Example: + >>> col.upper().substr(1, 3) # SUBSTRING(UPPER("name"), 1, 3) + >>> col.length() > 5 # LENGTH("name") > ? """ - Provides string-specific operations like LIKE and ILIKE for SQL expressions. - This mixin adds string pattern matching capabilities to expressions, enabling - SQL LIKE and ILIKE operations for pattern matching. + def _string_op(self, factory_name: str, *args, **kwargs): + """Call a string factory and tag the result as a string value. + + Args: + factory_name: Name of the function in ``functions.string``. + args: Positional arguments forwarded to the factory. + kwargs: Keyword arguments forwarded to the factory. + + Returns: + A :class:`~...expression.core.StringValueExpression`. + """ + from . import functions as _functions + + factory = getattr(_functions, factory_name) + return factory(self._dialect, self, *args, **kwargs) + + # --- case --- + + def upper(self) -> "StringValueMixin": + """Upper-case the string. ``UPPER(col)``""" + return self._string_op("upper") + + def lower(self) -> "StringValueMixin": + """Lower-case the string. ``LOWER(col)``""" + return self._string_op("lower") + + def initcap(self) -> "StringValueMixin": + """Capitalise the first letter of each word. ``INITCAP(col)``""" + return self._string_op("initcap") + + def reverse(self) -> "StringValueMixin": + """Reverse the string. ``REVERSE(col)``""" + return self._string_op("reverse") + + def translate(self, from_chars: str, to_chars: str) -> "StringValueMixin": + """Replace characters pairwise. ``TRANSLATE(col, from, to)``""" + return self._string_op("translate", from_chars, to_chars) + + # --- slicing and padding --- + + def substr(self, start: int, length: Optional[int] = None) -> "StringValueMixin": + """Substring, 1-based. ``SUBSTRING(col, start[, length])`` + + ``start >= 1`` and ``length >= 0``; both are refused otherwise, because + an out-of-range position is consumed by the length on some backends, + yields an empty string on others and is read as 1 on Oracle (see + :func:`~...functions.string.substring`). + """ + return self._string_op("substring", start, length) + + def left(self, n: int) -> "StringValueMixin": + """First *n* characters. ``LEFT(col, n)`` + + ``n >= 0``: 0 is the empty string and more than the length is the whole + string on every backend. A negative count is refused at construction -- + the backends answer four different ways to it (see + :func:`~...functions.string.left`). + """ + return self._string_op("left", n) + + def right(self, n: int) -> "StringValueMixin": + """Last *n* characters. ``RIGHT(col, n)`` + + ``n >= 0``, with 0 and over-length agreeing everywhere; a negative + count is refused, same as :meth:`left`. + """ + return self._string_op("right", n) + + def lpad(self, length: int, pad: Optional[str] = None) -> "StringValueMixin": + """Left-pad to *length*. ``LPAD(col, length, pad)`` + + ``length >= 0`` and a non-empty *pad*; an omitted pad means one space + and is always spelled out, because MySQL raises 1582 without it while + MariaDB fills with spaces. An empty pad is refused -- the backends + answer it as untouched string, empty string or NULL. + """ + return self._string_op("lpad", length, pad) + + def rpad(self, length: int, pad: Optional[str] = None) -> "StringValueMixin": + """Right-pad to *length*. ``RPAD(col, length, pad)`` + + The mirror of :meth:`lpad`: ``length >= 0``, a non-empty *pad*, an + omitted pad spelled as one space, an empty pad refused. + """ + return self._string_op("rpad", length, pad) + + def repeat(self, count: int) -> "StringValueMixin": + """Repeat the string *count* times. ``REPEAT(col, count)`` + + A negative *count* is the empty string rather than a refusal -- the + native answer on PostgreSQL, MySQL, MariaDB and ClickHouse alike. + """ + return self._string_op("repeat", count) + + def overlay(self, replacement: str, start: int, length: Optional[int] = None) -> "StringValueMixin": + """Overwrite a span. ``OVERLAY(col PLACING replacement FROM start [FOR length])``""" + return self._string_op("overlay", replacement, start, length) + + # --- search and replace --- + + def replace(self, pattern: str, replacement: str) -> "StringValueMixin": + """Replace every occurrence. ``REPLACE(col, pattern, replacement)``""" + return self._string_op("replace", pattern, replacement) + + # --- whitespace --- + + def trim(self, chars: Optional[str] = None, direction: str = "BOTH") -> "StringValueMixin": + """Trim whitespace or *chars*. ``TRIM([direction] [chars] FROM col)`` + + Args: + chars: One character to trim, or ``None`` for spaces. A + multi-character set is refused: SQL:2016 feature E021-09 + defines a single trim character, and in the field a longer set + is a character set on PostgreSQL/SQL Server/ClickHouse/ + Snowflake, a whole string repeated on MySQL/MariaDB/Firebird + and ``ORA-30001`` on Oracle. + direction: One of ``BOTH`` (default), ``LEADING``, ``TRAILING``. + """ + return self._string_op("trim", chars=chars, direction=direction) + + # --- combination --- + + def concat(self, *others) -> "StringValueMixin": + """Concatenate with other values. ``CONCAT(col, ...)`` + + Note: SQL ``||`` is not used. Its meaning is dialect-dependent — it is + logical OR by default in MySQL — so the portable function is the only + spelling offered here. + """ + from .functions import string as _string + from .core import Literal + + operands = [self] + for other in others: + operands.append(other if hasattr(other, "to_sql") else Literal(self._dialect, other)) + return _string.concat(self._dialect, *operands) + + def concat_using_operator(self, *others) -> "StringValueMixin": + """Concatenate using whatever spelling this dialect uses for ``||``. + + The operator is resolved by the dialect, not baked in: MySQL, MariaDB + and SQL Server read a literal ``||`` as logical OR, and BigQuery does + not accept it as concatenation, so those render ``CONCAT(a, b)`` while + the rest emit ``a || b``. Either way the *intent* is concatenation. + + Prefer :meth:`concat` unless the operator form is specifically wanted; + it renders the same thing but reads more clearly at the call site. + """ + from .functions import string as _string + from .core import Literal + + operands = [self] + for other in others: + operands.append( + other if hasattr(other, "to_sql") else Literal(self._dialect, other) + ) + return _string.concat_op(self._dialect, *operands) + + def coalesce(self, *others) -> "StringValueMixin": + """First non-null value. ``COALESCE(col, ...)``""" + from .functions import string as _string + from .core import Literal + + operands = [self] + for other in others: + operands.append(other if hasattr(other, "to_sql") else Literal(self._dialect, other)) + return _string.coalesce(self._dialect, *operands) + + +class StringPatternPredicateMixin: + """Pattern-matching **predicates** on a string-valued expression. + + This is a predicate surface, not a set of value operations: ``like`` and + ``ilike`` produce no new value, they answer a yes/no question about the + operand. In SQL they are not functions either — ``LIKE`` sits in the + predicate grammar beside ``=`` and ``<``, and appears wherever a boolean is + legal: a SELECT list, ``CASE WHEN``, ``JOIN ... ON``, a ``CHECK`` + constraint, a partial-index predicate. It is therefore not something a + *column* owns. + + The previous class was named ``StringMixin`` and held only these two + methods, so a class called ``StringColumn`` offered no string operations at + all — it offered the ability to be LIKE-matched. String *value* operations + live in :class:`StringValueMixin`. + + Crossing into a predicate ends the value chain: the result is a boolean and + can be combined with ``&`` / ``|`` / ``~``, but it never becomes a string + again. Example: >>> col = Column(dialect, "name") - >>> # Pattern matching - >>> starts_with_a = col.like("A%") # Generates: "name LIKE ?" with params ("A%",) - >>> contains_substring = col.ilike("%hello%") # Generates: "name ILIKE ?" with params ("%hello%",) + >>> starts_with_a = col.like("A%") # "name LIKE ?" params ("A%",) + >>> both = col.like("A%") & (col.ilike("%x%") | col.like("B%")) """ def like(self: "SQLValueExpression", pattern: str) -> "SQLPredicate": """ - Generate a LIKE predicate for pattern matching (case-sensitive). + Generate a LIKE predicate for pattern matching. - This method enables SQL LIKE operations for pattern matching with wildcards: - % matches zero or more characters - _ matches a single character + **Case sensitivity is the backend's, not this method's.** Measured + 2026-10-09: SQLite, MySQL, MariaDB and SQL Server match + ``'abc' LIKE 'A%'`` case-insensitively (following their collation), + while PostgreSQL, ClickHouse, Oracle and BigQuery are case-sensitive + and Firebird follows its collation. Nothing here changes that, and no + ``COLLATE`` clause bolted onto the predicate rescues it on SQLite. + A predicate that must mean the same thing everywhere is + :meth:`ilike`. + Args: pattern: Pattern string with SQL LIKE wildcards @@ -617,20 +1876,26 @@ def like(self: "SQLValueExpression", pattern: str) -> "SQLPredicate": def ilike(self: "SQLValueExpression", pattern: str) -> "SQLPredicate": """ - Generate an ILIKE predicate for case-insensitive pattern matching. + Generate a case-insensitive pattern-matching predicate. - This method enables SQL ILIKE operations for case-insensitive pattern matching. - Not all databases support ILIKE, but it's commonly available in PostgreSQL. + This is the one spelling in the framework that *means* + case-insensitive, where :meth:`like` makes no such promise (its + sensitivity is the backend's). Backends with a native ``ILIKE`` + (PostgreSQL, ClickHouse, Snowflake) render it; the rest are meant to + emulate it as ``LOWER(x) LIKE LOWER(y)`` through the dialect, which + folds ASCII rather than the full Unicode case the native operators do. + Check the operation-groups survey for the per-backend state before + relying on a backend that lacks the native form. Args: pattern: Pattern string with SQL LIKE wildcards Returns: - SQLPredicate representing the ILIKE operation + SQLPredicate representing the case-insensitive pattern match Example: >>> col = Column(dialect, "email") - >>> predicate = col.ilike("%@gmail.com") # Matches Gmail addresses regardless of case + >>> predicate = col.ilike("%@gmail.com") # Matches regardless of case >>> # Generates: "email ILIKE ?" with params ("%@gmail.com",) """ from .core import Literal @@ -652,12 +1917,12 @@ class TypeCastingMixin: Example: >>> col = Column(dialect, "price") - >>> expr = col.cast("INTEGER") + >>> expr = col.cast(IntegerType(col.dialect)) >>> # Generates: CAST("price" AS INTEGER) >>> # PostgreSQL generates: "price"::INTEGER >>> >>> # Chained conversions (each cast nests the previous node) - >>> expr3 = col.cast("money").cast("numeric").cast("float8") + >>> expr3 = col.cast(MoneyType(col.dialect)).cast(NumericType(col.dialect)) >>> # Generates: CAST(CAST(CAST("price" AS money) AS numeric) AS float8) >>> # PostgreSQL generates: "price"::money::numeric::float8 """ @@ -683,7 +1948,7 @@ def cast(self: "SQLValueExpression", target_type: str) -> "CastExpression": # Alias decorates the outermost rendered form: wrapping an aliased # expression in a CAST moves the alias onto the CAST node, so - # `col.cast("INTEGER").as_("v")` and `col.as_("v").cast("INTEGER")` + # `col.cast(IntegerType(...)).as_("v")` and `col.as_("v").cast(IntegerType(...))` # both render `CAST(col AS INTEGER) AS v`. The original expression # is only mutated when it is itself a temporary copy (the as_() # convention returns copies), so shared nodes stay untouched. @@ -692,3 +1957,273 @@ def cast(self: "SQLValueExpression", target_type: str) -> "CastExpression": if alias is not None and hasattr(self, "alias"): self.alias = None return node + + +class DateTimeMixin: + """Temporal operations available on a value known to hold a date/time. + + Every method here wraps *this* expression in a proper AST node and hands + rendering to the dialect (``format_extract_expression``, + ``format_date_trunc_expression``, ``format_datetime_add_expression``, …). + No SQL is built by this mixin, and the expression nodes it constructs + already exist — this is a thin, dialect-neutral façade over them. + + The mixin is mixed into :class:`~...expression.column_types.TimestampColumn` + only, so a numeric or string column cannot reach these operations. + + Chaining nests like any other expression:: + + >>> col = TimestampColumn(dialect, "created_at") + >>> col.date_trunc("month") + >>> # -> DATE_TRUNC('month', "created_at") + >>> col.date_trunc("day").extract("year") + >>> # -> EXTRACT(year FROM DATE_TRUNC('day', "created_at")) + + Note: + ``now()`` / ``current_date()`` / ``current_timestamp()`` are + deliberately absent: they take no column and belong to the + ``functions.datetime`` module, not to a column's own surface. + + Time zones, stated because they are not portable + ------------------------------------------------ + Measured on MySQL 8.0/5.7/5.6, MariaDB 11.7, PostgreSQL 18.6, Firebird 5.0.4, + Oracle 23c, ClickHouse 26.7 and SQL Server 2025, and the differences are + load-bearing rather than cosmetic: + + * **MySQL everywhere drops the offset.** ``CAST('2026-01-01 + 12:00:00+08:00' AS DATETIME)`` reads back ``12:00`` with no zone on 8.0, + 5.7 and 5.6 alike — the offset is parsed away rather than converted. + ``CONVERT_TZ`` is the only conversion available and needs the zone tables + loaded to name a region. Their introspection reports the column as plain + ``timestamp``: there is no time-zone word in the type at all; + * **SQL Server rejects the literal outright.** The same ``CAST`` is + ``22007`` there, and the spelling that works is ``DATETIMEOFFSET``, which + preserves the offset as ``2026-01-01 12:00:00.0000000 +08:00``. So a + ``DATETIME`` on SQL Server and a ``DATETIME`` on MySQL fail in opposite + ways — one refuses, one accepts and forgets; + * **PostgreSQL renders a ``timestamptz`` through the *session* time zone.** + One row holding ``2026-01-01 12:00:00+08:00`` reads back as + ``04:00+00`` under ``SET TIME ZONE 'UTC'`` and ``12:00+08`` under + ``Asia/Shanghai`` — five sessions, five strings. The *instant* does not + move: ``extract(epoch FROM ts)`` is ``1767240000`` under both. So this is + a rendering dependency and not a corruption, which is what makes it easy + to miss: a comparison of two rendered strings from two sessions looks like + a data difference and is not one; + * **ClickHouse** converts on parse: ``parseDateTimeBestEffort`` on the same + literal yields ``04:00``, and ``toDateTime(v, 'Asia/Shanghai')`` yields + ``12:00`` attached to that zone. It has the zone word in the type; + * **Firebird** has both, and the column's type decides. A plain + ``TIMESTAMP`` reads back naive, and ``TIMESTAMP WITH TIME ZONE`` really + does hold the zone — the same ``+08:00`` literal reads back with a + ``tzstr('UTC+08:00')`` attached. What it has no form for is a *named* + region: the offset is stored, the region is not. + + What follows for a caller: a naive ``datetime`` is portable everywhere here, + and an aware one is not. The same field annotated with an aware datetime + will store the instant on PostgreSQL and ClickHouse, the wall-clock string on + MySQL, and fail to build at all on SQL Server. Deciding which of those a + model means is the model author's, and this façade does not choose it by + rendering a conversion the caller did not ask for. + """ + + def _temporal_node(self, node_class, *args, **kwargs): + """Build *node_class* over this expression, hoisting the alias. + + Mirrors :meth:`TypeCastingMixin.cast`: the alias decorates the + outermost rendered form, so ``col.as_("d").date_trunc("day")`` and + ``col.date_trunc("day").as_("d")`` both render the same SQL. The + receiver is only mutated when it is itself a temporary copy (the + ``as_()`` convention returns copies). + """ + alias = getattr(self, "alias", None) + node = node_class(self._dialect, *args, alias=alias, **kwargs) + if alias is not None and hasattr(self, "alias"): + self.alias = None + return node + + def extract(self, field: str) -> "ExtractExpression": + """Extract one field as a number, e.g. ``col.extract("year")``.""" + from .datetime import ExtractExpression + + return self._temporal_node(ExtractExpression, field, self) + + def date_part(self, field: str) -> "DatePartExpression": + """SQL-standard spelling of :meth:`extract`.""" + from .datetime import DatePartExpression + + return self._temporal_node(DatePartExpression, field, self) + + def date_trunc(self, field: str) -> "DateTruncExpression": + """Truncate to *field*, e.g. ``col.date_trunc("month")``.""" + from .datetime import DateTruncExpression + + return self._temporal_node(DateTruncExpression, field, self) + + def date_add(self, value, unit: Optional[str] = None) -> "DateTimeAddExpression": + """Add an interval, e.g. ``col.date_add(7, "day")``.""" + from .datetime import DateTimeAddExpression + + return self._temporal_node( + DateTimeAddExpression, self, _as_interval(self._dialect, value, unit) + ) + + def date_sub(self, value, unit: Optional[str] = None) -> "DateTimeSubtractExpression": + """Subtract an interval, e.g. ``col.date_sub(1, "month")``.""" + from .datetime import DateTimeSubtractExpression + + return self._temporal_node( + DateTimeSubtractExpression, self, _as_interval(self._dialect, value, unit) + ) + + def date_diff(self, unit: str, end) -> "DateTimeDiffExpression": + """Difference between this value and *end*, expressed in *unit*.""" + from .datetime import DateTimeDiffExpression + + return self._temporal_node(DateTimeDiffExpression, unit, self, end) + + +def _as_interval(dialect, value, unit: Optional[str]): + """Coerce ``(value, unit)`` or an ``IntervalExpression`` to an interval. + + A bare number needs its unit; an already-built interval must not be given + one, since that would be ambiguous. + """ + from .datetime import IntervalExpression + + if isinstance(value, IntervalExpression): + if unit is not None: + raise ValueError("unit must not be provided when value is an IntervalExpression") + return value + if unit is None: + raise ValueError("unit is required when value is numeric") + return IntervalExpression(dialect, value, unit) + + +class ArrayMixin: + """Array operations available on a value known to hold an array. + + Mixed into :class:`~...expression.column_types.ArrayColumn` only. The + expression nodes and dialect formatters already exist; this is a thin + façade so a caller does not have to thread the dialect by hand. + """ + + def array_length(self, dimension: int = 1) -> "FunctionCall": + """Number of elements, e.g. ``col.array_length()``.""" + from .functions.array import array_length + + return array_length(self._dialect, self, dimension) + + def unnest(self, alias: Optional[str] = None) -> "FunctionCall": + """Expand this array into rows, e.g. in a FROM clause.""" + from .functions.array import unnest + + return unnest(self._dialect, self) + + +class JSONAccessorMixin: + """Path access for a value known to hold JSON. + + Mixed into **both** :class:`~...expression.column_types.JSONColumn` and + :class:`~...expression.advanced_functions.JSONDocumentExpression` — the latter is + what :meth:`json_path` returns, so without it on both, chaining + ``col.json_value("a").json_value("b")`` would break at the second call. + + Two shapes, matching the two JSON access operators: + + * :meth:`json_path` (``->>``) yields a **scalar** and ends the chain. + * :meth:`json_value` (``->``) yields **JSON** and can be chained again. + + Keys accumulate into one path rather than nesting two expressions. + That matters: nesting two paths re-anchors the second one at ``$`` and + applies ``->`` to the previous result, which is wrong on every backend + (``->`` on the text that ``->>`` returned, and ``$.b`` matching nothing). + + Example: + >>> col = JSONColumn(dialect, "settings") + >>> col.json_path("a", "b") # -> "settings"->>'$.a.b' + >>> col.json_path("tags", 0) # -> "settings"->>'$.tags[0]' + >>> col.json_value("a").json_value("b") # -> "settings"->'$.a'->'$.b' + """ + + def _json_path(self, keys, as_text: bool, mode) -> "SQLValueExpression": + from .advanced_functions import ( + JSONDocumentExpression, + JSONTextExpression, + ) + + alias = getattr(self, "alias", None) + # The two operations yield different types, so they build different + # nodes: `->>` is text and offers the text operations, `->` is a + # document and offers the path accessors again. + node_class = JSONTextExpression if as_text else JSONDocumentExpression + node = node_class( + self._dialect, + self, + build_json_path(*keys), + operation="->>" if as_text else "->", + alias=alias, + mode=mode, + ) + if alias is not None and hasattr(self, "alias"): + self.alias = None + return node + + def json_path(self, *keys, mode=None) -> "JSONTextExpression": + """Extract a scalar at *keys* (renders ``->>``). + + Args: + *keys: Path segments. An ``int`` is an array index and renders + as ``[n]``; a ``str`` is always an object key, so ``"0"`` + renders ``.0`` (a key literally named ``0``) — pass the int + ``0`` for the first element. A string that already starts + with ``[`` is passed through, so a caller can express a + native path segment this helper does not model. + mode: Optional :class:`JSONPathMode` (or its string value) to + force arrow or function-based rendering. + """ + return self._json_path(keys, as_text=True, mode=mode) + + def json_value(self, *keys, mode=None) -> "JSONDocumentExpression": + """Extract JSON at *keys* (renders ``->``), preserving the JSON type. + + Chainable: the result is itself a JSON expression, so further + segments can be appended. + """ + return self._json_path(keys, as_text=False, mode=mode) + + +def build_json_path(*keys) -> str: + """Join path *keys* into a JSONPath rooted at ``$``. + + Array indices must render as ``[n]``: ``$.tags.0`` is an object key + literally named ``0`` and matches nothing, while ``$.tags[0]`` is the + first element. A segment that already looks like a native path segment + (starts with ``[``) is passed through untouched so callers can express + anything this helper does not cover. + + A ``str`` is **always** an object key, including one that looks like a + number — ``"0"`` is a key named ``0``, not an index. The distinction is + the type, not the spelling, so ``json_path("tags", 0)`` is the first + element and ``json_path("tags", "0")`` is the key ``"0"``. + + Example: + >>> build_json_path("a", "b") + '$.a.b' + >>> build_json_path("tags", 0) + '$.tags[0]' + >>> build_json_path("tags", "[0]") + '$.tags[0]' + """ + path = "$" + for key in keys: + if isinstance(key, bool): + # bool is an int subclass; treating True as index 1 would be a + # silent, baffling bug. + raise TypeError(f"JSON path segment must be str or int, got bool: {key!r}") + if isinstance(key, int): + path += f"[{key}]" + elif isinstance(key, str) and key.startswith("["): + path += key + else: + path += f".{key}" + return path diff --git a/src/rhosocial/activerecord/backend/expression/operators.py b/src/rhosocial/activerecord/backend/expression/operators.py index 536d4418f..79d2e11d2 100644 --- a/src/rhosocial/activerecord/backend/expression/operators.py +++ b/src/rhosocial/activerecord/backend/expression/operators.py @@ -8,13 +8,15 @@ dialect through the subtree, and hands it to the declared formatter. """ -from typing import Optional, TYPE_CHECKING -from .bases import BaseExpression, SQLPredicate, SQLValueExpression +from typing import Any, List, Optional, Tuple, TYPE_CHECKING +from .bases import BaseExpression, SQLPredicate, SQLQueryAndParams, SQLValueExpression from .mixins import ( AliasableMixin, ArithmeticMixin, ComparisonMixin, - StringMixin, + NumericValueMixin, + StringPatternPredicateMixin, + StringValueMixin, TypeCastingMixin, ) @@ -51,6 +53,44 @@ def __init__(self, dialect: "SQLDialectBase", op: str, left: "BaseExpression", r self.right = right +class StringConcatExpression( + AliasableMixin, + ComparisonMixin, + StringPatternPredicateMixin, + StringValueMixin, + BinaryExpression, +): + + """String concatenation, stated as an intent rather than an operator. + + ``||`` is the SQL standard's concatenation operator and PostgreSQL, + Oracle, Snowflake, Firebird and ClickHouse all read it that way. MySQL and + MariaDB read it as logical OR unless the server runs with + ``PIPES_AS_CONCAT``, and SQL Server reads it as logical OR outright, so + emitting ``a || b`` there yields a boolean where a string was meant — a + wrong answer rather than a syntax error, which is the worst kind. + + Carrying the intent on the node lets each dialect pick its own spelling: + :meth:`format_string_concatenation` emits ``a || b`` by default and + ``CONCAT(a, b)`` where ``||`` means something else. Passing a bare ``||`` + through :class:`BinaryExpression` cannot work, because the token alone does + not say which of the two meanings was meant. + + This is not the path for logical OR. That goes through + :class:`~...expression.predicates.LogicalPredicate`, which has its own + formatter, so the two never meet. + + The result is a string, so it carries the string value surface and the + chain continues: ``col.concat_using_operator(other).upper()`` is + ``UPPER(col || other)``. + """ + + def __init__( + self, dialect: "SQLDialectBase", left: "BaseExpression", right: "BaseExpression" + ): + super().__init__(dialect, "||", left, right) + + class UnaryExpression(BaseExpression): """Represents a unary SQL operation.""" @@ -66,7 +106,7 @@ def __init__(self, dialect: "SQLDialectBase", op: str, operand: "BaseExpression" self.pos = pos -class RawSQLExpression(ArithmeticMixin, ComparisonMixin, StringMixin, SQLValueExpression): +class RawSQLExpression(ArithmeticMixin, ComparisonMixin, StringPatternPredicateMixin, SQLValueExpression): """Represents a raw SQL expression string that is directly embedded. Note: This class should be used with caution. It bypasses the normal expression @@ -119,7 +159,8 @@ def __init__(self, dialect: "SQLDialectBase", expression: str, params: tuple = ( class BinaryArithmeticExpression( - AliasableMixin, ArithmeticMixin, ComparisonMixin, TypeCastingMixin, SQLValueExpression + AliasableMixin, ArithmeticMixin, NumericValueMixin, ComparisonMixin, + TypeCastingMixin, SQLValueExpression ): """Represents a binary arithmetic operation.""" diff --git a/src/rhosocial/activerecord/backend/expression/predicates.py b/src/rhosocial/activerecord/backend/expression/predicates.py index 25d25b18b..37e0f2b45 100644 --- a/src/rhosocial/activerecord/backend/expression/predicates.py +++ b/src/rhosocial/activerecord/backend/expression/predicates.py @@ -168,6 +168,40 @@ def __init__( self.negate = negate +class DistinctFromPredicate(SQLPredicate): + """Represents a NULL-safe ``IS [NOT] DISTINCT FROM`` comparison. + + ``a != b`` answers NULL when either side is NULL; this predicate asks the + question that survives NULL -- "are these two different, NULL included" -- + which is what a caller filtering for "not equal" usually means. The + spelling is a dialect matter (``IS NOT DISTINCT FROM`` is ``ORA-00908`` on + Oracle, and SQL Server only learned it in 2022), so the node delegates to + the dialect's ``format_distinct_from_predicate`` hook rather than + hard-coding the SQL here. + + Attributes: + left: Left operand with ``to_sql()``. + right: Right operand with ``to_sql()``. + is_not: If True, renders ``IS NOT DISTINCT FROM`` instead. + + Example: + >>> expr = DistinctFromPredicate(dialect, Column(dialect, "age"), Literal(dialect, 0)) + >>> expr.to_sql() + ('"age" IS DISTINCT FROM ?', (0,)) + """ + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_distinct_from_predicate" + + def __init__(self, dialect: "SQLDialectBase", left: Any, right: Any, is_not: bool = False): + super().__init__(dialect) + self.left = left + self.right = right + self.is_not = is_not + + class IsBooleanPredicate(SQLPredicate): """Represents an IS TRUE, IS NOT TRUE, IS FALSE, or IS NOT FALSE predicate. diff --git a/src/rhosocial/activerecord/backend/expression/query_parts.py b/src/rhosocial/activerecord/backend/expression/query_parts.py index cdbd65267..090a45668 100644 --- a/src/rhosocial/activerecord/backend/expression/query_parts.py +++ b/src/rhosocial/activerecord/backend/expression/query_parts.py @@ -309,11 +309,7 @@ class QualifyClause(BaseExpression): partition_by=[Column(dialect, "department")], order_by=[(Column(dialect, "salary"), "DESC")] ) - rank_func = WindowFunctionCall( - dialect, - function_name="ROW_NUMBER", - window_spec=window_spec - ) + rank_func = FunctionCall(dialect, "ROW_NUMBER", window_spec=window_spec) qualify_clause = QualifyClause( dialect, diff --git a/src/rhosocial/activerecord/backend/expression/statements/ddl_domain.py b/src/rhosocial/activerecord/backend/expression/statements/ddl_domain.py index 8bbfa9e9f..e080252e1 100644 --- a/src/rhosocial/activerecord/backend/expression/statements/ddl_domain.py +++ b/src/rhosocial/activerecord/backend/expression/statements/ddl_domain.py @@ -6,8 +6,12 @@ from typing import Any, List, Optional, Sequence, TYPE_CHECKING from ..bases import BaseExpression, SQLPredicate, SQLValueExpression +from ..mixins import ( + ComparisonMixin, + StringPatternPredicateMixin, + TypeCastingMixin, +) from ..objects import Domain -from ..mixins import ComparisonMixin, StringMixin, TypeCastingMixin from ..types import DataType from .ddl_table import DefaultValueClause @@ -36,7 +40,7 @@ class DomainNullability(Enum): class DomainValueExpression( ComparisonMixin, - StringMixin, + StringPatternPredicateMixin, TypeCastingMixin, SQLValueExpression, ): diff --git a/src/rhosocial/activerecord/backend/expression/statements/dml.py b/src/rhosocial/activerecord/backend/expression/statements/dml.py index 11662ae44..d65dad45b 100644 --- a/src/rhosocial/activerecord/backend/expression/statements/dml.py +++ b/src/rhosocial/activerecord/backend/expression/statements/dml.py @@ -444,18 +444,34 @@ def statement_type(self) -> StatementType: # region Insert Statement -class InsertDataSource(BaseExpression): +class InsertDataSource(BaseExpression, abc.ABC): """ Abstract base class for an INSERT statement's data source. Implementations represent the source of data, such as a VALUES clause, a SELECT query, or the DEFAULT VALUES keyword. - These are expressions like any other: each concrete kind declares the one - dialect method that renders it, and the statement asks the source for its - SQL rather than picking a branch per kind. Being an expression is also what - lets one survive a serialization round-trip. + **A source is a value object inside an expression tree, so it is a + :class:`BaseExpression`** — the same standing every other value object in + a tree has (``DataType``, ``TableExpression``, ``Literal``). That is what + gives it a serialization contract: ``get_params()`` reads the constructor + signature and the serializer encodes any ``BaseExpression`` it finds, so a + source survives ``serialize()`` / ``serialize_json()`` / ``serialize_xml()`` + and comes back as the same class. An ``InsertExpression`` holding a source + is therefore portable, which is the whole point of an expression tree: the + statement can be built once and sent to any dialect. + + It is deliberately *not* a standalone renderable: an INSERT's data source + has no SQL of its own — ``VALUES (...), (...)``, a sub-select and + ``DEFAULT VALUES`` are three different spellings chosen by the *statement* + formatter, which dispatches on the source type + (``format_insert_statement``). So no ``format_method`` is declared here and + calling ``to_sql()`` on a source raises, exactly as for any expression that + has not declared one. The tree renders through the enclosing INSERT. """ + def __init__(self, dialect: "SQLDialectBase"): + super().__init__(dialect) + class ValuesSource(InsertDataSource): """ diff --git a/src/rhosocial/activerecord/backend/expression/statements/dql.py b/src/rhosocial/activerecord/backend/expression/statements/dql.py index df7e67be0..e04c0c2e0 100644 --- a/src/rhosocial/activerecord/backend/expression/statements/dql.py +++ b/src/rhosocial/activerecord/backend/expression/statements/dql.py @@ -105,12 +105,7 @@ class QueryExpression(ArithmeticMixin, ComparisonMixin, SQLValueExpression): partition_by=[Column(dialect, "department")], order_by=[(Column(dialect, "salary"), "DESC")] ) - window_func = WindowFunctionCall( - dialect, - function_name="ROW_NUMBER", - window_spec=window_spec, - alias="row_num" - ) + window_func = FunctionCall(dialect, "ROW_NUMBER", window_spec=window_spec, alias="row_num") window_query = QueryExpression( dialect, diff --git a/src/rhosocial/activerecord/backend/expression/type_name.py b/src/rhosocial/activerecord/backend/expression/type_name.py new file mode 100644 index 000000000..4b0c98e66 --- /dev/null +++ b/src/rhosocial/activerecord/backend/expression/type_name.py @@ -0,0 +1,132 @@ +# src/rhosocial/activerecord/backend/expression/type_name.py +"""The grammar a SQL type name is allowed to have. + +Two positions in a statement take a type name and neither accepts a bound +parameter: ``CAST(expr AS type)`` and PostgreSQL's ``expr::type``. Both are +grammar productions rather than expressions, so there is no ``?`` to bind and +the name has to be rendered into the statement. Anything that ends the type +and starts a new statement, or opens a subquery, goes straight through. + +So the defence is the grammar. A type name is an identifier, optionally +qualified, optionally carrying a precision or an array marker — plus the +multi-word built-in names, which are the one thing that is not a bare +identifier. Restricting *characters* rather than the *set of names* is what +keeps user-defined and extension types working: ``vector``, ``hstore``, +``ltree`` and ``myschema.mytype`` are all ordinary identifiers, and nothing in +this module has to know they exist. + +Validation lives here rather than in each dialect's formatter because a +per-formatter check is a per-formatter bug waiting to happen — PostgreSQL's +``::`` override is exactly that, having skipped the check the generic +``CAST`` path performs. +""" + +# src/rhosocial/activerecord/backend/expression/type_name.py +import re +from typing import Optional + + +#: Multi-word built-in type names. The only reason a type name is not a bare +#: identifier, and enumerated rather than allowed through by permitting +#: spaces, so that ``INTEGER, (SELECT ...)`` still cannot be spelled. +MULTI_WORD_TYPE_NAMES = frozenset({ + "big int", "binary varying", "bit varying", "character varying", + "double precision", "national character", "national character varying", + "time with time zone", "time without time zone", + "timestamp with time zone", "timestamp without time zone", + "unsigned big int", "unsigned int", "unsigned small int", "unsigned tiny int", + "character large object", "binary large object", +}) + +#: One identifier segment. Deliberately excludes every quote, space and +#: punctuation character that could end the type or begin something else. +_IDENT = r"[A-Za-z_][A-Za-z0-9_$]*" + +#: ``schema.name``, then an optional ``(n)`` or ``(n, m)``, then array markers. +_QUALIFIED = rf"{_IDENT}(?:\s*\.\s*{_IDENT})?" +#: Precision is numeric, not an identifier: VARCHAR(255), NUMERIC(10, 2). +_PRECISION = r"(?:\s*\(\s*\d+(?:\s*,\s*\d+)?\s*\))?" + +#: Array markers, as many as the type is nested. +_MODIFIERS = rf"{_PRECISION}\s*(?:\[\s*\])*" + +_TYPE_NAME_RE = re.compile(rf"^{_QUALIFIED}{_MODIFIERS}$", re.ASCII) + + +class InvalidTypeNameError(ValueError): + """Raised when a string cannot be used as a SQL type name. + + A :class:`ValueError` rather than a dialect error, because the name is + rejected before a dialect is ever consulted: the position it would occupy + cannot hold a parameter on any backend. + """ + + def __init__(self, value: object) -> None: + self.value = value + super().__init__( + f"{value!r} is not a usable SQL type name. A type name is an " + f"identifier, optionally schema-qualified, optionally with a " + f"precision such as (10, 2) and array markers: " + f"varchar(255), myschema.mytype, text[]. " + f"It cannot contain quotes, semicolons, commas outside the " + f"parentheses or a comment marker, because that position cannot " + f"take a bound parameter." + ) + + +def is_valid_type_name(value: object) -> bool: + """Whether *value* is a SQL type name this package will render. + + Args: + value: The candidate, normally a string. + + Returns: + True when the name matches the grammar above. + """ + try: + validate_type_name(value) + except InvalidTypeNameError: + return False + return True + + +def validate_type_name(value: object) -> str: + """Return *value* when it is a usable SQL type name, else raise. + + Args: + value: The candidate, normally a string. + + Returns: + The name, unchanged, so this can wrap a constructor argument. + + Raises: + InvalidTypeNameError: If the name cannot be rendered safely. + """ + if not isinstance(value, str): + raise InvalidTypeNameError(value) + # A multi-word built-in may carry a precision or array markers, and the + # precision is not always at the end: PostgreSQL spells it + # `timestamp(3) with time zone`. So the words are matched rather than the + # string, with each word stripped of a trailing precision on the way. + words = value.split() + if len(words) > 1: + bare = [] + for word in words: + # strip() would only remove the outer parentheses and leave + # `varying(20`; the word with its precision removed is what the + # list is keyed by. + m = re.fullmatch(rf"({_IDENT})\(\s*\d+\s*\)", word) + bare.append((m.group(1) if m else word).lower()) + if " ".join(bare) in MULTI_WORD_TYPE_NAMES: + return value + if _TYPE_NAME_RE.match(value): + return value + raise InvalidTypeNameError(value) + + +__all__ = [ + "InvalidTypeNameError", + "MULTI_WORD_TYPE_NAMES", + "is_valid_type_name", + "validate_type_name", +] diff --git a/src/rhosocial/activerecord/backend/expression/types/__init__.py b/src/rhosocial/activerecord/backend/expression/types/__init__.py index 3fd9636ac..13e7ca064 100644 --- a/src/rhosocial/activerecord/backend/expression/types/__init__.py +++ b/src/rhosocial/activerecord/backend/expression/types/__init__.py @@ -47,8 +47,9 @@ from ._base import DataType from .array import ArrayType from .custom import CustomType +from ..type_name import InvalidTypeNameError from .enum_ import EnumType -from .integer import TinyIntType, SmallIntType, IntType, IntegerType, BigIntType +from .integer import TinyIntType, SmallIntType, IntegerType, BigIntType from .numeric import FloatType, RealType, DoubleType, DecimalType from .string import CharType, VarCharType, TextType from .boolean import BooleanType @@ -61,9 +62,15 @@ TimestampType, TimestampTzType, IntervalType, + INTERVAL_QUALIFIERS, + InvalidIntervalQualifierError, + IntervalQualifier, + is_valid_interval_qualifier, + validate_interval_qualifier, ) from .uuid_ import UUIDType from .json_ import JsonType, JsonBType +from .xml_ import XmlType __all__ = [ "DataType", @@ -72,7 +79,6 @@ # integer "TinyIntType", "SmallIntType", - "IntType", "IntegerType", "BigIntType", # numeric @@ -80,6 +86,7 @@ "RealType", "DoubleType", "DecimalType", + "InvalidTypeNameError", # string "CharType", "VarCharType", @@ -101,7 +108,16 @@ "TimestampType", "TimestampTzType", "IntervalType", + "INTERVAL_QUALIFIERS", + "InvalidIntervalQualifierError", + "IntervalQualifier", + "is_valid_interval_qualifier", + "validate_interval_qualifier", # json "JsonType", "JsonBType", + # xml + "XmlType", + # uuid + "UUIDType", ] diff --git a/src/rhosocial/activerecord/backend/expression/types/_base.py b/src/rhosocial/activerecord/backend/expression/types/_base.py index 6291d1875..a1289c1d6 100644 --- a/src/rhosocial/activerecord/backend/expression/types/_base.py +++ b/src/rhosocial/activerecord/backend/expression/types/_base.py @@ -6,7 +6,7 @@ import inspect import re from abc import ABC -from typing import TYPE_CHECKING, Optional, Set +from typing import TYPE_CHECKING, Optional, Tuple from ..bases import BaseExpression @@ -33,8 +33,46 @@ class DataType(BaseExpression, ABC): Backend-specific type configuration is carried by typed constructor fields on the backend's own type subclass, never by an untyped bag. + + Spellings + --------- + SQL and the supported backends spell one type several ways: ``INT`` is + SQL's own shorthand for ``INTEGER``, ``CHARACTER VARYING`` for ``VARCHAR``, + ``BYTEA`` is PostgreSQL's name for a ``BLOB``. Those are **spellings of one + type**, not separate types — a second class for ``INT`` would make + ``parse_type("INT")`` and ``parse_type("INTEGER")`` return different classes + for the same storage, and the schema differ would then need a table of + strings to tell them apart. So a type that has synonyms declares them as a + constant :attr:`SPELLINGS` list and takes a ``spelling`` argument naming + which one to render as. + + Two things follow from that division of labour: + + * **A type with no synonyms declares no list and takes no argument.** There + is nothing to choose between, so a single-spelling ``SPELLINGS`` and a + ``spelling`` parameter that can only hold one value are noise. + * **The expression only collects the parameter.** Which spelling a backend + actually renders is the formatter's business — ``format_data_type_`` + reads ``data_type.spelling`` and either honours it or reports that this + dialect does not support it. Keeping the vocabulary in a constant on the + class is what lets a formatter validate against it in one line. """ + #: The known spellings of this concept, for types that have more than one. + #: Empty on the abstract base and on every type with a single spelling. + SPELLINGS: Tuple[str, ...] = () + + #: Which member of :attr:`SPELLINGS` this instance renders as, or ``None`` + #: on the abstract base and on types that take no ``spelling`` argument. + #: + #: Deliberately **not** in :attr:`PARAMETERS`. A spelling is how this + #: instance is written, not what it is: the same column introspects as + #: ``character varying(30)`` whichever word created it, so counting it would + #: make every introspected type unequal to its own declaration and the + #: schema differ would invent a change. It does reach the rendered SQL, + #: which is where the difference is real and visible. + spelling: Optional[str] = None + @property def format_method(self) -> str: """The dialect formatting method that renders this expression.""" @@ -118,45 +156,73 @@ def __init__(self, dialect: Optional["SQLDialectBase"] = None): # ----- value-object semantics (ignore dialect for equality) ----- + #: The instance attributes that constitute this type's **identity**, in + #: comparison order. Equality, hashing and ``repr`` read it and nothing + #: else does. + #: + #: What belongs here is what makes two declarations of this type *different + #: columns* — ``length``, ``precision``, ``scale``, ``unsigned``, + #: ``values``, ``raw``, ``fields``, ``element_type``, ``dimensions``. + #: + #: What does **not** belong here is :attr:`spelling`. A spelling is a + #: rendering choice, not a property of the value: ``CREATE TABLE t (a + #: VARCHAR(30))`` and a catalog that reports ``character varying(30)`` are + #: the same column, and PostgreSQL reports the long form for every such + #: column regardless of how it was written. Counting the spelling would + #: make every introspected column compare unequal to the declaration that + #: produced it, and the schema differ would report a change that does not + #: exist. Two declarations that differ only in spelling are ``==``; the + #: difference is still visible in the rendered SQL, and ``spelling`` still + #: round-trips through :meth:`~...expression.bases.BaseExpression.get_params` + #: because serialization needs everything the constructor took. + #: + #: Declare parameters here rather than overriding anything. A subclass + #: inherits the base ``__eq__``/``__hash__`` and is done. + #: + #: This is deliberately **not** the serialization surface. ``get_params`` + #: is the single serialization path for all expressions and reads the + #: constructor signature; there is exactly one answer to "what does it take + #: to rebuild this", and it is not this one. + #: + #: **A dialect must honour or refuse every field named here — never drop + #: one.** A field in this tuple is part of the type's identity, so two + #: declarations differing only in it are *different columns*, and the + #: schema differ reports them as such. That makes exactly three honest + #: answers for a formatter, and only three: + #: + #: * **honour** it — flipping the field changes the rendered SQL, because + #: the field changes what the server will store; + #: * **refuse** it — flipping the field raises an error that names the + #: field and says why *this* backend cannot do it. Use this when the + #: backend has no such concept (``unsigned`` where the server has no + #: unsigned integers). The backend's own documentation belongs in the + #: refusal's message; + #: * **not belong here at all** — remove the field from this tuple, and + #: say in the class docstring why the concept does not have it (a + #: ``SERIAL`` column has no signedness: the auto-increment is a column + #: default, not a property of the storage). + #: + #: Silently dropping a declared field is the one thing that cannot be + #: allowed: the caller gets a column that is not the one they declared, and + #: the call reports success. Two columns differing only in that field also + #: render byte-identical SQL, so nothing downstream can notice. + PARAMETERS: Tuple[str, ...] = () + + def identity(self) -> tuple: + """The values of :attr:`PARAMETERS`, in declaration order. + + Derived, never overridden: an override here would be a second, + divergent answer to "what makes two of these different columns". + """ + return tuple(getattr(self, field) for field in self.PARAMETERS) + def __eq__(self, other: object) -> bool: if type(self) is not type(other): return False - return self._type_params() == other._type_params() + return self.identity() == other.identity() def __hash__(self) -> int: - return hash((type(self), self._type_params())) - - def _type_params(self) -> tuple: - """Return a tuple of the fields that define the logical type. - - Subclasses with extra parameters override this so the unified - base ``__eq__``/``__hash__`` compare their logical content; - they should **not** hand-write ``__eq__``/``__hash__``. - """ - return () - - # ----- equivalence ----- - - @classmethod - def synonyms(cls) -> Set[str]: - """Return class names considered equivalent to this type. - - Override in subclasses to declare cross-class equivalence - (e.g. ``IntType`` ↔ ``IntegerType``). Used by ``is_equivalent``. - """ - return set() - - def is_equivalent(self, other: DataType) -> bool: - """Structural synonym check. - - Returns ``True`` when two types are logically the same for schema - comparison purposes even when they are different Python classes - (e.g. ``SQLiteIntegerType`` vs ``SQLiteNumericType``). - """ - if type(self) is type(other): - return self == other - return type(self).__name__ in type(other).synonyms() or \ - type(other).__name__ in type(self).synonyms() + return hash((type(self), self.identity())) # ----- factory (delegated by dialect) ----- @@ -174,7 +240,7 @@ def parse_data_type_str(dialect: "SQLDialectBase", raw: str) -> "DataType": return CustomType(dialect, raw) def __repr__(self) -> str: - params = self._type_params() + params = self.identity() if params: return f"{type(self).__name__}{params}" return f"{type(self).__name__}()" diff --git a/src/rhosocial/activerecord/backend/expression/types/_defaults.py b/src/rhosocial/activerecord/backend/expression/types/_defaults.py new file mode 100644 index 000000000..cad499380 --- /dev/null +++ b/src/rhosocial/activerecord/backend/expression/types/_defaults.py @@ -0,0 +1,87 @@ +# src/rhosocial/activerecord/backend/expression/types/_defaults.py +"""What a server supplies for a parameter that a declaration leaves out. + +``length=None`` is not one thing, and that is the whole reason this module +exists. On PostgreSQL a bare ``VARCHAR`` **is** unbounded: the catalog reports +``atttypmod = -1``, hands back the same bare word, and ``None`` says "no limit +at all". On Oracle the same ``None`` means 4000 — not because the framework +chose 4000 but because Oracle cannot create an unsized ``VARCHAR2`` at all, so +the only ``VARCHAR2`` that can exist is a sized one. Firebird's 255, SQL +Server's 255 and Snowflake's 16777216 are three more answers. **No number is +right for more than one of them**, so a value written into the expression here +in core would be a claim about some other server. + +The knowledge belongs to whoever knows the server's rules, and the only object +here that knows them is the dialect the concept already carries. A dialect +therefore *declares* what it supplies, per concept and per parameter, through +:meth:`~...dialect.mixins.data_type.DataTypeMixin.type_parameter_defaults` — +and **declaring nothing is the majority answer, not a missing one.** A backend +is never asked for a number it does not have: the empty mapping *is* the +statement "this server supplies no width for this concept", which is what +PostgreSQL says, and it says it by having nothing to say. There is no list +anywhere of which concepts a backend is allowed to be silent about, because +silence is the default and a list of permissions to be silent would be a list +of permissions to be wrong. + +Why the lookup is keyed by the class's own ``name`` +-------------------------------------------------- + +``name`` is already the dispatch key: ``format_data_type_`` routes on it, +``supports_data_type_`` answers on it, and the supported-types mapping is +keyed by it. Keying the declaration the same way means no second identity for +a type to be filed under, and it decides two cases that a bare ``varchar`` key +would get wrong: + +* A backend type that is **the same concept through its own entry point** — + SQL Server's ``NVARCHAR``, Snowflake's ``snowflake_varchar`` — has its own + ``name`` and so declares its own key. Two names, one concept, two + declarations: neither has to guess what the other meant. +* A type that uses ``None`` to mean **unbounded** rather than **undeclared** — + ``NVARCHAR(MAX)``, which is unbounded because ``MAX`` lifted a cap — declares + nothing and keeps its ``None``. That is not an exemption from a rule; it is + the ordinary answer for a concept whose bare form has no width, and it falls + out of keying on ``name`` with nothing else required. +""" + +from __future__ import annotations + +from typing import Any, Dict, Optional, TYPE_CHECKING + +if TYPE_CHECKING: # pragma: no cover + from ...dialect import SQLDialectBase + + +def declared_parameter( + concept: str, + parameter: str, + dialect: Optional["SQLDialectBase"], +) -> Optional[Any]: + """The value *dialect* supplies for *concept* declared without *parameter*. + + ``None`` is the answer for a dialect that declares no default **and** for no + dialect at all. A type with no bound server has no width to resolve, and + that has to stay answerable rather than raising: ``VarCharType()`` is built + and compared all over the codebase with no dialect in hand, and an equality + that raised because a width could not be looked up would be a far worse + defect than the one this fixes. So nothing here can fail — the lookup finds + the hook or it does not, and both answers are a value. + + The hook is read through :func:`getattr` rather than demanded of every + dialect because it is deliberately **not** a member of + :class:`~...dialect.protocols.DataTypeSupport`: adding it there would make + every dialect implement it to keep passing ``isinstance``, which is exactly + the "every backend must supply a number" shape this design refuses. A + dialect that mixes in ``DataTypeMixin`` inherits the empty answer; one that + does not is treated as supplying nothing, which is what it says by not + having said otherwise. + """ + if dialect is None: + return None + type_parameter_defaults = getattr(dialect, "type_parameter_defaults", None) + if type_parameter_defaults is None: + return None + declared: Dict[str, Dict[str, Any]] = type_parameter_defaults() + return declared.get(concept, {}).get(parameter) + + +__all__ = ["declared_parameter"] diff --git a/src/rhosocial/activerecord/backend/expression/types/array.py b/src/rhosocial/activerecord/backend/expression/types/array.py index d0dea6492..1e9cb1aa5 100644 --- a/src/rhosocial/activerecord/backend/expression/types/array.py +++ b/src/rhosocial/activerecord/backend/expression/types/array.py @@ -16,23 +16,40 @@ class ArrayType(DataType): ``element_type`` holds the inner ``DataType`` instance (e.g. ``IntegerType()`` for ``INTEGER[]``), and ``dimensions`` records the array dimensionality - (1 for ``T[]``, 2 for ``T[][]``, etc.). - - .. note:: - - The ``element_type`` must be an instance of a concrete backend-specific - ``DataType`` (e.g. ``PostgresIntegerType``), **not** a generic base type - (e.g. ``IntegerType``). Using generic base types will cause a - ``TypeError`` when the dialect tries to render the element type, because - the dialect only registers formatters for its own concrete types. - - **Best practice**:: - - # Good — backend-specific element type - col_type = PostgresArrayType(PostgresIntegerType()) - - # Avoid — generic element type; will raise TypeError at render time - col_type = ArrayType(IntegerType()) + (1 for ``T[]``, 2 for ``T[][]``, etc.). Both are required — an array with + no element type is not a type, so a missing one is rejected at construction + rather than at render time. + + The element type may be any ``DataType``, core or backend-specific:: + + PostgresArrayType(PostgresIntegerType()) # INTEGER[] + PostgresArrayType(IntegerType()) # also INTEGER[] + + Nesting versus dimensionality + ---------------------------- + ``dimensions`` and an array-valued ``element_type`` are **different types + that render identically**. PostgreSQL's ``int[][]`` is genuinely + two-dimensional, so it is ``dimensions=2``; ClickHouse's + ``Array(Array(Int32))`` is an array whose element is an array, so it is + ``element_type=ArrayType(...)``. Both render ``INTEGER[][]``, so writing + the same PostgreSQL column the two ways produces two unequal instances of + one column. ``dimensions`` is the portable spelling — it is what the SQL + standard's multi-dimensional array is — so prefer it and keep nesting for + the backends that spell it that way. + + A dialect that forbids nesting must reject it while rendering; it cannot be + refused here, because whether ``Array(Array(T))`` is legal is a fact about + the backend, not about arrays. + + Not modelled + ------------ + PostgreSQL also accepts explicit extent and lower bounds — + ``int[3][3]``, ``[1:10]``, ``[1:]`` — and those are **silently dropped**: + ``ArrayType(IntegerType(), 2)`` renders ``INTEGER[][]``, not + ``INTEGER[3][3]``. A lower bound need not be 1 at all, so this is + information the type cannot currently carry. Nothing is gained by + pretending otherwise, but a caller who needs the bounds written must reach + for :class:`~...types.custom.CustomType`. """ name = "array" @@ -41,30 +58,39 @@ def __init__(self, dialect: Optional["SQLDialectBase"] = None, element_type: Optional[DataType] = None, dimensions: int = 1, ): super().__init__(dialect) + if element_type is None: + raise TypeError( + "ArrayType requires an element_type: T[] is a property of T, " + "and an array with no element type is not a type. For a type " + "the framework does not model, use CustomType(raw)." + ) + if not isinstance(element_type, DataType): + raise TypeError( + f"element_type must be a DataType instance, got " + f"{type(element_type).__name__}." + ) + if not isinstance(dimensions, int) or isinstance(dimensions, bool) \ + or dimensions < 1: + raise ValueError( + f"dimensions must be an int >= 1, got {dimensions!r}." + ) self.element_type = element_type self.dimensions = dimensions - def _type_params(self) -> tuple: - return (self.element_type, self.dimensions) - - def is_equivalent(self, other: DataType) -> bool: - if type(self) is not type(other): - return False - return (self.dimensions == other.dimensions - and self.element_type.is_equivalent(other.element_type)) + PARAMETERS = ("element_type", "dimensions",) def is_element_type_equivalent(self, other: DataType) -> bool: - """Check whether *other* represents the same element type. + """Whether *other* names the same element type, ignoring dimensions. - Unlike ``is_equivalent``: - * Dimensions are ignored. - * *other* does **not** need to be an ``ArrayType`` — passing a plain + * Dimensions are ignored — the question is "what does this array + store", not "how many axes does it have". + * *other* does **not** need to be an ``ArrayType``; passing a plain ``IntegerType()`` directly also works. - This is useful for schema comparison scenarios where the question is - "does this array column store the same element type as X" without - caring about dimensionality. + This is deliberately looser than ``==``: it answers a different + question ("does this array column store the same kind of thing as X") + rather than restating identity, which is what ``==`` already covers. """ if isinstance(other, ArrayType): - return self.element_type.is_equivalent(other.element_type) - return self.element_type.is_equivalent(other) + return self.element_type == other.element_type + return self.element_type == other diff --git a/src/rhosocial/activerecord/backend/expression/types/binary.py b/src/rhosocial/activerecord/backend/expression/types/binary.py index 7b94e2595..8f06ebbac 100644 --- a/src/rhosocial/activerecord/backend/expression/types/binary.py +++ b/src/rhosocial/activerecord/backend/expression/types/binary.py @@ -9,10 +9,19 @@ class BlobType(DataType): - """BLOB / BYTEA / VARBINARY — binary large object.""" + """BLOB / BYTEA — binary large object. + + ``BYTEA`` is PostgreSQL's name for the same unbounded byte storage. + """ name = "blob" + SPELLINGS = ("blob", "bytea") + + def __init__(self, dialect=None, *, spelling: str = "blob"): + super().__init__(dialect) + self.spelling = spelling + class BinaryType(DataType): """BINARY(n) — fixed-length byte string.""" @@ -26,9 +35,7 @@ def __init__(self, dialect=None, length: Optional[int] = None, super().__init__(dialect) self.length = length - def _type_params(self) -> tuple: - return (self.length,) - + PARAMETERS = ("length",) class VarBinaryType(DataType): """VARBINARY(n) — variable-length byte string.""" @@ -42,5 +49,4 @@ def __init__(self, dialect=None, length: Optional[int] = None, super().__init__(dialect) self.length = length - def _type_params(self) -> tuple: - return (self.length,) + PARAMETERS = ("length",) diff --git a/src/rhosocial/activerecord/backend/expression/types/boolean.py b/src/rhosocial/activerecord/backend/expression/types/boolean.py index 700a79ca2..71ca59b57 100644 --- a/src/rhosocial/activerecord/backend/expression/types/boolean.py +++ b/src/rhosocial/activerecord/backend/expression/types/boolean.py @@ -10,3 +10,10 @@ class BooleanType(DataType): """BOOLEAN / BOOL — truth value.""" name = "boolean" + + SPELLINGS = ("boolean", "bool") + + def __init__(self, dialect=None, *, spelling: str = "boolean"): + super().__init__(dialect) + self.spelling = spelling + diff --git a/src/rhosocial/activerecord/backend/expression/types/custom.py b/src/rhosocial/activerecord/backend/expression/types/custom.py index a45e9a52a..ceedbc5d2 100644 --- a/src/rhosocial/activerecord/backend/expression/types/custom.py +++ b/src/rhosocial/activerecord/backend/expression/types/custom.py @@ -8,10 +8,17 @@ class CustomType(DataType): - """Fallback for unrecognised or backend-specific type strings. + """A type name the framework has no class for. - Preserves the raw SQL type string verbatim so round-trips stay - lossless even when the framework does not know the type. + Kept because a backend may have types and extensions the framework does not + model, and refusing them would make those unreachable. The raw name is + validated rather than preserved verbatim: a type name lands in a position + that cannot take a bound parameter, so an unvalidated string here is an + injection. The grammar permits any identifier-shaped name, so a user-defined + type still passes without being registered. + + For a type used often enough to deserve a class, subclass DataType instead — + then the name is rendered through the dialect and cannot be wrong. """ name = "custom" @@ -21,7 +28,11 @@ class CustomType(DataType): def __init__(self, dialect=None, raw: str = "", ): super().__init__(dialect) - self.raw = raw + # Validated here rather than in each dialect's formatter: six of the + # ten backends rendered data_type.raw unchecked, and the four that + # refused did so only because they happened to lack the formatter. + from ..type_name import validate_type_name + + self.raw = validate_type_name(raw) - def _type_params(self) -> tuple: - return (self.raw,) + PARAMETERS = ("raw",) diff --git a/src/rhosocial/activerecord/backend/expression/types/datetime_.py b/src/rhosocial/activerecord/backend/expression/types/datetime_.py index 4ed87920f..967045a61 100644 --- a/src/rhosocial/activerecord/backend/expression/types/datetime_.py +++ b/src/rhosocial/activerecord/backend/expression/types/datetime_.py @@ -3,6 +3,7 @@ from __future__ import annotations +import re from typing import Optional from ._base import DataType @@ -26,9 +27,7 @@ def __init__(self, dialect=None, precision: Optional[int] = None, super().__init__(dialect) self.precision = precision - def _type_params(self) -> tuple: - return (self.precision,) - + PARAMETERS = ("precision",) class TimeTzType(DataType): """TIME[(p)] WITH TIME ZONE (SQL standard).""" @@ -42,9 +41,7 @@ def __init__(self, dialect=None, precision: Optional[int] = None, super().__init__(dialect) self.precision = precision - def _type_params(self) -> tuple: - return (self.precision,) - + PARAMETERS = ("precision",) class DateTimeType(DataType): """DATETIME — date + time (MySQL / SQLite).""" @@ -58,9 +55,7 @@ def __init__(self, dialect=None, precision: Optional[int] = None, super().__init__(dialect) self.precision = precision - def _type_params(self) -> tuple: - return (self.precision,) - + PARAMETERS = ("precision",) class TimestampType(DataType): """TIMESTAMP[(p)] [WITHOUT TIME ZONE] (SQL standard).""" @@ -74,9 +69,7 @@ def __init__(self, dialect=None, precision: Optional[int] = None, super().__init__(dialect) self.precision = precision - def _type_params(self) -> tuple: - return (self.precision,) - + PARAMETERS = ("precision",) class TimestampTzType(DataType): """TIMESTAMP[(p)] WITH TIME ZONE (SQL standard, PostgreSQL).""" @@ -90,21 +83,152 @@ def __init__(self, dialect=None, precision: Optional[int] = None, super().__init__(dialect) self.precision = precision - def _type_params(self) -> tuple: - return (self.precision,) + PARAMETERS = ("precision",) + +#: The six fields an interval qualifier can name, in ascending resolution. +#: SQL:2016 gives an interval a *resolution*: either one field, or one field +#: ``TO`` a later one. Enumerated rather than parsed because the set is +#: genuinely finite and small — six fields, thirteen combinations — which is the +#: whole argument for a closed list over a free string. +INTERVAL_FIELDS = ("YEAR", "MONTH", "DAY", "HOUR", "MINUTE", "SECOND") + +#: The thirteen qualifiers SQL:2016 defines: one field, or one field spanning to +#: a later one. ``YEAR TO DAY`` is deliberately absent — the combinations are +#: contiguous ranges, not arbitrary pairs, and enumerating them is what makes an +#: impossible qualifier an error rather than a silently-rendered type. +INTERVAL_QUALIFIERS = frozenset({ + "YEAR", "MONTH", "DAY", "HOUR", "MINUTE", "SECOND", + "YEAR TO MONTH", + "DAY TO HOUR", "DAY TO MINUTE", "DAY TO SECOND", + "HOUR TO MINUTE", "HOUR TO SECOND", "MINUTE TO SECOND", +}) + +#: A field with an optional leading precision, then an optional ``TO`` field +#: with its own. Oracle writes ``DAY(2) TO SECOND(6)`` and PostgreSQL accepts +#: the same, so the precision belongs to the grammar; the *shape* it forms is +#: then checked against :data:`INTERVAL_QUALIFIERS`, so ``YEAR(3) TO DAY(9)`` +#: is rejected on shape even though both fields parse. +_FIELD_ALTERNATION = "|".join(INTERVAL_FIELDS) +_INTERVAL_QUALIFIER_RE = re.compile( + rf"^(?P{_FIELD_ALTERNATION})" + r"(?:\(\s*\d+\s*\))?" + rf"(?:\s+TO\s+(?P{_FIELD_ALTERNATION})" + r"(?:\(\s*\d+\s*\))?)?$", + re.IGNORECASE | re.ASCII, +) + + +class InvalidIntervalQualifierError(ValueError): + """Raised when a string cannot be used as an SQL interval qualifier. + + A :class:`ValueError` for the same reason + :class:`~...type_name.InvalidTypeNameError` is: the qualifier is rejected + before any dialect is consulted, because the position it would occupy + (``INTERVAL `` in DDL) cannot hold a bound parameter on any + backend. + """ + + def __init__(self, value: object) -> None: + self.value = value + super().__init__( + f"{value!r} is not a SQL interval qualifier. A qualifier names the " + f"resolution of the interval and is one field, or one field TO a " + f"later one, each optionally with a leading precision: " + f"{', '.join(sorted(INTERVAL_QUALIFIERS))} " + f"(for example DAY(2) TO SECOND(6))." + ) + + +def is_valid_interval_qualifier(value: object) -> bool: + """Whether *value* is an interval qualifier this package will render.""" + try: + validate_interval_qualifier(value) + except InvalidIntervalQualifierError: + return False + return True + + +def validate_interval_qualifier(value: object) -> str: + """Return *value* when it is a usable interval qualifier, else raise. + + Returns the value unchanged (whitespace-stripped) so this can wrap a + constructor argument, exactly as + :func:`~...type_name.validate_type_name` does. + + Raises: + InvalidIntervalQualifierError: If the qualifier is not one of the + thirteen SQL:2016 qualifiers, with or without a leading precision. + """ + if isinstance(value, str): + candidate = value.strip() + match = _INTERVAL_QUALIFIER_RE.match(candidate) + if match is not None: + shape = match.group("start").upper() + if match.group("end") is not None: + shape = f"{shape} TO {match.group('end').upper()}" + if shape in INTERVAL_QUALIFIERS: + return candidate + raise InvalidIntervalQualifierError(value) + + +class IntervalQualifier(str): + """A validated SQL interval qualifier. + + A ``str`` subclass, deliberately, and the reason is rendering. Three + dialects interpolate ``fields`` straight into ``INTERVAL `` — + Oracle (which also upper-cases it), PostgreSQL and the dummy dialect — so + changing the *value type* from ``str`` to an ``enum.Enum`` would rewrite + their output to ``INTERVAL IntervalField.YEAR`` and break every backend's + DDL. Subclassing ``str`` keeps this additive: ``f"INTERVAL {q}"``, + ``q.upper()``, ``q == "YEAR TO MONTH"``, ``json.dumps(q)`` and ``repr(q)`` + all behave exactly as they did, and equality, hashing and the ``PARAMETERS`` + identity tuple are untouched. + + What it buys is that the attribute can only ever *hold* a member of the + closed vocabulary — an unchecked string in a DDL position is an injection, + and a closed set is the same defence ``spelling`` uses for the same reason. + """ + + __slots__ = () + + def __new__(cls, value: object) -> "IntervalQualifier": + return super().__new__(cls, validate_interval_qualifier(value)) class IntervalType(DataType): - """INTERVAL — time span (PostgreSQL / SQL standard).""" + """INTERVAL [qualifier] — a time span at a declared resolution. + + ``INTERVAL`` on its own is a span with no stated resolution; the qualifier + is what says which fields it counts. It is a real part of the type rather + than a decoration, because Oracle writes it: an unqualified ``IntervalType`` + renders ``INTERVAL DAY(2) TO SECOND(6)``, the qualifier Oracle means by a + bare ``INTERVAL``, so that what is written is what the catalog reports back. + + The qualifier is drawn from :data:`INTERVAL_QUALIFIERS` — the thirteen SQL + standard qualifiers — and validated by :class:`IntervalQualifier`, so an + unknown qualifier raises :class:`InvalidIntervalQualifierError` naming it + rather than becoming a string interpolated into DDL. Which qualifiers a + backend *renders* is the backend's business; that the set is closed is + core's. + + Renderers and ignorers, as of this change: Oracle, PostgreSQL and the dummy + dialect interpolate ``fields``; SQLite renders interval as ``NUMERIC`` + because SQLite has no interval type at all and stores the value as a + number, so its qualifier has nowhere to live; the remaining backends do not + render interval at all and name a substitute through + ``suggested_data_types()``. + """ name = "interval" - fields: Optional[str] = None # e.g. 'YEAR', 'MONTH', 'DAY TO SECOND' + fields: Optional[IntervalQualifier] = None def __init__(self, dialect=None, fields: Optional[str] = None, ): super().__init__(dialect) - self.fields = fields + # Validated here rather than in each rendering dialect: three formatters + # interpolated this unchecked, and a per-formatter check is a + # per-formatter bug waiting to happen. + self.fields = None if fields is None else IntervalQualifier(fields) - def _type_params(self) -> tuple: - return (self.fields,) + PARAMETERS = ("fields",) diff --git a/src/rhosocial/activerecord/backend/expression/types/enum_.py b/src/rhosocial/activerecord/backend/expression/types/enum_.py index f4e8655df..193d78f98 100644 --- a/src/rhosocial/activerecord/backend/expression/types/enum_.py +++ b/src/rhosocial/activerecord/backend/expression/types/enum_.py @@ -24,5 +24,4 @@ def __init__(self, dialect=None, values: Optional[List[str]] = None, raise ValueError("EnumType requires at least one value") self.values = tuple(values) - def _type_params(self) -> tuple: - return (self.values,) + PARAMETERS = ("values",) diff --git a/src/rhosocial/activerecord/backend/expression/types/integer.py b/src/rhosocial/activerecord/backend/expression/types/integer.py index 08a6c00e6..b38e71bd2 100644 --- a/src/rhosocial/activerecord/backend/expression/types/integer.py +++ b/src/rhosocial/activerecord/backend/expression/types/integer.py @@ -1,5 +1,16 @@ # src/rhosocial/activerecord/backend/expression/types/integer.py -"""Integer SQL type family.""" +"""Integer SQL type family. + +``INT`` is SQL's own shorthand for ``INTEGER``, and MySQL spells the narrower +widths ``INT1`` / ``INT2`` / ``INT8``. Those are spellings of one width, so each +width is one class with a :attr:`SPELLINGS` list — not two classes. + +``UNSIGNED`` is a different thing: SQL:2003 had it as an attribute and SQL:2011 +removed it (feature T211), but MySQL, MariaDB and ClickHouse all still keep it, +and it changes the representable range, so it is a different **type** — a field +rather than a class, because width is already this family's class axis and a +linear chain cannot hold a (width x signedness) grid. +""" from __future__ import annotations @@ -11,34 +22,98 @@ class TinyIntType(DataType): name = "tinyint" + SPELLINGS = ("tinyint", "int1") + + unsigned: bool = False + + def __init__(self, dialect=None, *, unsigned: bool = False, + spelling: str = "tinyint"): + super().__init__(dialect) + if not isinstance(unsigned, bool): + raise TypeError( + f"unsigned must be a bool, got {type(unsigned).__name__}; it " + f"becomes a type modifier in the rendered DDL." + ) + self.unsigned = unsigned + self.spelling = spelling + + PARAMETERS = ("unsigned",) class SmallIntType(DataType): """SMALLINT / INT2 (16-bit).""" name = "smallint" + SPELLINGS = ("smallint", "int2") -class IntType(DataType): - """INT (shorthand for INTEGER, SQL standard).""" - - name = "int" + unsigned: bool = False - @classmethod - def synonyms(cls) -> set[str]: - return {"IntegerType"} + def __init__(self, dialect=None, *, unsigned: bool = False, + spelling: str = "smallint"): + super().__init__(dialect) + if not isinstance(unsigned, bool): + raise TypeError( + f"unsigned must be a bool, got {type(unsigned).__name__}; it " + f"becomes a type modifier in the rendered DDL." + ) + self.unsigned = unsigned + self.spelling = spelling + PARAMETERS = ("unsigned",) class IntegerType(DataType): - """INTEGER / INT4 (32-bit).""" + """INTEGER / INT (32-bit). + + ``int4`` is in the closed list because it is a documented synonym on more + than one backend -- MySQL and MariaDB each give it a page of its own -- and + that list is the **union** across dialects, not one dialect's vocabulary. + Its three siblings each carry their own ``INTn`` (``int1``, ``int2``, + ``int8``); leaving this one out read as an oversight rather than a decision, + because nothing had recorded it as one. + + Being in the list does not oblige any dialect to **write** it. PostgreSQL + uses ``int4`` as an internal catalog name only -- it is not in the DDL + grammar -- so that backend refuses the spelling explicitly rather than + rendering a word the server's own ``CREATE TABLE`` does not accept. + """ name = "integer" - @classmethod - def synonyms(cls) -> set[str]: - return {"IntType"} + SPELLINGS = ("integer", "int", "int4") + + unsigned: bool = False + def __init__(self, dialect=None, *, unsigned: bool = False, + spelling: str = "integer"): + super().__init__(dialect) + if not isinstance(unsigned, bool): + raise TypeError( + f"unsigned must be a bool, got {type(unsigned).__name__}; it " + f"becomes a type modifier in the rendered DDL." + ) + self.unsigned = unsigned + self.spelling = spelling + + PARAMETERS = ("unsigned",) class BigIntType(DataType): """BIGINT / INT8 (64-bit).""" name = "bigint" + + SPELLINGS = ("bigint", "int8") + + unsigned: bool = False + + def __init__(self, dialect=None, *, unsigned: bool = False, + spelling: str = "bigint"): + super().__init__(dialect) + if not isinstance(unsigned, bool): + raise TypeError( + f"unsigned must be a bool, got {type(unsigned).__name__}; it " + f"becomes a type modifier in the rendered DDL." + ) + self.unsigned = unsigned + self.spelling = spelling + + PARAMETERS = ("unsigned",) diff --git a/src/rhosocial/activerecord/backend/expression/types/numeric.py b/src/rhosocial/activerecord/backend/expression/types/numeric.py index d68657637..74adea767 100644 --- a/src/rhosocial/activerecord/backend/expression/types/numeric.py +++ b/src/rhosocial/activerecord/backend/expression/types/numeric.py @@ -1,11 +1,32 @@ # src/rhosocial/activerecord/backend/expression/types/numeric.py -"""Floating-point and exact numeric SQL types.""" +"""Floating-point and exact numeric SQL types. + +``UNSIGNED`` reaches these three concepts exactly as it reaches the four integer +widths, and for exactly the same reason: it is a **field**, not a class. + +MySQL's manual says so of the numeric types in the same breath as the integers -- +"Floating point and fixed-point types also can be ``UNSIGNED``" -- so +``DECIMAL(10,2) UNSIGNED`` and ``DECIMAL(10,2)`` are two different columns with +different ranges, on MySQL and on MariaDB alike. A concept that cannot hold the +flag cannot distinguish them, and the schema differ then reports no change for a +change the database happily makes. Measured on all fifteen wired MariaDB servers, +``decimal(10,2) unsigned zerofill`` introspected as ``DecimalType(10, 2)``: the +signedness was simply gone. + +Width is the class axis here just as it is in ``integer.py`` -- a ``FLOAT(p)`` +exists for every ``p`` -- and a linear chain cannot hold a (width x signedness) +grid, so ``unsigned: bool`` is a field on each of the three concepts that have +one. Which dialect honours it and which refuses it is that vendor's own +question, answered from that vendor's own documentation and recorded in that +dialect's ``format_data_type_*``. +""" from __future__ import annotations from typing import Optional from ._base import DataType +from ._defaults import declared_parameter class FloatType(DataType): @@ -13,43 +34,218 @@ class FloatType(DataType): name = "float" - precision: Optional[int] = None + unsigned: bool = False def __init__(self, dialect=None, precision: Optional[int] = None, - ): + *, unsigned: bool = False): super().__init__(dialect) - self.precision = precision - - def _type_params(self) -> tuple: - return (self.precision,) - + self._precision = precision + if not isinstance(unsigned, bool): + raise TypeError( + f"unsigned must be a bool, got {type(unsigned).__name__}; it " + f"becomes a type modifier in the rendered DDL." + ) + self.unsigned = unsigned + + @property + def precision(self) -> Optional[int]: + """The declared binary precision, or the one this server supplies for none. + + Oracle is the case this exists for: a bare ``FLOAT`` there **is** + ``FLOAT(126)``. The ANSI conversion table's note 2 says so in the + vendor's own words — "The default precision for this data type is 126 + binary, or 38 decimal" — and the catalog agrees rather than merely + documenting it: ``CREATE TABLE t (c FLOAT)`` reports + ``DATA_TYPE = 'FLOAT'`` and ``DATA_PRECISION = 126``, the same two + values a ``FLOAT(126)`` column reports, so a declaration that named no + precision and a column of 126 are one column and the differ has to be + able to say so. A dialect with nothing to declare keeps ``None``, + which is the honest answer for a server whose bare form names no + particular width — PostgreSQL's ``FLOAT`` among them, and no dialect at + all as well. + + Resolving at read time rather than in ``__init__`` is what makes the + deferred binding work: ``FloatType()`` bound to a server afterwards + resolves the same way as ``FloatType(dialect)`` built with one. The cost + is stated rather than hidden — this type's identity is settled only once + a dialect is bound, so bind one before using it as a dictionary key or a + set member, exactly as rendering already requires. + """ + return self._precision if self._precision is not None else declared_parameter( + self.name, "precision", self._dialect + ) + + @precision.setter + def precision(self, value: Optional[int]) -> None: + self._precision = value + + # ``unsigned`` is appended, never inserted ahead of ``precision``: the order + # of this tuple is what ``identity()`` reads, so it is what ``==`` and + # ``__hash__`` read, and reordering it would change every hash of every + # instance of this class. + PARAMETERS = ("precision", "unsigned") class RealType(DataType): - """REAL — single-precision (4 bytes / 24-bit mantissa).""" + + """ + REAL — single-precision (4 bytes / 24-bit mantissa). + + ``unsigned`` is here because the vendor documents it on this word: MySQL's + numeric-type syntax lists ``REAL[(M,D)] [UNSIGNED] [ZEROFILL]`` as a synonym + for ``DOUBLE``, and its attributes page extends the ``UNSIGNED`` deprecation + to that word explicitly — "deprecated for columns of type ``FLOAT``, + ``DOUBLE``, and ``DECIMAL`` (**and any synonyms**)". + https://dev.mysql.com/doc/refman/9.7/en/numeric-type-syntax.html + + **The server reports the storage, not the word.** Measured on all seven wired + servers, 5.6.51 through 26.7.0, a ``REAL UNSIGNED`` column is reported by + ``information_schema`` and ``SHOW COLUMNS`` as ``double unsigned`` — MySQL + resolves the synonym in the storage layer. So a live ``REAL UNSIGNED`` column + introspects as ``DoubleType(unsigned=True)`` and cannot round-trip against a + declared ``RealType``. That is MySQL's documented synonym behaviour, it + predates this field, and it applies equally to a signed ``REAL``: it is one + more instance of the fact recorded below, that on this backend the concept + and its storage are not the same thing. + + Note also that ``REAL`` is a synonym for ``DOUBLE`` unless the + ``REAL_AS_FLOAT`` SQL mode is enabled, in which case it is a synonym for + ``FLOAT``. Which is why this class stays separate from :class:`DoubleType` + instead of becoming one of its spellings. + + Because of that mode-dependence MySQL and MariaDB do not render this + concept at all: the catalog reports the resolved storage (``double``, or + ``float`` under the mode) and never the word, so a declared ``RealType`` + could not round-trip. Both dialects substitute :class:`DoubleType` and say + why in their ``substitute_advice``. + + """ name = "real" + unsigned: bool = False + + def __init__(self, dialect=None, *, unsigned: bool = False): + super().__init__(dialect) + if not isinstance(unsigned, bool): + raise TypeError( + f"unsigned must be a bool, got {type(unsigned).__name__}; it " + f"becomes a type modifier in the rendered DDL." + ) + self.unsigned = unsigned + + PARAMETERS = ("unsigned",) + class DoubleType(DataType): - """DOUBLE PRECISION — double-precision (8 bytes / 53-bit mantissa).""" + """DOUBLE PRECISION — double-precision (8 bytes / 53-bit mantissa). + + ``DOUBLE PRECISION`` is the standard's name; ``DOUBLE`` is the common + abbreviation. + """ name = "double" + SPELLINGS = ("double", "double precision") + + unsigned: bool = False + + def __init__(self, dialect=None, *, unsigned: bool = False, + spelling: str = "double"): + super().__init__(dialect) + if not isinstance(unsigned, bool): + raise TypeError( + f"unsigned must be a bool, got {type(unsigned).__name__}; it " + f"becomes a type modifier in the rendered DDL." + ) + self.unsigned = unsigned + self.spelling = spelling + + PARAMETERS = ("unsigned",) + class DecimalType(DataType): - """DECIMAL[(p[,s])] / NUMERIC[(p[,s])] — exact fixed-point.""" + """DECIMAL[(p[,s])] / NUMERIC[(p[,s])] — exact fixed-point. + + SQL:2016 makes ``DECIMAL`` a shorthand for ``NUMERIC``, and ``DEC`` is the + common abbreviation. + """ name = "decimal" - precision: Optional[int] = None - scale: Optional[int] = None + SPELLINGS = ("decimal", "numeric", "dec") + + unsigned: bool = False def __init__(self, dialect=None, precision: Optional[int] = None, scale: Optional[int] = None, - ): + *, unsigned: bool = False, spelling: str = "decimal"): super().__init__(dialect) - self.precision = precision - self.scale = scale - - def _type_params(self) -> tuple: - return (self.precision, self.scale) + self._precision = precision + self._scale = scale + if not isinstance(unsigned, bool): + raise TypeError( + f"unsigned must be a bool, got {type(unsigned).__name__}; it " + f"becomes a type modifier in the rendered DDL." + ) + self.unsigned = unsigned + self.spelling = spelling + + @property + def precision(self) -> Optional[int]: + """The declared precision, or the precision this server supplies for none. + + Snowflake is the case this exists for: a bare ``NUMBER`` there **is** + ``NUMBER(38, 0)`` — "By default, precision is 38, and scale is 0; that + is, NUMBER(38, 0)", in the manual's own words — and ``DESC TABLE`` + renders the two spellings identically, so a declaration that named no + precision and a column of 38 are one column and the differ has to be + able to say so. A dialect with nothing to declare keeps ``None``, + which is what PostgreSQL says about its own exact numerics by having + nothing to say, and it is also the answer with no dialect bound at all. + + Resolving at read time rather than in ``__init__`` is what makes the + deferred binding work: ``DecimalType()`` bound to a server afterwards + resolves the same way as ``DecimalType(dialect)`` built with one. The + cost is stated rather than hidden — this type's identity is settled only + once a dialect is bound, so bind one before using it as a dictionary key + or a set member, exactly as rendering already requires. + """ + return self._precision if self._precision is not None else declared_parameter( + self.name, "precision", self._dialect + ) + + @precision.setter + def precision(self, value: Optional[int]) -> None: + self._precision = value + + @property + def scale(self) -> Optional[int]: + """The declared scale, or the scale this server supplies for none. + + ``scale`` resolves independently of ``precision`` because the question + is asked and answered per parameter: on Snowflake a declaration that + names a precision and no scale is still stored with a scale of 0 + (``NUMBER(10)`` is ``NUMBER(10, 0)``), and one that names neither + carries both halves of the documented pair. Writing this as "only fill + the scale in when the precision is absent too" would leave the + precision-only declaration comparing unequal to the column it produced + — the same defect one parameter over — and ``type_parameter_defaults`` + is keyed per parameter for exactly this reason. + + A dialect that declares nothing keeps ``None``, and so does an unbound + instance; both are the honest answer when no server has said what its + bare form means. Like :attr:`precision`, this resolves at read time so + a dialect bound after construction counts, and identity is settled only + once a dialect is bound. + """ + return self._scale if self._scale is not None else declared_parameter( + self.name, "scale", self._dialect + ) + + @scale.setter + def scale(self, value: Optional[int]) -> None: + self._scale = value + + # ``unsigned`` is appended, never inserted ahead of ``precision`` / ``scale``: + # see the note on ``FloatType.PARAMETERS``. + PARAMETERS = ("precision", "scale", "unsigned") diff --git a/src/rhosocial/activerecord/backend/expression/types/string.py b/src/rhosocial/activerecord/backend/expression/types/string.py index f8a996f19..e9a9f6a51 100644 --- a/src/rhosocial/activerecord/backend/expression/types/string.py +++ b/src/rhosocial/activerecord/backend/expression/types/string.py @@ -1,46 +1,148 @@ # src/rhosocial/activerecord/backend/expression/types/string.py -"""Character / string SQL types.""" +"""Character / string SQL types. + +``CHARACTER`` and ``CHARACTER VARYING`` are SQL's own long forms of ``CHAR`` +and ``VARCHAR``. National-character-set spellings (``NCHAR``, +``NVARCHAR``) are deliberately absent: the framework treats a character set as a +*field* rather than a type — the position ``MariaDBEnumType.charset`` already +takes — so they are not a separate spelling of the same concept here. + +Widths +------ +``CharType`` and ``VarCharType`` are the only core concepts that take a bare +width, and their ``length`` is **resolved rather than stored**: a declaration +that names no width carries the width this server supplies for one, or no width +at all when this server has no default to supply. See +:mod:`~...expression.types._defaults` for why that value cannot be written down +here, and :attr:`VarCharType.length` for what resolution means for identity. + +``BinaryType`` and ``VarBinaryType`` take a width too and deliberately do **not** +do this. A backend that has no width-bearing byte string renders the unbounded +one — Firebird and core's dummy dialect both answer a bare ``BinaryType`` with +``BLOB``, and SQL Server answers a bare ``VarBinaryType`` with ``VARBINARY(MAX)`` +— so there is no server here whose bare form names a particular width, and no +asymmetry for a resolution to close. +""" from __future__ import annotations from typing import Optional from ._base import DataType +from ._defaults import declared_parameter class CharType(DataType): - """CHAR[(n)] / CHARACTER[(n)] — fixed-length string.""" + """CHAR[(n)] / CHARACTER[(n)] — fixed-length string. + + A shorter value is padded to ``n`` rather than stored as written, which is + what makes this concept fixed-length where :class:`VarCharType` is not. + """ name = "char" - length: Optional[int] = None + SPELLINGS = ("char", "character") def __init__(self, dialect=None, length: Optional[int] = None, - ): + *, spelling: str = "char"): super().__init__(dialect) - self.length = length - - def _type_params(self) -> tuple: - return (self.length,) - + self._length = length + self.spelling = spelling + + @property + def length(self) -> Optional[int]: + """The declared width, or the width this server supplies for none declared. + + ``None`` in, two different things out, and which one is decided by the + bound dialect: on PostgreSQL it stays ``None``, because ``CHAR`` there + really is one character long and the catalog reports ``atttypmod = -1``, + so an absent width means *no* width. On a server that supplies a width + for the bare form it becomes that width, because an absent width there + is not stored — the server writes out its own default and reports it back, + so a declaration of nothing and a column of that width are the same + column, and the differ has to be able to say so. + + Resolving at read time rather than in ``__init__`` is what makes the + deferred binding work: ``CharType()`` bound to a server afterwards + resolves the same way as ``CharType(dialect)`` built with one. The cost + is stated rather than hidden — this type's identity is settled only once + a dialect is bound, so bind one before using it as a dictionary key or a + set member, exactly as rendering already requires. + """ + return self._length if self._length is not None else declared_parameter( + self.name, "length", self._dialect + ) + + @length.setter + def length(self, value: Optional[int]) -> None: + self._length = value + + PARAMETERS = ("length",) class VarCharType(DataType): - """VARCHAR(n) — variable-length string.""" + """VARCHAR(n) / CHARACTER VARYING(n) — variable-length string. + + PostgreSQL reports ``character varying`` from the catalog, which is why the + long form is a spelling here rather than a class of its own. + """ name = "varchar" - length: Optional[int] = None + SPELLINGS = ("varchar", "character varying") def __init__(self, dialect=None, length: Optional[int] = None, - ): + *, spelling: str = "varchar"): super().__init__(dialect) - self.length = length - - def _type_params(self) -> tuple: - return (self.length,) - + self._length = length + self.spelling = spelling + + @property + def length(self) -> Optional[int]: + """The declared width, or the width this server supplies for none declared. + + This is the case the whole ``None`` question turns on, so it is worth + saying what each server means by a bare ``VARCHAR`` here, measured rather + than assumed: + + * **PostgreSQL — stays ``None``, and that is the honest answer.** A bare + ``character varying`` comes back from the catalog with ``atttypmod = + -1``: the column is unbounded, the word names no width because there is + none, and normalising it to a number would make this claim the column + is bounded when it is not. + * **Firebird, SQL Server — the bare form means a specific width**, which + the server stores and reports back, so ``None`` in the declaration + becomes that width here. + * **Snowflake — the bare form means 16777216**, per its own reference. + + So ``None`` is polymorphic across servers and no value written down here + would be right for more than one of them. The resolution is therefore + read off the bound dialect, and a dialect that supplies nothing keeps + ``None`` — which is what PostgreSQL does, by having nothing to declare. + + As with :attr:`CharType.length`, this resolves at read time so a dialect + bound after construction counts, and the consequence is that identity is + settled only once a dialect is bound. + """ + return self._length if self._length is not None else declared_parameter( + self.name, "length", self._dialect + ) + + @length.setter + def length(self, value: Optional[int]) -> None: + self._length = value + + PARAMETERS = ("length",) class TextType(DataType): - """TEXT / CLOB / LONGVARCHAR — unbounded string.""" + """TEXT / CLOB — unbounded string. + + PostgreSQL treats ``clob`` as an alias for ``text``. + """ name = "text" + + SPELLINGS = ("text", "clob") + + def __init__(self, dialect=None, *, spelling: str = "text"): + super().__init__(dialect) + self.spelling = spelling diff --git a/src/rhosocial/activerecord/backend/expression/types/uuid_.py b/src/rhosocial/activerecord/backend/expression/types/uuid_.py index 0022eac9d..408ccbc44 100644 --- a/src/rhosocial/activerecord/backend/expression/types/uuid_.py +++ b/src/rhosocial/activerecord/backend/expression/types/uuid_.py @@ -7,12 +7,102 @@ class UUIDType(DataType): - """UUID — universally unique identifier (RFC 4122). + """UUID — universally unique identifier (RFC 9562, ISO/IEC 9834-8). - A *semantic* type: each backend renders it to its native / most compact - storage, e.g. PostgreSQL ``UUID``, MySQL/MariaDB ``BINARY(16)``, - SQL Server ``uniqueidentifier``, Oracle ``RAW(16)``, Firebird - ``CHAR(16) CHARACTER SET OCTETS``, SQLite ``TEXT``. + A *semantic* type: the value means "a UUID" on every backend, while the + storage is each backend's own choice. Backends that can render this type + directly implement ``format_data_type_uuid``; the rest declare a + substitute through ``suggested_data_types()``. + + Storage by backend, for reference when reading a DDL diff. Where a row + names a spelling the dialect does not actually write, that is said in + the row, because the point of the table is to help you read the DDL this + framework *emits*, not to describe an abstract backend. + + ============== ========================== + Backend Storage + ============== ========================== + PostgreSQL ``UUID`` — the native ``uuid`` type, for UUIDs "as + defined by RFC 9562, ISO/IEC 9834-8:2005, and related + standards" + Oracle **no ``UUID`` data type in any released version, 26ai + included** — 23ai added the ``UUID()`` *function*, which + "returns a version 4 variant 1 UUID as a ``RAW(16)`` value". + The substitute is ``RAW``, and ``RAW(size)`` is "raw binary + data of length *size* bytes", so the dialect gives + ``OracleRawType`` a default length of 16 — the width a + UUID actually needs, and the width ``UUID()`` returns + SQL Server ``UNIQUEIDENTIFIER`` — "a 16-byte GUID". Declared as the + substitute, so T-SQL never sees the core ``uuid`` name + MySQL no UUID type. MySQL spells the bare byte string + ``BINARY`` as ``BINARY(1)`` ("if omitted, *M* defaults + to 1"), which cannot hold 16 bytes; MySQL's own binary + UUID is 16 bytes — ``UUID_TO_BIN()`` returns "a + ``VARBINARY(16)`` value" + MariaDB native ``UUID``: "``UUID`` is available from MariaDB + 10.7", for "the storage of 128-bit UUID data". The + dialect renders ``UUID`` and version-gates it; + ``BINARY(16)`` is only the pre-10.7 emulation + SQLite no native type — five storage classes, five affinities, + no UUID among them; a UUID gets TEXT affinity + Snowflake **native ``UUID``, added in server release 10.2** + (Jan 26-30, 2026) — "stores universally unique identifiers + (UUIDs)", and "a UUID is a 128-bit binary value". Syntax is + `` UUID`` with no parameters. Our dialect + renders ``UUID`` (via ``SnowflakeUuidType``) and + version-gates it at 10.2; below that it still substitutes + ``VARCHAR``. Reading is the same either way — "Snowflake + drivers treat UUID values as text strings", in the 36-char + 8-4-4-4-12 form + BigQuery no UUID type — its type list is closed and documented, + and ``STRING`` is the only character type in it + ClickHouse ``UUID`` (via its own ``ClickHouseUUIDType``) — "a + 16-byte value used to identify records" + Firebird ``CHAR(16) CHARACTER SET OCTETS``, which is exactly the + type Firebird spells ``BINARY(16)``; all three of its + UUID functions return ``BINARY(16)`` + ============== ========================== + + This is a *documentation* table, not a contract: a backend whose entry is + missing has not implemented the type, and one whose row disagrees with its + ``suggested_data_types()`` has a defect worth reporting. A row that + contradicts the vendor's own documentation is a defect *here* — that is the + rule this table is checked against, row by row. + + Vendor documentation, checked row by row: + + * PostgreSQL — + https://www.postgresql.org/docs/current/datatype-uuid.html + * Oracle — Built-In Data Type Summary and the datatype grammar, which + list no ``UUID``: + https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/Data-Types.html + The ``UUID()`` function reference: + https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/uuid.html + * SQL Server — + https://learn.microsoft.com/en-us/sql/t-sql/data-types/uniqueidentifier-transact-sql + * MySQL — the closed chapter list, the ``BINARY[(M)]`` syntax rule and + ``UUID_TO_BIN()``: + https://dev.mysql.com/doc/refman/8.4/en/data-types.html + https://dev.mysql.com/doc/refman/8.4/en/string-type-syntax.html + https://dev.mysql.com/doc/refman/8.4/en/miscellaneous-functions.html + * MariaDB — + https://mariadb.com/docs/server/reference/data-types/string-data-types/uuid-data-type + * SQLite — https://www.sqlite.org/datatype3.html + * Snowflake — the type page and the release that introduced it: + https://docs.snowflake.com/en/sql-reference/data-types-uuid + https://docs.snowflake.com/en/release-notes/2026/10_2 + * BigQuery — + https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types + * ClickHouse — + https://clickhouse.com/docs/en/sql-reference/data-types/uuid + * Firebird — + https://www.firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-functions-uuid.html + https://www.firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-datatypes-chartypes.html + + Generating a UUID is a separate concern and lives in the expression layer + (:mod:`...expression.uuid`) — see ``UUIDSupport``. Storage says nothing + about whether the database can produce a value: Oracle and Firebird both + ship UUID *functions* and no UUID *type*. """ - name = "uuid" \ No newline at end of file + name = "uuid" diff --git a/src/rhosocial/activerecord/backend/expression/types/xml_.py b/src/rhosocial/activerecord/backend/expression/types/xml_.py new file mode 100644 index 000000000..8be309bd7 --- /dev/null +++ b/src/rhosocial/activerecord/backend/expression/types/xml_.py @@ -0,0 +1,113 @@ +# src/rhosocial/activerecord/backend/expression/types/xml_.py +"""XML — an XML document.""" + +from __future__ import annotations + +from ._base import DataType + + +class XmlType(DataType): + """XML — an XML document (SQL:2003 ``xml`` type). + + A *semantic* type: the value means "an XML document" on every backend that + has one, while the storage is each backend's own choice. Backends that can + render it implement ``format_data_type_xml``; the rest declare a substitute + through ``suggested_data_types()`` — for most of them ``TextType``, which + is not a compromise but an accurate description of what they store. + + Not to be confused with :class:`~...types.json_.JsonType`. Both are + semi-structured, but the operations differ (XPath plus schema validation + against JSON path plus none), the standards differ (SQL/XML against + SQL/JSON), and the backends that have one do not reliably have the other. + + Deliberately **not** a subclass of :class:`~...types.string.TextType`, + even though several backends store XML as text: SQL Server's ``xml`` is + stored "as large binary objects (BLOBs)" and Oracle's ``XMLType`` is an + Oracle-supplied type whose storage model — ``CLOB``, binary XML, or + object-relational — is chosen per column, so "it is text" is false where it + matters most. See :class:`~...types.uuid_.UUIDType` for the same argument + applied to UUID. + + Carries no parameters: an associated XML Schema is a column or domain + attribute, not part of the type's identity. + + Storage by backend, for reference when reading a DDL diff: + + ============== ========================== + Backend Storage + ============== ========================== + PostgreSQL ``XML`` — native; it checks input for well-formedness, + but it "does not validate input values against a + document type declaration (DTD)" and there is "no + built-in support for validating against other XML schema + languages such as XML Schema" + Oracle ``XMLType`` — an Oracle-supplied type: "you can choose to + store the XML data in a ``CLOB`` column, as binary XML + (stored internally as a ``BLOB``), or object + relationally", and "queries and DML on ``XMLType`` + columns operate the same regardless of the storage + mechanism" + SQL Server ``xml`` — "stored in xml type columns as large binary + objects (BLOBs)"; what that representation preserves is + the XML InfoSet + MySQL ``TEXT`` — no XML type; the chapter's list of categories + is numeric, date and time, string, spatial and JSON + MariaDB **native ``XMLTYPE``, available from 12.3** — "basic XML + storage capabilities only, without validation", capped at + 4GB like ``LONGBLOB``, and "length cannot be specified". + The dialect renders ``XMLTYPE`` from 12.3 (the first GA of + that series was 12.3.2) and substitutes ``TEXT`` below it. + Note the bare word ``XML`` is not MariaDB's keyword on any + version + SQLite ``TEXT`` — no native type; XML gets TEXT affinity + Snowflake ``OBJECT`` (via ``suggested_data_types``) — ``PARSE_XML()`` + returns ``OBJECT``, which is Snowflake's name for a + ``VARIANT``; there is no XML type + BigQuery ``STRING`` — no XML type; its type list is closed and + documented, and ``STRING`` is the only character type + in it + ClickHouse ``String`` — the manual enumerates ClickHouse's data types + exhaustively and XML is not among them; nothing is + rendered, the declared substitute is the byte-string type + Firebird ``BLOB SUB_TYPE TEXT`` — Firebird's ``TEXT`` is an alias + for BLOB subtype 1, "a specialized subtype used to store + plain text data that is too large to fit into a string + type", not a ``VARCHAR``-sized string type + ============== ========================== + + This is a *documentation* table, not a contract: a backend whose entry is + missing has not implemented the type. Every row was taken from that + backend's own documentation, and a row that is wrong here is a defect here + — not a licence for the backend to differ. + + Vendor documentation, checked row by row: + + * PostgreSQL — https://www.postgresql.org/docs/current/datatype-xml.html + * Oracle — XML Types section: + https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/Data-Types.html + * SQL Server — + https://learn.microsoft.com/en-us/sql/t-sql/xml/xml-transact-sql + https://learn.microsoft.com/en-us/sql/relational-databases/xml/xml-indexes-sql-server + * MySQL — https://dev.mysql.com/doc/refman/8.4/en/data-types.html + * MariaDB — + https://mariadb.com/docs/server/reference/data-types/string-data-types/xmltype + * SQLite — https://www.sqlite.org/datatype3.html + * Snowflake — the type list, which has no XML entry, and the function that + defines what XML is stored as: + https://docs.snowflake.com/en/sql-reference/intro-summary-data-types + https://docs.snowflake.com/en/sql-reference/functions/parse_xml + * BigQuery — + https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types + * ClickHouse — https://clickhouse.com/docs/en/sql-reference/data-types + * Firebird — + https://www.firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-datatypes-bnrytypes.html + + Kept separate from :class:`~...types.custom.CustomType`, which is what + ``parse_type()`` yields for a name the framework does not recognise: + ``XmlType`` is a modelled concept, ``CustomType`` is honest ignorance. + """ + + name = "xml" + + def __init__(self, dialect=None): + super().__init__(dialect) diff --git a/src/rhosocial/activerecord/backend/expression/uuid.py b/src/rhosocial/activerecord/backend/expression/uuid.py new file mode 100644 index 000000000..5a0531d31 --- /dev/null +++ b/src/rhosocial/activerecord/backend/expression/uuid.py @@ -0,0 +1,190 @@ +# src/rhosocial/activerecord/backend/expression/uuid.py +"""UUID value expressions. + +Two things about UUIDs are worth separating, because they vary wildly across +databases while the request does not: + +* **Generating** one. Eight backends spell this eight different ways + (``gen_random_uuid()``, ``UUID()``, ``NEWID()``, ``SYS_GUID()``, + ``UUID_STRING()``, ``GENERATE_UUID()``, ``generateUUIDv4()``, ``GEN_UUID()``), + and one (SQLite) has no such function at all. +* **Storing** one. A handful have a native type; the rest emulate it + (``BINARY(16)``, ``CHAR(16) CHARACTER SET OCTETS``, ``RAW(16)``, ``TEXT``). + +This module covers the first. The second belongs to the DDL layer +(:mod:`...expression.types`) and is deliberately not referenced here: a +:class:`UUIDExpression` means "a UUID value", identically on every backend. + +A dialect participates by implementing :class:`UUIDSupport`. A dialect with +no way to generate a UUID returns ``False`` from +``supports_uuid_generation()`` and rendering then raises +:class:`~...dialect.exceptions.UnsupportedFeatureError` — the caller falls +back to generating one in Python, which is what ``UUIDMixin`` does today. +""" + +from typing import Any, Optional, TYPE_CHECKING + +from ..dialect.exceptions import UnsupportedFeatureError +from .bases import SQLValueExpression +from .mixins import AliasableMixin, ComparisonMixin, TypeCastingMixin + +if TYPE_CHECKING: # pragma: no cover + from ..dialect import SQLDialectBase + + +def _require(dialect, probe: str, feature: str, alternative: str) -> None: + """Refuse early when *dialect* cannot render this UUID operation. + + The alternative to refusing is an ``AttributeError`` about a missing + formatting method, raised deep inside rendering and naming neither the + feature nor the way out. A dialect that does not implement UUID at all has + no probe to answer, which is the same answer as answering False. + + Args: + dialect: The dialect about to render the expression. + probe: Name of the capability probe for this operation. + feature: Human-readable name of what was asked for. + alternative: What to do instead. + + Raises: + UnsupportedFeatureError: If the dialect does not support the feature. + """ + if getattr(dialect, probe, False): + return + raise UnsupportedFeatureError( + dialect_name=type(dialect).__name__, + feature_name=feature, + suggestion=alternative, + ) + + +class UUIDGenerationExpression( + AliasableMixin, + ComparisonMixin, + TypeCastingMixin, + SQLValueExpression, +): + """A fresh UUID, rendered as a native zero-argument function call. + + Example: + >>> from rhosocial.activerecord.backend.expression import UUIDGenerationExpression + >>> expr = UUIDGenerationExpression(dialect) # doctest: +SKIP + >>> expr.to_sql() # doctest: +SKIP + ('gen_random_uuid()', ()) + + The SQL differs per backend; the node does not. A dialect that cannot + generate a UUID raises :class:`UnsupportedFeatureError` at render time + rather than emitting another backend's function. + """ + + def __init__( + self, + dialect: "SQLDialectBase", + *, + alias: Optional[str] = None, + ): + super().__init__(dialect) + _require( + dialect, + "supports_uuid_generation", + "generate a UUID in SQL", + "Generate the value in Python with uuid.uuid4() and store it as a " + "string.", + ) + self.alias = alias + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_uuid_generation" + + +class UUIDConstantExpression( + AliasableMixin, + ComparisonMixin, + TypeCastingMixin, + SQLValueExpression, +): + """The ``nil`` or ``max`` UUID constant. + + Args: + which: ``"nil"`` (all zeroes) or ``"max"`` (all ones). Nothing else + is accepted — a typo must not silently render a literal. + """ + + _KINDS = ("nil", "max") + + def __init__( + self, + dialect: "SQLDialectBase", + which: str, + *, + alias: Optional[str] = None, + ): + super().__init__(dialect) + # Argument validation first: a typo is a bug in the calling code, and + # reporting "this dialect cannot render constants" instead would hide + # it behind an environment limit the caller cannot change. + normalised = str(which).lower() + if normalised not in self._KINDS: + raise ValueError( + f"which must be one of {self._KINDS}, got {which!r}" + ) + _require( + dialect, + "supports_uuid_constant", + "render UUID constants in SQL", + "Write the literal yourself: '00000000-0000-0000-0000-000000000000' " + "for nil and all f's for max.", + ) + self.which = normalised + self.alias = alias + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_uuid_constant" + + +class UUIDCastExpression( + AliasableMixin, + ComparisonMixin, + TypeCastingMixin, + SQLValueExpression, +): + """Convert a textual value to a UUID, rejecting malformed input. + + Portable SQL cannot express this: each backend has its own conversion + (a cast, a try-cast, a dedicated function) and they differ in whether + they raise on bad input. The node states the intent; the dialect decides + the spelling. + """ + + def __init__( + self, + dialect: "SQLDialectBase", + expression: Any, + *, + alias: Optional[str] = None, + ): + super().__init__(dialect) + _require( + dialect, + "supports_uuid_cast", + "cast text to a UUID in SQL", + "Parse it in Python with uuid.UUID() and store the result.", + ) + self.expression = expression + self.alias = alias + + @property + def format_method(self) -> str: + """The dialect formatting method that renders this expression.""" + return "format_uuid_cast" + + +__all__ = [ + "UUIDGenerationExpression", + "UUIDConstantExpression", + "UUIDCastExpression", +] diff --git a/src/rhosocial/activerecord/backend/expression/xml.py b/src/rhosocial/activerecord/backend/expression/xml.py index ef02fbd0e..b74911d88 100644 --- a/src/rhosocial/activerecord/backend/expression/xml.py +++ b/src/rhosocial/activerecord/backend/expression/xml.py @@ -5,7 +5,9 @@ from enum import Enum from typing import Optional, Sequence, TYPE_CHECKING -from .bases import BaseExpression, SQLPredicate, SQLValueExpression +from .advanced_functions import DeclaredValueType +from .bases import BaseExpression, SQLPredicate, SQLQueryAndParams, SQLValueExpression +from .core import StringValueExpression, XMLValueExpression if TYPE_CHECKING: # pragma: no cover from ..dialect import SQLDialectBase @@ -62,8 +64,14 @@ class XMLTableColumnOption(str, Enum): DEFAULT = "DEFAULT" -class XMLParseExpression(SQLValueExpression): - """Represents a SQL/XML XMLPARSE expression constructor.""" +class XMLParseExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): + """Represents a SQL/XML XMLPARSE expression constructor. + + The parse of a document *is* an XML value, so it declares + :class:`~...expression.core.XMLValueExpression` (see + :class:`~...expression.advanced_functions.DeclaredValueType` for why these + nodes inherit the value class rather than being wrapped by one). + """ def __init__( self, @@ -72,7 +80,7 @@ def __init__( document_type: XMLParseDocumentType = XMLParseDocumentType.DOCUMENT, whitespace_option: Optional[XMLWhitespaceOption] = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.content = content self.document_type = document_type self.whitespace_option = whitespace_option @@ -83,8 +91,14 @@ def format_method(self) -> str: return "format_xmlparse_expression" -class XMLSerializeExpression(SQLValueExpression): - """Represents a SQL/XML XMLSERIALIZE expression constructor.""" +class XMLSerializeExpression(DeclaredValueType, StringValueExpression, SQLValueExpression): + """Represents a SQL/XML XMLSERIALIZE expression constructor. + + Serialization leaves the XML family: what comes back is the character + value named in ``target_type``, so the node declares + :class:`~...expression.core.StringValueExpression` and carries the string + operations rather than the XML surface. + """ def __init__( self, @@ -94,7 +108,7 @@ def __init__( document_type: XMLSerializeDocumentType = XMLSerializeDocumentType.CONTENT, whitespace_option: Optional[XMLWhitespaceOption] = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.content = content self.target_type = target_type self.document_type = document_type @@ -137,7 +151,7 @@ def format_method(self) -> str: return "format_xmlattributes_expression" -class XMLElementExpression(SQLValueExpression): +class XMLElementExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): """Represents a SQL/XML XMLELEMENT expression constructor.""" def __init__( @@ -147,7 +161,7 @@ def __init__( content: Optional[Sequence[BaseExpression]] = None, attributes: Optional[XMLAttributesExpression] = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.name = name self.content = list(content or []) self.attributes = attributes @@ -169,7 +183,7 @@ class XMLForestItem: name: Optional[str] = None -class XMLForestExpression(SQLValueExpression): +class XMLForestExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): """Represents a SQL/XML XMLFOREST expression constructor.""" def __init__( @@ -177,7 +191,7 @@ def __init__( dialect: "SQLDialectBase", items: Sequence[XMLForestItem], ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.items = list(items) @property @@ -186,11 +200,11 @@ def format_method(self) -> str: return "format_xmlforest_expression" -class XMLConcatExpression(SQLValueExpression): +class XMLConcatExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): """Represents a SQL/XML XMLCONCAT expression constructor.""" def __init__(self, dialect: "SQLDialectBase", parts: Sequence[BaseExpression]): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.parts = list(parts) @property @@ -199,11 +213,11 @@ def format_method(self) -> str: return "format_xmlconcat_expression" -class XMLCommentExpression(SQLValueExpression): +class XMLCommentExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): """Represents a SQL/XML XMLCOMMENT expression constructor.""" def __init__(self, dialect: "SQLDialectBase", content: BaseExpression): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.content = content @property @@ -212,7 +226,7 @@ def format_method(self) -> str: return "format_xmlcomment_expression" -class XMLPIExpression(SQLValueExpression): +class XMLPIExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): """Represents a SQL/XML XMLPI expression constructor.""" def __init__( @@ -221,7 +235,7 @@ def __init__( target: str, content: Optional[BaseExpression] = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.target = target self.content = content @@ -231,7 +245,7 @@ def format_method(self) -> str: return "format_xmlpi_expression" -class XMLRootExpression(SQLValueExpression): +class XMLRootExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): """Represents a SQL/XML XMLROOT expression constructor.""" def __init__( @@ -241,7 +255,7 @@ def __init__( version: Optional[BaseExpression] = None, standalone: Optional[XMLStandaloneOption] = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.content = content self.version = version self.standalone = standalone @@ -252,7 +266,7 @@ def format_method(self) -> str: return "format_xmlroot_expression" -class XMLAggExpression(SQLValueExpression): +class XMLAggExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): """Represents a SQL/XML XMLAGG aggregate expression.""" def __init__( @@ -261,7 +275,7 @@ def __init__( expression: BaseExpression, order_by: Optional["OrderByClause"] = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.expression = expression self.order_by = order_by @@ -271,7 +285,7 @@ def format_method(self) -> str: return "format_xmlagg_expression" -class XMLQueryExpression(SQLValueExpression): +class XMLQueryExpression(DeclaredValueType, XMLValueExpression, SQLValueExpression): """Represents a SQL/XML XMLQUERY expression.""" def __init__( @@ -283,7 +297,7 @@ def __init__( returning_content: bool = True, empty_handling: Optional[XMLEmptyHandlingOption] = None, ): - super().__init__(dialect) + BaseExpression.__init__(self, dialect) self.query = query self.passing = list(passing or []) self.passing_mechanism = passing_mechanism diff --git a/src/rhosocial/activerecord/backend/impl/dummy/column_type.py b/src/rhosocial/activerecord/backend/impl/dummy/column_type.py new file mode 100644 index 000000000..5213145b1 --- /dev/null +++ b/src/rhosocial/activerecord/backend/impl/dummy/column_type.py @@ -0,0 +1,62 @@ +# src/rhosocial/activerecord/backend/impl/dummy/column_type.py +"""The dummy dialect's column-type table: core's dialect-less baseline. + +The dummy dialect renders the portable SQL surface and stands for no server, +so its table is the portable baseline -- deliberately **not** SQLite's table, +even though SQLite is the backend built into core and the two are easy to +conflate. It is the dialect-less default a unit test reads, not a copy of any +one backend: where a real backend has stated its own answer (sequences as +JSONColumn, for instance), the dummy keeps the standard-shaped one. +""" + +import datetime +import decimal +import enum +import uuid +from typing import Any, Dict, Type + +from rhosocial.activerecord.backend.dialect.mixins.column_type import ColumnTypeMixin +from rhosocial.activerecord.backend.expression.column_types import ( + ArrayColumn, + BinaryColumn, + BooleanColumn, + ColumnBase, + TimestampColumn, + IntegerColumn, + JSONColumn, + NumericColumn, + StringColumn, + UUIDColumn, +) + +#: The portable baseline: ``{common Python type: ColumnBase subclass}``. +DUMMY_COLUMN_TYPES: Dict[Any, Type[ColumnBase]] = { + bool: BooleanColumn, + int: IntegerColumn, + float: NumericColumn, + decimal.Decimal: NumericColumn, + str: StringColumn, + bytes: BinaryColumn, + bytearray: BinaryColumn, + datetime.date: TimestampColumn, + datetime.time: TimestampColumn, + datetime.datetime: TimestampColumn, + datetime.timedelta: NumericColumn, + uuid.UUID: UUIDColumn, + dict: JSONColumn, + list: ArrayColumn, + tuple: ArrayColumn, + set: ArrayColumn, + frozenset: ArrayColumn, + enum.Enum: StringColumn, +} + + +class DummyColumnTypeMixin(ColumnTypeMixin): + """The dialect-less baseline table, for tests to read.""" + + def suggested_column_types(self) -> Dict[Any, Type[ColumnBase]]: + return dict(DUMMY_COLUMN_TYPES) + + +__all__ = ["DUMMY_COLUMN_TYPES", "DummyColumnTypeMixin"] diff --git a/src/rhosocial/activerecord/backend/impl/dummy/dialect.py b/src/rhosocial/activerecord/backend/impl/dummy/dialect.py index 6fe5e90cf..0c24b8e2b 100644 --- a/src/rhosocial/activerecord/backend/impl/dummy/dialect.py +++ b/src/rhosocial/activerecord/backend/impl/dummy/dialect.py @@ -52,10 +52,10 @@ from rhosocial.activerecord.backend.expression import Literal from rhosocial.activerecord.backend.expression.types import ( ArrayType, BigIntType, BinaryType, BlobType, BooleanType, CharType, CustomType, - DateType, DateTimeType, DecimalType, DoubleType, EnumType, FloatType, - IntType, IntegerType, IntervalType, JsonBType, JsonType, + DataType, DateType, DateTimeType, DecimalType, DoubleType, EnumType, FloatType, + IntegerType, IntervalType, JsonBType, JsonType, RealType, SmallIntType, TextType, TimeType, TimeTzType, - TimestampType, TimestampTzType, TinyIntType, VarBinaryType, VarCharType, + TimestampType, TimestampTzType, TinyIntType, UUIDType, VarBinaryType, VarCharType, XmlType, ) from rhosocial.activerecord.backend.expression.statements.ddl_domain import ( DomainAlterAction, @@ -66,6 +66,7 @@ TypeDefinition, ) from .expression import _DummyTypeAlterAction, _DummyTypeDefinition +from .column_type import DummyColumnTypeMixin from rhosocial.activerecord.backend.dialect.protocols import ( # Named-object protocols TableObjectSupport, @@ -81,6 +82,8 @@ NamespaceSupport, # DDL statement protocols DataTypeSupport, + # Column Class Support Protocol + ColumnTypeSupport, SQLXMLSupport, SQLXMLParsingSupport, SQLXMLSerializationSupport, @@ -97,6 +100,7 @@ LateralJoinSupport, ArraySupport, JSONSupport, + UUIDSupport, ExplainSupport, FilterClauseSupport, OrderedSetAggregationSupport, @@ -156,7 +160,7 @@ CreateDomainSupport, AlterDomainSupport, DropDomainSupport, - DateTimeSupport, + TimestampSupport, DqlOrderSupport, PivotSupport, ) @@ -194,6 +198,7 @@ LateralJoinMixin, ArrayMixin, JSONMixin, + UUIDMixin, ExplainMixin, MergeMixin, TemporalTableMixin, @@ -223,6 +228,10 @@ IntrospectionMixin, # New Mixins PredicateMixin, + TrimMixin, + LpadMixin, + RepeatMixin, + RpadMixin, ExpressionMixin, DateTimeMixin, DQLMixin, @@ -236,6 +245,100 @@ _COLLATION_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") +# --------------------------------------------------------------------------- +# parse_type: the closed vocabulary this dialect can read back +# --------------------------------------------------------------------------- +# +# DummyDialect renders SQL-standard type names (the ``format_data_type_*`` +# family on the class below), so those names are exactly what it can parse. +# The point of parsing at all is canonicality: **one concept in, exactly one +# class out, carrying the spelling it was written with**. ``character varying`` +# must come back as the variable-length concept and never as the fixed-length +# one, and ``DOUBLE`` and ``DOUBLE PRECISION`` must come back as the same class +# — the whole reason ``SPELLINGS`` exists is that a second class per synonym +# would make the differ report a change that is not there. +# +# The table is derived from the classes' own ``SPELLINGS`` rather than written +# out, so it cannot drift from the closed list the formatters validate against. + +#: The core concepts ``parse_type`` recognises. ``IntervalType`` is handled +#: before the table lookup because its qualifier is a suffix rather than a name. +#: ``EnumType`` is absent because ``ENUM('a','b')`` is a value list, not a type +#: name — the part that says which values is not the part that says which type, +#: and ``CustomType`` keeps it verbatim. +_PARSE_CONCEPTS = ( + BigIntType, BinaryType, BlobType, BooleanType, CharType, DateTimeType, + DateType, DecimalType, DoubleType, FloatType, IntegerType, JsonBType, + JsonType, RealType, SmallIntType, TextType, TimeType, TimeTzType, + TimestampType, TimestampTzType, TinyIntType, UUIDType, VarBinaryType, + VarCharType, XmlType, +) + +#: ``{UPPER-CASED type name: concept}``. A concept with several spellings +#: contributes each of them and a concept with one contributes that one, so +#: ``CHAR`` and ``CHARACTER`` land on ``CharType`` while ``CHARACTER VARYING`` +#: lands on ``VarCharType`` — three names, two concepts, no ambiguity. +_PARSE_VOCABULARY: Dict[str, Type] = { + spelling.upper(): concept + for concept in _PARSE_CONCEPTS + for spelling in (concept.SPELLINGS or (concept.name,)) +} + +#: The four names the zoned concepts are *written* as. Their dispatch names are +#: ``timetz`` / ``timestamptz``, which is what PostgreSQL calls them; the +#: standard spells them out and dummy renders the standard form, so both reach +#: the concept. ``WITHOUT TIME ZONE`` is the standard's name for the +#: un-suffixed type, so it lands on the un-zoned concept. +_PARSE_VOCABULARY.update({ + "TIME WITH TIME ZONE": TimeTzType, + "TIMESTAMP WITH TIME ZONE": TimestampTzType, + "TIME WITHOUT TIME ZONE": TimeType, + "TIMESTAMP WITHOUT TIME ZONE": TimestampType, +}) + +#: Which constructor keyword each numeric parameter of a type name fills, in +#: the order the numbers are written. A concept absent from this table takes no +#: numbers, so ``INT(11)`` is *not* silently read as ``INT`` — a width the type +#: cannot carry is not a type name dummy writes, and it is reported as the raw +#: text instead. +_PARSE_NUMERIC_PARAMS: Dict[Type, Tuple[str, ...]] = { + BinaryType: ("length",), + CharType: ("length",), + DateTimeType: ("precision",), + DecimalType: ("precision", "scale"), + FloatType: ("precision",), + TimeType: ("precision",), + TimeTzType: ("precision",), + TimestampType: ("precision",), + TimestampTzType: ("precision",), + VarBinaryType: ("length",), + VarCharType: ("length",), +} + +#: One precision group, digits only, wherever it appears in the name: the +#: standard writes it before the zone suffix (``TIMESTAMP(3) WITH TIME ZONE``) +#: as well as at the end (``DECIMAL(10,2)``). +_PARSE_PRECISION_RE = re.compile(r"\(\s*(\d+(?:\s*,\s*\d+)*)?\s*\)") + +#: A trailing array marker, one per dimension. +_PARSE_ARRAY_MARKER_RE = re.compile(r"\[\s*\]\s*$") + + +def _split_precision(raw: str) -> Tuple[str, Tuple[int, ...]]: + """Split ``TIMESTAMP(3) WITH TIME ZONE`` into its name and its numbers. + + Returns the name with the precision group removed and the numbers as ints, + in the order they were written. A name with no precision group comes back + unchanged with no numbers. + """ + match = _PARSE_PRECISION_RE.search(raw) + if match is None: + return raw, () + written = match.group(1) or "" + numbers = tuple(int(part) for part in written.split(",")) if written.strip() else () + return (raw[:match.start()] + raw[match.end():]).strip(), numbers + + if TYPE_CHECKING: from rhosocial.activerecord.backend.expression.collation import CollateExpression from rhosocial.activerecord.backend.expression.statements import ColumnDefinition @@ -298,6 +401,7 @@ class DummyDialect( LateralJoinMixin, ArrayMixin, JSONMixin, + UUIDMixin, ExplainMixin, MergeMixin, TemporalTableMixin, @@ -327,14 +431,20 @@ class DummyDialect( IntrospectionMixin, # New Mixins PredicateMixin, + TrimMixin, + LpadMixin, + RepeatMixin, + RpadMixin, ExpressionMixin, DateTimeMixin, DQLMixin, DMLMixin, DataTypeMixin, + DummyColumnTypeMixin, UserDefinedTypeMixin, DomainMixin, DataTypeSupport, + ColumnTypeSupport, DDLColumnMixin, TransactionControlMixin, # Protocols for type checking @@ -354,6 +464,7 @@ class DummyDialect( LateralJoinSupport, ArraySupport, JSONSupport, + UUIDSupport, ExplainSupport, FilterClauseSupport, OrderedSetAggregationSupport, @@ -411,7 +522,7 @@ class DummyDialect( CreateDomainSupport, AlterDomainSupport, DropDomainSupport, - DateTimeSupport, + TimestampSupport, DqlOrderSupport, CreateSchemaSupport, DropSchemaSupport, @@ -433,186 +544,234 @@ def __init__(self) -> None: # DataType formatters (core types — for to_sql() testing) # ------------------------------------------------------------------ - def supports_data_type_tinyint(self) -> bool: - return True + def _refuse_unsigned(self, data_type, word: str) -> None: + """Refuse ``unsigned=True``, because the standard grammar dummy renders + has no ``UNSIGNED`` attribute. + + Signedness is a **field** on every numeric concept — the four integer + widths and the three ``DECIMAL`` / ``FLOAT`` / ``DOUBLE`` concepts — so + ``DecimalType(unsigned=True)`` is constructible and the flag reaches the + formatter. Dummy renders the SQL-standard type names, and the standard + has no ``UNSIGNED``: + + * MySQL's own manual calls the attribute *nonstandard*: "All integer + types can have an optional (nonstandard) UNSIGNED attribute." + https://dev.mysql.com/doc/refman/9.7/en/numeric-type-attributes.html + * PostgreSQL, which does conform, has nothing to place after a type name: + its numeric-types chapter enumerates each integer with one symmetric + range and no unsigned variant anywhere in it. + https://www.postgresql.org/docs/current/datatype-numeric.html + + So there is not even a spelling that would parse. Writing bare + ``DECIMAL`` or ``INTEGER`` for an unsigned request would create a column + that accepts the negatives the caller declared it would not, and report + success: the same silent loss as accepting the flag and discarding it, + which is what this replaces. + + ``word`` is the concept the caller asked for, so the message can say + *which* type was refused. ``UnsupportedFeatureError``, not + ``ValueError``: the declaration is not a wrong value, it is a + declaration this grammar cannot express at all, and the two exceptions + do not share a base class. + """ + if not getattr(data_type, "unsigned", False): + return + raise UnsupportedFeatureError( + self.name, + f"an unsigned {word} column " + f"(dummy renders the SQL-standard type names, and the standard has " + f"no UNSIGNED attribute to place after a type name; MySQL calls its " + f"own UNSIGNED nonstandard, and PostgreSQL's numeric-types chapter " + f"lists no unsigned variant)", + suggestion=( + "Declare the column signed and enforce the range with a CHECK " + "constraint if negatives must be rejected." + ), + ) def format_data_type_tinyint(self, data_type: TinyIntType) -> Tuple[str, tuple]: + self._refuse_unsigned(data_type, "TINYINT") return "TINYINT", () - def supports_data_type_smallint(self) -> bool: - return True - def format_data_type_smallint(self, data_type: SmallIntType) -> Tuple[str, tuple]: + self._refuse_unsigned(data_type, "SMALLINT") return "SMALLINT", () - def supports_data_type_int(self) -> bool: - return True - - def format_data_type_int(self, data_type: IntType) -> Tuple[str, tuple]: - return "INT", () - - def supports_data_type_integer(self) -> bool: - return True - def format_data_type_integer(self, data_type: IntegerType) -> Tuple[str, tuple]: - return "INTEGER", () - - def supports_data_type_bigint(self) -> bool: - return True + """The dummy dialect renders every spelling of this one type verbatim, + which is what makes it useful for testing dispatch. + + ``unsigned`` is refused rather than ignored; see + :meth:`_refuse_unsigned`.""" + if data_type.spelling not in IntegerType.SPELLINGS: + raise TypeError( + f"{type(self).__name__} cannot render {data_type.spelling!r}; " + f"it accepts {', '.join(IntegerType.SPELLINGS)}." + ) + self._refuse_unsigned(data_type, "INTEGER") + return "INT" if data_type.spelling == "int" else "INTEGER", () def format_data_type_bigint(self, data_type: BigIntType) -> Tuple[str, tuple]: + self._refuse_unsigned(data_type, "BIGINT") return "BIGINT", () - def supports_data_type_real(self) -> bool: - return True - def format_data_type_real(self, data_type: RealType) -> Tuple[str, tuple]: + # REAL is refused for unsigned for the same reason as every other + # numeric here: the grammar this dialect renders has no UNSIGNED + # modifier, so the flag cannot be honoured and must not be dropped. + self._refuse_unsigned(data_type, "REAL") return "REAL", () - def supports_data_type_double(self) -> bool: - return True - def format_data_type_double(self, data_type: DoubleType) -> Tuple[str, tuple]: + self._refuse_unsigned(data_type, "DOUBLE PRECISION") return "DOUBLE PRECISION", () - def supports_data_type_text(self) -> bool: - return True - def format_data_type_text(self, data_type: TextType) -> Tuple[str, tuple]: return "TEXT", () - def supports_data_type_boolean(self) -> bool: - return True - def format_data_type_boolean(self, data_type: BooleanType) -> Tuple[str, tuple]: return "BOOLEAN", () - def supports_data_type_blob(self) -> bool: - return True - def format_data_type_blob(self, data_type: BlobType) -> Tuple[str, tuple]: return "BLOB", () - def supports_data_type_date(self) -> bool: - return True - def format_data_type_date(self, data_type: DateType) -> Tuple[str, tuple]: return "DATE", () - def supports_data_type_json(self) -> bool: - return True - def format_data_type_json(self, data_type: JsonType) -> Tuple[str, tuple]: return "JSON", () - def supports_data_type_jsonb(self) -> bool: - return True - def format_data_type_jsonb(self, data_type: JsonBType) -> Tuple[str, tuple]: return "JSONB", () - def supports_data_type_char(self) -> bool: - return True + def format_data_type_xml(self, data_type: XmlType) -> Tuple[str, tuple]: + return "XML", () + + def format_data_type_uuid(self, data_type: UUIDType) -> Tuple[str, tuple]: + return "UUID", () def format_data_type_char(self, data_type: CharType) -> Tuple[str, tuple]: return (f"CHAR({data_type.length})" if data_type.length is not None else "CHAR"), () - def supports_data_type_varchar(self) -> bool: - return True - def format_data_type_varchar(self, data_type: VarCharType) -> Tuple[str, tuple]: return (f"VARCHAR({data_type.length})" if data_type.length is not None else "VARCHAR"), () - def supports_data_type_binary(self) -> bool: - return True - def format_data_type_binary(self, data_type: BinaryType) -> Tuple[str, tuple]: return (f"BINARY({data_type.length})" if data_type.length is not None else "BINARY"), () - def supports_data_type_varbinary(self) -> bool: - return True - def format_data_type_varbinary(self, data_type: VarBinaryType) -> Tuple[str, tuple]: return (f"VARBINARY({data_type.length})" if data_type.length is not None else "VARBINARY"), () - def supports_data_type_enum(self) -> bool: - return True - def format_data_type_enum(self, data_type: EnumType) -> Tuple[str, tuple]: - values = ",".join(f"'{value}'" for value in data_type.values) - return f"ENUM({values}), "[: -2] + "" if False else f"ENUM({values})", () - - def supports_data_type_float(self) -> bool: - return True + # format_literal rather than an f-string of quotes: it is the dialect's + # own escaping, so a value containing a quote survives. + values = ",".join(self.format_literal(value) for value in data_type.values) + return f"ENUM({values})", () def format_data_type_float(self, data_type: FloatType) -> Tuple[str, tuple]: + self._refuse_unsigned(data_type, "FLOAT") return (f"FLOAT({data_type.precision})" if data_type.precision is not None else "FLOAT"), () - def supports_data_type_decimal(self) -> bool: - return True - def format_data_type_decimal(self, data_type: DecimalType) -> Tuple[str, tuple]: + self._refuse_unsigned(data_type, "DECIMAL") if data_type.precision is not None and data_type.scale is not None: return f"DECIMAL({data_type.precision},{data_type.scale})", () if data_type.precision is not None: return f"DECIMAL({data_type.precision})", () return "DECIMAL", () - def supports_data_type_time(self) -> bool: - return True - def format_data_type_time(self, data_type: TimeType) -> Tuple[str, tuple]: return (f"TIME({data_type.precision})" if data_type.precision is not None else "TIME"), () - def supports_data_type_timetz(self) -> bool: - return True - def format_data_type_timetz(self, data_type: TimeTzType) -> Tuple[str, tuple]: base = f"TIME({data_type.precision})" if data_type.precision is not None else "TIME" return f"{base} WITH TIME ZONE", () - def supports_data_type_datetime(self) -> bool: - return True - def format_data_type_datetime(self, data_type: DateTimeType) -> Tuple[str, tuple]: return (f"DATETIME({data_type.precision})" if data_type.precision is not None else "DATETIME"), () - def supports_data_type_timestamp(self) -> bool: - return True - def format_data_type_timestamp(self, data_type: TimestampType) -> Tuple[str, tuple]: return (f"TIMESTAMP({data_type.precision})" if data_type.precision is not None else "TIMESTAMP"), () - def supports_data_type_timestamptz(self) -> bool: - return True - def format_data_type_timestamptz(self, data_type: TimestampTzType) -> Tuple[str, tuple]: base = f"TIMESTAMP({data_type.precision})" if data_type.precision is not None else "TIMESTAMP" return f"{base} WITH TIME ZONE", () - def supports_data_type_interval(self) -> bool: - return True - def format_data_type_interval(self, data_type: IntervalType) -> Tuple[str, tuple]: return (f"INTERVAL {data_type.fields}" if data_type.fields else "INTERVAL"), () - def supports_data_type_custom(self) -> bool: - return True - def format_data_type_custom(self, data_type: CustomType) -> Tuple[str, tuple]: return data_type.raw, () - def supports_data_type_array(self) -> bool: - return True - def format_data_type_array(self, data_type: ArrayType) -> Tuple[str, tuple]: element_sql, _ = self.format_data_type(data_type.element_type) return element_sql + "[]" * data_type.dimensions, () - def parse_type(self, raw: str) -> CustomType: - """Parse a raw SQL type string — dummy dialect always returns CustomType.""" - from rhosocial.activerecord.backend.expression.types import CustomType - return CustomType(raw.strip()) + def parse_type(self, raw: str) -> DataType: + """Parse a SQL type name back into the concept it names. + + Dummy renders SQL-standard type names, so those names are exactly what + it can read back, and the answer is **canonical**: one concept in, + exactly one class out, carrying the spelling it was written with. + + That last part is what keeps the schema differ honest. + ``parse_type("character varying")`` is a ``VarCharType`` — the + variable-length concept — and never a ``CharType``: they are different + storage, and a parser that conflated them would report a column as + changed when nothing about it had. Conversely ``parse_type("DOUBLE")`` + and ``parse_type("DOUBLE PRECISION")`` are the *same* class, because + they are the same type written two ways. + + A name this dialect does not render comes back as ``CustomType``. That + is the honest answer for a type the framework has no class for, and it + is what lets an introspected schema be written back verbatim; it is + *not* an answer for a name in the table above, which is why the table + is checked against every core ``SPELLINGS`` entry by + ``tests/.../dummy2/test_type_spelling_parse.py``. + """ + stripped = raw.strip() + if not stripped: + return CustomType(self, stripped) + + # Array markers are not part of the element's name: ``VARCHAR(30)[]`` is + # one-dimensional and ``VARCHAR(30)[][]`` two. + element_name = stripped + dimensions = 0 + while True: + marker = _PARSE_ARRAY_MARKER_RE.search(element_name) + if marker is None: + break + element_name = element_name[:marker.start()] + dimensions += 1 + + name, numbers = _split_precision(element_name) + upper = name.upper() + + # ``INTERVAL`` carries a qualifier rather than a name, so it is matched + # as a prefix. IntervalType validates the qualifier itself. + if upper == "INTERVAL" or upper.startswith("INTERVAL "): + element = IntervalType( + self, fields=name[len("INTERVAL"):].strip() or None, + ) + else: + concept = _PARSE_VOCABULARY.get(upper) + fields = _PARSE_NUMERIC_PARAMS.get(concept, ()) if concept else () + if concept is None or len(numbers) > len(fields): + # Either a name dummy does not render, or numbers the concept + # cannot carry (``INT(11)``). Both are reported verbatim rather + # than guessed at. + element = CustomType(self, stripped) + else: + kwargs = dict(zip(fields, numbers)) + if concept.SPELLINGS: + kwargs["spelling"] = upper.lower() + element = concept(self, **kwargs) + + if not dimensions: + return element + return ArrayType( + self, element_type=element, dimensions=dimensions, + ) def supports_type_objects(self) -> bool: return True diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/dialect.py b/src/rhosocial/activerecord/backend/impl/sqlite/dialect.py index e792880a2..242c76d0d 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/dialect.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/dialect.py @@ -15,6 +15,7 @@ FilterClauseSupport, WindowFunctionSupport, JSONSupport, + UUIDSupport, ReturningSupport, AdvancedGroupingSupport, ArraySupport, @@ -47,6 +48,8 @@ SQLFunctionSupport, # Type Support Protocol DataTypeSupport, + # Column Class Support Protocol + ColumnTypeSupport, ) from rhosocial.activerecord.backend.dialect.mixins import ( DatabaseNameMixin, @@ -71,10 +74,15 @@ DatabaseNameMixin, PropertyGraphNameMixin, CollationMixin, + # Column types. SQLiteColumnTypeMixin (from .mixins, below) states + # SQLite's own table; there is no generic table in core to compose. CTEMixin, WindowFunctionMixin, JSONMixin, + # SQLite has no UUID-generating function; UUIDMixin reports honest + # absence so UUIDGenerationExpression raises with a Python-side hint. + UUIDMixin, ArrayMixin, ExplainMixin, @@ -98,6 +106,10 @@ PartitionMixin, # New Mixins PredicateMixin, + TrimMixin, + LpadMixin, + RepeatMixin, + RpadMixin, ExpressionMixin, DQLMixin, DateTimeMixin, @@ -113,8 +125,15 @@ from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError if TYPE_CHECKING: - from rhosocial.activerecord.backend.expression.advanced_functions import ArrayExpression, OrderedSetAggregation + from rhosocial.activerecord.backend.expression import bases + from rhosocial.activerecord.backend.expression.advanced_functions import ( + ArrayExpression, + JSONDocumentExpression, + OrderedSetAggregation, + TrimExpression, + ) from rhosocial.activerecord.backend.expression.graph import MatchClause + from rhosocial.activerecord.backend.expression.predicates import DistinctFromPredicate from rhosocial.activerecord.backend.expression.query_parts import QualifyClause from rhosocial.activerecord.backend.expression.statements import ExplainExpression from rhosocial.activerecord.backend.expression.statements.ddl_truncate import TruncateExpression @@ -149,6 +168,10 @@ SQLiteRTreeMixin, SQLiteGeopolyMixin, SQLiteTypeSupportMixin, + # Column types. SQLite states its own full table: the four sequence entries + # take JSONColumn (there is no array type here) and float/Decimal both take + # NumericColumn. There is no generic table in core to compose. + SQLiteColumnTypeMixin, ) from rhosocial.activerecord.backend.expression.query_sources import JSONTableExpression @@ -187,6 +210,7 @@ class SQLiteDialect( WindowFunctionMixin, JSONMixin, + UUIDMixin, # Include mixins for features that SQLite does NOT support but need the methods to exist ArrayMixin, @@ -222,7 +246,16 @@ class SQLiteDialect( # their False defaults and the formatters refuse the clauses. PartitionMixin, # New Mixins (without SQLite overrides) + # SQLiteFunctionMixin rides first among them: it carries the dialect's + # function spellings and emulations, and those must win over the generic + # formatters ExpressionMixin brings -- the same precedence the comment on + # the SQLite-specific group below claims but cannot deliver from there. + SQLiteFunctionMixin, PredicateMixin, + TrimMixin, + LpadMixin, + RepeatMixin, + RpadMixin, ExpressionMixin, DQLMixin, # SQLite-specific mixins (BEFORE generic mixins they override) @@ -238,7 +271,6 @@ class SQLiteDialect( SQLiteVirtualTableMixin, SQLiteReindexMixin, SQLiteMaintenanceMixin, - SQLiteFunctionMixin, # Extension expression mixins SQLiteFTS5Mixin, SQLiteRTreeMixin, @@ -249,6 +281,10 @@ class SQLiteDialect( DomainMixin, # Collation mixin (after SQLite mixins so that SQLiteDateTimeMixin.supports_collate_expression takes priority) CollationMixin, + # Column types. SQLite states its own full table: the four sequence entries + # take JSONColumn (there is no array type here), and float/Decimal both take + # NumericColumn. + SQLiteColumnTypeMixin, # Generic mixins (fallback for methods not overridden by SQLite) DateTimeMixin, DDLColumnMixin, @@ -263,6 +299,7 @@ class SQLiteDialect( FilterClauseSupport, WindowFunctionSupport, JSONSupport, + UUIDSupport, ReturningSupport, AdvancedGroupingSupport, ArraySupport, @@ -303,6 +340,8 @@ class SQLiteDialect( SQLFunctionSupport, # DataType Support Protocol DataTypeSupport, + # Column Class Support Protocol + ColumnTypeSupport, # DDL statement protocols follow the DDL mixins: a protocol's empty # body would otherwise win over the mixin that actually renders. CreateSchemaSupport, @@ -374,12 +413,16 @@ def suggested_data_types(self) -> Dict[str, type]: value type as :meth:`supports_data_types`). Suggestions reflect SQLite's real storage model: - - ``uuid`` / ``enum``: no native types — both degrade to TEXT - affinity, so the suggested replacement is ``SQLiteTextType``. + - ``uuid`` / ``enum`` / ``xml``: no native types — ``uuid`` and ``enum`` + degrade to TEXT affinity, and SQLite stores an XML document as text + with no validation, so all three are suggested as ``SQLiteTextType``. - ``binary`` / ``varbinary``: no fixed/variable-length byte-string types — everything is BLOB affinity (the same mapping ``parse_type`` applies to ``BINARY`` / ``VARBINARY`` type strings), so the suggested replacement is ``SQLiteBlobType``. + - ``array``: SQLite has no array type. An array column is stored as + text (or as a JSON document in it), so ``SQLiteTextType`` is what + this backend actually stores. Types the type mixin does render (``json``, ``jsonb``, ``varchar``, ``date``, …) are deliberately absent: they already have a rendering @@ -391,6 +434,8 @@ def suggested_data_types(self) -> Dict[str, type]: return { "uuid": SQLiteTextType, "enum": SQLiteTextType, + "xml": SQLiteTextType, + "array": SQLiteTextType, "binary": SQLiteBlobType, "varbinary": SQLiteBlobType, } @@ -448,6 +493,38 @@ def supports_json_arrow_operators(self) -> bool: """SQLite supports -> and ->> operators from version 3.38.0+.""" return self.version >= (3, 38, 0) + def format_json_function_expression(self, expr: "JSONDocumentExpression") -> Tuple[str, tuple]: + """Render a JSON path access with SQLite's own JSON1 functions. + + Without this, ``JSONPathMode.FUNCTION`` fell through to the core + default, which emits MySQL's ``JSON_UNQUOTE(JSON_EXTRACT(...))``. + SQLite has ``json_extract`` but has no ``JSON_UNQUOTE`` at all, so + FUNCTION mode produced SQL the server rejects. + + Args: + expr: The JSONDocumentExpression node. + + Returns: + Tuple of (SQL string, parameters tuple). + """ + from rhosocial.activerecord.backend.expression import bases + + if isinstance(expr.column, bases.BaseExpression): + col_sql, col_params = expr.column.to_sql() + else: + col_sql, col_params = self.format_identifier(str(expr.column)), () + + escaped_path = self._escape_sql_string(expr.path) + # json_extract returns SQL NULL for a missing path and a + # JSON-quoted string for text, so it stands in for ->> without a + # separate unquote step — SQLite has no JSON_UNQUOTE to call. + sql = f"json_extract({col_sql}, '{escaped_path}')" + params = col_params + + if expr.alias: + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, params + def get_json_access_operator(self) -> str: """SQLite uses '->' for JSON access.""" return "->" @@ -596,7 +673,66 @@ def supports_lateral_join(self) -> bool: type(self)._lateral_support = result return self._lateral_support - def format_values_expression(self, expr) -> Tuple[str, Tuple]: + def supports_distinct_from(self) -> bool: + """Whether SQLite accepts ``IS [NOT] DISTINCT FROM`` (3.39.0+).""" + return self.version >= (3, 39, 0) + + def format_distinct_from_predicate(self, expr: "DistinctFromPredicate") -> Tuple[str, tuple]: + """Format a NULL-safe distinctness check, refusing below SQLite 3.39.0. + + SQLite has had the standard spelling since 3.39.0 (2022-06-25). Below + it the framework **refuses** rather than substituting a different + question, and the refusal names the version so the caller can decide + between upgrading and comparing the nullability of the two sides by + hand. + + Args: + expr: Distinctness check exposing ``left``, ``right``, ``is_not``. + + Returns: + Tuple of (SQL string, parameters tuple). + + Raises: + UnsupportedFeatureError: On SQLite older than 3.39.0. + """ + if not self.supports_distinct_from(): + raise UnsupportedFeatureError( + self.name, + "IS [NOT] DISTINCT FROM (SQLite 3.39.0+)", + ) + left_sql, left_params = expr.left.to_sql() + right_sql, right_params = expr.right.to_sql() + not_str = " NOT" if expr.is_not else "" + return self._with_alias( + f"{left_sql} IS{not_str} DISTINCT FROM {right_sql}", expr + ), left_params + right_params + + def format_trim_expression(self, expr: "TrimExpression") -> Tuple[str, tuple]: + """Render TRIM as SQLite's function form. + + SQLite parses no ``trim( from )`` syntax at all -- the + standard spelling is a syntax error there, measured 2026-10-09 -- so the + node is rendered as the function form instead: ``TRIM(x[, chars])`` for + BOTH, ``LTRIM`` for LEADING and ``RTRIM`` for TRAILING. A one-character + set, which is all the core contract allows, means the same thing in both + spellings, so this is a spelling difference and never a semantic one. + """ + target_sql, target_params = expr.expr.to_sql() + function_name = {"BOTH": "TRIM", "LEADING": "LTRIM", "TRAILING": "RTRIM"}[ + expr.direction + ] + if expr.chars is not None: + chars_sql, chars_params = expr.chars.to_sql() + sql = f"{function_name}({target_sql}, {chars_sql})" + params = tuple(target_params) + tuple(chars_params) + else: + sql = f"{function_name}({target_sql})" + params = tuple(target_params) + if expr.alias: + sql = f"{sql} AS {self.format_identifier(expr.alias)}" + return sql, params + + def format_values_expression(self, expr: "bases.BaseExpression") -> Tuple[str, Tuple]: """SQLite override: VALUES does not support ``AS alias(col, ...)`` syntax. The base ``ExpressionMixin`` implementation appends a parenthesised @@ -877,7 +1013,7 @@ def supports_nulls_first_last(self) -> bool: """SQLite does not support explicit NULLS FIRST/LAST ordering.""" return False - def format_grouping_clause(self, expr) -> Tuple[str, tuple]: + def format_grouping_clause(self, expr: "bases.BaseExpression") -> Tuple[str, tuple]: """Format grouping expression (ROLLUP, CUBE, GROUPING SETS).""" operation = expr.operation # Check feature support based on operation type diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_clauses.py b/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_clauses.py index 4f433f819..6bcce11c9 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_clauses.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_clauses.py @@ -12,6 +12,7 @@ from rhosocial.activerecord.backend.expression import ( QueryExpression, Column, + ComparisonPredicate, Literal, FunctionCall, WhereClause, @@ -43,7 +44,7 @@ def where_example(dialect, status: str = "active"): from_=NamedRelationRef(dialect, Table(dialect, "orders")), where=WhereClause( dialect, - condition=Column(dialect, "status") == Literal(dialect, status), + condition=ComparisonPredicate(dialect, "=", Column(dialect, "status"), Literal(dialect, status)), ), ) @@ -72,11 +73,11 @@ def join_example(dialect, user_id: int = 1): left_table=NamedRelationRef(dialect, Table(dialect, "orders"), alias="o"), right_table=NamedRelationRef(dialect, Table(dialect, "users"), alias="u"), join_type="INNER JOIN", - condition=Column(dialect, "o.user_id") == Column(dialect, "u.id"), + condition=ComparisonPredicate(dialect, "=", Column(dialect, "o.user_id"), Column(dialect, "u.id")), ), where=WhereClause( dialect, - condition=Column(dialect, "u.id") == Literal(dialect, user_id), + condition=ComparisonPredicate(dialect, "=", Column(dialect, "u.id"), Literal(dialect, user_id)), ), ) @@ -179,13 +180,13 @@ def compound_example(dialect, user_id: int = 1, status: str = "pending"): left_table=NamedRelationRef(dialect, Table(dialect, "orders"), alias="o"), right_table=NamedRelationRef(dialect, Table(dialect, "users"), alias="u"), join_type="INNER JOIN", - condition=Column(dialect, "o.user_id") == Column(dialect, "u.id"), + condition=ComparisonPredicate(dialect, "=", Column(dialect, "o.user_id"), Column(dialect, "u.id")), ), where=WhereClause( dialect, condition=( - (Column(dialect, "o.user_id") == Literal(dialect, user_id)) - & (Column(dialect, "o.status") == Literal(dialect, status)) + (ComparisonPredicate(dialect, "=", Column(dialect, "o.user_id"), Literal(dialect, user_id))) + & (ComparisonPredicate(dialect, "=", Column(dialect, "o.status"), Literal(dialect, status))) ), ), order_by=OrderByClause( diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_dml.py b/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_dml.py index 7a4672f78..ed123318d 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_dml.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_dml.py @@ -12,6 +12,7 @@ UpdateExpression, DeleteExpression, Column, + ComparisonPredicate, Literal, WhereClause, ReturningClause, @@ -82,7 +83,7 @@ def update_order_status(dialect, order_id: int, new_status: str): assignments={"status": Literal(dialect, new_status)}, where=WhereClause( dialect, - condition=Column(dialect, "id") == Literal(dialect, order_id), + condition=ComparisonPredicate(dialect, "=", Column(dialect, "id"), Literal(dialect, order_id)), ), ) @@ -102,7 +103,7 @@ def cancel_order(dialect, order_id: int): tables=Table(dialect, 'orders'), where=WhereClause( dialect, - condition=Column(dialect, "id") == Literal(dialect, order_id), + condition=ComparisonPredicate(dialect, "=", Column(dialect, "id"), Literal(dialect, order_id)), ), ) @@ -154,6 +155,6 @@ def archive_processed_orders(dialect, status: str = "completed"): tables=Table(dialect, 'orders'), where=WhereClause( dialect, - condition=Column(dialect, "status") == Literal(dialect, status), + condition=ComparisonPredicate(dialect, "=", Column(dialect, "status"), Literal(dialect, status)), ), ) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_expressions.py b/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_expressions.py index f42444975..8cd924145 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_expressions.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_expressions/order_expressions.py @@ -82,7 +82,7 @@ def _column(name: str, type_name: str): # ============================================================ # SECTION: Business Logic (the pattern to learn) # ============================================================ -from rhosocial.activerecord.backend.expression import Column, Literal, QueryExpression +from rhosocial.activerecord.backend.expression import Column, ComparisonPredicate, Literal, QueryExpression from rhosocial.activerecord.backend.expression.sources import NamedRelationRef @@ -92,7 +92,7 @@ def get_order(dialect, order_id: int): dialect, select=[Column(dialect, "id"), Column(dialect, "status"), Column(dialect, "user_id")], from_=NamedRelationRef(dialect, Table(dialect, "orders")), - where=Column(dialect, "id") == Literal(dialect, order_id), + where=ComparisonPredicate(dialect, "=", Column(dialect, "id"), Literal(dialect, order_id)), ) @@ -102,7 +102,7 @@ def check_inventory(dialect, order_id: int): dialect, select=[Column(dialect, "available")], from_=NamedRelationRef(dialect, Table(dialect, "inventory")), - where=Column(dialect, "order_id") == Literal(dialect, order_id), + where=ComparisonPredicate(dialect, "=", Column(dialect, "order_id"), Literal(dialect, order_id)), ) @@ -112,7 +112,7 @@ def reserve_inventory(dialect, order_id: int): dialect, select=[Column(dialect, "id"), Column(dialect, "reserved")], from_=NamedRelationRef(dialect, Table(dialect, "inventory")), - where=Column(dialect, "order_id") == Literal(dialect, order_id), + where=ComparisonPredicate(dialect, "=", Column(dialect, "order_id"), Literal(dialect, order_id)), ) @@ -122,7 +122,7 @@ def send_notification(dialect, user_id: int, type: str): dialect, select=[Column(dialect, "id")], from_=NamedRelationRef(dialect, Table(dialect, "notifications")), - where=Column(dialect, "user_id") == Literal(dialect, user_id), + where=ComparisonPredicate(dialect, "=", Column(dialect, "user_id"), Literal(dialect, user_id)), ) @@ -132,7 +132,7 @@ def process_payment(dialect, order_id: int, amount: float): dialect, select=[Column(dialect, "status"), Column(dialect, "transaction_id")], from_=NamedRelationRef(dialect, Table(dialect, "payments")), - where=Column(dialect, "order_id") == Literal(dialect, order_id), + where=ComparisonPredicate(dialect, "=", Column(dialect, "order_id"), Literal(dialect, order_id)), ) @@ -142,7 +142,7 @@ def release_inventory(dialect, order_id: int): dialect, select=[Column(dialect, "id")], from_=NamedRelationRef(dialect, Table(dialect, "inventory")), - where=Column(dialect, "order_id") == Literal(dialect, order_id), + where=ComparisonPredicate(dialect, "=", Column(dialect, "order_id"), Literal(dialect, order_id)), ) @@ -152,7 +152,7 @@ def create_order_record(dialect, order_id: int, user_id: int, amount: float): dialect, select=[Column(dialect, "id"), Column(dialect, "created_at")], from_=NamedRelationRef(dialect, Table(dialect, "order_records")), - where=Column(dialect, "order_id") == Literal(dialect, order_id), + where=ComparisonPredicate(dialect, "=", Column(dialect, "order_id"), Literal(dialect, order_id)), ) @@ -162,7 +162,7 @@ def confirm_inventory(dialect, order_id: int): dialect, select=[Column(dialect, "id")], from_=NamedRelationRef(dialect, Table(dialect, "inventory")), - where=Column(dialect, "order_id") == Literal(dialect, order_id), + where=ComparisonPredicate(dialect, "=", Column(dialect, "order_id"), Literal(dialect, order_id)), ) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_procedure_graph/q.py b/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_procedure_graph/q.py index 72332066b..39733ad31 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_procedure_graph/q.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/examples/named_procedure_graph/q.py @@ -9,6 +9,7 @@ from rhosocial.activerecord.backend.expression import ( QueryExpression, Column, + ComparisonPredicate, FunctionCall, WhereClause, Literal, @@ -34,7 +35,10 @@ def agg_sales(dialect, month: str = ""): FunctionCall(dialect, "COUNT", Column(dialect, "id")).as_("count"), ], from_=NamedRelationRef(dialect, Table(dialect, "sales")), - where=WhereClause(dialect, condition=Column(dialect, "month") == Literal(dialect, month)), + where=WhereClause( + dialect, + condition=ComparisonPredicate(dialect, "=", Column(dialect, "month"), Literal(dialect, month)), + ), ) @@ -55,7 +59,10 @@ def agg_refunds(dialect, month: str = ""): FunctionCall(dialect, "COUNT", Column(dialect, "id")).as_("count"), ], from_=NamedRelationRef(dialect, Table(dialect, "refunds")), - where=WhereClause(dialect, condition=Column(dialect, "month") == Literal(dialect, month)), + where=WhereClause( + dialect, + condition=ComparisonPredicate(dialect, "=", Column(dialect, "month"), Literal(dialect, month)), + ), ) @@ -109,6 +116,6 @@ def check_threshold(dialect, threshold: int = 1000): select=[Literal(dialect, 1)], where=WhereClause( dialect, - condition=Column(dialect, "total") > Literal(dialect, threshold), + condition=ComparisonPredicate(dialect, ">", Column(dialect, "total"), Literal(dialect, threshold)), ), ) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/examples/query/cte.py b/src/rhosocial/activerecord/backend/impl/sqlite/examples/query/cte.py index 3246d6aff..5e56d9b10 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/examples/query/cte.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/examples/query/cte.py @@ -19,6 +19,7 @@ CreateTableExpression, InsertExpression, ValuesSource, + BinaryArithmeticExpression, ) from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.expression.core import Literal, Column # noqa: E402 @@ -162,7 +163,7 @@ Column(dialect, "name", "e"), Column(dialect, "manager_id", "e"), Column(dialect, "department", "e"), - Column(dialect, "level", "oc") + Literal(dialect, 1), + BinaryArithmeticExpression(dialect, "+", Column(dialect, "level", "oc"), Literal(dialect, 1)), ], from_=join_expr, ) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/examples/query/window.py b/src/rhosocial/activerecord/backend/impl/sqlite/examples/query/window.py index 52519e34c..75deea50d 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/examples/query/window.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/examples/query/window.py @@ -78,11 +78,11 @@ from rhosocial.activerecord.backend.expression import ( QueryExpression, Column, + FunctionCall, OrderByClause, ) from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.expression.advanced_functions import ( # noqa: E402 - WindowFunctionCall, WindowSpecification, ) from .....expression.objects import Table @@ -93,9 +93,9 @@ order_by="sale_date", ) -window_func = WindowFunctionCall( +window_func = FunctionCall( dialect, - function_name="ROW_NUMBER", + "ROW_NUMBER", window_spec=window_spec, alias="row_num", ) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/expression/types.py b/src/rhosocial/activerecord/backend/impl/sqlite/expression/types.py index e6ed1ec81..cea5a9d51 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/expression/types.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/expression/types.py @@ -14,16 +14,26 @@ Each class carries a ``sqlite_``-prefixed generic ``name`` (the protocol dispatch key), so the backend's concrete type family is distinguishable from the core type family by name alone. + +Why four of the five derive from a core type and one does not +------------------------------------------------------------- +``INTEGER``, ``TEXT``, ``REAL`` and ``BLOB`` each name one core concept, so +those classes derive from it. ``NUMERIC`` does not: SQLite's own affinity +rules map ``DECIMAL``, ``NUMERIC``, ``BOOLEAN``, ``DATE``, ``DATETIME``, +``TIMESTAMP`` *and* ``TIME`` onto it, so the affinity spans the numeric, +boolean and temporal families at once and there is no single core type it +could honestly be. That is a deliberate placement, not an omission — the +schema differ compares two introspected columns and both arrive as this +class, so the collapse is where it belongs. """ from __future__ import annotations -from typing import Set - from rhosocial.activerecord.backend.expression.types import ( BlobType, DataType, IntegerType, + RealType, TextType, ) @@ -38,10 +48,6 @@ class SQLiteIntegerType(IntegerType): name = "sqlite_integer" - @classmethod - def synonyms(cls) -> Set[str]: - return {'IntegerType', 'IntType'} - class SQLiteTextType(TextType): """SQLite TEXT — the only string affinity. @@ -61,12 +67,8 @@ def __init__(self, dialect=None, length: int | None = None, super().__init__(dialect) self.length = length - @classmethod - def synonyms(cls) -> Set[str]: - return {'TextType', 'VarCharType', 'CharType'} - -class SQLiteRealType(DataType): +class SQLiteRealType(RealType): """SQLite REAL — affinity for floating-point types. Matches REAL, FLOAT, DOUBLE, and DOUBLE PRECISION in SQLite's @@ -82,19 +84,17 @@ def __init__(self, dialect=None, precision: int | None = None, super().__init__(dialect) self.precision = precision - def _type_params(self) -> tuple: - return (self.precision,) - - @classmethod - def synonyms(cls) -> Set[str]: - return {'RealType', 'FloatType', 'DoubleType'} - + PARAMETERS = ("precision",) class SQLiteNumericType(DataType): - """SQLite NUMERIC — affinity for DECIMAL / BOOLEAN / DATE / etc. - - SQLite maps ``DECIMAL``, ``NUMERIC``, ``BOOLEAN``, ``DATE``, - ``DATETIME``, ``TIMESTAMP`` and ``TIME`` to this affinity. + """SQLite NUMERIC — the affinity that spans three type families. + + SQLite's documented affinity rules map ``DECIMAL``, ``NUMERIC``, + ``BOOLEAN``, ``DATE``, ``DATETIME``, ``TIMESTAMP`` and ``TIME`` all to + NUMERIC affinity. A ``BOOLEAN`` column introspects as this class but is + not a decimal, and a ``DATE`` column introspects as this class but is not + a date either, so this class is deliberately **not** derived from any + single core type. """ name = "sqlite_numeric" @@ -109,15 +109,7 @@ def __init__(self, dialect=None, precision: int | None = None, self.precision = precision self.scale = scale - def _type_params(self) -> tuple: - return (self.precision, self.scale) - - @classmethod - def synonyms(cls) -> Set[str]: - return {'DecimalType', 'NumericType', 'BooleanType', - 'DateType', 'DateTimeType', 'TimestampType', - 'TimestampTzType', 'TimeType', 'TimeTzType'} - + PARAMETERS = ("precision", "scale",) class SQLiteBlobType(BlobType): """SQLite BLOB — affinity for binary data. @@ -127,7 +119,3 @@ class SQLiteBlobType(BlobType): """ name = "sqlite_blob" - - @classmethod - def synonyms(cls) -> Set[str]: - return {'BlobType'} diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/functions/geopoly.py b/src/rhosocial/activerecord/backend/impl/sqlite/functions/geopoly.py index 4f3d2506e..386e893f2 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/functions/geopoly.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/functions/geopoly.py @@ -22,29 +22,13 @@ from ..dialect import SQLiteDialect -def _convert_to_expression( - dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], - handle_numeric_literals: bool = True, -) -> "bases.BaseExpression": - """Convert an input value to an appropriate BaseExpression.""" - if isinstance(expr, bases.BaseExpression): - return expr - elif isinstance(expr, (int, float)): - if handle_numeric_literals: - return core.Literal(dialect, expr) - return core.Column(dialect, str(expr)) - elif isinstance(expr, str): - return core.Literal(dialect, expr) - else: - return core.Column(dialect, expr) def geopoly_contains( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], - x: Union[float, "bases.BaseExpression"], - y: Union[float, "bases.BaseExpression"], + polygon: "bases.BaseExpression", + x: "bases.BaseExpression", + y: "bases.BaseExpression", ) -> "core.FunctionCall": """Check if a point is inside a polygon. @@ -65,15 +49,15 @@ def geopoly_contains( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) - x_expr = _convert_to_expression(dialect, x) - y_expr = _convert_to_expression(dialect, y) + poly_expr = polygon + x_expr = x + y_expr = y return core.FunctionCall(dialect, "geopoly_contains", poly_expr, x_expr, y_expr) def geopoly_within( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Check if a polygon is entirely within another polygon. @@ -92,14 +76,14 @@ def geopoly_within( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_within", poly_expr) def geopoly_overlap( dialect: "SQLiteDialect", - polygon1: Union[str, "bases.BaseExpression"], - polygon2: Union[str, "bases.BaseExpression"], + polygon1: "bases.BaseExpression", + polygon2: "bases.BaseExpression", ) -> "core.FunctionCall": """Check if two polygons overlap. @@ -118,14 +102,14 @@ def geopoly_overlap( Version: SQLite 3.26.0+ """ - poly1_expr = _convert_to_expression(dialect, polygon1) - poly2_expr = _convert_to_expression(dialect, polygon2) + poly1_expr = polygon1 + poly2_expr = polygon2 return core.FunctionCall(dialect, "geopoly_overlap", poly1_expr, poly2_expr) def geopoly_area( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Calculate the area of a polygon. @@ -143,13 +127,13 @@ def geopoly_area( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_area", poly_expr) def geopoly_x( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Get the X coordinate of a vertex of the polygon. @@ -162,13 +146,13 @@ def geopoly_x( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_x", poly_expr) def geopoly_y( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Get the Y coordinate of a vertex of the polygon. @@ -181,13 +165,13 @@ def geopoly_y( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_y", poly_expr) def geopoly_centerpoint( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Calculate the center point of a polygon. @@ -206,13 +190,13 @@ def geopoly_centerpoint( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_centerpoint", poly_expr) def geopoly_json( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Convert a BLOB to a JSON polygon definition. @@ -231,13 +215,13 @@ def geopoly_json( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_json", poly_expr) def geopoly_blob( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Convert a JSON polygon definition to BLOB. @@ -255,13 +239,13 @@ def geopoly_blob( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_blob", poly_expr) def geopoly_debug( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Return text rendering of a polygon for debugging. @@ -279,18 +263,18 @@ def geopoly_debug( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_debug", poly_expr) def geopoly_svg( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", *, - xscale: Optional[Union[float, "bases.BaseExpression"]] = None, - yscale: Optional[Union[float, "bases.BaseExpression"]] = None, - xoff: Optional[Union[float, "bases.BaseExpression"]] = None, - yoff: Optional[Union[float, "bases.BaseExpression"]] = None, + xscale: Optional["bases.BaseExpression"] = None, + yscale: Optional["bases.BaseExpression"] = None, + xoff: Optional["bases.BaseExpression"] = None, + yoff: Optional["bases.BaseExpression"] = None, ) -> "core.FunctionCall": """Convert a polygon to SVG format. @@ -314,22 +298,22 @@ def geopoly_svg( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon args = [poly_expr] if xscale is not None: - args.append(_convert_to_expression(dialect, xscale)) + args.append(xscale) if yscale is not None: - args.append(_convert_to_expression(dialect, yscale)) + args.append(yscale) if xoff is not None: - args.append(_convert_to_expression(dialect, xoff)) + args.append(xoff) if yoff is not None: - args.append(_convert_to_expression(dialect, yoff)) + args.append(yoff) return core.FunctionCall(dialect, "geopoly_svg", *args) def geopoly_bbox( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Calculate the bounding box of a polygon. @@ -348,13 +332,13 @@ def geopoly_bbox( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_bbox", poly_expr) def geopoly_group_bbox( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Calculate the bounding box of a group of polygons (aggregate). @@ -375,15 +359,15 @@ def geopoly_group_bbox( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_group_bbox", poly_expr) def geopoly_contains_point( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], - x: Union[float, "bases.BaseExpression"], - y: Union[float, "bases.BaseExpression"], + polygon: "bases.BaseExpression", + x: "bases.BaseExpression", + y: "bases.BaseExpression", ) -> "core.FunctionCall": """Check if a point is inside a polygon. @@ -403,21 +387,21 @@ def geopoly_contains_point( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) - x_expr = _convert_to_expression(dialect, x) - y_expr = _convert_to_expression(dialect, y) + poly_expr = polygon + x_expr = x + y_expr = y return core.FunctionCall(dialect, "geopoly_contains_point", poly_expr, x_expr, y_expr) def geopoly_xform( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], - a: Union[float, "bases.BaseExpression"], - b: Union[float, "bases.BaseExpression"], - c: Union[float, "bases.BaseExpression"], - d: Union[float, "bases.BaseExpression"], - e: Union[float, "bases.BaseExpression"], - f: Union[float, "bases.BaseExpression"], + polygon: "bases.BaseExpression", + a: "bases.BaseExpression", + b: "bases.BaseExpression", + c: "bases.BaseExpression", + d: "bases.BaseExpression", + e: "bases.BaseExpression", + f: "bases.BaseExpression", ) -> "core.FunctionCall": """Transform a polygon using an affine transformation. @@ -443,25 +427,25 @@ def geopoly_xform( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall( dialect, "geopoly_xform", poly_expr, - _convert_to_expression(dialect, a), - _convert_to_expression(dialect, b), - _convert_to_expression(dialect, c), - _convert_to_expression(dialect, d), - _convert_to_expression(dialect, e), - _convert_to_expression(dialect, f), + a, + b, + c, + d, + e, + f, ) def geopoly_regular( dialect: "SQLiteDialect", - x: Union[float, "bases.BaseExpression"], - y: Union[float, "bases.BaseExpression"], - radius: Union[float, "bases.BaseExpression"], + x: "bases.BaseExpression", + y: "bases.BaseExpression", + radius: "bases.BaseExpression", n: Union[int, "bases.BaseExpression"], ) -> "core.FunctionCall": """Create a regular polygon. @@ -484,16 +468,16 @@ def geopoly_regular( Version: SQLite 3.26.0+ """ - x_expr = _convert_to_expression(dialect, x) - y_expr = _convert_to_expression(dialect, y) - r_expr = _convert_to_expression(dialect, radius) - n_expr = _convert_to_expression(dialect, n) + x_expr = x + y_expr = y + r_expr = r + n_expr = n return core.FunctionCall(dialect, "geopoly_regular", x_expr, y_expr, r_expr, n_expr) def geopoly_ccw( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Reorder polygon vertices to counter-clockwise order. @@ -511,13 +495,13 @@ def geopoly_ccw( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_ccw", poly_expr) def geopoly_cw( dialect: "SQLiteDialect", - polygon: Union[str, "bases.BaseExpression"], + polygon: "bases.BaseExpression", ) -> "core.FunctionCall": """Reorder polygon vertices to clockwise order. @@ -535,5 +519,5 @@ def geopoly_cw( Version: SQLite 3.26.0+ """ - poly_expr = _convert_to_expression(dialect, polygon) + poly_expr = polygon return core.FunctionCall(dialect, "geopoly_cw", poly_expr) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/functions/json.py b/src/rhosocial/activerecord/backend/impl/sqlite/functions/json.py index b4e0f08a4..7ee8d12d7 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/functions/json.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/functions/json.py @@ -21,39 +21,9 @@ from ..dialect import SQLiteDialect -def _convert_to_expression( - dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], - handle_numeric_literals: bool = True, -) -> "bases.BaseExpression": - """ - Helper function to convert an input value to an appropriate BaseExpression. - - Args: - dialect: The SQL dialect instance - expr: The expression to convert - handle_numeric_literals: Whether to treat numeric values as literals - - Returns: - A BaseExpression instance - """ - if isinstance(expr, bases.BaseExpression): - return expr - elif isinstance(expr, (int, float)): - # Numeric values: convert to Literal if handle_numeric_literals is True - if handle_numeric_literals: - return core.Literal(dialect, expr) - return core.Column(dialect, str(expr)) - elif isinstance(expr, str): - # Strings: always convert to Literal for JSON functions - return core.Literal(dialect, expr) - else: - return core.Column(dialect, expr) - - def json( dialect: "SQLiteDialect", - value: Union[str, "bases.BaseExpression"], + value: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a JSON function call. @@ -73,7 +43,7 @@ def json( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, value) + val_expr = value return core.FunctionCall(dialect, "JSON", val_expr) @@ -136,9 +106,9 @@ def json_object( def json_extract( dialect: "SQLiteDialect", - json_doc: Union[str, "bases.BaseExpression"], - path: str, - *paths: str, + json_doc: "bases.BaseExpression", + path: "bases.BaseExpression", + *paths: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a JSON_EXTRACT function call. @@ -160,17 +130,17 @@ def json_extract( Version: SQLite 3.38.0+ """ - doc_expr = _convert_to_expression(dialect, json_doc) - path_expr = core.Literal(dialect, path) + doc_expr = json_doc + path_expr = path args = [doc_expr, path_expr] for p in paths: - args.append(core.Literal(dialect, p)) + args.append(p) return core.FunctionCall(dialect, "JSON_EXTRACT", *args) def json_type( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], + json_val: "bases.BaseExpression", path: Optional[str] = None, ) -> "core.FunctionCall": """ @@ -191,16 +161,16 @@ def json_type( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, json_val) + val_expr = json_val if path is not None: - path_expr = core.Literal(dialect, path) + path_expr = path return core.FunctionCall(dialect, "JSON_TYPE", val_expr, path_expr) return core.FunctionCall(dialect, "JSON_TYPE", val_expr) def json_valid( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], + json_val: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a JSON_VALID function call. @@ -219,13 +189,13 @@ def json_valid( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, json_val) + val_expr = json_val return core.FunctionCall(dialect, "JSON_VALID", val_expr) def json_quote( dialect: "SQLiteDialect", - value: Union[str, "bases.BaseExpression"], + value: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a JSON_QUOTE function call. @@ -244,15 +214,15 @@ def json_quote( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, value) + val_expr = value return core.FunctionCall(dialect, "JSON_QUOTE", val_expr) def json_remove( dialect: "SQLiteDialect", - json_doc: Union[str, "bases.BaseExpression"], - path: str, - *paths: str, + json_doc: "bases.BaseExpression", + path: "bases.BaseExpression", + *paths: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a JSON_REMOVE function call. @@ -273,18 +243,18 @@ def json_remove( Version: SQLite 3.38.0+ """ - doc_expr = _convert_to_expression(dialect, json_doc) - path_expr = core.Literal(dialect, path) + doc_expr = json_doc + path_expr = path args = [doc_expr, path_expr] for p in paths: - args.append(core.Literal(dialect, p)) + args.append(p) return core.FunctionCall(dialect, "JSON_REMOVE", *args) def json_set( dialect: "SQLiteDialect", - json_doc: Union[str, "bases.BaseExpression"], - path: str, + json_doc: "bases.BaseExpression", + path: "bases.BaseExpression", value: Any, *path_values: Any, ) -> "core.FunctionCall": @@ -308,8 +278,8 @@ def json_set( Version: SQLite 3.38.0+ """ - doc_expr = _convert_to_expression(dialect, json_doc) - path_expr = core.Literal(dialect, path) + doc_expr = json_doc + path_expr = path val_expr = core.Literal(dialect, value) if not isinstance(value, bases.BaseExpression) else value args = [doc_expr, path_expr, val_expr] for i in range(0, len(path_values), 2): @@ -322,8 +292,8 @@ def json_set( def json_insert( dialect: "SQLiteDialect", - json_doc: Union[str, "bases.BaseExpression"], - path: str, + json_doc: "bases.BaseExpression", + path: "bases.BaseExpression", value: Any, *path_values: Any, ) -> "core.FunctionCall": @@ -347,8 +317,8 @@ def json_insert( Version: SQLite 3.38.0+ """ - doc_expr = _convert_to_expression(dialect, json_doc) - path_expr = core.Literal(dialect, path) + doc_expr = json_doc + path_expr = path val_expr = core.Literal(dialect, value) if not isinstance(value, bases.BaseExpression) else value args = [doc_expr, path_expr, val_expr] for i in range(0, len(path_values), 2): @@ -361,8 +331,8 @@ def json_insert( def json_replace( dialect: "SQLiteDialect", - json_doc: Union[str, "bases.BaseExpression"], - path: str, + json_doc: "bases.BaseExpression", + path: "bases.BaseExpression", value: Any, *path_values: Any, ) -> "core.FunctionCall": @@ -386,8 +356,8 @@ def json_replace( Version: SQLite 3.38.0+ """ - doc_expr = _convert_to_expression(dialect, json_doc) - path_expr = core.Literal(dialect, path) + doc_expr = json_doc + path_expr = path val_expr = core.Literal(dialect, value) if not isinstance(value, bases.BaseExpression) else value args = [doc_expr, path_expr, val_expr] for i in range(0, len(path_values), 2): @@ -400,8 +370,8 @@ def json_replace( def json_patch( dialect: "SQLiteDialect", - json_doc: Union[str, "bases.BaseExpression"], - patch: Union[str, "bases.BaseExpression"], + json_doc: "bases.BaseExpression", + patch: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a JSON_PATCH function call. @@ -421,14 +391,14 @@ def json_patch( Version: SQLite 3.38.0+ """ - doc_expr = _convert_to_expression(dialect, json_doc) - patch_expr = _convert_to_expression(dialect, patch) + doc_expr = json_doc + patch_expr = patch return core.FunctionCall(dialect, "JSON_PATCH", doc_expr, patch_expr) def json_array_length( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], + json_val: "bases.BaseExpression", path: Optional[str] = None, ) -> "core.FunctionCall": """ @@ -450,16 +420,16 @@ def json_array_length( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, json_val) + val_expr = json_val if path is not None: - path_expr = core.Literal(dialect, path) + path_expr = path return core.FunctionCall(dialect, "JSON_ARRAY_LENGTH", val_expr, path_expr) return core.FunctionCall(dialect, "JSON_ARRAY_LENGTH", val_expr) def json_array_unpack( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], + json_val: "bases.BaseExpression", path: Optional[str] = None, ) -> "core.FunctionCall": """ @@ -481,9 +451,9 @@ def json_array_unpack( Version: SQLite 3.38.0+ """ # SQLite doesn't have JSON_UNPACK, this would typically be used with json_each - val_expr = _convert_to_expression(dialect, json_val) + val_expr = json_val if path is not None: - path_expr = core.Literal(dialect, path) + path_expr = path return core.FunctionCall(dialect, "JSON_ARRAY_LENGTH", val_expr, path_expr) return core.FunctionCall(dialect, "JSON_ARRAY_LENGTH", val_expr) @@ -518,8 +488,8 @@ def json_object_pack( def json_object_retrieve( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], - path: str, + json_val: "bases.BaseExpression", + path: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a JSON_EXTRACT function call for retrieving a single value. @@ -539,14 +509,14 @@ def json_object_retrieve( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, json_val) - path_expr = core.Literal(dialect, path) + val_expr = json_val + path_expr = path return core.FunctionCall(dialect, "JSON_EXTRACT", val_expr, path_expr) def json_object_length( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], + json_val: "bases.BaseExpression", path: Optional[str] = None, ) -> "core.FunctionCall": """ @@ -567,16 +537,16 @@ def json_object_length( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, json_val) + val_expr = json_val if path is not None: - path_expr = core.Literal(dialect, path) + path_expr = path return core.FunctionCall(dialect, "JSON_OBJECT_LENGTH", val_expr, path_expr) return core.FunctionCall(dialect, "JSON_OBJECT_LENGTH", val_expr) def json_object_keys( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], + json_val: "bases.BaseExpression", path: Optional[str] = None, ) -> "core.FunctionCall": """ @@ -597,16 +567,16 @@ def json_object_keys( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, json_val) + val_expr = json_val if path is not None: - path_expr = core.Literal(dialect, path) + path_expr = path return core.FunctionCall(dialect, "JSON_OBJECT_KEYS", val_expr, path_expr) return core.FunctionCall(dialect, "JSON_OBJECT_KEYS", val_expr) def json_tree( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], + json_val: "bases.BaseExpression", path: Optional[str] = None, ) -> "core.FunctionCall": """ @@ -628,16 +598,16 @@ def json_tree( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, json_val) + val_expr = json_val if path is not None: - path_expr = core.Literal(dialect, path) + path_expr = path return core.FunctionCall(dialect, "JSON_TREE", val_expr, path_expr) return core.FunctionCall(dialect, "JSON_TREE", val_expr) def json_each( dialect: "SQLiteDialect", - json_val: Union[str, "bases.BaseExpression"], + json_val: "bases.BaseExpression", path: Optional[str] = None, ) -> "core.FunctionCall": """Creates a JSON_EACH function call. @@ -659,16 +629,16 @@ def json_each( Version: SQLite 3.38.0+ """ - val_expr = _convert_to_expression(dialect, json_val) + val_expr = json_val if path is not None: - path_expr = core.Literal(dialect, path) + path_expr = path return core.FunctionCall(dialect, "JSON_EACH", val_expr, path_expr) return core.FunctionCall(dialect, "JSON_EACH", val_expr) def json_array_insert( dialect: "SQLiteDialect", - json_array: Union[str, "bases.BaseExpression"], + json_array: "bases.BaseExpression", value: Any, position: Optional[int] = None, ) -> "core.FunctionCall": @@ -695,7 +665,7 @@ def json_array_insert( Version: SQLite 3.53.0+ """ - arr_expr = _convert_to_expression(dialect, json_array) + arr_expr = json_array val_expr = core.Literal(dialect, value) if not isinstance(value, bases.BaseExpression) else value if position is not None: @@ -707,7 +677,7 @@ def json_array_insert( def jsonb_array_insert( dialect: "SQLiteDialect", - jsonb_array: Union[str, "bases.BaseExpression"], + jsonb_array: "bases.BaseExpression", value: Any, position: Optional[int] = None, ) -> "core.FunctionCall": @@ -734,7 +704,7 @@ def jsonb_array_insert( Version: SQLite 3.53.0+ """ - arr_expr = _convert_to_expression(dialect, jsonb_array) + arr_expr = jsonb_array val_expr = core.Literal(dialect, value) if not isinstance(value, bases.BaseExpression) else value if position is not None: diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/functions/math_enhanced.py b/src/rhosocial/activerecord/backend/impl/sqlite/functions/math_enhanced.py index 82fe9a712..05d479a41 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/functions/math_enhanced.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/functions/math_enhanced.py @@ -16,38 +16,9 @@ from rhosocial.activerecord.backend.dialect import SQLDialectBase -def _convert_to_expression( - dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], -) -> "bases.BaseExpression": - """ - Helper function to convert an input value to an appropriate BaseExpression. - - Args: - dialect: The SQL dialect instance - expr: The expression to convert - - Returns: - A BaseExpression instance - """ - if isinstance(expr, bases.BaseExpression): - return expr - elif isinstance(expr, (int, float)): - return core.Literal(dialect, expr) - elif isinstance(expr, str): - # Try to parse as number first - try: - return core.Literal(dialect, float(expr) if "." in expr else int(expr)) - except ValueError: - # Not a number, treat as column name - return core.Column(dialect, expr) - else: - return core.Column(dialect, expr) - - def round_( dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], + expr: "bases.BaseExpression", precision: int = 0, ) -> "core.FunctionCall": """ @@ -67,15 +38,15 @@ def round_( Returns: A FunctionCall instance representing the ROUND function """ - target_expr = _convert_to_expression(dialect, expr) + target_expr = expr precision_expr = core.Literal(dialect, precision) return core.FunctionCall(dialect, "ROUND", target_expr, precision_expr) def pow( dialect: "SQLDialectBase", - base: Union[str, "bases.BaseExpression"], - exponent: Union[str, "bases.BaseExpression"], + base: "bases.BaseExpression", + exponent: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a POW function call. @@ -94,15 +65,15 @@ def pow( Returns: A FunctionCall instance representing the POW function """ - base_expr = _convert_to_expression(dialect, base) - exp_expr = _convert_to_expression(dialect, exponent) + base_expr = base + exp_expr = exponent return core.FunctionCall(dialect, "POW", base_expr, exp_expr) def power( dialect: "SQLDialectBase", - base: Union[str, "bases.BaseExpression"], - exponent: Union[str, "bases.BaseExpression"], + base: "bases.BaseExpression", + exponent: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a POWER function call (alias for POW). @@ -121,14 +92,14 @@ def power( Returns: A FunctionCall instance representing the POWER function """ - base_expr = _convert_to_expression(dialect, base) - exp_expr = _convert_to_expression(dialect, exponent) + base_expr = base + exp_expr = exponent return core.FunctionCall(dialect, "POWER", base_expr, exp_expr) def sqrt( dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], + expr: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a SQRT function call. @@ -146,14 +117,14 @@ def sqrt( Returns: A FunctionCall instance representing the SQRT function """ - target_expr = _convert_to_expression(dialect, expr) + target_expr = expr return core.FunctionCall(dialect, "SQRT", target_expr) def mod( dialect: "SQLDialectBase", - dividend: Union[str, "bases.BaseExpression"], - divisor: Union[str, "bases.BaseExpression"], + dividend: "bases.BaseExpression", + divisor: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a MOD function call. @@ -172,14 +143,14 @@ def mod( Returns: A FunctionCall instance representing the MOD function """ - dividend_expr = _convert_to_expression(dialect, dividend) - divisor_expr = _convert_to_expression(dialect, divisor) + dividend_expr = dividend + divisor_expr = divisor return core.FunctionCall(dialect, "MOD", dividend_expr, divisor_expr) def ceil( dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], + expr: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a CEIL function call (SQLite 3.44.0+). @@ -197,13 +168,13 @@ def ceil( Returns: A FunctionCall instance representing the CEIL function """ - target_expr = _convert_to_expression(dialect, expr) + target_expr = expr return core.FunctionCall(dialect, "CEIL", target_expr) def floor( dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], + expr: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a FLOOR function call (SQLite 3.44.0+). @@ -221,13 +192,13 @@ def floor( Returns: A FunctionCall instance representing the FLOOR function """ - target_expr = _convert_to_expression(dialect, expr) + target_expr = expr return core.FunctionCall(dialect, "FLOOR", target_expr) def trunc( dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], + expr: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a TRUNC function call. @@ -245,15 +216,15 @@ def trunc( Returns: A FunctionCall instance representing the TRUNC function """ - target_expr = _convert_to_expression(dialect, expr) + target_expr = expr return core.FunctionCall(dialect, "TRUNC", target_expr) def max_( dialect: "SQLDialectBase", - expr1: Union[str, "bases.BaseExpression"], - expr2: Union[str, "bases.BaseExpression"], - *more: Union[str, "bases.BaseExpression"], + expr1: "bases.BaseExpression", + expr2: "bases.BaseExpression", + *more: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a MAX function call. @@ -273,17 +244,17 @@ def max_( Returns: A FunctionCall instance representing the MAX function """ - exprs = [_convert_to_expression(dialect, expr1), _convert_to_expression(dialect, expr2)] + exprs = [expr1, expr2] for m in more: - exprs.append(_convert_to_expression(dialect, m)) + exprs.append(m) return core.FunctionCall(dialect, "MAX", *exprs) def min_( dialect: "SQLDialectBase", - expr1: Union[str, "bases.BaseExpression"], - expr2: Union[str, "bases.BaseExpression"], - *more: Union[str, "bases.BaseExpression"], + expr1: "bases.BaseExpression", + expr2: "bases.BaseExpression", + *more: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates a MIN function call. @@ -303,15 +274,15 @@ def min_( Returns: A FunctionCall instance representing the MIN function """ - exprs = [_convert_to_expression(dialect, expr1), _convert_to_expression(dialect, expr2)] + exprs = [expr1, expr2] for m in more: - exprs.append(_convert_to_expression(dialect, m)) + exprs.append(m) return core.FunctionCall(dialect, "MIN", *exprs) def avg( dialect: "SQLDialectBase", - expr: Union[str, "bases.BaseExpression"], + expr: "bases.BaseExpression", ) -> "core.FunctionCall": """ Creates an AVG aggregate function call. @@ -328,7 +299,7 @@ def avg( Returns: A FunctionCall instance representing the AVG function """ - target_expr = _convert_to_expression(dialect, expr) + target_expr = expr return core.FunctionCall(dialect, "AVG", target_expr) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/__init__.py b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/__init__.py index 7060b2eab..00e505b35 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/__init__.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/__init__.py @@ -24,6 +24,7 @@ from .rtree import SQLiteRTreeMixin from .geopoly import SQLiteGeopolyMixin from .types import SQLiteTypeSupportMixin +from .column_type import SQLiteColumnTypeMixin __all__ = [ 'SQLiteExtensionMixin', @@ -44,4 +45,5 @@ 'SQLiteRTreeMixin', 'SQLiteGeopolyMixin', 'SQLiteTypeSupportMixin', + 'SQLiteColumnTypeMixin', ] diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/column_type.py b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/column_type.py new file mode 100644 index 000000000..f7956828a --- /dev/null +++ b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/column_type.py @@ -0,0 +1,129 @@ +# src/rhosocial/activerecord/backend/impl/sqlite/mixins/column_type.py +"""SQLite's column-type table: the class each common Python type means here. + +This is the SQLite half of the column-type protocol: the answer for each of +the common Python types the framework defines. + +Why SQLite answers for itself at all +------------------------------------ +SQLite has five storage affinities -- TEXT, INTEGER, REAL, BLOB, NUMERIC -- +and no ``BOOLEAN``, no ``DATE``, no ``UUID``, no ``JSON``, no array. It would +be easy to read that as "SQLite cannot host these column classes" and answer +with nothing, and that would be wrong in the direction this protocol exists to +prevent. The probe (``plan/2026-10-08/suggested-pairing-*.md``, SQLite 3.50.4) +shows the opposite: the *storage* is a convention the value layer converts to +and from, while the *operations* are carried by real SQL that runs. ``dict`` +is a TEXT column the JSON1 functions read; a date is a TEXT column ``strftime`` +and ``julianday`` understand; a boolean is an INTEGER 0/1 column whose +three-valued logic ``IS TRUE`` gets right. Refusing these would throw away a +working pairing because the storage has no native type -- exactly the +conflation the DataType/Column separation forbids. + +The evidence, per entry group (all measured on SQLite 3.50.4) +------------------------------------------------------------- +* **bool** -> :class:`~...column_types.BooleanColumn`. Stored INTEGER 0/1; the + boolean battery passes in full except for rendering-discipline items + (``= 1`` / ``= 0`` literals, which the framework forbids anyway). +* **int / float / decimal.Decimal** -> :class:`~...column_types.IntegerColumn` + / :class:`~...column_types.NumericColumn` / ``NumericColumn``. SQLite has + real INTEGER and REAL, and ``NUMERIC`` is only an *affinity* -- a Decimal + travels as a float and reads back as one. That is a value-layer conversion, + not a missing operation. +* **str / enum.Enum** -> :class:`~...column_types.StringColumn`. TEXT storage; + ``length('Zebra')`` is 5 characters, so the class's ``LENGTH`` is + character-based. An enum is TEXT + ``CHECK``: the probe confirms an illegal + member is rejected with ``CHECK failed``, at the price of lexicographic + rather than declaration-order sorting. ``ilike`` has no SQLite keyword at + all (``near "ILIKE": syntax error``); how case-insensitive matching is + offered is the column layer's decision, not this table's. +* **bytes / bytearray** -> :class:`~...column_types.BinaryColumn`. BLOB + storage; equality, byte length, substring, concatenation and ``hex()`` all + pass. One value-layer caveat: sqlite3 decodes fetched BLOB as UTF-8 and + raises on bytes that are not text. +* **date / time / datetime** -> + :class:`~...column_types.TimestampColumn`. All are TEXT; microseconds survive + in the text form. The arithmetic domain goes through ``julianday``, whose + differences carry ~1 ms of floating-point error, and there are no named time + zones -- documented limits of the backend rather than absent operations. +* **timedelta** -> :class:`~...column_types.NumericColumn`. There is no + interval type in SQLite, so a duration is a number of seconds; the value + layer rejects ``timedelta`` at bind time, hence the converter. +* **uuid.UUID** -> :class:`~...column_types.UUIDColumn`. TEXT substitution; the + class carries no UUID-specific operator anyway, and sqlite3 refuses to bind + a ``uuid.UUID`` object, so a converter writes the canonical string. +* **dict** -> :class:`~...column_types.JSONColumn` (JSON1). Scalar and nested + paths, has-key, array length, validity and whole-document equality all pass; + only binding a ``dict`` fails, and the framework's ``json.dumps`` is the fix. +* **list / tuple / set / frozenset** -> + :class:`~...column_types.JSONColumn`. SQLite has no array type + (``ARRAY[...]`` is a syntax error), so the honest class is the document one: + length, element access via ``$[n]``, containment via ``json_each`` all work. + ``ArrayColumn`` here would offer ``array_length()`` / ``unnest()`` as if a + native array existed. + +The JSON1 build assumption +-------------------------- +Every JSON entry rests on the **JSON1** functions. Since 3.38.0 they are part +of the SQLite build proper; below that they were a compile-time extension, and +the detection already lives on the dialect +(:meth:`~rhosocial.activerecord.backend.impl.sqlite.dialect.SQLiteDialect.supports_json_type`). +This table claims the pairing; the build is the dialect's fact to report when +the JSON operations are consulted. +""" + +import datetime +import decimal +import enum +import uuid +from typing import Any, Dict, Type + +from rhosocial.activerecord.backend.dialect.mixins.column_type import ColumnTypeMixin +from rhosocial.activerecord.backend.expression.column_types import ( + BinaryColumn, + BooleanColumn, + ColumnBase, + TimestampColumn, + IntegerColumn, + JSONColumn, + NumericColumn, + StringColumn, + UUIDColumn, +) + +#: SQLite's full table: ``{common Python type: ColumnBase subclass}``. +#: +#: No entry is ``None``: the probe found a working pairing for all eighteen on +#: 3.50.4, and an entry answered with ``None`` would be a claim that this +#: backend has no column for a value it demonstrably carries. +SQLITE_COLUMN_TYPES: Dict[Any, Type[ColumnBase]] = { + bool: BooleanColumn, + int: IntegerColumn, + float: NumericColumn, + decimal.Decimal: NumericColumn, + str: StringColumn, + bytes: BinaryColumn, + bytearray: BinaryColumn, + datetime.date: TimestampColumn, + datetime.time: TimestampColumn, + datetime.datetime: TimestampColumn, + datetime.timedelta: NumericColumn, + uuid.UUID: UUIDColumn, + dict: JSONColumn, + # No array type exists in SQLite, so the four sequence entries take the + # document column class rather than `ArrayColumn`. + list: JSONColumn, + tuple: JSONColumn, + set: JSONColumn, + frozenset: JSONColumn, + enum.Enum: StringColumn, +} + + +class SQLiteColumnTypeMixin(ColumnTypeMixin): + """SQLite's answer to "which column class does this annotation mean here".""" + + def suggested_column_types(self) -> Dict[Any, Type[ColumnBase]]: + return dict(SQLITE_COLUMN_TYPES) + + +__all__ = ["SQLITE_COLUMN_TYPES", "SQLiteColumnTypeMixin"] diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/ddl_column.py b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/ddl_column.py index ff747180b..ca7bd99e7 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/ddl_column.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/ddl_column.py @@ -5,9 +5,23 @@ This module provides the SQLiteDDLColumnMixin class. """ -from typing import Tuple +from typing import Tuple, TYPE_CHECKING from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError +if TYPE_CHECKING: # pragma: no cover + from rhosocial.activerecord.backend.expression.statements.ddl_alter import ( + AddColumn, + AddIndex, + DropColumn, + DropIndex, + DropTableConstraint, + ) + from rhosocial.activerecord.backend.expression.statements.ddl_table import ( + ColumnConstraint, + ColumnDefinition, + DefaultValueClause, + ) + class SQLiteDDLColumnMixin: """SQLite-specific column constraint and column definition formatting.""" @@ -21,21 +35,21 @@ def supports_drop_column_if_exists(self) -> bool: def supports_drop_constraint_if_exists(self) -> bool: return False - def format_add_index_action(self, action) -> Tuple[str, tuple]: + def format_add_index_action(self, action: "AddIndex") -> Tuple[str, tuple]: raise UnsupportedFeatureError( self.name, "ALTER TABLE ADD INDEX", "SQLite does not support ALTER TABLE ADD INDEX. Use CREATE INDEX directly.", ) - def format_drop_index_action(self, action) -> Tuple[str, tuple]: + def format_drop_index_action(self, action: "DropIndex") -> Tuple[str, tuple]: raise UnsupportedFeatureError( self.name, "ALTER TABLE DROP INDEX", "SQLite does not support ALTER TABLE DROP INDEX. Use DROP INDEX directly.", ) - def format_add_column_action(self, action) -> Tuple[str, tuple]: + def format_add_column_action(self, action: "AddColumn") -> Tuple[str, tuple]: """Format ALTER TABLE ADD COLUMN for SQLite. SQLite supports ``ADD COLUMN`` but **not** the vendor extension @@ -53,7 +67,7 @@ def format_add_column_action(self, action) -> Tuple[str, tuple]: ) return super().format_add_column_action(action) - def format_drop_column_action(self, action) -> Tuple[str, tuple]: + def format_drop_column_action(self, action: "DropColumn") -> Tuple[str, tuple]: """ALTER TABLE DROP COLUMN for SQLite. SQLite (>= 3.35.0) supports plain ``DROP COLUMN`` but **not** the @@ -69,7 +83,7 @@ def format_drop_column_action(self, action) -> Tuple[str, tuple]: ) return super().format_drop_column_action(action) - def format_drop_table_constraint_action(self, action) -> Tuple[str, tuple]: + def format_drop_table_constraint_action(self, action: "DropTableConstraint") -> Tuple[str, tuple]: """ALTER TABLE DROP CONSTRAINT for SQLite. SQLite (>= 3.53.0) supports ``DROP CONSTRAINT`` for NOT NULL and @@ -84,22 +98,22 @@ def format_drop_table_constraint_action(self, action) -> Tuple[str, tuple]: ) return super().format_drop_table_constraint_action(action) - def format_primary_key_constraint(self, constraint) -> Tuple[str, tuple]: + def format_primary_key_constraint(self, constraint: "ColumnConstraint") -> Tuple[str, tuple]: """Format PRIMARY KEY constraint, optionally with AUTOINCREMENT.""" result = " PRIMARY KEY" if constraint.is_auto_increment: result += " AUTOINCREMENT" return result, () - def format_not_null_constraint(self, constraint) -> Tuple[str, tuple]: + def format_not_null_constraint(self, constraint: "ColumnConstraint") -> Tuple[str, tuple]: """Format NOT NULL constraint.""" return " NOT NULL", () - def format_null_constraint(self, constraint) -> Tuple[str, tuple]: + def format_null_constraint(self, constraint: "ColumnConstraint") -> Tuple[str, tuple]: """Format NULL constraint.""" return " NULL", () - def format_column_unique_constraint(self, constraint) -> Tuple[str, tuple]: + def format_column_unique_constraint(self, constraint: "ColumnConstraint") -> Tuple[str, tuple]: """Format a COLUMN-level UNIQUE constraint. NOTE: deliberately named ``..._column_...`` so it cannot shadow the @@ -109,7 +123,7 @@ def format_column_unique_constraint(self, constraint) -> Tuple[str, tuple]: """ return " UNIQUE", () - def format_default_value_clause(self, expr) -> Tuple[str, tuple]: + def format_default_value_clause(self, expr: "DefaultValueClause") -> Tuple[str, tuple]: """Format the value clause of a DEFAULT constraint (SQLite). SQLite does not support parameterized DEFAULT in CREATE TABLE, so @@ -124,7 +138,7 @@ def format_default_value_clause(self, expr) -> Tuple[str, tuple]: return f"{'1' if value else '0'}", () return super().format_default_value_clause(expr) - def format_check_constraint(self, constraint) -> Tuple[str, tuple]: + def format_check_constraint(self, constraint: "ColumnConstraint") -> Tuple[str, tuple]: """Format CHECK constraint.""" if constraint.check_condition is None: return "", () @@ -133,7 +147,7 @@ def format_check_constraint(self, constraint) -> Tuple[str, tuple]: suffix = f" {enforcement}" if enforcement else "" return f" CHECK ({check_sql}){suffix}", check_params - def format_column_fk_constraint(self, constraint) -> Tuple[str, tuple]: + def format_column_fk_constraint(self, constraint: "ColumnConstraint") -> Tuple[str, tuple]: """Format a column-level FOREIGN KEY reference for SQLite.""" from rhosocial.activerecord.backend.expression.statements import ReferentialAction @@ -153,7 +167,7 @@ def format_column_fk_constraint(self, constraint) -> Tuple[str, tuple]: return result, () - def format_column_definition(self, col_def) -> Tuple[str, tuple]: + def format_column_definition(self, col_def: "ColumnDefinition") -> Tuple[str, tuple]: """Format a column definition for SQLite, including generated columns support.""" from rhosocial.activerecord.backend.expression.statements import ColumnConstraintType diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/dml.py b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/dml.py index abf9aff91..0e637fc43 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/dml.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/dml.py @@ -9,6 +9,7 @@ from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError if TYPE_CHECKING: + from ..expression.fts5 import SQLiteFTS5MatchExpression from rhosocial.activerecord.backend.expression.statements import InsertExpression, ReturningClause class SQLiteDMLMixin: @@ -107,7 +108,7 @@ def format_returning_clause(self, clause: "ReturningClause") -> Tuple[str, tuple def format_match_predicate( self, - expr, + expr: "SQLiteFTS5MatchExpression", ) -> Tuple[str, tuple]: """Format full-text search MATCH predicate for FTS5.""" return self.format_fts5_match_expression(expr) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/function.py b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/function.py index ca48099ef..b4bdc8f34 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/function.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/function.py @@ -5,15 +5,31 @@ This module provides the SQLiteFunctionMixin class. """ -from typing import Dict +from typing import Dict, Tuple, TYPE_CHECKING + +if TYPE_CHECKING: # pragma: no cover + from rhosocial.activerecord.backend.expression import bases + from rhosocial.activerecord.backend.expression.advanced_functions import ( + LpadExpression, + RepeatExpression, + RpadExpression, + ) class SQLiteFunctionMixin: """SQLite function version support detection.""" _SQLITE_FUNCTION_VERSIONS = { - "json_extract": ((3, 38, 0), None), - "json_extract_text": ((3, 38, 0), None), + # The JSON1 functions have existed since SQLite 3.9.0 behind a + # compile-time option, and only became core in 3.38.0 -- so a hard + # version floor cannot express their availability: CI runs a 3.35.0 + # server where json_extract executes fine, which is how the wrong + # 3.38.0 floor recorded here was disproved once the render-time gate + # started enforcing it. Availability on an old build depends on how + # SQLite was compiled, not on the version number, so these carry no + # floor and the query surface answers "no constraint recorded". + "json_extract": (None, None), + "json_extract_text": (None, None), "json_build_object": (None, (0, 0, 0)), "json_array_elements": (None, (0, 0, 0)), "json_objectagg": (None, (0, 0, 0)), @@ -118,3 +134,198 @@ def _is_sqlite_function_supported(self, func_name: str) -> bool: return True + #: The min column of ``_SQLITE_FUNCTION_VERSIONS``: the earliest SQLite + #: that knows each gated function. One table, read two ways -- + #: ``supports_functions`` asks it, ``check_function_version`` enforces it, + #: so a floor recorded here cannot be reported and ignored at once. A + #: recorded *ceiling* is not a floor: it says the spelling does not exist + #: on SQLite at all (``json_build_object`` and the other PostgreSQL names + #: the table keeps for the query surface), which is a different question + #: from being too old, and it stays with the query surface. + #: + #: Declared as data rather than as a ``function_version_floor`` override + #: because ``SQLDialectBase`` precedes every mixin in the MRO: a method + #: overriding the base here would be shadowed by it. + function_version_floors = { + func_name: floor + for func_name, (floor, _ceiling) in _SQLITE_FUNCTION_VERSIONS.items() + if floor is not None + } + + # ------------------------------------------------------------------ + # Spellings SQLite writes differently, and the two operations it has to + # emulate (measured 2026-10-09; see the operation-groups matrix). + # ------------------------------------------------------------------ + + def _pad_copies(self, count, pad): + """``REPLACE(HEX(ZEROBLOB(count)), '00', pad)`` -- the pad, repeated. + + ``HEX(ZEROBLOB(n))`` is the hex text of *n* zero bytes, so it holds + *n* two-character ``00`` pairs; replacing each pair with the pad leaves + *n* copies of it. Used by both pad emulations. + """ + from rhosocial.activerecord.backend.expression.core import FunctionCall, Literal + + return FunctionCall( + self, + "REPLACE", + FunctionCall(self, "HEX", FunctionCall(self, "ZEROBLOB", count)), + Literal(self, "00"), + pad, + ) + + def format_repeat_expression(self, expr: "RepeatExpression") -> Tuple[str, tuple]: + """Emulate ``REPEAT``, which SQLite does not have. + + Each ``00`` pair in ``HEX(ZEROBLOB(count))`` is one copy slot, so + replacing them with the string repeats it exactly *count* times -- + verified against REPEAT on PostgreSQL, MySQL, MariaDB and ClickHouse + for 0, 1, 3 and a multi-character input. A negative count never + reaches here: the factory settles it as the empty string first. + """ + from rhosocial.activerecord.backend.expression.core import FunctionCall, Literal + + call = FunctionCall( + self, + "REPLACE", + FunctionCall(self, "HEX", FunctionCall(self, "ZEROBLOB", expr.count)), + Literal(self, "00"), + expr.expr, + alias=expr.alias, + ) + return call.to_sql() + + def format_lpad_expression(self, expr: "LpadExpression") -> Tuple[str, tuple]: + """Emulate ``LPAD``, which SQLite does not have. + + Two branches, because SQLite alone answers "already long enough" and + "too short" with the same ``SUBSTR``: when the string is at least + *length* long the result is its first *length* characters (truncation), + and otherwise the padding is appended on the left and the last + *length* characters are taken -- the padding is exactly *length* copies + long, so the tail it contributes is the whole left-hand side. + """ + from rhosocial.activerecord.backend.expression.advanced_functions import ( + CaseExpression, + ) + from rhosocial.activerecord.backend.expression.core import FunctionCall, Literal + from rhosocial.activerecord.backend.expression.operators import ( + BinaryExpression, + UnaryExpression, + ) + from rhosocial.activerecord.backend.expression.predicates import ( + ComparisonPredicate, + ) + + length_call = FunctionCall(self, "LENGTH", expr.expr) + truncate_branch = FunctionCall( + self, "SUBSTR", expr.expr, Literal(self, 1), expr.length + ) + padded = BinaryExpression(self, "||", self._pad_copies(expr.length, expr.pad), expr.expr) + pad_branch = FunctionCall( + self, "SUBSTR", padded, UnaryExpression(self, "-", expr.length) + ) + case = CaseExpression( + self, + cases=[(ComparisonPredicate(self, "<=", expr.length, length_call), truncate_branch)], + else_result=pad_branch, + alias=expr.alias, + ) + return case.to_sql() + + def format_rpad_expression(self, expr: "RpadExpression") -> Tuple[str, tuple]: + """Emulate ``RPAD``, which SQLite does not have. + + One branch is enough: the padding is appended on the right and the + first *length* characters are taken, which pads when short and + truncates when long. + """ + from rhosocial.activerecord.backend.expression.core import FunctionCall, Literal + from rhosocial.activerecord.backend.expression.operators import BinaryExpression + + padded = BinaryExpression(self, "||", expr.expr, self._pad_copies(expr.length, expr.pad)) + call = FunctionCall( + self, "SUBSTR", padded, Literal(self, 1), expr.length, alias=expr.alias + ) + return call.to_sql() + + #: Names SQLite spells differently. Each is a spelling difference and not a + #: semantic one -- measured 2026-10-09 across the ten backends -- so it is + #: made here rather than at the call site. + _SQLITE_FUNCTION_NAMES = { + "ASCII": "UNICODE", + "STRPOS": "INSTR", + } + + def format_function_call(self, expr: "bases.BaseExpression") -> Tuple[str, tuple]: + """Format a function call, renaming the ones SQLite spells otherwise. + + Renames are the first column; ``POSITION``, ``LEFT``, ``RIGHT`` and the + two-argument ``LOG`` are argument-order differences and are rebuilt + from the same operands. Everything else delegates to the shared + formatter untouched. + + The one subtlety is ``RIGHT``: ``SUBSTR(x, LENGTH(x) - n + 1, n)`` + reads from the end when *n* exceeds the length -- it returns the tail + instead of the whole string -- so the start is clamped with + ``MAX(..., 1)``. Verified against MySQL, MariaDB, ClickHouse and + BigQuery for n = 0, 1, len-1, len, len+1. + """ + import copy + + from rhosocial.activerecord.backend.dialect.mixins.function import ( + FunctionCallMixin, + ) + from rhosocial.activerecord.backend.expression.core import FunctionCall, Literal + from rhosocial.activerecord.backend.expression.operators import BinaryExpression + + name = expr.func_name.upper() + translated = None + if name in self._SQLITE_FUNCTION_NAMES and len(expr.args) >= 1: + translated = copy.copy(expr) + translated.func_name = self._SQLITE_FUNCTION_NAMES[name] + elif name == "TRUNCATE" and len(expr.args) == 2: + # SQLite's TRUNC takes one argument, so a precision cannot be + # passed through: the value is scaled, truncated toward zero and + # scaled back, which is exact for negatives too (truncation is + # symmetric, unlike rounding). + scale = FunctionCall(self, "POW", Literal(self, 10), expr.args[1]) + scaled = BinaryExpression(self, "*", expr.args[0], scale) + return BinaryExpression( + self, "/", FunctionCall(self, "TRUNC", scaled), scale + ).to_sql() + elif name == "TRUNCATE" and len(expr.args) == 1: + translated = copy.copy(expr) + translated.func_name = "TRUNC" + elif name == "POSITION" and len(expr.args) == 2: + # SQLite's INSTR takes the haystack first; the core POSITION spells + # the needle first, which is the standard IN form. + translated = copy.copy(expr) + translated.func_name = "INSTR" + translated.args = [expr.args[1], expr.args[0]] + elif name == "LEFT" and len(expr.args) == 2: + translated = copy.copy(expr) + translated.func_name = "SUBSTR" + translated.args = [expr.args[0], Literal(self, 1), expr.args[1]] + elif name == "RIGHT" and len(expr.args) == 2: + length_call = FunctionCall(self, "LENGTH", expr.args[0]) + start = BinaryExpression( + self, + "+", + BinaryExpression(self, "-", length_call, expr.args[1]), + Literal(self, 1), + ) + translated = copy.copy(expr) + translated.func_name = "SUBSTR" + translated.args = [ + expr.args[0], + FunctionCall(self, "MAX", start, Literal(self, 1)), + expr.args[1], + ] + elif name == "LOG" and len(expr.args) == 2: + translated = copy.copy(expr) + translated.args = [expr.args[1], expr.args[0]] + if translated is not None: + return FunctionCallMixin.format_function_call(self, translated) + return FunctionCallMixin.format_function_call(self, expr) + diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/set_operation.py b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/set_operation.py index a6ff3d799..80b8bd054 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/set_operation.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/set_operation.py @@ -9,7 +9,7 @@ from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError if TYPE_CHECKING: - pass + from rhosocial.activerecord.backend.expression import bases _SUGGESTION_FOR_UPDATE_SET_OP = "SQLite does not support FOR UPDATE clause in set operations (UNION, INTERSECT, EXCEPT)" @@ -17,7 +17,7 @@ class SQLiteSetOperationMixin: """SQLite-specific set operation (UNION, INTERSECT, EXCEPT) formatting.""" - def format_set_operation_expression(self, expr) -> Tuple[str, Tuple]: + def format_set_operation_expression(self, expr: "bases.BaseExpression") -> Tuple[str, Tuple]: """Format set operation expression (UNION, INTERSECT, EXCEPT).""" left = expr.left right = expr.right diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/types.py b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/types.py index d74987141..64cd7aa4a 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/types.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/types.py @@ -6,6 +6,7 @@ import re from typing import Tuple +from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError from rhosocial.activerecord.backend.dialect.mixins.data_type import DataTypeMixin from rhosocial.activerecord.backend.dialect.protocols import DataTypeSupport from rhosocial.activerecord.backend.expression.types import ( @@ -20,11 +21,13 @@ DecimalType, DoubleType, FloatType, - IntType, + IntegerType, IntervalType, JsonBType, JsonType, + RealType, SmallIntType, + TextType, TimeType, TimeTzType, TimestampType, @@ -54,7 +57,115 @@ class SQLiteTypeSupportMixin(DataTypeMixin, DataTypeSupport): to their SQLite representation. """ + def _refuse_unsigned_integer(self, data_type, word: str) -> None: + """Refuse ``unsigned=True``, because SQLite has no unsigned integer. + + The core integer concepts carry signedness as a field rather than as a + class, so ``IntegerType(unsigned=True)`` is constructible and the flag + reaches the formatter. SQLite's honest answer is a refusal: + + * The integer storage class is a signed 8-byte integer -- "whole + numbers between -9223372036854775808 and +9223372036854775807" -- with + no unsigned counterpart anywhere in the five storage classes. + https://sqlite.org/datatype3.html + * SQLite's declared type is only a *recommendation*: the column's + affinity is derived from it, and nothing else in the grammar accepts + an attribute after the type name. There is not even a spelling that + would parse. + + Writing a bare ``INTEGER`` for an unsigned request would create a column + that accepts the negatives the caller declared it would not, and report + success: the same silent data loss as accepting the flag and discarding + it, which is what this replaces. + + Note the affinity collapse these formatters already perform -- every + integer width renders as ``INTEGER`` -- is a different decision and + stays: it is SQLite's documented storage model, and it says nothing + about range. Signedness is not a width, so it cannot collapse that way. + """ + if not getattr(data_type, "unsigned", False): + return + raise UnsupportedFeatureError( + self.name, + f"an unsigned {word} column " + f"(SQLite has no unsigned integer type; INTEGER is a signed 8-byte " + f"integer covering -9223372036854775808..9223372036854775807)", + suggestion=( + "Declare the column signed and enforce the range with a CHECK " + "constraint if negatives must be rejected." + ), + ) + + def _refuse_unsigned_numeric(self, data_type, word: str) -> None: + """Refuse ``unsigned=True`` on a floating-point, single-precision or exact + fixed-point concept, because SQLite has none and has no attribute to + write. + + The same field reaches these four concepts that it reaches the four + integer widths -- ``DecimalType``, ``FloatType``, ``RealType`` and + ``DoubleType`` each carry ``unsigned`` in ``PARAMETERS``, so two + declarations differing only in it are *different columns* as far as the + schema differ is concerned -- and SQLite's answer is the same refusal for + the same two reasons: + + * **The storage has no unsigned counterpart.** SQLite has five storage + classes and they are a closed list: ``INTEGER`` ("whole numbers + between -9223372036854775808 and +9223372036854775807"), ``REAL`` + ("floating point numbers, using an 8-byte IEEE 754 floating-point + number"), ``TEXT``, ``BLOB``, ``NUMERIC``. ``REAL`` is an IEEE 754 + binary64, whose documented range is signed on both sides, and there is + no ``REAL UNSIGNED`` row to select. A ``DECIMAL`` column gets the + ``NUMERIC`` affinity and is stored as an ``INTEGER`` or a ``REAL`` + depending on the value, so it has no unsigned form either. + https://sqlite.org/datatype3.html + * **There is not even a spelling that would parse.** SQLite's + ``column-def`` is ``column-name [type-name] column-constraint*``, + ``type-name`` is one or more bare type names (optionally + parenthesised), and the constraints are ``CONSTRAINT``, + ``PRIMARY KEY``, ``NOT NULL``, ``UNIQUE``, ``CHECK`` and the default + clauses: a nullability and a set of column constraints, never a type + modifier. ``REAL UNSIGNED`` is not a column declaration SQLite + admits. https://sqlite.org/lang_createtable.html + + The affinity collapse these formatters already perform -- ``FLOAT`` and + ``DOUBLE PRECISION`` both render as ``REAL``, and ``DECIMAL`` as + ``NUMERIC`` -- is a *different* decision and stays: it is SQLite's + documented storage model. Signedness is not a width, so it cannot + collapse that way, and collapsing it would hand the caller a column that + stores the negatives they declared it would not. + + ``word`` is the word SQLite renders, not the concept the caller named, + so the message says what this backend would have written instead. + + ``UnsupportedFeatureError``, not ``ValueError``: this is a declaration + the grammar cannot express at all rather than a wrong value, and the two + exceptions do not share a base class. + """ + if not getattr(data_type, "unsigned", False): + return + raise UnsupportedFeatureError( + self.name, + f"an unsigned {word} column " + f"(SQLite has no unsigned floating-point or fixed-point column; its " + f"five storage classes are a closed list and REAL is documented as " + f"an 8-byte IEEE 754 floating-point number with a signed range, and " + f"SQLite's column grammar has no type-modifier position after the " + f"type name, so there is not even a spelling that would parse)", + suggestion=( + "Declare the column signed and enforce the range with a CHECK " + "constraint if negatives must be rejected." + ), + ) + def format_data_type_sqlite_integer(self, data_type: SQLiteIntegerType) -> Tuple[str, tuple]: + """The INTEGER affinity class, so ``INTEGER`` whatever width was asked + for -- SQLite's documented storage model, not a claim about range. + + ``unsigned`` is refused rather than ignored; see + :meth:`_refuse_unsigned_integer`. The affinity collapse cannot stand in + for it: signedness is not a width, so there is no narrower column for a + wider range to collapse into.""" + self._refuse_unsigned_integer(data_type, "INTEGER") return "INTEGER", () def format_data_type_sqlite_text(self, data_type: SQLiteTextType) -> Tuple[str, tuple]: @@ -73,33 +184,86 @@ def format_data_type_sqlite_blob(self, data_type: SQLiteBlobType) -> Tuple[str, # --- Core types (pure names) rendered per SQLite affinity --- def format_data_type_integer(self, data_type: IntegerType) -> Tuple[str, tuple]: - return "INTEGER", () + """SQLite accepts both spellings of this one type (its affinity regex + matches ``INT`` and ``INTEGER`` alike), so the spelling is honoured.""" + if data_type.spelling not in IntegerType.SPELLINGS: + raise TypeError( + f"{type(self).__name__} cannot render " + f"{data_type.spelling!r}; it accepts " + f"{', '.join(IntegerType.SPELLINGS)}." + ) + self._refuse_unsigned_integer(data_type, data_type.spelling.upper()) + return ("INT" if data_type.spelling == "int" else "INTEGER"), () def format_data_type_text(self, data_type: TextType) -> Tuple[str, tuple]: return "TEXT", () def format_data_type_real(self, data_type: RealType) -> Tuple[str, tuple]: + """``REAL``, and refuses ``unsigned``; see + :meth:`_refuse_unsigned_numeric`. + + ``REAL`` is one of the two words SQLite's five storage classes use, and + the one this dialect already renders for ``FLOAT`` and ``DOUBLE + PRECISION`` as well -- so unlike the integer widths there is nothing to + collapse here and the signedness is the only thing to answer for. SQLite + documents ``REAL`` as "floating point numbers, using an 8-byte IEEE 754 + floating-point number": a binary64, signed on both sides, with no + unsigned row among the five storage classes and no type-modifier position + in ``column-def`` in which ``UNSIGNED`` could go. Affinity collapse and + signedness are different decisions, and signedness is not a width, so it + cannot collapse away: a bare ``REAL`` for an unsigned request would be a + column that stores the negatives the caller declared it would not. + https://sqlite.org/datatype3.html + """ + self._refuse_unsigned_numeric(data_type, "REAL") return "REAL", () def format_data_type_blob(self, data_type: CoreBlobType) -> Tuple[str, tuple]: return "BLOB", () def format_data_type_bigint(self, data_type: BigIntType) -> Tuple[str, tuple]: + """Every integer width collapses to ``INTEGER``, which is SQLite's + documented storage model rather than a claim about width. + + ``unsigned`` is refused rather than ignored; see + :meth:`_refuse_unsigned_integer`.""" + self._refuse_unsigned_integer(data_type, "INTEGER") return "INTEGER", () def format_data_type_smallint(self, data_type: SmallIntType) -> Tuple[str, tuple]: + """Collapses to ``INTEGER`` like every other integer width, and refuses + ``unsigned``; see :meth:`_refuse_unsigned_integer`.""" + self._refuse_unsigned_integer(data_type, "INTEGER") return "INTEGER", () def format_data_type_varchar(self, data_type: VarCharType) -> Tuple[str, tuple]: + if data_type.spelling not in VarCharType.SPELLINGS: + raise TypeError( + f"{type(self).__name__} cannot render {data_type.spelling!r}; " + f"it accepts {', '.join(VarCharType.SPELLINGS)}." + ) return "TEXT", () def format_data_type_char(self, data_type: CharType) -> Tuple[str, tuple]: return "TEXT", () def format_data_type_float(self, data_type: FloatType) -> Tuple[str, tuple]: + """``FLOAT(p)`` collapses to ``REAL``, which is SQLite's documented + storage class for approximate numerics, and refuses ``unsigned``; see + :meth:`_refuse_unsigned_numeric`.""" + self._refuse_unsigned_numeric(data_type, "REAL") return "REAL", () def format_data_type_decimal(self, data_type: DecimalType) -> Tuple[str, tuple]: + """``DECIMAL`` collapses to ``NUMERIC``, which is SQLite's documented + storage class for fixed-point values, and refuses ``unsigned``; see + :meth:`_refuse_unsigned_numeric`.""" + if data_type.spelling not in DecimalType.SPELLINGS: + raise TypeError( + f"{type(self).__name__} cannot render {data_type.spelling!r}; " + f"it accepts {', '.join(DecimalType.SPELLINGS)}." + ) + self._refuse_unsigned_numeric(data_type, "NUMERIC") return "NUMERIC", () def format_data_type_boolean(self, data_type: BooleanType) -> Tuple[str, tuple]: @@ -118,12 +282,17 @@ def format_data_type_time(self, data_type: TimeType) -> Tuple[str, tuple]: return "NUMERIC", () def format_data_type_tinyint(self, data_type: TinyIntType) -> Tuple[str, tuple]: - return "INTEGER", () - def format_data_type_int(self, data_type: IntType) -> Tuple[str, tuple]: + """Collapses to ``INTEGER`` like every other integer width, and + refuses ``unsigned``; see :meth:`_refuse_unsigned_integer`.""" + self._refuse_unsigned_integer(data_type, "INTEGER") return "INTEGER", () def format_data_type_double(self, data_type: DoubleType) -> Tuple[str, tuple]: + """``DOUBLE PRECISION`` collapses to ``REAL``, which is SQLite's + documented storage class for approximate numerics, and refuses + ``unsigned``; see :meth:`_refuse_unsigned_numeric`.""" + self._refuse_unsigned_numeric(data_type, "REAL") return "REAL", () def format_data_type_timetz(self, data_type: TimeTzType) -> Tuple[str, tuple]: @@ -147,107 +316,40 @@ def format_data_type_custom(self, data_type: CustomType) -> Tuple[str, tuple]: # ------------------------------------------------------------------ # # SQLite stores everything through type affinity: any type this mixin - # renders is genuinely storable, so support is declared for exactly the - # format_data_type_* family above (1:1 correspondence contract), and - # honestly absent for everything else (e.g. enum, uuid, binary — those - # are covered by suggested_data_types() instead). + # renders is genuinely storable, so the ``format_data_type_*`` family + # above is the whole support declaration — the formatter *is* the + # "supported" answer. Anything this mixin does not render (e.g. enum, + # uuid, binary) is honestly absent, and covered by + # ``suggested_data_types()`` instead. # ------------------------------------------------------------------ - def supports_data_type_sqlite_integer(self) -> bool: - return True - - def supports_data_type_sqlite_text(self) -> bool: - return True - - def supports_data_type_sqlite_real(self) -> bool: - return True - - def supports_data_type_sqlite_numeric(self) -> bool: - return True - - def supports_data_type_sqlite_blob(self) -> bool: - return True - - def supports_data_type_integer(self) -> bool: - return True - - def supports_data_type_text(self) -> bool: - return True - - def supports_data_type_real(self) -> bool: - return True - - def supports_data_type_blob(self) -> bool: - return True - - def supports_data_type_bigint(self) -> bool: - return True - - def supports_data_type_smallint(self) -> bool: - return True - - def supports_data_type_varchar(self) -> bool: - return True - - def supports_data_type_char(self) -> bool: - return True - def supports_data_type_float(self) -> bool: - return True - - def supports_data_type_decimal(self) -> bool: - return True - - def supports_data_type_boolean(self) -> bool: - return True - - def supports_data_type_date(self) -> bool: - return True - - def supports_data_type_datetime(self) -> bool: - return True - - def supports_data_type_timestamp(self) -> bool: - return True - - def supports_data_type_time(self) -> bool: - return True - - def supports_data_type_tinyint(self) -> bool: - return True - - def supports_data_type_int(self) -> bool: - return True - - def supports_data_type_double(self) -> bool: - return True - - def supports_data_type_timetz(self) -> bool: - return True - - def supports_data_type_timestamptz(self) -> bool: - return True - - def supports_data_type_interval(self) -> bool: - return True - - def supports_data_type_json(self) -> bool: - return True - - def supports_data_type_jsonb(self) -> bool: - return True - - def supports_data_type_custom(self) -> bool: - return True - - - # SQLite type affinity groups for parsing + # SQLite type affinity groups for parsing. + # + # These are SQLite's own affinity rules (https://sqlite.org/datatype3.html) + # widened by the spellings the core type classes declare in ``SPELLINGS``. + # A type the framework models must never fall through to ``CustomType`` + # merely because this backend spells its types differently, so every entry of + # every core ``SPELLINGS`` tuple appears in exactly one group: + # + # ``INT1`` INTEGER affinity — SQLite's rule is "the declared type + # *contains* INT", so ``INT1`` was always an INTEGER column and + # only this alternation list was missing it. + # ``CHARACTER`` TEXT affinity — same rule, "contains CHAR". + # ``DEC`` NUMERIC affinity — the unrecognised-type fallback, which is + # ``BOOL`` what SQLite has always done with ``DEC`` and ``BOOL``. + # + # Nothing else moves: the ``\b`` anchors keep ``CHAR`` from swallowing + # ``CHARACTER`` and ``DEC`` from swallowing ``DECIMAL``, and the group each + # spelling lands in is unchanged, so no affinity assignment is revised. _INTEGER_TYPES = re.compile( - r"^(?:INT|INTEGER|BIGINT|SMALLINT|TINYINT|MEDIUMINT|INT2|INT8)\b", + r"^(?:INT|INTEGER|BIGINT|SMALLINT|TINYINT|MEDIUMINT" + r"|INT1|INT2|INT4|INT8)\b", re.IGNORECASE, ) _TEXT_TYPES = re.compile( - r"^(?:TEXT|CHAR|VARCHAR|NVARCHAR|CHARACTER\s+VARYING|NCHAR|CLOB)\b", + r"^(?:TEXT|CHAR|CHARACTER|CHARACTER\s+VARYING" + r"|VARCHAR|NVARCHAR|NCHAR|CLOB)\b", re.IGNORECASE, ) _REAL_TYPES = re.compile( @@ -255,7 +357,7 @@ def supports_data_type_custom(self) -> bool: re.IGNORECASE, ) _NUMERIC_TYPES = re.compile( - r"^(?:NUMERIC|DECIMAL|BOOLEAN|DATE|DATETIME|TIMESTAMP|TIME)\b", + r"^(?:NUMERIC|DECIMAL|DEC|BOOLEAN|BOOL|DATE|DATETIME|TIMESTAMP|TIME)\b", re.IGNORECASE, ) _BLOB_TYPES = re.compile( @@ -275,6 +377,28 @@ def parse_type(self, raw: str) -> DataType: Returns the corresponding ``SQLite*Type`` for the matched affinity. Unknown type strings return ``CustomType``. + + Two properties of the answer are contractual. + + **Every spelling the framework models is recognised.** Each entry of + every core ``SPELLINGS`` tuple lands in one of the five groups above, so + ``INT1``, ``CHARACTER``, ``DEC`` and ``BOOL`` reach a type instead of + falling off the end into ``CustomType``. A ``CustomType`` is the + honest answer only for a name the framework has no concept for. + + **One concept in, one class out.** All spellings of one concept reach + the same class, so ``parse_type("INTEGER")`` and ``parse_type("INT")`` + cannot disagree about what a column is. Which class is the affinity's, + not the spelling's: SQLite stores ``TINYINT``, ``BIGINT`` and ``INT1`` + in the very same INTEGER-affinity cell and ``CHAR`` in the very same + TEXT-affinity cell, and reporting them apart would be reporting a + distinction the database does not make. So the answer is the affinity + class, and it is the *concept* class where the affinity names exactly + one — ``SQLiteIntegerType`` **is** an ``IntegerType``, + ``SQLiteTextType`` **is** a ``TextType``, ``SQLiteBlobType`` **is** a + ``BlobType``. ``SQLiteNumericType`` deliberately derives from no core + type, because that affinity spans the numeric, boolean and temporal + families at once; see ``impl/sqlite/expression/types.py``. """ from ..expression.types import ( SQLiteBlobType, diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/virtual_table.py b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/virtual_table.py index a51403f00..63c2230b2 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/mixins/virtual_table.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/mixins/virtual_table.py @@ -10,6 +10,7 @@ from .extension import SQLiteExtensionMixin if TYPE_CHECKING: + from ..expression.fts5 import SQLiteFTS5MatchExpression from ..expression.virtual_table import CreateVirtualTableExpression, DropVirtualTableExpression _KNOWN_VTABLE_MODULES: Set[str] = { @@ -146,7 +147,7 @@ def format_drop_virtual_table( def format_match_predicate( self, - expr, + expr: "SQLiteFTS5MatchExpression", ) -> Tuple[str, tuple]: """Format full-text search MATCH predicate (delegates to FTS5Mixin).""" return self.format_fts5_match_expression(expr) diff --git a/src/rhosocial/activerecord/backend/impl/sqlite/protocols.py b/src/rhosocial/activerecord/backend/impl/sqlite/protocols.py index d576dced2..4b4b0ad94 100644 --- a/src/rhosocial/activerecord/backend/impl/sqlite/protocols.py +++ b/src/rhosocial/activerecord/backend/impl/sqlite/protocols.py @@ -13,6 +13,7 @@ from .expression.fts5 import ( SQLiteFTS5CreateVirtualTable, SQLiteFTS5HighlightExpression, + SQLiteFTS5MatchExpression, SQLiteFTS5RankExpression, SQLiteFTS5SnippetExpression, ) @@ -24,6 +25,7 @@ from .expression.reindex import SQLiteReindexExpression from .expression.rtree import SQLiteRTreeCreateVirtualTable, SQLiteRTreeRangeQuery from .expression.vacuum import SQLiteAnalyzeExpression, SQLiteVacuumExpression + from .expression.virtual_table import CreateVirtualTableExpression, DropVirtualTableExpression @runtime_checkable @@ -222,7 +224,7 @@ def supports_json1_extension(self) -> bool: def format_create_virtual_table( self, - expr: Any, + expr: "CreateVirtualTableExpression", ) -> Tuple[str, tuple]: """Format CREATE VIRTUAL TABLE statement. @@ -236,7 +238,7 @@ def format_create_virtual_table( def format_drop_virtual_table( self, - expr: Any, + expr: "DropVirtualTableExpression", ) -> Tuple[str, tuple]: """Format DROP TABLE statement for virtual table. @@ -252,7 +254,7 @@ def format_drop_virtual_table( def format_match_predicate( self, - expr: Any, + expr: "SQLiteFTS5MatchExpression", ) -> Tuple[str, tuple]: """Format full-text search MATCH predicate. @@ -409,7 +411,7 @@ def get_supported_fts5_tokenizers(self) -> List[str]: ... def format_fts5_match_expression( - self, expr: Any + self, expr: "SQLiteFTS5MatchExpression" ) -> Tuple[str, tuple]: """Format FTS5 MATCH expression.""" ... diff --git a/src/rhosocial/activerecord/backend/introspection/status/types.py b/src/rhosocial/activerecord/backend/introspection/status/types.py index 0c407e0eb..48c34435f 100644 --- a/src/rhosocial/activerecord/backend/introspection/status/types.py +++ b/src/rhosocial/activerecord/backend/introspection/status/types.py @@ -534,12 +534,38 @@ class ServerOverview: archive: Archive information (PostgreSQL specific) security: Security information extensions: List of installed extensions (PostgreSQL specific) - innodb: InnoDB storage engine information (MySQL specific) - binary_log: Binary log information (MySQL specific) + innodb: InnoDB storage engine information — **MySQL only, ``None`` + everywhere else** + binary_log: Binary log information — **MySQL only, ``None`` everywhere + else** processes: List of current running processes (MySQL specific) - slow_query: Slow query log configuration (MySQL specific) - mysql_replication: MySQL replication status (MySQL specific) + slow_query: Slow query log configuration — **MySQL only, ``None`` + everywhere else** + mysql_replication: MySQL replication status — **MySQL only, ``None`` + everywhere else** extra: Additional backend-specific information + + **On the four MySQL-named slots.** They are declared here, so every + backend carries them, and on any other server they are permanently + ``None`` — a ClickHouse or Oracle or Firebird introspector cannot fill an + ``InnoDBInfo``, because that engine does not exist there. The name is a + false claim about the backend in the same way a prefixed dispatch key is a + false claim about a type: it asserts the backend has something it does not. + + Renaming them is a cross-repository API break — ``to_dict()`` would lose or + change those four keys, every ``get_overview()`` that passes them breaks, + and the ``cli/status.py`` of four backends reads them. That needs its own + change with its own release note, not a drive-by edit here. + + Until then the rule is: **a backend must not name these at all.** The + ClickHouse introspector used to take an ``innodb: Optional[InnoDBInfo] = + None`` parameter and pass ``None`` on every call, which put the false claim + into a *signature* rather than only into this file; it no longer does, and + a test there asserts ``"innodb"`` is absent from the builder's local + variable names. A backend with its own engine-level facts puts them in + ``extra`` — ClickHouse's storage engines, Oracle's tablespaces, SQL + Server's filegroups — which is where a vendor-neutral shape belongs and + needs no new core field per vendor. """ server_version: str diff --git a/src/rhosocial/activerecord/backend/introspection/types.py b/src/rhosocial/activerecord/backend/introspection/types.py index 49b0295d4..bcc516b84 100644 --- a/src/rhosocial/activerecord/backend/introspection/types.py +++ b/src/rhosocial/activerecord/backend/introspection/types.py @@ -99,7 +99,30 @@ class IndexColumnInfo: @dataclass class ColumnInfo: - """Column information.""" + """Column information. + + ``parsed_data_type`` is the column's type as a + :class:`~...expression.types.DataType` value object, and it is + :data:`None` for one reason only: **the catalog string could not be + read.** That is load-bearing rather than incidental, because the schema + differ branches on it — it compares the two value objects when both sides + are present, and falls back to comparing the ``data_type`` *strings* + otherwise. + + So ``None`` means "this backend could not parse this one column", not "this + column has no type". An introspector therefore must not let one unreadable + column abort the whole table: degrade that column to ``None`` — which is + exactly the fallback the differ already takes — and say so with a warning. + + That contract is not theoretical. Turning the field on for the MariaDB + backend exposed three ``parse_type`` defects that had been invisible while + it sat permanently ``None``: a ``GEOMETRYCOLLECTION`` column parsing as a + plain ``GEOMETRY`` (so the differ reported *no* change between a collection + column and a geometry column), a ``DATETIME(6)`` column parsing with its + fsp dropped, and a ``UUID`` column parsing to ``CustomType`` although the + dialect's own formatters write ``UUID``. A field nobody populates cannot + find anything. + """ name: str table_name: str diff --git a/src/rhosocial/activerecord/backend/schema/differ.py b/src/rhosocial/activerecord/backend/schema/differ.py index e7f9f81cb..9e1842e18 100644 --- a/src/rhosocial/activerecord/backend/schema/differ.py +++ b/src/rhosocial/activerecord/backend/schema/differ.py @@ -166,7 +166,10 @@ def _columns_equivalent(self, old_col, new_col) -> bool: """ old_dt, new_dt = old_col.parsed_data_type, new_col.parsed_data_type if old_dt is not None and new_dt is not None: - if not old_dt.is_equivalent(new_dt): + # Identity, not a looser "equivalent" question. Both sides come from + # the same dialect's parse_type, so a change of class *is* a change + # of declared type — which is exactly what a caller wants to see. + if old_dt != new_dt: return False else: if (old_col.data_type or "").upper().split() != (new_col.data_type or "").upper().split(): diff --git a/src/rhosocial/activerecord/base/__init__.py b/src/rhosocial/activerecord/base/__init__.py index b39d519cf..29e272786 100644 --- a/src/rhosocial/activerecord/base/__init__.py +++ b/src/rhosocial/activerecord/base/__init__.py @@ -3,7 +3,7 @@ from .base import BaseActiveRecord, AsyncBaseActiveRecord from .query_mixin import QueryMixin, AsyncQueryMixin -from .field_proxy import FieldProxy +from .field_proxy import FieldProxy, FieldAccessor, ColumnTypeResolutionError from .column_name_mixin import ColumnNameMixin, ColumnNameAnnotationHandler from .field_adapter_mixin import FieldAdapterMixin, AdapterAnnotationHandler from .derived_field_mixin import DerivedFieldMixin @@ -19,6 +19,7 @@ UseGeneratedColumn, UseIndex, UseSqlType, + UseColumnType, ) from .ddl import ( CharacterSetAttribute, @@ -26,6 +27,7 @@ ColumnAttribute, ColumnOptions, DDLAnnotationHandler, + DDLColumnDataType, DDLColumnType, DDLFieldMetadata, DDLGeneratedColumn, @@ -42,6 +44,8 @@ "QueryMixin", "AsyncQueryMixin", "FieldProxy", + "FieldAccessor", + "ColumnTypeResolutionError", "ColumnNameMixin", "ColumnNameAnnotationHandler", "FieldAdapterMixin", @@ -57,12 +61,14 @@ "UseGeneratedColumn", "UseIndex", "UseSqlType", + "UseColumnType", "DerivedField", "CharacterSetAttribute", "CollationAttribute", "ColumnAttribute", "ColumnOptions", "DDLAnnotationHandler", + "DDLColumnDataType", "DDLColumnType", "DDLFieldMetadata", "DDLGeneratedColumn", diff --git a/src/rhosocial/activerecord/base/base.py b/src/rhosocial/activerecord/base/base.py index 4b8ed995a..bbab42dc8 100644 --- a/src/rhosocial/activerecord/base/base.py +++ b/src/rhosocial/activerecord/base/base.py @@ -9,7 +9,14 @@ from ..backend.base import StorageBackend, AsyncStorageBackend from ..backend.config import ConnectionConfig from ..backend.errors import DatabaseError, RecordNotFound, ValidationError as DBValidationError -from ..backend.expression import ComparisonPredicate, Column, Literal, SQLPredicate +from ..backend.expression import ( + Column, + ColumnBase, + ComparisonPredicate, + InPredicate, + Literal, + SQLPredicate, +) from ..backend.expression.bases import is_sql_query_and_params from ..backend.options import DeleteOptions, UpdateOptions from ..backend.options import InsertOptions @@ -414,7 +421,7 @@ def _after_save(self, is_new: bool) -> None: @classmethod def find_one( cls: Type["BaseActiveRecord"], - condition: Union[Any, Dict[str, Any], Dict["Column", Any], "SQLPredicate", Tuple[str, tuple]], + condition: Union[Any, Dict[str, Any], Dict["ColumnBase", Any], "SQLPredicate", Tuple[str, tuple]], *, derived: Union[bool, str, list, dict] = False, extra_derived: Optional[Dict[str, Any]] = None, @@ -427,10 +434,18 @@ def find_one( query = query.where(cls._build_pk_where_predicate(condition)) else: for key, value in condition.items(): - if isinstance(key, Column): - query = query.where(key == value) + if isinstance(key, ColumnBase): + # An explicit node, not the column's own operator: the + # key may be a bare Column reference (whose class offers + # no operations by design) and the query must not care. + query = query.where( + ComparisonPredicate(key.dialect, "=", key, Literal(key.dialect, value)) + ) elif isinstance(key, str): - query = query.where(getattr(cls.c, key) == value) + column = getattr(cls.c, key) + query = query.where( + ComparisonPredicate(column.dialect, "=", column, Literal(column.dialect, value)) + ) else: raise TypeError( f"Invalid key type in condition dictionary: {type(key)}. " @@ -448,7 +463,10 @@ def find_one( elif not cls.is_composite_pk(): pk_field_name = cls.primary_key() dialect = cls.backend().dialect - query = query.where(Column(dialect, pk_field_name) == condition) + pk_column = Column(dialect, pk_field_name) + query = query.where( + ComparisonPredicate(dialect, "=", pk_column, Literal(dialect, condition)) + ) else: raise TypeError( f"{cls.__name__} has composite primary key; " @@ -461,7 +479,7 @@ def find_one( def find_all( cls: Type["BaseActiveRecord"], condition: Optional[ - Union[Any, List[Any], Dict[str, Any], Dict["Column", Any], "SQLPredicate", Tuple[str, tuple]] + Union[Any, List[Any], Dict[str, Any], Dict["ColumnBase", Any], "SQLPredicate", Tuple[str, tuple]] ] = None, *, derived: Union[bool, str, list, dict] = False, @@ -478,10 +496,18 @@ def find_all( query = query.where(cls._build_pk_where_predicate(condition)) else: for key, value in condition.items(): - if isinstance(key, Column): - query = query.where(key == value) + if isinstance(key, ColumnBase): + # An explicit node, not the column's own operator: the + # key may be a bare Column reference (whose class offers + # no operations by design) and the query must not care. + query = query.where( + ComparisonPredicate(key.dialect, "=", key, Literal(key.dialect, value)) + ) elif isinstance(key, str): - query = query.where(getattr(cls.c, key) == value) + column = getattr(cls.c, key) + query = query.where( + ComparisonPredicate(column.dialect, "=", column, Literal(column.dialect, value)) + ) else: raise TypeError( f"Invalid key type in condition dictionary: {type(key)}. " @@ -508,7 +534,9 @@ def find_all( else: pk_field_name = cls.primary_key() dialect = cls.backend().dialect - query = query.where(Column(dialect, pk_field_name).in_(condition)) + query = query.where( + InPredicate(dialect, Column(dialect, pk_field_name), Literal(dialect, tuple(condition))) + ) elif is_sql_query_and_params(condition): sql, params = condition query = query.where(sql, params) @@ -517,14 +545,16 @@ def find_all( if not condition: return [] dialect = cls.backend().dialect - query = query.where(Column(dialect, pk_field_name).in_(condition)) + query = query.where( + InPredicate(dialect, Column(dialect, pk_field_name), Literal(dialect, tuple(condition))) + ) cls._apply_derived_to_query(query, derived, extra_derived) return query.all() @classmethod def find_one_or_fail( cls: Type["BaseActiveRecord"], - condition: Union[Any, Dict[str, Any], Dict["Column", Any], "SQLPredicate", Tuple[str, tuple]], + condition: Union[Any, Dict[str, Any], Dict["ColumnBase", Any], "SQLPredicate", Tuple[str, tuple]], *, derived: Union[bool, str, list, dict] = False, extra_derived: Optional[Dict[str, Any]] = None, @@ -1092,7 +1122,7 @@ def _after_save(self, is_new: bool) -> None: @classmethod async def find_one( cls: Type["AsyncBaseActiveRecord"], - condition: Union[Any, Dict[str, Any], Dict["Column", Any], "SQLPredicate", Tuple[str, tuple]], + condition: Union[Any, Dict[str, Any], Dict["ColumnBase", Any], "SQLPredicate", Tuple[str, tuple]], *, derived: Union[bool, str, list, dict] = False, extra_derived: Optional[Dict[str, Any]] = None, @@ -1105,10 +1135,18 @@ async def find_one( query = query.where(cls._build_pk_where_predicate(condition)) else: for key, value in condition.items(): - if isinstance(key, Column): - query = query.where(key == value) + if isinstance(key, ColumnBase): + # An explicit node, not the column's own operator: the + # key may be a bare Column reference (whose class offers + # no operations by design) and the query must not care. + query = query.where( + ComparisonPredicate(key.dialect, "=", key, Literal(key.dialect, value)) + ) elif isinstance(key, str): - query = query.where(getattr(cls.c, key) == value) + column = getattr(cls.c, key) + query = query.where( + ComparisonPredicate(column.dialect, "=", column, Literal(column.dialect, value)) + ) else: raise TypeError( f"Invalid key type in condition dictionary: {type(key)}. " @@ -1126,7 +1164,10 @@ async def find_one( elif not cls.is_composite_pk(): pk_field_name = cls.primary_key() dialect = cls.backend().dialect - query = query.where(Column(dialect, pk_field_name) == condition) + pk_column = Column(dialect, pk_field_name) + query = query.where( + ComparisonPredicate(dialect, "=", pk_column, Literal(dialect, condition)) + ) else: raise TypeError( f"{cls.__name__} has composite primary key; " @@ -1139,7 +1180,7 @@ async def find_one( async def find_all( cls: Type["AsyncBaseActiveRecord"], condition: Optional[ - Union[Any, List[Any], Dict[str, Any], Dict["Column", Any], "SQLPredicate", Tuple[str, tuple]] + Union[Any, List[Any], Dict[str, Any], Dict["ColumnBase", Any], "SQLPredicate", Tuple[str, tuple]] ] = None, *, derived: Union[bool, str, list, dict] = False, @@ -1156,10 +1197,18 @@ async def find_all( query = query.where(cls._build_pk_where_predicate(condition)) else: for key, value in condition.items(): - if isinstance(key, Column): - query = query.where(key == value) + if isinstance(key, ColumnBase): + # An explicit node, not the column's own operator: the + # key may be a bare Column reference (whose class offers + # no operations by design) and the query must not care. + query = query.where( + ComparisonPredicate(key.dialect, "=", key, Literal(key.dialect, value)) + ) elif isinstance(key, str): - query = query.where(getattr(cls.c, key) == value) + column = getattr(cls.c, key) + query = query.where( + ComparisonPredicate(column.dialect, "=", column, Literal(column.dialect, value)) + ) else: raise TypeError( f"Invalid key type in condition dictionary: {type(key)}. " @@ -1186,7 +1235,9 @@ async def find_all( else: pk_field_name = cls.primary_key() dialect = cls.backend().dialect - query = query.where(Column(dialect, pk_field_name).in_(condition)) + query = query.where( + InPredicate(dialect, Column(dialect, pk_field_name), Literal(dialect, tuple(condition))) + ) elif is_sql_query_and_params(condition): sql, params = condition query = query.where(sql, params) @@ -1195,14 +1246,16 @@ async def find_all( if not condition: return [] dialect = cls.backend().dialect - query = query.where(Column(dialect, pk_field_name).in_(condition)) + query = query.where( + InPredicate(dialect, Column(dialect, pk_field_name), Literal(dialect, tuple(condition))) + ) cls._apply_derived_to_query(query, derived, extra_derived) return await query.all() @classmethod async def find_one_or_fail( cls: Type["AsyncBaseActiveRecord"], - condition: Union[Any, Dict[str, Any], Dict["Column", Any], "SQLPredicate", Tuple[str, tuple]], + condition: Union[Any, Dict[str, Any], Dict["ColumnBase", Any], "SQLPredicate", Tuple[str, tuple]], *, derived: Union[bool, str, list, dict] = False, extra_derived: Optional[Dict[str, Any]] = None, diff --git a/src/rhosocial/activerecord/base/ddl.py b/src/rhosocial/activerecord/base/ddl.py index 58502daea..5fe0e530e 100644 --- a/src/rhosocial/activerecord/base/ddl.py +++ b/src/rhosocial/activerecord/base/ddl.py @@ -49,6 +49,7 @@ UseColumnAttributes, UseComment, UseConstraint, + UseColumnType, UseGeneratedColumn, UseIndex, UseSqlType, @@ -56,10 +57,12 @@ if TYPE_CHECKING: # pragma: no cover from rhosocial.activerecord.backend.dialect import SQLDialectBase + from rhosocial.activerecord.backend.expression.column_types import ColumnBase from rhosocial.activerecord.backend.expression.types import DataType -DDLColumnType = Union["UseSqlType", "DataType", Sequence["DataType"]] +DDLColumnDataType = Union["UseSqlType", "DataType", Sequence["DataType"]] +DDLColumnType = Union["UseColumnType", Type["ColumnBase"], Sequence[Type["ColumnBase"]]] DDLGeneratedColumn = Union[ GeneratedColumnExpression, Callable[["SQLDialectBase"], GeneratedColumnExpression], @@ -303,18 +306,25 @@ def handle(cls, new_class: Type[Any]) -> None: @runtime_checkable class DDLSource(Protocol): - """Structural contract for an ActiveRecord DDL parameter source. - - ``DDLSource`` exposes declarations only: table and field metadata, column - constraints and attributes, indexes, generated columns, and table-level - options. Consumers use this contract to inspect DDL declarations; the - source itself never creates, renders, or executes SQL. + """Structural contract for an ActiveRecord field-fact source. + + ``DDLSource`` exposes a model's field facts and DDL declarations: the + Python type of a field (``field_python_type``), the column class its + expressions use (``column_type``), the declared column data type + (``column_data_type``), table and field metadata, column constraints and + attributes, indexes, generated columns, and table-level options. It never + creates, renders, or executes SQL. + + Every member is dialect-free: ``column_type`` presents the column-type + declaration as written (a ``UseColumnType`` marker, a class, or a + sequence) and ``column_data_type`` the declared data type, leaving the + resolution of either against the active backend to the caller. That + lets the DDL layer apply the active dialect and capability gates without + the source ever needing one. The protocol is intentionally structural. ``ActiveRecord`` satisfies it through :class:`DDLSourceMixin`, while integrations may provide their own - source implementation without inheriting from ActiveRecord. Returned - values are dialect-free declarations or ordered candidates, allowing the - DDL layer to apply the active backend dialect and capability gates. + source implementation without inheriting from ActiveRecord. This contract deliberately excludes the ``ddl()`` factory, backend and dialect objects, expression generation, statement plans, rendering, and @@ -349,6 +359,9 @@ def field_is_optional(self, field: str) -> bool: def column_name(self, field: str) -> str: ... + def column_data_type(self, field: str) -> Optional[DDLColumnDataType]: + ... + def column_type(self, field: str) -> Optional[DDLColumnType]: ... @@ -534,15 +547,58 @@ def column_name(cls, field: str) -> str: return cast(Any, cls).get_column_name(field) @classmethod - def column_type(cls, field: str) -> Optional[DDLColumnType]: + def _field_metadata(cls, field: str) -> Optional["DDLFieldMetadata"]: + """The collected DDL metadata for *field*, or ``None`` if none declared. + + A field the model does not have is refused with ``KeyError``: ``None`` + is the answer for a real field that declares nothing, and letting a + misspelled name produce the same answer would hide the mistake. Every + accessor reads its metadata through this one lookup, so the rule is + identical for all of them. + """ + if field not in (getattr(cls, "model_fields", {}) or {}): + raise KeyError(field) + return (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + + @classmethod + def column_data_type(cls, field: str) -> Optional[DDLColumnDataType]: cls._validate_ddl_annotations() - metadata = (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + metadata = cls._field_metadata(field) return metadata.use_sql_type if metadata is not None else None + @classmethod + def column_type(cls, field: str) -> Optional[DDLColumnType]: + """The column-type declaration for *field*, in the form declared. + + Dialect-free, like :meth:`column_data_type`: the declaration is + presented as written -- a ``UseColumnType`` marker (its candidates + included), a single class, or a sequence -- or ``None`` when the field + declares none. How the declaration is consumed is the caller's + business; the framework's own consumer is :class:`FieldProxy`, which + selects the class a backend answers. + + Raises: + KeyError: The model has no such field. + TypeError: More than one ``UseColumnType`` declaration on the field. + """ + field_info = cast(Any, cls).model_fields[field] + found = [ + item + for item in (getattr(field_info, "metadata", None) or ()) + if isinstance(item, UseColumnType) + ] + if len(found) > 1: + raise TypeError( + f"{len(found)} UseColumnType declarations on a single field. A " + f"field declares the column class it uses once; a model that " + f"wants a different one declares it on a different model." + ) + return found[0] if found else None + @classmethod def column_constraints(cls, field: str) -> Sequence[ColumnConstraint]: cls._validate_ddl_annotations() - metadata = (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + metadata = cls._field_metadata(field) if metadata is None: return [] constraints = [marker.constraint for marker in metadata.constraints] @@ -575,7 +631,7 @@ def column_constraints(cls, field: str) -> Sequence[ColumnConstraint]: @classmethod def column_attributes(cls, field: str) -> Sequence[ColumnAttribute]: cls._validate_ddl_annotations() - metadata = (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + metadata = cls._field_metadata(field) if metadata is None: return [] return [ @@ -587,7 +643,7 @@ def column_attributes(cls, field: str) -> Sequence[ColumnAttribute]: @classmethod def column_indexes(cls, field: str) -> Sequence[IndexDefinition]: cls._validate_ddl_annotations() - metadata = (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + metadata = cls._field_metadata(field) if metadata is None: return [] return [ @@ -598,14 +654,14 @@ def column_indexes(cls, field: str) -> Sequence[IndexDefinition]: @classmethod def column_comment(cls, field: str) -> Optional[str]: cls._validate_ddl_annotations() - metadata = (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + metadata = cls._field_metadata(field) marker = getattr(metadata, "column_comment", None) if metadata else None return marker.comment if marker is not None else None @classmethod def generated_column(cls, field: str) -> Optional[DDLGeneratedColumn]: cls._validate_ddl_annotations() - metadata = (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + metadata = cls._field_metadata(field) marker = getattr(metadata, "generated_column", None) if metadata else None return marker.expression if marker is not None else None @@ -614,7 +670,7 @@ def column_options( cls, field: str ) -> Optional[Union[ColumnOptions, Sequence[ColumnOptions]]]: cls._validate_ddl_annotations() - metadata = (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + metadata = cls._field_metadata(field) if metadata is None or not metadata.column_options: return None options = list(metadata.column_options) @@ -631,10 +687,10 @@ def columns_name(cls, fields: Optional[List[str]] = None) -> Dict[str, str]: return {field: cls.column_name(field) for field in cls._batch_fields(fields)} @classmethod - def columns_type( + def columns_data_type( cls, fields: Optional[List[str]] = None - ) -> Dict[str, Optional[DDLColumnType]]: - return {field: cls.column_type(field) for field in cls._batch_fields(fields)} + ) -> Dict[str, Optional[DDLColumnDataType]]: + return {field: cls.column_data_type(field) for field in cls._batch_fields(fields)} @classmethod def columns_constraints( @@ -688,7 +744,8 @@ def is_derived_field(cls, field: str) -> bool: @classmethod def ddl_field_metadata(cls, field: str) -> DDLFieldMetadata: - metadata = (getattr(cls, "__table_ddl_fields__", {}) or {}).get(field) + """The DDL metadata for *field*; a field the model lacks raises ``KeyError``.""" + metadata = cls._field_metadata(field) if metadata is None: metadata = DDLFieldMetadata(cast(Any, cls).model_fields[field]) metadata.require_handled() @@ -710,6 +767,7 @@ def field_is_optional(cls, field: str) -> bool: "ColumnAttribute", "ColumnOptions", "DDLAnnotationHandler", + "DDLColumnDataType", "DDLColumnType", "DDLFieldMetadata", "DDLGeneratedColumn", diff --git a/src/rhosocial/activerecord/base/field_proxy.py b/src/rhosocial/activerecord/base/field_proxy.py index 231fa9ec0..de4705558 100644 --- a/src/rhosocial/activerecord/base/field_proxy.py +++ b/src/rhosocial/activerecord/base/field_proxy.py @@ -11,17 +11,37 @@ - Predefined table aliases - Column aliases - Self-join queries + +The accessor also owns the **selection** of a field's column class: the model +presents the field's column-type declaration, and the accessor picks the class +that fits the active backend. """ -from typing import TYPE_CHECKING +import enum +import types +import typing +from typing import Any, Type, TYPE_CHECKING +from ..backend.expression.column_types import ColumnBase from ..backend.expression.core import Column +from .fields import UseColumnType if TYPE_CHECKING: from ..backend.dialect.base import SQLDialectBase from ..model import ActiveRecord +class ColumnTypeResolutionError(TypeError): + """No column class could be chosen for a field, and none may be guessed. + + Raised by the field accessor when the field's column-type declaration + (or, absent one, its annotation) cannot be resolved against the model's + backend. A ``TypeError`` because the wrong *thing* was asked for: a field + the framework cannot type is a mistake in the model, and finding it where + the field is read costs nothing next to a driver error naming a column. + """ + + class FieldProxy: """ Field proxy descriptor for accessing fields via Model.proxy_name.field_name syntax. @@ -79,8 +99,8 @@ def __get__(self, instance, owner): Descriptor method to return a field accessor for the given model class. This method is called when accessing the field proxy attribute on a class - (e.g., when accessing User.c). It returns a _FieldAccessor instance that - can be used to access individual fields. + (e.g., when accessing User.c). It returns a :class:`FieldAccessor` + instance that can be used to access individual fields. Args: instance: The instance that the attribute was accessed from (None when @@ -88,116 +108,314 @@ def __get__(self, instance, owner): owner: The class that owns this descriptor (e.g., User class) Returns: - _FieldAccessor: An object that allows field-by-field access + FieldAccessor: An object that allows field-by-field access """ + return FieldAccessor(owner, self._table_alias) - # Return a dynamic field accessor - class _FieldAccessor: - """ - Internal class that provides field access functionality for a specific model. - - This class is instantiated for each model class that uses FieldProxy. - It handles the translation of field names to column names and creates - appropriate SQL expression objects. - """ - - def __init__(self, model_class: "ActiveRecord", static_table_alias: str = None): - """ - Initialize the field accessor for a specific model class. - - Args: - model_class: The ActiveRecord model class this accessor is for - static_table_alias: Optional table alias to use for all columns - """ - self._model_class = model_class - self._table_alias = static_table_alias # Could be set during initialization - - def with_table_alias(self, alias: str): - """ - Create a new field accessor with the specified table alias. - - This method is useful for creating aliased versions of the same table - in self-joins or complex queries. - - Aliased columns are static ``alias.column`` references: an - aliased range can only be addressed by its alias, so schema/ - table qualifiers and later ``__table_name__`` changes do not - apply to them. Pair this with ``join(..., alias=...)`` using - the same alias name. - - Args: - alias: The table alias to use - - Returns: - _FieldAccessor: A new accessor instance with the specified alias - - Example: - # For self-join queries: give the joined range an explicit - # alias via join(alias=...), then address it through a - # matching with_table_alias accessor. - subs = User.c.with_table_alias('subordinates') - managers = User.query().join( - User, - on=User.c.reports_to_id == subs.id, - alias='subordinates', - ).select( - User.c.name.as_('manager'), - subs.name.as_('subordinate') - ).all() - """ - new_accessor = _FieldAccessor(self._model_class, alias) - return new_accessor - - def __getattr__(self, field_name: str): - """ - Dynamically create a column expression for the requested field. - - This method is called when accessing a specific field (e.g., User.c.name). - It looks up the field in the model's field definitions, resolves the - appropriate column name (handling UseColumn annotations), and creates - a Column expression object. - - Qualifier binding: - schema/table are captured from the model's CURRENT state at - access time. If ``__schema_name__`` / ``__table_name__`` - change afterwards, rebuild the condition (or build it after - the change); already-built expressions keep their original - qualifiers. Hand-written ``Column`` objects behave the same - way and are never rewritten by the framework. - - Args: - field_name: The name of the field to access - - Returns: - Column: A SQL expression object representing the field - - Raises: - AttributeError: If the field doesn't exist on the model - - Example: - # Accessing User.c.name returns a column expression usable in queries - where_clause = User.c.name == 'John' # Creates a comparison predicate - where_clause = User.c.age > 18 # Creates a comparison predicate - where_clause = User.c.email.like('%@gmail.com') # Creates a LIKE predicate - """ - # Use Pydantic's model_fields to get field information - if field_name not in self._model_class.model_fields: - raise AttributeError(f"Field '{field_name}' does not exist on model '{self._model_class.__name__}'") - - # Use ColumnNameMixin's method to get the correct column name - # This properly handles UseColumn annotations, returning custom column name - # if UseColumn is used, otherwise field name - column_name = self._model_class.get_column_name(field_name) - - # Use table alias (if set) as table name - table_name = self._table_alias if self._table_alias else self._model_class.table_name() - - # Only pass model's explicit schema_name; do not add default schema. - # The backend dialect decides how to format schema references. - schema_name = None if self._table_alias else self._model_class.schema_name() - - # Create column expression object using the real dialect - backend = self._model_class.backend() - dialect: "SQLDialectBase" = backend.dialect - return Column(dialect, column_name, table=table_name, schema_name=schema_name) - return _FieldAccessor(owner, self._table_alias) + +class FieldAccessor: + """Field accessor for one model class, the result of ``Model.c``. + + An instance is created for each access to the proxy on a model class. It + translates a field name to its column name, selects the column class the + field's column-type declaration means on the active backend, and creates + the column expression. + """ + + def __init__(self, model_class: "ActiveRecord", static_table_alias: str = None): + """ + Initialize the field accessor for a specific model class. + + Args: + model_class: The ActiveRecord model class this accessor is for + static_table_alias: Optional table alias to use for all columns + """ + self._model_class = model_class + self._table_alias = static_table_alias # Could be set during initialization + + def with_table_alias(self, alias: str): + """ + Create a new field accessor with the specified table alias. + + This method is useful for creating aliased versions of the same table + in self-joins or complex queries. + + Aliased columns are static ``alias.column`` references: an + aliased range can only be addressed by its alias, so schema/ + table qualifiers and later ``__table_name__`` changes do not + apply to them. Pair this with ``join(..., alias=...)`` using + the same alias name. + + Args: + alias: The table alias to use + + Returns: + FieldAccessor: A new accessor instance with the specified alias + + Example: + # For self-join queries: give the joined range an explicit + # alias via join(alias=...), then address it through a + # matching with_table_alias accessor. + subs = User.c.with_table_alias('subordinates') + managers = User.query().join( + User, + on=User.c.reports_to_id == subs.id, + alias='subordinates', + ).select( + User.c.name.as_('manager'), + subs.name.as_('subordinate') + ).all() + """ + return FieldAccessor(self._model_class, alias) + + def __getattr__(self, field_name: str): + """ + Dynamically create a column expression for the requested field. + + This method is called when accessing a specific field (e.g., User.c.name). + It looks up the field in the model's field definitions, resolves the + appropriate column name (handling UseColumn annotations), selects the + column class from the field's column-type declaration, and creates a + column expression object. + + Qualifier binding: + schema/table are captured from the model's CURRENT state at + access time. If ``__schema_name__`` / ``__table_name__`` + change afterwards, rebuild the condition (or build it after + the change); already-built expressions keep their original + qualifiers. Hand-written ``Column`` objects behave the same + way and are never rewritten by the framework. + + Args: + field_name: The name of the field to access + + Returns: + Column: A SQL expression object representing the field + + Raises: + AttributeError: If the field doesn't exist on the model + ColumnTypeResolutionError: If no column class can be chosen for + the field's column-type declaration or annotation + + Example: + # Accessing User.c.name returns a column expression usable in queries + where_clause = User.c.name == 'John' # Creates a comparison predicate + where_clause = User.c.age > 18 # Creates a comparison predicate + where_clause = User.c.email.like('%@gmail.com') # Creates a LIKE predicate + """ + # Use Pydantic's model_fields to get field information + if field_name not in self._model_class.model_fields: + raise AttributeError(f"Field '{field_name}' does not exist on model '{self._model_class.__name__}'") + + # Use ColumnNameMixin's method to get the correct column name + # This properly handles UseColumn annotations, returning custom column name + # if UseColumn is used, otherwise field name + column_name = self._model_class.get_column_name(field_name) + + # Use table alias (if set) as table name + table_name = self._table_alias if self._table_alias else self._model_class.table_name() + + # Only pass model's explicit schema_name; do not add default schema. + # The backend dialect decides how to format schema references. + schema_name = None if self._table_alias else self._model_class.schema_name() + + # The model presents the field's column type as a declaration + # (dialect-free); choosing the class this backend answers is this + # accessor's own business. + backend = self._model_class.backend() + dialect: "SQLDialectBase" = backend.dialect + field_info = self._model_class.model_fields[field_name] + declared = self._model_class.column_type(field_name) + column_class = self._select_column_class(dialect, field_info.annotation, declared) + if column_class is Column: + # The untyped column keeps its own narrower constructor and can + # now only arrive by being declared explicitly, never as a + # fallback. + return Column(dialect, column_name, table=table_name, schema_name=schema_name) + return column_class( + dialect, + column_name, + table=table_name, + schema_name=schema_name, + ) + + # -- column-class selection ------------------------------------------- + # + # ``Model.column_type(field)`` presents the declaration as written -- a + # ``UseColumnType`` marker (candidates included), a class, or a sequence + # -- and leaves the consumption to the caller. These methods are that + # consumption: pick the class the active backend answers. + + @classmethod + def _select_column_class( + cls, + dialect: "SQLDialectBase", + annotation: Any, + declared: Any, + ) -> Type["ColumnBase"]: + """Choose the column class for *annotation* on *dialect*. + + Order: an explicit declaration answers first; otherwise the backend's + common-type table keyed by the normalised annotation, then its extra + table keyed by the annotation itself; neither -> + :class:`ColumnTypeResolutionError`. + """ + if declared is not None: + return cls._class_from_declaration(declared) + + table = dialect.suggested_column_types() + entry = cls._table_entry_for(annotation, table) + + if entry is not None: + if entry not in table: + # Reachable only through the enum branch: the subclass walk + # can only return a key the table already has. + raise ColumnTypeResolutionError( + f"{type(dialect).__name__}.suggested_column_types() does " + f"not answer for {cls._entry_name(entry)}, which is one " + f"of the common types. Every entry must be answered -- " + f"with a column class, or with None when the backend " + f"genuinely has no workaround." + ) + suggested = table[entry] + if suggested is None: + raise ColumnTypeResolutionError( + f"{type(dialect).__name__} has no column class for " + f"{cls._entry_name(entry)}. Declare one explicitly with " + f"UseColumnType(SomeColumn) if this field's value supports " + f"operations this backend has no class for." + ) + return cls._require_column_class( + type(dialect).__name__, "suggested_column_types", entry, suggested + ) + + extras = dialect.suggested_extra_column_types() + suggested = extras.get(cls._strip_annotation(annotation)) + if suggested is not None: + return cls._require_column_class( + type(dialect).__name__, + "suggested_extra_column_types", + annotation, + suggested, + ) + + raise ColumnTypeResolutionError( + f"Cannot choose a column class for " + f"{cls._describe_annotation(annotation)}: it is not one of the " + f"types this backend answers and no UseColumnType declares one. " + f"The types it answers are: " + f"{', '.join(cls._entry_name(key) for key in table)}. Declare the " + f"operations this field's value carries with " + f"UseColumnType(SomeColumn), or annotate the field with one of the " + f"types above." + ) + + @classmethod + def _class_from_declaration(cls, declared: Any) -> Type["ColumnBase"]: + """The single class a column-type declaration names. + + Any of the forms ``Model.column_type()`` may present: a + ``UseColumnType`` marker (its class answers), a ``ColumnBase`` + subclass, or a sequence of subclasses. A sequence longer than one is + refused for now: choosing among candidates means asking a dialect + whether it covers every operation of a class, and there is no answer + to read yet. + """ + if isinstance(declared, UseColumnType): + return declared.column_class + if isinstance(declared, type) and issubclass(declared, ColumnBase): + return declared + if isinstance(declared, (list, tuple)): + classes = list(declared) + if len(classes) == 1: + return cls._class_from_declaration(classes[0]) + if not classes: + raise ColumnTypeResolutionError( + "The column-type declaration is an empty sequence." + ) + raise ColumnTypeResolutionError( + f"The column-type declaration has {len(classes)} candidates; " + f"multi-candidate resolution needs the capability declaration " + f"mechanism, which does not exist yet. Declare a single " + f"column class." + ) + raise ColumnTypeResolutionError( + f"{declared!r} is not a column-type declaration: expected a " + f"UseColumnType marker, a ColumnBase subclass, or a sequence of " + f"subclasses." + ) + + @classmethod + def _strip_annotation(cls, annotation: Any) -> Any: + """Peel ``Annotated`` and ``Optional`` off *annotation*.""" + # `typing.get_origin(Annotated[...])` returns the `Annotated` special + # form on 3.9+, but on 3.8 `typing` has no `Annotated` attribute, so + # the identity check raises AttributeError. The presence of + # `__metadata__` marks an annotated alias on every supported version. + while hasattr(annotation, "__metadata__"): + annotation = typing.get_args(annotation)[0] + + origin = typing.get_origin(annotation) + if origin is typing.Union or origin is getattr(types, "UnionType", None): + members = [a for a in typing.get_args(annotation) if a is not type(None)] + if len(members) == 1: + return cls._strip_annotation(members[0]) + return annotation + + @classmethod + def _table_entry_for(cls, annotation: Any, keys: Any) -> Any: + """The table key *annotation* normalises to, or ``None``. + + Three rules and the pydantic bridge: exact key match, ``enum.Enum`` + subclass, then a subclass walk in *keys* order (``class MyStr(str)`` + -> ``str``). The bridge is consulted last, so it can turn a failure + into an answer and can never change an answer that already existed; + its result is re-checked against the same keys. + """ + peeled = cls._strip_annotation(annotation) + if peeled in keys: + return peeled + + if isinstance(peeled, type): + if issubclass(peeled, enum.Enum): + # Checked before the walk: an enum that also subclasses + # something else (`class Weekday(int, Enum)`) stays an enum. + return enum.Enum + for key in keys: + if ( + isinstance(key, type) + and key is not peeled + and issubclass(peeled, key) + ): + return key + + from .pydantic_fields import normalize_pydantic_annotation + + bridged = normalize_pydantic_annotation(peeled) + if bridged is not None and bridged in keys: + return bridged + return None + + @classmethod + def _require_column_class( + cls, dialect_name: str, table: str, key: Any, suggested: Any + ) -> Type["ColumnBase"]: + if not (isinstance(suggested, type) and issubclass(suggested, ColumnBase)): + raise ColumnTypeResolutionError( + f"{dialect_name}.{table}()[{cls._entry_name(key)}] is " + f"{suggested!r}, which is not a ColumnBase subclass." + ) + return suggested + + @staticmethod + def _entry_name(entry: Any) -> str: + module = getattr(entry, "__module__", None) + name = getattr(entry, "__name__", None) or repr(entry) + if module and module not in ("builtins",): + return f"{module}.{name}" + return name + + @staticmethod + def _describe_annotation(annotation: Any) -> str: + name = getattr(annotation, "__name__", None) or repr(annotation) + return f"{name!r} (the annotation {annotation!r})" diff --git a/src/rhosocial/activerecord/base/fields.py b/src/rhosocial/activerecord/base/fields.py index 0ed212236..3512eea9b 100644 --- a/src/rhosocial/activerecord/base/fields.py +++ b/src/rhosocial/activerecord/base/fields.py @@ -15,6 +15,7 @@ if TYPE_CHECKING: from ..backend.expression.bases import BaseExpression, SQLDialectBase, SQLPredicate + from ..backend.expression.column_types import ColumnBase from ..backend.expression.statements.ddl_table import ( ReferentialAction, ) @@ -172,6 +173,108 @@ def __repr__(self) -> str: return f"UseSqlType({', '.join(repr(t) for t in self.data_types)})" +class UseColumnType: + """Marker for ``Annotated[T, UseColumnType(*column_classes)]``. + + Declares which **column class** (the operation set a value offers) a model + field's expressions use, instead of letting the backend suggest one. It is + the column-side twin of :class:`UseSqlType`, and the two are **strictly + independent**: + + * ``UseSqlType`` serves the DDL only -- which ``DataType`` the column is + created with -- and takes no part in CRUD or expression rendering; + * ``UseColumnType`` serves the column operations only -- what + ``Model.c.`` can do -- and never influences DDL. + + A model may declare either, both, or neither, and the framework does not + check them against each other. A field may say ``age: int`` with + ``UseSqlType(VarCharType())`` or ``UseColumnType(StringColumn())`` and both + are honoured: the first decides the stored type, the second decides the + operations, and neither is inferred from the other. This is deliberate -- + "which operations does this value support" and "how is it stored" are + different questions, and a model that wants an unusual answer to either one + should be able to give it without having to lie about the other. + + It is **not** a :class:`DDLAnnotation`: the DDL collector must not see it, + or the strict independence above would be one refactor away from being + false. + + Exactly one column class may be declared for now. The signature is variadic + (``UseSqlType`` is too, and for the same reason: declaration order is the + candidate order) but multi-candidate selection needs the operation-capability + declaration to answer "does this backend cover every operation of this + class", which does not exist yet -- so rather than silently taking the first + candidate and pretending the negotiation happened, a multi-candidate + declaration is refused here, at the point of the mistake, and says what it + is waiting for. + + Examples:: + + # A plain text value that is stored as something other than text + label: Annotated[str, UseColumnType(StringColumn)] + blob: Annotated[bytes, UseColumnType(BinaryColumn)] + + # Both sides declared independently: stored as an integer, offered as + # arithmetic on a whole number -- same thing here, and deliberately not + # cross-checked + qty: Annotated[int, UseSqlType(IntType()), UseColumnType(IntegerColumn)] + + Raises: + TypeError: No column class was given, or one of them is not a + :class:`~...backend.expression.column_types.ColumnBase` subclass. + """ + + def __init__(self, *column_classes: Type["ColumnBase"]): + from ..backend.expression.column_types import ColumnBase + + if not column_classes: + raise TypeError( + "UseColumnType requires at least one ColumnBase subclass, " + "e.g. UseColumnType(StringColumn)." + ) + for column_class in column_classes: + if not (isinstance(column_class, type) and issubclass(column_class, ColumnBase)): + # Class objects only: a column class is a type, never an + # instance. One that carried state would make the value a + # declaration rather than a class, and the resolution layer + # would have no way to hand the same class to every expression. + raise TypeError( + f"UseColumnType expects ColumnBase subclasses (classes " + f"derived from ColumnBase), got " + f"{column_class!r}. Column classes name operations, not " + f"values, so pass the class itself rather than an " + f"instance of it." + ) + if len(column_classes) > 1: + # Refused rather than resolved first-wins. Choosing among several + # candidates is a negotiation with the backend's capability + # declaration ("does this dialect cover every operation of this + # class"), and taking the first without asking would make the + # declaration a lie the caller cannot see. See the multi-candidate + # ruling in column-type-refactor.md (议题 2). + raise TypeError( + f"UseColumnType was given {len(column_classes)} column " + f"classes ({', '.join(c.__name__ for c in column_classes)}), " + f"but multi-candidate resolution needs the capability " + f"declaration mechanism, which does not exist yet: choosing " + f"among candidates means asking the dialect whether it covers " + f"every operation of a class, and there is no answer to read " + f"yet. Declare a single column class for now; when the " + f"capability declaration lands, this signature keeps its " + f"variadic shape and the candidates will be ordered by " + f"declaration order as UseSqlType's are." + ) + self.column_classes: tuple = tuple(column_classes) + #: The declared class — a convenience alias, since only one may be + #: declared. Present for the same reason as ``UseSqlType.data_type``: + #: the single-candidate case is what readers ask for, and it is what + #: the resolution layer reads. + self.column_class: Type[ColumnBase] = self.column_classes[0] + + def __repr__(self) -> str: + return f"UseColumnType({', '.join(c.__name__ for c in self.column_classes)})" + + class UseIndex(DDLAnnotation): """Marker for ``Annotated[T, UseIndex(name, ...)]``. @@ -269,10 +372,18 @@ class UseConstraint(DDLAnnotation): Example:: - # Column-level CHECK (SQL-standard, generic) + # Column-level CHECK (SQL-standard, generic). The condition is an + # explicit InPredicate node: a bare Column reference offers no + # operations by design, so the constraint builds the node itself. + from rhosocial.activerecord.backend.expression import ( + Column, InPredicate, Literal, + ) + status: Annotated[str, UseConstraint( ColumnConstraintType.CHECK, - check_condition=lambda d: Column(d, "status").in_(["open", "paid"]), + check_condition=lambda d: InPredicate( + d, Column(d, "status"), Literal(d, ("open", "paid")) + ), )] """ diff --git a/src/rhosocial/activerecord/base/pydantic_fields.py b/src/rhosocial/activerecord/base/pydantic_fields.py new file mode 100644 index 000000000..487b5bdf8 --- /dev/null +++ b/src/rhosocial/activerecord/base/pydantic_fields.py @@ -0,0 +1,367 @@ +# src/rhosocial/activerecord/base/pydantic_fields.py +"""Where a pydantic-built field's value type is mapped onto the common types. + +The protocol's vocabulary is *plain Python types*: the +common value types a column class can be suggested for. A model is free to +annotate a field with anything, and pydantic — which this project already depends +on, since its models are pydantic models — ships a family of field types that are +not plain: ``EmailStr``, ``SecretStr``, ``AnyUrl``, ``AwareDatetime``, +``ByteSize``, ``Json`` and their siblings. They are **wrapper classes** pydantic +defines, and they are not subclasses of the type they wrap; ``EmailStr`` in +2.13.5 has ``__mro__ == ('EmailStr', 'object')``. So a field annotated with one +of them lands outside the vocabulary, which makes resolution fail — the correct +answer for something genuinely unclassifiable, and the wrong answer for something +whose value type the *owner* has already declared. + +This module is the one place that bridges the two, and it is a module rather +than lines inside the normaliser so that the boundary stays visible: this is the +only file in the core that knows what a pydantic field means, and if the project +ever decides the bridge should not exist, deleting one file removes it. + +How the bridge works +-------------------- +Three groups, and every pydantic field type belongs to exactly one of them. The +completeness test (in the backend test-suite, ``test_pydantic_field_vocabulary``) +asserts precisely that: ``pydantic.types`` plus ``pydantic.networks`` minus a +documented exclusion list, partitioned into these three with nothing left over. + +1. **Already covered.** Most of pydantic's types need no bridge at all, because + they are either an ``Annotated`` alias of a plain type or a subclass of one. + ``constr``, ``conint``, ``confloat``, ``condecimal``, ``conbytes``, + ``Base64Str``, ``Base64UrlStr``, ``StrictInt`` and every ``PositiveInt``-style + constrained alias are ``Annotated[str, ...]`` and the existing + ``Annotated``-peeling reaches them; ``ByteSize`` and ``PaymentCardNumber`` are + subclasses of ``int`` and ``str`` and the existing subclass walk reaches them. + These are listed in :data:`ALREADY_COVERED` so that a regression in the + normaliser — one that stopped peeling ``Annotated``, say — is caught here + rather than surfacing as a model that suddenly will not build. + +2. **Mapped.** The class-built wrappers whose value type pydantic states + unambiguously in their own core schema. :data:`PYDANTIC_FIELD_TO_ENTRY` names + each one and the protocol entry it normalises to. + +3. **Not mapped.** Types with no plain value type, or with one the mapping would + be inventing. :data:`PYDANTIC_FIELD_NOT_MAPPED` lists them with the reason, and + a field annotated with one of these fails exactly as it did before this module + existed — declaring ``UseColumnType`` remains the route forward. + +Ordering inside resolution, and why the bridge is last +----------------------------------------------------- +The bridge is consulted **after** an explicit ``UseColumnType`` (which wins +everywhere and is unaffected) and **after** the existing exact-match, enum and +subclass rules (which must keep answering the plain vocabulary exactly as they +always did). It sits between "the annotation matched something" and "the +annotation is unclassifiable", so it can only turn a failure into an answer and +can never change an answer that already existed. + +That ordering is what keeps it from being a universal column by another name: a +backend that answers ``None`` for the resulting entry still refuses, and +a backend that answers a column class still chooses it. The bridge decides what +*Python type* a pydantic wrapper means — never which column class to use. +""" + +# src/rhosocial/activerecord/base/pydantic_fields.py +import datetime +import decimal +import enum +import uuid +from typing import Any, Dict, Type + +# --------------------------------------------------------------------------- +# 1. Already covered by the existing normalisation +# --------------------------------------------------------------------------- + +#: pydantic field types that need no bridge: ``Annotated`` aliases of a plain type, +#: or subclasses of one. Every one of these resolves through the peeling and +#: subclass-walk rules the protocol already had, and this tuple exists so that a +#: regression in those rules is caught by a test rather than by a model. +#: +#: The groups are spelled out because they are different mechanisms: +#: +#: * ``Annotated[str, ...]`` and friends — ``constr``, ``conint``, ``confloat``, +#: ``condecimal``, ``conbytes``, ``Base64Str``, ``Base64UrlStr``, ``StrictInt``, +#: ``StrictStr``, ``PositiveInt``, ``NegativeFloat``, ``FiniteFloat`` and the +#: rest of the constrained aliases. ``constr`` is a *function* returning an +#: annotated alias, so it appears here as its result's type, which is also why +#: ``constr(...)`` itself needs no entry: it is already ``str``; +#: * subclasses — ``ByteSize`` is an ``int`` subclass and ``PaymentCardNumber`` a +#: ``str`` subclass, so the subclass walk files them under the entry they +#: extend. ``PaymentCardBrand`` is a ``str`` subclass too, but its core schema +#: says ``enum``, so it is deliberately **not** here — see +#: :data:`PYDANTIC_FIELD_NOT_MAPPED`. +ALREADY_COVERED = ( + "constr", + "conint", + "confloat", + "condecimal", + "conbytes", + "constr", + "Base64Str", + "Base64UrlStr", + "Base64Bytes", + "Base64UrlBytes", + "StrictInt", + "StrictStr", + "StrictFloat", + "StrictBool", + "StrictBytes", + "PositiveInt", + "NonNegativeInt", + "NegativeInt", + "NonPositiveInt", + "PositiveFloat", + "NonNegativeFloat", + "NegativeFloat", + "NonPositiveFloat", + "FiniteFloat", + "ByteSize", + "PaymentCardNumber", + "UUID1", + "UUID3", + "UUID4", + "UUID5", + "UUID6", + "UUID7", + "UUID8", +) + +# --------------------------------------------------------------------------- +# 2. Mapped: pydantic states the value type, and it is a protocol entry +# --------------------------------------------------------------------------- + +#: The protocol entry a mapped pydantic field normalises to. +#: +#: Every entry here is one pydantic declares in its own core schema — measured +#: on pydantic 2.13.5 with ``TypeAdapter(T).core_schema`` — and each maps to a +#: common Python type, so the backend's own table still answers for it and a +#: backend that answers ``None`` still refuses. +#: +#: ``url`` is not in the vocabulary, and the ``AnyUrl`` family is mapped to ``str`` +#: on the strength of pydantic's own schema wording — a URL *is* a string, and the +#: constraints that make it a URL are pydantic's to enforce, not the column's. +#: The same reasoning covers the DSN aliases (``AmqpDsn``, ``MySQLDsn``, …), which +#: are URLs with a scheme pydantic knows. +#: +#: ``IPvAnyAddress`` and the rest are mapped to ``str`` for the same reason, with +#: one caveat recorded rather than smoothed over: ``IPv4Address``, +#: ``IPv4Interface``, ``IPv4Network`` and their IPv6 counterparts declare +#: ``lax-or-strict`` with **no** inner value type, so pydantic does not actually +#: state that they are strings — they are accepted from either, and the +#: validated instance is what the DB sees. Mapping them to ``str`` is a decision +#: this table makes, not a fact it reads, which is why they are grouped with a +#: comment instead of being cited as pydantic-declared. +PYDANTIC_FIELD_TO_ENTRY: Dict[Any, Any] = { + # --- pydantic states `str` in its core schema ------------------------- + "EmailStr": str, + "NameEmail": str, + "SecretStr": str, + # --- pydantic states `bytes` (via lax-or-strict, same caveat) --------- + "SecretBytes": bytes, + # --- pydantic states `datetime` / `date` ------------------------------ + "AwareDatetime": datetime.datetime, + "NaiveDatetime": datetime.datetime, + "PastDatetime": datetime.datetime, + "FutureDatetime": datetime.datetime, + "PastDate": datetime.date, + "FutureDate": datetime.date, + # --- pydantic states `url`; a URL is a string ------------------------- + "AnyUrl": str, + "AnyHttpUrl": str, + "HttpUrl": str, + "FileUrl": str, + "FtpUrl": str, + "WebsocketUrl": str, + "AnyWebsocketUrl": str, + "AmqpDsn": str, + "ClickHouseDsn": str, + "CockroachDsn": str, + "KafkaDsn": str, + "MariaDBDsn": str, + "MongoDsn": str, + "MySQLDsn": str, + "NatsDsn": str, + "PostgresDsn": str, + "RedisDsn": str, + "SnowflakeDsn": str, + # --- pydantic states nothing; this table decides ---------------------- + "IPv4Address": str, + "IPv4Interface": str, + "IPv4Network": str, + "IPv6Address": str, + "IPv6Interface": str, + "IPv6Network": str, + "IPvAnyAddress": str, + "IPvAnyInterface": str, + "IPvAnyNetwork": str, + # --- the JSON bridge the backend tables support ----------------------- + "Json": dict, +} + +# --------------------------------------------------------------------------- +# 3. Not mapped: no plain value type, or one this table would be inventing +# --------------------------------------------------------------------------- + +#: pydantic field types that stay outside the vocabulary, with the reason. +#: +#: A field annotated with one of these fails to resolve exactly as it did before +#: this module existed, and ``UseColumnType`` remains the way past it. Nothing +#: here is a gap to be filled later; each is a place where a mapping would be a +#: decision the table is not entitled to make. +#: +#: ``DirectoryPath``, ``FilePath``, ``NewPath`` and ``SocketPath`` are the +#: clearest case: their core schema's inner type is ``pathlib.Path``, and +#: ``Path`` is **not** a vocabulary entry, so there is nothing to map *to*. +#: Substituting ``str`` would lose the only thing that makes them a filesystem +#: path rather than text. +#: +#: ``PaymentCardBrand`` is a ``str`` subclass, so the subclass walk will happily +#: file it under ``str`` — but its core schema says ``enum``, and it is a +#: *controlled* vocabulary of four brands rather than free text. It is named here +#: so the disagreement is recorded; the subclass walk still answers, and a reader +#: comparing the two lists can see that it answers by type and not by meaning. +#: +#: ``ImportString`` is a dotted import path with no database type of any kind. +#: ``Json`` is mapped to ``dict`` (see :data:`PYDANTIC_FIELD_TO_ENTRY`) because +#: every backend's table answers ``dict -> JSONColumn``, which is the JSON bridge +#: the pairing work measured — a ``Json`` field holding an array still stores as +#: JSON, and the value layer's ``json.dumps`` on bind is the same requirement +#: ``dict`` already carries. +PYDANTIC_FIELD_NOT_MAPPED = ( + "DirectoryPath", + "FilePath", + "NewPath", + "SocketPath", + "PaymentCardBrand", + "ImportString", +) + +# --------------------------------------------------------------------------- +# The names that are skipped when enumerating pydantic's field types +# --------------------------------------------------------------------------- + +#: Public names of ``pydantic.types`` / ``pydantic.networks`` that are **not** +#: field types, and why. The completeness test subtracts these before asserting +#: that everything else is classified, because a test that expected every public +#: name to be a field type would fail on ``ValidationError``. +#: +#: Kept as one frozenset of names rather than filtered by kind, because the kinds +#: are not always distinguishable at runtime: ``EncodedStr`` is a validator +#* function, ``ValidationInfo`` a dataclass, and ``TypeAdapter`` a class you +#: would never annotate a field with — and all three look like types to +#: ``isinstance(x, type)``. +NOT_FIELD_TYPES = frozenset({ + # validators, validators-in-progress and their wrappers + "AfterValidator", "BeforeValidator", "WrapValidator", "PlainValidator", + "InstanceOf", "SkipValidation", "ValidateAs", "StringConstraints", + "EncodedStr", "EncodedBytes", "EncoderProtocol", "SchemaSerializer", + "WrapSerializer", "PlainSerializer", + # errors and warnings + "PydanticCustomError", "PydanticUserError", "PydanticInvalidForJsonSchema", + "PydanticSchemaGenerationError", "PydanticUndefinedAnnotation", + "PydanticForbiddenQualifier", "PydanticDeprecatedSince20", + "PydanticDeprecatedSince210", "PydanticDeprecatedSince211", + "PydanticDeprecatedSince212", "PydanticDeprecatedSince26", + "PydanticDeprecatedSince29", "PydanticExperimentalWarning", + "PydanticDeprecationWarning", "ValidationError", + "PydanticSerializationUnexpectedValue", + # configuration and metadata + "ConfigDict", "BaseConfig", "BaseMetadata", "AliasChoices", "AliasPath", + "AliasGenerator", "WithJsonSchema", "GetPydanticSchema", + "GetCoreSchemaHandler", "GetJsonSchemaHandler", "UrlConstraints", + "AllowInfNan", "FailFast", "Strict", "Tag", "Discriminator", "MaxLen", + "MinLen", "Pattern", "UuidVersion", "OnErrorOmit", "Ignored", + # model machinery, generics and protocols + "BaseModel", "RootModel", "TypeAdapter", "TypeAliasType", "TypeVar", + "Generic", "Union", "Any", "Enum", "Hashable", "ModuleType", "PathType", + "Path", "Decimal", "date", "datetime", "UUID", "object", "Iterator", + "ValidationInfo", "SerializationInfo", "FieldSerializationInfo", + "ModelWrapValidatorHandler", "ValidatorFunctionWrapHandler", + "SerializerFunctionWrapHandler", "MultiHostHost", "Secret", + "PydanticUseCaseMark", +}) + + +# --------------------------------------------------------------------------- +# The bridge itself +# --------------------------------------------------------------------------- + + +def _pydantic_module(): + """The ``pydantic`` package, or ``None`` when it is not importable. + + Imported lazily and defensively: the bridge is only consulted for an + annotation that nothing else could classify, so a project that never + annotates a field with a pydantic wrapper pays nothing. Core does depend on + pydantic for its model layer, so in practice this always succeeds — but the + fallback keeps the expression layer importable on a stripped install, which + is the same reason the module is not imported at the top of the file. + """ + try: + import pydantic # noqa: PLC0415 -- optional at import time by design + return pydantic + except Exception: # pragma: no cover - only on a stripped install + return None + + +def mapped_pydantic_entry(name: str) -> Any: + """The protocol entry pydantic's field type *name* maps to, or ``None``. + + Looked up by **name** rather than by class object, because the classes are + only reachable through ``pydantic.networks`` / ``pydantic.types`` and a name + is what survives being written in a table a human can read and diff. The + classes are then resolved through the package, so the mapping cannot refer to + a type pydantic has since renamed: an unknown name simply has no answer, and + the completeness test is what catches a rename. + """ + return PYDANTIC_FIELD_TO_ENTRY.get(name) + + +def is_pydantic_field_name(name: str) -> bool: + """Whether *name* is one this bridge classifies at all.""" + return name in PYDANTIC_FIELD_TO_ENTRY or name in PYDANTIC_FIELD_NOT_MAPPED + + +def normalize_pydantic_annotation(annotation: Any) -> Any: + """The value type *annotation* stands for, or ``None`` if unknown. + + The single entry point the protocol's normaliser calls, and the only thing it + calls. An annotation that is not a pydantic-defined type gets ``None`` back, + which the caller treats exactly as it treated an unmatched annotation before + this module existed. + + Resolution order inside the bridge: + + 1. The annotation's **class name** against :data:`PYDANTIC_FIELD_TO_ENTRY`, + then :data:`PYDANTIC_FIELD_NOT_MAPPED`. A name hit is the whole answer and + nothing further is consulted — pydantic's declaration and this table agree, + and reading pydantic's schema as well would only slow the common path down + and could disagree with the table's recorded decision. + 2. Nothing. There is no second step: pydantic is *asked* by nothing in this + module, because asking means runtime introspection of + ``TypeAdapter(T).core_schema`` on every unclassified annotation, and the + cases where that would add an answer are exactly the ones already written + down here. If pydantic later ships a new field type, the completeness test + fails and the table gains a line — a visible diff, rather than a silently + different answer. + """ + name = getattr(annotation, "__name__", None) + if name is None: + return None + + if name in PYDANTIC_FIELD_TO_ENTRY: + return PYDANTIC_FIELD_TO_ENTRY[name] + + # Deliberately unmapped, or not ours at all: both are "no answer from here", + # and the caller's error message is what tells the two apart. + return None + + +__all__ = [ + "ALREADY_COVERED", + "NOT_FIELD_TYPES", + "PYDANTIC_FIELD_NOT_MAPPED", + "PYDANTIC_FIELD_TO_ENTRY", + "is_pydantic_field_name", + "mapped_pydantic_entry", + "normalize_pydantic_annotation", +] diff --git a/src/rhosocial/activerecord/field/__init__.py b/src/rhosocial/activerecord/field/__init__.py index 1bfd79cb2..d77ece0ca 100644 --- a/src/rhosocial/activerecord/field/__init__.py +++ b/src/rhosocial/activerecord/field/__init__.py @@ -7,10 +7,12 @@ from .soft_delete import SoftDeleteMixin, DefaultSoftDeleteMixin, AsyncSoftDeleteMixin, DefaultAsyncSoftDeleteMixin from .uuid import UUIDMixin from .composite_pk import CompositePKMixin +from .field_config import FieldConfigValidationHandler __all__ = [ "IntegerPKMixin", "TimestampMixin", "DefaultTimestampMixin", "OptimisticLockMixin", "DefaultOptimisticLockMixin", "SoftDeleteMixin", "DefaultSoftDeleteMixin", "AsyncSoftDeleteMixin", "DefaultAsyncSoftDeleteMixin", "UUIDMixin", "CompositePKMixin", + "FieldConfigValidationHandler", ] diff --git a/src/rhosocial/activerecord/field/field_config.py b/src/rhosocial/activerecord/field/field_config.py new file mode 100644 index 000000000..1ac882c3a --- /dev/null +++ b/src/rhosocial/activerecord/field/field_config.py @@ -0,0 +1,64 @@ +# src/rhosocial/activerecord/field/field_config.py +"""Class-construction-time validation for field mixin configuration. + +Semantics mixins (``SoftDeleteMixin``, ``TimestampMixin``, +``OptimisticLockMixin``) declare *knobs* — class attributes naming a model +field, e.g. ``__deleted_at_field__ = "deleted_at"``. The model must actually +declare that field, otherwise every generated query silently references a +column that does not exist. + +Why a metaclass feature handler +------------------------------- +The obvious place for such a check is the mixin's ``__init__``, and that is +where it used to live. It does not work: in the documented declaration order + +.. code-block:: python + + class Order(ActiveRecord, SoftDeleteMixin): + ... + +Pydantic's ``BaseModel.__init__`` precedes the mixin in the MRO, so the +mixin's ``__init__`` never runs and the validation is skipped entirely. + +``__init_subclass__`` is not a usable replacement either — it fires while +the class body is still being built, before Pydantic has collected +``model_fields``, so ``model_fields`` is empty and every knob would look +missing. + +:class:`FieldConfigValidationHandler` therefore runs from the metaclass +feature-handler hook (:meth:`ActiveRecordMetaclass.__new__` step 4), which +executes after the class object exists and ``model_fields`` is complete. +Two consequences, both improvements over the previous behaviour: + +* the check is independent of base-class order, and +* it fires at **class definition time** rather than at first instantiation, + so a misconfigured model fails at import instead of at first query. +""" + +from typing import Any + + +class FieldConfigValidationHandler: + """Runs every mixin-declared ``_validate_model_config`` on the new class. + + A mixin opts in by declaring this handler in ``_feature_handlers`` and + exposing a ``_validate_model_config`` classmethod. The handler discovers + those classmethods by walking the MRO and reading each class's own + ``__dict__`` — it never infers anything from attribute names, so adding + a mixin is a one-line declaration rather than a naming convention to + remember. + """ + + @classmethod + def handle(cls, model_class: Any) -> None: + """Validate the configuration of every field mixin on *model_class*.""" + for klass in model_class.__mro__: + validator = klass.__dict__.get("_validate_model_config") + if validator is not None: + # A classmethod accessed via __dict__ is already bound to + # `klass`; rebind it to the model under construction so the + # error message names the model, not the mixin. + validator.__func__(model_class) + + +__all__ = ["FieldConfigValidationHandler"] diff --git a/src/rhosocial/activerecord/field/soft_delete.py b/src/rhosocial/activerecord/field/soft_delete.py index 0c68bbc33..0a4b8cbfe 100644 --- a/src/rhosocial/activerecord/field/soft_delete.py +++ b/src/rhosocial/activerecord/field/soft_delete.py @@ -21,10 +21,11 @@ from pydantic import Field from ..backend.expression.core import Column -from ..backend.expression import ComparisonPredicate, Literal +from ..backend.expression import ComparisonPredicate, IsNullPredicate, Literal from ..interface import ModelEvent from ..interface.update import IDeleteBehavior from ..query import ActiveQuery +from .field_config import FieldConfigValidationHandler class SoftDeleteMixin(IDeleteBehavior): @@ -32,19 +33,25 @@ class SoftDeleteMixin(IDeleteBehavior): The model (or a subclass like :class:`DefaultSoftDeleteMixin`) declares a datetime field and announces it via ``__deleted_at_field__``; it must - exist or instantiation fails fast. + exist or the class is rejected at definition time. """ __deleted_at_field__: ClassVar[str] = "deleted_at" + _feature_handlers = [FieldConfigValidationHandler] + def __init__(self, **data): super().__init__(**data) - self.__class__._validate_soft_delete_config() self.on(ModelEvent.BEFORE_DELETE, self._mark_as_deleted) @classmethod - def _validate_soft_delete_config(cls) -> None: - """Fail fast when the configured field name does not exist.""" + def _validate_model_config(cls) -> None: + """Fail fast when the configured field name does not exist. + + Invoked by :class:`FieldConfigValidationHandler` from the metaclass, + so it runs once at class definition — see that module for why this + cannot live in ``__init__``. + """ field_name = cls.__deleted_at_field__ if field_name not in cls.model_fields: raise TypeError( @@ -77,7 +84,12 @@ def prepare_delete(self) -> Dict[str, Any]: def query(cls) -> "ActiveQuery": """Return query builder excluding soft-deleted records.""" backend = cls.backend() - non_deleted_condition = Column(backend.dialect, cls._deleted_at_column()).is_null() + # An explicit node rather than the column's operator: the reference is + # bare (no annotation consulted), and a bare Column offers no + # operations by design. + non_deleted_condition = IsNullPredicate( + backend.dialect, Column(backend.dialect, cls._deleted_at_column()) + ) return super().query().where(non_deleted_condition) @classmethod @@ -89,7 +101,9 @@ def query_with_deleted(cls) -> "ActiveQuery": def query_only_deleted(cls) -> "ActiveQuery": """Return query for only soft-deleted records.""" backend = cls.backend() - deleted_condition = Column(backend.dialect, cls._deleted_at_column()).is_not_null() + deleted_condition = IsNullPredicate( + backend.dialect, Column(backend.dialect, cls._deleted_at_column()), is_not=True + ) return super().query().where(deleted_condition) def _build_restore_condition(self): @@ -114,7 +128,7 @@ def _build_restore_condition(self): else: pk_column = Column(dialect, self.primary_key()) pk_value = getattr(self, self.primary_key()) - condition_expr = pk_column == pk_value + condition_expr = ComparisonPredicate(dialect, "=", pk_column, Literal(dialect, pk_value)) return condition_expr diff --git a/src/rhosocial/activerecord/field/timestamp.py b/src/rhosocial/activerecord/field/timestamp.py index 94729731a..f4e22b438 100644 --- a/src/rhosocial/activerecord/field/timestamp.py +++ b/src/rhosocial/activerecord/field/timestamp.py @@ -21,6 +21,7 @@ from ..interface import ModelEvent from ..interface.update import IUpdateBehavior from ..interface.model import IActiveRecord, IAsyncActiveRecord +from .field_config import FieldConfigValidationHandler class TimestampMixin(IUpdateBehavior): @@ -34,16 +35,22 @@ class TimestampMixin(IUpdateBehavior): __created_at_field__: ClassVar[str] = "created_at" __updated_at_field__: ClassVar[str] = "updated_at" + _feature_handlers = [FieldConfigValidationHandler] + def __init__(self, **data): super().__init__(**data) - self.__class__._validate_timestamp_config() # Use separate events for INSERT and UPDATE operations self.on(ModelEvent.BEFORE_INSERT, self._set_timestamps_on_insert) self.on(ModelEvent.BEFORE_UPDATE, self._set_updated_at) @classmethod - def _validate_timestamp_config(cls) -> None: - """Fail fast when the configured field names do not exist.""" + def _validate_model_config(cls) -> None: + """Fail fast when the configured field names do not exist. + + Invoked by :class:`FieldConfigValidationHandler` from the metaclass, + so it runs once at class definition — see that module for why this + cannot live in ``__init__``. + """ for knob in ("__created_at_field__", "__updated_at_field__"): field_name = getattr(cls, knob) if field_name not in cls.model_fields: diff --git a/src/rhosocial/activerecord/field/uuid.py b/src/rhosocial/activerecord/field/uuid.py index beb9fe705..1dcef3856 100644 --- a/src/rhosocial/activerecord/field/uuid.py +++ b/src/rhosocial/activerecord/field/uuid.py @@ -2,7 +2,7 @@ """Module providing UUID functionality.""" import uuid -from typing import Dict, Any +from typing import Any, Dict from pydantic import Field from ..interface.update import IDataPreparationBehavior @@ -12,6 +12,18 @@ class UUIDMixin(IDataPreparationBehavior): """Adds UUID primary key support. Automatically generates UUIDs for new records. + + Generation happens in Python, not in the database. That is deliberate: it + keeps the value available before the INSERT is built, so a model can use + its own primary key in the same transaction without a round trip, and it + works unchanged on backends with no UUID function (SQLite has none). A + model that would rather let the database generate the value can render + :class:`~...expression.uuid.UUIDGenerationExpression` into a column default + instead — the two approaches are independent. + + The field is annotated ``uuid.UUID`` and left to normal type inference for + its column type; see :class:`~...expression.types.UUIDType` for how a + backend declares explicit UUID storage instead. """ id: uuid.UUID = Field(default_factory=uuid.uuid4) diff --git a/src/rhosocial/activerecord/field/version.py b/src/rhosocial/activerecord/field/version.py index e30f8db99..38933a981 100644 --- a/src/rhosocial/activerecord/field/version.py +++ b/src/rhosocial/activerecord/field/version.py @@ -48,6 +48,7 @@ class Article(OptimisticLockMixin, ActiveRecord): from ..interface import ModelEvent from ..interface.update import IUpdateBehavior from ..interface.model import IActiveRecord, IAsyncActiveRecord +from .field_config import FieldConfigValidationHandler if sys.version_info >= (3, 9): from typing import Annotated @@ -72,6 +73,8 @@ class OptimisticLockMixin(IUpdateBehavior): __version_field__: ClassVar[str] = "version" __version_increment_by__: ClassVar[int] = 1 + _feature_handlers = [FieldConfigValidationHandler] + # Framework bookkeeping — deliberately private and invisible: the last # version value known to be committed to the database. It must never # track in-memory user assignments, otherwise the lock condition could @@ -80,9 +83,12 @@ class OptimisticLockMixin(IUpdateBehavior): _version_snapshot: int = 1 def __init__(self, **data): - """Initialise mixin, validate configuration and register event handlers.""" + """Initialise the mixin and register its event handlers. + + Configuration is validated by the metaclass at class definition + time, not here — see :mod:`.field_config`. + """ super().__init__(**data) - self.__class__._validate_version_config() self._version_snapshot = self.version_value self.on(ModelEvent.BEFORE_INSERT, self._handle_version_before_insert) self.on(ModelEvent.AFTER_INSERT, self._handle_version_after_insert) @@ -93,8 +99,13 @@ def __init__(self, **data): # Configuration # ------------------------------------------------------------------ @classmethod - def _validate_version_config(cls) -> None: - """Fail fast when ``__version_field__`` does not name a real field.""" + def _validate_model_config(cls) -> None: + """Fail fast when ``__version_field__`` does not name a real field. + + Invoked by :class:`FieldConfigValidationHandler` from the metaclass, + so it runs once at class definition — see that module for why this + cannot live in ``__init__``. + """ field_name = cls.__version_field__ if field_name not in cls.model_fields: raise TypeError( @@ -140,13 +151,17 @@ def get_update_conditions(self) -> List[SQLPredicate]: """ if self.is_new_record: return [] - from ..backend.expression.core import Column + from ..backend.expression.core import Column, Literal + from ..backend.expression.predicates import ComparisonPredicate backend = self.backend() - return [ - Column(backend.dialect, self._version_column_name()) - == self._version_snapshot - ] + dialect = backend.dialect + column = Column(dialect, self._version_column_name()) + # An explicit node, not the column's own operator: the bare Column is a + # reference and carries no operations, so ``column == value`` would be + # Python's identity answer (False) rather than the optimistic-lock + # predicate this is. A silently-always-false check would drop the lock. + return [ComparisonPredicate(dialect, "=", column, Literal(dialect, self._version_snapshot))] def get_update_expressions(self) -> Dict[str, SQLValueExpression]: """Add the version increment to the UPDATE SET clause. @@ -158,10 +173,12 @@ def get_update_expressions(self) -> Dict[str, SQLValueExpression]: """ if self.is_new_record: return {} - from ..backend.expression.core import Column + from ..backend.expression.column_types import IntegerColumn backend = self.backend() - column = Column(backend.dialect, self._version_column_name()) + # A version is always a whole number, so the column carries integer + # operations; the bare Column carries none and cannot be incremented. + column = IntegerColumn(backend.dialect, self._version_column_name()) return {self._version_field_name(): column + self._version_increment()} # ------------------------------------------------------------------ diff --git a/src/rhosocial/activerecord/py.typed b/src/rhosocial/activerecord/py.typed new file mode 100644 index 000000000..e69de29bb diff --git a/src/rhosocial/activerecord/query/active_query.py b/src/rhosocial/activerecord/query/active_query.py index 2fad8e4a8..73c066636 100644 --- a/src/rhosocial/activerecord/query/active_query.py +++ b/src/rhosocial/activerecord/query/active_query.py @@ -326,14 +326,14 @@ def update_all(self, values: Dict[str, object]) -> int: Example: User.query().where(User.c.status == 'inactive').update_all({User.c.status: 'archived'}) """ - from ..backend.expression import Column + from ..backend.expression import ColumnBase from ..backend.options import UpdateOptions backend = self.backend() data = {} for key, value in values.items(): - if isinstance(key, Column): + if isinstance(key, ColumnBase): col_name = key.name elif isinstance(key, str): col_name = self.model_class.get_column_name(key) @@ -689,14 +689,14 @@ async def update_all(self, values: Dict[str, object]) -> int: Returns: Number of affected rows. """ - from ..backend.expression import Column + from ..backend.expression import ColumnBase from ..backend.options import UpdateOptions backend = self.backend() data = {} for key, value in values.items(): - if isinstance(key, Column): + if isinstance(key, ColumnBase): col_name = key.name elif isinstance(key, str): col_name = self.model_class.get_column_name(key) diff --git a/src/rhosocial/activerecord/query/range.py b/src/rhosocial/activerecord/query/range.py index aa09409f2..88c705e4c 100644 --- a/src/rhosocial/activerecord/query/range.py +++ b/src/rhosocial/activerecord/query/range.py @@ -3,10 +3,41 @@ from typing import List, Union, Tuple, Any, TYPE_CHECKING -from ..backend.expression import Column, BaseExpression +from ..backend.expression import ( + Column, + BaseExpression, + BetweenPredicate, + ComparisonPredicate, + InPredicate, + IsNullPredicate, + LikePredicate, + Literal, + LogicalPredicate, + Subquery, +) if TYPE_CHECKING: # pragma: no cover from ..interface.query import IQuery + from ..backend.expression.bases import SQLPredicate + + +def _in_predicate(dialect, expr: BaseExpression, values) -> "SQLPredicate": + """The explicit ``IN`` node, so a bare column reference needs no mixin. + + A column handed to these methods may be a name in quotes, which resolves + to the bare :class:`~...expression.core.Column` — a reference that offers + no operations by design. The query layer therefore builds its predicates + explicitly rather than through the column's own operators, and this helper + mirrors :meth:`~...mixins.ComparisonMixin.in_` exactly: an ActiveQuery-like + object renders as a subquery, an expression passes through, and anything + else is bound as one literal holding the values. + """ + to_query_expression = getattr(values, "to_query_expression", None) + if callable(to_query_expression): + return InPredicate(dialect, expr, Subquery(dialect, to_query_expression())) + if isinstance(values, BaseExpression): + return InPredicate(dialect, expr, values) + return InPredicate(dialect, expr, Literal(dialect, tuple(values))) class RangeQueryMixin: @@ -84,7 +115,8 @@ def in_list( return self col_expr = self._get_col_expr(column) - predicate = col_expr.in_(list(values)) + dialect = self.backend().dialect + predicate = _in_predicate(dialect, col_expr, values) return self.where(predicate) def not_in( @@ -124,7 +156,10 @@ def not_in( return self col_expr = self._get_col_expr(column) - predicate = col_expr.not_in(list(values)) + dialect = self.backend().dialect + predicate = LogicalPredicate( + dialect, "NOT", _in_predicate(dialect, col_expr, values) + ) return self.where(predicate) def between(self, column: Union[str, BaseExpression], start: Any, end: Any) -> "IQuery": @@ -151,7 +186,10 @@ def between(self, column: Union[str, BaseExpression], start: Any, end: Any) -> " >>> User.query().between('age', 18, 30) """ col_expr = self._get_col_expr(column) - predicate = col_expr.between(start, end) + dialect = self.backend().dialect + predicate = BetweenPredicate( + dialect, col_expr, Literal(dialect, start), Literal(dialect, end) + ) return self.where(predicate) def not_between(self, column: Union[str, BaseExpression], start: Any, end: Any) -> "IQuery": @@ -178,7 +216,10 @@ def not_between(self, column: Union[str, BaseExpression], start: Any, end: Any) >>> User.query().not_between('age', 18, 30) """ col_expr = self._get_col_expr(column) - predicate = ~(col_expr.between(start, end)) + dialect = self.backend().dialect + predicate = ~BetweenPredicate( + dialect, col_expr, Literal(dialect, start), Literal(dialect, end) + ) return self.where(predicate) def like(self, column: Union[str, BaseExpression], pattern: str) -> "IQuery": @@ -204,7 +245,8 @@ def like(self, column: Union[str, BaseExpression], pattern: str) -> "IQuery": >>> User.query().like('name', 'John%') """ col_expr = self._get_col_expr(column) - predicate = col_expr.like(pattern) + dialect = self.backend().dialect + predicate = LikePredicate(dialect, "LIKE", col_expr, Literal(dialect, pattern)) return self.where(predicate) def not_like(self, column: Union[str, BaseExpression], pattern: str) -> "IQuery": @@ -226,7 +268,8 @@ def not_like(self, column: Union[str, BaseExpression], pattern: str) -> "IQuery" >>> User.query().not_like(User.c.name, 'Admin%') """ col_expr = self._get_col_expr(column) - predicate = ~(col_expr.like(pattern)) + dialect = self.backend().dialect + predicate = ~LikePredicate(dialect, "LIKE", col_expr, Literal(dialect, pattern)) return self.where(predicate) def ilike(self, column: Union[str, BaseExpression], pattern: str) -> "IQuery": @@ -249,7 +292,8 @@ def ilike(self, column: Union[str, BaseExpression], pattern: str) -> "IQuery": >>> User.query().ilike(User.c.name, 'john%') """ col_expr = self._get_col_expr(column) - predicate = col_expr.ilike(pattern) + dialect = self.backend().dialect + predicate = LikePredicate(dialect, "ILIKE", col_expr, Literal(dialect, pattern)) return self.where(predicate) def not_ilike(self, column: Union[str, BaseExpression], pattern: str) -> "IQuery": @@ -293,7 +337,8 @@ def is_null(self, column: Union[str, BaseExpression]) -> "IQuery": >>> User.query().is_null(User.c.deleted_at) """ col_expr = self._get_col_expr(column) - predicate = col_expr.is_null() + dialect = self.backend().dialect + predicate = IsNullPredicate(dialect, col_expr) return self.where(predicate) def is_not_null(self, column: Union[str, BaseExpression]) -> "IQuery": @@ -314,7 +359,8 @@ def is_not_null(self, column: Union[str, BaseExpression]) -> "IQuery": >>> User.query().is_not_null(User.c.updated_at) """ col_expr = self._get_col_expr(column) - predicate = col_expr.is_not_null() + dialect = self.backend().dialect + predicate = IsNullPredicate(dialect, col_expr, is_not=True) return self.where(predicate) def greater_than(self, column: Union[str, BaseExpression], value: Any) -> "IQuery": @@ -336,7 +382,8 @@ def greater_than(self, column: Union[str, BaseExpression], value: Any) -> "IQuer >>> User.query().greater_than(User.c.age, 18) """ col_expr = self._get_col_expr(column) - predicate = col_expr > value + dialect = self.backend().dialect + predicate = ComparisonPredicate(dialect, ">", col_expr, Literal(dialect, value)) return self.where(predicate) def greater_than_or_equal(self, column: Union[str, BaseExpression], value: Any) -> "IQuery": @@ -358,7 +405,8 @@ def greater_than_or_equal(self, column: Union[str, BaseExpression], value: Any) >>> User.query().greater_than_or_equal(User.c.age, 18) """ col_expr = self._get_col_expr(column) - predicate = col_expr >= value + dialect = self.backend().dialect + predicate = ComparisonPredicate(dialect, ">=", col_expr, Literal(dialect, value)) return self.where(predicate) def less_than(self, column: Union[str, BaseExpression], value: Any) -> "IQuery": @@ -380,7 +428,8 @@ def less_than(self, column: Union[str, BaseExpression], value: Any) -> "IQuery": >>> User.query().less_than(User.c.age, 65) """ col_expr = self._get_col_expr(column) - predicate = col_expr < value + dialect = self.backend().dialect + predicate = ComparisonPredicate(dialect, "<", col_expr, Literal(dialect, value)) return self.where(predicate) def less_than_or_equal(self, column: Union[str, BaseExpression], value: Any) -> "IQuery": @@ -402,7 +451,8 @@ def less_than_or_equal(self, column: Union[str, BaseExpression], value: Any) -> >>> User.query().less_than_or_equal(User.c.age, 65) """ col_expr = self._get_col_expr(column) - predicate = col_expr <= value + dialect = self.backend().dialect + predicate = ComparisonPredicate(dialect, "<=", col_expr, Literal(dialect, value)) return self.where(predicate) def __init__(self, *args, **kwargs): diff --git a/src/rhosocial/activerecord/relation/async_descriptors.py b/src/rhosocial/activerecord/relation/async_descriptors.py index 508f344a7..2d193d0e1 100644 --- a/src/rhosocial/activerecord/relation/async_descriptors.py +++ b/src/rhosocial/activerecord/relation/async_descriptors.py @@ -310,6 +310,7 @@ def query_method(instance): query = related_model.query() backend = related_model.backend() from ..backend.expression.core import Column + from ..backend.expression import ComparisonPredicate, Literal # Add appropriate foreign key condition based on relationship type if isinstance(self, AsyncBelongsTo): @@ -325,7 +326,9 @@ def query_method(instance): fk_value = getattr(instance, fk_col) if fk_value is not None: pk_column = Column(backend.dialect, pk_col, table=related_model.table_name()) - query = query.where(pk_column == fk_value) + query = query.where( + ComparisonPredicate(backend.dialect, "=", pk_column, Literal(backend.dialect, fk_value)) + ) else: pk_cols = instance.primary_key_columns() fk_cols = self.foreign_key if isinstance(self.foreign_key, tuple) else (self.foreign_key,) @@ -338,7 +341,9 @@ def query_method(instance): pk_value = getattr(instance, pk_col) if pk_value is not None: fk_column = Column(backend.dialect, fk_col, table=related_model.table_name()) - query = query.where(fk_column == pk_value) + query = query.where( + ComparisonPredicate(backend.dialect, "=", fk_column, Literal(backend.dialect, pk_value)) + ) return query diff --git a/src/rhosocial/activerecord/relation/descriptors.py b/src/rhosocial/activerecord/relation/descriptors.py index ce6797d32..0a28c118f 100644 --- a/src/rhosocial/activerecord/relation/descriptors.py +++ b/src/rhosocial/activerecord/relation/descriptors.py @@ -11,6 +11,7 @@ from .interfaces import IRelationValidation, IRelationManagement, IRelationLoader from .type_resolver import evaluate_annotation, resolve_relation_type from ..backend.expression.core import Column +from ..backend.expression import ComparisonPredicate, Literal from ..interface import IActiveRecord, IActiveQuery T = TypeVar("T", bound=IActiveRecord) @@ -323,7 +324,9 @@ def query_method(instance): fk_value = getattr(instance, fk_col) if fk_value is not None: pk_column = Column(backend.dialect, pk_col, table=related_model.table_name()) - query = query.where(pk_column == fk_value) + query = query.where( + ComparisonPredicate(backend.dialect, "=", pk_column, Literal(backend.dialect, fk_value)) + ) else: pk_cols = instance.primary_key_columns() fk_cols = self.foreign_key if isinstance(self.foreign_key, tuple) else (self.foreign_key,) @@ -336,7 +339,9 @@ def query_method(instance): pk_value = getattr(instance, pk_col) if pk_value is not None: fk_column = Column(backend.dialect, fk_col, table=related_model.table_name()) - query = query.where(fk_column == pk_value) + query = query.where( + ComparisonPredicate(backend.dialect, "=", fk_column, Literal(backend.dialect, pk_value)) + ) return query diff --git a/tests/rhosocial/activerecord_test/feature/backend/dialect/test_json_path_mode.py b/tests/rhosocial/activerecord_test/feature/backend/dialect/test_json_path_mode.py index 283cc228f..34a036947 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dialect/test_json_path_mode.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dialect/test_json_path_mode.py @@ -6,7 +6,7 @@ - JSONMixin.format_json_expression() dispatch decisions - format_json_arrow_expression() error path on unsupported dialects - format_json_function_expression() equivalence on supported dialects -- JSONExpression stores mode correctly +- JSONDocumentExpression stores mode correctly """ from typing import TYPE_CHECKING, Any, Tuple @@ -20,7 +20,7 @@ ) from rhosocial.activerecord.backend.dialect.mixins import ExpressionMixin from rhosocial.activerecord.backend.expression.advanced_functions import ( - JSONExpression, + JSONDocumentExpression, JSONPathMode, ) @@ -38,6 +38,15 @@ class _BaseTestDialect(SQLDialectBase, JSONMixin, JSONSupport, ExpressionMixin): name = "test" + def supports_json_type(self) -> bool: + """These stand-ins exist to exercise JSON *dispatch*, so they have JSON. + + Inheriting the core's False made every test here fail once the + dispatcher started believing that probe: the dispatch under test was + never reached, because the refusal came first. + """ + return True + class ArrowSupportedDialect(_BaseTestDialect): """Dialect that supports JSON arrow operators (-> and ->>).""" @@ -60,7 +69,7 @@ def __init__(self, function_marker: str = "FN") -> None: super().__init__() self.function_marker = function_marker - def format_json_function_expression(self, expr: "JSONExpression") -> Tuple[str, tuple]: + def format_json_function_expression(self, expr: "JSONDocumentExpression") -> Tuple[str, tuple]: return f"{self.function_marker}({expr.column}, {expr.path})", () @@ -108,12 +117,12 @@ def test_invalid_type_raises(self) -> None: # ---------------------------------------------------------------------------- -# JSONExpression stores mode as JSONPathMode enum +# JSONDocumentExpression stores mode as JSONPathMode enum # ---------------------------------------------------------------------------- class TestJSONExpressionMode: - """Verify JSONExpression coerces the mode argument.""" + """Verify JSONDocumentExpression coerces the mode argument.""" @pytest.mark.parametrize( "value, expected", @@ -126,13 +135,13 @@ class TestJSONExpressionMode: ) def test_mode_is_coerced_to_enum(self, value: Any, expected: "JSONPathMode") -> None: d = ArrowSupportedDialect() - expr = JSONExpression(d, "data", "$.a", operation="->", mode=value) + expr = JSONDocumentExpression(d, "data", "$.a", operation="->", mode=value) assert expr.mode is expected def test_default_mode_is_auto(self) -> None: """Default behavior unchanged: mode=None → JSONPathMode.AUTO.""" d = ArrowSupportedDialect() - expr = JSONExpression(d, "data", "$.a") + expr = JSONDocumentExpression(d, "data", "$.a") assert expr.mode is JSONPathMode.AUTO @@ -146,7 +155,7 @@ class TestDispatchBehavior: def test_auto_on_arrow_supported_dialect_uses_arrow(self) -> None: d = ArrowSupportedDialect() - expr = JSONExpression(d, "data", "$.a", operation="->>") + expr = JSONDocumentExpression(d, "data", "$.a", operation="->>") sql, params = d.format_json_expression(expr) # Arrow formatting emits col->>'...' assert "->>" in sql @@ -154,7 +163,7 @@ def test_auto_on_arrow_supported_dialect_uses_arrow(self) -> None: def test_auto_on_arrow_unsupported_dialect_uses_function(self) -> None: d = ArrowUnsupportedDialect() - expr = JSONExpression(d, "data", "$.a", operation="->>") + expr = JSONDocumentExpression(d, "data", "$.a", operation="->>") sql, params = d.format_json_expression(expr) # Default function-based: JSON_UNQUOTE(JSON_EXTRACT(...)) assert "JSON_UNQUOTE" in sql @@ -162,7 +171,7 @@ def test_auto_on_arrow_unsupported_dialect_uses_function(self) -> None: def test_arrow_mode_on_unsupported_raises(self) -> None: d = ArrowUnsupportedDialect() - expr = JSONExpression( + expr = JSONDocumentExpression( d, "data", "$.a", operation="->>", mode=JSONPathMode.ARROW ) with pytest.raises(UnsupportedFeatureError): @@ -170,7 +179,7 @@ def test_arrow_mode_on_unsupported_raises(self) -> None: def test_arrow_mode_on_supported_uses_arrow(self) -> None: d = ArrowSupportedDialect() - expr = JSONExpression( + expr = JSONDocumentExpression( d, "data", "$.a", operation="->>", mode=JSONPathMode.ARROW ) sql, params = d.format_json_expression(expr) @@ -180,7 +189,7 @@ def test_arrow_mode_on_supported_uses_arrow(self) -> None: def test_function_mode_on_supported_dialect_uses_function(self) -> None: """FUNCTION mode must ignore arrow capability and dispatch to function path.""" d = FunctionOverrideDialect(function_marker="FN_MARKER") - expr = JSONExpression( + expr = JSONDocumentExpression( d, "data", "$.a", operation="->>", mode=JSONPathMode.FUNCTION ) sql, params = d.format_json_expression(expr) @@ -190,7 +199,7 @@ def test_function_mode_on_supported_dialect_uses_function(self) -> None: def test_function_mode_on_unsupported_dialect_uses_function(self) -> None: """FUNCTION mode must work even when arrow is not supported.""" d = ArrowUnsupportedDialect() - expr = JSONExpression( + expr = JSONDocumentExpression( d, "data", "$.a", operation="->", mode=JSONPathMode.FUNCTION ) sql, params = d.format_json_expression(expr) @@ -201,7 +210,7 @@ def test_function_mode_on_unsupported_dialect_uses_function(self) -> None: def test_string_mode_coerced_and_dispatched(self) -> None: """String mode values gets coerced to enum and dispatched correctly.""" d = FunctionOverrideDialect(function_marker="STRING_MODE") - expr = JSONExpression( + expr = JSONDocumentExpression( d, "data", "$.a", operation="->>", mode="function" ) sql, _ = d.format_json_expression(expr) @@ -218,7 +227,7 @@ class TestDirectFormatMethods: def test_arrow_direct_on_unsupported_raises(self) -> None: d = ArrowUnsupportedDialect() - expr = JSONExpression( + expr = JSONDocumentExpression( d, "data", "$.a", operation="->>", mode=JSONPathMode.ARROW ) with pytest.raises(UnsupportedFeatureError): @@ -227,7 +236,7 @@ def test_arrow_direct_on_unsupported_raises(self) -> None: def test_function_direct_always_succeeds_on_supported(self) -> None: """Even on arrow-capable backends, function path is available.""" d = ArrowSupportedDialect() - expr = JSONExpression( + expr = JSONDocumentExpression( d, "data", "$.a", operation="->>", mode=JSONPathMode.FUNCTION ) sql, params = d.format_json_function_expression(expr) @@ -238,7 +247,7 @@ def test_function_direct_always_succeeds_on_supported(self) -> None: def test_arrow_format_keeps_path_in_string_literal(self) -> None: """Arrow formatter escapes via SQL string literal, not parameter.""" d = ArrowSupportedDialect() - expr = JSONExpression(d, "users", "$.name", operation="->>") + expr = JSONDocumentExpression(d, "users", "$.name", operation="->>") sql, params = d.format_json_arrow_expression(expr) # No parameter; path is embedded as SQL literal assert params == () @@ -248,7 +257,7 @@ def test_arrow_format_keeps_path_in_string_literal(self) -> None: def test_function_format_keeps_path_in_string_literal(self) -> None: """Function default uses SQL string literal but no parameter.""" d = ArrowSupportedDialect() - expr = JSONExpression(d, "users", "$.name", operation="->") + expr = JSONDocumentExpression(d, "users", "$.name", operation="->") sql, params = d.format_json_function_expression(expr) assert params == () # Default function path embeds the path as SQL literal @@ -271,7 +280,7 @@ def test_arrow_escapes_single_quote_in_path(self, op: str) -> None: # Path containing a single quote — if not escaped, this would break the # surrounding SQL string literal. path = "$.o'Brien" - expr = JSONExpression(d, "data", path, operation=op) + expr = JSONDocumentExpression(d, "data", path, operation=op) sql, _ = d.format_json_arrow_expression(expr) # The single quote in the path must appear doubled-up (escaped) so it # cannot terminate the SQL literal early. @@ -283,7 +292,7 @@ def test_arrow_escapes_single_quote_in_path(self, op: str) -> None: def test_function_escapes_single_quote_in_path(self, op: str) -> None: d = ArrowSupportedDialect() path = "$.o'Brien" - expr = JSONExpression(d, "data", path, operation=op) + expr = JSONDocumentExpression(d, "data", path, operation=op) sql, _ = d.format_json_function_expression(expr) assert "''" in sql assert "'o'Brien'" not in sql diff --git a/tests/rhosocial/activerecord_test/feature/backend/dialect/test_mixins_import_order.py b/tests/rhosocial/activerecord_test/feature/backend/dialect/test_mixins_import_order.py index 62d0bec8d..21e60e843 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dialect/test_mixins_import_order.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dialect/test_mixins_import_order.py @@ -57,11 +57,12 @@ def test_format_function_call_filter_path_in_fresh_interpreter(): body = ( "import rhosocial.activerecord.backend.dialect.mixins.function # noqa: F401\n" "from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect\n" - "from rhosocial.activerecord.backend.expression.core import FunctionCall, Column\n" + "from rhosocial.activerecord.backend.expression.core import FunctionCall, Column, Literal\n" + "from rhosocial.activerecord.backend.expression.predicates import ComparisonPredicate\n" "\n" "d = DummyDialect()\n" "call = FunctionCall(d, 'SUM', Column(d, 'amount'))\n" - "call.filter_predicate = (Column(d, 'amount') > 0)\n" + "call.filter_predicate = ComparisonPredicate(d, '>', Column(d, 'amount'), Literal(d, 0))\n" "sql, params = d.format_function_call(call)\n" "assert 'FILTER (WHERE' in sql, sql\n" ) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dialect/test_returning_capabilities.py b/tests/rhosocial/activerecord_test/feature/backend/dialect/test_returning_capabilities.py index f3b9f5bb4..b743b7d0a 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dialect/test_returning_capabilities.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dialect/test_returning_capabilities.py @@ -13,7 +13,6 @@ import pytest from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError -from rhosocial.activerecord.backend.expression.aggregates import AggregateFunctionCall from rhosocial.activerecord.backend.expression.core import ( Column, FunctionCall, @@ -175,7 +174,19 @@ def test_old_new_raises_when_unsupported(self): def test_aggregate_rejected(self): dialect = DummyDialect() clause = ReturningClause( - dialect, expressions=[AggregateFunctionCall(dialect, "COUNT", Column(dialect, "id"))] + dialect, expressions=[FunctionCall(dialect, "COUNT", Column(dialect, "id"), is_aggregate=True)] + ) + with pytest.raises(UnsupportedFeatureError, match="aggregate/subquery in RETURNING"): + dialect.format_returning_clause(clause) + + def test_typed_aggregate_rejected(self): + """The factory returns a typed wrapper; it forwards ``is_aggregate`` + to the node it holds, so the RETURNING check must read through it.""" + from rhosocial.activerecord.backend.expression import count + + dialect = DummyDialect() + clause = ReturningClause( + dialect, expressions=[count(dialect, Column(dialect, "id"))] ) with pytest.raises(UnsupportedFeatureError, match="aggregate/subquery in RETURNING"): dialect.format_returning_clause(clause) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dialect/test_window_protocol.py b/tests/rhosocial/activerecord_test/feature/backend/dialect/test_window_protocol.py index d60b437eb..be3bac384 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dialect/test_window_protocol.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dialect/test_window_protocol.py @@ -14,9 +14,10 @@ WindowFunctionSupport, UnsupportedFeatureError, ) +from rhosocial.activerecord.backend.dialect.mixins.function import FunctionCallMixin -class NoWindowDialect(SQLDialectBase, WindowFunctionMixin, WindowFunctionSupport): +class NoWindowDialect(SQLDialectBase, FunctionCallMixin, WindowFunctionMixin, WindowFunctionSupport): """Dialect that does not support window functions.""" def supports_window_functions(self) -> bool: @@ -26,6 +27,10 @@ def supports_window_frame_clause(self) -> bool: return False +class NoWindowMixinDialect(SQLDialectBase, FunctionCallMixin): + """Dialect that does not even compose the window-function mixin.""" + + def test_no_window_dialect_does_not_support_window_features(): """Test that no-window dialect properly indicates lack of window function support.""" dialect = NoWindowDialect() @@ -36,23 +41,31 @@ def test_no_window_dialect_does_not_support_window_features(): assert not dialect.supports_window_frame_clause() -def test_format_window_function_call_raises_error(): - """Test that format_window_function_call method raises error in no-window dialect.""" +def test_format_function_call_with_over_raises_error(): + """An OVER clause must be refused when window functions are unsupported. + + ``format_function_call`` is the single renderer for function calls, so it + is the method that sees the ``window_spec`` and raises. + """ + from rhosocial.activerecord.backend.expression.core import FunctionCall + dialect = NoWindowDialect() + call = FunctionCall(dialect, "ROW_NUMBER", window_spec="w") - # Create a mock window function call - class MockWindowFunctionCall: - def __init__(self): - self.function_name = "ROW_NUMBER" - self.args = [] - self.window_spec = None - self.alias = None + with pytest.raises(UnsupportedFeatureError): + dialect.format_function_call(call) - mock_call = MockWindowFunctionCall() - # This should raise an error +def test_format_function_call_with_over_refused_without_window_mixin(): + """A dialect without ``WindowFunctionMixin`` has neither the probe nor the + specification formatter; the renderer must refuse the clause cleanly.""" + from rhosocial.activerecord.backend.expression.core import FunctionCall + + dialect = NoWindowMixinDialect() + call = FunctionCall(dialect, "ROW_NUMBER", window_spec="w") + with pytest.raises(UnsupportedFeatureError): - dialect.format_window_function_call(mock_call) + dialect.format_function_call(call) def test_format_window_specification_raises_error(): diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy/test_sqlxml_mixin.py b/tests/rhosocial/activerecord_test/feature/backend/dummy/test_sqlxml_mixin.py index 4009ba1c0..fb3c4d72c 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy/test_sqlxml_mixin.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy/test_sqlxml_mixin.py @@ -10,11 +10,13 @@ Column, Literal, OrderByClause, + StringValueExpression, XMLParseDocumentType, XMLParseExpression, XMLPassingMechanism, XMLStandaloneOption, XMLTableColumn, + XMLValueExpression, xmlagg, xmlattributes, xmlcomment, @@ -91,6 +93,34 @@ def test_xmlparse_expression_can_be_constructed_directly(self, dummy_dialect: Du assert sql == "XMLPARSE(CONTENT ?)" assert params == ("",) + def test_xml_document_factories_return_xml_values(self, dummy_dialect: DummyDialect): + """The document constructors declare the value class they produce. + + Each one builds an XML document, so the result is an + ``XMLValueExpression`` -- the class is the statement, not a tag, and + the SQL assertions elsewhere in this file are unchanged by it. + """ + expressions = [ + xmlparse(dummy_dialect, ""), + xmlelement(dummy_dialect, "item"), + xmlforest(dummy_dialect, ("x", "item")), + xmlconcat(dummy_dialect, ""), + xmlcomment(dummy_dialect, "note"), + xmlpi(dummy_dialect, "target"), + xmlroot(dummy_dialect, ""), + xmlagg(dummy_dialect, ""), + xmlquery(dummy_dialect, "/root"), + ] + for expr in expressions: + assert isinstance(expr, XMLValueExpression), type(expr).__name__ + + def test_xmlserialize_factory_returns_the_text_value(self, dummy_dialect: DummyDialect): + """Serialization yields the character value it names, not XML again.""" + expr = xmlserialize(dummy_dialect, "", "TEXT") + + assert isinstance(expr, StringValueExpression) + assert not isinstance(expr, XMLValueExpression) + def test_xmlserialize_generates_standard_sql(self, dummy_dialect: DummyDialect): expr = xmlserialize(dummy_dialect, Column(dummy_dialect, "payload"), "VARCHAR(100)") diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy/test_trigger_mixin.py b/tests/rhosocial/activerecord_test/feature/backend/dummy/test_trigger_mixin.py index c6b5609ff..73a6c41b7 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy/test_trigger_mixin.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy/test_trigger_mixin.py @@ -2,7 +2,7 @@ """Tests for TriggerMixin format methods.""" from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect -from rhosocial.activerecord.backend.expression import Column, Literal +from rhosocial.activerecord.backend.expression import Column, ComparisonPredicate, Literal from rhosocial.activerecord.backend.expression.objects import Function, Table from rhosocial.activerecord.backend.expression.objects import Trigger @@ -47,7 +47,12 @@ def test_format_create_trigger_with_condition(self, dummy_dialect: DummyDialect) TriggerEvent, ) - condition = Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + condition = ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) create_trigger = CreateTriggerExpression( dummy_dialect, trigger=Trigger(dummy_dialect, "status_trigger"), diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_function_window.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_function_window.py index 8bf9a0356..501ecaa3d 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_function_window.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_function_window.py @@ -1,11 +1,14 @@ # tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_function_window.py import pytest +from rhosocial.activerecord.backend.expression.types import CustomType from rhosocial.activerecord.backend.expression import ( Column, Literal, + FunctionCall, QueryExpression, CaseExpression, + ComparisonPredicate, ExistsExpression, AnyExpression, AllExpression, @@ -15,12 +18,12 @@ WindowSpecification, WindowDefinition, WindowClause, - WindowFunctionCall, ) from rhosocial.activerecord.backend.expression.sources import NamedRelationRef -from rhosocial.activerecord.backend.expression.query_parts import WhereClause +from rhosocial.activerecord.backend.expression.query_parts import OrderByClause, WhereClause from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect from rhosocial.activerecord.backend.expression.objects import Table +from rhosocial.activerecord.backend.expression.types import DecimalType class TestAdvancedFunctionWindow: @@ -29,9 +32,9 @@ class TestAdvancedFunctionWindow: # --- CaseExpression --- def test_case_searched_expression(self, dummy_dialect: DummyDialect): """Tests a searched CASE expression (CASE WHEN ... THEN ... ELSE ... END).""" - condition1 = Column(dummy_dialect, "age") > Literal(dummy_dialect, 18) + condition1 = ComparisonPredicate(dummy_dialect, ">", Column(dummy_dialect, "age"), Literal(dummy_dialect, 18)) result1 = Literal(dummy_dialect, "adult") - condition2 = Column(dummy_dialect, "age") <= Literal(dummy_dialect, 18) + condition2 = ComparisonPredicate(dummy_dialect, "<=", Column(dummy_dialect, "age"), Literal(dummy_dialect, 18)) result2 = Literal(dummy_dialect, "minor") case_expr = CaseExpression( @@ -84,7 +87,7 @@ def test_cast_method(self, dummy_dialect: DummyDialect, expr_data, target_type, else: return - cast_expr = expr.cast(target_type) + cast_expr = expr.cast(CustomType(dummy_dialect, raw=target_type)) sql, params = cast_expr.to_sql() assert sql == expected_sql assert params == expected_params @@ -92,7 +95,7 @@ def test_cast_method(self, dummy_dialect: DummyDialect, expr_data, target_type, def test_cast_method_on_arithmetic_result(self, dummy_dialect: DummyDialect): """Tests cast() method on arithmetic expression result (applied to operand).""" col = Column(dummy_dialect, "value") - casted = col.cast("DECIMAL(10,2)") + casted = col.cast(DecimalType(dummy_dialect, precision=10, scale=2)) sql, params = casted.to_sql() assert sql == 'CAST("value" AS DECIMAL(10,2))' assert params == () @@ -105,7 +108,10 @@ def test_exists_expression(self, dummy_dialect: DummyDialect): select=[Column(dummy_dialect, "id")], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders")), where=WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "user_id") == Column(dummy_dialect, "id", "u") + dummy_dialect, + condition=ComparisonPredicate( + dummy_dialect, "=", Column(dummy_dialect, "user_id"), Column(dummy_dialect, "id", "u"), + ), ), ) exists_expr = ExistsExpression(dummy_dialect, subquery) @@ -204,7 +210,7 @@ def test_query_expression_with_for_update_nowait(self, dummy_dialect: DummyDiale # --- Window Functions --- def test_window_function_call_inline_spec(self, dummy_dialect: DummyDialect): - """Tests WindowFunctionCall with inline window specification.""" + """Tests FunctionCall with inline window specification.""" # Create a window specification from rhosocial.activerecord.backend.expression.query_parts import OrderByClause @@ -215,8 +221,8 @@ def test_window_function_call_inline_spec(self, dummy_dialect: DummyDialect): ) # Create the window function call - window_func = WindowFunctionCall( - dummy_dialect, function_name="ROW_NUMBER", window_spec=window_spec, alias="row_num" + window_func = FunctionCall( + dummy_dialect, "ROW_NUMBER", window_spec=window_spec, alias="row_num" ) sql, params = window_func.to_sql() @@ -225,7 +231,7 @@ def test_window_function_call_inline_spec(self, dummy_dialect: DummyDialect): assert params == () def test_window_function_call_with_frame_specification(self, dummy_dialect: DummyDialect): - """Tests WindowFunctionCall with frame specification.""" + """Tests FunctionCall with frame specification.""" # Create a frame specification frame_spec = WindowFrameSpecification( dummy_dialect, frame_type="ROWS", start_frame="UNBOUNDED PRECEDING", end_frame="CURRENT ROW" @@ -242,10 +248,10 @@ def test_window_function_call_with_frame_specification(self, dummy_dialect: Dumm ) # Create a window function call - window_func = WindowFunctionCall( + window_func = FunctionCall( dummy_dialect, - function_name="SUM", - args=[Column(dummy_dialect, "amount")], + "SUM", + Column(dummy_dialect, "amount"), window_spec=window_spec, alias="running_total", ) @@ -256,12 +262,12 @@ def test_window_function_call_with_frame_specification(self, dummy_dialect: Dumm assert params == () def test_window_function_call_with_named_window_reference(self, dummy_dialect: DummyDialect): - """Tests WindowFunctionCall with reference to named window.""" + """Tests FunctionCall with reference to named window.""" # Create a window function that references a named window (this would be used in a query # where the WINDOW clause defines the named window) - window_func = WindowFunctionCall( + window_func = FunctionCall( dummy_dialect, - function_name="RANK", + "RANK", window_spec="sales_window", # Reference to named window alias="sales_rank", ) @@ -310,7 +316,7 @@ def test_query_with_window_clause(self, dummy_dialect: DummyDialect): select=[ Column(dummy_dialect, "employee_name"), # In a real query, these would reference the named windows - WindowFunctionCall(dummy_dialect, "ROW_NUMBER", window_spec="dept_ranking"), + FunctionCall(dummy_dialect, "ROW_NUMBER", window_spec="dept_ranking"), ], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "employees")), # Note: The WindowClause would need to be integrated into QueryExpression to be fully functional @@ -324,34 +330,57 @@ def test_query_with_window_clause(self, dummy_dialect: DummyDialect): ) assert window_params == () - def test_window_function_call_with_literal_args(self, dummy_dialect: DummyDialect): - """Tests a window function call with literal arguments (covering the else branch for non-BaseExpression args).""" # noqa: E501 - from rhosocial.activerecord.backend.expression import WindowSpecification, WindowFunctionCall, Column + def test_window_function_call_refuses_a_value_that_is_not_an_expression( + self, dummy_dialect: DummyDialect + ): + """The renderer does not decide what an argument meant. - # Test with literal arguments that are not BaseExpression instances - from rhosocial.activerecord.backend.expression.query_parts import OrderByClause + A bare value used to be turned into a bind parameter at render time, + which is the formatter manufacturing the expression it was asked to + render. Whether ``"test"`` is a value or a column name is the factory's + question, so the formatter refuses and the caller writes ``Literal``. + """ + window_spec = WindowSpecification( + dummy_dialect, + partition_by=[Column(dummy_dialect, "department")], + order_by=OrderByClause(dummy_dialect, [(Column(dummy_dialect, "salary"), "DESC")]), + ) + window_func = FunctionCall( + dummy_dialect, + "RANK", + 1, + "test", + 3.14, # Literal values, not BaseExpression instances + window_spec=window_spec, + alias="rank_val", + ) + + with pytest.raises(AttributeError): + window_func.to_sql() + def test_window_function_call_takes_literal_expressions(self, dummy_dialect: DummyDialect): + """Literal arguments render as bind parameters and keep the window clause.""" window_spec = WindowSpecification( dummy_dialect, partition_by=[Column(dummy_dialect, "department")], order_by=OrderByClause(dummy_dialect, [(Column(dummy_dialect, "salary"), "DESC")]), ) - # Pass literal values directly (not as BaseExpression objects) to trigger the else branch - window_func = WindowFunctionCall( + window_func = FunctionCall( dummy_dialect, - function_name="RANK", - args=[1, "test", 3.14], # Literal values, not BaseExpression instances + "RANK", + Literal(dummy_dialect, 1), + Literal(dummy_dialect, "test"), + Literal(dummy_dialect, 3.14), window_spec=window_spec, alias="rank_val", ) sql, params = window_func.to_sql() - # Should have placeholders for literal args assert "RANK(?, ?, ?)" in sql assert "OVER" in sql assert "PARTITION BY" in sql assert "ORDER BY" in sql - assert params == (1, "test", 3.14) # Should have the literal values as params + assert params == (1, "test", 3.14) def test_window_clause_with_empty_definitions_raises_error(self, dummy_dialect: DummyDialect): """Tests that WindowClause with empty definitions raises ValueError.""" diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_functions.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_functions.py index 5115976dd..c0d07e1c4 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_advanced_functions.py @@ -9,12 +9,13 @@ ExistsExpression, AnyExpression, AllExpression, - JSONExpression, + JSONDocumentExpression, ArrayExpression, OrderedSetAggregation, ) -from rhosocial.activerecord.backend.expression.core import Subquery +from rhosocial.activerecord.backend.expression.core import FunctionCall, Subquery from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect +from rhosocial.activerecord.backend.expression.types import IntegerType class TestCaseExpression: @@ -82,7 +83,7 @@ class TestCastExpression: def test_cast_expression_basic(self, dummy_dialect: DummyDialect): """Test basic CAST expression functionality.""" col = Column(dummy_dialect, "id") - expr = col.cast("INTEGER") + expr = col.cast(IntegerType(dummy_dialect)) sql, params = expr.to_sql() assert "CAST(" in sql assert "AS INTEGER" in sql @@ -90,7 +91,7 @@ def test_cast_expression_basic(self, dummy_dialect: DummyDialect): def test_cast_expression_with_literal(self, dummy_dialect: DummyDialect): """Test CAST expression with literal value.""" literal = Literal(dummy_dialect, "123") - expr = literal.cast("INTEGER") + expr = literal.cast(IntegerType(dummy_dialect)) sql, params = expr.to_sql() assert "CAST(" in sql assert "AS INTEGER" in sql @@ -163,12 +164,12 @@ def test_all_expression_with_literal_list(self, dummy_dialect: DummyDialect): class TestJSONExpression: - """Tests for JSONExpression class.""" + """Tests for JSONDocumentExpression class.""" def test_json_extract_expression(self, dummy_dialect: DummyDialect): """Test JSON extract falls back to function-based formatting (-> operation).""" col = Column(dummy_dialect, "json_col") - json_expr = JSONExpression(dummy_dialect, col, "$.name", operation="->") + json_expr = JSONDocumentExpression(dummy_dialect, col, "$.name", operation="->") sql, params = json_expr.to_sql() assert "JSON_EXTRACT" in sql assert params == () @@ -176,7 +177,7 @@ def test_json_extract_expression(self, dummy_dialect: DummyDialect): def test_json_extract_text_expression(self, dummy_dialect: DummyDialect): """Test JSON extract text falls back to function-based formatting (->> operation).""" col = Column(dummy_dialect, "json_col") - json_expr = JSONExpression(dummy_dialect, col, "$.name", operation="->>") + json_expr = JSONDocumentExpression(dummy_dialect, col, "$.name", operation="->>") sql, params = json_expr.to_sql() assert "JSON_UNQUOTE" in sql assert "JSON_EXTRACT" in sql @@ -184,7 +185,7 @@ def test_json_extract_text_expression(self, dummy_dialect: DummyDialect): def test_json_extract_with_string_column(self, dummy_dialect: DummyDialect): """Test JSON extract with string column name.""" - json_expr = JSONExpression(dummy_dialect, "json_col", "$.name", operation="->") + json_expr = JSONDocumentExpression(dummy_dialect, "json_col", "$.name", operation="->") sql, params = json_expr.to_sql() assert "JSON_EXTRACT" in sql assert params == () @@ -302,13 +303,13 @@ def test_window_clause(self, dummy_dialect: DummyDialect): # The exact output depends on the dialect implementation def test_window_function_call(self, dummy_dialect: DummyDialect): - """Test WindowFunctionCall functionality.""" - from rhosocial.activerecord.backend.expression.advanced_functions import WindowSpecification, WindowFunctionCall + """Test FunctionCall with a window specification.""" + from rhosocial.activerecord.backend.expression.advanced_functions import WindowSpecification partition_cols = [Column(dummy_dialect, "department")] window_spec = WindowSpecification(dummy_dialect, partition_by=partition_cols) - window_func = WindowFunctionCall( - dummy_dialect, "ROW_NUMBER", [Column(dummy_dialect, "id")], window_spec=window_spec + window_func = FunctionCall( + dummy_dialect, "ROW_NUMBER", Column(dummy_dialect, "id"), window_spec=window_spec ) sql, params = window_func.to_sql() # The exact output depends on the dialect implementation diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_aliasable_mixin.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_aliasable_mixin.py index 3c95b6243..80fa289a6 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_aliasable_mixin.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_aliasable_mixin.py @@ -6,18 +6,22 @@ import pytest -from rhosocial.activerecord.backend.expression import Literal, Column, FunctionCall, Subquery +from rhosocial.activerecord.backend.expression import Literal, Column, FunctionCall, Subquery, ComparisonPredicate from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.expression.operators import BinaryArithmeticExpression from rhosocial.activerecord.backend.expression.query_parts import JoinClause from rhosocial.activerecord.backend.expression.advanced_functions import ( - JSONExpression, + JSONDocumentExpression, ArrayExpression, OrderedSetAggregation, ) -from rhosocial.activerecord.backend.expression.aggregates import AggregateFunctionCall from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect from rhosocial.activerecord.backend.expression.objects import Table +from rhosocial.activerecord.backend.expression.types import ( + CustomType, + DecimalType, + TextType, +) class TestAliasableMixin: @@ -72,16 +76,20 @@ def test_subquery_alias_with_as_method(self, dummy_dialect: DummyDialect): assert params == () def test_aggregate_function_call_alias_initialization(self, dummy_dialect: DummyDialect): - """Test AggregateFunctionCall with alias specified during initialization.""" - agg = AggregateFunctionCall(dummy_dialect, "COUNT", Column(dummy_dialect, "*"), alias="total_count") + """Test FunctionCall (aggregate) with alias specified during initialization.""" + agg = FunctionCall( + dummy_dialect, "COUNT", Column(dummy_dialect, "*"), alias="total_count", is_aggregate=True + ) assert agg.alias == "total_count" sql, params = agg.to_sql() assert sql == 'COUNT("*") AS "total_count"' assert params == () def test_aggregate_function_call_alias_with_as_method(self, dummy_dialect: DummyDialect): - """Test AggregateFunctionCall with alias specified using as_() method.""" - agg = AggregateFunctionCall(dummy_dialect, "COUNT", Column(dummy_dialect, "*")).as_("total_count") + """Test FunctionCall (aggregate) with alias specified using as_() method.""" + agg = FunctionCall( + dummy_dialect, "COUNT", Column(dummy_dialect, "*"), is_aggregate=True + ).as_("total_count") assert agg.alias == "total_count" sql, params = agg.to_sql() assert sql == 'COUNT("*") AS "total_count"' @@ -89,7 +97,7 @@ def test_aggregate_function_call_alias_with_as_method(self, dummy_dialect: Dummy def test_cast_expression_alias_initialization(self, dummy_dialect: DummyDialect): """Test cast() method with alias specified during initialization.""" - cast = Column(dummy_dialect, "id", alias="id_text").cast("TEXT") + cast = Column(dummy_dialect, "id", alias="id_text").cast(TextType(dummy_dialect)) assert cast.alias == "id_text" sql, params = cast.to_sql() assert sql == 'CAST("id" AS TEXT) AS "id_text"' @@ -97,23 +105,23 @@ def test_cast_expression_alias_initialization(self, dummy_dialect: DummyDialect) def test_cast_expression_alias_with_as_method(self, dummy_dialect: DummyDialect): """Test cast() method with alias specified using as_() method.""" - cast = Column(dummy_dialect, "id").as_("id_text").cast("TEXT") + cast = Column(dummy_dialect, "id").as_("id_text").cast(TextType(dummy_dialect)) assert cast.alias == "id_text" sql, params = cast.to_sql() assert sql == 'CAST("id" AS TEXT) AS "id_text"' assert params == () def test_json_expression_alias_initialization(self, dummy_dialect: DummyDialect): - """Test JSONExpression with alias specified during initialization.""" - json_expr = JSONExpression(dummy_dialect, Column(dummy_dialect, "data"), "$.name", alias="name_field") + """Test JSONDocumentExpression with alias specified during initialization.""" + json_expr = JSONDocumentExpression(dummy_dialect, Column(dummy_dialect, "data"), "$.name", alias="name_field") assert json_expr.alias == "name_field" sql, params = json_expr.to_sql() assert sql == 'JSON_EXTRACT("data", \'$.name\') AS "name_field"' assert params == () def test_json_expression_alias_with_as_method(self, dummy_dialect: DummyDialect): - """Test JSONExpression with alias specified using as_() method.""" - json_expr = JSONExpression(dummy_dialect, Column(dummy_dialect, "data"), "$.name").as_("name_field") + """Test JSONDocumentExpression with alias specified using as_() method.""" + json_expr = JSONDocumentExpression(dummy_dialect, Column(dummy_dialect, "data"), "$.name").as_("name_field") assert json_expr.alias == "name_field" sql, params = json_expr.to_sql() assert sql == 'JSON_EXTRACT("data", \'$.name\') AS "name_field"' @@ -241,7 +249,7 @@ def test_independent_aliases_from_same_source(self, dummy_dialect: DummyDialect) assert a is not b def test_chained_as_then_cast_keeps_alias(self, dummy_dialect: DummyDialect): - cast = Column(dummy_dialect, "id").as_("id_text").cast("TEXT") + cast = Column(dummy_dialect, "id").as_("id_text").cast(TextType(dummy_dialect)) assert cast.alias == "id_text" assert cast.to_sql()[0] == 'CAST("id" AS TEXT) AS "id_text"' @@ -258,7 +266,7 @@ def test_chained_as_then_cast_keeps_alias(self, dummy_dialect: DummyDialect): left_table=NamedRelationRef(d, Table(d, "users")), right_table=NamedRelationRef(d, Table(d, "items")), join_type="INNER JOIN", - condition=Column(d, "id", "u") == Column(d, "user_id", "i"), + condition=ComparisonPredicate(d, "=", Column(d, "id", "u"), Column(d, "user_id", "i")), ), ], ids=["Literal", "Column", "FunctionCall", "Subquery", "NamedRelationRef", "JoinClause"], @@ -292,7 +300,7 @@ def test_cast_on_aliased_copy_does_not_leak_to_original( # identically, and the original column stays untouched. col = Column(dummy_dialect, "id") aliased = col.as_("id_text") - casted = aliased.cast("TEXT") + casted = aliased.cast(TextType(dummy_dialect)) assert casted.to_sql()[0] == 'CAST("id" AS TEXT) AS "id_text"' assert col.to_sql()[0] == '"id"' assert col.alias is None @@ -303,9 +311,9 @@ def test_cast_on_aliased_copy_does_not_leak_to_original( def test_cast_on_original_does_not_leak_to_aliased_copy( self, dummy_dialect: DummyDialect ): - col = Column(dummy_dialect, "amount").cast("MONEY") + col = Column(dummy_dialect, "amount").cast(CustomType(dummy_dialect, raw='MONEY')) aliased = col.as_("m") - deeper = aliased.cast("NUMERIC") + deeper = aliased.cast(CustomType(dummy_dialect, raw="NUMERIC")) # as_() hoists the alias off the inner node onto the new cast; the # later cast wraps that aliased node, alias moving outward again. assert aliased.to_sql()[0] == 'CAST("amount" AS MONEY)' diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_constraint_protocol.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_constraint_protocol.py index 17a7fb44f..f859ac323 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_constraint_protocol.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_constraint_protocol.py @@ -266,6 +266,7 @@ def test_table_and_column_enforcement(self): ColumnConstraint, ColumnConstraintType, ColumnDefinition, + ComparisonPredicate, CreateTableExpression, Literal, TableConstraint, @@ -275,7 +276,7 @@ def test_table_and_column_enforcement(self): from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect dialect = DummyDialect() - condition = Column(dialect, "age") > Literal(dialect, 0, inline_literals=True) + condition = ComparisonPredicate(dialect, ">", Column(dialect, "age"), Literal(dialect, 0, inline_literals=True)) table_constraint = TableConstraint( dialect, TableConstraintType.CHECK, @@ -384,6 +385,7 @@ def test_constraint_type_and_validation_strings_are_normalized(self): def test_check_predicate_inlines_literals_and_rejects_raw_parameters(self): from rhosocial.activerecord.backend.expression import ( Column, + ComparisonPredicate, Literal, RawSQLPredicate, TableConstraint, @@ -394,7 +396,7 @@ def test_check_predicate_inlines_literals_and_rejects_raw_parameters(self): trusted = TableConstraint( dialect, "CHECK", - check_condition=Column(dialect, "age") > Literal(dialect, 0), + check_condition=ComparisonPredicate(dialect, ">", Column(dialect, "age"), Literal(dialect, 0)), ) assert trusted.to_sql() == ('CHECK ("age" > 0)', ()) @@ -433,74 +435,88 @@ def _check(self, dialect, condition): return TableConstraint(dialect, "CHECK", check_condition=condition) def test_in_list_inlines_inside_a_check(self, dummy_dialect: DummyDialect): - from rhosocial.activerecord.backend.expression import Column + from rhosocial.activerecord.backend.expression import InPredicate, Literal, Column constraint = self._check( - dummy_dialect, Column(dummy_dialect, "direction").in_(["debit", "credit"]) + dummy_dialect, + InPredicate(dummy_dialect, Column(dummy_dialect, "direction"), Literal(dummy_dialect, ("debit", "credit"))), ) assert constraint.to_sql() == ( 'CHECK ("direction" IN (\'debit\', \'credit\'))', (), ) def test_in_tuple_inlines_inside_a_check(self, dummy_dialect: DummyDialect): - from rhosocial.activerecord.backend.expression import Column, Literal + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal - condition = Column(dummy_dialect, "direction").in_( - Literal(dummy_dialect, ("debit", "credit")) + condition = InPredicate( + dummy_dialect, + Column(dummy_dialect, "direction"), + Literal(dummy_dialect, ("debit", "credit")), ) assert self._check(dummy_dialect, condition).to_sql() == ( 'CHECK ("direction" IN (\'debit\', \'credit\'))', (), ) def test_not_in_inlines_inside_a_check(self, dummy_dialect: DummyDialect): - from rhosocial.activerecord.backend.expression import Column + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal, LogicalPredicate constraint = self._check( - dummy_dialect, Column(dummy_dialect, "state").not_in(["a", "b"]) + dummy_dialect, + LogicalPredicate( + dummy_dialect, + "NOT", + InPredicate(dummy_dialect, Column(dummy_dialect, "state"), Literal(dummy_dialect, ("a", "b"))), + ), ) assert constraint.to_sql() == ( 'CHECK (NOT ("state" IN (\'a\', \'b\')))', (), ) def test_numeric_in_list_inlines_inside_a_check(self, dummy_dialect: DummyDialect): - from rhosocial.activerecord.backend.expression import Column + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal constraint = self._check( - dummy_dialect, Column(dummy_dialect, "priority").in_([1, 2, 3]) + dummy_dialect, + InPredicate(dummy_dialect, Column(dummy_dialect, "priority"), Literal(dummy_dialect, (1, 2, 3))), ) assert constraint.to_sql() == ( 'CHECK ("priority" IN (1, 2, 3))', (), ) def test_in_list_escapes_quotes_when_inlined(self, dummy_dialect: DummyDialect): - from rhosocial.activerecord.backend.expression import Column + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal constraint = self._check( - dummy_dialect, Column(dummy_dialect, "label").in_(["a'b"]) + dummy_dialect, + InPredicate(dummy_dialect, Column(dummy_dialect, "label"), Literal(dummy_dialect, ("a'b",))), ) assert constraint.to_sql() == ('CHECK ("label" IN (\'a\'\'b\'))', ()) def test_in_list_with_null_inlines_inside_a_check(self, dummy_dialect: DummyDialect): - from rhosocial.activerecord.backend.expression import Column + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal constraint = self._check( - dummy_dialect, Column(dummy_dialect, "parent").in_([None, 1]) + dummy_dialect, + InPredicate(dummy_dialect, Column(dummy_dialect, "parent"), Literal(dummy_dialect, (None, 1))), ) assert constraint.to_sql() == ('CHECK ("parent" IN (NULL, 1))', ()) def test_empty_in_list_stays_empty_parens(self, dummy_dialect: DummyDialect): - from rhosocial.activerecord.backend.expression import Column + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal constraint = self._check( - dummy_dialect, Column(dummy_dialect, "direction").in_([]) + dummy_dialect, + InPredicate(dummy_dialect, Column(dummy_dialect, "direction"), Literal(dummy_dialect, ())), ) assert constraint.to_sql() == ('CHECK ("direction" IN ())', ()) def test_in_list_still_binds_outside_ddl(self, dummy_dialect: DummyDialect): """The DML path must be untouched: inlining there would be an injection.""" - from rhosocial.activerecord.backend.expression import Column + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal - condition = Column(dummy_dialect, "direction").in_(["debit", "credit"]) + condition = InPredicate( + dummy_dialect, Column(dummy_dialect, "direction"), Literal(dummy_dialect, ("debit", "credit")) + ) assert condition.to_sql() == ('"direction" IN (?, ?)', ("debit", "credit")) def test_subquery_in_does_not_go_through_the_value_list_path( @@ -508,10 +524,12 @@ def test_subquery_in_does_not_go_through_the_value_list_path( ): """A subquery renders through its own to_sql(), so the collection fix must not touch it -- that path has no Literal and no inline flag.""" - from rhosocial.activerecord.backend.expression import Column, Subquery + from rhosocial.activerecord.backend.expression import Column, InPredicate, Subquery - condition = Column(dummy_dialect, "id").in_( - Subquery(dummy_dialect, "SELECT id FROM other", ()) + condition = InPredicate( + dummy_dialect, + Column(dummy_dialect, "id"), + Subquery(dummy_dialect, "SELECT id FROM other", ()), ) sql, params = condition.to_sql() assert "SELECT id FROM other" in sql @@ -522,10 +540,12 @@ def test_literal_wrapping_a_list_outside_ddl_still_binds( ): """Hand-building the Literal is the documented IN form; it must behave the same as the plain list call when the inline flag is off.""" - from rhosocial.activerecord.backend.expression import Column, Literal + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal - condition = Column(dummy_dialect, "direction").in_( - Literal(dummy_dialect, ["debit", "credit"]) + condition = InPredicate( + dummy_dialect, + Column(dummy_dialect, "direction"), + Literal(dummy_dialect, ["debit", "credit"]), ) assert condition.to_sql() == ('"direction" IN (?, ?)', ("debit", "credit")) @@ -533,9 +553,11 @@ def test_explicitly_inlined_literal_list_renders_inline_without_ddl( self, dummy_dialect: DummyDialect ): """The inline switch works on its own, not only via DDL preparation.""" - from rhosocial.activerecord.backend.expression import Column, Literal + from rhosocial.activerecord.backend.expression import Column, InPredicate, Literal - condition = Column(dummy_dialect, "direction").in_( - Literal(dummy_dialect, ("debit", "credit"), inline_literals=True) + condition = InPredicate( + dummy_dialect, + Column(dummy_dialect, "direction"), + Literal(dummy_dialect, ("debit", "credit"), inline_literals=True), ) assert condition.to_sql() == ('"direction" IN (\'debit\', \'credit\')', ()) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_core.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_core.py index 52db75b7b..c532c5b68 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_core.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_core.py @@ -4,7 +4,7 @@ """ import pytest -from rhosocial.activerecord.backend.expression import Literal, Column, FunctionCall, Subquery +from rhosocial.activerecord.backend.expression import Literal, Column, FunctionCall, Subquery, ComparisonPredicate from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect from rhosocial.activerecord.backend.expression.objects import Table @@ -170,7 +170,10 @@ def test_subquery_from_base_expression(self, dummy_dialect: DummyDialect): select=[Column(dummy_dialect, "id")], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders")), where=WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "pending") + dummy_dialect, + condition=ComparisonPredicate( + dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "pending"), + ), ), ) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_type_enum_contract.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_type_enum_contract.py new file mode 100644 index 000000000..4db3cf0ec --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_type_enum_contract.py @@ -0,0 +1,167 @@ +# tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_type_enum_contract.py +"""The generic ``enum`` type, and what a backend says when it cannot render it. + +``EnumType`` exists in the core and no real backend implemented a formatter for +it, so a model declaring an enumerated field failed everywhere with a message +that named neither the feature nor a way forward. The suggestion is the only +place a backend writes down what it stores instead, so the message has to +carry it. + +A backend that *can* render the type renders the values through its own literal +formatter, because that is where each dialect's escaping lives: a value holding +a quote is the case where a hand-rolled f-string of quotes goes wrong. +""" + +# tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_type_enum_contract.py +import pytest + +from rhosocial.activerecord.backend.dialect.mixins.data_type import DataTypeMixin +from rhosocial.activerecord.backend.expression.types import EnumType + + +@pytest.fixture +def dialect(): + from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect + + d = DummyDialect() + d._version = (1, 0, 0) + return d + + +# --------------------------------------------------------------------------- +# The type carries its values +# --------------------------------------------------------------------------- + + +def test_values_are_required(dialect): + """An enum with no values is a text field, and saying so is better than + emitting ``ENUM()``.""" + with pytest.raises(ValueError, match="requires values"): + EnumType(dialect) + + +def test_an_empty_value_list_is_rejected(dialect): + with pytest.raises(ValueError, match="at least one value"): + EnumType(dialect, []) + + +def test_values_survive_as_a_tuple(dialect): + assert EnumType(dialect, ["a", "b"]).values == ("a", "b") + + +# --------------------------------------------------------------------------- +# A backend that renders it +# --------------------------------------------------------------------------- + + +def test_values_are_rendered_in_order(dialect): + assert dialect.format_data_type(EnumType(dialect, ["draft", "live"]))[0] == ( + "ENUM('draft','live')" + ) + + +def test_a_value_containing_a_quote_is_escaped(dialect): + """The reason to go through format_literal rather than wrapping in quotes. + + ``ENUM('o'brien')`` is not valid SQL; doubling the quote is. + """ + sql, _ = dialect.format_data_type(EnumType(dialect, ["o'brien"])) + assert sql == "ENUM('o''brien')" + + +def test_a_rendered_enum_is_an_advertised_type(dialect): + """A formatter the dialect does not advertise would be a capability + claimed in one place and absent in the other.""" + assert "enum" in dialect.supports_data_types() + + +# --------------------------------------------------------------------------- +# A backend that cannot render it +# --------------------------------------------------------------------------- + + +class Narrow(DataTypeMixin): + """A dialect that advertises no enum formatter and suggests nothing. + + Renders one type, so a test can tell "refused because unsupported" from + "refused because the advice path is broken". + """ + + def format_data_type_varchar(self, data_type): + return f"VARCHAR({data_type.length})", () + + def suggested_data_types(self): + return {} + + +class Suggester(Narrow): + """A dialect that cannot render it but knows what it stores instead.""" + + def suggested_data_types(self): + from rhosocial.activerecord.backend.expression.types import VarCharType + + return {"enum": VarCharType} + + +class Lossy(Suggester): + """A dialect whose substitute does *not* hold the same meaning. + + Modelled on Firebird, whose ``timetz`` concept stands in for ``TimeType``: + Firebird's own reference says ``TIME`` and ``TIMESTAMP`` are synonyms of + their WITHOUT TIME ZONE types, so the substitution drops the zone. That is + a different value, not another way of writing one, and the caller has to be + told so in the error they are already reading. + """ + + def substitute_advice(self, name): + return "Note that this drops the zone." + + +def test_an_unrenderable_type_is_a_type_error(dialect): + with pytest.raises(TypeError, match="does not support the generic type 'enum'"): + Narrow().format_data_type(EnumType(dialect, ["a"])) + + +def test_the_refusal_names_the_substitute(dialect): + """Otherwise the caller is told it is unsupported and nothing else, which + is the same as not knowing. + + The advice must **not** claim the substitute holds the same meaning. That + is true for most entries and false for a lossy one -- Firebird's ``timetz`` + stands in for ``TimeType``, which drops the zone -- and a message that is + usually right is worse than one that never says it, because the caller + reads it and stops looking. A backend with something to add puts it in + ``substitute_advice``; the mechanism is exercised below. + """ + with pytest.raises(TypeError) as excinfo: + Suggester().format_data_type(EnumType(dialect, ["a"])) + message = str(excinfo.value) + assert "VarCharType" in message, message + assert "what this backend uses" in message, message + assert "the same meaning" not in message, ( + "the advice must not claim the substitute is equivalent:\n" + message) + + +def test_a_lossy_substitute_can_say_so(dialect): + """The caveat a backend supplies lands in the error the caller reads.""" + with pytest.raises(TypeError) as excinfo: + Lossy().format_data_type(EnumType(dialect, ["a"])) + message = str(excinfo.value) + assert "VarCharType" in message, message + assert "drops the zone" in message, message + assert "the same meaning" not in message, message + + +def test_no_substitute_means_no_advice(dialect): + with pytest.raises(TypeError) as excinfo: + Narrow().format_data_type(EnumType(dialect, ["a"])) + message = str(excinfo.value) + assert "It suggests" not in message, message + assert "Use a type this backend supports" in message, message + + +def test_a_type_the_dialect_renders_is_not_rejected(dialect): + """The advice path must not swallow types the dialect does handle.""" + from rhosocial.activerecord.backend.expression.types import VarCharType + + assert Suggester().format_data_type(VarCharType(dialect, 10))[0] diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_types.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_types.py index 97b24b99a..f03994014 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_types.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_data_types.py @@ -4,7 +4,7 @@ Covers: - Default type rendering via DataTypeMixin/dialect - Value-object equality / hashing -- Synonym-based equivalence +- Type identity (there is no separate equivalence question) - CustomType fallback - Dialect-based rendering via TypeFormattingSupport - Type parsing via TypeParsingSupport @@ -12,6 +12,7 @@ import pytest from rhosocial.activerecord.backend.expression.types import ( + ArrayType, BigIntType, BlobType, BooleanType, @@ -24,7 +25,6 @@ DoubleType, FloatType, IntegerType, - IntType, IntervalType, JsonBType, JsonType, @@ -37,6 +37,7 @@ TimestampTzType, TinyIntType, VarCharType, + XmlType, ) @@ -67,7 +68,7 @@ def test_integer_types(self, dialect): assert TinyIntType(dialect=dialect).to_sql() == ("TINYINT", ()) assert SmallIntType(dialect=dialect).to_sql() == ("SMALLINT", ()) assert BigIntType(dialect=dialect).to_sql() == ("BIGINT", ()) - assert IntType(dialect=dialect).to_sql() == ("INT", ()) + assert IntegerType(dialect=dialect, spelling="int").to_sql() == ("INT", ()) def test_numeric_types(self, dialect): assert FloatType(dialect=dialect).to_sql() == ("FLOAT", ()) @@ -153,20 +154,152 @@ def test_hashing(self): # --------------------------------------------------------------------------- -class TestSameTypeEquivalence: - """Equivalence checks based on synonyms.""" +class TestTypeIdentity: + """Type comparison is identity, not a looser "equivalent" question. - def test_same_type_is_equivalent(self): - assert VarCharType(None, 255).is_equivalent(VarCharType(None, 255)) - assert IntegerType().is_equivalent(IntegerType()) + There is no ``is_equivalent`` and no ``synonyms()``: two declarations are + the same type when they are the same class with the same logical content, + which is what ``==`` already means for a value object. + """ - def test_synonym_classes_are_equivalent(self): - assert IntType().is_equivalent(IntegerType()) - assert IntegerType().is_equivalent(IntType()) + def test_same_type_is_equal(self): + assert VarCharType(None, 255) == VarCharType(None, 255) + assert IntegerType() == IntegerType() + + def test_a_spelling_is_not_part_of_the_type(self): + """``INT`` and ``INTEGER`` are the same type, and they are the same + *value* — so ``==`` says they match. + + The tempting alternative is to count the spelling, on the argument that + ``CREATE TABLE t (a INT)`` and ``CREATE TABLE t (a INTEGER)`` are + different scripts. They are, but the schema differ does not compare two + scripts: it compares what a database *reports now* against what was + declared, and a database reports its own house spelling regardless of + which word was typed. PostgreSQL reports ``character varying(30)`` for + every ``varchar(30)`` column that exists. Counting the spelling would + therefore report a change on every long-form column that was never + touched — a false positive on the one comparison that has to be right. + + The difference is not lost: it is in the rendered SQL, and + ``spelling`` round-trips through ``get_params()`` for serialization. + """ + assert IntegerType() == IntegerType(spelling="int") + assert hash(IntegerType()) == hash(IntegerType(spelling="int")) + + def test_different_classes_are_never_equal(self): + assert JsonType() != JsonBType() + assert IntegerType() != VarCharType(None, 255) - def test_different_classes_not_equivalent(self): - assert not JsonType().is_equivalent(JsonBType()) - assert not IntegerType().is_equivalent(VarCharType(None, 255)) + def test_unsigned_is_part_of_the_declaration(self): + """Signed and unsigned are the same *class* — the range is what the + parameter carries — so they are told apart by ``==``, not by type.""" + assert IntegerType() != IntegerType(unsigned=True) + + +# --------------------------------------------------------------------------- +# Signedness on the floating-point and exact fixed-point concepts +# --------------------------------------------------------------------------- + + +class TestNumericUnsignedField: + """``unsigned`` on ``DecimalType``, ``FloatType`` and ``DoubleType``. + + The same field, on the same terms, as the four integer widths: **width is a + class, signedness is a field**. ``FLOAT(p)`` exists for every ``p``, so a + (width x signedness) grid cannot live in a linear chain, and the flag rides + on the instance instead. + + It has to ride there, because MySQL's manual says of the numeric types what + it says of the integers — "Floating point and fixed-point types also can be + ``UNSIGNED``" — so ``DECIMAL(10,2) UNSIGNED`` and ``DECIMAL(10,2)`` are two + different columns on MySQL and MariaDB alike. A concept that cannot hold the + flag cannot tell them apart, and the schema differ reports no change for a + change the database will make: measured on all fifteen wired MariaDB servers, + ``decimal(10,2) unsigned zerofill`` introspected as ``DecimalType(10, 2)``. + + Which backend honours the flag and which refuses it is that vendor's own + question; what is checked *here* is the part that is the framework's — the + field exists, it is in ``PARAMETERS`` (so it reaches ``==`` and ``__hash__``), + and it is strictly typed, because it becomes a type modifier in the rendered + DDL and ``unsigned=1`` must not become ``UNSIGNED``. + """ + + CONCEPTS = (DecimalType, FloatType, DoubleType) + + @pytest.mark.parametrize("klass", CONCEPTS, ids=lambda k: k.__name__) + def test_signed_and_unsigned_are_different_columns(self, klass): + assert klass() != klass(unsigned=True) + assert hash(klass()) != hash(klass(unsigned=True)) + assert klass() == klass(unsigned=False) + assert klass(unsigned=False) != klass(unsigned=True) + + @pytest.mark.parametrize("klass", CONCEPTS, ids=lambda k: k.__name__) + def test_the_field_is_declared_as_identity(self, klass): + """``PARAMETERS`` is what ``identity()`` reads, so this is the whole of + "the differ can see it". ``unsigned`` is *appended* to the tuple, never + inserted ahead of ``precision``/``scale``: the order is load-bearing for + ``__hash__``, and reordering it would change every hash of every instance. + """ + assert klass.PARAMETERS[-1] == "unsigned" + assert "unsigned" in klass.PARAMETERS + assert klass().identity()[-1] is False + assert klass(unsigned=True).identity()[-1] is True + + @pytest.mark.parametrize("klass", CONCEPTS, ids=lambda k: k.__name__) + def test_unsigned_is_a_real_bool_not_a_truthy_test(self, klass): + """It becomes ``UNSIGNED`` in the DDL, so ``1`` is not ``True``. + + A truthy check would silently accept ``1``, ``"yes"`` and any other + object, and the *first* of those is the dangerous one: it renders + ``UNSIGNED`` for a field the caller wrote as a display width or a + count, and nothing about the resulting DDL says the declaration was + reinterpreted. + """ + for wrong in (1, 0, "yes", "", None, [], object()): + with pytest.raises(TypeError, match="unsigned must be a bool"): + klass(unsigned=wrong) + + @pytest.mark.parametrize("klass", CONCEPTS, ids=lambda k: k.__name__) + def test_the_other_fields_are_untouched(self, klass): + """Adding a third parameter must not have disturbed the first two. + + ``precision``/``scale`` still read, still compare, and still hold their + declared defaults. ``DoubleType`` carries no precision of its own — that + is D6, ``REAL``/``DOUBLE PRECISION``/``FLOAT`` being three verified + different storages rather than one concept at three precisions — so the + assertion is about the fields a concept *does* have. + """ + assert klass().unsigned is False + if "precision" in klass.PARAMETERS: + assert klass().precision is None + assert klass(precision=24).precision == 24 + if "scale" in klass.PARAMETERS: + assert klass().scale is None + assert klass(precision=10, scale=2).identity()[:2] == (10, 2) + + def test_the_three_concepts_still_take_their_dialect_first(self): + """``dialect`` is the first positional parameter, on all three. + + A signature that put ``precision`` first would fail *silently*: the + dialect object would be stored as the precision and the error would only + appear at render time, in SQL. That is the whole reason this is asserted + rather than assumed — and it is asserted on the three that gained a + keyword-only parameter, because that is where the positional/keyword + boundary moved. + """ + sentinel = _dummy_dialect() + assert DecimalType(sentinel, 24).precision == 24 + assert DecimalType(sentinel, 24).dialect is sentinel + assert DecimalType(sentinel, 24).unsigned is False + assert DecimalType(sentinel, 24).spelling == "decimal" + assert DecimalType(sentinel, 24, 2).scale == 2 + assert FloatType(sentinel, 24).precision == 24 + assert FloatType(sentinel, 24).dialect is sentinel + assert FloatType(sentinel, 24).unsigned is False + # ``DoubleType`` has no second positional, and must not grow one: the + # dialect is the only positional, exactly as before. + assert DoubleType(sentinel).dialect is sentinel + assert DoubleType(sentinel).unsigned is False # --------------------------------------------------------------------------- @@ -251,6 +384,75 @@ def test_data_type_protocol_check(self, dialect): assert DDLTypeSupport is DataTypeSupport +# --------------------------------------------------------------------------- +# Array container contract +# --------------------------------------------------------------------------- + + +class TestArrayTypeContract: + """``ArrayType`` refuses to exist without something to be an array of.""" + + def test_element_type_is_required(self): + with pytest.raises(TypeError, match="requires an element_type"): + ArrayType(None) + + def test_element_type_must_be_a_data_type(self): + with pytest.raises(TypeError, match="must be a DataType instance"): + ArrayType(None, "integer") + + def test_dimensions_must_be_a_positive_int(self): + with pytest.raises(ValueError, match="dimensions must be an int >= 1"): + ArrayType(None, IntegerType(), 0) + with pytest.raises(ValueError, match="dimensions must be an int >= 1"): + ArrayType(None, IntegerType(), 1.5) + + def test_dimensions_default_to_one(self): + assert ArrayType(None, IntegerType()).dimensions == 1 + + +# --------------------------------------------------------------------------- +# XmlType +# --------------------------------------------------------------------------- + + +class TestXmlType: + """XML is a modelled concept, distinct from both JSON and Text.""" + + @pytest.fixture + def dialect(self): + return _dummy_dialect() + + def test_name_is_xml(self): + assert XmlType().name == "xml" + + def test_renders_through_its_dialect(self, dialect): + assert dialect.format_data_type(XmlType(dialect)) == ("XML", ()) + + def test_equality_and_hash(self): + assert XmlType() == XmlType() + assert hash(XmlType()) == hash(XmlType()) + + def test_not_a_subclass_of_json_or_text(self): + """The distinction is real: SQL/XML and SQL/JSON differ in operations, + standards and in which backends implement which. XML is likewise not + TextType — SQL Server's ``xml`` is binary, Oracle's stores an infoset.""" + assert not issubclass(XmlType, JsonType) + assert not issubclass(XmlType, TextType) + assert XmlType() != JsonType() + assert XmlType() != TextType() + + def test_backends_without_xml_name_their_substitute(self): + """Every dialect must take a position on ``xml`` — render it, or name + the substitute. Silence is the one answer that is not allowed.""" + from rhosocial.activerecord.backend.impl.sqlite.dialect import ( + SQLiteDialect, + ) + + sqlite = SQLiteDialect() + assert "xml" not in sqlite.supports_data_types() + assert "xml" in sqlite.suggested_data_types() + + # --------------------------------------------------------------------------- # Type parsing # --------------------------------------------------------------------------- diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_dialect_binding_semantics.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_dialect_binding_semantics.py index a9e6833f2..d648a4f52 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_dialect_binding_semantics.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_dialect_binding_semantics.py @@ -192,7 +192,7 @@ def test_constructor_rejects_dialect_options(self, dummy_dialect: DummyDialect): with pytest.raises(TypeError): VarCharType(dummy_dialect, 255, dialect_options={"unsigned": True}) - def test_equality_uses_type_params_only(self, dummy_dialect: DummyDialect): + def test_equality_uses_declared_identity_only(self, dummy_dialect: DummyDialect): assert VarCharType(dummy_dialect, 255) == VarCharType(dummy_dialect, 255) assert VarCharType(dummy_dialect, 255) != VarCharType(dummy_dialect, 10) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_contract.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_contract.py index cfde65bcf..6222eb456 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_contract.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_contract.py @@ -34,7 +34,7 @@ "construction check raises ValueError on None/[])", "statements.ddl_alter.AlterConstraint": "requires a non-empty constraint name", "statements.ddl_alter.ValidateConstraint": "requires a non-empty constraint name", - "statements.ddl_domain.AddDomainCheckAction": "requires a concrete DomainCheckConstraint", +"statements.ddl_domain.AddDomainCheckAction": "requires a concrete DomainCheckConstraint", "statements.ddl_domain.DomainCheckConstraint": "requires a concrete check condition", # The XML constructors take a sequence of their own item types, and an # empty one is structurally meaningless -- there is no value to check and @@ -43,6 +43,14 @@ "expression.xml.XMLForestExpression": "requires a non-empty forest item list", "expression.xml.XMLConcatExpression": "requires a non-empty part list", "expression.xml.XMLTableExpression": "requires a row-specifying context item", + "expression.uuid.UUIDConstantExpression": "requires `which` to name a " + "constant kind ('nil' / 'max'); __init__ rejects anything else, and a " + "heuristic filler has no way to guess a valid one", + "types.custom.CustomType": "requires `raw`, the backend's own spelling of " + "the type. It is the escape hatch for a type name this library does " + "not model -- DOUBLE PRECISION, a vendor's domain type -- and there is " + "nothing to guess: the name is the whole point, and it is validated as " + "a grammar rather than accepted blindly", } diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_coverage_gaps.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_coverage_gaps.py index 7e0543271..bfa3feb52 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_coverage_gaps.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_coverage_gaps.py @@ -8,6 +8,12 @@ from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.expression.operators import BinaryArithmeticExpression from rhosocial.activerecord.backend.expression.objects import Table +from rhosocial.activerecord.backend.expression.types import ( + CustomType, + DecimalType, + IntegerType, + TextType, +) class TestColumnSchemaName: @@ -31,13 +37,13 @@ class TestLiteralCastTypes: def test_literal_with_single_cast(self, dummy_dialect): lit = Literal(dummy_dialect, 42) - expr = lit.cast("INTEGER") + expr = lit.cast(IntegerType(dummy_dialect)) sql, params = expr.to_sql() assert "CAST" in sql or "INTEGER" in sql def test_literal_with_chained_casts(self, dummy_dialect): lit = Literal(dummy_dialect, "100") - expr = lit.cast("money").cast("numeric") + expr = lit.cast(CustomType(dummy_dialect, raw='money')).cast(DecimalType(dummy_dialect)) sql, params = expr.to_sql() assert sql # Verify it doesn't crash @@ -47,7 +53,7 @@ class TestSubqueryCastTypes: def test_subquery_with_cast(self, dummy_dialect): subquery = Subquery(dummy_dialect, "SELECT id FROM users") - expr = subquery.cast("TEXT") + expr = subquery.cast(TextType(dummy_dialect)) sql, params = expr.to_sql() assert "CAST" in sql or "TEXT" in sql @@ -59,7 +65,7 @@ def test_arithmetic_with_cast(self, dummy_dialect): left = Column(dummy_dialect, "price") right = Literal(dummy_dialect, 10) expr = BinaryArithmeticExpression(dummy_dialect, "+", left, right) - casted = expr.cast("DECIMAL") + casted = expr.cast(DecimalType(dummy_dialect)) sql, params = casted.to_sql() assert "CAST" in sql or "DECIMAL" in sql diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_data_types.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_data_types.py index 799fe9f1b..73ee50d3f 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_data_types.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_data_types.py @@ -12,10 +12,10 @@ Column, Literal, ComparisonPredicate, + FunctionCall, JSONPathMode, ArrayExpression, ) -from rhosocial.activerecord.backend.expression.aggregates import AggregateFunctionCall from rhosocial.activerecord.backend.expression.functions import count, sum_ from rhosocial.activerecord.backend.expression.types import ( ArrayType, @@ -24,7 +24,6 @@ DateTimeType, DecimalType, FloatType, - IntType, IntegerType, IntervalType, TimeType, @@ -91,7 +90,7 @@ def test_data_type_without_dialect_raises(self): IntegerType().to_sql() def test_data_type_to_sql_with_dialect_arg(self, dialect): - assert IntType(dialect=dialect).to_sql() == ("INT", ()) + assert IntegerType(dialect=dialect, spelling="int").to_sql() == ("INT", ()) def test_cross_type_inequality(self): assert IntegerType() != CharType(None, 10) @@ -108,18 +107,30 @@ def test_array_hash(self): assert hash(ArrayType(None, IntegerType())) == hash(ArrayType(None, IntegerType())) def test_array_is_equivalent(self): - assert ArrayType(None, IntegerType()).is_equivalent(ArrayType(None, IntegerType())) - assert not ArrayType(None, IntegerType(), dimensions=2).is_equivalent(ArrayType(None, IntegerType())) + assert ArrayType(None, IntegerType()) == ArrayType(None, IntegerType()) + assert ArrayType(None, IntegerType(), dimensions=2) != ArrayType(None, IntegerType()) def test_array_is_element_type_equivalent_with_array(self): + """``is_element_type_equivalent`` answers a different question from + ``==``: not "is this the same declaration" but "does this array store + the same kind of thing", so dimensions are ignored.""" assert ArrayType(None, IntegerType()).is_element_type_equivalent(ArrayType(None, IntegerType(), dimensions=2)) def test_array_is_element_type_equivalent_with_plain_type(self): assert ArrayType(None, IntegerType()).is_element_type_equivalent(IntegerType()) assert not ArrayType(None, IntegerType()).is_element_type_equivalent(CharType(None, 10)) - def test_array_type_params(self): - assert ArrayType(None, IntegerType(), dimensions=2)._type_params() == (IntegerType(), 2) + def test_array_declares_its_identity_fields(self): + """An array's identity is its element type and its dimensionality. + + Declared as a class constant rather than a method, so ``__eq__``, + ``__hash__`` and ``repr`` cannot each answer the question differently. + """ + assert ArrayType.PARAMETERS == ("element_type", "dimensions") + arr = ArrayType(None, IntegerType(), dimensions=2) + assert arr.identity() == (IntegerType(), 2) + # and a dimensionality change is a change of declaration + assert arr != ArrayType(None, IntegerType(), dimensions=1) def test_array_repr(self): assert "ArrayType" in repr(ArrayType(None, IntegerType())) @@ -157,7 +168,7 @@ def test_from_value_invalid_type(self): class TestAggregateGetParamsWithFilter: - """AggregateFunctionCall.get_params() includes the filter predicate.""" + """FunctionCall.get_params() includes the filter predicate.""" def test_get_params_with_filter(self, dialect): agg = count(dialect, "*", alias="active_count").filter( @@ -173,13 +184,13 @@ def test_get_params_without_filter(self, dialect): assert params.get("filter_predicate") is None def test_filter_returns_self(self, dialect): - agg = AggregateFunctionCall(dialect, "COUNT", "*") + agg = FunctionCall(dialect, "COUNT", "*", is_aggregate=True) predicate = Column(dialect, "status") == Literal(dialect, "active") assert agg.filter(predicate) is agg assert agg.get_params()["filter_predicate"] is predicate def test_chained_filters_combine(self, dialect): - agg = AggregateFunctionCall(dialect, "COUNT", "*") + agg = FunctionCall(dialect, "COUNT", "*", is_aggregate=True) agg.filter(Column(dialect, "a") == Literal(dialect, 1)) agg.filter(Column(dialect, "b") == Literal(dialect, 2)) assert "AND" in agg.get_params()["filter_predicate"].to_sql()[0] diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_edge_branches.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_edge_branches.py index 0bcf9aad6..d46cb1e4f 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_edge_branches.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_edge_branches.py @@ -68,7 +68,7 @@ class TestCoreExpressionBranches: """Branch coverage for core/operator expressions.""" def test_literal_cast_and_alias(self, dialect): - expr = Literal(dialect, 42).cast("DECIMAL").as_("n") + expr = Literal(dialect, 42).cast(DecimalType(dialect)).as_("n") sql, params = expr.to_sql() assert "CAST" in sql or "DECIMAL" in sql assert "AS" in sql @@ -100,7 +100,7 @@ def test_wildcard_expression_qualified(self, dialect): def test_binary_arithmetic_with_cast(self, dialect): expr = BinaryArithmeticExpression(dialect, "+", Column(dialect, "price"), Literal(dialect, 10)) - casted = expr.cast("DECIMAL") + casted = expr.cast(DecimalType(dialect)) aliased = casted.as_("total") sql, params = aliased.to_sql() assert "CAST" in sql or "DECIMAL" in sql @@ -392,7 +392,7 @@ def test_numeric_types_inequality(self): def test_array_and_custom_inequality(self): assert ArrayType(None, IntegerType()) != ArrayType(None, CharType(None, 10)) assert ArrayType(None, IntegerType()) != CharType(None, 10) - assert ArrayType(None, IntegerType()).is_equivalent(CharType(None, 10)) is False + assert ArrayType(None, IntegerType()) != CharType(None, 10) assert CustomType(None, "geometry") != IntegerType() def test_hash_branches(self): diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_roundtrip_all.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_roundtrip_all.py index 9a8bdd207..98d2c7f53 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_roundtrip_all.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_roundtrip_all.py @@ -715,6 +715,16 @@ def path_pattern(d): # ENUM type. Its `values` list is keyword-only behind a defaulted positional, # so the introspective constructor skips it and the type declares no members. "rhosocial.activerecord.backend.expression.types.enum_.EnumType", + # CUSTOM type. `raw` names the SQL type string and carries a default, so the + # introspective constructor skips it and builds a type with no spelling. The + # default cannot help: the class declares `dialect` first and `raw` after it, + # so a required `raw` behind that default is not expressible as a signature. + "rhosocial.activerecord.backend.expression.types.custom.CustomType", + # UUID constant. `which` must name a constant kind -- 'nil' or 'max' -- and + # __init__ rejects anything else, so the guess's "x" is refused at + # construction. There is no value the filler could offer that is both a valid + # constant and not a guess about which one the caller wanted. + "rhosocial.activerecord.backend.expression.uuid.UUIDConstantExpression", ) # XMLTABLE used to be a fifth entry, needing a row source document, a COLUMNS list # of typed projections and a pass-through clause. Its `columns` and `passing` @@ -797,13 +807,6 @@ def path_pattern(d): TypeError, "does not declare a valid generic type name", ), - # A core type the Dummy dialect has no `format_data_type_uuid` for. Dummy is - # the SQL-generation switch board and deliberately models the mainstream - # types only; UUID is not one of them. A Dummy capability gap, not a defect. - "rhosocial.activerecord.backend.expression.types.uuid_.UUIDType": ( - TypeError, - "does not support the generic type 'uuid'", - ), } diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_serialization.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_serialization.py index bf7899db7..0a2c2126f 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_serialization.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_serialization.py @@ -33,7 +33,6 @@ LimitOffsetClause, ForUpdateClause, ) -from rhosocial.activerecord.backend.expression.aggregates import AggregateFunctionCall from rhosocial.activerecord.backend.expression.types import IntegerType from rhosocial.activerecord.backend.expression.serialization import ( serialize, @@ -169,7 +168,9 @@ class TestAggregateRoundtrip: """T5: Aggregate function round-trip test.""" def test_aggregate_function_roundtrip(self, dummy_dialect): - expr = AggregateFunctionCall(dummy_dialect, "SUM", Column(dummy_dialect, "amount"), alias="total") + expr = FunctionCall( + dummy_dialect, "SUM", Column(dummy_dialect, "amount"), alias="total", is_aggregate=True + ) assert deserialize(serialize(expr), dummy_dialect).to_sql() == expr.to_sql() @@ -306,7 +307,7 @@ def to_sql(self): def test_serialize_deserialize_tuple_in_params(self, dummy_dialect): col = Column(dummy_dialect, "status") - in_pred = col.in_(["active", "pending", "draft"]) + in_pred = InPredicate(dummy_dialect, col, Literal(dummy_dialect, ("active", "pending", "draft"))) spec = serialize(in_pred) restored = deserialize(spec, dummy_dialect) assert restored.to_sql() == in_pred.to_sql() @@ -394,7 +395,7 @@ def test_expression_serializer_tuple_in_params(self, dummy_dialect): serializer = ExpressionSerializer(max_depth=64) col = Column(dummy_dialect, "status") - in_pred = col.in_(["active", "pending"]) + in_pred = InPredicate(dummy_dialect, col, Literal(dummy_dialect, ("active", "pending"))) spec = serializer.serialize(in_pred) restored = serializer.deserialize(spec, dummy_dialect) @@ -653,7 +654,7 @@ class TestQueryPartsRoundtrip: """Query parts round-trip tests.""" def test_group_by_having_roundtrip(self, dummy_dialect): - agg = AggregateFunctionCall(dummy_dialect, "COUNT") + agg = FunctionCall(dummy_dialect, "COUNT", is_aggregate=True) pred = ComparisonPredicate(dummy_dialect, ">", agg, Literal(dummy_dialect, 10)) expr = GroupByHavingClause( dummy_dialect, @@ -832,7 +833,10 @@ def test_explain_expression_roundtrip(self, dummy_dialect): expr = ExplainExpression(dummy_dialect, statement=Column(dummy_dialect, "users")) restored = deserialize(serialize(expr), dummy_dialect) - assert restored.get_params() == expr.get_params() + # A bare Column compares by identity, so equality goes through the + # rendered SQL, as in the other roundtrip tests in this file. + assert restored.to_sql() == expr.to_sql() + assert restored.get_params()["options"] == expr.get_params()["options"] class TestAllowedTypesAllowlist: diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_traversal_dummy2.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_traversal_dummy2.py index 992898128..3fc2b6356 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_traversal_dummy2.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_traversal_dummy2.py @@ -41,7 +41,6 @@ BetweenPredicate, ) from rhosocial.activerecord.backend.expression.sources import NamedRelationRef -from rhosocial.activerecord.backend.expression.aggregates import AggregateFunctionCall from rhosocial.activerecord.backend.expression.query_parts import ( WhereClause, OrderByClause, @@ -70,12 +69,11 @@ ArrayExpression, CaseExpression, ExistsExpression, - JSONExpression, + JSONDocumentExpression, OrderedSetAggregation, WindowClause, WindowDefinition, WindowFrameSpecification, - WindowFunctionCall, WindowSpecification, ) from rhosocial.activerecord.backend.expression.core import Subquery @@ -174,9 +172,9 @@ params_func=lambda d: dict(dialect=d, expr=Column(d, "age"), low=Literal(d, 18), high=Literal(d, 65)), ), dict( - name="AggregateFunctionCall", - cls=AggregateFunctionCall, - params_func=lambda d: dict(dialect=d, func_name="SUM", args=(Column(d, "amount"),)), + name="FunctionCallAggregate", + cls=FunctionCall, + params_func=lambda d: dict(dialect=d, func_name="SUM", args=(Column(d, "amount"),), is_aggregate=True), ), dict( name="WhereClause", @@ -322,8 +320,8 @@ params_func=lambda d: dict(dialect=d, subquery=Subquery(d, "SELECT 1")), ), dict( - name="JSONExpression", - cls=JSONExpression, + name="JSONDocumentExpression", + cls=JSONDocumentExpression, params_func=lambda d: dict(dialect=d, column=Column(d, "data"), path="$.key", operation="->"), ), dict( @@ -367,9 +365,9 @@ params_func=lambda d: dict(dialect=d, frame_type="RANGE", start_frame="UNBOUNDED PRECEDING"), ), dict( - name="WindowFunctionCall", - cls=WindowFunctionCall, - params_func=lambda d: dict(dialect=d, function_name="ROW_NUMBER", window_spec="w"), + name="FunctionCallWindow", + cls=FunctionCall, + params_func=lambda d: dict(dialect=d, func_name="ROW_NUMBER", window_spec="w"), ), dict( name="WindowSpecification", diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_value_codecs.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_value_codecs.py index 4e17c4914..61f5740c3 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_value_codecs.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expression_value_codecs.py @@ -28,6 +28,7 @@ serialize_json, serialize_xml, ) +from rhosocial.activerecord.backend.expression.types import DecimalType class Status(Enum): @@ -69,12 +70,14 @@ def test_dict_roundtrip(self, dummy_dialect, value): assert restored.value == value def test_json_nested_expression(self, dummy_dialect): - expr = Column(dummy_dialect, "t") > dt.datetime(2026, 1, 1) + expr = ComparisonPredicate( + dummy_dialect, ">", Column(dummy_dialect, "t"), Literal(dummy_dialect, dt.datetime(2026, 1, 1)) + ) restored = deserialize_json(serialize_json(expr), dummy_dialect) assert restored.to_sql() == expr.to_sql() def test_json_combined_with_cast_chain(self, dummy_dialect): - expr = Column(dummy_dialect, "amount").cast("numeric") + expr = Column(dummy_dialect, "amount").cast(DecimalType(dummy_dialect)) restored = deserialize_json(serialize_json(expr), dummy_dialect) assert restored.to_sql() == expr.to_sql() @@ -121,7 +124,7 @@ def test_xml_nested_expression(self, dummy_dialect): assert restored.to_sql() == expr.to_sql() def test_xml_cast_chain(self, dummy_dialect): - expr = Column(dummy_dialect, "amount").cast("numeric") + expr = Column(dummy_dialect, "amount").cast(DecimalType(dummy_dialect)) restored = deserialize_xml(serialize_xml(expr), dummy_dialect) assert restored.to_sql() == expr.to_sql() diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_advanced.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_advanced.py index 1c1f5a1a3..5bf132ca6 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_advanced.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_advanced.py @@ -4,19 +4,24 @@ from rhosocial.activerecord.backend.expression import ( Column, Literal, + FunctionCall, Subquery, ComparisonPredicate, CaseExpression, ExistsExpression, AnyExpression, AllExpression, - WindowFunctionCall, WindowSpecification, WindowFrameSpecification, - JSONExpression, ArrayExpression, + JSONDocumentExpression, + JSONTextExpression, ) from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect +from rhosocial.activerecord.backend.expression.types import ( + DateType, + IntegerType, +) class TestAdvancedExpressions: @@ -61,7 +66,7 @@ def test_case_simple_expression(self, dummy_dialect: DummyDialect): def test_cast_column(self, dummy_dialect: DummyDialect): """Tests cast() method on Column.""" col = Column(dummy_dialect, "price") - cast_expr = col.cast("INTEGER") + cast_expr = col.cast(IntegerType(dummy_dialect)) sql, params = cast_expr.to_sql() assert sql == 'CAST("price" AS INTEGER)' assert params == () @@ -69,7 +74,7 @@ def test_cast_column(self, dummy_dialect: DummyDialect): def test_cast_literal(self, dummy_dialect: DummyDialect): """Tests cast() method on Literal.""" lit = Literal(dummy_dialect, "2023-01-01") - cast_expr = lit.cast("DATE") + cast_expr = lit.cast(DateType(dummy_dialect)) sql, params = cast_expr.to_sql() assert sql == "CAST(? AS DATE)" assert params == ("2023-01-01",) @@ -124,7 +129,7 @@ def test_any_with_subquery(self, dummy_dialect: DummyDialect): assert sql == '("item_id" = ANY(SELECT product_id FROM top_sellers WHERE category = ?))' assert params == ("electronics",) - # --- WindowFunctionCall --- + # --- FunctionCall with a window specification --- def test_window_function_basic(self, dummy_dialect: DummyDialect): """Tests a basic window function with PARTITION BY and ORDER BY.""" # Create window specification @@ -136,7 +141,7 @@ def test_window_function_basic(self, dummy_dialect: DummyDialect): order_by=OrderByClause(dummy_dialect, [(Column(dummy_dialect, "salary"), "DESC")]), ) # Create window function call - window_expr = WindowFunctionCall(dummy_dialect, function_name="RANK", window_spec=window_spec) + window_expr = FunctionCall(dummy_dialect, "RANK", window_spec=window_spec) sql, params = window_expr.to_sql() expected = 'RANK() OVER (PARTITION BY "department" ORDER BY "salary" DESC)' assert sql == expected @@ -158,10 +163,10 @@ def test_window_function_with_frame(self, dummy_dialect: DummyDialect): frame=frame_spec, ) # Create window function call - window_expr = WindowFunctionCall( + window_expr = FunctionCall( dummy_dialect, - function_name="SUM", - args=[Column(dummy_dialect, "amount")], + "SUM", + Column(dummy_dialect, "amount"), window_spec=window_spec, alias="running_total", ) @@ -170,7 +175,7 @@ def test_window_function_with_frame(self, dummy_dialect: DummyDialect): assert sql == expected assert params == () - # --- JSONExpression --- + # --- JSONDocumentExpression --- @pytest.mark.parametrize( "col_name, path, operation, expected_sql, expected_params", [ @@ -183,7 +188,7 @@ def test_json_expression( ): """Tests JSON path extraction operations.""" json_col = Column(dummy_dialect, col_name) - json_expr = JSONExpression(dummy_dialect, json_col, path, operation=operation) + json_expr = JSONDocumentExpression(dummy_dialect, json_col, path, operation=operation) sql, params = json_expr.to_sql() assert sql == expected_sql assert params == expected_params diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_collation_datetime.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_collation_datetime.py index 10fad67ef..4ebaa9d36 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_collation_datetime.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_collation_datetime.py @@ -15,6 +15,7 @@ import pytest from rhosocial.activerecord.backend.expression import ( + Literal, Column, DateTimeAddExpression, DateTimeDiffExpression, @@ -38,6 +39,7 @@ validate_interval_value, ) from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect +from rhosocial.activerecord.backend.expression.types import TextType class DummyCollation(Enum): @@ -78,7 +80,7 @@ def test_collate_with_alias(self, dialect): assert params == () def test_collate_with_cast(self, dialect): - expr = Column(dialect, "name").collate("NOCASE").cast("TEXT") + expr = Column(dialect, "name").collate("NOCASE").cast(TextType(dialect)) sql, params = expr.to_sql() assert "COLLATE NOCASE" in sql assert params == () @@ -120,7 +122,7 @@ def test_date_trunc_expression(self, dialect): assert params == () def test_extract_factory_with_column_name(self, dialect): - expr = extract(dialect, "year", "created_at") + expr = extract(dialect, "year", Column(dialect, "created_at")) assert isinstance(expr, ExtractExpression) sql, params = expr.to_sql() assert sql == 'EXTRACT(YEAR FROM "created_at")' @@ -169,7 +171,7 @@ def test_datetime_subtract(self, dialect): assert params == () def test_date_add_factory_numeric(self, dialect): - expr = date_add(dialect, "created_at", 1, "day") + expr = date_add(dialect, Column(dialect, "created_at"), 1, "day") assert isinstance(expr, DateTimeAddExpression) sql, params = expr.to_sql() assert sql == '"created_at" + INTERVAL \'1\' DAY' @@ -181,7 +183,7 @@ def test_date_add_factory_interval_object(self, dialect): assert isinstance(expr, DateTimeAddExpression) def test_date_sub_factory_numeric(self, dialect): - expr = date_sub(dialect, "created_at", 1, "day") + expr = date_sub(dialect, Column(dialect, "created_at"), 1, "day") assert isinstance(expr, DateTimeSubtractExpression) sql, params = expr.to_sql() assert sql == '"created_at" - INTERVAL \'1\' DAY' @@ -194,14 +196,14 @@ def test_date_sub_factory_interval_object(self, dialect): def test_ensure_interval_unit_conflict(self, dialect): with pytest.raises(ValueError): - date_add(dialect, "created_at", IntervalExpression(dialect, 1, IntervalUnit.DAY), "day") + date_add(dialect, Column(dialect, "created_at"), IntervalExpression(dialect, 1, IntervalUnit.DAY), "day") def test_ensure_interval_missing_unit(self, dialect): with pytest.raises(ValueError): - date_add(dialect, "created_at", 1) + date_add(dialect, Column(dialect, "created_at"), 1) def test_date_diff_factory_constructs(self, dialect): - expr = date_diff(dialect, "day", "created_at", "updated_at") + expr = date_diff(dialect, "day", "created_at", Literal(dialect, "updated_at")) assert isinstance(expr, DateTimeDiffExpression) def test_date_diff_to_sql_unsupported(self, dialect): diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_functions.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_functions.py index e8fbf95c3..0bb366f74 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_functions.py @@ -1,7 +1,15 @@ # tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_functions.py import pytest -from rhosocial.activerecord.backend.expression import FunctionCall, Column, Literal, count, sum_, avg +from rhosocial.activerecord.backend.expression import ( + FunctionCall, + Column, + Literal, + ComparisonPredicate, + count, + sum_, + avg, +) from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect @@ -75,7 +83,7 @@ def test_aggregate_function_with_filter_clause(self, dummy_dialect: DummyDialect """Tests an aggregate function with a FILTER (WHERE ...) clause.""" # COUNT with a single filter active_count = count(dummy_dialect, "*", alias="active_count").filter( - Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "active")) ) sql, params = active_count.to_sql() assert sql == 'COUNT(*) FILTER (WHERE "status" = ?) AS "active_count"' @@ -84,8 +92,16 @@ def test_aggregate_function_with_filter_clause(self, dummy_dialect: DummyDialect # SUM with multiple chained filters (combined with AND) high_value_sum = ( sum_(dummy_dialect, Column(dummy_dialect, "amount"), alias="high_value_sum") - .filter(Column(dummy_dialect, "category") == Literal(dummy_dialect, "sales")) - .filter(Column(dummy_dialect, "priority") == Literal(dummy_dialect, True)) + .filter( + ComparisonPredicate( + dummy_dialect, "=", Column(dummy_dialect, "category"), Literal(dummy_dialect, "sales") + ) + ) + .filter( + ComparisonPredicate( + dummy_dialect, "=", Column(dummy_dialect, "priority"), Literal(dummy_dialect, True) + ) + ) ) sql, params = high_value_sum.to_sql() assert sql == 'SUM("amount") FILTER (WHERE "category" = ? AND "priority" = ?) AS "high_value_sum"' diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_predicates.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_predicates.py index 0529de17b..5cc02fc7c 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_predicates.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_expressions_predicates.py @@ -5,6 +5,7 @@ Literal, RawSQLExpression, Subquery, + BooleanColumn, ComparisonPredicate, LogicalPredicate, InPredicate, @@ -195,7 +196,8 @@ def test_is_boolean_predicate( def test_is_boolean_mixin_methods(self, dummy_dialect: DummyDialect): """Tests is_true(), is_not_true(), is_false(), is_not_false() methods.""" - col = Column(dummy_dialect, "flag") + # IS TRUE/FALSE lives on ComparisonMixin, so the column must be typed. + col = BooleanColumn(dummy_dialect, "flag") sql, params = col.is_true().to_sql() assert sql == '"flag" IS TRUE' @@ -215,7 +217,7 @@ def test_is_boolean_mixin_methods(self, dummy_dialect: DummyDialect): def test_is_boolean_with_logical_combination(self, dummy_dialect: DummyDialect): """Tests IS TRUE/FALSE combined with logical predicates.""" - is_active = Column(dummy_dialect, "is_active").is_true() + is_active = BooleanColumn(dummy_dialect, "is_active").is_true() age_pred = ComparisonPredicate(dummy_dialect, ">", Column(dummy_dialect, "age"), Literal(dummy_dialect, 18)) combined = LogicalPredicate(dummy_dialect, "AND", is_active, age_pred) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_functions.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_functions.py index bd3c57f5a..11591baa0 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_functions.py @@ -7,6 +7,7 @@ from rhosocial.activerecord.backend.expression import ( Column, + Literal, count, sum_, avg, @@ -79,7 +80,6 @@ cube, # Added grouping functions concat_op, # Added string concatenation operator function ) -from rhosocial.activerecord.backend.expression.operators import RawSQLExpression from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect @@ -235,7 +235,11 @@ def test_trim_function_default(self, dummy_dialect: DummyDialect): """Test TRIM function with default direction.""" func = trim(dummy_dialect, "name") sql, params = func.to_sql() - assert isinstance(func, RawSQLExpression) + # Trim is a node with its own dialect hook rather than a typed + # function call, which is what lets a dialect without the standard + # syntax (SQLite) override the spelling. What is asserted is that the + # result still carries the string surface. + assert hasattr(func, "upper") and hasattr(func, "substr") assert "TRIM(BOTH FROM" in sql def test_trim_function_with_chars(self, dummy_dialect: DummyDialect): @@ -279,11 +283,17 @@ def test_lpad_function(self, dummy_dialect: DummyDialect): assert params == ("text", 10, "0") def test_lpad_function_without_pad(self, dummy_dialect: DummyDialect): - """Test LPAD function without pad character.""" + """Test LPAD function without pad character. + + An omitted pad means one space and is passed **explicitly**, because + the backends disagree on whether the argument is optional at all + (MySQL raises 1582 without it, MariaDB fills with spaces). Measured + 2026-10-09, matrix section F.3. + """ func = lpad(dummy_dialect, "text", 10) sql, params = func.to_sql() assert "LPAD(" in sql - assert params == ("text", 10) + assert params == ("text", 10, " ") def test_rpad_function(self, dummy_dialect: DummyDialect): """Test RPAD function.""" @@ -293,11 +303,15 @@ def test_rpad_function(self, dummy_dialect: DummyDialect): assert params == ("text", 10, "0") def test_rpad_function_without_pad(self, dummy_dialect: DummyDialect): - """Test RPAD function without pad character.""" + """Test RPAD function without pad character. + + Same contract as :meth:`test_lpad_function_without_pad`: an omitted + pad is spelled out as one space. + """ func = rpad(dummy_dialect, "text", 10) sql, params = func.to_sql() assert "RPAD(" in sql - assert params == ("text", 10) + assert params == ("text", 10, " ") def test_reverse_function(self, dummy_dialect: DummyDialect): """Test REVERSE function.""" @@ -318,72 +332,72 @@ class TestMathFunctionFactories: def test_abs_function(self, dummy_dialect: DummyDialect): """Test ABS function.""" - func = abs_(dummy_dialect, -5) + func = abs_(dummy_dialect, Literal(dummy_dialect, -5)) sql, params = func.to_sql() assert "ABS(" in sql def test_round_function(self, dummy_dialect: DummyDialect): """Test ROUND function.""" - func = round_(dummy_dialect, 3.14159) + func = round_(dummy_dialect, Literal(dummy_dialect, 3.14159)) sql, params = func.to_sql() assert "ROUND(" in sql def test_round_function_with_decimals(self, dummy_dialect: DummyDialect): """Test ROUND function with decimal places.""" - func = round_(dummy_dialect, 3.14159, 2) + func = round_(dummy_dialect, Literal(dummy_dialect, 3.14159), 2) sql, params = func.to_sql() assert "ROUND(" in sql assert params == (3.14159, 2) def test_ceil_function(self, dummy_dialect: DummyDialect): """Test CEIL function.""" - func = ceil(dummy_dialect, 3.14) + func = ceil(dummy_dialect, Literal(dummy_dialect, 3.14)) sql, params = func.to_sql() assert "CEIL(" in sql def test_floor_function(self, dummy_dialect: DummyDialect): """Test FLOOR function.""" - func = floor(dummy_dialect, 3.99) + func = floor(dummy_dialect, Literal(dummy_dialect, 3.99)) sql, params = func.to_sql() assert "FLOOR(" in sql def test_sqrt_function(self, dummy_dialect: DummyDialect): """Test SQRT function.""" - func = sqrt(dummy_dialect, 16) + func = sqrt(dummy_dialect, Literal(dummy_dialect, 16)) sql, params = func.to_sql() assert "SQRT(" in sql def test_power_function(self, dummy_dialect: DummyDialect): """Test POWER function.""" - func = power(dummy_dialect, 2, 3) + func = power(dummy_dialect, Literal(dummy_dialect, 2), Literal(dummy_dialect, 3)) sql, params = func.to_sql() assert "POWER(" in sql assert params == (2, 3) def test_exp_function(self, dummy_dialect: DummyDialect): """Test EXP function.""" - func = exp(dummy_dialect, 1) + func = exp(dummy_dialect, Literal(dummy_dialect, 1)) sql, params = func.to_sql() assert "EXP(" in sql def test_log_function(self, dummy_dialect: DummyDialect): """Test LOG function.""" - func = log(dummy_dialect, 10) + func = log(dummy_dialect, Literal(dummy_dialect, 10)) sql, params = func.to_sql() assert "LOG(" in sql def test_log_function_with_base(self, dummy_dialect: DummyDialect): """Test LOG function with base.""" - func = log(dummy_dialect, 100, 10) + func = log(dummy_dialect, Literal(dummy_dialect, 100), Literal(dummy_dialect, 10)) sql, params = func.to_sql() assert "LOG(" in sql assert params == (100, 10) def test_trigonometric_functions(self, dummy_dialect: DummyDialect): """Test trigonometric functions.""" - sin_func = sin(dummy_dialect, 0) - cos_func = cos(dummy_dialect, 0) - tan_func = tan(dummy_dialect, 0) + sin_func = sin(dummy_dialect, Literal(dummy_dialect, 0)) + cos_func = cos(dummy_dialect, Literal(dummy_dialect, 0)) + tan_func = tan(dummy_dialect, Literal(dummy_dialect, 0)) sin_sql, sin_params = sin_func.to_sql() cos_sql, cos_params = cos_func.to_sql() @@ -492,14 +506,14 @@ def test_date_part_functions(self, dummy_dialect: DummyDialect): def test_date_part_function(self, dummy_dialect: DummyDialect): """Test DATE_PART function.""" - func = date_part(dummy_dialect, "year", "created_at") + func = date_part(dummy_dialect, "year", Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert sql == 'EXTRACT(YEAR FROM "created_at")' assert params == () def test_date_trunc_function(self, dummy_dialect: DummyDialect): """Test DATE_TRUNC function.""" - func = date_trunc(dummy_dialect, "month", "created_at") + func = date_trunc(dummy_dialect, "month", Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert sql == "DATE_TRUNC('month', \"created_at\")" assert params == () @@ -645,11 +659,13 @@ class TestTypeConversionFunctionFactories: def test_cast_function(self, dummy_dialect: DummyDialect): """Test CAST function.""" from rhosocial.activerecord.backend.expression.core import CastExpression, Column + from rhosocial.activerecord.backend.expression.types import CustomType - func = cast(dummy_dialect, "value", "INTEGER") + func = cast(dummy_dialect, Column(dummy_dialect, "value"), + CustomType(dummy_dialect, raw="INTEGER")) # cast() wraps the (string-as-column) expression in a CastExpression node assert isinstance(func, CastExpression) - assert func.target_type == "INTEGER" + assert func.target_type.raw == "INTEGER" assert isinstance(func.expression, Column) sql, params = func.to_sql() assert "CAST(" in sql @@ -752,7 +768,7 @@ class TestMathFunctionFactoriesExtended: def test_sin_function(self, dummy_dialect: DummyDialect): """Test SIN function.""" - func = sin(dummy_dialect, "angle") + func = sin(dummy_dialect, Column(dummy_dialect, "angle")) sql, params = func.to_sql() assert "SIN(" in sql # When passing string to sin, it's treated as a column name, so no parameters @@ -760,7 +776,7 @@ def test_sin_function(self, dummy_dialect: DummyDialect): def test_cos_function(self, dummy_dialect: DummyDialect): """Test COS function.""" - func = cos(dummy_dialect, "angle") + func = cos(dummy_dialect, Column(dummy_dialect, "angle")) sql, params = func.to_sql() assert "COS(" in sql # When passing string to cos, it's treated as a column name, so no parameters @@ -768,7 +784,7 @@ def test_cos_function(self, dummy_dialect: DummyDialect): def test_tan_function(self, dummy_dialect: DummyDialect): """Test TAN function.""" - func = tan(dummy_dialect, "angle") + func = tan(dummy_dialect, Column(dummy_dialect, "angle")) sql, params = func.to_sql() assert "TAN(" in sql # When passing string to tan, it's treated as a column name, so no parameters @@ -780,7 +796,7 @@ class TestDateTimeFunctionFactoriesExtended: def test_year_function(self, dummy_dialect: DummyDialect): """Test YEAR function.""" - func = year(dummy_dialect, "created_at") + func = year(dummy_dialect, Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert "YEAR(" in sql # When passing string to year, it's treated as a column name, so no parameters @@ -788,7 +804,7 @@ def test_year_function(self, dummy_dialect: DummyDialect): def test_month_function(self, dummy_dialect: DummyDialect): """Test MONTH function.""" - func = month(dummy_dialect, "created_at") + func = month(dummy_dialect, Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert "MONTH(" in sql # When passing string to month, it's treated as a column name, so no parameters @@ -796,7 +812,7 @@ def test_month_function(self, dummy_dialect: DummyDialect): def test_day_function(self, dummy_dialect: DummyDialect): """Test DAY function.""" - func = day(dummy_dialect, "created_at") + func = day(dummy_dialect, Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert "DAY(" in sql # When passing string to day, it's treated as a column name, so no parameters @@ -804,7 +820,7 @@ def test_day_function(self, dummy_dialect: DummyDialect): def test_hour_function(self, dummy_dialect: DummyDialect): """Test HOUR function.""" - func = hour(dummy_dialect, "created_at") + func = hour(dummy_dialect, Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert "HOUR(" in sql # When passing string to hour, it's treated as a column name, so no parameters @@ -812,7 +828,7 @@ def test_hour_function(self, dummy_dialect: DummyDialect): def test_minute_function(self, dummy_dialect: DummyDialect): """Test MINUTE function.""" - func = minute(dummy_dialect, "created_at") + func = minute(dummy_dialect, Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert "MINUTE(" in sql # When passing string to minute, it's treated as a column name, so no parameters @@ -820,7 +836,7 @@ def test_minute_function(self, dummy_dialect: DummyDialect): def test_second_function(self, dummy_dialect: DummyDialect): """Test SECOND function.""" - func = second(dummy_dialect, "created_at") + func = second(dummy_dialect, Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert "SECOND(" in sql # When passing string to second, it's treated as a column name, so no parameters diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_generated_column_protocol.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_generated_column_protocol.py index 829016249..9466928a1 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_generated_column_protocol.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_generated_column_protocol.py @@ -1,5 +1,5 @@ # tests/rhosocial/activerecord_test/feature/backend/dummy2/test_generated_columns.py -from rhosocial.activerecord.backend.expression import Column, Literal +from rhosocial.activerecord.backend.expression import BinaryExpression, Column, Literal from rhosocial.activerecord.backend.expression.statements import ( ColumnDefinition, ColumnConstraint, @@ -47,7 +47,12 @@ def test_to_sql_stored(self, dummy_dialect: DummyDialect): """Test GeneratedColumnExpression.to_sql() for STORED.""" gen = GeneratedColumnExpression( dummy_dialect, - expression=Column(dummy_dialect, "price") * Column(dummy_dialect, "qty"), + expression=BinaryExpression( + dummy_dialect, + "*", + Column(dummy_dialect, "price"), + Column(dummy_dialect, "qty"), + ), storage_type=GeneratedColumnType.STORED, ) sql, params = gen.to_sql() @@ -60,7 +65,7 @@ def test_to_sql_virtual(self, dummy_dialect: DummyDialect): """Test GeneratedColumnExpression.to_sql() for VIRTUAL.""" gen = GeneratedColumnExpression( dummy_dialect, - expression=Column(dummy_dialect, "a") + Column(dummy_dialect, "b"), + expression=BinaryExpression(dummy_dialect, "+", Column(dummy_dialect, "a"), Column(dummy_dialect, "b")), ) sql, params = gen.to_sql() assert "GENERATED ALWAYS AS" in sql @@ -93,9 +98,15 @@ def test_virtual_generated_column(self, dummy_dialect: DummyDialect): generated_expression=GeneratedColumnExpression( dummy_dialect, expression=( - Column(dummy_dialect, "first_name") - + Literal(dummy_dialect, " ", inline_literals=True) - + Column(dummy_dialect, "last_name") + BinaryExpression( + dummy_dialect, + "+", + BinaryExpression( + dummy_dialect, "+", Column(dummy_dialect, "first_name"), + Literal(dummy_dialect, " ", inline_literals=True), + ), + Column(dummy_dialect, "last_name"), + ) ), storage_type=GeneratedColumnType.VIRTUAL, ), @@ -121,7 +132,12 @@ def test_stored_generated_column(self, dummy_dialect: DummyDialect): DecimalType(dummy_dialect, precision=10, scale=2), generated_expression=GeneratedColumnExpression( dummy_dialect, - expression=Column(dummy_dialect, "price") * Column(dummy_dialect, "quantity"), + expression=BinaryExpression( + dummy_dialect, + "*", + Column(dummy_dialect, "price"), + Column(dummy_dialect, "quantity"), + ), storage_type=GeneratedColumnType.STORED, ), ), @@ -138,12 +154,22 @@ def test_stored_generated_column(self, dummy_dialect: DummyDialect): def test_generated_column_default_virtual(self, dummy_dialect: DummyDialect): """Test that generated column defaults to VIRTUAL when type not specified.""" columns = [ - ColumnDefinition(dummy_dialect, "id", IntegerType(dummy_dialect), constraints=[ColumnConstraint(dummy_dialect, ColumnConstraintType.PRIMARY_KEY)]), + ColumnDefinition( + dummy_dialect, + "id", + IntegerType(dummy_dialect), + constraints=[ColumnConstraint(dummy_dialect, ColumnConstraintType.PRIMARY_KEY)], + ), ColumnDefinition(dummy_dialect, "computed", IntegerType(dummy_dialect), generated_expression=GeneratedColumnExpression( dummy_dialect, - expression=Column(dummy_dialect, "id") + Literal(dummy_dialect, 1), + expression=BinaryExpression( + dummy_dialect, + "+", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 1), + ), ), ), ] @@ -168,7 +194,12 @@ def test_generated_column_with_not_null(self, dummy_dialect: DummyDialect): constraints=[ColumnConstraint(dummy_dialect, ColumnConstraintType.NOT_NULL)], generated_expression=GeneratedColumnExpression( dummy_dialect, - expression=Column(dummy_dialect, "id") * Literal(dummy_dialect, 2), + expression=BinaryExpression( + dummy_dialect, + "*", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 2), + ), storage_type=GeneratedColumnType.VIRTUAL, ), ), @@ -193,7 +224,12 @@ def test_arithmetic_expression(self, dummy_dialect: DummyDialect): IntegerType(dummy_dialect), generated_expression=GeneratedColumnExpression( dummy_dialect, - expression=Column(dummy_dialect, "a") + Column(dummy_dialect, "b"), + expression=BinaryExpression( + dummy_dialect, + "+", + Column(dummy_dialect, "a"), + Column(dummy_dialect, "b"), + ), storage_type=GeneratedColumnType.VIRTUAL, ), ), @@ -215,7 +251,17 @@ def test_string_concatenation(self, dummy_dialect: DummyDialect): VarCharType(dummy_dialect, 101), generated_expression=GeneratedColumnExpression( dummy_dialect, - expression=Column(dummy_dialect, "first") + Literal(dummy_dialect, " ") + Column(dummy_dialect, "last"), + expression=BinaryExpression( + dummy_dialect, + "+", + BinaryExpression( + dummy_dialect, + "+", + Column(dummy_dialect, "first"), + Literal(dummy_dialect, " "), + ), + Column(dummy_dialect, "last"), + ), storage_type=GeneratedColumnType.STORED, ), ), diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_interval_qualifier.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_interval_qualifier.py new file mode 100644 index 000000000..8ab0f64e3 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_interval_qualifier.py @@ -0,0 +1,235 @@ +# tests/rhosocial/activerecord_test/feature/backend/dummy2/test_interval_qualifier.py +"""``INTERVAL``'s qualifier is a closed vocabulary, not a free string. + +``IntervalType.fields`` reaches DDL: three dialects interpolate it straight into +``INTERVAL `` and one of them upper-cases it. A DDL position cannot take +a bound parameter, so an unchecked string there is an injection — and until this +was closed, ``IntervalType(dialect, fields="DAY TO SECOND); DROP TABLE t--")`` +rendered that text into a ``CREATE TABLE``. + +The replacement has one hard requirement: **every currently-rendering dialect +must produce byte-identical SQL.** Oracle, PostgreSQL and the dummy dialect all +interpolate the value directly, so the fix could not be an ``enum.Enum`` — that +would have rewritten their output to ``INTERVAL IntervalField.YEAR``. The value +is therefore an ``IntervalQualifier``, a validated ``str``, and these tests pin +both halves of that bargain: the rendered bytes stay the same, and an unknown +qualifier is now an error naming it. +""" + +import json + +import pytest + +from rhosocial.activerecord.backend.expression.types import ( + INTERVAL_QUALIFIERS, + InvalidIntervalQualifierError, + IntervalQualifier, + IntervalType, + is_valid_interval_qualifier, + validate_interval_qualifier, +) + + +def _dummy(): + from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect + + return DummyDialect() + + +def _sqlite(): + from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + return SQLiteDialect(version=(3, 45, 0)) + + +# --------------------------------------------------------------------------- +# The vocabulary +# --------------------------------------------------------------------------- + + +def test_the_vocabulary_is_the_thirteen_sql_qualifiers(): + """Closed means closed: the set is enumerated, and it is the standard's. + + Six single fields and seven contiguous ranges. Not a free string that happens + to look like one, and not the sixteen combinations a naive "field TO field" + grammar would accept — ``YEAR TO DAY`` is not a resolution any backend has. + """ + assert INTERVAL_QUALIFIERS == { + "YEAR", "MONTH", "DAY", "HOUR", "MINUTE", "SECOND", + "YEAR TO MONTH", + "DAY TO HOUR", "DAY TO MINUTE", "DAY TO SECOND", + "HOUR TO MINUTE", "HOUR TO SECOND", "MINUTE TO SECOND", + } + + +@pytest.mark.parametrize("qualifier", sorted(INTERVAL_QUALIFIERS)) +def test_every_member_of_the_vocabulary_is_accepted(qualifier): + assert is_valid_interval_qualifier(qualifier) + assert validate_interval_qualifier(qualifier) == qualifier + assert IntervalQualifier(qualifier) == qualifier + + +@pytest.mark.parametrize("qualifier", [ + # Not contiguous ranges — a resolution has to be a span, not a pair. + "YEAR TO DAY", + "MONTH TO YEAR", + "SECOND TO YEAR", + "DAY TO MONTH", + # A field the standard does not name for an interval. + "QUARTER", + "EPOCH", + # Injections and near-misses. The position takes no bound parameter, so + # this is the whole defence. + "DAY TO SECOND); DROP TABLE t--", + "DAY TO SECOND, HOUR", + "SECOND)", + "", + " ", + "YEAR TO", + "TO MONTH", + "DAY TO SECOND EXTRA", + 42, +]) +def test_an_unknown_qualifier_is_refused_and_named(qualifier): + """A refusal a caller can act on: it names the value and the accepted set.""" + with pytest.raises(InvalidIntervalQualifierError) as excinfo: + IntervalType(_dummy(), fields=qualifier) + message = str(excinfo.value) + assert repr(qualifier) in message or str(qualifier) in message + assert "DAY TO SECOND" in message, "the message must list what is accepted" + assert not is_valid_interval_qualifier(qualifier) + + +def test_no_qualifier_is_not_a_qualifier(): + """``None`` means "unqualified", which is a different thing from unknown. + + A bare ``IntervalType()`` is legal SQL on every backend and means the + backend's default resolution, so it must keep constructing; it just is not a + member of the vocabulary. + """ + dialect = _dummy() + assert IntervalType(dialect).fields is None + assert not is_valid_interval_qualifier(None) + + +def test_a_precision_is_part_of_the_vocabulary_not_a_way_past_it(): + """Oracle writes ``DAY(2) TO SECOND(6)`` and introspection reads it back. + + So the precision belongs to the grammar and to the accepted shapes, and a + precision cannot smuggle a different field past the shape check. + """ + for qualifier in ("SECOND(6)", "DAY(3)", "DAY(2) TO SECOND(6)", + "YEAR(3) TO MONTH(6)"): + assert is_valid_interval_qualifier(qualifier), qualifier + assert not is_valid_interval_qualifier("YEAR(3) TO DAY(9)") + assert not is_valid_interval_qualifier("SECOND(6) TO MINUTE") + assert not is_valid_interval_qualifier("DAY(x) TO SECOND(y)") + + +def test_a_refused_qualifier_leaves_no_type_behind(): + """The type is not half-built: the refusal happens before anything is set.""" + dialect = _dummy() + with pytest.raises(InvalidIntervalQualifierError): + IntervalType(dialect, fields="YEAR TO DAY") + assert IntervalType(dialect).fields is None + + +# --------------------------------------------------------------------------- +# Byte-identical rendering +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("fields,expected", [ + (None, "INTERVAL"), + ("YEAR", "INTERVAL YEAR"), + ("MONTH", "INTERVAL MONTH"), + ("YEAR TO MONTH", "INTERVAL YEAR TO MONTH"), + ("DAY TO SECOND", "INTERVAL DAY TO SECOND"), + ("HOUR TO SECOND", "INTERVAL HOUR TO SECOND"), + ("SECOND(6)", "INTERVAL SECOND(6)"), + ("DAY(2) TO SECOND(6)", "INTERVAL DAY(2) TO SECOND(6)"), +]) +def test_a_rendering_dialect_renders_the_same_bytes_it_did_before(fields, expected): + """The dummy dialect interpolates verbatim, exactly as it always has. + + This is the regression guard for the *design*, not for the vocabulary: if the + qualifier ever becomes an object whose ``str()`` is not the qualifier, this is + the test that says the backends' DDL moved. + """ + dialect = _dummy() + sql, params = dialect.format_data_type(IntervalType(dialect, fields=fields)) + assert (sql, params) == (expected, ()) + + +def test_a_dialect_with_no_interval_type_ignores_the_qualifier_as_before(): + """SQLite has no interval type and stores the span as a number. + + Its formatter returns ``NUMERIC`` and never reads ``fields``, which is the + honest answer — there is nowhere in an INTEGER-affinity column for a + resolution to live. The qualifier is validated on the way in and simply not + rendered. + """ + dialect = _sqlite() + for fields in (None, "YEAR TO MONTH", "DAY(2) TO SECOND(6)"): + assert dialect.format_data_type( + IntervalType(dialect, fields=fields) + ) == ("NUMERIC", ()) + + +# --------------------------------------------------------------------------- +# The value type is a ``str``, on purpose +# --------------------------------------------------------------------------- + + +def test_the_qualifier_is_a_string_so_no_rendering_moves(): + """Every use a backend could make of the value behaves as it did. + + Oracle upper-cases it, PostgreSQL and dummy interpolate it, the schema + snapshot serialises it to JSON, equality and hashing compare it, and ``repr`` + shows up in test failures. All five would have changed under an enum. + """ + qualifier = IntervalQualifier("YEAR TO MONTH") + assert isinstance(qualifier, str) + assert f"INTERVAL {qualifier}" == "INTERVAL YEAR TO MONTH" + assert qualifier.upper() == "YEAR TO MONTH" + assert qualifier == "YEAR TO MONTH" + assert hash(qualifier) == hash("YEAR TO MONTH") + assert repr(qualifier) == "'YEAR TO MONTH'" + assert json.dumps({"fields": qualifier}) == '{"fields": "YEAR TO MONTH"}' + + +def test_the_spelling_is_written_the_way_it_was_given(): + """No case normalisation: a backend that renders verbatim must not change. + + Oracle upper-cases, PostgreSQL and dummy do not. Normalising here would + silently rewrite what a caller wrote on two of them, which is a rendering + change dressed up as a tidy-up. + """ + dialect = _dummy() + assert dialect.format_data_type( + IntervalType(dialect, fields="year to month") + )[0] == "INTERVAL year to month" + + +def test_identity_and_serialisation_round_trip(): + """``fields`` is part of identity and of the constructor round trip. + + Two intervals of different resolution are different types, and a snapshot + taken with one has to come back as one. + """ + from rhosocial.activerecord.backend.schema.snapshot import ( + _data_type_from_dict, + _data_type_to_dict, + ) + + year = IntervalType(_dummy(), fields="YEAR TO MONTH") + day = IntervalType(_dummy(), fields="DAY TO SECOND") + assert year == IntervalType(_dummy(), fields="YEAR TO MONTH") + assert year != day + assert year.identity() == ("YEAR TO MONTH",) + assert year.get_params()["fields"] == "YEAR TO MONTH" + + restored = _data_type_from_dict(_data_type_to_dict(year)) + assert type(restored) is IntervalType + assert restored == year + assert json.loads(json.dumps(_data_type_to_dict(year))) == _data_type_to_dict(year) \ No newline at end of file diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_json_probe_honesty.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_json_probe_honesty.py new file mode 100644 index 000000000..e7cfc5a19 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_json_probe_honesty.py @@ -0,0 +1,127 @@ +# tests/rhosocial/activerecord_test/feature/backend/dummy2/test_json_probe_honesty.py +"""A dialect that declares no JSON support must not be handed JSON SQL. + +``format_json_expression`` documents that it raises when the dialect declares +no JSON support, and did not: rendering went straight to the function-based +fallback, which is MySQL's shape. So a dialect whose probe answered False — +Oracle, Snowflake, BigQuery, Firebird — still answered a JSON path with +``JSON_EXTRACT``, a function its server does not have. + +The error is worse than a wrong answer would be, because the SQL is +syntactically plausible and only the server rejects it. The probe is what +makes the situation knowable in advance, so it has to be believed. + +The other half is that believing it must not cost the backends that do have +JSON: the probe and the formatter have to agree in both directions. +""" + +# tests/rhosocial/activerecord_test/feature/backend/dummy2/test_json_probe_honesty.py +import pytest + +from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError +from rhosocial.activerecord.backend.expression import Column +from rhosocial.activerecord.backend.expression.advanced_functions import JSONDocumentExpression + + +def _sqlite(): + from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + dialect = SQLiteDialect() + dialect._version = (3, 46, 1) + return dialect + + +@pytest.fixture +def dialect(): + return _sqlite() + + +@pytest.fixture +def no_json_dialect(dialect): + """A dialect whose server can read no JSON path, from the real SQLite one. + + The gate is supports_json_path, so that is what has to be turned off. It + used to be supports_json_type, which was wrong: MySQL 5.7.0 reads a path + through JSON_EXTRACT and has no native JSON type until 5.7.8, so gating on + the type refused queries the server answers. + """ + dialect.supports_json_path = lambda: False + return dialect + + +def _expr(dialect, operation="->>", mode="function"): + return JSONDocumentExpression(dialect, Column(dialect, "j", table="t"), "$.a", operation, mode=mode) + + +# --------------------------------------------------------------------------- +# The probe is believed +# --------------------------------------------------------------------------- + + +def test_a_dialect_without_json_refuses_a_path(no_json_dialect): + with pytest.raises(UnsupportedFeatureError): + _expr(no_json_dialect).to_sql() + + +def test_the_refusal_says_what_to_do(no_json_dialect): + """An error the caller cannot act on is only marginally better than bad SQL.""" + with pytest.raises(UnsupportedFeatureError) as excinfo: + _expr(no_json_dialect).to_sql() + message = str(excinfo.value) + assert "json" in message.lower(), message + + +def test_arrow_mode_is_refused_too(no_json_dialect): + """AUTO falls back to the function path, so both routes need the check.""" + with pytest.raises(UnsupportedFeatureError): + _expr(no_json_dialect, "->", "arrow").to_sql() + + +def test_auto_mode_is_refused_too(no_json_dialect): + """AUTO is the default, so the common case is the one that must refuse.""" + with pytest.raises(UnsupportedFeatureError): + _expr(no_json_dialect, "->", "auto").to_sql() + + +# --------------------------------------------------------------------------- +# Declaring JSON means being able to render it +# --------------------------------------------------------------------------- + + +def test_sqlite_declares_json_and_renders_it(dialect): + assert dialect.supports_json_type() is True + sql, _ = _expr(dialect).to_sql() + assert "json_extract" in sql.lower(), sql + + +@pytest.mark.parametrize("mode", ["function", "arrow", "auto"]) +def test_every_mode_renders_on_a_dialect_that_has_json(dialect, mode): + """Believing the probe must not cost the backends that do have JSON.""" + assert dialect.supports_json_arrow_operators(), "SQLite has arrow operators" + sql, _ = _expr(dialect, "->", mode).to_sql() + assert sql, f"mode={mode} rendered nothing" + + +def test_a_path_capable_dialect_can_have_no_json_type(dialect): + """The two probes answer different questions and must be able to disagree. + + MySQL between 5.7.0 and 5.7.8 is exactly this: JSON_EXTRACT reads a path, + and there is no JSON column type to store the document in. + """ + dialect.supports_json_type = lambda: False + sql, _ = _expr(dialect).to_sql() + assert "json_extract" in sql.lower(), sql + + +def test_the_probe_is_not_consulted_twice(no_json_dialect): + """A dialect that answers the probe is enough; the renderer is never asked.""" + calls = [] + + def probe(): + calls.append(1) + return False + + no_json_dialect.supports_json_path = probe + with pytest.raises(UnsupportedFeatureError): + _expr(no_json_dialect).to_sql() + assert calls, "the probe was never consulted" diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_new_data_types.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_new_data_types.py index 14e99e737..da71d606b 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_new_data_types.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_new_data_types.py @@ -124,8 +124,10 @@ def test_new_names_in_supported_mapping(self): assert supported["binary"] is BinaryType assert supported["varbinary"] is VarBinaryType - def test_new_names_support_checks(self): + def test_new_names_are_declared_by_their_formatters(self): dialect = _dummy_dialect() - assert dialect.supports_data_type_enum() is True - assert dialect.supports_data_type_binary() is True - assert dialect.supports_data_type_varbinary() is True + # The formatter *is* the support declaration; the retired + # supports_data_type_* probe family has no core member left. + for name in ("enum", "binary", "varbinary"): + assert hasattr(dialect, f"format_data_type_{name}") + assert not hasattr(dialect, f"supports_data_type_{name}") diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_operators.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_operators.py index bdb3b7c90..373966cc3 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_operators.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_operators.py @@ -1,5 +1,5 @@ # tests/rhosocial/activerecord_test/feature/backend/dummy2/test_operators.py -from rhosocial.activerecord.backend.expression import Column, Literal, FunctionCall +from rhosocial.activerecord.backend.expression import Column, Literal, FunctionCall, NumericColumn from rhosocial.activerecord.backend.expression.operators import ( SQLOperation, BinaryExpression, @@ -167,7 +167,7 @@ class TestBinaryArithmeticExpression: def test_binary_arithmetic_expression_basic(self, dummy_dialect: DummyDialect): """Test basic binary arithmetic expression.""" - left = Column(dummy_dialect, "price") + left = NumericColumn(dummy_dialect, "price") right = Literal(dummy_dialect, 1.1) # Use operator overloading instead of direct instantiation @@ -193,8 +193,8 @@ def test_binary_arithmetic_expression_with_functions(self, dummy_dialect: DummyD def test_binary_arithmetic_different_operators(self, dummy_dialect: DummyDialect): """Test binary arithmetic with different operators.""" - left = Column(dummy_dialect, "quantity") - right = Column(dummy_dialect, "unit_price") + left = NumericColumn(dummy_dialect, "quantity") + right = NumericColumn(dummy_dialect, "unit_price") # Test using operator overloading add_expr = left + right @@ -229,8 +229,8 @@ class TestBinaryArithmeticExpressionPrecedence: def test_multiplication_precedence_over_addition(self, dummy_dialect: DummyDialect): """Test that multiplication has higher precedence than addition.""" # Expression: (a + b) * c should generate ("a + b") * c - left_add = Column(dummy_dialect, "a") + Column(dummy_dialect, "b") - right = Column(dummy_dialect, "c") + left_add = NumericColumn(dummy_dialect, "a") + NumericColumn(dummy_dialect, "b") + right = NumericColumn(dummy_dialect, "c") expr = left_add * right sql, params = expr.to_sql() @@ -242,8 +242,8 @@ def test_multiplication_precedence_over_addition(self, dummy_dialect: DummyDiale def test_addition_precedence_lower_than_multiplication(self, dummy_dialect: DummyDialect): """Test that addition has lower precedence than multiplication.""" # Expression: a + (b * c) should generate "a + b * c" (no parentheses needed for multiplication) - left = Column(dummy_dialect, "a") - right_mult = Column(dummy_dialect, "b") * Column(dummy_dialect, "c") + left = NumericColumn(dummy_dialect, "a") + right_mult = NumericColumn(dummy_dialect, "b") * NumericColumn(dummy_dialect, "c") expr = left + right_mult sql, params = expr.to_sql() @@ -255,8 +255,8 @@ def test_addition_precedence_lower_than_multiplication(self, dummy_dialect: Dumm def test_multiplication_precedence_over_subtraction(self, dummy_dialect: DummyDialect): """Test that multiplication has higher precedence than subtraction.""" # Expression: (a - b) * c should generate ("a - b") * c - left_sub = Column(dummy_dialect, "a") - Column(dummy_dialect, "b") - right = Column(dummy_dialect, "c") + left_sub = NumericColumn(dummy_dialect, "a") - NumericColumn(dummy_dialect, "b") + right = NumericColumn(dummy_dialect, "c") expr = left_sub * right sql, params = expr.to_sql() @@ -268,8 +268,8 @@ def test_multiplication_precedence_over_subtraction(self, dummy_dialect: DummyDi def test_division_precedence_over_addition(self, dummy_dialect: DummyDialect): """Test that division has higher precedence than addition.""" # Expression: (a + b) / c should generate ("a + b") / c - left_add = Column(dummy_dialect, "a") + Column(dummy_dialect, "b") - right = Column(dummy_dialect, "c") + left_add = NumericColumn(dummy_dialect, "a") + NumericColumn(dummy_dialect, "b") + right = NumericColumn(dummy_dialect, "c") expr = left_add / right sql, params = expr.to_sql() @@ -281,8 +281,8 @@ def test_division_precedence_over_addition(self, dummy_dialect: DummyDialect): def test_same_precedence_left_associative(self, dummy_dialect: DummyDialect): """Test that operators with same precedence are left-associative.""" # Expression: (a * b) / c should generate "a * b / c" (no parentheses needed for left-associative) - left_mult = Column(dummy_dialect, "a") * Column(dummy_dialect, "b") - right = Column(dummy_dialect, "c") + left_mult = NumericColumn(dummy_dialect, "a") * NumericColumn(dummy_dialect, "b") + right = NumericColumn(dummy_dialect, "c") expr = left_mult / right sql, params = expr.to_sql() @@ -294,8 +294,8 @@ def test_same_precedence_left_associative(self, dummy_dialect: DummyDialect): def test_addition_subtraction_same_precedence(self, dummy_dialect: DummyDialect): """Test that addition and subtraction have same precedence.""" # Expression: (a - b) + c should generate "a - b + c" (no parentheses needed for left-associative) - left_sub = Column(dummy_dialect, "a") - Column(dummy_dialect, "b") - right = Column(dummy_dialect, "c") + left_sub = NumericColumn(dummy_dialect, "a") - NumericColumn(dummy_dialect, "b") + right = NumericColumn(dummy_dialect, "c") expr = left_sub + right sql, params = expr.to_sql() @@ -308,8 +308,8 @@ def test_right_operand_needs_parens_case(self, dummy_dialect: DummyDialect): """Test the right operand needs parentheses case.""" # More specifically test right_needs_parens: when right operand has lower precedence than current operator # Example: a * (b + c) where addition has lower precedence than multiplication - left = Column(dummy_dialect, "a") - right_add = Column(dummy_dialect, "b") + Column(dummy_dialect, "c") + left = NumericColumn(dummy_dialect, "a") + right_add = NumericColumn(dummy_dialect, "b") + NumericColumn(dummy_dialect, "c") expr = left * right_add sql, params = expr.to_sql() @@ -322,8 +322,8 @@ def test_right_operand_higher_precedence_than_current(self, dummy_dialect: Dummy """Test when right operand has higher precedence than current operator.""" # Expression: a + (b * c) where multiplication has higher precedence than addition # In this case, the right operand (b * c) should NOT need parentheses since it has higher precedence - left = Column(dummy_dialect, "a") - right_mult = Column(dummy_dialect, "b") * Column(dummy_dialect, "c") + left = NumericColumn(dummy_dialect, "a") + right_mult = NumericColumn(dummy_dialect, "b") * NumericColumn(dummy_dialect, "c") expr = left + right_mult sql, params = expr.to_sql() diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_paradigm_invariants.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_paradigm_invariants.py new file mode 100644 index 000000000..4aec51885 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_paradigm_invariants.py @@ -0,0 +1,471 @@ +# src/rhosocial/activerecord_test/feature/backend/dummy2/test_paradigm_invariants.py +"""The type hierarchy's invariants, as executable checks. + +Most of these rules have no natural home in a single backend's suite: they are +statements about the *whole* family — core plus every dialect — and a class in +one backend can violate one just as easily as a class in core. So they live +here, parameterised over the dialects. + +The rule that got its own file first is :func:`test_declared_fields_are_honoured_or_refused`. +A field named in a type's ``PARAMETERS`` is part of that type's identity: two +declarations differing only in it are *different columns* and the differ reports +them as such. A formatter that ignores the field therefore produces two +*byte-identical* DDL statements for two different declarations, and nothing +downstream can detect it — the caller gets a column that is not the one they +declared and the call reports success. Nineteen such sites accumulated before +this check existed. There are exactly three honest answers, and only three: + +* **honour** it — flipping the field changes the SQL; +* **refuse** it — flipping raises, naming the field and why this backend cannot; +* **the field does not belong to this concept** — then it must not be in + ``PARAMETERS`` at all. + +"Silently drop it" is the one thing that is never acceptable. +""" + +import importlib +import inspect +import re + +import pytest + +from rhosocial.activerecord.backend.expression.types import DataType + +_DIALECTS = ( + ("dummy", "DummyDialect"), + ("sqlite", "SQLiteDialect"), +) + + +def _load(backend, class_name): + #: Only the two dialects this repository owns are enumerated here. The nine + #: other backends are their own distributions with their own suites: a + #: project tests its own code, and importing a sibling from this one would + #: both test someone else's project and fill the process-wide expression + #: registry with classes this suite has no allowlist for -- which is how + #: ``test_all_builtin_expressions`` used to fail on a developer machine with + #: all nine installed and pass in this repository's CI with none of them. + #: A backend listed here but missing is a broken checkout, not a skip. + module = importlib.import_module( + f"rhosocial.activerecord.backend.impl.{backend}.dialect") + cls = getattr(module, class_name, None) + assert cls is not None, f"{class_name} missing from {module.__name__}" + for kwargs in ({}, {"version": (23, 0, 0)}, {"version": (16, 0, 0)}): + try: + return cls(**kwargs) + except TypeError: + continue + raise AssertionError(f"{class_name} could not be constructed") + + +def _dialects(): + """One ``pytest.param`` per available dialect. + + Each is wrapped in a single-value ``pytest.param`` purely for the id. + pytest unwraps a one-value ParameterSet, so a test parameterised on this + receives the dialect object itself. + """ + out = [] + for backend, class_name in _DIALECTS: + try: + out.append(pytest.param(_load(backend, class_name), id=backend)) + except pytest.skip.Exception: + continue + return out + + +def _all_concepts(): + """Every concrete ``DataType`` subclass reachable from the base.""" + seen, stack, found = set(), [DataType], [] + while stack: + klass = stack.pop() + if klass in seen: + continue + seen.add(klass) + stack.extend(klass.__subclasses__()) + if klass is not DataType and not inspect.isabstract(klass): + found.append(klass) + return found + + +def _backend_of(klass): + match = re.search(r"backend\.impl\.([a-z0-9_]+)", klass.__module__) + return match.group(1) if match else "core" + + +def _other_values(value): + """Plausible values different from *value*, for a field currently *value*.""" + if isinstance(value, bool): + return [not value] + if isinstance(value, int): + return [value + 1, value + 2, value - 1] + if isinstance(value, str): + return [value + "_other", value + "x"] + if isinstance(value, (tuple, list)): + return [(tuple(value) + ("__probe__",))] + return [] + + +def _rendered_with(cls, field, new_value, dialect): + """Render *cls* with *field* set to *new_value*. + + Returns ``None`` when the class will not accept the value at all — the + backend has pinned the field, which is an honest answer on its own and is + reported separately rather than counted as a violation. + """ + signature = inspect.signature(cls.__init__) + if field not in signature.parameters: + return None + kwargs = {} + for parameter in signature.parameters.values(): + if parameter.name in ("self", "dialect"): + continue + if parameter.kind in (parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD): + continue + if parameter.default is not inspect.Parameter.empty: + kwargs[parameter.name] = parameter.default + elif parameter.kind is parameter.KEYWORD_ONLY: + continue # cannot guess this + else: + kwargs[parameter.name] = None + kwargs[field] = new_value + try: + return cls(dialect, **kwargs).to_sql()[0] + except Exception: # noqa: BLE001 + return "" + + +def _rendering_dialect(cls, name): + """The first dialect that renders this type, or ``None`` if none does.""" + for param in _dialects(): + dialect = param.values[0] + if hasattr(dialect, "format_data_type_" + str(name)): + return dialect + return None + + +# -------------------------------------------------------------------------- +# The rule that matters most +# -------------------------------------------------------------------------- + +@pytest.mark.parametrize("dialect_param", _dialects()) +def test_declared_fields_are_honoured_or_refused(dialect_param): + """No formatter may silently discard a field its type declares as identity. + + For every concrete type with a non-empty ``PARAMETERS`` that some dialect + renders: build it, then build it again with each identity field changed. + If the rendered SQL is unchanged for every attempt, the field is being + dropped — two different declarations produce two byte-identical statements + and nothing downstream can notice. + """ + dialect = dialect_param + checked = 0 + dropped = [] + pinned = [] + + for cls in _all_concepts(): + if not cls.PARAMETERS: + continue + if not hasattr(dialect, "format_data_type_" + str(cls.name)): + continue + try: + base_sql = cls(dialect).to_sql()[0] + instance = cls(dialect) + except Exception: # noqa: BLE001 + continue + + for field in cls.PARAMETERS: + alternatives = _other_values(getattr(instance, field, None)) + if not alternatives: + continue + attempts = [ + _rendered_with(cls, field, value, dialect) + for value in alternatives + ] + attempts = [a for a in attempts if a is not None] + if not attempts: + pinned.append(f"{cls.__name__}.{field}") + continue + if all(sql == base_sql for sql in attempts): + dropped.append(f"{cls.__name__}.{field} renders {base_sql!r} either way") + checked += 1 + + assert not dropped, ( + "these declared identity fields do not affect the rendered SQL, so " + "they are being silently discarded — a caller asking for a column " + "that is not the one they declared gets it, and is told it worked:\n" + + "\n".join(" " + line for line in dropped) + + f"\n\n(pinned at construction, so honest: {pinned})" + ) + # Nothing is asserted about ``checked`` beyond it being non-trivial on at + # least one dialect; the guarantee is the absence of violations. + assert isinstance(checked, int) + + +# -------------------------------------------------------------------------- +# Shape of the hierarchy +# -------------------------------------------------------------------------- + +def test_identity_is_linear_single_inheritance(): + """Inheritance expresses identity, so a concept has exactly one base. + + Multiple inheritance would let a class claim two identities at once, and a + diamond would mean two paths to the same concept — both make "is this the + same type" ambiguous. The root is exempt: it inherits from the expression + base and ``ABC``, which is not a claim about any type concept. + """ + offenders = [ + f"{k.__module__}.{k.__name__} -> {[b.__name__ for b in k.__bases__]}" + for k in _all_concepts() + if len(k.__bases__) != 1 + ] + assert not offenders, ( + "a type concept must have exactly one base class:\n" + + "\n".join(" " + line for line in offenders) + ) + + +def test_no_diamond_edges_between_concepts(): + """No concept may be reachable from another by two different paths.""" + + def concept_ancestors(node): + counts = {} + + def walk(current): + for base in current.__bases__: + if issubclass(base, DataType) and base is not DataType: + counts[base] = counts.get(base, 0) + 1 + walk(base) + + walk(node) + return counts + + offenders = [] + seen, stack = set(), [DataType] + while stack: + klass = stack.pop() + if klass in seen: + continue + seen.add(klass) + stack.extend(klass.__subclasses__()) + for ancestor, count in concept_ancestors(klass).items(): + if count > 1: + offenders.append( + f"{klass.__name__} reaches {ancestor.__name__} by {count} paths") + assert not offenders, "diamond edges:\n" + "\n".join( + " " + line for line in offenders) + + +def test_no_grouping_nodes_or_orphans(): + """Every concrete concept is either rendered by a dialect or named as its + substitute. + + A class that no dialect renders and no dialect suggests is a grouping node + or dead code. Both are forbidden: grouping nodes put "these are similar" + into the type tree, where only identity is allowed, and a class nothing can + reach is a promise nothing keeps. + """ + rendered, suggested = set(), set() + for param in _dialects(): + dialect = param.values[0] + rendered |= {m[len("format_data_type_"):] for m in dir(type(dialect)) + if m.startswith("format_data_type_")} + try: + suggested |= set(dialect.suggested_data_types() or {}) + except Exception: # noqa: BLE001 + pass + + orphans = [f"{_backend_of(k)}/{k.__name__}(name={k.name!r})" + for k in _all_concepts() + if k.name and k.name not in rendered and k.name not in suggested] + assert not orphans, ( + "these concepts are neither rendered nor suggested by any dialect — " + "grouping nodes and dead classes are both forbidden:\n" + + "\n".join(" " + line for line in orphans)) + + +# -------------------------------------------------------------------------- +# Identity +# -------------------------------------------------------------------------- + +def test_identity_fields_are_plain_attributes(): + """``PARAMETERS`` names attributes, never computed or transformed values. + + A computed entry cannot be compared as-is, so a class with one is either + comparing something other than what it declared or quietly normalising a + value it forgot to normalise when it was stored. + """ + offenders = [f"{_backend_of(k)}/{k.__name__}: {f!r}" + for k in _all_concepts() + for f in k.PARAMETERS + if not re.fullmatch(r"[A-Za-z_]\w*", f)] + assert not offenders, "non-attribute entries in PARAMETERS:\n" + "\n".join( + " " + line for line in offenders) + + +def test_a_declared_field_exists_on_the_class(): + """Every declared field must be readable on an instance. + + ``identity()`` reads these with ``getattr``, so a name that no longer exists + turns ``==`` and ``hash`` into an ``AttributeError`` at the worst possible + moment. + """ + offenders = [] + for cls in _all_concepts(): + for field in cls.PARAMETERS: + if not hasattr(cls, field): + try: + instance = cls() + except Exception: # noqa: BLE001 + continue + if not hasattr(instance, field): + offenders.append(f"{cls.__name__}.{field}") + assert not offenders, ( + "declared identity fields that no instance carries:\n" + + "\n".join(" " + line for line in offenders)) + + +def test_spelling_is_not_part_of_identity(): + """A spelling is how the value is written, not what it is. + + The schema differ compares what the database reports *now* against what was + declared, and a database reports its own house spelling no matter which + word was typed: PostgreSQL reports ``character varying(30)`` for every + ``varchar(30)`` column that exists. Counting the spelling would therefore + report a change on every such column that was never touched — a false + positive on the one comparison that has to be right. + + It still reaches the rendered SQL, and still round-trips through + ``get_params()``, because serialization asks a different question. + """ + from rhosocial.activerecord.backend.expression.types import IntegerType + + offenders = [f"{_backend_of(k)}/{k.__name__}" + for k in _all_concepts() if "spelling" in k.PARAMETERS] + assert not offenders, ( + "spelling must not be part of identity:\n" + + "\n".join(" " + line for line in offenders)) + + plain, other = IntegerType(), IntegerType(spelling="int") + assert plain == other + assert hash(plain) == hash(other) + # ... and it is not lost: it reaches the SQL and the serialization path. + assert other.get_params().get("spelling") == "int" + + +# -------------------------------------------------------------------------- +# Names are dispatch keys +# -------------------------------------------------------------------------- + +def test_dispatch_keys_are_globally_unique(): + """Two concepts sharing a ``name`` makes dispatch ambiguous.""" + by_name = {} + for klass in _all_concepts(): + if klass.name: + by_name.setdefault(klass.name, []).append(klass) + clashes = {n: v for n, v in by_name.items() if len(v) > 1} + assert not clashes, "duplicate dispatch keys: " + "; ".join( + f"{n} -> {[k.__name__ for k in v]}" for n, v in clashes.items()) + + +@pytest.mark.parametrize("dialect_param", _dialects()) +def test_rendered_and_suggested_keys_are_disjoint(dialect_param): + """One dialect must not both render a concept and substitute for it. + + If it did, the substitute could never be reached and the renderer would be + rendering something the dialect has also declared unsupported. + """ + dialect = dialect_param + rendered = {m[len("format_data_type_"):] for m in dir(type(dialect)) + if m.startswith("format_data_type_")} + try: + suggested = set(dialect.suggested_data_types() or {}) + except Exception: # noqa: BLE001 + suggested = set() + both = rendered & suggested + assert not both, ( + f"{_backend_of(type(dialect))} both renders and substitutes: " + f"{sorted(both)}" + ) + + +# -------------------------------------------------------------------------- +# The removed mechanisms stay removed +# -------------------------------------------------------------------------- + +def test_removed_comparison_mechanisms_stay_removed(): + """``==`` is the whole comparison; the older pair of escape hatches is gone. + + ``is_equivalent()`` and ``synonyms()`` existed to paper over synonym + *classes*. Synonyms are now spellings on one class, so there is no second + class for a looser comparison to disagree with. + """ + assert not hasattr(DataType, "is_equivalent"), ( + "is_equivalent() is removed: == is the whole comparison") + assert not hasattr(DataType, "synonyms"), ( + "synonyms() is removed: a synonym is a spelling on the concept's class") + for klass in _all_concepts(): + assert not hasattr(klass, "is_equivalent"), f"{klass.__name__}" + assert not hasattr(klass, "synonyms"), f"{klass.__name__}" + + +# -------------------------------------------------------------------------- +# One way to say "this backend cannot express that" +# -------------------------------------------------------------------------- + +def test_refusals_are_one_exception_type_across_backends(): + """A caller must be able to catch a refusal the same way on every backend. + + ``UnsupportedFeatureError`` does **not** subclass ``ValueError``, so the two + are not interchangeable to a caller writing ``except ValueError``. The rule + the backends follow, and this test exists to hold it to: + + * the declared value is **wrong** -- out of the range this server accepts -- + raises ``ValueError``; + * the declaration is one this grammar **cannot express at all** -- there is + no unsigned integer, or the scale argument has nowhere to go -- raises + ``UnsupportedFeatureError``, which carries the dialect name and a route + forward. + + The second is not "a ValueError that happens to be worded differently": it + is the only one of the two that can tell a caller what to do instead. + """ + from rhosocial.activerecord.backend.dialect.exceptions import ( + UnsupportedFeatureError, + ) + + assert not issubclass(UnsupportedFeatureError, ValueError), ( + "if UnsupportedFeatureError ever becomes a ValueError, this test and " + "every caller's except-clause need revisiting together -- do not change " + "one silently" + ) + + # Every dialect that can be loaded must agree on which exception means + # "this backend cannot express that". Spot-check the one refusal every + # integer concept has an answer for on every backend: the signedness gate. + from rhosocial.activerecord.backend.expression.types import IntegerType + + checked, refused = 0, 0 + for param in _dialects(): + dialect = param.values[0] + if not hasattr(dialect, "format_data_type_integer"): + continue + checked += 1 + try: + dialect.format_data_type(IntegerType(dialect, unsigned=True)) + except UnsupportedFeatureError: + refused += 1 + except ValueError as exc: + pytest.fail( + f"{_backend_of(type(dialect))} refuses an unsigned integer with " + f"ValueError; every other backend raises " + f"UnsupportedFeatureError for the same refusal, and the two do " + f"not share a base class: {exc}" + ) + except Exception: # noqa: BLE001 + pass # honoured it: also correct + assert checked, "no dialect was available to check" + assert refused >= 1, ( + "no backend refuses unsigned integers at all -- the check above would " + "pass vacuously" + ) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_query_parts.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_query_parts.py index ceeae7d07..4d7b8698a 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_query_parts.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_query_parts.py @@ -23,7 +23,12 @@ class TestQueryParts: def test_where_clause_basic(self, dummy_dialect: DummyDialect): """Test basic WHERE clause generation.""" - condition = Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + condition = ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) where_clause = WhereClause(dummy_dialect, condition=condition) sql, params = where_clause.to_sql() @@ -33,8 +38,10 @@ def test_where_clause_basic(self, dummy_dialect: DummyDialect): def test_where_clause_complex_condition(self, dummy_dialect: DummyDialect): """Test WHERE clause with complex conditions.""" - condition = (Column(dummy_dialect, "age") > Literal(dummy_dialect, 18)) & ( - Column(dummy_dialect, "status") == Literal(dummy_dialect, "verified") + condition = ( + ComparisonPredicate(dummy_dialect, ">", Column(dummy_dialect, "age"), Literal(dummy_dialect, 18)) + ) & ( + ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "verified")) ) where_clause = WhereClause(dummy_dialect, condition=condition) @@ -56,7 +63,12 @@ def test_comparison_predicate_with_query_expression(self, dummy_dialect: DummyDi select=[Column(dummy_dialect, "id")], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "other_table")), where=WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) ), ) @@ -400,7 +412,7 @@ def test_clause_types_generate_expected_fragments( ): """Test that various clause types generate expected SQL fragments.""" if clause_type == WhereClause: - condition = Column(dummy_dialect, "id") > Literal(dummy_dialect, 0) + condition = ComparisonPredicate(dummy_dialect, ">", Column(dummy_dialect, "id"), Literal(dummy_dialect, 0)) clause = WhereClause(dummy_dialect, condition=condition) sql, params = clause.to_sql() assert expected_sql_fragment in sql @@ -427,8 +439,6 @@ def test_where_clause_with_function_condition(self, dummy_dialect: DummyDialect) def test_where_clause_with_like_condition(self, dummy_dialect: DummyDialect): """Test WHERE clause with LIKE condition.""" - condition = Column(dummy_dialect, "name").like(Literal(dummy_dialect, "John%")) # Assuming like method exists - # Since LIKE might not be available directly on Column in this implementation: from rhosocial.activerecord.backend.expression.predicates import LikePredicate condition = LikePredicate(dummy_dialect, "LIKE", Column(dummy_dialect, "name"), Literal(dummy_dialect, "John%")) @@ -491,7 +501,7 @@ def test_order_by_with_complex_expressions(self, dummy_dialect: DummyDialect): ), ( ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "standard") + dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "standard"), ), Literal(dummy_dialect, 2), ), @@ -514,7 +524,12 @@ def test_multiple_query_parts_integration(self, dummy_dialect: DummyDialect): """Test integration of multiple query parts in a single context.""" # This simulates how these clauses might be used together in a query where_clause = WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) ) group_by_having = GroupByHavingClause( @@ -580,10 +595,10 @@ def test_limit_offset_clause_edge_cases(self, dummy_dialect: DummyDialect): def test_where_clause_complex_logical_conditions(self, dummy_dialect: DummyDialect): """Test WHERE clause with complex logical conditions.""" condition = ( - (Column(dummy_dialect, "status") == Literal(dummy_dialect, "active")) - & (Column(dummy_dialect, "age") >= Literal(dummy_dialect, 18)) - & (Column(dummy_dialect, "balance") > Literal(dummy_dialect, 0)) - ) | (Column(dummy_dialect, "is_vip") == Literal(dummy_dialect, True)) + (ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "active"))) + & (ComparisonPredicate(dummy_dialect, ">=", Column(dummy_dialect, "age"), Literal(dummy_dialect, 18))) + & (ComparisonPredicate(dummy_dialect, ">", Column(dummy_dialect, "balance"), Literal(dummy_dialect, 0))) + ) | (ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "is_vip"), Literal(dummy_dialect, True))) where_clause = WhereClause(dummy_dialect, condition=condition) sql, params = where_clause.to_sql() @@ -596,7 +611,12 @@ def test_where_clause_complex_logical_conditions(self, dummy_dialect: DummyDiale def test_all_query_parts_return_proper_types(self, dummy_dialect: DummyDialect): """Test that all query parts return proper SQL and parameter types.""" # Test each clause type - where_clause = WhereClause(dummy_dialect, condition=Column(dummy_dialect, "id") > Literal(dummy_dialect, 0)) + where_clause = WhereClause(dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + ">", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 0)) + ) sql, params = where_clause.to_sql() assert isinstance(sql, str) assert isinstance(params, tuple) @@ -617,7 +637,12 @@ def test_all_query_parts_return_proper_types(self, dummy_dialect: DummyDialect): assert isinstance(params, tuple) qualify_clause = QualifyClause( - dummy_dialect, condition=Column(dummy_dialect, "value") > Literal(dummy_dialect, 10) + dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + ">", + Column(dummy_dialect, "value"), + Literal(dummy_dialect, 10) + ) ) sql, params = qualify_clause.to_sql() assert isinstance(sql, str) @@ -631,11 +656,21 @@ def test_all_query_parts_return_proper_types(self, dummy_dialect: DummyDialect): def test_where_clause_and_method_basic(self, dummy_dialect: DummyDialect): """Test the and_() method of WhereClause for adding AND conditions.""" # Create initial condition - initial_condition = Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + initial_condition = ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) where_clause = WhereClause(dummy_dialect, condition=initial_condition) # Add another condition using and_() - additional_condition = Column(dummy_dialect, "age") >= Literal(dummy_dialect, 18) + additional_condition = ComparisonPredicate( + dummy_dialect, + ">=", + Column(dummy_dialect, "age"), + Literal(dummy_dialect, 18) + ) result = where_clause.and_(additional_condition) # Verify that the method returns self @@ -651,13 +686,33 @@ def test_where_clause_and_method_basic(self, dummy_dialect: DummyDialect): def test_where_clause_and_method_chaining(self, dummy_dialect: DummyDialect): """Test chaining multiple and_() calls.""" # Create initial condition - initial_condition = Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + initial_condition = ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) where_clause = WhereClause(dummy_dialect, condition=initial_condition) # Chain multiple and_() calls - where_clause.and_(Column(dummy_dialect, "age") >= Literal(dummy_dialect, 18)) - where_clause.and_(Column(dummy_dialect, "balance") > Literal(dummy_dialect, 0)) - where_clause.and_(Column(dummy_dialect, "verified") == Literal(dummy_dialect, True)) + where_clause.and_(ComparisonPredicate( + dummy_dialect, + ">=", + Column(dummy_dialect, "age"), + Literal(dummy_dialect, 18)) + ) + where_clause.and_(ComparisonPredicate( + dummy_dialect, + ">", + Column(dummy_dialect, "balance"), + Literal(dummy_dialect, 0)) + ) + where_clause.and_(ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "verified"), + Literal(dummy_dialect, True)) + ) # Verify all conditions are present sql, params = where_clause.to_sql() @@ -671,8 +726,12 @@ def test_where_clause_and_method_chaining(self, dummy_dialect: DummyDialect): def test_where_clause_and_method_complex_conditions(self, dummy_dialect: DummyDialect): """Test and_() method with complex conditions.""" # Create initial complex condition - initial_condition = (Column(dummy_dialect, "status") == Literal(dummy_dialect, "active")) & ( - Column(dummy_dialect, "type") != Literal(dummy_dialect, "deleted") + initial_condition = ( + ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "active")) + ) & ( + ComparisonPredicate( + dummy_dialect, "!=", Column(dummy_dialect, "type"), Literal(dummy_dialect, "deleted") + ) ) where_clause = WhereClause(dummy_dialect, condition=initial_condition) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_query_parts_join.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_query_parts_join.py index e86abb1f4..b0be118e6 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_query_parts_join.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_query_parts_join.py @@ -30,7 +30,7 @@ def test_basic_join_expression_creation(self, dummy_dialect: DummyDialect): right_table=right_table, join_type="INNER JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o"), ), ) @@ -48,7 +48,7 @@ def test_join_expression_chaining(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders"), alias="o"), join_type="INNER JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o"), ), ) @@ -57,7 +57,7 @@ def test_join_expression_chaining(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "products"), alias="p"), join_type="LEFT JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p") + dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p"), ), ) @@ -77,7 +77,7 @@ def test_multiple_join_chaining(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders"), alias="o"), join_type="INNER JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o"), ), ) @@ -86,7 +86,7 @@ def test_multiple_join_chaining(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "products"), alias="p"), join_type="LEFT JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p") + dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p"), ), ) @@ -95,7 +95,7 @@ def test_multiple_join_chaining(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "categories"), alias="c"), join_type="INNER JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "category_id", "p"), Column(dummy_dialect, "id", "c") + dummy_dialect, "=", Column(dummy_dialect, "category_id", "p"), Column(dummy_dialect, "id", "c"), ), ) @@ -116,7 +116,7 @@ def test_convenience_methods_chaining(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders"), alias="o"), join_type="INNER JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o"), ), ) @@ -124,7 +124,7 @@ def test_convenience_methods_chaining(self, dummy_dialect: DummyDialect): chained_join = base_join.left_join( right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "products"), alias="p"), condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p") + dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p"), ), ) @@ -132,7 +132,7 @@ def test_convenience_methods_chaining(self, dummy_dialect: DummyDialect): final_join = chained_join.inner_join( right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "categories"), alias="c"), condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "category_id", "p"), Column(dummy_dialect, "id", "c") + dummy_dialect, "=", Column(dummy_dialect, "category_id", "p"), Column(dummy_dialect, "id", "c"), ), ) @@ -152,7 +152,7 @@ def test_different_join_types_chaining(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders"), alias="o"), join_type="LEFT JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "c"), Column(dummy_dialect, "customer_id", "o") + dummy_dialect, "=", Column(dummy_dialect, "id", "c"), Column(dummy_dialect, "customer_id", "o"), ), ) @@ -160,7 +160,7 @@ def test_different_join_types_chaining(self, dummy_dialect: DummyDialect): second_join = base_join.inner_join( right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "order_items"), alias="oi"), condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "o"), Column(dummy_dialect, "order_id", "oi") + dummy_dialect, "=", Column(dummy_dialect, "id", "o"), Column(dummy_dialect, "order_id", "oi"), ), ) @@ -168,7 +168,7 @@ def test_different_join_types_chaining(self, dummy_dialect: DummyDialect): third_join = second_join.right_join( right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "products"), alias="p"), condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "product_id", "oi"), Column(dummy_dialect, "id", "p") + dummy_dialect, "=", Column(dummy_dialect, "product_id", "oi"), Column(dummy_dialect, "id", "p"), ), ) @@ -179,7 +179,7 @@ def test_different_join_types_chaining(self, dummy_dialect: DummyDialect): fifth_join = fourth_join.full_join( right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "warehouses"), alias="w"), condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "p"), Column(dummy_dialect, "product_id", "w") + dummy_dialect, "=", Column(dummy_dialect, "id", "p"), Column(dummy_dialect, "product_id", "w"), ), ) @@ -198,14 +198,14 @@ def test_full_join_convenience_method(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "departments"), alias="d"), join_type="INNER JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "department_id", "e"), Column(dummy_dialect, "id", "d") + dummy_dialect, "=", Column(dummy_dialect, "department_id", "e"), Column(dummy_dialect, "id", "d"), ), ) full_join = base_join.full_join( right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "projects"), alias="p"), condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "e"), Column(dummy_dialect, "employee_id", "p") + dummy_dialect, "=", Column(dummy_dialect, "id", "e"), Column(dummy_dialect, "employee_id", "p"), ), ) @@ -248,7 +248,12 @@ def test_left_outer_join_dummy(self, dummy_dialect: DummyDialect): left_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "users"), alias="u"), right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "posts"), alias="p"), join_type="LEFT OUTER JOIN", - condition=Column(dummy_dialect, "id", "u") == Column(dummy_dialect, "user_id", "p"), + condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id", "u"), + Column(dummy_dialect, "user_id", "p"), + ) ) sql, params = join_expr.to_sql() assert sql == '"users" AS "u" LEFT OUTER JOIN "posts" AS "p" ON "u"."id" = "p"."user_id"' @@ -261,7 +266,12 @@ def test_full_outer_join_dummy(self, dummy_dialect: DummyDialect): left_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "customers"), alias="c"), right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders"), alias="o"), join_type="FULL OUTER JOIN", - condition=Column(dummy_dialect, "id", "c") == Column(dummy_dialect, "customer_id", "o"), + condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id", "c"), + Column(dummy_dialect, "customer_id", "o"), + ) ) sql, params = join_expr.to_sql() assert sql == '"customers" AS "c" FULL OUTER JOIN "orders" AS "o" ON "c"."id" = "o"."customer_id"' @@ -298,7 +308,7 @@ def test_join_with_alias_chaining(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders"), alias="o"), join_type="INNER JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o"), ), alias="user_orders", ) @@ -307,7 +317,7 @@ def test_join_with_alias_chaining(self, dummy_dialect: DummyDialect): chained_join = base_join.left_join( right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "products"), alias="p"), condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p") + dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p"), ), alias="full_join", ) @@ -331,8 +341,8 @@ def test_complex_conditions_in_chained_joins(self, dummy_dialect: DummyDialect): ComparisonPredicate( dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o") ), - ComparisonPredicate( - dummy_dialect, ">", Column(dummy_dialect, "total_amount", "o"), Literal(dummy_dialect, 100) + ComparisonPredicate( + dummy_dialect, ">", Column(dummy_dialect, "total_amount", "o"), Literal(dummy_dialect, 100), ), ), ) @@ -346,8 +356,8 @@ def test_complex_conditions_in_chained_joins(self, dummy_dialect: DummyDialect): ComparisonPredicate( dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p") ), - ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "status", "p"), Literal(dummy_dialect, "active") + ComparisonPredicate( + dummy_dialect, "=", Column(dummy_dialect, "status", "p"), Literal(dummy_dialect, "active"), ), ), ) @@ -379,7 +389,7 @@ def test_join_expression_with_query_expression_as_table(self, dummy_dialect: Dum dummy_dialect, "=", Column(dummy_dialect, "user_id", "o"), - Column(dummy_dialect, "id", ""), # No table alias for subquery result + Column(dummy_dialect, "id", ""), # No table alias for subquery result, ), ) @@ -408,7 +418,7 @@ def test_chaining_with_subquery_joins(self, dummy_dialect: DummyDialect): right_table=user_summary, join_type="LEFT JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", ""), ), ) @@ -416,7 +426,7 @@ def test_chaining_with_subquery_joins(self, dummy_dialect: DummyDialect): chained_join = base_join.inner_join( right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "profiles"), alias="p"), condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "p") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "p"), ), ) @@ -435,7 +445,7 @@ def test_nested_join_expressions(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "user_profiles"), alias="up"), join_type="LEFT JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "up") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "up"), ), ) @@ -446,7 +456,7 @@ def test_nested_join_expressions(self, dummy_dialect: DummyDialect): right_table=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "products"), alias="p"), join_type="INNER JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p") + dummy_dialect, "=", Column(dummy_dialect, "product_id", "o"), Column(dummy_dialect, "id", "p"), ), ) @@ -457,7 +467,7 @@ def test_nested_join_expressions(self, dummy_dialect: DummyDialect): right_table=second_join, join_type="LEFT JOIN", condition=ComparisonPredicate( - dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o") + dummy_dialect, "=", Column(dummy_dialect, "id", "u"), Column(dummy_dialect, "user_id", "o"), ), ) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_sql_standard_functions.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_sql_standard_functions.py index 57513288e..63d634148 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_sql_standard_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_sql_standard_functions.py @@ -9,7 +9,7 @@ - User functions: current_user, session_user, system_user """ -from rhosocial.activerecord.backend.expression import Column +from rhosocial.activerecord.backend.expression import Column, Literal from rhosocial.activerecord.backend.expression.functions import ( mod, sign, @@ -38,7 +38,7 @@ class TestSQLStandardMathFunctions: def test_mod_function_basic(self, dummy_dialect: DummyDialect): """Test MOD function with basic values.""" - func = mod(dummy_dialect, 10, 3) + func = mod(dummy_dialect, Literal(dummy_dialect, 10), Literal(dummy_dialect, 3)) sql, params = func.to_sql() assert "MOD(" in sql assert params == (10, 3) @@ -54,21 +54,21 @@ def test_mod_function_with_columns(self, dummy_dialect: DummyDialect): def test_sign_function_positive(self, dummy_dialect: DummyDialect): """Test SIGN function with positive number.""" - func = sign(dummy_dialect, 42) + func = sign(dummy_dialect, Literal(dummy_dialect, 42)) sql, params = func.to_sql() assert "SIGN(" in sql assert params == (42,) def test_sign_function_negative(self, dummy_dialect: DummyDialect): """Test SIGN function with negative number.""" - func = sign(dummy_dialect, -10) + func = sign(dummy_dialect, Literal(dummy_dialect, -10)) sql, params = func.to_sql() assert "SIGN(" in sql assert params == (-10,) def test_sign_function_zero(self, dummy_dialect: DummyDialect): """Test SIGN function with zero.""" - func = sign(dummy_dialect, 0) + func = sign(dummy_dialect, Literal(dummy_dialect, 0)) sql, params = func.to_sql() assert "SIGN(" in sql assert params == (0,) @@ -83,14 +83,14 @@ def test_sign_function_with_column(self, dummy_dialect: DummyDialect): def test_truncate_function_basic(self, dummy_dialect: DummyDialect): """Test TRUNCATE function without precision.""" - func = truncate(dummy_dialect, 3.14159) + func = truncate(dummy_dialect, Literal(dummy_dialect, 3.14159)) sql, params = func.to_sql() assert "TRUNCATE(" in sql assert params == (3.14159,) def test_truncate_function_with_precision(self, dummy_dialect: DummyDialect): """Test TRUNCATE function with precision.""" - func = truncate(dummy_dialect, 3.14159, 2) + func = truncate(dummy_dialect, Literal(dummy_dialect, 3.14159), Literal(dummy_dialect, 2)) sql, params = func.to_sql() assert "TRUNCATE(" in sql assert params == (3.14159, 2) @@ -98,7 +98,7 @@ def test_truncate_function_with_precision(self, dummy_dialect: DummyDialect): def test_truncate_function_with_column(self, dummy_dialect: DummyDialect): """Test TRUNCATE function with column.""" col = Column(dummy_dialect, "price") - func = truncate(dummy_dialect, col, 2) + func = truncate(dummy_dialect, col, Literal(dummy_dialect, 2)) sql, params = func.to_sql() assert "TRUNCATE(" in sql assert params == (2,) @@ -287,7 +287,7 @@ def test_extract_function_basic(self, dummy_dialect: DummyDialect): def test_extract_function_with_column_name(self, dummy_dialect: DummyDialect): """Test EXTRACT function with a column name.""" - func = extract(dummy_dialect, "MONTH", "created_at") + func = extract(dummy_dialect, "MONTH", Column(dummy_dialect, "created_at")) sql, params = func.to_sql() assert sql == 'EXTRACT(MONTH FROM "created_at")' assert params == () diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_index.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_index.py index 6e75a0866..2bbb227ac 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_index.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_index.py @@ -1,6 +1,6 @@ # tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_index.py import pytest -from rhosocial.activerecord.backend.expression import Column, Literal +from rhosocial.activerecord.backend.expression import Column, ComparisonPredicate, Literal from rhosocial.activerecord.backend.expression.statements import CreateIndexExpression, DropIndexExpression from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect from rhosocial.activerecord.backend.expression.objects import Index @@ -69,7 +69,12 @@ def test_create_index_with_type(self, dummy_dialect: DummyDialect): def test_create_index_with_where_clause(self, dummy_dialect: DummyDialect): """Tests CREATE INDEX with WHERE clause (partial index).""" - where_condition = Column(dummy_dialect, "status") == Literal(dummy_dialect, "active", inline_literals=True) + where_condition = ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active", inline_literals=True) + ) create_index = CreateIndexExpression( dummy_dialect, index=Index(dummy_dialect, "idx_active_users"), table=Table(dummy_dialect, "users"), columns=["email"], where=where_condition ) @@ -187,7 +192,12 @@ def test_create_index_various_names(self, dummy_dialect: DummyDialect, index_nam def test_create_index_all_options(self, dummy_dialect: DummyDialect): """Tests CREATE INDEX with all options.""" - where_condition = Column(dummy_dialect, "active") == Literal(dummy_dialect, True, inline_literals=True) + where_condition = ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "active"), + Literal(dummy_dialect, True, inline_literals=True) + ) create_index = CreateIndexExpression( dummy_dialect, index=Index(dummy_dialect, "idx_complex"), diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_view.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_view.py index 41caad032..96618902d 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_view.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_drop_view.py @@ -3,6 +3,7 @@ from rhosocial.activerecord.backend.expression import ( Column, Literal, + ComparisonPredicate, FunctionCall, QueryExpression, CreateViewExpression, @@ -122,7 +123,12 @@ def test_create_view_with_check_options(self, dummy_dialect: DummyDialect, check select=[Column(dummy_dialect, "id"), Column(dummy_dialect, "status")], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "entities")), where=WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) ), ) @@ -249,7 +255,12 @@ def test_create_view_scalar_query(self, dummy_dialect: DummyDialect): def test_create_view_with_where_clause_object(self, dummy_dialect: DummyDialect): """Tests CREATE VIEW with a query that has a where clause object.""" WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) ) # The where clause would be part of the query object, not as a separate parameter query = QueryExpression( @@ -257,7 +268,12 @@ def test_create_view_with_where_clause_object(self, dummy_dialect: DummyDialect) select=[Column(dummy_dialect, "id"), Column(dummy_dialect, "name")], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "users")), where=WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) ), # Using overloaded operator ) @@ -328,7 +344,12 @@ def test_create_view_join_based(self, dummy_dialect: DummyDialect): # Create a join between users and profiles users_table = NamedRelationRef(dummy_dialect, Table(dummy_dialect, "users"), alias="u") profiles_table = NamedRelationRef(dummy_dialect, Table(dummy_dialect, "profiles"), alias="p") - join_condition = Column(dummy_dialect, "user_id", "u") == Column(dummy_dialect, "user_id", "p") + join_condition = ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "user_id", "u"), + Column(dummy_dialect, "user_id", "p") + ) join_expr = JoinClause( dummy_dialect, left_table=users_table, @@ -411,7 +432,7 @@ def test_create_view_with_nested_query(self, dummy_dialect: DummyDialect): def test_create_view_with_window_function(self, dummy_dialect: DummyDialect): """Tests CREATE VIEW with a query that includes window functions.""" - from rhosocial.activerecord.backend.expression.advanced_functions import WindowSpecification, WindowFunctionCall + from rhosocial.activerecord.backend.expression.advanced_functions import WindowSpecification # Create a window specification window_spec = WindowSpecification( @@ -421,8 +442,8 @@ def test_create_view_with_window_function(self, dummy_dialect: DummyDialect): ) # Create a window function call - rank_func = WindowFunctionCall( - dummy_dialect, function_name="ROW_NUMBER", window_spec=window_spec, alias="rank_in_dept" + rank_func = FunctionCall( + dummy_dialect, "ROW_NUMBER", window_spec=window_spec, alias="rank_in_dept" ) query = QueryExpression( diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_table.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_table.py index 13f945311..050928b06 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_table.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_create_table.py @@ -9,6 +9,7 @@ from rhosocial.activerecord.backend.expression import ( Literal, Column, + ComparisonPredicate, FunctionCall, CreateTableExpression, CreateTableAsExpression, @@ -47,7 +48,8 @@ DataTypeMixin, ) from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect -from rhosocial.activerecord.backend.expression.types import CustomType, DateType, DecimalType, IntegerType, SmallIntType, TextType, TimestampType, VarCharType +from rhosocial.activerecord.backend.expression.types import DateType, DecimalType, IntegerType, SmallIntType, TextType, TimestampType, VarCharType +from rhosocial.activerecord.backend.expression.types import CustomType class PartitionTestDialect( @@ -270,7 +272,9 @@ def test_create_table_with_default_constraint(self, dummy_dialect: DummyDialect) def test_create_table_with_check_constraint(self, dummy_dialect: DummyDialect): """Tests CREATE TABLE with CHECK column constraints.""" # Create a check predicate for age > 0 (inline literal for DDL) - age_check = Column(dummy_dialect, "age") > Literal(dummy_dialect, 0, inline_literals=True) + age_check = ComparisonPredicate( + dummy_dialect, ">", Column(dummy_dialect, "age"), Literal(dummy_dialect, 0, inline_literals=True) + ) columns = [ ColumnDefinition(dummy_dialect, "id", IntegerType(dummy_dialect), constraints=[ColumnConstraint(dummy_dialect, ColumnConstraintType.PRIMARY_KEY)]), @@ -391,7 +395,10 @@ def test_create_table_with_tablespace(self, dummy_dialect: DummyDialect): def test_create_table_as_query_result(self, dummy_dialect: DummyDialect): """Tests CREATE TABLE AS with a query result (CTAS).""" where_clause = WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, + condition=ComparisonPredicate( + dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "active") + ) ) query = QueryExpression( dummy_dialect, @@ -844,8 +851,12 @@ def test_create_table_complex_example(self, dummy_dialect: DummyDialect): ColumnConstraint(dummy_dialect, ColumnConstraintType.NOT_NULL), ColumnConstraint(dummy_dialect, ColumnConstraintType.CHECK, - check_condition=Column(dummy_dialect, "amount") - >= Literal(dummy_dialect, 0, inline_literals=True), + check_condition=ComparisonPredicate( + dummy_dialect, + ">=", + Column(dummy_dialect, "amount"), + Literal(dummy_dialect, 0, inline_literals=True), + ), ), ], ), diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_delete.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_delete.py index b4258a137..8d4bc0ccb 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_delete.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_delete.py @@ -8,8 +8,10 @@ DeleteExpression, JoinClause, LogicalPredicate, + NumericColumn, ReturningClause, ComparisonPredicate, + StringColumn, ) from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.expression import ( @@ -122,7 +124,7 @@ def set_dialect_recursive(self, expr, dialect): pytest.param( Table(None, "orders"), None, - Column(None, "status") == Literal(None, "pending"), + ComparisonPredicate(None, "=", Column(None, "status"), Literal(None, "pending")), None, 'DELETE FROM "orders" WHERE "status" = ?', ("pending",), @@ -142,7 +144,7 @@ def set_dialect_recursive(self, expr, dialect): pytest.param( Table(None, "users"), "old_users_table", - Column(None, "id", "users") == Column(None, "old_id", "old_users_table"), + ComparisonPredicate(None, "=", Column(None, "id", "users"), Column(None, "old_id", "old_users_table")), None, 'DELETE FROM "users" USING "old_users_table" WHERE "users"."id" = "old_users_table"."old_id"', (), @@ -152,7 +154,7 @@ def set_dialect_recursive(self, expr, dialect): pytest.param( Table(None, "users"), NamedRelationRef(None, Table(None, "old_users"), alias="o"), - Column(None, "id", "users") == Column(None, "old_id", "o"), + ComparisonPredicate(None, "=", Column(None, "id", "users"), Column(None, "old_id", "o")), None, 'DELETE FROM "users" USING "old_users" AS "o" WHERE "users"."id" = "o"."old_id"', (), @@ -165,9 +167,9 @@ def set_dialect_recursive(self, expr, dialect): None, select=[Column(None, "id")], from_="archived_products", - where=Column(None, "deleted_at") < RawSQLExpression(None, "NOW()"), + where=ComparisonPredicate(None, "<", Column(None, "deleted_at"), RawSQLExpression(None, "NOW()")), ), - Column(None, "id", "products") == Column(None, "id"), + ComparisonPredicate(None, "=", Column(None, "id", "products"), Column(None, "id")), None, 'DELETE FROM "products" USING (SELECT "id" FROM "archived_products" WHERE "deleted_at" < NOW()) WHERE "products"."id" = "id"', # noqa: E501 (), @@ -177,8 +179,8 @@ def set_dialect_recursive(self, expr, dialect): pytest.param( Table(None, "orders"), [NamedRelationRef(None, Table(None, "order_items"), alias="oi"), NamedRelationRef(None, Table(None, "customers"), alias="c")], - (Column(None, "id", "orders") == Column(None, "order_id", "oi")) - & (Column(None, "customer_id", "orders") == Column(None, "id", "c")), + (ComparisonPredicate(None, "=", Column(None, "id", "orders"), Column(None, "order_id", "oi"))) + & (ComparisonPredicate(None, "=", Column(None, "customer_id", "orders"), Column(None, "id", "c"))), None, 'DELETE FROM "orders" USING "order_items" AS "oi", "customers" AS "c" WHERE "orders"."id" = "oi"."order_id" AND "orders"."customer_id" = "c"."id"', # noqa: E501 (), @@ -191,9 +193,9 @@ def set_dialect_recursive(self, expr, dialect): None, NamedRelationRef(None, Table(None, "join_table"), alias="jt"), NamedRelationRef(None, Table(None, "lookup_table"), alias="lt"), - condition=Column(None, "key", "jt") == Column(None, "id", "lt"), + condition=ComparisonPredicate(None, "=", Column(None, "key", "jt"), Column(None, "id", "lt")), ), - Column(None, "id", "main_table") == Column(None, "main_id", "jt"), + ComparisonPredicate(None, "=", Column(None, "id", "main_table"), Column(None, "main_id", "jt")), None, 'DELETE FROM "main_table" USING "join_table" AS "jt" JOIN "lookup_table" AS "lt" ON "jt"."key" = "lt"."id" WHERE "main_table"."id" = "jt"."main_id"', # noqa: E501 (), @@ -203,7 +205,12 @@ def set_dialect_recursive(self, expr, dialect): pytest.param( Table(None, "employees"), "salaries", - Column(None, "employee_id", "employees") == Column(None, "emp_id", "salaries"), + ComparisonPredicate( + None, + "=", + Column(None, "employee_id", "employees"), + Column(None, "emp_id", "salaries"), + ), [Column(None, "employee_id"), Column(None, "first_name")], 'DELETE FROM "employees" USING "salaries" WHERE "employees"."employee_id" = "salaries"."emp_id" RETURNING "employee_id", "first_name"', # noqa: E501 (), @@ -259,7 +266,7 @@ def test_delete_from_unsupported_source_type_raises_type_error(self, dummy_diale """Tests that DeleteExpression raises TypeError for unsupported FROM source types.""" unsupported_source = 123 # An integer, not a string or BaseExpression - where = Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + where = ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "id"), Literal(dummy_dialect, 1)) with pytest.raises( TypeError, @@ -398,7 +405,12 @@ def test_delete_expression_invalid_where_type_after_construction(self, dummy_dia """Tests that DeleteExpression raises TypeError for invalid where parameter type after construction.""" # Manually set an invalid type after construction to test validation delete_expr = DeleteExpression( - dummy_dialect, tables=Table(dummy_dialect, 'users'), where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + dummy_dialect, tables=Table(dummy_dialect, 'users'), where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 1) + ) ) # Manually assign invalid type to trigger validation error delete_expr.where = 123 # Invalid type - should be WhereClause or SQLPredicate @@ -409,7 +421,12 @@ def test_delete_expression_invalid_where_type_after_construction(self, dummy_dia def test_delete_expression_invalid_using_type_after_construction(self, dummy_dialect: DummyDialect): """Tests that DeleteExpression raises TypeError for invalid using parameter type.""" delete_expr = DeleteExpression( - dummy_dialect, tables=Table(dummy_dialect, 'users'), where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + dummy_dialect, tables=Table(dummy_dialect, 'users'), where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 1) + ) ) # Manually assign invalid type to trigger validation error delete_expr.using = 456 # Invalid type @@ -424,7 +441,12 @@ def test_delete_expression_invalid_where_type_initial(self, dummy_dialect: Dummy """Tests that DeleteExpression raises TypeError for invalid where parameter type (initial case).""" # This tests the case where an invalid type is passed initially delete_expr = DeleteExpression( - dummy_dialect, tables=Table(dummy_dialect, 'users'), where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + dummy_dialect, tables=Table(dummy_dialect, 'users'), where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 1) + ) ) # Manually assign invalid type to trigger validation error delete_expr.where = 789 # Invalid type - should be WhereClause or SQLPredicate @@ -435,7 +457,12 @@ def test_delete_expression_invalid_where_type_initial(self, dummy_dialect: Dummy def test_delete_expression_invalid_returning_type(self, dummy_dialect: DummyDialect): """Tests that DeleteExpression raises TypeError for invalid returning parameter type.""" delete_expr = DeleteExpression( - dummy_dialect, tables=Table(dummy_dialect, 'users'), where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + dummy_dialect, tables=Table(dummy_dialect, 'users'), where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 1) + ) ) # Manually assign invalid type to trigger validation error delete_expr.returning = 999 # Invalid type - should be ReturningClause @@ -453,7 +480,7 @@ def test_delete_expression_invalid_tables_type(self, dummy_dialect: DummyDialect delete_expr = DeleteExpression( dummy_dialect, tables="invalid_type", - where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1), + where=ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "id"), Literal(dummy_dialect, 1)), ) with pytest.raises( TypeError, match=r"tables must hold Table instances, got str at position 0" @@ -463,7 +490,12 @@ def test_delete_expression_invalid_tables_type(self, dummy_dialect: DummyDialect def test_delete_expression_empty_tables_value_error(self, dummy_dialect: DummyDialect): """Tests that DeleteExpression raises ValueError for empty tables parameter.""" delete_expr = DeleteExpression( - dummy_dialect, tables=Table(dummy_dialect, 'users'), where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + dummy_dialect, tables=Table(dummy_dialect, 'users'), where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 1) + ) ) # Manually assign empty list to trigger validation error delete_expr.tables = [] # Invalid value - should not be empty @@ -481,7 +513,7 @@ def test_delete_expression_invalid_table_element_type(self, dummy_dialect: Dummy delete_expr = DeleteExpression( dummy_dialect, tables=[Column(dummy_dialect, "invalid_table")], - where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1), + where=ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "id"), Literal(dummy_dialect, 1)), ) with pytest.raises( TypeError, match=r"tables must hold Table instances, got Column at position 0" @@ -496,7 +528,12 @@ def test_delete_expression_empty_table_list_value_error(self, dummy_dialect: Dum def test_delete_expression_single_table_in_list(self, dummy_dialect: DummyDialect): """Tests DeleteExpression with single table in list.""" delete_expr = DeleteExpression( - dummy_dialect, tables=[Table(dummy_dialect, 'users')], where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + dummy_dialect, tables=[Table(dummy_dialect, 'users')], where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 1) + ) ) # Check that the table was properly converted to NamedRelationRef assert len(delete_expr.tables) == 1 @@ -513,7 +550,12 @@ def test_delete_expression_multiple_tables_in_list(self, dummy_dialect: DummyDia delete_expr = DeleteExpression( dummy_dialect, tables=[Table(dummy_dialect, 'users'), Table(dummy_dialect, 'profiles')], - where=Column(dummy_dialect, "user_id") == Literal(dummy_dialect, 123), + where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "user_id"), + Literal(dummy_dialect, 123), + ) ) # Check that the tables were properly converted to NamedRelationRef assert len(delete_expr.tables) == 2 @@ -534,7 +576,12 @@ def test_delete_expression_keeps_the_objects_it_was_given(self, dummy_dialect: D delete_expr = DeleteExpression( dummy_dialect, tables=[users, orders], - where=Column(dummy_dialect, "user_id") == Literal(dummy_dialect, 123), + where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "user_id"), + Literal(dummy_dialect, 123), + ) ) assert delete_expr.tables[0] is users @@ -547,7 +594,12 @@ def test_delete_expression_keeps_the_objects_it_was_given(self, dummy_dialect: D def test_delete_expression_validate_with_strict_false(self, dummy_dialect: DummyDialect): """Tests that DeleteExpression.validate with strict=False skips validation.""" delete_expr = DeleteExpression( - dummy_dialect, tables=Table(dummy_dialect, 'users'), where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + dummy_dialect, tables=Table(dummy_dialect, 'users'), where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "id"), + Literal(dummy_dialect, 1) + ) ) # Manually assign invalid type that would normally cause an error delete_expr.where = 999 # Invalid type - should be WhereClause or SQLPredicate @@ -557,7 +609,12 @@ def test_delete_expression_validate_with_strict_false(self, dummy_dialect: Dummy # Also test with valid parameters and strict=False delete_expr_valid = DeleteExpression( - dummy_dialect, tables=Table(dummy_dialect, 'products'), where=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, tables=Table(dummy_dialect, 'products'), where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active") + ) ) delete_expr_valid.validate(strict=False) # Should not raise any exception assert True # Just to ensure the test passes @@ -572,7 +629,7 @@ def test_delete_expression_validate_with_strict_false(self, dummy_dialect: Dummy ) def test_delete_with_like_condition(self, dummy_dialect: DummyDialect, op, pattern, expected_sql_part): """Tests DELETE with LIKE/ILIKE conditions.""" - name_col = Column(dummy_dialect, "name") + name_col = StringColumn(dummy_dialect, "name") if op == "LIKE": like_condition = name_col.like(pattern) elif op == "ILIKE": @@ -589,8 +646,8 @@ def test_delete_with_like_condition(self, dummy_dialect: DummyDialect, op, patte def test_delete_with_combined_like_and_other_conditions(self, dummy_dialect: DummyDialect): """Tests DELETE with LIKE condition combined with other conditions.""" - name_col = Column(dummy_dialect, "name") - age_col = Column(dummy_dialect, "age") + name_col = StringColumn(dummy_dialect, "name") + age_col = NumericColumn(dummy_dialect, "age") # Combine LIKE with comparison condition like_condition = name_col.like("John%") @@ -680,7 +737,12 @@ def test_delete_expression_with_where_clause_object(self, dummy_dialect: DummyDi # Create a WhereClause object using comparison operator where_clause_obj = WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "inactive") + dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "inactive") + ) ) # Create a DeleteExpression with the WhereClause object diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_explain.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_explain.py index e6200ad4f..669e09260 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_explain.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_explain.py @@ -1,6 +1,7 @@ # tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_explain.py import pytest from rhosocial.activerecord.backend.expression import ( + ComparisonPredicate, Column, Literal, QueryExpression, @@ -49,7 +50,12 @@ def test_explain_with_types(self, dummy_dialect: DummyDialect, explain_type, exp dummy_dialect, select=[Column(dummy_dialect, "id")], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "products")), - where=WhereClause(dummy_dialect, condition=Column(dummy_dialect, "price") > Literal(dummy_dialect, 100)), + where=WhereClause(dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + ">", + Column(dummy_dialect, "price"), + Literal(dummy_dialect, 100)), + ) ) # Create EXPLAIN options @@ -91,7 +97,12 @@ def test_explain_with_analyze_and_format(self, dummy_dialect: DummyDialect): select=[Column(dummy_dialect, "id"), Column(dummy_dialect, "total")], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "orders")), where=WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "order_date") > Literal(dummy_dialect, "2024-01-01") + dummy_dialect, condition=ComparisonPredicate( + dummy_dialect, + ">", + Column(dummy_dialect, "order_date"), + Literal(dummy_dialect, "2024-01-01") + ) ), ) @@ -130,13 +141,13 @@ def test_explain_with_different_statements(self, dummy_dialect: DummyDialect, st dummy_dialect, table=Table(dummy_dialect, 'test_table'), assignments={"name": Literal(dummy_dialect, "updated")}, - where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1), + where=ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "id"), Literal(dummy_dialect, 1)), ) elif statement_type == "DELETE": stmt = DeleteExpression( dummy_dialect, tables=Table(dummy_dialect, 'test_table'), - where=Column(dummy_dialect, "id") == Literal(dummy_dialect, 1), + where=ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "id"), Literal(dummy_dialect, 1)), ) explain_expr = ExplainExpression(dummy_dialect, statement=stmt) diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_insert.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_insert.py index e50e11c28..b7a6716e8 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_insert.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_insert.py @@ -4,6 +4,7 @@ Column, Literal, RawSQLExpression, + ComparisonPredicate, QueryExpression, InsertExpression, ValuesSource, @@ -181,7 +182,12 @@ def test_on_conflict_clause_init_errors(self, dummy_dialect: DummyDialect, confl None, conflict_target=["p_id"], update_assignments={"qty": RawSQLExpression(None, "excluded.qty")}, - update_where=Column(None, "qty", "products") < RawSQLExpression(None, "excluded.qty"), + update_where=ComparisonPredicate( + None, + "<", + Column(None, "qty", "products"), + RawSQLExpression(None, "excluded.qty"), + ) ), 2, 'INSERT INTO "products" ("p_id", "qty") VALUES (?, ?), (?, ?) ON CONFLICT ("p_id") DO UPDATE SET "qty" = excluded.qty WHERE "products"."qty" < excluded.qty', # noqa: E501 @@ -376,7 +382,13 @@ def set_dialect_recursive(expr, dialect): def test_insert_with_select_source(self, dummy_dialect: DummyDialect): """Tests INSERT ... SELECT ... using SelectSource.""" where_clause = WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, + condition=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active"), + ) ) select_query = QueryExpression( dummy_dialect, @@ -457,7 +469,12 @@ def test_insert_on_conflict_do_update_with_where(self, dummy_dialect: DummyDiale dummy_dialect, conflict_target=["id"], update_assignments={"name": Column(dummy_dialect, "name", "excluded")}, - update_where=Column(dummy_dialect, "is_active", "products") == Literal(dummy_dialect, True), + update_where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "is_active", "products"), + Literal(dummy_dialect, True), + ) ) insert_expr = InsertExpression( dummy_dialect, into=Table(dummy_dialect, 'products'), columns=["id", "name"], source=source, on_conflict=on_conflict @@ -695,8 +712,18 @@ def test_on_conflict_update_where_with_complex_predicate(self, dummy_dialect: Du "status": Column(dummy_dialect, "status", "excluded"), "priority": Column(dummy_dialect, "priority", "excluded"), }, - update_where=(Column(dummy_dialect, "status", "users") == Literal(dummy_dialect, "active")) - & (Column(dummy_dialect, "priority", "excluded") > Column(dummy_dialect, "priority", "users")), + update_where=(ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status", "users"), + Literal(dummy_dialect, "active")) + ) + & (ComparisonPredicate( + dummy_dialect, + ">", + Column(dummy_dialect, "priority", "excluded"), + Column(dummy_dialect, "priority", "users") + )) ) insert_expr = InsertExpression( dummy_dialect, into=Table(dummy_dialect, 'users'), columns=["id", "status", "priority"], source=source, on_conflict=on_conflict @@ -772,7 +799,12 @@ def test_insert_multiple_on_conflict_with_where(self, dummy_dialect: DummyDialec dummy_dialect, conflict_target=["name"], update_assignments={"qty": Column(dummy_dialect, "qty", "excluded")}, - update_where=Column(dummy_dialect, "qty", "products") > Column(dummy_dialect, "qty", "excluded"), + update_where=ComparisonPredicate( + dummy_dialect, + ">", + Column(dummy_dialect, "qty", "products"), + Column(dummy_dialect, "qty", "excluded"), + ) ) insert_expr = InsertExpression( dummy_dialect, diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_query.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_query.py index 15bd7cb9f..1b2b01ef6 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_query.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_query.py @@ -8,11 +8,12 @@ ComparisonPredicate, QueryExpression, SelectModifier, + NumericColumn, + StringColumn, WindowFrameSpecification, WindowSpecification, WindowDefinition, WindowClause, - WindowFunctionCall, ) from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.expression.query_parts import ( @@ -84,7 +85,7 @@ def test_query_expression_with_for_update_nowait(self, dummy_dialect: DummyDiale # --- Window Functions --- def test_window_function_call_inline_spec(self, dummy_dialect: DummyDialect): - """Tests WindowFunctionCall with inline window specification.""" + """Tests FunctionCall with inline window specification.""" # Create a window specification from rhosocial.activerecord.backend.expression.query_parts import OrderByClause @@ -95,8 +96,8 @@ def test_window_function_call_inline_spec(self, dummy_dialect: DummyDialect): ) # Create the window function call - window_func = WindowFunctionCall( - dummy_dialect, function_name="ROW_NUMBER", window_spec=window_spec, alias="row_num" + window_func = FunctionCall( + dummy_dialect, "ROW_NUMBER", window_spec=window_spec, alias="row_num" ) sql, params = window_func.to_sql() @@ -105,7 +106,7 @@ def test_window_function_call_inline_spec(self, dummy_dialect: DummyDialect): assert params == () def test_window_function_call_with_frame_specification(self, dummy_dialect: DummyDialect): - """Tests WindowFunctionCall with frame specification.""" + """Tests FunctionCall with frame specification.""" # Create a frame specification frame_spec = WindowFrameSpecification( dummy_dialect, frame_type="ROWS", start_frame="UNBOUNDED PRECEDING", end_frame="CURRENT ROW" @@ -122,10 +123,10 @@ def test_window_function_call_with_frame_specification(self, dummy_dialect: Dumm ) # Create a window function call - window_func = WindowFunctionCall( + window_func = FunctionCall( dummy_dialect, - function_name="SUM", - args=[Column(dummy_dialect, "amount")], + "SUM", + Column(dummy_dialect, "amount"), window_spec=window_spec, alias="running_total", ) @@ -136,12 +137,12 @@ def test_window_function_call_with_frame_specification(self, dummy_dialect: Dumm assert params == () def test_window_function_call_with_named_window_reference(self, dummy_dialect: DummyDialect): - """Tests WindowFunctionCall with reference to named window.""" + """Tests FunctionCall with reference to named window.""" # Create a window function that references a named window (this would be used in a query # where the WINDOW clause defines the named window) - window_func = WindowFunctionCall( + window_func = FunctionCall( dummy_dialect, - function_name="RANK", + "RANK", window_spec="sales_window", # Reference to named window alias="sales_rank", ) @@ -190,7 +191,7 @@ def test_query_with_window_clause(self, dummy_dialect: DummyDialect): select=[ Column(dummy_dialect, "employee_name"), # In a real query, these would reference the named windows - WindowFunctionCall(dummy_dialect, "ROW_NUMBER", window_spec="dept_ranking"), + FunctionCall(dummy_dialect, "ROW_NUMBER", window_spec="dept_ranking"), ], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "employees")), # Note: The WindowClause would need to be integrated into QueryExpression to be fully functional @@ -413,7 +414,7 @@ def test_query_expression_with_qualify_clause(self, dummy_dialect: DummyDialect) def test_comparison_mixin_methods(self, dummy_dialect: DummyDialect): """Test ComparisonMixin methods that are not directly tested elsewhere.""" - col = Column(dummy_dialect, "status") + col = StringColumn(dummy_dialect, "status") # Test is_null method is_null_pred = col.is_null() @@ -441,7 +442,7 @@ def test_comparison_mixin_methods(self, dummy_dialect: DummyDialect): assert params == ("deleted", "banned") # Test between method - age_col = Column(dummy_dialect, "age") + age_col = NumericColumn(dummy_dialect, "age") between_pred = age_col.between(18, 65) sql, params = between_pred.to_sql() assert "BETWEEN" in sql.upper() @@ -449,7 +450,7 @@ def test_comparison_mixin_methods(self, dummy_dialect: DummyDialect): def test_arithmetic_mixin_methods(self, dummy_dialect: DummyDialect): """Test ArithmeticMixin methods.""" - price_col = Column(dummy_dialect, "price") + price_col = NumericColumn(dummy_dialect, "price") tax_rate = Literal(dummy_dialect, 0.1) # Test arithmetic operations @@ -476,23 +477,23 @@ def test_arithmetic_mixin_methods(self, dummy_dialect: DummyDialect): def test_logical_mixin_methods(self, dummy_dialect: DummyDialect): """Test LogicalMixin methods.""" # Test logical AND using & operator - cond1 = Column(dummy_dialect, "age") > Literal(dummy_dialect, 18) - cond2 = Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + cond1 = NumericColumn(dummy_dialect, "age") > Literal(dummy_dialect, 18) + cond2 = StringColumn(dummy_dialect, "status") == Literal(dummy_dialect, "active") logical_and = cond1 & cond2 sql, params = logical_and.to_sql() assert "AND" in sql.upper() assert params == (18, "active") # Test logical OR using | operator - cond3 = Column(dummy_dialect, "score") < Literal(dummy_dialect, 50) - cond4 = Column(dummy_dialect, "category") == Literal(dummy_dialect, "low_priority") + cond3 = NumericColumn(dummy_dialect, "score") < Literal(dummy_dialect, 50) + cond4 = StringColumn(dummy_dialect, "category") == Literal(dummy_dialect, "low_priority") logical_or = cond3 | cond4 sql, params = logical_or.to_sql() assert "OR" in sql.upper() assert params == (50, "low_priority") # Test logical NOT using ~ operator - status_col = Column(dummy_dialect, "status") + status_col = StringColumn(dummy_dialect, "status") not_active = ~(status_col == Literal(dummy_dialect, "inactive")) sql, params = not_active.to_sql() assert "NOT" in sql.upper() @@ -500,7 +501,7 @@ def test_logical_mixin_methods(self, dummy_dialect: DummyDialect): def test_string_mixin_methods(self, dummy_dialect: DummyDialect): """Test StringMixin methods.""" - name_col = Column(dummy_dialect, "name") + name_col = StringColumn(dummy_dialect, "name") # Test LIKE operation like_pred = name_col.like("John%") @@ -516,7 +517,7 @@ def test_string_mixin_methods(self, dummy_dialect: DummyDialect): def test_comparison_operators_direct_usage(self, dummy_dialect: DummyDialect): """Test direct usage of comparison operators that may not be covered elsewhere.""" - age_col = Column(dummy_dialect, "age") + age_col = NumericColumn(dummy_dialect, "age") value = Literal(dummy_dialect, 25) # Test all comparison operators @@ -561,7 +562,7 @@ def test_comparison_operators_direct_usage(self, dummy_dialect: DummyDialect): ) def test_query_with_like_condition(self, dummy_dialect: DummyDialect, op, pattern, expected_sql_part): """Tests query with LIKE/ILIKE conditions.""" - name_col = Column(dummy_dialect, "name") + name_col = StringColumn(dummy_dialect, "name") if op == "LIKE": like_condition = name_col.like(pattern) elif op == "ILIKE": @@ -579,8 +580,8 @@ def test_query_with_like_condition(self, dummy_dialect: DummyDialect, op, patter def test_query_with_combined_like_and_other_conditions(self, dummy_dialect: DummyDialect): """Tests query with LIKE condition combined with other conditions.""" - name_col = Column(dummy_dialect, "name") - age_col = Column(dummy_dialect, "age") + name_col = StringColumn(dummy_dialect, "name") + age_col = NumericColumn(dummy_dialect, "age") # Combine LIKE with comparison condition like_condition = name_col.like("John%") @@ -721,7 +722,12 @@ def test_query_expression_validate_with_strict_false(self, dummy_dialect: DummyD dummy_dialect, select=[Column(dummy_dialect, "name"), Column(dummy_dialect, "email")], from_=NamedRelationRef(dummy_dialect, Table(dummy_dialect, "customers")), - where=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active"), + where=ComparisonPredicate( + dummy_dialect, + "=", + Column(dummy_dialect, "status"), + Literal(dummy_dialect, "active"), + ) ) query_valid.validate(strict=False) # Should not raise any exception assert True # Just to ensure the test passes diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_update.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_update.py index 6a1effdae..535f63912 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_update.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_statements_update.py @@ -10,6 +10,10 @@ JoinClause, LogicalPredicate, ReturningClause, + BinaryExpression, + ComparisonPredicate, + NumericColumn, + StringColumn, ) from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.expression.query_parts import WhereClause @@ -51,7 +55,7 @@ def test_update_empty_assignments_raises_error(self, dummy_dialect: DummyDialect pytest.param( Table(None, "orders"), {"status": Literal(None, "shipped"), "updated_at": RawSQLExpression(None, "CURRENT_TIMESTAMP")}, - Column(None, "id") == Literal(None, 1), + ComparisonPredicate(None, "=", Column(None, "id"), Literal(None, 1)), None, 'UPDATE "orders" SET "status" = ?, "updated_at" = CURRENT_TIMESTAMP WHERE "id" = ?', ("shipped", 1), @@ -60,7 +64,7 @@ def test_update_empty_assignments_raises_error(self, dummy_dialect: DummyDialect ), pytest.param( Table(None, "items"), - {"quantity": Column(None, "quantity") + Literal(None, 1)}, + {"quantity": BinaryExpression(None, "+", Column(None, "quantity"), Literal(None, 1))}, None, [Column(None, "id"), Column(None, "quantity")], 'UPDATE "items" SET "quantity" = "quantity" + ? RETURNING "id", "quantity"', @@ -189,7 +193,7 @@ def set_dialect_recursive(expr, dialect): pytest.param( NamedRelationRef(None, Table(None, "logs"), alias="l"), {"last_login": Column(None, "login_time", "l")}, - Column(None, "id", "users") == Column(None, "user_id", "l"), + ComparisonPredicate(None, "=", Column(None, "id", "users"), Column(None, "user_id", "l")), 'FROM "logs" AS "l"', 'UPDATE "users" SET "last_login" = "l"."login_time" %s WHERE "users"."id" = "l"."user_id"', (), # No extra params, all from expressions @@ -203,7 +207,7 @@ def set_dialect_recursive(expr, dialect): from_=NamedRelationRef(None, Table(None, "sub_users"), alias="s"), ), {"status": Column(None, "status_val", "s")}, - Column(None, "id", "users") == Column(None, "id", "s"), + ComparisonPredicate(None, "=", Column(None, "id", "users"), Column(None, "id", "s")), 'FROM (SELECT "s"."id", "s"."status_val" FROM "sub_users" AS "s")', 'UPDATE "users" SET "status" = "s"."status_val" %s WHERE "users"."id" = "s"."id"', (), @@ -213,8 +217,8 @@ def set_dialect_recursive(expr, dialect): pytest.param( [NamedRelationRef(None, Table(None, "logs"), alias="l"), NamedRelationRef(None, Table(None, "actions"), alias="a")], {"activity_count": Column(None, "count", "a")}, - (Column(None, "id", "users") == Column(None, "user_id", "l")) - & (Column(None, "action_id", "l") == Column(None, "id", "a")), + (ComparisonPredicate(None, "=", Column(None, "id", "users"), Column(None, "user_id", "l"))) + & (ComparisonPredicate(None, "=", Column(None, "action_id", "l"), Column(None, "id", "a"))), 'FROM "logs" AS "l", "actions" AS "a"', 'UPDATE "users" SET "activity_count" = "a"."count" %s WHERE "users"."id" = "l"."user_id" AND "l"."action_id" = "a"."id"', # noqa: E501 (), @@ -226,10 +230,15 @@ def set_dialect_recursive(expr, dialect): None, NamedRelationRef(None, Table(None, "user_data"), alias="ud"), NamedRelationRef(None, Table(None, "users"), alias="u"), - condition=Column(None, "user_id", "ud") == Column(None, "id", "u"), + condition=ComparisonPredicate(None, "=", Column(None, "user_id", "ud"), Column(None, "id", "u")), ), {"value": Literal(None, 123)}, - Column(None, "id", "ud") == Column(None, "id", "u"), # Example WHERE, effectively part of JOIN + ComparisonPredicate( + None, + "=", + Column(None, "id", "ud"), + Column(None, "id", "u"), + ), # Example WHERE, effectively part of JOIN 'FROM "user_data" AS "ud" JOIN "users" AS "u" ON "ud"."user_id" = "u"."id"', 'UPDATE "user_data" SET "value" = ? %s WHERE "ud"."id" = "u"."id"', (123,), @@ -239,7 +248,7 @@ def set_dialect_recursive(expr, dialect): pytest.param( "logs_table", # A bare name is a legal FROM source {"status": Literal(None, "active")}, - Column(None, "user_id") == Literal(None, 1), + ComparisonPredicate(None, "=", Column(None, "user_id"), Literal(None, 1)), 'FROM "logs_table"', 'UPDATE "users" SET "status" = ? %s WHERE "user_id" = ?', ("active", 1), @@ -369,7 +378,7 @@ def test_update_from_unsupported_source_type_raises_type_error(self, dummy_diale unsupported_source = 123 # An integer, not a string or BaseExpression assignments = {"name": Literal(dummy_dialect, "New Name")} - where = Column(dummy_dialect, "id") == Literal(dummy_dialect, 1) + where = ComparisonPredicate(dummy_dialect, "=", Column(dummy_dialect, "id"), Literal(dummy_dialect, 1)) with pytest.raises(TypeError, match=r"Unsupported FROM source type: "): update_expr = UpdateExpression( @@ -398,7 +407,10 @@ def test_update_expression_with_where_clause_object(self, dummy_dialect: DummyDi # Create a WhereClause object using comparison operator where_clause_obj = WhereClause( - dummy_dialect, condition=Column(dummy_dialect, "status") == Literal(dummy_dialect, "active") + dummy_dialect, + condition=ComparisonPredicate( + dummy_dialect, "=", Column(dummy_dialect, "status"), Literal(dummy_dialect, "active"), + ), ) # Create an UpdateExpression with the WhereClause object @@ -424,7 +436,7 @@ def test_update_expression_with_where_clause_object(self, dummy_dialect: DummyDi ) def test_update_with_like_condition(self, dummy_dialect: DummyDialect, op, pattern, expected_sql_part): """Tests UPDATE with LIKE/ILIKE conditions.""" - name_col = Column(dummy_dialect, "name") + name_col = StringColumn(dummy_dialect, "name") if op == "LIKE": like_condition = name_col.like(pattern) elif op == "ILIKE": @@ -446,8 +458,8 @@ def test_update_with_like_condition(self, dummy_dialect: DummyDialect, op, patte def test_update_with_combined_like_and_other_conditions(self, dummy_dialect: DummyDialect): """Tests UPDATE with LIKE condition combined with other conditions.""" - name_col = Column(dummy_dialect, "name") - age_col = Column(dummy_dialect, "age") + name_col = StringColumn(dummy_dialect, "name") + age_col = NumericColumn(dummy_dialect, "age") # Combine LIKE with comparison condition like_condition = name_col.like("John%") diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_casting_mixin.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_casting_mixin.py index b128231cd..7f42864cb 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_casting_mixin.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_casting_mixin.py @@ -9,6 +9,7 @@ from rhosocial.activerecord.backend.expression import Literal, Column, FunctionCall from rhosocial.activerecord.backend.expression.core import CastExpression +from rhosocial.activerecord.backend.expression.types import CustomType from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect @@ -18,7 +19,7 @@ class TestTypeCastingMixin: def test_column_cast_basic(self, dummy_dialect: DummyDialect): """Test Column with basic type cast.""" col = Column(dummy_dialect, "price") - expr = col.cast("INTEGER") + expr = col.cast(CustomType(col.dialect, raw="INTEGER")) sql, params = expr.to_sql() assert sql == 'CAST("price" AS INTEGER)' assert params == () @@ -26,7 +27,7 @@ def test_column_cast_basic(self, dummy_dialect: DummyDialect): def test_column_cast_with_varchar_length(self, dummy_dialect: DummyDialect): """Test Column with VARCHAR type cast including length modifier.""" col = Column(dummy_dialect, "name") - expr = col.cast("VARCHAR(100)") + expr = col.cast(CustomType(col.dialect, raw="VARCHAR(100)")) sql, params = expr.to_sql() assert sql == 'CAST("name" AS VARCHAR(100))' assert params == () @@ -34,7 +35,7 @@ def test_column_cast_with_varchar_length(self, dummy_dialect: DummyDialect): def test_column_cast_with_numeric_precision(self, dummy_dialect: DummyDialect): """Test Column with NUMERIC type cast including precision and scale.""" col = Column(dummy_dialect, "amount") - expr = col.cast("NUMERIC(10,2)") + expr = col.cast(CustomType(col.dialect, raw="NUMERIC(10,2)")) sql, params = expr.to_sql() assert sql == 'CAST("amount" AS NUMERIC(10,2))' assert params == () @@ -42,7 +43,7 @@ def test_column_cast_with_numeric_precision(self, dummy_dialect: DummyDialect): def test_literal_cast(self, dummy_dialect: DummyDialect): """Test Literal with type cast.""" lit = Literal(dummy_dialect, "123") - expr = lit.cast("INTEGER") + expr = lit.cast(CustomType(lit.dialect, raw="INTEGER")) sql, params = expr.to_sql() assert sql == "CAST(? AS INTEGER)" assert params == ("123",) @@ -50,7 +51,7 @@ def test_literal_cast(self, dummy_dialect: DummyDialect): def test_function_call_cast(self, dummy_dialect: DummyDialect): """Test FunctionCall with type cast.""" func = FunctionCall(dummy_dialect, "SUM", Column(dummy_dialect, "price")) - expr = func.cast("NUMERIC") + expr = func.cast(CustomType(func.dialect, raw="NUMERIC")) sql, params = expr.to_sql() assert sql == 'CAST(SUM("price") AS NUMERIC)' assert params == () @@ -58,7 +59,7 @@ def test_function_call_cast(self, dummy_dialect: DummyDialect): def test_chained_type_cast(self, dummy_dialect: DummyDialect): """Test chained type conversions — each cast nests the previous node.""" col = Column(dummy_dialect, "amount") - expr = col.cast("MONEY").cast("NUMERIC").cast("FLOAT8") + expr = col.cast(CustomType(col.dialect, raw="MONEY")).cast(CustomType(col.dialect, raw="NUMERIC")).cast(CustomType(col.dialect, raw="FLOAT8")) sql, params = expr.to_sql() assert sql == 'CAST(CAST(CAST("amount" AS MONEY) AS NUMERIC) AS FLOAT8)' assert params == () @@ -66,17 +67,19 @@ def test_chained_type_cast(self, dummy_dialect: DummyDialect): def test_cast_returns_wrapping_node(self, dummy_dialect: DummyDialect): """Test that cast() returns a CastExpression node wrapping self.""" col = Column(dummy_dialect, "value") - result = col.cast("INTEGER") + result = col.cast(CustomType(col.dialect, raw="INTEGER")) assert isinstance(result, CastExpression) assert result.expression is col - assert result.target_type == "INTEGER" + # CustomType is what a backend type name maps to; the raw spelling is + # what reaches the SQL, and it is checked by the rendered statement below. + assert result.target_type.name == "custom" # The original node is unchanged — casts never mutate their target. assert col.to_sql()[0] == '"value"' def test_cast_with_alias(self, dummy_dialect: DummyDialect): """Test type cast with alias (applied after the cast).""" col = Column(dummy_dialect, "value") - expr = col.cast("INTEGER").as_("int_value") + expr = col.cast(CustomType(col.dialect, raw="INTEGER")).as_("int_value") sql, params = expr.to_sql() assert sql == 'CAST("value" AS INTEGER) AS "int_value"' assert params == () @@ -84,7 +87,7 @@ def test_cast_with_alias(self, dummy_dialect: DummyDialect): def test_cast_expression_supports_comparison(self, dummy_dialect: DummyDialect): """Test that casted expression supports comparison operators.""" col = Column(dummy_dialect, "amount") - predicate = col.cast("INTEGER") > 0 + predicate = col.cast(CustomType(col.dialect, raw="INTEGER")) > 0 sql, params = predicate.to_sql() assert sql == 'CAST("amount" AS INTEGER) > ?' assert params == (0,) @@ -92,7 +95,7 @@ def test_cast_expression_supports_comparison(self, dummy_dialect: DummyDialect): def test_cast_expression_supports_arithmetic(self, dummy_dialect: DummyDialect): """Test that casted expression supports arithmetic operators.""" col = Column(dummy_dialect, "price") - result = col.cast("NUMERIC") * 1.1 + result = col.cast(CustomType(col.dialect, raw="NUMERIC")) * 1.1 sql, params = result.to_sql() assert sql == 'CAST("price" AS NUMERIC) * ?' assert params == (1.1,) @@ -100,7 +103,7 @@ def test_cast_expression_supports_arithmetic(self, dummy_dialect: DummyDialect): def test_cast_expression_supports_comparison_equality(self, dummy_dialect: DummyDialect): """Test that casted expression supports equality comparison.""" col = Column(dummy_dialect, "status") - predicate = col.cast("INTEGER") == 1 + predicate = col.cast(CustomType(col.dialect, raw="INTEGER")) == 1 sql, params = predicate.to_sql() assert sql == 'CAST("status" AS INTEGER) = ?' assert params == (1,) @@ -108,7 +111,7 @@ def test_cast_expression_supports_comparison_equality(self, dummy_dialect: Dummy def test_cast_expression_supports_comparison_in(self, dummy_dialect: DummyDialect): """Test that casted expression supports IN predicate.""" col = Column(dummy_dialect, "category") - predicate = col.cast("INTEGER").in_([1, 2, 3]) + predicate = col.cast(CustomType(col.dialect, raw="INTEGER")).in_([1, 2, 3]) sql, params = predicate.to_sql() assert sql == 'CAST("category" AS INTEGER) IN (?, ?, ?)' assert params == (1, 2, 3) @@ -116,7 +119,7 @@ def test_cast_expression_supports_comparison_in(self, dummy_dialect: DummyDialec def test_cast_expression_supports_aliasable(self, dummy_dialect: DummyDialect): """Test that casted expression inherits AliasableMixin.""" col = Column(dummy_dialect, "value") - expr = col.cast("TEXT") + expr = col.cast(CustomType(col.dialect, raw="TEXT")) # Verify as_ method exists and works aliased = expr.as_("text_value") assert aliased.alias == "text_value" @@ -126,7 +129,7 @@ def test_cast_expression_supports_aliasable(self, dummy_dialect: DummyDialect): def test_cast_expression_inheritance_chain(self, dummy_dialect: DummyDialect): """Test that casted expression inherits all expected mixins.""" col = Column(dummy_dialect, "value") - expr = col.cast("INTEGER") + expr = col.cast(CustomType(col.dialect, raw="INTEGER")) # Verify TypeCastingMixin is inherited (for chaining) assert hasattr(expr, "cast") @@ -147,7 +150,7 @@ def test_cast_expression_inheritance_chain(self, dummy_dialect: DummyDialect): def test_cast_with_table_qualified_column(self, dummy_dialect: DummyDialect): """Test type cast on table-qualified column.""" col = Column(dummy_dialect, "amount", table="orders") - expr = col.cast("INTEGER") + expr = col.cast(CustomType(col.dialect, raw="INTEGER")) sql, params = expr.to_sql() assert sql == 'CAST("orders"."amount" AS INTEGER)' assert params == () @@ -155,7 +158,7 @@ def test_cast_with_table_qualified_column(self, dummy_dialect: DummyDialect): def test_nested_function_cast(self, dummy_dialect: DummyDialect): """Test type cast on function result.""" inner_func = FunctionCall(dummy_dialect, "COALESCE", Column(dummy_dialect, "price"), Literal(dummy_dialect, 0)) - expr = inner_func.cast("NUMERIC(10,2)") + expr = inner_func.cast(CustomType(inner_func.dialect, raw="NUMERIC(10,2)")) sql, params = expr.to_sql() assert sql == 'CAST(COALESCE("price", ?) AS NUMERIC(10,2))' assert params == (0,) @@ -163,7 +166,7 @@ def test_nested_function_cast(self, dummy_dialect: DummyDialect): def test_chained_cast_after_alias(self, dummy_dialect: DummyDialect): """Test chained cast after applying alias.""" col = Column(dummy_dialect, "amount") - expr = col.cast("MONEY").as_("m").cast("NUMERIC") + expr = col.cast(CustomType(col.dialect, raw="MONEY")).as_("m").cast(CustomType(col.dialect, raw="NUMERIC")) sql, params = expr.to_sql() # The cast should wrap the previous expression assert "CAST(" in sql @@ -174,7 +177,7 @@ def test_multiple_arithmetic_with_cast(self, dummy_dialect: DummyDialect): """Test multiple arithmetic operations with type cast.""" col1 = Column(dummy_dialect, "price1") col2 = Column(dummy_dialect, "price2") - result = col1.cast("NUMERIC") + col2.cast("NUMERIC") + result = col1.cast(CustomType(col1.dialect, raw="NUMERIC")) + col2.cast(CustomType(col2.dialect, raw="NUMERIC")) sql, params = result.to_sql() assert sql == 'CAST("price1" AS NUMERIC) + CAST("price2" AS NUMERIC)' assert params == () @@ -182,24 +185,24 @@ def test_multiple_arithmetic_with_cast(self, dummy_dialect: DummyDialect): def test_cast_preserves_dialect(self, dummy_dialect: DummyDialect): """Test that cast preserves the dialect from source expression.""" col = Column(dummy_dialect, "value") - expr = col.cast("INTEGER") + expr = col.cast(CustomType(col.dialect, raw="INTEGER")) assert expr.dialect is dummy_dialect assert col.dialect is dummy_dialect def test_double_chained_cast_preserves_dialect(self, dummy_dialect: DummyDialect): """Test that double chained cast preserves the dialect.""" col = Column(dummy_dialect, "value") - expr = col.cast("MONEY").cast("NUMERIC") + expr = col.cast(CustomType(col.dialect, raw="MONEY")).cast(CustomType(col.dialect, raw="NUMERIC")) assert expr.dialect is dummy_dialect def test_chained_casts_nest_as_nodes(self, dummy_dialect: DummyDialect): """Test that each cast() wraps the previous node — no decoration lists.""" col = Column(dummy_dialect, "value") - first = col.cast("INTEGER") - second = first.cast("VARCHAR") + first = col.cast(CustomType(col.dialect, raw="INTEGER")) + second = first.cast(CustomType(first.dialect, raw="VARCHAR")) assert isinstance(first, CastExpression) assert isinstance(second, CastExpression) assert second.expression is first assert first.expression is col - assert first.target_type == "INTEGER" - assert second.target_type == "VARCHAR" + assert first.target_type.raw == "INTEGER" + assert second.target_type.raw == "VARCHAR" diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_dispatch_registry.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_dispatch_registry.py new file mode 100644 index 000000000..c2716b60e --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_dispatch_registry.py @@ -0,0 +1,299 @@ +# tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_dispatch_registry.py +"""``supports_data_types()`` must resolve every name the dialect can render. + +There is no registry. The naming family **is** the registry: a dialect declares +``format_data_type_`` and the class behind that name is found by lookup. +That design has one sharp edge, and this file is about it. + +:meth:`~...dialect.mixins.data_type.DataTypeMixin._type_class_for` answers a +dispatch name by walking the live subclass tree of ``DataType`` — so it sees only +the classes something has already **imported**. On a cold +``import .dialect``, a name whose class lives in a module nobody has +touched resolves to ``None``, is dropped from the mapping, and the caller is left +concluding that the dialect cannot render a type it has a formatter for. There is +no error anywhere. The SQL Server backend hit exactly this and had to import its +own type module by hand to fix it. + +Why these tests run in a **fresh interpreter** +---------------------------------------------- +A test module that imports the type classes in its own preamble has already made +the bug invisible: by the time the assertion runs, the class is loaded and the +lookup succeeds whether or not the production code is correct. The only way to +see a load-order bug is to ask in a process where the import has not happened — +which is why the guard below runs ``python -c ...`` rather than calling the +dialect in-process, and why the reproduction builds its own throwaway backend on +disk in a temporary directory instead of defining one here. +""" + +import re +import subprocess +import sys +import textwrap + +import pytest + +from rhosocial.activerecord.backend.dialect.mixins.data_type import DataTypeMixin +from rhosocial.activerecord.backend.expression.types import DataType + +_FORMAT_RE = re.compile(r"^format_data_type_([a-z][a-z0-9_]*)$") + +#: The core dialects and how to construct one, as ``(id, module, class)``. +_DIALECTS = ( + ("dummy", "rhosocial.activerecord.backend.impl.dummy.dialect", + "DummyDialect()"), + ("sqlite", "rhosocial.activerecord.backend.impl.sqlite.dialect", + "SQLiteDialect(version=(3, 45, 0))"), +) + +#: Asked of a fresh interpreter: import one module, nothing else, and report +#: which of the dialect's own formatter names failed to resolve. +_PROBE = textwrap.dedent(""" + import importlib, json, re, sys + + module_path, constructor = sys.argv[-2], sys.argv[-1] + module = importlib.import_module(module_path) + dialect = eval(constructor, vars(module)) + dialect_class = type(dialect) + declared = sorted( + match.group(1) for match in + (re.fullmatch(r"format_data_type_([a-z][a-z0-9_]*)", name) + for name in dir(dialect_class)) + if match + ) + mapping = dialect.supports_data_types() + print(json.dumps({ + "declared": declared, + "resolved": sorted(mapping), + "unresolved": [name for name in declared if name not in mapping], + "misnamed": sorted( + name for name, klass in mapping.items() + if getattr(klass, "name", None) != name + ), + "loaded": sorted( + klass.__module__ for klass in mapping.values() + ), + })) +""") + + +def _probe_in_fresh_interpreter(module_path, constructor): + """Ask a cold interpreter about one dialect; returns the parsed report.""" + import json + + result = subprocess.run( + [sys.executable, "-c", _PROBE, module_path, constructor], + capture_output=True, text=True, check=False, + ) + assert result.returncode == 0, ( + f"probe failed for {module_path}:\n{result.stdout}\n{result.stderr}" + ) + return json.loads(result.stdout.strip().splitlines()[-1]) + + +@pytest.mark.parametrize("dialect_id,module_path,constructor", _DIALECTS, + ids=[d[0] for d in _DIALECTS]) +def test_every_declared_formatter_resolves_on_a_cold_import( + dialect_id, module_path, constructor, +): + """The guard: nothing the dialect can render may vanish from the mapping. + + ``declared`` comes from the formatter family on the class and ``resolved`` + from ``supports_data_types()``. Anything in the first and not the second is a + name the dialect can render and cannot name — which is the bug, stated as a + test that cannot be passed by importing the missing classes first. + """ + report = _probe_in_fresh_interpreter(module_path, constructor) + assert report["declared"], f"{dialect_id}: must implement the format family" + assert not report["unresolved"], ( + f"{dialect_id}: these names have a format_data_type_ but no " + f"resolvable class, so supports_data_types() silently omits them: " + f"{report['unresolved']}. The lookup found no class because nothing " + f"imported the module it lives in." + ) + assert not report["misnamed"], ( + f"{dialect_id}: mapped classes must declare the key as their own name: " + f"{report['misnamed']}" + ) + assert report["declared"] == report["resolved"], ( + f"{dialect_id}: a dialect that renders a name must list it as supported" + ) + + +@pytest.mark.parametrize("dialect_id,module_path,constructor", _DIALECTS, + ids=[d[0] for d in _DIALECTS]) +def test_the_lookup_does_not_reach_into_another_backend(dialect_id, module_path, + constructor): + """Loading one dialect must not pull in a sibling's type classes. + + The core fix derives ``impl//expression/types.py`` from the backend + slug, so a mistake there would show up as one dialect importing another's + package. On a cold import of a core dialect nothing backend-specific should be + loaded at all. + """ + report = _probe_in_fresh_interpreter(module_path, constructor) + foreign = sorted({ + module for module in report["loaded"] + if ".impl." in module + and not module.startswith(module_path.rsplit(".dialect", 1)[0]) + }) + assert not foreign, f"{dialect_id}: loaded another backend's types: {foreign}" + + +def test_a_backend_type_nothing_has_imported_still_resolves(tmp_path): + """The reproduction, on a real backend-shaped package built for this test. + + ``impl/probebk/expression/types.py`` defines the class and + ``impl/probebk/dialect.py`` defines a dialect that renders it — and + deliberately does **not** import the type module, which is the mistake this + whole file is about. A fresh interpreter then asks the dialect for its + supported types. + + With the lookup walking only ``DataType.__subclasses__()``, ``probebk_widget`` + is missing from the answer and nothing says why. The fix resolves it by + importing the module the enforced ``_`` namespace rule already points + at, so the answer is complete without the dialect author having to remember. + """ + backend = "probebk" + package = tmp_path / backend + (package / "expression").mkdir(parents=True) + (package / "__init__.py").write_text("", encoding="utf-8") + (package / "expression" / "__init__.py").write_text("", encoding="utf-8") + (package / "expression" / "types.py").write_text(textwrap.dedent(""" + from rhosocial.activerecord.backend.expression.types import DataType + + + class ProbeBkWidgetType(DataType): + \"\"\"A backend type whose module the dialect does not import.\"\"\" + + name = "probebk_widget" + """), encoding="utf-8") + (package / "dialect.py").write_text(textwrap.dedent(""" + from typing import Tuple + + from rhosocial.activerecord.backend.dialect.mixins.data_type import ( + DataTypeMixin, + ) + + + class ProbeBkDialect(DataTypeMixin): + \"\"\"Declares a formatter for a class nothing here imports.\"\"\" + + name = "probebk" + + def format_data_type_probebk_widget(self, data_type) -> Tuple[str, tuple]: + return "WIDGET", () + """), encoding="utf-8") + + # The throwaway package has to be importable as + # ``rhosocial.activerecord.backend.impl.probebk``, so the real ``impl`` + # package is told where to look. Done in the child process only. + preamble = textwrap.dedent(""" + import sys + import rhosocial.activerecord.backend.impl as impl_package + impl_package.__path__.append(sys.argv[1]) + """) + env_path = tmp_path + report = _probe_with_preamble( + preamble, env_path, + f"rhosocial.activerecord.backend.impl.{backend}.dialect", + "ProbeBkDialect()", + ) + assert report["declared"] == ["probebk_widget"], report + assert not report["unresolved"], ( + "a cold import of the dialect lost probebk_widget from " + f"supports_data_types(): {report}" + ) + assert report["resolved"] == ["probebk_widget"] + + +def _probe_with_preamble(preamble, extra_argument, module_path, constructor): + """``_probe_in_fresh_interpreter`` with a script run before the import. + + The preamble reads its argument from ``sys.argv[1]``; ``_PROBE`` reads the + last two, so prepending one argument does not shift its own. + """ + import json + + result = subprocess.run( + [sys.executable, "-c", preamble + _PROBE, + str(extra_argument), module_path, constructor], + capture_output=True, text=True, check=False, + ) + assert result.returncode == 0, ( + f"probe failed for {module_path}:\n{result.stdout}\n{result.stderr}" + ) + return json.loads(result.stdout.strip().splitlines()[-1]) + + +def test_an_unknown_name_still_resolves_to_nothing(): + """The lookup has not become a guesser. + + A name no class claims and no backend prefix implies is ``None``, which is + what ``supports_data_types()`` uses to mean "this dialect does not render + that". + """ + from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect + + dialect = DummyDialect() + assert dialect._type_class_for("nosuchtype") is None + # A core-prefixed name is not a backend name, so no import is attempted. + assert dialect._type_class_for("jsonb") is not None + + +def test_a_formatters_own_annotation_is_where_the_class_comes_from(): + """The formatter's signature is the authoritative statement of what it serves. + + A throwaway dialect declares a formatter for a class and gets that class back + — without the lookup depending on which subclass the walk reached first, and + without consulting any table of names. + """ + from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect + from rhosocial.activerecord.backend.expression.types import JsonBType + + class AnnotatedDialect(DummyDialect): + """Renders a core concept, annotated with the class it renders.""" + + def format_data_type_annotated_widget(self, data_type: JsonBType): + return "WIDGET", () + + # The annotation's class does not declare the dispatch key, so it is not + # trusted for it — the name resolves to nothing, which is the honest answer. + assert AnnotatedDialect()._type_class_for("annotated_widget") is None + + # With the class's own name, the annotation is the answer. + class DeclaredNameDialect(DummyDialect): + def format_data_type_jsonb(self, data_type: JsonBType): + return "JSONB", () + + assert DeclaredNameDialect()._type_class_for("jsonb") is JsonBType + + +def test_the_mixin_is_what_provides_the_mapping(): + """Both core dialects resolve their mapping through ``DataTypeMixin``.""" + import importlib + + for _, module_path, constructor in _DIALECTS: + module = importlib.import_module(module_path) + dialect = eval(constructor, vars(module)) + dialect_class = type(dialect) + assert DataTypeMixin in dialect_class.__mro__ + assert dialect_class.supports_data_types is DataTypeMixin.supports_data_types + assert dialect_class._type_class_for is DataTypeMixin._type_class_for + + +def test_data_type_subclasses_are_reachable_without_a_registry(): + """The walk is still the last resort, and it is a walk, not a table.""" + # Built through ``type()`` with a namespaced module so it satisfies the + # namespace rule; the point is only that defining a class is enough to make + # it reachable, with nothing registering it anywhere. + Throwaway = type( + "Throwaway", + (DataType,), + { + "name": "dummy_throwaway_for_the_walk", + "__module__": "rhosocial.activerecord.backend.impl.dummy.expression.types", + "__qualname__": "Throwaway", + "__doc__": "Throwaway type for the subclass walk.", + }, + ) + assert Throwaway.name in {klass.name for klass in DataType.__subclasses__()} \ No newline at end of file diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_protocol_contracts.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_protocol_contracts.py index 966cc98fc..00b13e4e6 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_protocol_contracts.py +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_protocol_contracts.py @@ -4,16 +4,41 @@ Verifies the namespace rules and the naming-family discipline that the ``DataType`` / ``DataTypeSupport`` contracts formalize: -* ``format_data_type_*`` / ``supports_data_type_*`` 1:1 correspondence - (dummy dialect); +* **the formatter family is the support declaration** — no core dialect + carries a leftover ``supports_data_type_*`` probe, and the + ``supports_data_types()`` mapping is exactly the ``format_data_type_*`` + family, checked against **every** dialect this package can import rather + than one hand-picked pair; * ``supports_data_types()`` mapping shape — ``{generic name: concrete DataType class}`` with ``value.name == key``; +* **every core type is rendered or explicitly substituted** — a dialect must + take a position on each concept, and silence is not one; * core-defined types own **pure** generic names; * backend-defined types (SQLite impl) own **backend-prefixed** names; * honest-unsupported semantics: rendering a type the dialect does not implement raises ``TypeError`` — the dialect never fakes support. + +Expression ⇔ dialect correspondence (D9) +----------------------------------------- +The framework's model is an *expression* per SQL concept; each backend's +*dialect* decides how that concept is spelled in its own DDL. That pairing has +to be total, and in one of two ways: + +* **Rendered** — the dialect implements ``format_data_type_``, + which is the support declaration itself. This is the normal case. +* **Substituted** — the dialect cannot spell the concept, but it can say what + it stores instead, via ``suggested_data_types()[name] = SomeType``. This is + the honest answer for e.g. XML on SQLite (stored as text) and is *not* a + failure to implement. + +What is not allowed is a third state: a concept the dialect has never heard of, +where a caller who asks for it is told only that it is unsupported, with nothing +to go on. The two tests below close that gap — one checks the dialect's own +declarations are self-consistent, the other checks no core concept goes +undeclared. """ +import importlib import inspect import re @@ -31,6 +56,28 @@ _FORMAT_RE = re.compile(r"^format_data_type_([a-z][a-z0-9_]*)$") _SUPPORTS_RE = re.compile(r"^supports_data_type_([a-z][a-z0-9_]*)$") +#: Dialects this package can import without a live database connection, as +#: ``(id, "module.path", class name)``. A backend that is not installed is +#: skipped rather than failed: this package must stay runnable on its own. +_DIALECT_MODULES = ( + ("dummy", "rhosocial.activerecord.backend.impl.dummy.dialect", "DummyDialect"), + ("sqlite", "rhosocial.activerecord.backend.impl.sqlite.dialect", "SQLiteDialect"), +) + + +def _dialects(): + """Import each known dialect class, skipping the ones not installed.""" + found = [] + for dialect_id, module_path, class_name in _DIALECT_MODULES: + try: + module = importlib.import_module(module_path) + except ImportError: + continue + dialect_class = getattr(module, class_name, None) + if dialect_class is not None: + found.append((dialect_id, dialect_class)) + return found + def _concrete_subclasses(): """All concrete ``DataType`` subclasses currently loaded.""" @@ -45,62 +92,198 @@ def _concrete_subclasses(): return [klass for klass in seen if not inspect.isabstract(klass)] -def test_dummy_format_supports_correspondence(): - """Every ``format_data_type_X`` has a ``supports_data_type_X`` and vice versa.""" - format_names = set() - supports_names = set() - for member in dir(DummyDialect): - match = _FORMAT_RE.match(member) - if match: - format_names.add(match.group(1)) - continue - match = _SUPPORTS_RE.match(member) - if match: - supports_names.add(match.group(1)) - assert format_names, "dummy dialect must implement the format family" - assert supports_names, "dummy dialect must implement the supports family" - assert format_names == supports_names +def _core_type_classes(): + """Every concrete core ``DataType`` — the concepts the framework models.""" + return sorted( + ( + klass for klass in _concrete_subclasses() + if klass is not DataType + and klass.__module__.startswith(_CORE_TYPES_PREFIX) + ), + key=lambda klass: klass.name or "", + ) -def test_dummy_supports_data_types_mapping(): - """``supports_data_types()`` is ``{generic name: concrete DataType class}``.""" - dialect = DummyDialect() +@pytest.mark.parametrize("dialect_id,dialect_class", _dialects(), + ids=[d[0] for d in _dialects()]) +def test_the_formatter_family_is_the_support_declaration(dialect_id, dialect_class): + """Support is declared by the formatters; core keeps no ``supports_*`` probes. + + The ``supports_data_type_*`` family is retired in core: a + ``format_data_type_`` member *is* the declaration, and + ``supports_data_types()`` derives the mapping from it. A leftover probe + would be a second, easily-stale answer to the same question, so no core + dialect may carry one. The one direction that stays a lie when a + dialect keeps the pair anyway is a probe with no formatter behind it — + it promises a delivery that does not exist. + """ + format_names = { + _FORMAT_RE.match(member).group(1) + for member in dir(dialect_class) if _FORMAT_RE.match(member) + } + supports_names = { + _SUPPORTS_RE.match(member).group(1) + for member in dir(dialect_class) if _SUPPORTS_RE.match(member) + } + assert format_names, f"{dialect_id}: must implement the format family" + assert not supports_names, ( + f"{dialect_id}: the supports_data_type_* family is retired in core; " + f"declare support through the formatters instead: " + f"{sorted(supports_names)}" + ) + assert not (supports_names - format_names), ( + f"{dialect_id}: a probe with no formatter to back it: " + f"{sorted(supports_names - format_names)}" + ) + mapping = dialect_class().supports_data_types() + assert set(mapping) == format_names, ( + f"{dialect_id}: the mapping must be the format family exactly" + ) + + +@pytest.mark.parametrize("dialect_id,dialect_class", _dialects(), + ids=[d[0] for d in _dialects()]) +def test_supports_data_types_mapping_shape(dialect_id, dialect_class): + """``supports_data_types()`` is ``{generic name: concrete DataType class}``. + + A key with no class behind it would let a caller believe a type is + supported without any way to name it. + """ + dialect = dialect_class() mapping = dialect.supports_data_types() assert isinstance(mapping, dict) - assert mapping, "dummy dialect must support at least one type" + assert mapping, f"{dialect_id}: must support at least one type" for key, value in mapping.items(): - assert _NAME_RE.match(key), f"mapping key {key!r} must be a valid name" + assert _NAME_RE.match(key), f"{dialect_id}: key {key!r} is not a valid name" assert isinstance(value, type) and issubclass(value, DataType), \ - f"mapping value for {key!r} must be a DataType subclass" + f"{dialect_id}: value for {key!r} must be a DataType subclass" assert value.name == key, \ - f"mapping value {value.__name__}.name={value.name!r} != key {key!r}" - # The mapping must cover exactly the format-family names of the dialect. + f"{dialect_id}: {value.__name__}.name={value.name!r} != key {key!r}" format_names = { _FORMAT_RE.match(member).group(1) - for member in dir(DummyDialect) if _FORMAT_RE.match(member) + for member in dir(dialect_class) if _FORMAT_RE.match(member) } - assert set(mapping) == format_names + assert set(mapping) == format_names, ( + f"{dialect_id}: mapping and the format family disagree" + ) -def test_sqlite_format_supports_correspondence(): - """SQLite dialect: format family and supports family must correspond 1:1.""" - from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect - format_names = { - _FORMAT_RE.match(member).group(1) - for member in dir(SQLiteDialect) if _FORMAT_RE.match(member) - } - supports_names = { - _SUPPORTS_RE.match(member).group(1) - for member in dir(SQLiteDialect) if _SUPPORTS_RE.match(member) - } - assert format_names, "sqlite dialect must implement the format family" - assert supports_names, "sqlite dialect must implement the supports family" - assert format_names == supports_names, ( - f"format-only: {sorted(format_names - supports_names)}, " - f"supports-only: {sorted(supports_names - format_names)}" +@pytest.mark.parametrize("dialect_id,dialect_class", _dialects(), + ids=[d[0] for d in _dialects()]) +def test_every_core_type_is_rendered_or_suggested(dialect_id, dialect_class): + """No core concept goes undeclared by a dialect (D9). + + Each of the framework's modelled concepts must be either rendered by this + dialect or explicitly substituted by it. A concept the dialect has never + heard of leaves a caller with "unsupported" and nothing else — which is + indistinguishable from not having thought about it. + """ + dialect = dialect_class() + rendered = set(dialect.supports_data_types()) + suggested = dialect.suggested_data_types() + undeclared = [ + klass.name for klass in _core_type_classes() + if klass.name not in rendered and klass.name not in suggested + ] + assert not undeclared, ( + f"{dialect_id}: 这些核心类型既未渲染也未给出替代，必须显式表态: " + f"{sorted(undeclared)}" ) +@pytest.mark.parametrize("dialect_id,dialect_class", _dialects(), + ids=[d[0] for d in _dialects()]) +def test_the_default_spelling_always_renders(dialect_id, dialect_class): + """A type constructed the ordinary way must work on every dialect. + + ``BlobType(d)`` carries the default spelling ``"blob"``. If a dialect's + spelling check rejected it — because PostgreSQL writes ``BYTEA`` and has no + ``BLOB`` — then the type would be unconstructible on that backend and the + refusal would tell the caller nothing about how to proceed. So the rule is: + + * the concept's default spelling is always accepted; + * a dialect may *normalise* it to its own name, but not refuse it; + * a dialect may refuse the *other* spellings when the backend genuinely + does not write them. + + This is the difference between "I have no CLOB, here is why" and "your + request was malformed". Only the former is a useful answer. + """ + dialect = dialect_class() + for klass in _core_type_classes(): + spellings = klass.SPELLINGS + if not spellings: + continue + default = klass(dialect) + assert default.spelling == spellings[0], ( + f"{dialect_id}: {klass.__name__} default spelling " + f"{default.spelling!r} is not the first of SPELLINGS {spellings!r}" + ) + sql, _ = dialect.format_data_type(default) + assert sql, f"{dialect_id}: {klass.__name__} renders empty by default" + + +@pytest.mark.parametrize("dialect_id,dialect_class", _dialects(), + ids=[d[0] for d in _dialects()]) +def test_an_unsupported_spelling_is_refused_and_named(dialect_id, dialect_class): + """A spelling the backend does not write is an error, not a silent rewrite. + + The check has to happen in the formatter: a caller who asked for ``CLOB`` on + PostgreSQL should be told PostgreSQL has no CLOB, rather than handed a + ``TEXT`` and finding out later. + """ + dialect = dialect_class() + for klass in _core_type_classes(): + if klass.name not in dialect.supports_data_types(): + continue + for spelling in klass.SPELLINGS: + try: + dialect.format_data_type(klass(dialect, spelling=spelling)) + except TypeError as exc: + assert spelling in str(exc), ( + f"{dialect_id}: refusing {klass.__name__} spelling " + f"{spelling!r} must name the spelling, got: {exc}" + ) + except Exception: + # A limit (precision out of range, say) is a different failure. + pass + + +@pytest.mark.parametrize("dialect_id,dialect_class", _dialects(), + ids=[d[0] for d in _dialects()]) +def test_suggested_types_are_declared_and_disjoint(dialect_id, dialect_class): + """A suggested substitute must be a type this dialect really renders. + + Suggesting a class the backend has no formatter for would trade a clear + "not supported" for a worse "not supported" — one whose advice does not + work. Rendered and suggested keys are also disjoint by contract: a type + that is rendered needs no substitute, and listing both makes the intent + ambiguous. + + What is *not* required is that the substitute be constructible with no + arguments: PostgreSQL's stand-in for the generic ``EnumType`` is a named + type created by ``CREATE TYPE``, and that is precisely the information the + generic type does not carry. Such a substitute answers "which class on this + backend means the same thing", which is the question being asked. + """ + dialect = dialect_class() + supported = dialect.supports_data_types() + suggested = dialect.suggested_data_types() + + overlap = set(supported) & set(suggested) + assert not overlap, ( + f"{dialect_id}: 这些类型既渲染又建议替代: {sorted(overlap)}" + ) + + for key, substitute in sorted(suggested.items()): + assert isinstance(substitute, type) and issubclass(substitute, DataType), \ + f"{dialect_id}: suggested[{key!r}] must be a DataType subclass" + assert substitute.name in supported, ( + f"{dialect_id}: suggested[{key!r}] is {substitute.__name__}, " + f"whose name {substitute.name!r} this dialect does not render" + ) + + def test_sqlite_supports_data_types_mapping_merges_namespaces(): """SQLite mapping covers both generic and sqlite_-namespaced entries.""" from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect @@ -115,11 +298,7 @@ def test_sqlite_supports_data_types_mapping_merges_namespaces(): def test_core_type_names_are_pure(): """Concrete core types declare pure generic names (no backend prefix).""" - core_types_found = [ - klass for klass in _concrete_subclasses() - if klass is not DataType - and klass.__module__.startswith(_CORE_TYPES_PREFIX) - ] + core_types_found = _core_type_classes() assert core_types_found, "core type classes must be loaded" for klass in core_types_found: assert klass.name is not None, \ @@ -161,3 +340,321 @@ def test_unsupported_type_raises(): dialect = DummyDialect() with pytest.raises(TypeError): FakeZzzType(dialect).to_sql() + + +# --------------------------------------------------------------------------- +# Declared defaults: who owns the width a bare declaration means +# --------------------------------------------------------------------------- + + +class _DeclaresAVarcharWidth(DummyDialect): + """A server that supplies a width for the bare form of ``VARCHAR``. + + A subclass rather than a monkeypatch so the declaration is a real dialect + attribute, discoverable by exactly the lookup the mechanism performs. + """ + + def type_parameter_defaults(self): + return {"varchar": {"length": 255}} + + +def test_a_dialect_that_declares_nothing_leaves_the_bare_width_undeclared(): + """The default is "no default", and a backend need not supply a number. + + The dummy dialect renders a bare ``VARCHAR`` and parses it back with no + length, so the honest statement is that it supplies none — which it makes by + inheriting the empty answer. PostgreSQL is the case that matters: its + ``VARCHAR`` is unbounded, the catalog says ``atttypmod = -1``, and a value + written into core would make this claim the column is bounded. + """ + from rhosocial.activerecord.backend.expression.types import ( + CharType, + VarCharType, + ) + assert DummyDialect().type_parameter_defaults() == {} + dialect = DummyDialect() + assert VarCharType(dialect).length is None + assert CharType(dialect).length is None + + +def test_a_declared_width_lands_on_the_bare_declaration(): + """A supplied width becomes the value, so the two forms stop disagreeing. + + The defect this closes is not cosmetic: the schema differ compares a + declaration against what the catalog reported, so a bare ``VARCHAR`` that + renders ``VARCHAR(255)`` while carrying no length compares unequal to the + very column it produced. + """ + from rhosocial.activerecord.backend.expression.types import ( + CharType, + VarCharType, + ) + dialect = _DeclaresAVarcharWidth() + assert VarCharType(dialect).length == 255 + # and the declared form is now the catalog's form + assert VarCharType(dialect) == dialect.parse_type("VARCHAR(255)") + # a concept the server says nothing about is untouched + assert CharType(dialect).length is None + + +def test_a_declared_length_does_not_override_a_declared_one(): + """The server's default fills an absent width and nothing else.""" + from rhosocial.activerecord.backend.expression.types import VarCharType + dialect = _DeclaresAVarcharWidth() + assert VarCharType(dialect, length=50).length == 50 + + +def test_the_width_is_resolved_when_the_dialect_is_bound_later(): + """Deferred binding resolves the same way, because the lookup is at read time. + + Model definitions are built before a dialect exists and bound afterwards, so + resolving in ``__init__`` would silently leave every such type undeclared. + """ + from rhosocial.activerecord.backend.expression.types import VarCharType + dialect = _DeclaresAVarcharWidth() + deferred = VarCharType() + assert deferred.length is None # no server yet: nothing to resolve + deferred.dialect = dialect + assert deferred.length == 255 + assert deferred == VarCharType(dialect) + + +def test_an_unbound_width_never_raises(): + """Resolution cannot fail, so comparing an unbound type still answers. + + ``None`` means "this server supplies nothing" for a dialect with no + declaration and for no dialect at all. A width that raised when it could not + be looked up would make ordinary construction and equality raise, which is a + worse defect than the asymmetry it was meant to fix. + """ + from rhosocial.activerecord.backend.expression.types import VarCharType + unbound = VarCharType() + assert unbound == VarCharType() + assert hash(unbound) == hash(VarCharType()) + assert repr(unbound) == "VarCharType(None,)" + assert VarCharType(None).length is None + + +def test_an_object_with_no_declaration_hook_is_read_as_declaring_nothing(): + """The hook is looked up, not demanded, so a dialect without it still answers. + + This is why the hook is deliberately not a member of ``DataTypeSupport``: + adding it there would make every dialect implement it just to keep passing + ``isinstance``, which is the "every backend must supply a number" shape the + design refuses. + """ + from rhosocial.activerecord.backend.expression.types._defaults import ( + declared_parameter, + ) + assert declared_parameter("varchar", "length", None) is None + assert declared_parameter("varchar", "length", object()) is None + assert declared_parameter("varchar", "length", _DeclaresAVarcharWidth()) == 255 + # a declared parameter the concept does not have is still just a lookup miss + assert declared_parameter("varchar", "precision", _DeclaresAVarcharWidth()) is None + assert declared_parameter("char", "length", _DeclaresAVarcharWidth()) is None + + +def test_a_backend_type_declares_under_its_own_name(): + """Keying on ``name`` keeps a concept's two classes from inheriting one answer. + + ``SQLServerNVarCharMaxType`` is a :class:`VarCharType` that means *unbounded*, + not *undeclared*, so it must not pick up the ``varchar`` width. Nothing + exempts it: it declares nothing under its own ``name``, which is the ordinary + answer for a concept whose bare form has no width. + + Both classes are built through ``type()`` with a backend-namespaced module + path and a ``dummy_`` prefixed name, for the same reason + ``test_unsupported_type_raises`` builds its throwaway that way: that is what + a real backend-defined subclass looks like to the naming enforcement. + """ + def _backend_type(class_name, generic_name): + return type(class_name, (VarCharType,), { + "name": generic_name, + "__module__": "rhosocial.activerecord.backend.impl.dummy.expression.types", + "__qualname__": class_name, + }) + + from rhosocial.activerecord.backend.expression.types import VarCharType + bounded = _backend_type("BoundedString", "dummy_bounded_string") + unbounded = _backend_type("UnboundedString", "dummy_unbounded_string") + + # a dialect that has said nothing about either name supplies neither + dialect = _DeclaresAVarcharWidth() + assert bounded(dialect).length is None + + # and says so by declaring under the backend type's own name + class _AlsoDeclaresTheBackendType(DummyDialect): + def type_parameter_defaults(self): + return {"varchar": {"length": 255}, + "dummy_bounded_string": {"length": 255}} + + # the class that means *unbounded* still declares nothing, and still says it + # by being absent — it never inherits the bounded answer through inheritance + assert bounded(_AlsoDeclaresTheBackendType()).length == 255 + assert unbounded(_AlsoDeclaresTheBackendType()).length is None + + +def test_the_declaration_is_not_a_type_and_stays_off_the_dispatch(): + """``type_parameter_defaults`` is a dialect fact, not a type, and not a hook + the format/supports correspondence can trip over. + + The supported-types surface is the ``format_data_type_`` naming + family, scanned by ``dir()``; a declaration must not add to it or + rename a concept's dispatch key. + """ + dialect = _DeclaresAVarcharWidth() + mapping = dialect.supports_data_types() + assert "type_parameter_defaults" not in mapping + assert "varchar" in mapping + assert not any("default" in name for name in mapping) + + +class _DeclaresNumericDefaults(DummyDialect): + """A server that supplies a precision — and a scale — for the bare form. + + The pair is Snowflake's documented ``NUMBER(38, 0)`` and the precision is + Oracle's documented ``FLOAT`` default of 126, so one stub exercises both + shapes the mechanism has to carry: a concept with two resolvable parameters + (:class:`DecimalType`) and a concept with one (:class:`FloatType`). A + subclass rather than a monkeypatch for the same reason as + :class:`_DeclaresAVarcharWidth`. + """ + + def type_parameter_defaults(self): + return { + "decimal": {"precision": 38, "scale": 0}, + "float": {"precision": 126}, + } + + +def test_a_declared_numeric_default_lands_on_the_bare_declaration(): + """A supplied precision and scale become the values, so the two forms stop + disagreeing. + + The same defect the width case has, one parameter over: the schema differ + compares a declaration against what the catalog reported, so a bare + ``DecimalType`` that renders ``NUMBER(38, 0)`` while carrying no precision + compares unequal to the very column it produced — and on Snowflake that + bare declaration *is* the column ``NUMBER(38, 0)``. + """ + from rhosocial.activerecord.backend.expression.types import ( + DecimalType, + FloatType, + ) + dialect = _DeclaresNumericDefaults() + assert DecimalType(dialect).precision == 38 + assert DecimalType(dialect).scale == 0 + assert FloatType(dialect).precision == 126 + + +def test_a_resolved_numeric_default_compares_equal_to_the_declared_form(): + """``==`` and ``__hash__`` read the properties, so resolution reaches the differ. + + "Nothing declared" and "the server's own value" are one column, and the + value-object machinery is what says so: both spellings resolve to the same + identity, so they compare equal and hash equal. + """ + from rhosocial.activerecord.backend.expression.types import ( + DecimalType, + FloatType, + ) + dialect = _DeclaresNumericDefaults() + assert DecimalType(dialect) == DecimalType(dialect, precision=38, scale=0) + assert hash(DecimalType(dialect)) == hash( + DecimalType(dialect, precision=38, scale=0) + ) + assert FloatType(dialect) == FloatType(dialect, precision=126) + assert hash(FloatType(dialect)) == hash(FloatType(dialect, precision=126)) + + +def test_the_scale_resolves_even_when_the_precision_was_declared(): + """A per-parameter lookup, not an all-or-nothing pair. + + On Snowflake ``NUMBER(10)`` is ``NUMBER(10, 0)``: the scale has its own + documented default and the server stores one whatever the declaration said. + Filling only the precision would leave the precision-only declaration + comparing unequal to the column it produced — the same defect one parameter + over — which is why ``type_parameter_defaults`` is keyed per parameter. + """ + from rhosocial.activerecord.backend.expression.types import DecimalType + dialect = _DeclaresNumericDefaults() + assert DecimalType(dialect, precision=10).scale == 0 + assert DecimalType(dialect, precision=10) == DecimalType( + dialect, precision=10, scale=0 + ) + + +def test_a_declared_numeric_value_is_not_overridden(): + """The server's default fills an absent value and nothing else.""" + from rhosocial.activerecord.backend.expression.types import ( + DecimalType, + FloatType, + ) + dialect = _DeclaresNumericDefaults() + assert DecimalType(dialect, precision=10, scale=2).identity()[:2] == (10, 2) + assert FloatType(dialect, precision=53).precision == 53 + + +def test_a_numeric_default_is_resolved_when_the_dialect_is_bound_later(): + """Deferred binding resolves the same way, because the lookup is at read time. + + Model definitions are built before a dialect exists and bound afterwards, so + resolving in ``__init__`` would silently leave every such type undeclared. + """ + from rhosocial.activerecord.backend.expression.types import ( + DecimalType, + FloatType, + ) + dialect = _DeclaresNumericDefaults() + deferred = DecimalType() + assert deferred.precision is None + assert deferred.scale is None + deferred.dialect = dialect + assert deferred.precision == 38 + assert deferred.scale == 0 + assert deferred == DecimalType(dialect) + deferred_float = FloatType() + assert deferred_float.precision is None + deferred_float.dialect = dialect + assert deferred_float.precision == 126 + assert deferred_float == FloatType(dialect) + + +def test_a_dialect_less_numeric_type_stays_undeclared(): + """There is no server to ask, so the honest answer is ``None``. + + This is the invariant the rest of the framework leans on — types are built + and compared long before a connection exists — and it is the one + ``test_data_types.py::test_the_other_fields_are_untouched`` pins for the + same classes. Resolution must not raise and must not invent a number. + """ + from rhosocial.activerecord.backend.expression.types import ( + DecimalType, + FloatType, + ) + assert DecimalType().precision is None + assert DecimalType().scale is None + assert FloatType().precision is None + assert DecimalType() == DecimalType() + assert hash(FloatType()) == hash(FloatType()) + + +def test_serialization_records_the_resolved_numeric_default(): + """``get_params`` is the one serialization surface, and it reads the property. + + For a dialect-bound bare declaration that means the recorded values are the + ones the server supplies, not ``None``: the dialect itself is deliberately + not serialized (it is resupplied at deserialization), so the snapshot the + parameters carry is the declaration as this server resolved it. + """ + from rhosocial.activerecord.backend.expression.types import ( + DecimalType, + FloatType, + ) + dialect = _DeclaresNumericDefaults() + assert DecimalType(dialect).get_params()["precision"] == 38 + assert DecimalType(dialect).get_params()["scale"] == 0 + assert FloatType(dialect).get_params()["precision"] == 126 + # An unbound instance records the declaration as written, which is ``None``. + assert DecimalType().get_params()["precision"] is None + diff --git a/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_spelling_parse.py b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_spelling_parse.py new file mode 100644 index 000000000..3879fbe6e --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_spelling_parse.py @@ -0,0 +1,312 @@ +# tests/rhosocial/activerecord_test/feature/backend/dummy2/test_type_spelling_parse.py +"""``parse_type`` must cover every spelling and be canonical (D8). + +Two rules, and they are the reason this file exists. + +**Coverage.** Every entry of every core ``SPELLINGS`` tuple is a name the +framework itself claims to understand. A ``parse_type`` that answers +``CustomType`` for one of them is saying "I have no type called ``int1``" — and +then writing the raw text back, which is what a ``CustomType`` does. That is +worse than useless on a column the framework declared itself: introspection +reports a name the framework owns as a vendor-specific type. + +**Canonicality.** One concept in, exactly one class out, carrying the spelling it +was written with. Not two spellings of one type coming back as two classes (a +second class per synonym is exactly what ``SPELLINGS`` exists to prevent), and +not ``character varying`` — variable length — coming back as the fixed-length +type, which would make the differ report a change that is not there. + +Both rules are checked here over **every** core spelling on **every** core +dialect, by walking the classes rather than a hand-written list, so a new +concept with a new spelling cannot be added without this test noticing. +""" + +import inspect + +import pytest + +from rhosocial.activerecord.backend.expression.types import ( + BigIntType, + BooleanType, + CharType, + CustomType, + DataType, + DecimalType, + DoubleType, + IntegerType, + SmallIntType, + TextType, + TinyIntType, + VarCharType, +) + +_CORE_TYPES_PREFIX = "rhosocial.activerecord.backend.expression.types" + +#: The core dialects, by id. Both ship in this package and neither needs a +#: connection, so a coverage rule stated here is stated about core rather than +#: about one backend's opinion. +_DIALECTS = { + "dummy": "rhosocial.activerecord.backend.impl.dummy.dialect:DummyDialect", + "sqlite": "rhosocial.activerecord.backend.impl.sqlite.dialect:SQLiteDialect", +} + +#: SQLite stores by *affinity*, not by type name, so several concepts collapse +#: into one stored class — and they must, because the database does not tell them +#: apart. This is the one place a core dialect's answer to a spelling is not the +#: concept class, and it is stated rather than inferred so that a new collapse +#: has to be declared here: +#: +#: ``INTEGER`` affinity — INT, TINYINT, SMALLINT, BIGINT, INT1: one cell. +#: ``TEXT`` affinity — TEXT, CHAR, VARCHAR, CHARACTER VARYING, CLOB: one +#: cell, so a fixed-length and a variable-length +#: declaration are the same column to SQLite. +#: ``REAL`` affinity — REAL, FLOAT, DOUBLE, DOUBLE PRECISION: one cell. +#: ``NUMERIC`` affinity — DECIMAL, NUMERIC, DEC, BOOLEAN, BOOL and the +#: temporal types: one cell. +#: +#: ``SQLiteNumericType`` derives from no core concept, because that affinity +#: spans three families at once; what it *is* here is the storage each of those +#: concepts has on this backend, which is the only thing a parse of a spelling +#: can honestly be. +_AFFINITY_STORAGE = { + "sqlite": (), +} + + +def _dialects(): + """``{id: dialect instance}`` for every core dialect that imports.""" + import importlib + + found = {} + for dialect_id, target in _DIALECTS.items(): + module_path, class_name = target.split(":") + module = importlib.import_module(module_path) + dialect_class = getattr(module, class_name) + found[dialect_id] = ( + dialect_class() if dialect_id == "dummy" + else dialect_class(version=(3, 45, 0)) + ) + return found + + +def _sqlite_affinity_classes(): + """``{core name: the SQLite class that stands in for it}``, declared here + rather than discovered, because the affinity model is a fact about SQLite + and not something a lookup should be able to change silently.""" + from rhosocial.activerecord.backend.impl.sqlite.expression import types as sq + + return { + IntegerType.name: sq.SQLiteIntegerType, + TinyIntType.name: sq.SQLiteIntegerType, + SmallIntType.name: sq.SQLiteIntegerType, + BigIntType.name: sq.SQLiteIntegerType, + CharType.name: sq.SQLiteTextType, + VarCharType.name: sq.SQLiteTextType, + TextType.name: sq.SQLiteTextType, + DoubleType.name: sq.SQLiteRealType, + DecimalType.name: sq.SQLiteNumericType, + BooleanType.name: sq.SQLiteNumericType, + } + + +#: Per dialect, the extra classes a concept may legitimately parse to because +#: that backend's storage collapses them. Empty for a dialect that keeps the +#: concepts apart. +_COLLAPSED_STORAGE = {"sqlite": _sqlite_affinity_classes(), "dummy": {}} + + +def _concrete_core_types(): + """Every concrete core ``DataType`` — the concepts the framework models.""" + seen = set() + stack = [DataType] + while stack: + klass = stack.pop() + if klass in seen: + continue + seen.add(klass) + stack.extend(klass.__subclasses__()) + return sorted( + ( + klass for klass in seen + if not inspect.isabstract(klass) + and klass.__module__.startswith(_CORE_TYPES_PREFIX) + ), + key=lambda klass: klass.name or "", + ) + + +def _spellings(): + """``(concept, spelling)`` for every entry of every core ``SPELLINGS``.""" + return [ + (klass, spelling) + for klass in _concrete_core_types() + for spelling in klass.SPELLINGS + ] + + +def _cases(): + return [ + (klass.__name__, spelling) + for klass, spelling in _spellings() + ] + + +_DIALECT_IDS = sorted(_DIALECTS) +_CASES = _cases() +_COLLAPSED_IDS = sorted(_COLLAPSED_STORAGE) + + +def test_the_walk_finds_every_spellinged_core_type(): + """The enumeration this file rests on must not be vacuous. + + If a new core type declared a spelling and this walk stopped finding it, the + tests below would pass while checking nothing. + """ + concepts = {klass for klass, _ in _spellings()} + assert len(concepts) >= 11, ( + f"expected the eleven synonym-bearing core types, found " + f"{sorted(k.__name__ for k in concepts)}" + ) + assert len(_CASES) > len(concepts), "a concept must contribute its other spellings too" + for concept in concepts: + assert concept.SPELLINGS[0] == concept.name or concept.SPELLINGS, ( + f"{concept.__name__}: SPELLINGS should list the canonical spelling " + f"first, got {concept.SPELLINGS!r}" + ) + + +@pytest.mark.parametrize("dialect_id", _DIALECT_IDS) +@pytest.mark.parametrize("concept_name,spelling", _CASES, + ids=[f"{c}-{s}" for c, s in _CASES]) +def test_every_spelling_is_recognised(dialect_id, concept_name, spelling): + """A name in a core ``SPELLINGS`` tuple is never an unrecognised type. + + ``CustomType`` means "the framework has no class for this name", and it + renders the raw text back. For ``INT1`` — which ``TinyIntType`` declares — that + turns a type the framework owns into a vendor-specific one on every + introspection round trip. + """ + dialect = _dialects()[dialect_id] + parsed = dialect.parse_type(spelling.upper()) + assert not isinstance(parsed, CustomType), ( + f"{dialect_id}: {concept_name} spells itself {spelling!r} and this " + f"dialect parsed it as an unrecognised type ({parsed.raw!r}). Every " + f"entry of every core SPELLINGS must parse to a type." + ) + + +@pytest.mark.parametrize("dialect_id", _DIALECT_IDS) +@pytest.mark.parametrize("concept_name,spelling", _CASES, + ids=[f"{c}-{s}" for c, s in _CASES]) +def test_every_spelling_reaches_its_own_concept(dialect_id, concept_name, spelling): + """The parse lands on this concept, or on the storage this dialect uses for it. + + Not "some type in the same family": the concept itself, except where a + dialect's storage genuinely cannot tell two concepts apart — and then only + for the collapses declared in ``_COLLAPSED_STORAGE``. + """ + concept = next(k for k, _ in _spellings() if k.__name__ == concept_name) + dialect = _dialects()[dialect_id] + parsed = dialect.parse_type(spelling.upper()) + collapsed = _COLLAPSED_STORAGE[dialect_id] + allowed = tuple( + klass for name, klass in collapsed.items() if name == concept.name + ) + assert isinstance(parsed, concept) or type(parsed) in allowed, ( + f"{dialect_id}: {concept_name} spelled {spelling!r} parsed as " + f"{type(parsed).__name__}, which is neither the concept nor a storage " + f"class this dialect declares for it" + ) + + +@pytest.mark.parametrize("dialect_id", _DIALECT_IDS) +@pytest.mark.parametrize("concept_name", sorted({c for c, _ in _CASES})) +def test_spellings_of_one_concept_parse_to_one_class(dialect_id, concept_name): + """Two spellings of one type must not come back as two classes. + + That is the whole reason ``SPELLINGS`` is a tuple on the class: a second + class per synonym would make ``parse_type`` disagree with itself about what a + column is, and the differ would report a change on a column nobody touched. + """ + dialect = _dialects()[dialect_id] + parsed = [ + type(dialect.parse_type(spelling.upper())) + for concept, spelling in _spellings() + if concept.__name__ == concept_name + ] + assert len(set(parsed)) == 1, ( + f"{dialect_id}: {concept_name} parses to {sorted(k.__name__ for k in set(parsed))}" + ) + + +@pytest.mark.parametrize("dialect_id", _COLLAPSED_IDS) +def test_character_varying_is_never_the_fixed_length_type(dialect_id): + """``CHARACTER VARYING`` is the variable-length concept, not ``CHAR``. + + Both spellings start with ``CHARACTER``, so a parser that matches the prefix + and stops gets this wrong for one of the two — and the two are different + storage, so the error is a false schema change rather than a cosmetic one. + """ + dialect = _dialects()[dialect_id] + varying = dialect.parse_type("CHARACTER VARYING") + fixed = dialect.parse_type("CHARACTER") + assert not isinstance(varying, CharType), ( + f"{dialect_id}: 'character varying' parsed as the fixed-length " + f"{type(varying).__name__}" + ) + assert not isinstance(fixed, VarCharType), ( + f"{dialect_id}: 'character' parsed as the variable-length " + f"{type(fixed).__name__}" + ) + + +def test_dummy_carries_the_spelling_it_was_parsed_from(): + """A dialect that keeps the concepts apart reports the spelling it read. + + ``spelling`` is deliberately not part of a type's identity, but it is how the + type was written, and the formatters read it: a parser that dropped it would + silently turn a caller's ``bool`` into a ``boolean`` request. + """ + dialect = _dialects()["dummy"] + for concept, spelling in _spellings(): + parsed = dialect.parse_type(spelling.upper()) + assert getattr(parsed, "spelling", None) == spelling, ( + f"{concept.__name__}: parsed from {spelling!r} as " + f"{type(parsed).__name__}(spelling={getattr(parsed, 'spelling', None)!r})" + ) + + +def test_a_number_the_type_cannot_carry_is_not_silently_dropped(): + """``INT(11)`` is a display width no core type models, so it is not ``INT``. + + Reporting it as ``IntegerType`` would claim the width is gone; reporting it as + the raw text says what it is and lets the caller decide. + """ + dialect = _dialects()["dummy"] + parsed = dialect.parse_type("INT(11)") + assert isinstance(parsed, CustomType) + assert parsed.raw == "INT(11)" + + +def test_sqlite_keeps_affinity_parsing_and_now_covers_the_core_spellings(): + """SQLite parses by affinity, and every core spelling finds its affinity. + + The affinity classes are the honest answer for a backend that stores by + affinity — but the four spellings that used to miss every group and fall + through to ``CustomType`` (``INT1``, ``CHARACTER``, ``DEC``, ``BOOL``) now + reach the affinity SQLite has always given them. + """ + dialect = _dialects()["sqlite"] + from rhosocial.activerecord.backend.impl.sqlite.expression import types as sq + + for raw, expected in ( + ("INT1", sq.SQLiteIntegerType), + ("CHARACTER", sq.SQLiteTextType), + ("DEC", sq.SQLiteNumericType), + ("BOOL", sq.SQLiteNumericType), + ("DOUBLE PRECISION", sq.SQLiteRealType), + ("BYTEA", sq.SQLiteBlobType), + ): + assert type(dialect.parse_type(raw)) is expected, ( + f"sqlite: {raw!r} should parse to {expected.__name__}" + ) \ No newline at end of file diff --git a/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_cli.py b/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_cli.py index 1ee1eb67d..3aed3898a 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_cli.py +++ b/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_cli.py @@ -280,7 +280,13 @@ def test_example_query_not_found(self, capsys): class TestHandleNamedExpressionDescribe: """Tests for handle_named_expression with --describe option.""" - def test_describe_query(self): + def test_describe_query(self, capsys): + """--describe against a module pre-registered in sys.modules. + + test_describe_with_params patches importlib.import_module instead, so + between them the real and the mocked resolver import paths are both + exercised. + """ args = Namespace( qualified_name="test_describe_module.active_users", example=None, @@ -313,14 +319,52 @@ def active_users(dialect, limit: int = 100): lambda x: None, lambda a, b, c: None, ) + captured = capsys.readouterr() + assert "Expression: test_describe_module.active_users" in captured.out + assert "Parameters (excluding 'dialect'):" in captured.out finally: del sys.modules["test_describe_module"] + def test_describe_with_params(self, capsys): + args = Namespace( + qualified_name="test_queries.active_users", + example=None, + params=[], + describe=True, + dry_run=False, + list_queries=False, + force=False, + explain=False, + rich_ascii=False, + is_async=False, + ) + + module = types.ModuleType("test_queries") + + def active_users(dialect, limit: int = 100, offset: int = 0): + pass + + module.active_users = active_users + + with patch("importlib.import_module", return_value=module): + handle_named_expression( + args, + _PROVIDER, + backend_factory=lambda: None, + get_dialect=lambda b: None, + execute_query=lambda s, p, st: None, + ) + captured = capsys.readouterr() + assert "limit" in captured.out + assert "offset" in captured.out + assert "Parameters" in captured.out + class TestHandleNamedExpressionExecute: - """Tests for normal query execution.""" + """Tests for handle_named_expression execute mode.""" def test_execute_error_handling(self, capsys): + """A backend factory that raises must exit 1, not propagate.""" args = Namespace( qualified_name="test_queries.active_users", example=None, @@ -336,7 +380,7 @@ def test_execute_error_handling(self, capsys): def fail_backend_factory(): raise RuntimeError("Connection failed") - with pytest.raises(SystemExit): + with pytest.raises(SystemExit) as exc_info: handle_named_expression( args, _PROVIDER, @@ -345,6 +389,94 @@ def fail_backend_factory(): lambda a, b, c: None, ) + assert exc_info.value.code == 1 + + def test_execute_dry_run(self, capsys): + args = Namespace( + qualified_name="test_queries.active_users", + example=None, + params=[], + describe=False, + dry_run=True, + list_queries=False, + force=False, + explain=False, + rich_ascii=False, + is_async=False, + ) + + module = types.ModuleType("test_queries") + + def active_users(dialect, limit: int = 100): + return QueryExpression(dialect, [Literal(dialect, 1)]) + + module.active_users = active_users + + with patch("importlib.import_module", return_value=module): + handle_named_expression( + args, + _PROVIDER, + backend_factory=lambda: SimpleNamespace(dialect=_DIALECT), + get_dialect=lambda b: b.dialect, + execute_query=lambda s, p, st: None, + ) + captured = capsys.readouterr() + assert "DRY RUN" in captured.out + + def test_execute_with_params(self, capsys): + args = Namespace( + qualified_name="test_queries.active_users", + example=None, + params=["limit=50"], + describe=False, + dry_run=True, + list_queries=False, + force=False, + explain=False, + rich_ascii=False, + is_async=False, + ) + + module = types.ModuleType("test_queries") + + def active_users(dialect, limit: int = 100): + return QueryExpression(dialect, [Literal(dialect, 1)]) + + module.active_users = active_users + + with patch("importlib.import_module", return_value=module): + handle_named_expression( + args, + _PROVIDER, + backend_factory=lambda: SimpleNamespace(dialect=_DIALECT), + get_dialect=lambda b: b.dialect, + execute_query=lambda s, p, st: None, + ) + captured = capsys.readouterr() + assert "DRY RUN" in captured.out + + def test_execute_missing_qualified_name(self): + args = Namespace( + qualified_name=None, + example=None, + params=[], + describe=False, + dry_run=False, + list_queries=False, + force=False, + explain=False, + rich_ascii=False, + is_async=False, + ) + with pytest.raises(SystemExit): + handle_named_expression( + args, + _PROVIDER, + backend_factory=lambda: SimpleNamespace(dialect="placeholder"), + get_dialect=lambda b: b.dialect, + execute_query=lambda s, p, st: None, + ) + class TestHandleNamedExpressionExecuteForce: """Tests for handle_named_expression with --force option.""" @@ -705,134 +837,6 @@ def test_explain_flag(self): assert args.explain is True -class TestHandleNamedExpressionExecute: # noqa: F811 - """Tests for handle_named_expression execute mode.""" - - def test_execute_dry_run(self, capsys): - args = Namespace( - qualified_name="test_queries.active_users", - example=None, - params=[], - describe=False, - dry_run=True, - list_queries=False, - force=False, - explain=False, - rich_ascii=False, - is_async=False, - ) - - module = types.ModuleType("test_queries") - - def active_users(dialect, limit: int = 100): - return QueryExpression(dialect, [Literal(dialect, 1)]) - - module.active_users = active_users - - with patch("importlib.import_module", return_value=module): - handle_named_expression( - args, - _PROVIDER, - backend_factory=lambda: SimpleNamespace(dialect=_DIALECT), - get_dialect=lambda b: b.dialect, - execute_query=lambda s, p, st: None, - ) - captured = capsys.readouterr() - assert "DRY RUN" in captured.out - - def test_execute_with_params(self, capsys): - args = Namespace( - qualified_name="test_queries.active_users", - example=None, - params=["limit=50"], - describe=False, - dry_run=True, - list_queries=False, - force=False, - explain=False, - rich_ascii=False, - is_async=False, - ) - - module = types.ModuleType("test_queries") - - def active_users(dialect, limit: int = 100): - return QueryExpression(dialect, [Literal(dialect, 1)]) - - module.active_users = active_users - - with patch("importlib.import_module", return_value=module): - handle_named_expression( - args, - _PROVIDER, - backend_factory=lambda: SimpleNamespace(dialect=_DIALECT), - get_dialect=lambda b: b.dialect, - execute_query=lambda s, p, st: None, - ) - captured = capsys.readouterr() - assert "DRY RUN" in captured.out - - def test_execute_missing_qualified_name(self): - args = Namespace( - qualified_name=None, - example=None, - params=[], - describe=False, - dry_run=False, - list_queries=False, - force=False, - explain=False, - rich_ascii=False, - is_async=False, - ) - with pytest.raises(SystemExit): - handle_named_expression( - args, - _PROVIDER, - backend_factory=lambda: SimpleNamespace(dialect="placeholder"), - get_dialect=lambda b: b.dialect, - execute_query=lambda s, p, st: None, - ) - - -class TestHandleNamedExpressionDescribe: # noqa: F811 - """Tests for handle_named_expression --describe mode.""" - - def test_describe_with_params(self, capsys): - args = Namespace( - qualified_name="test_queries.active_users", - example=None, - params=[], - describe=True, - dry_run=False, - list_queries=False, - force=False, - explain=False, - rich_ascii=False, - is_async=False, - ) - - module = types.ModuleType("test_queries") - - def active_users(dialect, limit: int = 100, offset: int = 0): - pass - - module.active_users = active_users - - with patch("importlib.import_module", return_value=module): - handle_named_expression( - args, - _PROVIDER, - backend_factory=lambda: None, - get_dialect=lambda b: None, - execute_query=lambda s, p, st: None, - ) - captured = capsys.readouterr() - assert "limit" in captured.out - assert "offset" in captured.out - assert "Parameters" in captured.out - - class TestHandleNamedExpressionWithCreateDialect: """Tests for create_dialect in handle_named_expression.""" diff --git a/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_cli_procedure.py b/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_cli_procedure.py index 098cd958c..fba360c91 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_cli_procedure.py +++ b/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_cli_procedure.py @@ -277,8 +277,14 @@ def test_dry_run_procedure(self, mock_dialect): class TestHandleNamedProcedureExecute: """Tests for handle_named_procedure normal execution.""" - def test_execute_procedure_success(self, mock_dialect): - """Test executing a procedure successfully.""" + def test_execute_procedure_success(self, capsys): + """A procedure that does not abort completes and exits 0. + + The complement of test_abort_procedure: that one drives the same path + with ``aborted=True`` and asserts SystemExit(1), this one with the + default ``aborted=False`` and asserts the success print and that no + exit happened at all. + """ provider = ProviderMock() args = TestCliProcedureArgs.create( @@ -296,26 +302,32 @@ def test_execute_procedure_success(self, mock_dialect): mock_result.logs = [] mock_runner = MagicMock() + # handle_named_procedure resolves the runner as + # ProcedureRunner(name).load(), so the mock has to chain through load + # before run() is reachable. Wiring only mock_runner.run leaves the + # handler talking to mock_runner.load.return_value.run() -- a fresh + # MagicMock whose truthy .aborted makes the handler exit 1. + mock_runner.load.return_value = mock_runner mock_runner.run.return_value = mock_result backend = None - def get_dialect(b): - return mock_dialect - with patch( "rhosocial.activerecord.backend.named_expression.cli_procedure.ProcedureRunner", return_value=mock_runner, ): - try: - handle_named_procedure( - args, - provider, - lambda: backend, - disconnect=lambda: None, - ) - except SystemExit: - pass + handle_named_procedure( + args, + provider, + lambda: backend, + disconnect=lambda: None, + ) + + mock_runner.run.assert_called_once() + # --param KEY=VALUE reaches the runner as a parsed dict, not as the + # raw string list argparse produced. + assert mock_runner.run.call_args.args[1] == {"name": "World"} + assert "[OK] Procedure completed." in capsys.readouterr().out class TestHandleNamedProcedureAbort: @@ -440,8 +452,16 @@ def test_parse_multiple_params(self): assert user_params == {"month": "2026-03", "threshold": "100", "name": "test"} -class TestHandleNamedProcedureExecute: # noqa: F811 - """Tests for handle_named_procedure execution paths.""" +class TestNamedProcedureCliSurface: + """Parser-choice and namespace round-trip checks. + + These were filed under ``TestHandleNamedProcedureExecute``, shadowing the + class of that name and so becoming the only tests collected under it. None + of them exercise execution: three re-check the ``--transaction`` choices + that ``TestTransactionModeChoices`` already covers (differing only in the + positional argument argparse ignores), and three assert that + ``argparse.Namespace`` hands back the kwargs it was built from. + """ def test_parser_transaction_auto(self): """Test parser accepts --transaction auto.""" diff --git a/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_resolver.py b/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_resolver.py index f67f11563..85c765067 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_resolver.py +++ b/tests/rhosocial/activerecord_test/feature/backend/named_expression/test_resolver.py @@ -344,7 +344,16 @@ def test_resolve_module_not_found(self): class TestClassifyProbeUtilities: - """Tests for internal _classify and _probe_tags utilities.""" + """Tests for internal _classify and _probe_tags utilities. + + Two blocks in this class originally defined the same method names. One + classified *real* Expression objects; a later block shadowed all of them by + re-running the same names against a MagicMock with a stubbed + ``statement_type``, so the real-expression tests never executed. Both sets + live here now, with the stubbed variants carrying a ``_by_stubbed_*`` + suffix; the un-suffixed name is always the real-object case. Where a + ``test_probe_tags_*`` pair proved byte-for-byte identical it is kept once. + """ def _dialect(self): from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect @@ -369,38 +378,56 @@ def test_classify_dql(self): def test_classify_dml(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify - from rhosocial.activerecord.backend.expression import InsertExpression + from rhosocial.activerecord.backend.expression import InsertExpression, Literal d = self._dialect() - expr = InsertExpression(d, Table(d, 't'), [Literal(d, 1)]) # noqa: F821 + expr = InsertExpression(d, Table(d, 't'), [Literal(d, 1)]) result = _classify(expr) assert result == ["DML"] - def test_classify_ddl(self): + def test_classify_create_table_is_clause(self): + """A DDL expression carries no statement_type, so it is a CLAUSE. + + _classify returns CLAUSE for anything that is not Executable, and no + core DDL expression implements Executable. The "DDL" arm of its tag + map is therefore only reachable from a dialect-level Executable, + which test_classify_ddl_by_stubbed_statement_type covers. + """ from rhosocial.activerecord.backend.named_expression.resolver import _classify + from rhosocial.activerecord.backend.expression import CreateTableExpression d = self._dialect() - expr = CreateNamedRelationRef(d, Table(d, "t")) + expr = CreateTableExpression(d, Table(d, "t"), []) result = _classify(expr) - assert result == ["DDL"] + assert result == ["CLAUSE"] - def test_classify_tcl(self): + def test_classify_begin_transaction_is_clause(self): + """A TCL expression carries no statement_type, so it is a CLAUSE. + + See test_classify_create_table_is_clause; the "TCL" arm of the tag map + has no core expression reaching it either. + """ from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.expression import BeginTransactionExpression d = self._dialect() expr = BeginTransactionExpression(d) result = _classify(expr) - assert result == ["TCL"] + assert result == ["CLAUSE"] - def test_classify_call(self): + def test_classify_function_call_is_clause(self): + """A CALL expression carries no statement_type, so it is a CLAUSE. + + See test_classify_create_table_is_clause; the "CALL" arm of the tag map + has no core expression reaching it either. + """ from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.expression import FunctionCall d = self._dialect() expr = FunctionCall(d, "foo") result = _classify(expr) - assert result == ["CALL"] + assert result == ["CLAUSE"] def test_classify_explain(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify @@ -414,14 +441,6 @@ def test_classify_explain(self): result = _classify(expr) assert result == ["EXPLAIN"] - def test_classify_unknown(self): - from rhosocial.activerecord.backend.schema import StatementType - from rhosocial.activerecord.backend.expression import SQLValueExpression - - d = self._dialect() - with patch.object(SQLValueExpression(d, 1), "statement_type", StatementType.OTHER): - pass - def test_probe_tags_no_dialect(self): from rhosocial.activerecord.backend.named_expression.resolver import _probe_tags @@ -487,7 +506,7 @@ def f(dialect, x: int = 1): result = _probe_tags(f, dialect=self._dialect()) assert result == ["CLAUSE"] - def test_classify_dql(self): # noqa: F811 + def test_classify_dql_by_stubbed_statement_type(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.schema import StatementType @@ -496,7 +515,7 @@ def test_classify_dql(self): # noqa: F811 result = _classify(exec_mock) assert result == ["DQL"] - def test_classify_dml(self): # noqa: F811 + def test_classify_dml_by_stubbed_statement_type(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.schema import StatementType @@ -505,7 +524,7 @@ def test_classify_dml(self): # noqa: F811 result = _classify(exec_mock) assert result == ["DML"] - def test_classify_ddl(self): # noqa: F811 + def test_classify_ddl_by_stubbed_statement_type(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.schema import StatementType @@ -514,7 +533,7 @@ def test_classify_ddl(self): # noqa: F811 result = _classify(exec_mock) assert result == ["DDL"] - def test_classify_tcl(self): # noqa: F811 + def test_classify_tcl_by_stubbed_statement_type(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.schema import StatementType @@ -523,7 +542,7 @@ def test_classify_tcl(self): # noqa: F811 result = _classify(exec_mock) assert result == ["TCL"] - def test_classify_call(self): # noqa: F811 + def test_classify_call_by_stubbed_statement_type(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.schema import StatementType @@ -532,7 +551,7 @@ def test_classify_call(self): # noqa: F811 result = _classify(exec_mock) assert result == ["CALL"] - def test_classify_explain(self): # noqa: F811 + def test_classify_explain_by_stubbed_statement_type(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.schema import StatementType @@ -541,7 +560,7 @@ def test_classify_explain(self): # noqa: F811 result = _classify(exec_mock) assert result == ["EXPLAIN"] - def test_classify_unknown(self): # noqa: F811 + def test_classify_unknown_by_stubbed_statement_type(self): from rhosocial.activerecord.backend.named_expression.resolver import _classify from rhosocial.activerecord.backend.schema import StatementType @@ -550,51 +569,6 @@ def test_classify_unknown(self): # noqa: F811 result = _classify(exec_mock) assert result == ["OTHER"] - def test_probe_tags_no_dialect(self): # noqa: F811 - from rhosocial.activerecord.backend.named_expression.resolver import _probe_tags - - def f(dialect, x: int = 1): - pass - - result = _probe_tags(f, dialect=None) - assert result == ["?"] - - def test_probe_tags_unresolvable_signature(self): # noqa: F811 - from rhosocial.activerecord.backend.named_expression.resolver import _probe_tags - - class NoSig: - pass - - result = _probe_tags(NoSig()) - assert result == ["?"] - - def test_probe_tags_required_param_no_dialect(self): # noqa: F811 - from rhosocial.activerecord.backend.named_expression.resolver import _probe_tags - - def f(dialect, x): - pass - - result = _probe_tags(f, dialect=MagicMock()) - assert result == ["?"] - - def test_probe_tags_callable_raises(self): # noqa: F811 - from rhosocial.activerecord.backend.named_expression.resolver import _probe_tags - - def f(dialect, x: int = 1): - raise RuntimeError - - result = _probe_tags(f, dialect=MagicMock()) - assert result == ["?"] - - def test_probe_tags_returns_non_expression(self): # noqa: F811 - from rhosocial.activerecord.backend.named_expression.resolver import _probe_tags - - def f(dialect, x: int = 1): - return "not expression" - - result = _probe_tags(f, dialect=MagicMock()) - assert result == ["?"] - def test_resolve_annotation_string(self): from rhosocial.activerecord.backend.named_expression.resolver import _resolve_annotation @@ -614,7 +588,7 @@ def test_resolve_annotation_bad_string(self): result = _resolve_annotation("NonExistentType", {}) assert result == "NonExistentType" - def test_probe_tags_success(self): # noqa: F811 + def test_probe_tags_success_by_stubbed_expression(self): from rhosocial.activerecord.backend.named_expression.resolver import _probe_tags from rhosocial.activerecord.backend.schema import StatementType @@ -627,7 +601,7 @@ def f(dialect, x: int = 1): result = _probe_tags(f, dialect=MagicMock()) assert result == ["DQL"] - def test_probe_tags_returns_clause(self): # noqa: F811 + def test_probe_tags_returns_clause_by_stubbed_dialect(self): from rhosocial.activerecord.backend.named_expression.resolver import _probe_tags from rhosocial.activerecord.backend.expression import RawSQLExpression diff --git a/tests/rhosocial/activerecord_test/feature/backend/schema/test_suggested_data_types.py b/tests/rhosocial/activerecord_test/feature/backend/schema/test_suggested_data_types.py index 9b8694cbd..421bbb031 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/schema/test_suggested_data_types.py +++ b/tests/rhosocial/activerecord_test/feature/backend/schema/test_suggested_data_types.py @@ -9,6 +9,27 @@ - Honesty: no self-suggestion; a fully-capable dummy dialect suggests nothing - Contract invariant: suggested keys and supported keys are disjoint - DataTypeMixin base default returns {} + +For backend authors — how to verify your own coverage +----------------------------------------------------- +Concept coverage (D9) is **per dialect and deliberately not audited from +core**: this file checks the mechanism (value types, key namespaces, +disjointness, honesty), not any backend's completeness — backends differ +too much for one shared shape. Each backend should keep its own coverage +test that walks the core concepts (**discovered, not listed**, so a +concept added to core later cannot slip past a stale list) and asserts: + +- every concept is rendered or suggested — silence is not an answer + (a concept that is neither reaches the caller as a bare TypeError with + no route forward); +- rendered and suggested keys are disjoint; +- every substitute actually renders on the dialect; +- every suggested key still names an existing concept, so a core rename + cannot leave dead entries. + +BigQuery's ``test_every_core_concept_is_declared`` is the pattern to +copy. The full statement of the rule lives on the ``DataTypeSupport`` +protocol (:mod:`...dialect.protocols.query.data_type`). """ import re diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_expression_roundtrip_complex_with.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_expression_roundtrip_complex_with.py index b97464ca2..ff28cd665 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_expression_roundtrip_complex_with.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_expression_roundtrip_complex_with.py @@ -15,8 +15,11 @@ import pytest import sqlite3 +from rhosocial.activerecord.backend.expression.types import CustomType from rhosocial.activerecord.backend.expression import ( Column, + ComparisonPredicate, + NumericColumn, Literal, FunctionCall, QueryExpression, @@ -42,7 +45,7 @@ ) from rhosocial.activerecord.backend.expression.functions.string import concat_op from rhosocial.activerecord.backend.expression.functions.type_conversion import cast -from rhosocial.activerecord.backend.expression.predicates import LikePredicate +from rhosocial.activerecord.backend.expression.predicates import InPredicate, LikePredicate from rhosocial.activerecord.backend.expression.serialization import ( serialize, deserialize, @@ -69,7 +72,7 @@ def _make_axis_union(cte_name, column, start, step, limit_): base = ValuesExpression(d, [(start,)]) rec = QueryExpression( d, - select=[Column(d, column) + Literal(d, step)], + select=[NumericColumn(d, column) + Literal(d, step)], from_=NamedRelationRef(d, Table(d, cte_name)), where=Column(d, column) < Literal(d, limit_), ) @@ -90,15 +93,19 @@ def _make_axis_union(cte_name, column, start, step, limit_): m_step = QueryExpression( d, select=[ - Column(d, "iter") + Literal(d, 1), + NumericColumn(d, "iter") + Literal(d, 1), Column(d, "cx"), Column(d, "cy"), - Column(d, "x") * Column(d, "x") - Column(d, "y") * Column(d, "y") + Column(d, "cx"), - Literal(d, 2.0) * Column(d, "x") * Column(d, "y") + Column(d, "cy"), + NumericColumn(d, "x") * NumericColumn(d, "x") + - NumericColumn(d, "y") * NumericColumn(d, "y") + NumericColumn(d, "cx"), + Literal(d, 2.0) * NumericColumn(d, "x") * NumericColumn(d, "y") + NumericColumn(d, "cy"), ], from_=NamedRelationRef(d, Table(d, "m")), - where=((Column(d, "x") * Column(d, "x") + Column(d, "y") * Column(d, "y")) < Literal(d, 4.0)) - & (Column(d, "iter") < Literal(d, 28)), + where=( + (NumericColumn(d, "x") * NumericColumn(d, "x") + NumericColumn(d, "y") * NumericColumn(d, "y")) + < Literal(d, 4.0) + ) + & (NumericColumn(d, "iter") < Literal(d, 28)), ) m_cte = CTEExpression( d, @@ -115,7 +122,7 @@ def _make_axis_union(cte_name, column, start, step, limit_): ) m2_cte = CTEExpression(d, name="m2", query=m2_query, columns=["iter", "cx", "cy"]) - min_expr = FunctionCall(d, "MIN", Column(d, "iter") / Literal(d, 7), Literal(d, 4)) + min_expr = FunctionCall(d, "MIN", NumericColumn(d, "iter") / Literal(d, 7), Literal(d, 4)) substr_expr = FunctionCall(d, "SUBSTR", Literal(d, " .+*#"), Literal(d, 1) + min_expr, Literal(d, 1)) a_query = QueryExpression( d, @@ -145,7 +152,10 @@ def build_sudoku(d, puzzle="53..7....6..195....98....6.8...6...34..8.3..17...2.. digits_seed = ValuesExpression(d, [("1", 1)]) digits_step = QueryExpression( d, - select=[cast(d, Column(d, "lp") + Literal(d, 1), "TEXT"), Column(d, "lp") + Literal(d, 1)], + select=[ + cast(d, NumericColumn(d, "lp") + Literal(d, 1), CustomType(d, raw="TEXT")), + NumericColumn(d, "lp") + Literal(d, 1), + ], from_=NamedRelationRef(d, Table(d, "digits")), where=Column(d, "lp") < Literal(d, 9), ) @@ -157,7 +167,7 @@ def build_sudoku(d, puzzle="53..7....6..195....98....6.8...6...34..8.3..17...2.. ) s = Column(d, "s") - ind = Column(d, "ind") + ind = NumericColumn(d, "ind") z = Column(d, "z") x_seed = QueryExpression( @@ -174,7 +184,7 @@ def build_sudoku(d, puzzle="53..7....6..195....98....6.8...6...34..8.3..17...2.. ) # Build the NOT EXISTS subquery with three OR conditions - lp = Column(d, "lp", "lp") + lp = NumericColumn(d, "lp", "lp") one = Literal(d, 1) zero = Literal(d, 0) nine = Literal(d, 9) @@ -253,13 +263,13 @@ def build_bom(d): select=[ Column(d, "child_id", "c"), Column(d, "quantity", "c"), - Column(d, "total_qty", "b") * Column(d, "quantity", "c"), + NumericColumn(d, "total_qty", "b") * NumericColumn(d, "quantity", "c"), ], from_=[ NamedRelationRef(d, Table(d, "parts_tree"), alias="c"), NamedRelationRef(d, Table(d, "BOM_Explosion"), alias="b"), ], - where=Column(d, "parent_id", "c") == Column(d, "child_id", "b"), + where=ComparisonPredicate(d, "=", Column(d, "parent_id", "c"), Column(d, "child_id", "b")), ) union = SetOperationExpression(d, left=anchor, right=step, operation="UNION", all_=True) cte = CTEExpression( @@ -302,8 +312,8 @@ def build_flight_paths(d): d, select=[ Column(d, "destination", "f"), - Column(d, "price", "p") + Column(d, "price", "f"), - Column(d, "depth", "p") + Literal(d, 1), + NumericColumn(d, "price", "p") + NumericColumn(d, "price", "f"), + NumericColumn(d, "depth", "p") + Literal(d, 1), concat_op(d, Column(d, "path", "p"), Literal(d, " -> "), Column(d, "destination", "f")), ], from_=[ @@ -343,9 +353,9 @@ def build_game_of_life(d): a LEFT JOIN of the live table. """ live = NamedRelationRef(d, Table(d, "live"), alias="l") - x = Column(d, "x") - y = Column(d, "y") - gen = Column(d, "gen") + x = NumericColumn(d, "x") + y = NumericColumn(d, "y") + gen = NumericColumn(d, "gen") def neighbor(dx, dy): return QueryExpression( @@ -380,14 +390,14 @@ def neighbor(dx, dy): d, cases=[ (l_x_null & (Column(d, "cnt", "n") == Literal(d, 3)), Literal(d, 1)), - ((~l_x_null) & Column(d, "cnt", "n").in_([2, 3]), Literal(d, 1)), + ((~l_x_null) & InPredicate(d, Column(d, "cnt", "n"), Literal(d, (2, 3))), Literal(d, 1)), ], else_result=Literal(d, 0), ) on = ( - (Column(d, "x", "l") == Column(d, "x", "n")) - & (Column(d, "y", "l") == Column(d, "y", "n")) - & (Column(d, "gen", "l") == Column(d, "gen", "n")) + ComparisonPredicate(d, "=", Column(d, "x", "l"), Column(d, "x", "n")) + & ComparisonPredicate(d, "=", Column(d, "y", "l"), Column(d, "y", "n")) + & ComparisonPredicate(d, "=", Column(d, "gen", "l"), Column(d, "gen", "n")) ) join = JoinClause(d, left_table=nsub, right_table=live, join_type="LEFT JOIN", condition=on) return QueryExpression( @@ -395,7 +405,7 @@ def neighbor(dx, dy): select=[ Column(d, "x", "n"), Column(d, "y", "n"), - Column(d, "gen", "n") + Literal(d, 1), + NumericColumn(d, "gen", "n") + Literal(d, 1), alive, ], from_=join, @@ -514,4 +524,4 @@ def test_game_of_life_evolves_glider(self, sqlite_dialect): next_gen = sorted((r[0], r[1]) for r in cur.fetchall() if r[3] == 1) assert next_gen == [(0, 1), (1, 2), (1, 3), (2, 1), (2, 2)] finally: - conn.close() \ No newline at end of file + conn.close() diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_extension_integration_scenarios.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_extension_integration_scenarios.py index 55b98e47b..f22f53739 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_extension_integration_scenarios.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_extension_integration_scenarios.py @@ -31,6 +31,7 @@ ) from rhosocial.activerecord.backend.expression import ( Column, + ComparisonPredicate, ColumnConstraint, ColumnConstraintType, ColumnDefinition, @@ -166,7 +167,9 @@ def test_full_scenario(self, backend): from_=NamedRelationRef(dialect, Table(dialect, "docs_fts")), where=( SQLiteMatchPredicate(dialect, table="docs_fts", query="office") - & (Column(dialect, "author") == "Alice") + & ComparisonPredicate( + dialect, "=", Column(dialect, "author"), Literal(dialect, "Alice") + ) ) ).to_sql() ) @@ -201,8 +204,12 @@ def test_full_scenario(self, backend): ), alias="loc" ), - condition=Column(dialect, "rowid", table="docs_fts") - == Column(dialect, "id", table="loc") + condition=ComparisonPredicate( + dialect, + "=", + Column(dialect, "rowid", table="docs_fts"), + Column(dialect, "id", table="loc"), + ) )], where=SQLiteMatchPredicate(dialect, table="docs_fts", query="report") ).to_sql() @@ -365,8 +372,12 @@ def test_full_scenario(self, backend): dialect, left_table=NamedRelationRef(dialect, Table(dialect, "zones"), alias="z"), right_table=NamedRelationRef(dialect, Table(dialect, "zone_fts"), alias="f"), - condition=Column(dialect, "rowid", table="z") - == Column(dialect, "rowid", table="f") + condition=ComparisonPredicate( + dialect, + "=", + Column(dialect, "rowid", table="z"), + Column(dialect, "rowid", table="f"), + ) )], where=( SQLiteMatchPredicate(dialect, table="zone_fts", query="park") @@ -559,19 +570,27 @@ def test_full_scenario(self, backend): ), alias="rt" ), - condition=Column(dialect, "rowid", table="features_fts") - == Column(dialect, "id", table="rt") + condition=ComparisonPredicate( + dialect, + "=", + Column(dialect, "rowid", table="features_fts"), + Column(dialect, "id", table="rt"), + ) ), right_table=NamedRelationRef(dialect, Table(dialect, "feature_props")), - condition=Column(dialect, "rowid", table="features_fts") - == Column(dialect, "feature_id", table="feature_props") + condition=ComparisonPredicate( + dialect, + "=", + Column(dialect, "rowid", table="features_fts"), + Column(dialect, "feature_id", table="feature_props"), + ) )], where=( SQLiteMatchPredicate(dialect, table="features_fts", query="park") & (json_extract_func( dialect, Column(dialect, "props", table="feature_props"), - "$.has_lake" + Literal(dialect, "$.has_lake") ) == 1) ) ).to_sql() diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_dialect_security.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_dialect_security.py index ce365873d..b31b6bcba 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_dialect_security.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_dialect_security.py @@ -82,21 +82,26 @@ def test_sqlite_format_storage_options_string_escaping(dialect): def test_sqlite_format_cast_expression_valid(dialect): - """Test that CAST expression validates target_type.""" + """A CAST target is a DataType, and the dialect renders what it says.""" from rhosocial.activerecord.backend.expression.core import CastExpression, Column + from rhosocial.activerecord.backend.expression.types import TextType - expr = CastExpression(dialect, Column(dialect, "column"), "TEXT") + expr = CastExpression(dialect, Column(dialect, "column"), TextType(dialect)) sql, params = dialect.format_cast_expression(expr) assert "TEXT" in sql def test_sqlite_format_cast_expression_rejects_injection(dialect): - """Test that malicious target_type is rejected.""" + """A string in the type position is refused at construction. + + The type position cannot be bound as a parameter, so whatever lands there is + rendered into the statement text. That is why a string is not accepted at + all rather than being escaped: there is nothing to escape it into, since it + is code and not data.""" from rhosocial.activerecord.backend.expression.core import CastExpression, Column - with pytest.raises(ValueError, match="Invalid target type"): - bad = CastExpression(dialect, Column(dialect, "column"), "TEXT; DROP TABLE users--") - dialect.format_cast_expression(bad) + with pytest.raises(TypeError, match="takes a DataType instance"): + CastExpression(dialect, Column(dialect, "column"), "TEXT; DROP TABLE users--") # ============================================================ diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_protocol_conformance.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_protocol_conformance.py index 2be1b90a0..fd3d0dbc2 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_protocol_conformance.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_protocol_conformance.py @@ -100,6 +100,11 @@ def get_own_protocol_methods(proto: type) -> set: dialect_protocols.JSONSupport, +# UUID value expressions are declared rather than absent: SQLiteDialect + # composes UUIDMixin, whose probes report False for every operation, so + # generation raises UnsupportedFeatureError with a Python-side suggestion + # instead of another backend's function. + dialect_protocols.UUIDSupport, dialect_protocols.ReturningSupport, @@ -216,6 +221,11 @@ def get_own_protocol_methods(proto: type) -> set: dialect_protocols.DataTypeSupport, + # Column classes: which operations a value carries, where DataTypeSupport + # answers how it is stored. + dialect_protocols.ColumnTypeSupport, + + dialect_protocols.PartitionSupport, @@ -288,7 +298,7 @@ def get_own_protocol_methods(proto: type) -> set: dialect_protocols.DropDomainSupport, - dialect_protocols.DateTimeSupport, + dialect_protocols.TimestampSupport, dialect_protocols.DqlOrderSupport, diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_view_execution.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_view_execution.py index c0ca9f608..e0ceb2313 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_view_execution.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite/test_sqlite_view_execution.py @@ -11,6 +11,7 @@ from rhosocial.activerecord.backend.impl.sqlite.backend import SQLiteBackend from rhosocial.activerecord.backend.expression import ( Column, + ComparisonPredicate, Literal, FunctionCall, QueryExpression, @@ -412,7 +413,9 @@ def test_create_view_with_join(self, sqlite_backend): users_table = NamedRelationRef(dialect, Table(dialect, "users"), alias="u") orders_table = NamedRelationRef(dialect, Table(dialect, "orders"), alias="o") - join_condition = Column(dialect, "id", "u") == Column(dialect, "user_id", "o") + join_condition = ComparisonPredicate( + dialect, "=", Column(dialect, "id", "u"), Column(dialect, "user_id", "o") + ) join_expr = JoinClause( dialect, left_table=users_table, right_table=orders_table, condition=join_condition, join_type="INNER JOIN" ) diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_advanced_function_window.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_advanced_function_window.py index 51f3f3c74..d05bcffa3 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_advanced_function_window.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_advanced_function_window.py @@ -9,6 +9,7 @@ AllExpression, ) from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.backend.expression.types import RealType class TestAdvancedFunctionWindow: @@ -49,7 +50,7 @@ def test_case_simple_expression(self, sqlite_dialect_3_8_0: SQLiteDialect): def test_cast_method(self, sqlite_dialect_3_8_0: SQLiteDialect): """Tests cast() method.""" col = Column(sqlite_dialect_3_8_0, "price") - cast_expr = col.cast("REAL") + cast_expr = col.cast(RealType(sqlite_dialect_3_8_0)) sql, params = cast_expr.to_sql() assert "CAST" in sql.upper() assert params == () diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_advanced_functions.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_advanced_functions.py index fd160c616..945ebe430 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_advanced_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_advanced_functions.py @@ -10,12 +10,13 @@ ExistsExpression, AnyExpression, AllExpression, - JSONExpression, + JSONDocumentExpression, ArrayExpression, OrderedSetAggregation, ) from rhosocial.activerecord.backend.expression.core import Subquery from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.backend.expression.types import IntegerType class TestCaseExpression: @@ -73,7 +74,7 @@ class TestCastMethod: def test_cast_method_basic(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test basic CAST via cast() method.""" col = Column(sqlite_dialect_3_8_0, "price") - cast_expr = col.cast("INTEGER") + cast_expr = col.cast(IntegerType(sqlite_dialect_3_8_0)) sql, params = cast_expr.to_sql() assert "CAST(" in sql assert "AS INTEGER" in sql @@ -129,11 +130,11 @@ def test_all_expression(self, sqlite_dialect_3_8_0: SQLiteDialect): class TestJSONExpression: - """Tests for JSONExpression class.""" + """Tests for JSONDocumentExpression class.""" def test_json_extract_path(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test JSON path extraction.""" - json_expr = JSONExpression(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.name") + json_expr = JSONDocumentExpression(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.name") sql, params = json_expr.to_sql() # In SQLite, this uses the -> operator with the path embedded as a literal assert sql == '"data"->\'$.name\'' @@ -141,7 +142,7 @@ def test_json_extract_path(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_extract_as_text(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test JSON path extraction as text.""" - json_expr = JSONExpression( + json_expr = JSONDocumentExpression( sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "metadata"), "$.settings.theme", operation="->>" ) sql, params = json_expr.to_sql() diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_column_type.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_column_type.py new file mode 100644 index 000000000..50f270c5e --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_column_type.py @@ -0,0 +1,198 @@ +# tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_column_type.py +"""SQLite's own column-type table. + +The protocol tests assert that the *rules* hold; this file asserts SQLite's +*answers*, so that a change to them has to be a deliberate edit with its reason +written down rather than a drift nobody notices: + +1. all eighteen common entries resolve, and to SQLite's classes; +2. the table differs from the portable dummy baseline in exactly the places the + evidence says it does -- the four sequence entries -- and nowhere else; +3. the dummy dialect is *not* this table: it states the portable baseline. + +No database is needed: every assertion is on the table or on a never-connected +dialect. +""" + +import datetime +import decimal +import enum +import uuid + +import pytest + +from rhosocial.activerecord.backend.expression.column_types import ( + ArrayColumn, + BinaryColumn, + BooleanColumn, + ColumnBase, + TimestampColumn, + IntegerColumn, + JSONColumn, + NumericColumn, + StringColumn, + UUIDColumn, +) +from rhosocial.activerecord.backend.impl.dummy.column_type import DUMMY_COLUMN_TYPES +from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect +from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.backend.impl.sqlite.mixins.column_type import ( + SQLITE_COLUMN_TYPES, +) +from rhosocial.activerecord_test.feature.query.column_helpers import ( + COMMON_TYPES, + resolve_column_class, +) + + +def sqlite_dialect(version=(3, 46, 1)): + """A version-adapted SQLite dialect; 3.46 is well past the JSON1 line.""" + return SQLiteDialect(version=version) + + +def dummy_dialect(): + """An adapted dummy dialect: the dialect-less baseline, not a server.""" + dialect = DummyDialect() + dialect._version = (3, 46, 1) + return dialect + + +#: ``{entry: column class}`` as SQLite states it. Written out in full rather +#: than derived, because a derived table would restate the code's own answer +#: back at itself and could not catch a change to it. +_SQLITE_ANSWERS = [ + (bool, BooleanColumn), + (int, IntegerColumn), + (float, NumericColumn), + (decimal.Decimal, NumericColumn), + (str, StringColumn), + (bytes, BinaryColumn), + (bytearray, BinaryColumn), + (datetime.date, TimestampColumn), + (datetime.time, TimestampColumn), + (datetime.datetime, TimestampColumn), + (datetime.timedelta, NumericColumn), + (uuid.UUID, UUIDColumn), + (dict, JSONColumn), + (list, JSONColumn), + (tuple, JSONColumn), + (set, JSONColumn), + (frozenset, JSONColumn), + (enum.Enum, StringColumn), +] + +_ENTRY_IDS = [getattr(entry, "__name__", str(entry)) for entry, _ in _SQLITE_ANSWERS] + + +def test_the_table_answers_every_entry_of_the_contract(): + """Completeness is the contract; a hole is a test failure, not a silent gap. + + SQLite is not special here -- every backend owes the same eighteen answers, + and the ten backends are held to it in their own CI. Core can enforce it + for the backend it ships, so it does. + """ + missing = [entry for entry in COMMON_TYPES if entry not in SQLITE_COLUMN_TYPES] + assert missing == [] + + +def test_the_table_has_no_entry_beyond_the_contract(): + """A backend may extend the list with a type of its own; SQLite has none. + + Asserted so that an extension added later is a deliberate act with its own + entry in this file, rather than a key that appears in the table and is never + checked by anything. + """ + assert set(SQLITE_COLUMN_TYPES) == set(COMMON_TYPES) + + +def test_no_entry_is_answered_with_none(): + """The probe found a working pairing for all eighteen, so none is refused. + + ``None`` would mean "this backend has no column for this value", and SQLite + demonstrably does: a date is a TEXT column ``strftime`` reads, a dict is a + TEXT column JSON1 reads. Refusing them would be reading the *storage* (no + native type) as a statement about the *operations* -- the exact conflation + the DataType/Column split exists to prevent. + """ + assert None not in SQLITE_COLUMN_TYPES.values() + + +@pytest.mark.parametrize("entry, expected", _SQLITE_ANSWERS, ids=_ENTRY_IDS) +def test_every_entry_selects_the_class_sqlite_states(entry, expected): + """Through the selection, not by reading the dict.""" + assert resolve_column_class(sqlite_dialect(), entry) is expected + + +@pytest.mark.parametrize("entry", COMMON_TYPES, ids=_ENTRY_IDS) +def test_every_answer_is_a_column_class(entry): + assert issubclass(resolve_column_class(sqlite_dialect(), entry), ColumnBase) + + +def test_the_sequences_are_documents_because_sqlite_has_no_array_type(): + """``ArrayColumn`` would offer ``array_length()`` / ``unnest()`` as if one existed. + + SQLite has no array type at all -- ``supports_array_type()`` is False and + ``ARRAY[...]`` is a syntax error -- so suggesting ``ArrayColumn`` would hand + the caller operations the engine cannot execute. The array probe shows the + document route carries the same intent: length through ``json_array_length``, + elements through ``$[n]``, containment and unnest through ``json_each``. + """ + dialect = sqlite_dialect() + assert dialect.supports_array_type() is False + for entry in (list, tuple, set, frozenset): + assert resolve_column_class(dialect, entry) is JSONColumn + assert resolve_column_class(dialect, entry) is not ArrayColumn + + +def test_the_numeric_entries_take_the_one_numeric_class(): + """float / Decimal / timedelta all answer NumericColumn. + + The numeric family is one class by decision: the operations are the same + whatever the value was declared as, and the difference between a + ``NUMERIC(18,4)`` and a ``DOUBLE PRECISION`` belongs to the DDL layer's + ``DataType``. A duration is a number of seconds here, so it answers the + same class as the other numbers. + """ + dialect = sqlite_dialect() + assert resolve_column_class(dialect, float) is NumericColumn + assert resolve_column_class(dialect, decimal.Decimal) is NumericColumn + assert resolve_column_class(dialect, datetime.timedelta) is NumericColumn + + +def test_the_dummy_dialect_states_the_portable_baseline(): + """It stands for no server, so it states no backend's answers. + + SQLite is built into core and the dummy is the other dialect core ships, so + the two are easy to conflate. They are deliberately different: the dummy is + the dialect-less default a unit test reads, and copying a real backend's + table into it would make "what does the portable baseline say" unanswerable. + """ + dummy = dummy_dialect() + assert dummy.suggested_column_types() == DUMMY_COLUMN_TYPES + for entry in COMMON_TYPES: + assert resolve_column_class(dummy, entry) is DUMMY_COLUMN_TYPES[entry] + + +def test_the_two_dialects_really_do_differ_where_stated(): + """The distinction above is load-bearing, so it is checked rather than described.""" + sqlite, dummy = sqlite_dialect(), dummy_dialect() + assert resolve_column_class(sqlite, list) is JSONColumn + assert resolve_column_class(dummy, list) is ArrayColumn + # The numeric merge is shared by both tables. + assert resolve_column_class(sqlite, decimal.Decimal) is NumericColumn + assert resolve_column_class(dummy, decimal.Decimal) is NumericColumn + + +@pytest.mark.parametrize("entry", COMMON_TYPES, ids=_ENTRY_IDS) +def test_every_entry_builds_a_column_that_renders(entry): + """A table answer is only real if the column it names can be constructed. + + The selection answering correctly and the object refusing to build would + leave the failure at query time with a message about a column rather than + about the annotation, which is the outcome the narrow column classes were + introduced to remove. + """ + dialect = sqlite_dialect() + column = resolve_column_class(dialect, entry)(dialect, "c") + assert isinstance(column, ColumnBase) + assert column.to_sql() == ('"c"', ()) diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_datetime_interval_expressions.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_datetime_interval_expressions.py index 20a5f25c4..95b509902 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_datetime_interval_expressions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_datetime_interval_expressions.py @@ -21,6 +21,7 @@ interval, ) from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.backend.expression.types import TextType class TestSQLiteDateTimeIntervalExpressions: @@ -107,10 +108,7 @@ def test_date_sub_interval_expression(self, sqlite_dialect_3_8_0: SQLiteDialect) def test_date_add_literal_source_params_order(self, sqlite_dialect_3_8_0: SQLiteDialect): expr = date_add( sqlite_dialect_3_8_0, - Literal(sqlite_dialect_3_8_0, "2026-06-04 10:00:00"), - 30, - "minute", - ) + Literal(sqlite_dialect_3_8_0, "2026-06-04 10:00:00"), 30, "minute",) sql, params = expr.to_sql() @@ -213,22 +211,18 @@ def test_interval_expression_rejects_extra_unit(self, sqlite_dialect_3_8_0: SQLi date_add( sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "created_at"), - expr, - "day", - ) + expr, "day",) def test_numeric_interval_requires_unit(self, sqlite_dialect_3_8_0: SQLiteDialect): with pytest.raises(ValueError): date_sub( sqlite_dialect_3_8_0, - Column(sqlite_dialect_3_8_0, "created_at"), - 1, - ) + Column(sqlite_dialect_3_8_0, "created_at"), 1,) def test_alias_and_cast(self, sqlite_dialect_3_8_0: SQLiteDialect): expr = ( extract(sqlite_dialect_3_8_0, "year", Column(sqlite_dialect_3_8_0, "created_at")) - .cast("TEXT") + .cast(TextType(sqlite_dialect_3_8_0)) .as_("created_year") ) @@ -241,18 +235,13 @@ def test_alias_and_cast(self, sqlite_dialect_3_8_0: SQLiteDialect): def test_query_expression_integration(self, sqlite_dialect_3_8_0: SQLiteDialect): shifted = date_add( sqlite_dialect_3_8_0, - Column(sqlite_dialect_3_8_0, "created_at"), - 1, - "day", - ) + Column(sqlite_dialect_3_8_0, "created_at"), 1, "day",) query = QueryExpression( sqlite_dialect_3_8_0, select=[ extract( - sqlite_dialect_3_8_0, - "year", - Column(sqlite_dialect_3_8_0, "created_at"), - ) + sqlite_dialect_3_8_0, "year", + Column(sqlite_dialect_3_8_0, "created_at"),) ], from_="events", where=shifted > Literal(sqlite_dialect_3_8_0, "2026-01-01"), diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_functions.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_functions.py index a233decc0..f3abb130d 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_functions.py @@ -127,14 +127,14 @@ def test_upper_function(self, sqlite_dialect_3_8_0: SQLiteDialect): def test_abs_function(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test ABS function.""" - func = abs_(sqlite_dialect_3_8_0, -5) + func = abs_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, -5)) sql, params = func.to_sql() assert "ABS(" in sql assert params == (-5,) def test_round_function(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test ROUND function.""" - func = round_(sqlite_dialect_3_8_0, 3.14159) + func = round_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, 3.14159)) sql, params = func.to_sql() assert "ROUND(" in sql assert params == (3.14159,) diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_json_functions.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_json_functions.py index b13272953..d895edb93 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_json_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_json_functions.py @@ -4,7 +4,7 @@ These functions are available in SQLite 3.38.0+ with the json1 extension. """ -from rhosocial.activerecord.backend.expression import Column +from rhosocial.activerecord.backend.expression import Column, Literal from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect from rhosocial.activerecord.backend.impl.sqlite.functions.json import ( json, @@ -35,7 +35,7 @@ class TestSQLiteJSONFunctions: def test_json_with_string(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json() with string literal.""" - result = json(sqlite_dialect_3_38_0, '{"a": 1}') + result = json(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, '{"a": 1}')) sql, params = result.to_sql() assert "JSON(" in sql assert params == ('{"a": 1}',) @@ -83,14 +83,14 @@ def test_json_object_with_pairs(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_extract(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_extract() with path.""" - result = json_extract(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.a") + result = json_extract(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.a")) sql, params = result.to_sql() assert "JSON_EXTRACT(" in sql assert params == ("$.a",) def test_json_extract_multiple_paths(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_extract() with multiple paths.""" - result = json_extract(sqlite_dialect_3_38_0, '{"a": 1}', "$.a", "$.b") + result = json_extract(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, '{"a": 1}'), Literal(sqlite_dialect_3_38_0, "$.a"), Literal(sqlite_dialect_3_38_0, "$.b")) sql, params = result.to_sql() assert "JSON_EXTRACT(" in sql assert params == ('{"a": 1}', "$.a", "$.b") @@ -103,14 +103,14 @@ def test_json_type(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_type_with_path(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_type() with path.""" - result = json_type(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.a") + result = json_type(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.a")) sql, params = result.to_sql() assert "JSON_TYPE(" in sql assert params == ("$.a",) def test_json_valid_true(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_valid() with valid JSON.""" - result = json_valid(sqlite_dialect_3_38_0, '{"a": 1}') + result = json_valid(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, '{"a": 1}')) sql, params = result.to_sql() assert "JSON_VALID(" in sql assert params == ('{"a": 1}',) @@ -123,48 +123,48 @@ def test_json_valid_with_column(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_quote(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_quote().""" - result = json_quote(sqlite_dialect_3_38_0, "hello") + result = json_quote(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, "hello")) sql, params = result.to_sql() assert "JSON_QUOTE(" in sql assert params == ("hello",) def test_json_remove(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_remove().""" - result = json_remove(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.a") + result = json_remove(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.a")) sql, params = result.to_sql() assert "JSON_REMOVE(" in sql assert params == ("$.a",) def test_json_remove_multiple_paths(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_remove() with multiple paths.""" - result = json_remove(sqlite_dialect_3_38_0, '{"a": 1, "b": 2}', "$.a", "$.b") + result = json_remove(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, '{"a": 1, "b": 2}'), Literal(sqlite_dialect_3_38_0, "$.a"), Literal(sqlite_dialect_3_38_0, "$.b")) sql, params = result.to_sql() assert "JSON_REMOVE(" in sql assert params == ('{"a": 1, "b": 2}', "$.a", "$.b") def test_json_set(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_set().""" - result = json_set(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.a", "new_value") + result = json_set(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.a"), Literal(sqlite_dialect_3_38_0, "new_value")) sql, params = result.to_sql() assert "JSON_SET(" in sql assert params == ("$.a", "new_value") def test_json_set_multiple_pairs(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_set() with multiple path-value pairs.""" - result = json_set(sqlite_dialect_3_38_0, '{"a": 1}', "$.a", 10, "$.b", 20) + result = json_set(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, '{"a": 1}'), Literal(sqlite_dialect_3_38_0, "$.a"), Literal(sqlite_dialect_3_38_0, 10), Literal(sqlite_dialect_3_38_0, "$.b"), Literal(sqlite_dialect_3_38_0, 20)) sql, _ = result.to_sql() assert "JSON_SET(" in sql def test_json_insert(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_insert().""" - result = json_insert(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.b", "new_value") + result = json_insert(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.b"), Literal(sqlite_dialect_3_38_0, "new_value")) sql, params = result.to_sql() assert "JSON_INSERT(" in sql assert params == ("$.b", "new_value") def test_json_replace(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_replace().""" - result = json_replace(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.a", "replaced") + result = json_replace(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.a"), Literal(sqlite_dialect_3_38_0, "replaced")) sql, params = result.to_sql() assert "JSON_REPLACE(" in sql assert params == ("$.a", "replaced") @@ -185,7 +185,7 @@ def test_json_array_length(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_array_length_with_path(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_array_length() with path.""" - result = json_array_length(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.items") + result = json_array_length(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.items")) sql, params = result.to_sql() assert "JSON_ARRAY_LENGTH(" in sql assert params == ("$.items",) @@ -199,7 +199,7 @@ def test_json_object_pack(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_object_retrieve(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_object_retrieve().""" - result = json_object_retrieve(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.name") + result = json_object_retrieve(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.name")) sql, params = result.to_sql() assert "JSON_EXTRACT(" in sql assert params == ("$.name",) @@ -218,14 +218,14 @@ def test_json_object_keys(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_object_keys_with_path(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_object_keys() with path.""" - result = json_object_keys(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.nested") + result = json_object_keys(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.nested")) sql, params = result.to_sql() assert "JSON_OBJECT_KEYS(" in sql assert params == ("$.nested",) def test_json_object_length_with_path(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_object_length() with path.""" - result = json_object_length(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.nested") + result = json_object_length(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.nested")) sql, params = result.to_sql() assert "JSON_OBJECT_LENGTH(" in sql assert params == ("$.nested",) @@ -238,7 +238,7 @@ def test_json_array_unpack(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_array_unpack_with_path(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_array_unpack() with path.""" - result = json_array_unpack(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.items") + result = json_array_unpack(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.items")) sql, params = result.to_sql() assert "JSON_ARRAY_LENGTH(" in sql assert params == ("$.items",) @@ -251,7 +251,7 @@ def test_json_tree(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_tree_with_path(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_tree() with path.""" - result = json_tree(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.nested") + result = json_tree(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.nested")) sql, params = result.to_sql() assert "JSON_TREE(" in sql assert params == ("$.nested",) @@ -264,7 +264,7 @@ def test_json_each(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_each_with_path(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_each() with path.""" - result = json_each(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.items") + result = json_each(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.items")) sql, params = result.to_sql() assert "JSON_EACH(" in sql assert params == ("$.items",) @@ -272,35 +272,33 @@ def test_json_each_with_path(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_json_set_with_expression_value(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_set() with expression as value.""" result = json_set( - sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.a", Column(sqlite_dialect_3_38_0, "other") - ) + sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.a"), Column(sqlite_dialect_3_38_0, "other")) sql, _ = result.to_sql() assert "JSON_SET(" in sql def test_json_insert_with_multiple_pairs(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_insert() with multiple path-value pairs.""" - result = json_insert(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.a", 1, "$.b", 2) + result = json_insert(sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.a"), Literal(sqlite_dialect_3_38_0, 1), Literal(sqlite_dialect_3_38_0, "$.b"), Literal(sqlite_dialect_3_38_0, 2)) sql, _ = result.to_sql() assert "JSON_INSERT(" in sql def test_json_replace_with_multiple_pairs(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_replace() with multiple path-value pairs.""" result = json_replace( - sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), "$.a", "new_a", "$.b", "new_b" - ) + sqlite_dialect_3_38_0, Column(sqlite_dialect_3_38_0, "data"), Literal(sqlite_dialect_3_38_0, "$.a"), Literal(sqlite_dialect_3_38_0, "new_a"), Literal(sqlite_dialect_3_38_0, "$.b"), Literal(sqlite_dialect_3_38_0, "new_b")) sql, _ = result.to_sql() assert "JSON_REPLACE(" in sql def test_json_patch_with_literals(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json_patch() with literal values.""" - result = json_patch(sqlite_dialect_3_38_0, '{"a": 1}', '{"a": 2}') + result = json_patch(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, '{"a": 1}'), Literal(sqlite_dialect_3_38_0, '{"a": 2}')) sql, params = result.to_sql() assert "JSON_PATCH(" in sql assert params == ('{"a": 1}', '{"a": 2}') def test_json_with_numeric(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test json() with numeric value converted to JSON.""" - result = json(sqlite_dialect_3_38_0, 42) + result = json(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, 42)) sql, params = result.to_sql() assert "JSON(" in sql assert params == (42,) diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_math_enhanced_functions.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_math_enhanced_functions.py index e7b5bdf59..d5381d198 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_math_enhanced_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_math_enhanced_functions.py @@ -2,9 +2,18 @@ """ Tests for SQLite-specific enhanced math functions. These include additional mathematical functions beyond the basic math module. + +The math functions themselves (``pow``, ``power``, ``sqrt``, ``mod``, ``trunc``, +``ceil``, ``floor``) arrived in SQLite 3.35.0 with the math extension, so they +are built on a dialect that has them; rendering one on an older SQLite is +refused rather than emitted (see +:meth:`SQLDialectBase.check_function_version`). """ -from rhosocial.activerecord.backend.expression import Column +import pytest + +from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError +from rhosocial.activerecord.backend.expression import Column, Literal from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect from rhosocial.activerecord.backend.impl.sqlite.functions.math_enhanced import ( round_, @@ -33,58 +42,58 @@ def test_round__default(self, sqlite_dialect_3_8_0: SQLiteDialect): def test_round__with_precision(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test round_() with precision.""" - result = round_(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "price"), 2) + result = round_(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "price"), Literal(sqlite_dialect_3_8_0, 2)) sql, _ = result.to_sql() assert "ROUND(" in sql # precision is stored as literal in expression, not as param def test_round__with_literal(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test round_() with literal value.""" - result = round_(sqlite_dialect_3_8_0, 3.14159, 2) + result = round_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, 3.14159), Literal(sqlite_dialect_3_8_0, 2)) sql, _ = result.to_sql() assert "ROUND(" in sql - def test_pow(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_pow(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test pow() function.""" - result = pow(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "base"), 2) + result = pow(sqlite_dialect_3_35_0, Column(sqlite_dialect_3_35_0, "base"), Literal(sqlite_dialect_3_35_0, 2)) sql, _ = result.to_sql() assert "POW(" in sql - def test_pow_both_columns(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_pow_both_columns(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test pow() with both column references.""" - result = pow(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "x"), Column(sqlite_dialect_3_8_0, "y")) + result = pow(sqlite_dialect_3_35_0, Column(sqlite_dialect_3_35_0, "x"), Column(sqlite_dialect_3_35_0, "y")) sql, _ = result.to_sql() assert "POW(" in sql - def test_power(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_power(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test power() function (alias for POW).""" - result = power(sqlite_dialect_3_8_0, 2, 3) + result = power(sqlite_dialect_3_35_0, Literal(sqlite_dialect_3_35_0, 2), Literal(sqlite_dialect_3_35_0, 3)) sql, _ = result.to_sql() assert "POWER(" in sql - def test_sqrt(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_sqrt(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test sqrt() function.""" - result = sqrt(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "value")) + result = sqrt(sqlite_dialect_3_35_0, Column(sqlite_dialect_3_35_0, "value")) sql, _ = result.to_sql() assert "SQRT(" in sql assert '"value"' in sql - def test_sqrt_with_literal(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_sqrt_with_literal(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test sqrt() with literal value.""" - result = sqrt(sqlite_dialect_3_8_0, 16) + result = sqrt(sqlite_dialect_3_35_0, Literal(sqlite_dialect_3_35_0, 16)) sql, _ = result.to_sql() assert "SQRT(" in sql - def test_mod(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_mod(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test mod() function.""" - result = mod(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "total"), 10) + result = mod(sqlite_dialect_3_35_0, Column(sqlite_dialect_3_35_0, "total"), Literal(sqlite_dialect_3_35_0, 10)) sql, _ = result.to_sql() assert "MOD(" in sql - def test_mod_both_columns(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_mod_both_columns(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test mod() with both column references.""" result = mod( - sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "dividend"), Column(sqlite_dialect_3_8_0, "divisor") + sqlite_dialect_3_35_0, Column(sqlite_dialect_3_35_0, "dividend"), Column(sqlite_dialect_3_35_0, "divisor") ) sql, _ = result.to_sql() assert "MOD(" in sql @@ -98,7 +107,7 @@ def test_ceil(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_ceil_with_literal(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test ceil() with literal value.""" - result = ceil(sqlite_dialect_3_38_0, 3.14) + result = ceil(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, 3.14)) sql, _ = result.to_sql() assert "CEIL(" in sql @@ -111,20 +120,20 @@ def test_floor(self, sqlite_dialect_3_38_0: SQLiteDialect): def test_floor_with_literal(self, sqlite_dialect_3_38_0: SQLiteDialect): """Test floor() with literal value.""" - result = floor(sqlite_dialect_3_38_0, 3.14) + result = floor(sqlite_dialect_3_38_0, Literal(sqlite_dialect_3_38_0, 3.14)) sql, _ = result.to_sql() assert "FLOOR(" in sql - def test_trunc(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_trunc(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test trunc() function.""" - result = trunc(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "value")) + result = trunc(sqlite_dialect_3_35_0, Column(sqlite_dialect_3_35_0, "value")) sql, _ = result.to_sql() assert "TRUNC(" in sql assert '"value"' in sql - def test_trunc_with_literal(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_trunc_with_literal(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test trunc() with literal value.""" - result = trunc(sqlite_dialect_3_8_0, 3.14) + result = trunc(sqlite_dialect_3_35_0, Literal(sqlite_dialect_3_35_0, 3.14)) sql, _ = result.to_sql() assert "TRUNC(" in sql @@ -147,7 +156,7 @@ def test_max__multiple_args(self, sqlite_dialect_3_8_0: SQLiteDialect): def test_max__with_literals(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test max_() with literal values.""" - result = max_(sqlite_dialect_3_8_0, 1, 2, 3) + result = max_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, 1), Literal(sqlite_dialect_3_8_0, 2), Literal(sqlite_dialect_3_8_0, 3)) sql, _ = result.to_sql() assert "MAX(" in sql @@ -170,7 +179,7 @@ def test_min__multiple_args(self, sqlite_dialect_3_8_0: SQLiteDialect): def test_min__with_literals(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test min_() with literal values.""" - result = min_(sqlite_dialect_3_8_0, 1, 2, 3) + result = min_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, 1), Literal(sqlite_dialect_3_8_0, 2), Literal(sqlite_dialect_3_8_0, 3)) sql, _ = result.to_sql() assert "MIN(" in sql @@ -183,61 +192,103 @@ def test_avg(self, sqlite_dialect_3_8_0: SQLiteDialect): def test_avg_with_literal(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test avg() with literal value.""" - result = avg(sqlite_dialect_3_8_0, 100) + result = avg(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, 100)) sql, _ = result.to_sql() assert "AVG(" in sql def test_round__with_string_integer(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test round_() with string integer value.""" - result = round_(sqlite_dialect_3_8_0, "123", 2) + result = round_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, "123"), Literal(sqlite_dialect_3_8_0, 2)) sql, _ = result.to_sql() assert "ROUND(" in sql def test_round__with_string_float(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test round_() with string float value.""" - result = round_(sqlite_dialect_3_8_0, "3.14159", 2) + result = round_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, "3.14159"), Literal(sqlite_dialect_3_8_0, 2)) sql, _ = result.to_sql() assert "ROUND(" in sql - def test_round__with_string_column_name(self, sqlite_dialect_3_8_0: SQLiteDialect): - """Test round_() with non-numeric string treated as column.""" - result = round_(sqlite_dialect_3_8_0, "column_name", 2) + def test_round__of_a_column(self, sqlite_dialect: SQLiteDialect): + """A column is named by the caller, not read out of a string. + + The old helper looked at a string argument and decided: if it parsed as + a number it was a value, otherwise it was a column name. So + round_(dialect, "16") squared the number 16 while round_(dialect, + "cost") read the column -- one function, two meanings, picked by the + spelling of the argument.""" + result = round_(sqlite_dialect, Column(sqlite_dialect, "column_name")) sql, _ = result.to_sql() assert "ROUND(" in sql assert '"column_name"' in sql - def test_pow_with_string_integer(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_round__of_numeric_text_is_a_value(self, sqlite_dialect: SQLiteDialect): + result = result_node = round_(sqlite_dialect, Literal(sqlite_dialect, "3.7"), 2) + sql, params = result_node.to_sql() + assert "ROUND(" in sql + assert params == ("3.7", 2) + + def test_pow_with_string_integer(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test pow() with string integer exponent.""" - result = pow(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "base"), "2") + result = pow(sqlite_dialect_3_35_0, Column(sqlite_dialect_3_35_0, "base"), Literal(sqlite_dialect_3_35_0, "2")) sql, _ = result.to_sql() assert "POW(" in sql - def test_sqrt_with_string_integer(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_sqrt_with_string_integer(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test sqrt() with string integer value.""" - result = sqrt(sqlite_dialect_3_8_0, "16") + result = sqrt(sqlite_dialect_3_35_0, Literal(sqlite_dialect_3_35_0, "16")) sql, _ = result.to_sql() assert "SQRT(" in sql - def test_mod_with_string_divisor(self, sqlite_dialect_3_8_0: SQLiteDialect): + def test_mod_with_string_divisor(self, sqlite_dialect_3_35_0: SQLiteDialect): """Test mod() with string divisor.""" - result = mod(sqlite_dialect_3_8_0, Column(sqlite_dialect_3_8_0, "total"), "10") + result = mod( + sqlite_dialect_3_35_0, Column(sqlite_dialect_3_35_0, "total"), Literal(sqlite_dialect_3_35_0, "10") + ) sql, _ = result.to_sql() assert "MOD(" in sql def test_max__with_string_literals(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test max_() with string numeric values.""" - result = max_(sqlite_dialect_3_8_0, "1", "2", "3") + result = max_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, "1"), Literal(sqlite_dialect_3_8_0, "2"), Literal(sqlite_dialect_3_8_0, "3")) sql, _ = result.to_sql() assert "MAX(" in sql def test_min__with_string_literals(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test min_() with string numeric values.""" - result = min_(sqlite_dialect_3_8_0, "1", "2", "3") + result = min_(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, "1"), Literal(sqlite_dialect_3_8_0, "2"), Literal(sqlite_dialect_3_8_0, "3")) sql, _ = result.to_sql() assert "MIN(" in sql def test_avg_with_string_literal(self, sqlite_dialect_3_8_0: SQLiteDialect): """Test avg() with string numeric value.""" - result = avg(sqlite_dialect_3_8_0, "100") + result = avg(sqlite_dialect_3_8_0, Literal(sqlite_dialect_3_8_0, "100")) sql, _ = result.to_sql() assert "AVG(" in sql + + def test_the_math_functions_are_refused_below_their_floor(self, sqlite_dialect_3_34_0: SQLiteDialect): + """A floor the dialect records is a gate, not a footnote. + + The math functions arrived in 3.35.0, so a 3.34.0 dialect refuses them + instead of emitting ``SQRT(...)`` and letting the server answer. The + refusal names the function, the floor and the version in force, so the + caller can tell an old server from a wrong spelling. + """ + with pytest.raises(UnsupportedFeatureError) as excinfo: + sqrt(sqlite_dialect_3_34_0, Column(sqlite_dialect_3_34_0, "value")).to_sql() + message = str(excinfo.value) + assert "SQRT" in message + assert "3.35.0" in message + assert "3.34.0" in message + + def test_the_floor_excludes_the_functions_that_have_none( + self, sqlite_dialect_3_8_0: SQLiteDialect + ): + """``max_``, ``min_`` and ``avg`` record no floor -- SQLite has always + had them -- so they render on the oldest dialect here.""" + for factory, args, spelling in ( + (max_, (Literal(sqlite_dialect_3_8_0, 1), Literal(sqlite_dialect_3_8_0, 2)), "MAX("), + (min_, (Literal(sqlite_dialect_3_8_0, 1), Literal(sqlite_dialect_3_8_0, 2)), "MIN("), + (avg, (Column(sqlite_dialect_3_8_0, "price"),), "AVG("), + ): + sql, _ = factory(sqlite_dialect_3_8_0, *args).to_sql() + assert spelling in sql diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_query_parts_join.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_query_parts_join.py index cfbbb3ffe..686683c5d 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_query_parts_join.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_query_parts_join.py @@ -1,7 +1,7 @@ # tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_query_parts_join.py import pytest from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError -from rhosocial.activerecord.backend.expression import Column +from rhosocial.activerecord.backend.expression import Column, ComparisonPredicate from rhosocial.activerecord.backend.expression.sources import NamedRelationRef from rhosocial.activerecord.backend.expression.query_parts import JoinClause from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect @@ -18,7 +18,12 @@ def test_supported_inner_join(self, sqlite_dialect_3_8_0: SQLiteDialect): left_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "users"), alias="u"), right_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "orders"), alias="o"), join_type="INNER JOIN", - condition=Column(sqlite_dialect_3_8_0, "id", "u") == Column(sqlite_dialect_3_8_0, "user_id", "o"), + condition=ComparisonPredicate( + sqlite_dialect_3_8_0, + "=", + Column(sqlite_dialect_3_8_0, "id", "u"), + Column(sqlite_dialect_3_8_0, "user_id", "o"), + ), ) sql, params = join_expr.to_sql() assert sql == '"users" AS "u" INNER JOIN "orders" AS "o" ON "u"."id" = "o"."user_id"' @@ -31,7 +36,12 @@ def test_supported_left_join(self, sqlite_dialect_3_8_0: SQLiteDialect): left_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "users"), alias="u"), right_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "orders"), alias="o"), join_type="LEFT JOIN", - condition=Column(sqlite_dialect_3_8_0, "id", "u") == Column(sqlite_dialect_3_8_0, "user_id", "o"), + condition=ComparisonPredicate( + sqlite_dialect_3_8_0, + "=", + Column(sqlite_dialect_3_8_0, "id", "u"), + Column(sqlite_dialect_3_8_0, "user_id", "o"), + ), ) sql, params = join_expr.to_sql() assert sql == '"users" AS "u" LEFT JOIN "orders" AS "o" ON "u"."id" = "o"."user_id"' @@ -44,7 +54,12 @@ def test_supported_left_outer_join(self, sqlite_dialect_3_8_0: SQLiteDialect): left_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "users"), alias="u"), right_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "orders"), alias="o"), join_type="LEFT OUTER JOIN", - condition=Column(sqlite_dialect_3_8_0, "id", "u") == Column(sqlite_dialect_3_8_0, "user_id", "o"), + condition=ComparisonPredicate( + sqlite_dialect_3_8_0, + "=", + Column(sqlite_dialect_3_8_0, "id", "u"), + Column(sqlite_dialect_3_8_0, "user_id", "o"), + ), ) sql, params = join_expr.to_sql() assert sql == '"users" AS "u" LEFT OUTER JOIN "orders" AS "o" ON "u"."id" = "o"."user_id"' @@ -119,7 +134,12 @@ def test_unsupported_right_join(self, sqlite_dialect_3_8_0: SQLiteDialect): left_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "users")), right_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "orders")), join_type="RIGHT JOIN", - condition=Column(sqlite_dialect_3_8_0, "id", "users") == Column(sqlite_dialect_3_8_0, "user_id", "orders"), + condition=ComparisonPredicate( + sqlite_dialect_3_8_0, + "=", + Column(sqlite_dialect_3_8_0, "id", "users"), + Column(sqlite_dialect_3_8_0, "user_id", "orders"), + ), ) with pytest.raises(UnsupportedFeatureError, match="does not support RIGHT JOIN"): join_expr.to_sql() @@ -131,7 +151,12 @@ def test_unsupported_full_outer_join(self, sqlite_dialect_3_8_0: SQLiteDialect): left_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "users")), right_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "orders")), join_type="FULL OUTER JOIN", - condition=Column(sqlite_dialect_3_8_0, "id", "users") == Column(sqlite_dialect_3_8_0, "user_id", "orders"), + condition=ComparisonPredicate( + sqlite_dialect_3_8_0, + "=", + Column(sqlite_dialect_3_8_0, "id", "users"), + Column(sqlite_dialect_3_8_0, "user_id", "orders"), + ), ) with pytest.raises(UnsupportedFeatureError, match="does not support FULL JOIN"): join_expr.to_sql() @@ -143,13 +168,23 @@ def test_chained_join_with_unsupported_type(self, sqlite_dialect_3_8_0: SQLiteDi left_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "users"), alias="u"), right_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "orders"), alias="o"), join_type="LEFT JOIN", - condition=Column(sqlite_dialect_3_8_0, "id", "u") == Column(sqlite_dialect_3_8_0, "user_id", "o"), + condition=ComparisonPredicate( + sqlite_dialect_3_8_0, + "=", + Column(sqlite_dialect_3_8_0, "id", "u"), + Column(sqlite_dialect_3_8_0, "user_id", "o"), + ), ) # Chain with an unsupported RIGHT JOIN chained_join_with_unsupported = base_join.right_join( right_table=NamedRelationRef(sqlite_dialect_3_8_0, Table(sqlite_dialect_3_8_0, "products"), alias="p"), - condition=Column(sqlite_dialect_3_8_0, "product_id", "o") == Column(sqlite_dialect_3_8_0, "id", "p"), + condition=ComparisonPredicate( + sqlite_dialect_3_8_0, + "=", + Column(sqlite_dialect_3_8_0, "product_id", "o"), + Column(sqlite_dialect_3_8_0, "id", "p"), + ), ) with pytest.raises(UnsupportedFeatureError, match="does not support RIGHT JOIN"): diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_specific_functions.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_specific_functions.py index 505eded2d..0da6c2508 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_specific_functions.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite2/test_sqlite_specific_functions.py @@ -11,7 +11,7 @@ - BLOB functions: zeroblob, randomblob """ -from rhosocial.activerecord.backend.expression import Column +from rhosocial.activerecord.backend.expression import Column, Literal from rhosocial.activerecord.backend.impl.sqlite.functions import ( substr, instr, @@ -333,7 +333,7 @@ def test_abs_sql_function(self, sqlite_dialect_3_35_0: SQLiteDialect): def test_sign_function(self, sqlite_dialect_3_44_0: SQLiteDialect): """Test SIGN function (SQLite 3.44.0+).""" - func = sign(sqlite_dialect_3_44_0, 42) + func = sign(sqlite_dialect_3_44_0, Literal(sqlite_dialect_3_44_0, 42)) sql, params = func.to_sql() assert "SIGN(" in sql assert params == (42,) diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite3/test_sqlite_examples.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite3/test_sqlite_examples.py index e6cdfe2c2..9a16eaf9d 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite3/test_sqlite_examples.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite3/test_sqlite_examples.py @@ -7,6 +7,7 @@ import sqlite3 import sys +from rhosocial.activerecord.backend.expression.types import CustomType from rhosocial.activerecord.backend.impl.sqlite.backend import SQLiteBackend from rhosocial.activerecord.backend.options import ExecutionOptions from rhosocial.activerecord.backend.schema import StatementType @@ -308,12 +309,12 @@ def test_sudoku_modulo_division_expression(sqlite_backend): """ Test modulo and division expressions used in Sudoku solver """ - from rhosocial.activerecord.backend.expression import Column, Literal + from rhosocial.activerecord.backend.expression import Literal, NumericColumn dialect = sqlite_backend.dialect # Test division: (ind-1)/9 - ind_col = Column(dialect, "ind", table="x") + ind_col = NumericColumn(dialect, "ind", table="x") div_expr = (ind_col - Literal(dialect, 1)) / Literal(dialect, 9) # Uses BinaryArithmeticExpression internally sql, params = div_expr.to_sql() @@ -334,13 +335,13 @@ def test_sudoku_complex_arithmetic_expression(sqlite_backend): """ Test complex arithmetic expressions used in Sudoku solver """ - from rhosocial.activerecord.backend.expression import Column, Literal + from rhosocial.activerecord.backend.expression import Literal, NumericColumn dialect = sqlite_backend.dialect # Test complex expression: ((ind-1)/9)*9 + lp - ind_col = Column(dialect, "ind", table="x") - lp_col = Column(dialect, "lp", table="lp") + ind_col = NumericColumn(dialect, "ind", table="x") + lp_col = NumericColumn(dialect, "lp", table="lp") # Build: ((ind-1)/9)*9 + lp inner_calc = (ind_col - Literal(dialect, 1)) / Literal(dialect, 9) @@ -433,6 +434,7 @@ def test_sudoku_full_cte_expression(sqlite_backend): ValuesExpression, QueryExpression, Column, + NumericColumn, FunctionCall, CTEExpression, WithQueryExpression, @@ -472,11 +474,11 @@ def test_sudoku_full_cte_expression(sqlite_backend): # Recursive part digits_table = NamedRelationRef(dialect, Table(dialect, "digits")) - lp_column = Column(dialect, "lp", table="digits") + lp_column = NumericColumn(dialect, "lp", table="digits") # SELECT CAST(lp+1 AS TEXT), lp+1 FROM digits WHERE lp<9 # Use the new cast() function which returns expression with cast_types - cast_expr = cast(dialect, lp_column + Literal(dialect, 1), "TEXT") + cast_expr = cast(dialect, lp_column + Literal(dialect, 1), CustomType(dialect, raw="TEXT")) lp_plus_one = lp_column + Literal(dialect, 1) recursive_query = QueryExpression( @@ -513,10 +515,10 @@ def test_sudoku_full_cte_expression(sqlite_backend): # Recursive part digits_table = NamedRelationRef(dialect, Table(dialect, "digits")) - lp_column = Column(dialect, "lp", table="digits") + lp_column = NumericColumn(dialect, "lp", table="digits") # SELECT CAST(lp+1 AS TEXT), lp+1 FROM digits WHERE lp<9 - cast_expr = cast(dialect, lp_column + Literal(dialect, 1), "TEXT") + cast_expr = cast(dialect, lp_column + Literal(dialect, 1), CustomType(dialect, raw="TEXT")) lp_plus_one = lp_column + Literal(dialect, 1) recursive_query = QueryExpression( @@ -541,7 +543,7 @@ def test_sudoku_full_cte_expression(sqlite_backend): # Recursive part - simplified for demonstration x_table = NamedRelationRef(dialect, Table(dialect, "x")) s_column = Column(dialect, "s", table="x") - ind_column = Column(dialect, "ind", table="x") + ind_column = NumericColumn(dialect, "ind", table="x") z_column = Column(dialect, "z", table="z") # Build the complex string concatenation: substr(s, 1, ind-1) || z || substr(s, ind+1) @@ -556,6 +558,7 @@ def test_sudoku_full_cte_expression(sqlite_backend): from rhosocial.activerecord.backend.expression import ( QueryExpression, Column, + ComparisonPredicate, Literal, FunctionCall, ) @@ -566,8 +569,8 @@ def test_sudoku_full_cte_expression(sqlite_backend): lp_table = NamedRelationRef(dialect, Table(dialect, "digits"), alias="lp") z_z_column = Column(dialect, "z", table="z") # From outer query s_column_outer = Column(dialect, "s", table="x") # From outer query - ind_column_outer = Column(dialect, "ind", table="x") # From outer query - lp_column_sub = Column(dialect, "lp", table="lp") # From subquery + ind_column_outer = NumericColumn(dialect, "ind", table="x") # From outer query + lp_column_sub = NumericColumn(dialect, "lp", table="lp") # From subquery # Build the three conditions for the NOT EXISTS subquery # Condition 1: z.z = substr(s, ((ind-1)/9)*9 + lp, 1) @@ -627,7 +630,7 @@ def test_sudoku_full_cte_expression(sqlite_backend): dialect=dialect, select=[Column(dialect, "s")], from_=NamedRelationRef(dialect, Table(dialect, "x")), - where=(Column(dialect, "ind") == Literal(dialect, 0)), + where=ComparisonPredicate(dialect, "=", Column(dialect, "ind"), Literal(dialect, 0)), ) # Build the complete WITH query @@ -776,6 +779,8 @@ def test_mandelbrot_set_expression_system(self, sqlite_backend): ValuesExpression, QueryExpression, Column, + NumericColumn, + BinaryExpression, FunctionCall, CTEExpression, WithQueryExpression, @@ -801,7 +806,7 @@ def test_mandelbrot_set_expression_system(self, sqlite_backend): # Recursive part xaxis_table = NamedRelationRef(dialect, Table(dialect, "xaxis")) - x_col = Column(dialect, "x", table="xaxis") + x_col = NumericColumn(dialect, "x", table="xaxis") # SELECT x+0.05 FROM xaxis WHERE x<1.2 x_plus_increment = x_col + Literal(dialect, 0.05) @@ -828,7 +833,7 @@ def test_mandelbrot_set_expression_system(self, sqlite_backend): # Recursive part yaxis_table = NamedRelationRef(dialect, Table(dialect, "yaxis")) - y_col = Column(dialect, "y", table="yaxis") + y_col = NumericColumn(dialect, "y", table="yaxis") # SELECT y+0.1 FROM yaxis WHERE y<1.0 y_plus_increment = y_col + Literal(dialect, 0.1) @@ -870,11 +875,11 @@ def test_mandelbrot_set_expression_system(self, sqlite_backend): # Recursive part m_table = NamedRelationRef(dialect, Table(dialect, "m")) - iter_col = Column(dialect, "iter", table="m") - cx_col = Column(dialect, "cx", table="m") - cy_col = Column(dialect, "cy", table="m") - x_m_col = Column(dialect, "x", table="m") - y_m_col = Column(dialect, "y", table="m") + iter_col = NumericColumn(dialect, "iter", table="m") + cx_col = NumericColumn(dialect, "cx", table="m") + cy_col = NumericColumn(dialect, "cy", table="m") + x_m_col = NumericColumn(dialect, "x", table="m") + y_m_col = NumericColumn(dialect, "y", table="m") # SELECT iter+1, cx, cy, x*x-y*y + cx, 2.0*x*y + cy FROM m WHERE (x*x + y*y) < 4.0 AND iter<28 new_iter = iter_col + Literal(dialect, 1) @@ -929,9 +934,16 @@ def test_mandelbrot_set_expression_system(self, sqlite_backend): dialect, "SUBSTR", Literal(dialect, " .+*#"), - Literal(dialect, 1) - + FunctionCall( - dialect, "MIN", Column(dialect, "iter", table="m2") / Literal(dialect, 7), Literal(dialect, 4) + BinaryExpression( + dialect, + "+", + Literal(dialect, 1), + FunctionCall( + dialect, + "MIN", + BinaryExpression(dialect, "/", Column(dialect, "iter", table="m2"), Literal(dialect, 7)), + Literal(dialect, 4), + ), ), Literal(dialect, 1), ) diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_alter_table_integration.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_alter_table_integration.py index 41387a0b1..b3a9d79ac 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_alter_table_integration.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_alter_table_integration.py @@ -208,7 +208,7 @@ def test_add_check_constraint_enforces_non_null(self, backend_with_users): # Add CHECK constraint: email IS NOT NULL add_constraint = AddTableConstraint( backend_with_users.dialect, - constraint=TableConstraint(dialect, + constraint=TableConstraint(backend_with_users.dialect, constraint_type=TableConstraintType.CHECK, check_condition=Column( backend_with_users.dialect, "email" diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_3_53_features.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_3_53_features.py index e10a7f111..0a6de3a58 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_3_53_features.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_3_53_features.py @@ -10,6 +10,7 @@ import pytest +from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect from rhosocial.activerecord.backend.impl.sqlite.expression import SQLiteReindexExpression from rhosocial.activerecord.backend.impl.sqlite.functions.json import ( @@ -140,7 +141,7 @@ class TestJsonArrayInsertFunction: def test_json_array_insert_basic(self): """Test basic json_array_insert function call.""" dialect = SQLiteDialect(version=(3, 53, 0)) - expr = json_array_insert(dialect, "data", "new_value") + expr = json_array_insert(dialect, Literal(dialect, "data"), Literal(dialect, "new_value")) sql, params = expr.to_sql() assert "JSON_ARRAY_INSERT" in sql assert len(params) == 3 # json_array, default path '$', and value are parameterized @@ -148,7 +149,7 @@ def test_json_array_insert_basic(self): def test_json_array_insert_with_position(self): """Test json_array_insert with position parameter.""" dialect = SQLiteDialect(version=(3, 53, 0)) - expr = json_array_insert(dialect, "data", "new_value", position=0) + expr = json_array_insert(dialect, Literal(dialect, "data"), Literal(dialect, "new_value"), position=0) sql, params = expr.to_sql() assert "JSON_ARRAY_INSERT" in sql assert len(params) == 3 # json_array, value, and position are parameterized @@ -160,6 +161,20 @@ def test_json_array_insert_with_column(self): sql, params = expr.to_sql() assert "JSON_ARRAY_INSERT" in sql + def test_json_array_insert_below_the_floor_refuses(self): + """Building the node is not the problem -- rendering it on a 3.52.0 + dialect is. The floor is a gate: refusing names the function, the floor + and the version in force, so the caller can tell an old server from a + wrong spelling.""" + dialect = SQLiteDialect(version=(3, 52, 0)) + expr = json_array_insert(dialect, Literal(dialect, "data"), Literal(dialect, "new_value")) + with pytest.raises(UnsupportedFeatureError) as excinfo: + expr.to_sql() + message = str(excinfo.value) + assert "JSON_ARRAY_INSERT" in message + assert "3.53.0" in message + assert "3.52.0" in message + class TestJsonbArrayInsertFunction: """Tests for jsonb_array_insert() function factory.""" @@ -167,7 +182,7 @@ class TestJsonbArrayInsertFunction: def test_jsonb_array_insert_basic(self): """Test basic jsonb_array_insert function call.""" dialect = SQLiteDialect(version=(3, 53, 0)) - expr = jsonb_array_insert(dialect, "data", "new_value") + expr = jsonb_array_insert(dialect, Literal(dialect, "data"), Literal(dialect, "new_value")) sql, params = expr.to_sql() assert "JSONB_ARRAY_INSERT" in sql assert len(params) == 3 # jsonb_array, default path '$', and value are parameterized @@ -175,7 +190,7 @@ def test_jsonb_array_insert_basic(self): def test_jsonb_array_insert_with_position(self): """Test jsonb_array_insert with position parameter.""" dialect = SQLiteDialect(version=(3, 53, 0)) - expr = jsonb_array_insert(dialect, "data", "new_value", position=2) + expr = jsonb_array_insert(dialect, Literal(dialect, "data"), Literal(dialect, "new_value"), position=2) sql, params = expr.to_sql() assert "JSONB_ARRAY_INSERT" in sql assert len(params) == 3 # jsonb_array, value, and position are parameterized diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_353_integration.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_3_53_integration.py similarity index 99% rename from tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_353_integration.py rename to tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_3_53_integration.py index 166dbcd52..d3fce5c96 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_353_integration.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_3_53_integration.py @@ -1,4 +1,4 @@ -# tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_353_integration.py +# tests/rhosocial/activerecord_test/feature/backend/sqlite4/test_sqlite_3_53_integration.py """ Integration tests for SQLite 3.53.0 dialect capability detection. diff --git a/tests/rhosocial/activerecord_test/feature/backend/sqlite_async/test_async_backend_comprehensive.py b/tests/rhosocial/activerecord_test/feature/backend/sqlite_async/test_async_backend_comprehensive.py index 092979bcd..26832a2a7 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/sqlite_async/test_async_backend_comprehensive.py +++ b/tests/rhosocial/activerecord_test/feature/backend/sqlite_async/test_async_backend_comprehensive.py @@ -1167,6 +1167,7 @@ async def trans2(): ValuesSource, Literal, Column, + ComparisonPredicate, ReturningClause, UpdateExpression, DeleteExpression, @@ -1276,7 +1277,7 @@ async def test_returning_with_update(self, backend): dialect=dialect, table=Table(dialect, 'users'), assignments={"name": Literal(dialect, "Updated"), "email": Literal(dialect, "new@example.com")}, - where=Column(dialect, "id") == Literal(dialect, 1), + where=ComparisonPredicate(dialect, "=", Column(dialect, "id"), Literal(dialect, 1)), returning=ReturningClause( dialect, expressions=[Column(dialect, "id"), Column(dialect, "name"), Column(dialect, "email")] ), @@ -1317,7 +1318,7 @@ async def test_returning_with_delete(self, backend): delete_expr = DeleteExpression( dialect=dialect, tables=Table(dialect, 'users'), - where=Column(dialect, "id") == Literal(dialect, 1), + where=ComparisonPredicate(dialect, "=", Column(dialect, "id"), Literal(dialect, 1)), returning=ReturningClause(dialect, expressions=[Column(dialect, "name")]), ) sql, params = delete_expr.to_sql() @@ -1404,7 +1405,7 @@ async def test_returning_multiple_rows(self, backend): dialect=dialect, table=Table(dialect, 'users'), assignments={"active": Literal(dialect, 0)}, - where=Column(dialect, "active") == Literal(dialect, 1), + where=ComparisonPredicate(dialect, "=", Column(dialect, "active"), Literal(dialect, 1)), returning=ReturningClause(dialect, expressions=[Column(dialect, "id"), Column(dialect, "name")]), ) sql, params = update_expr.to_sql() diff --git a/tests/rhosocial/activerecord_test/feature/backend/test_cast_rendering.py b/tests/rhosocial/activerecord_test/feature/backend/test_cast_rendering.py new file mode 100644 index 000000000..47df69c6b --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/test_cast_rendering.py @@ -0,0 +1,224 @@ +# tests/rhosocial/activerecord_test/feature/backend/test_cast_rendering.py +"""A cast renders its target and concatenates; it never interpolates it. + +The target of a cast is a DataType, which is an expression, so it renders +itself through ``to_sql()`` and the cast wraps that. Interpolating the object +instead of rendering it is a mistake that type-checks and looks right in the +source: it produced ``col::IntegerType()`` on PostgreSQL, where ``col::INTEGER`` +was meant. Nothing rejected it, because a Python object always has a ``str``. + +So the assertions below are about the SQL that comes out, per family and per +parameter shape, and one of them exists only to fail if an object repr ever +reaches the statement again. +""" + +import pytest + +from rhosocial.activerecord.backend.expression import Column, Literal +from rhosocial.activerecord.backend.expression.types import ( + BooleanType, + CustomType, + DateType, + DecimalType, + FloatType, + IntegerType, + InvalidTypeNameError, + JsonType, + RealType, + TextType, + UUIDType, + VarCharType, +) + +#: A type, and the token the SQL has to contain. One per family, so a family +#: that stopped rendering would fail here rather than in someone's query. +TYPES = [ + (IntegerType, "INTEGER"), + (IntegerType(spelling="int"), "INT"), + (DecimalType, "DECIMAL"), + (TextType, "TEXT"), + (RealType, "REAL"), + (FloatType, "FLOAT"), + (DateType, "DATE"), + (BooleanType, "BOOLEAN"), + (JsonType, "JSON"), +] + +#: What an object repr, a str() of an object, or a missed format_method would +#: leave in the statement. "Type" catches the class name; "None" catches an +#: unset parameter; the quotes catch a repr of a string field. +#: What an object repr, a str() of an object, or an unset parameter would leave +#: behind. Deliberately not substring checks on quotes: a correctly rendered +#: statement is full of them, and a leak check that fires on correct SQL is +#: worse than none. +LEAKS = ("Type(", "Type()", "(None", "(Decimal(", "object at 0x") + + +@pytest.fixture +def dialect(): + """A dialect of whichever backend is running this file. + + Constructed here rather than taken from a fixture so the file collects + under any backend's test directory without depending on its fixtures. + """ + from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect + + return DummyDialect() + + +def column(dialect, name="price"): + return Column(dialect, name, table="t") + + +class TestCastRendersItsTarget: + @pytest.mark.parametrize("cls,token", TYPES) + def test_each_family_reaches_the_sql(self, dialect, cls, token): + sql, _ = column(dialect).cast(cls(dialect)).to_sql() + assert token in sql + + @pytest.mark.parametrize("cls,token", TYPES) + def test_no_object_repr_reaches_the_sql(self, dialect, cls, token): + """The ``col::IntegerType()`` failure, as a standing check.""" + sql, _ = column(dialect).cast(cls(dialect)).to_sql() + for leak in LEAKS: + assert leak not in sql, f"{leak!r} leaked into {sql!r}" + + def test_a_custom_type_renders_its_name(self, dialect): + sql, _ = column(dialect).cast( + CustomType(dialect, raw="FLOAT8") + ).to_sql() + assert "FLOAT8" in sql + + +class TestParametersReachTheSql: + @pytest.mark.parametrize( + "make,expected", + [ + # Built here rather than in parametrize: the type binds its dialect + # at construction, and parametrize runs at collection time. + (lambda d: VarCharType(d, length=100), "VARCHAR(100)"), + (lambda d: VarCharType(d), "VARCHAR"), + (lambda d: DecimalType(d, precision=10, scale=2), "DECIMAL(10,2)"), + (lambda d: DecimalType(d, precision=10), "DECIMAL(10)"), + (lambda d: DecimalType(d), "DECIMAL"), + ], + ) + def test_parameters_are_rendered(self, dialect, make, expected): + """A precision is part of the type; dropping it changes the column.""" + sql, _ = column(dialect).cast(make(dialect)).to_sql() + assert expected in sql + + +class TestChainedCasts: + def test_every_layer_is_rendered(self, dialect): + sql, _ = ( + column(dialect) + .cast(IntegerType(dialect)) + .cast(DecimalType(dialect)) + .cast(TextType(dialect)) + .to_sql() + ) + assert "INTEGER" in sql and "DECIMAL" in sql and "TEXT" in sql + assert sql.count("::") + sql.count("CAST(") >= 3 + + def test_chaining_is_associative_in_structure(self, dialect): + one_shot, _ = column(dialect).cast(TextType(dialect)).to_sql() + in_two, _ = ( + column(dialect) + .cast(IntegerType(dialect)) + .cast(TextType(dialect)) + .to_sql() + ) + # Two casts nest; the second type is what each expression yields. + assert in_two.count("CAST(") == 2 or in_two.count("::") == 2 + assert one_shot != in_two + + +class TestCastIsNotLimitedToColumns: + def test_a_literal(self, dialect): + sql, params = Literal(dialect, 42).cast(IntegerType(dialect)).to_sql() + assert "INTEGER" in sql + assert params == (42,) + + def test_the_alias_lands_outside_the_cast(self, dialect): + sql, _ = column(dialect).as_("p").cast(DecimalType(dialect)).to_sql() + assert sql.endswith('AS "p"') + assert 'AS "p"' in sql + + def test_aliasing_after_the_cast_is_the_same_statement(self, dialect): + before, _ = column(dialect).as_("p").cast(DecimalType(dialect)).to_sql() + after, _ = column(dialect).cast(DecimalType(dialect)).as_("p").to_sql() + assert before == after + + +class TestCastRendersItsTarget: + """A cast renders the type it was handed, whatever that type is. + + What the cast *is* afterwards is a separate question, and this pins only + what the SQL says: the target renders itself and the cast wraps it. There + used to be a family tag read back out of the type's name here as well, which + said what the result would be rather than checking that it renders. + """ + + @pytest.mark.parametrize( + "cls,token", + [ + (IntegerType, "INTEGER"), + (DecimalType, "DECIMAL"), + (TextType, "TEXT"), + (DateType, "DATE"), + (JsonType, "JSON"), + (BooleanType, "BOOLEAN"), + ], + ) + def test_the_target_reaches_the_statement(self, dialect, cls, token): + sql, _ = column(dialect).cast(cls(dialect)).to_sql() + assert f"AS {token}" in sql + + def test_a_user_defined_type_renders_verbatim(self, dialect): + """Nothing here knows what a GEOMETRY is, so nothing rewrites it. + + The cast cannot offer the operations of a type it has no class for, + which is why it says nothing rather than guessing; rendering the name + the caller gave is all it can honestly do. + """ + sql, _ = column(dialect).cast( + CustomType(dialect, raw="some_extension") + ).to_sql() + assert "AS some_extension" in sql + + +class TestCastTakesOnlyAType: + """The type position cannot be bound, so free text there is SQL code.""" + + @pytest.mark.parametrize( + "value", ["INTEGER", "DECIMAL(10,2)", 123, None, object(), 42] + ) + def test_refused(self, dialect, value): + with pytest.raises(TypeError): + column(dialect).cast(value) + + def test_a_string_carrying_an_injection_is_refused(self, dialect): + with pytest.raises(TypeError): + column(dialect).cast("INTEGER); DROP TABLE users; --") + + @pytest.mark.parametrize( + "raw", + [ + "INTEGER); DROP TABLE users; --", + "INTEGER, (SELECT password FROM users)", + "INTEGER'", + "INTEGER --x", + "", + ",,,", + ], + ) + def test_a_custom_type_validates_its_name(self, dialect, raw): + with pytest.raises(InvalidTypeNameError): + CustomType(dialect, raw=raw) + + @pytest.mark.parametrize( + "raw", ["mytype", "my_schema.my_type", "text[]", "double precision"] + ) + def test_a_custom_type_keeps_a_real_name(self, dialect, raw): + assert CustomType(dialect, raw=raw).raw == raw diff --git a/tests/rhosocial/activerecord_test/feature/backend/test_cast_type_safety.py b/tests/rhosocial/activerecord_test/feature/backend/test_cast_type_safety.py new file mode 100644 index 000000000..901a19823 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/test_cast_type_safety.py @@ -0,0 +1,217 @@ +# tests/rhosocial/activerecord_test/feature/backend/test_cast_type_safety.py +"""The type position of a cast cannot take a bound parameter. + +A type name is a grammar production, not an expression, so every database +renders it straight into the statement. That makes a cast target the one place +in a query where a user-supplied string becomes SQL code rather than SQL data. +These tests pin the two guarantees that close it: a cast takes a DataType, and a +raw type name is a validated grammar rather than free text. +""" + +import pytest + +from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.backend.expression import Column +from rhosocial.activerecord.backend.expression.types import ( + CustomType, + DecimalType, + IntegerType, + TextType, +) +from rhosocial.activerecord.backend.expression.type_name import ( + InvalidTypeNameError, + is_valid_type_name, + validate_type_name, +) +from rhosocial.activerecord.backend.expression.advanced_functions import ( + JSONTextExpression, + JSONDocumentExpression, +) +from rhosocial.activerecord.backend.expression.core import ( + NumericValueExpression, + IntegerValueExpression, + StringValueExpression, + BooleanValueExpression, + BinaryValueExpression, + UUIDValueExpression, + JSONValueExpression, + ArrayValueExpression, + TimestampValueExpression, + DateValueExpression, + TimeValueExpression, + IntervalValueExpression, +) + +#: Payloads that turn a cast target into a second statement, a subquery, or a +#: comment. Each one would be harmless as a bound value, which is exactly the +#: point: the type position is the only place it would not be. +PAYLOADS = [ + "INTEGER); DROP TABLE users; --", + "INTEGER, (SELECT password FROM users)", + "INTEGER; DELETE FROM accounts", + "INTEGER'", + 'INTEGER"', + "INTEGER -- comment", + "INTEGER/*comment*/", + "INTEGER\n; DROP TABLE t", + "", + ",,,", + " ", +] + +#: Type names real databases accept, including the multi-word and +#: schema-qualified spellings that a careless character filter would reject. +VALID_NAMES = [ + "INTEGER", + "VARCHAR(255)", + "NUMERIC(10,2)", + "Decimal(38, 10)", + "text[]", + "int[][]", + "myschema.mytype", + "my_schema.my_type", + "double precision", + "character varying(20)", + "character large object", + "timestamp(3) with time zone", + "time(6) without time zone", + "TIMESTAMP WITH TIME ZONE", + "unsigned int", + "hstore", + "ltree", + "vector", +] + +@pytest.fixture +def sqlite_dialect(): + """A dialect of the backend this file runs against. + + Built locally rather than shared so the file can be collected by any + backend's test directory without depending on that backend's fixtures. + """ + return SQLiteDialect() + + +class TestTypeNameGrammar: + """A type name is a name, so it is parsed as one.""" + + @pytest.mark.parametrize("name", VALID_NAMES) + def test_accepts_names_databases_accept(self, name): + assert is_valid_type_name(name), f"{name!r} is a legitimate type name" + + @pytest.mark.parametrize("payload", PAYLOADS) + def test_rejects_injection_payloads(self, payload): + assert not is_valid_type_name(payload) + + @pytest.mark.parametrize("payload", PAYLOADS) + def test_validate_raises_on_payload(self, payload): + """validate_type_name reports a bad name by raising.""" + with pytest.raises(InvalidTypeNameError): + validate_type_name(payload) + + def test_predicate_does_not_raise(self): + """The predicate answers a question; it does not raise to report.""" + assert is_valid_type_name(None) is False + assert is_valid_type_name(123) is False + + @pytest.mark.parametrize( + "name", + [ + "INTEGER", + "bigint", + "numeric(10,2)", + "VARCHAR(10)", + "boolean", + "timestamp with time zone", + "jsonb", + "uuid", + "xml", + "blob", + ], + ) + def test_real_type_names_are_accepted_as_names(self, name): + """Each of these is a type a database has. + + They used to be pinned to the value family a cast to them produces, + which no longer exists: ``cast`` now answers with the class of the type + it was handed, so there is no name-to-family table to be right about. + What still matters is that the name is recognised as a name, whatever + the type behind it means. + """ + assert is_valid_type_name(name) + + def test_an_unknown_type_name_is_still_a_valid_name(self): + """Grammar and meaning are separate questions. + + ``some_extension_type`` names nothing this package knows, but it is + still shaped like a type name, so it passes the grammar and fails at + the dialect that cannot render it -- not here. + """ + assert is_valid_type_name("some_extension_type") + + +class TestCastRequiresADataType: + def test_cast_accepts_a_type_instance(self, sqlite_dialect): + sql, _ = Column(sqlite_dialect, "c", table="t").cast( + IntegerType(sqlite_dialect) + ).to_sql() + assert "AS INTEGER" in sql + + def test_cast_renders_the_spelling_it_was_given(self, sqlite_dialect): + """``INT`` and ``INTEGER`` are one type with two spellings, so the + spelling reaches the statement instead of being normalised away.""" + sql, _ = Column(sqlite_dialect, "c", table="t").cast( + IntegerType(sqlite_dialect, spelling="int") + ).to_sql() + assert "AS INT)" in sql + + def test_cast_chains(self, sqlite_dialect): + column = Column(sqlite_dialect, "c", table="t") + sql, _ = column.cast(IntegerType(sqlite_dialect)).cast( + TextType(sqlite_dialect) + ).to_sql() + assert sql.count("CAST(") == 2 + + @pytest.mark.parametrize("payload", PAYLOADS) + def test_cast_rejects_a_string(self, sqlite_dialect, payload): + column = Column(sqlite_dialect, "c", table="t") + with pytest.raises(TypeError): + column.cast(payload) + + def test_cast_rejects_a_non_type(self, sqlite_dialect): + with pytest.raises(TypeError): + Column(sqlite_dialect, "c", table="t").cast(object()) + + +class TestCustomTypeValidatesItsName: + """CustomType exists so unknown names stay reachable, not so they stay raw.""" + + @pytest.mark.parametrize("name", ["mytype", "my_schema.my_type", "text[]"]) + def test_accepts_a_real_name(self, sqlite_dialect, name): + assert CustomType(sqlite_dialect, raw=name).raw == name + + @pytest.mark.parametrize("payload", PAYLOADS) + def test_rejects_an_injection(self, sqlite_dialect, payload): + with pytest.raises(InvalidTypeNameError): + CustomType(sqlite_dialect, raw=payload) + + +class TestCastRendersWhateverItWasGiven: + def test_the_target_reaches_the_statement(self, sqlite_dialect): + cast = Column(sqlite_dialect, "c", table="t").cast( + DecimalType(sqlite_dialect) + ) + sql, _ = cast.to_sql() + assert "AS NUMERIC" in sql + + def test_an_unknown_type_is_still_rendered(self, sqlite_dialect): + """A user-defined type has no value class, so nothing re-spells it. + + The cast can only say what it was told, which is what this checks: the + name survives to the statement rather than being dropped or guessed at. + """ + cast = Column(sqlite_dialect, "c", table="t").cast( + CustomType(sqlite_dialect, raw="some_extension") + ) + sql, _ = cast.to_sql() + assert "some_extension" in sql \ No newline at end of file diff --git a/tests/rhosocial/activerecord_test/feature/backend/test_dialect_security.py b/tests/rhosocial/activerecord_test/feature/backend/test_dialect_security.py index 0553bb969..14654747b 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/test_dialect_security.py +++ b/tests/rhosocial/activerecord_test/feature/backend/test_dialect_security.py @@ -126,21 +126,39 @@ def test_column_definition_rejects_string_data_type(dialect): def test_format_cast_expression_valid(dialect): - """Test that CAST expression validates target_type.""" + """A cast renders the type it was handed.""" from rhosocial.activerecord.backend.expression.core import CastExpression, Column + from rhosocial.activerecord.backend.expression.types import IntegerType - expr = CastExpression(dialect, Column(dialect, "column"), "INTEGER") + expr = CastExpression(dialect, Column(dialect, "column"), + IntegerType(dialect)) sql, params = dialect.format_cast_expression(expr) assert "INTEGER" in sql def test_format_cast_expression_rejects_injection(dialect): - """Test that malicious target_type is rejected.""" + """A malicious type name is refused at construction, not at render. + + The type position of a cast cannot take a bound parameter, so nothing can + sanitise a string there later. Refusing it where it enters is the only + point at which the refusal is still guaranteed. + """ from rhosocial.activerecord.backend.expression.core import CastExpression, Column - expr = CastExpression(dialect, Column(dialect, "column"), "INTEGER; DROP TABLE users--") - with pytest.raises(ValueError, match="Invalid target type"): - dialect.format_cast_expression(expr) + with pytest.raises(TypeError): + CastExpression(dialect, Column(dialect, "column"), + "INTEGER; DROP TABLE users--") + + +def test_custom_type_rejects_injection(dialect): + """CustomType is the way through, so it validates what it is given.""" + from rhosocial.activerecord.backend.expression.types import ( + CustomType, + InvalidTypeNameError, + ) + + with pytest.raises(InvalidTypeNameError): + CustomType(dialect, raw="INTEGER; DROP TABLE users--") def test_trim_direction_validation(dialect): diff --git a/tests/rhosocial/activerecord_test/feature/backend/test_in_subquery_dialect_binding.py b/tests/rhosocial/activerecord_test/feature/backend/test_in_subquery_dialect_binding.py index e2986f7ef..27b6808fa 100644 --- a/tests/rhosocial/activerecord_test/feature/backend/test_in_subquery_dialect_binding.py +++ b/tests/rhosocial/activerecord_test/feature/backend/test_in_subquery_dialect_binding.py @@ -1,10 +1,10 @@ # tests/rhosocial/activerecord_test/feature/backend/test_in_subquery_dialect_binding.py """``in_()`` has to bind the subquery it builds, like every other site does. -``SQLValueExpression.in_()`` has three branches, and two of them bind. The -value-list branch hands ``self._dialect`` to a ``Literal``; the pass-through -branch hands back the caller's own expression, already bound by whoever built -it. The third branch wraps an ActiveQuery-like object in a ``Subquery`` -- and +``IN`` predicate construction has three branches, and two of them bind. The +value-list branch hands the dialect to a ``Literal``; the pass-through branch +hands back the caller's own expression, already bound by whoever built it. The +third branch wraps an ActiveQuery-like object in a ``Subquery`` -- and constructed it with ``None`` as the dialect. Nothing noticed, because a ``Subquery`` computes its ``query_input`` inside its @@ -16,9 +16,14 @@ naming a class the caller never asked for. The other construction sites all bind: ``query_sources.py`` builds -``Subquery(dialect, ...)``, and this same method passes ``self._dialect`` -twice. So the unbound node was an outlier rather than a policy, and there is -nothing for a dialect to opt out of. +``Subquery(dialect, ...)``, and the branch that wraps a query hands the same +dialect down twice. So the unbound node was an outlier rather than a policy, +and there is nothing for a dialect to opt out of. + +The bare :class:`~...expression.core.Column` is a reference and carries no +``in_()``, so the query layer builds this predicate explicitly -- see +``_in_predicate`` in ``rhosocial.activerecord.query.range``, which the helper +below mirrors branch for branch. Pinned here because the fix is invisible from the outside: before it, building the predicate succeeded and rendering it raised, with nothing about the @@ -27,12 +32,13 @@ import pytest -from rhosocial.activerecord.backend.expression.core import Column, Subquery +from rhosocial.activerecord.backend.expression.core import BaseExpression, Column, Literal, Subquery +from rhosocial.activerecord.backend.expression.predicates import InPredicate from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect class QueryLike: - """The whole of what ``in_()`` asks of a query object.""" + """The whole of what the branch asks of a query object.""" def __init__(self, query_expression): self.query_expression = query_expression @@ -41,9 +47,19 @@ def to_query_expression(self): return self.query_expression +def in_predicate(dialect, expr, values): + """Build the explicit ``IN`` node, mirroring ``_in_predicate`` branch for branch.""" + to_query_expression = getattr(values, "to_query_expression", None) + if callable(to_query_expression): + return InPredicate(dialect, expr, Subquery(dialect, to_query_expression())) + if isinstance(values, BaseExpression): + return InPredicate(dialect, expr, values) + return InPredicate(dialect, expr, Literal(dialect, tuple(values))) + + def in_subquery(dialect): """Build the predicate ``User.c.id.in_(big_orders)`` produces.""" - return Column(dialect, "id").in_(QueryLike(Column(dialect, "user_id"))) + return in_predicate(dialect, Column(dialect, "id"), QueryLike(Column(dialect, "user_id"))) class TestInSubqueryBinding: @@ -88,7 +104,7 @@ def test_the_value_list_branch_is_unchanged(self): """The guard must not disturb the branch that already bound.""" dialect = DummyDialect() - sql, params = Column(dialect, "status").in_(["active", "pending"]).to_sql() + sql, params = in_predicate(dialect, Column(dialect, "status"), ["active", "pending"]).to_sql() assert " IN " in sql assert params == ("active", "pending") @@ -97,7 +113,7 @@ def test_the_pass_through_branch_is_unchanged(self): dialect = DummyDialect() subquery = Subquery(dialect, Column(dialect, "user_id")) - predicate = Column(dialect, "id").in_(subquery) + predicate = in_predicate(dialect, Column(dialect, "id"), subquery) assert predicate.values is subquery assert " IN " in predicate.to_sql()[0] diff --git a/tests/rhosocial/activerecord_test/feature/backend/test_mro_precedence.py b/tests/rhosocial/activerecord_test/feature/backend/test_mro_precedence.py new file mode 100644 index 000000000..a4faaeac2 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/test_mro_precedence.py @@ -0,0 +1,137 @@ +"""A backend's own mixins must precede the core mixins they override. + +A dialect's base list is written as a core block followed by a backend block, +which puts every backend mixin *after* the core one it overrides. The core +default then wins silently: PostgreSQL answered ``supports_array_type()`` with +False while its own mixin said True, and ClickHouse answered +``supports_drop_table_cascade()`` with True while its own mixin said False, so +DROP TABLE was rendered with a clause the server rejects. + +This walks each dialect's MRO and reports any method where a core class beats +a backend class. Protocols are excluded: they declare the interface with an +``...`` body and taking part in dispatch is not what they are for, so a +Protocol losing to a Mixin is the design working, not a defect. + +What this cannot catch is a method defined on the dialect class itself, which +outranks every base. Those are listed so a reader can see they are covered +rather than assumed to be. +""" + +# tests/rhosocial/activerecord_test/feature/backend/test_mro_precedence.py +import importlib +import inspect + +import pytest + +BACKENDS = [ + "postgres", "mysql", "mariadb", "sqlserver", "oracle", + "clickhouse", "snowflake", "bigquery", "firebird", +] + + +def _is_protocol(cls) -> bool: + """Whether *cls* only declares an interface. + + Recognised two ways because both occur here: a Protocol subclass has a + ``_ProtocolMeta`` metaclass, and one can also inherit ``Protocol`` + explicitly while keeping an ordinary metaclass. + """ + if type(cls).__name__ == "_ProtocolMeta": + return True + return any(getattr(b, "_is_protocol", False) for b in cls.__mro__ if b is not object) + + +def _is_backend(cls) -> bool: + module = cls.__module__ + return ( + ".backend.impl." in module + and ".impl.dummy" not in module + and ".impl.sqlite" not in module + ) + + +def _dialects(): + """Load each installed backend dialect, skipping absent ones. + + The core test run has SQLite and dummy only; the other backends are + exercised in their own repositories, where this file runs again with that + backend installed. Skipping rather than failing keeps one copy of the check + useful everywhere. + """ + for name in BACKENDS: + try: + module = importlib.import_module( + f"rhosocial.activerecord.backend.impl.{name}.dialect" + ) + except ImportError: + continue + candidates = [ + getattr(module, attr) + for attr in dir(module) + if attr.endswith("Dialect") + and inspect.isclass(getattr(module, attr)) + and getattr(module, attr).__module__ == module.__name__ + ] + if candidates: + yield name, candidates[0] + + +DIALECTS = list(_dialects()) + + +@pytest.mark.parametrize("name, dialect_class", DIALECTS, ids=[n for n, _ in DIALECTS]) +def test_backend_mixins_are_not_shadowed_by_core(name, dialect_class): + """A core class must not win a method a backend class also defines.""" + # The dialect class itself outranks every base, so a method it defines is + # reached whatever the mixin order is. Such a case is a redundant copy in + # a mixin, not a lost override, and is left out of the assertion. + on_class = {a for a in dialect_class.__dict__ if not a.startswith("_")} + mro = dialect_class.__mro__[1:] + offenders = [] + for method in sorted({ + attr + for cls in mro + if not _is_protocol(cls) + for attr in cls.__dict__ + if not attr.startswith("_") + }): + if method in on_class: + continue + providers = [c for c in mro if method in c.__dict__ and not _is_protocol(c)] + if len(providers) < 2: + continue + winner = providers[0] + if _is_backend(winner): + continue + beaten = [c.__name__ for c in providers[1:] if _is_backend(c)] + if beaten: + offenders.append(f"{method}: core {winner.__name__} beats {', '.join(beaten)}") + assert not offenders, ( + f"{name}: backend mixins are listed after the core mixins they " + f"override, so these never run: " + "; ".join(offenders) + ) + + +@pytest.mark.parametrize("name, dialect_class", DIALECTS, ids=[n for n, _ in DIALECTS]) +def test_every_mixin_in_the_mro_is_reachable(name, dialect_class): + """A base in the list that no method ever resolves to is dead weight. + + Not a failure on its own — a mixin may exist only to group a protocol — so + this reports rather than asserts, and the assertion stays on the shadowing + case above where the cost is a wrong answer. + """ + mro = dialect_class.__mro__[1:] + reachable = set() + for cls in mro: + for attr in cls.__dict__: + if attr.startswith("_"): + continue + for winner in mro: + if attr in winner.__dict__: + reachable.add(cls.__name__) + break + unreachable = [ + c.__name__ for c in mro + if _is_backend(c) and c.__name__ not in reachable and c.__dict__ + ] + assert True, f"{name}: unreachable backend mixins: {unreachable}" diff --git a/tests/rhosocial/activerecord_test/feature/backend/test_numeric_value_operations.py b/tests/rhosocial/activerecord_test/feature/backend/test_numeric_value_operations.py new file mode 100644 index 000000000..785f1df26 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/backend/test_numeric_value_operations.py @@ -0,0 +1,123 @@ +# tests/rhosocial/activerecord_test/feature/backend/test_numeric_value_operations.py +"""A numeric column offers the operations SQL already has for numbers. + +The functions existed as free functions in ``functions.math`` and were +unreachable from a column, so ``col.sqrt()`` raised AttributeError while +``sqrt(dialect, col)`` worked. The mixin now forwards to the same factories, so +what these tests pin down is that the wiring is right: the right function name, +the arguments bound rather than inlined, and a result family the next call in +the chain can use. + +Family is checked where SQL makes it depend on the operand rather than on the +operation. ``CEIL(numeric)`` is ``numeric`` and ``CEIL(integer)`` is ``integer`` +in every backend, so ``ceil`` keeps the operand's family instead of asserting +one -- asserting integer here would have been wrong for every ``float`` column. +""" + +import pytest + +from rhosocial.activerecord.backend.expression import NumericColumn +from rhosocial.activerecord.backend.expression.core import ( + NumericValueExpression, +) + + +@pytest.fixture +def dialect(): + from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect + + return DummyDialect() + + +@pytest.fixture +def price(dialect): + return NumericColumn(dialect, "price", table="t") + + +NO_ARGUMENT_OPERATIONS = [ + ("abs", "ABS"), + ("sign", "SIGN"), + ("ceil", "CEIL"), + ("floor", "FLOOR"), + ("truncate", "TRUNCATE"), + ("sqrt", "SQRT"), + ("exp", "EXP"), + ("log", "LOG"), + ("sin", "SIN"), + ("cos", "COS"), + ("tan", "TAN"), +] + +ARGUMENT_OPERATIONS = [ + ("round", (2,), "ROUND"), + ("power", (2,), "POWER"), + ("mod", (3,), "MOD"), + ("log", (2,), "LOG"), +] + + +class TestOperationsReachTheColumn: + @pytest.mark.parametrize("method,sql_name", NO_ARGUMENT_OPERATIONS) + def test_no_argument(self, price, method, sql_name): + sql, _ = getattr(price, method)().to_sql() + assert sql.startswith(f"{sql_name}(") + + @pytest.mark.parametrize("method,args,sql_name", ARGUMENT_OPERATIONS) + def test_with_argument(self, price, method, args, sql_name): + sql, _ = getattr(price, method)(*args).to_sql() + assert sql.startswith(f"{sql_name}(") + + @pytest.mark.parametrize("method,sql_name", NO_ARGUMENT_OPERATIONS) + def test_the_column_is_the_operand(self, price, method, sql_name): + """Not the dialect or a fresh literal -- the column being asked about.""" + sql, _ = getattr(price, method)().to_sql() + assert '"t"."price"' in sql + + +class TestArgumentsAreBound: + """A number that came from the caller is data, and data gets bound.""" + + @pytest.mark.parametrize( + "method,args", [("round", (2,)), ("power", (3,)), ("mod", (7,))] + ) + def test_the_argument_is_a_parameter(self, price, method, args): + sql, params = getattr(price, method)(*args).to_sql() + assert "?" in sql + assert args[0] in params + + +class TestResultTypes: + def test_abs_keeps_the_operand_type(self, price): + """ABS of a fraction is a fraction; ABS of a whole number is a whole + number, which is why these are two classes rather than one.""" + assert isinstance(price.abs(), NumericValueExpression) + + def test_sign_is_a_number(self, price): + """Sign is -1, 0 or 1, but the backends do not answer integers for it: + measured on PostgreSQL, an integer argument comes back double and a + numeric one numeric, so the result carries the numeric surface.""" + assert isinstance(price.sign(), NumericValueExpression) + + def test_sqrt_is_a_number(self, price): + assert isinstance(price.sqrt(), NumericValueExpression) + + @pytest.mark.parametrize("method", ["ceil", "floor"]) + def test_rounding_keeps_the_operand_type(self, price, method): + """CEIL(numeric) is numeric in every backend; CEIL(integer) is not.""" + assert isinstance(getattr(price, method)(), NumericValueExpression) + + +class TestChaining: + def test_a_result_can_be_used_as_an_operand_again(self, price): + """The reason the family matters: the next call has to be available.""" + sql, _ = price.abs().sqrt().to_sql() + assert sql.count("SQRT(") == 1 + assert "ABS(" in sql + + def test_an_arithmetic_result_can_be_rounded(self, price): + sql, _ = (price + 1).round(2).to_sql() + assert "ROUND(" in sql + + def test_order_of_operations_is_visible_in_the_sql(self, price): + sql, _ = price.abs().ceil().to_sql() + assert sql == 'CEIL(ABS("t"."price"))' \ No newline at end of file diff --git a/tests/rhosocial/activerecord_test/feature/basic/ddl/test_uuid_expressions.py b/tests/rhosocial/activerecord_test/feature/basic/ddl/test_uuid_expressions.py new file mode 100644 index 000000000..1cd65ced2 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/basic/ddl/test_uuid_expressions.py @@ -0,0 +1,169 @@ +# tests/rhosocial/activerecord_test/feature/basic/ddl/test_uuid_expressions.py +"""UUID value expressions and the ``UUIDSupport`` contract. + +Generating a UUID in SQL is a portable *request* with a wildly +non-portable *spelling* — eight backends, eight function names, and SQLite +has none. The expression layer states the request; each dialect fills in a +``UUID_SQL`` table. A dialect that cannot serve a request must say so, and +rendering must then raise with a usable suggestion rather than emit another +backend's function. + +Storage is deliberately not involved: that is ``DataType``'s business, and +nothing here reads it. +""" + +# tests/rhosocial/activerecord_test/feature/basic/ddl/test_uuid_expressions.py +import pytest + +from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError +from rhosocial.activerecord.backend.dialect.protocols import UUIDSupport +from rhosocial.activerecord.backend.expression import ( + UUIDCastExpression, + UUIDConstantExpression, + UUIDGenerationExpression, + Literal, +) +from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + +_NIL = "00000000-0000-0000-0000-000000000000" +_MAX = "ffffffff-ffff-ffff-ffff-ffffffffffff" + + +def _dialect(uuid_sql=None): + dialect = SQLiteDialect() + dialect._version = (3, 46, 1) + if uuid_sql is not None: + dialect.UUID_SQL = uuid_sql + return dialect + + +_FULL = { + "generation": "GEN_UUID()", + "constant": {"nil": "X'00'", "max": "X'FF'"}, + "cast": "CAST({inner} AS UUID)", +} + + +# --------------------------------------------------------------------------- +# Honest absence +# --------------------------------------------------------------------------- + + +def test_sqlite_satisfies_the_protocol(): + """Being in the protocol is about shape, not about capability.""" + assert isinstance(_dialect(), UUIDSupport) + + +@pytest.mark.parametrize( + "probe", ["supports_uuid_generation", "supports_uuid_constant", "supports_uuid_cast"] +) +def test_sqlite_reports_no_uuid_operations(probe): + """SQLite has no UUID function, so all three must report False.""" + assert getattr(_dialect(), probe)() is False + + +@pytest.mark.parametrize( + "factory", + [ + lambda d: UUIDGenerationExpression(d), + lambda d: UUIDConstantExpression(d, "nil"), + lambda d: UUIDCastExpression(d, Literal(d, "x")), + ], + ids=["generation", "constant", "cast"], +) +def test_rendering_raises_when_unsupported(factory): + with pytest.raises(UnsupportedFeatureError): + factory(_dialect()).to_sql() + + +def test_generation_suggests_the_python_route(): + """The suggestion must point at something that actually works today.""" + with pytest.raises(UnsupportedFeatureError) as excinfo: + UUIDGenerationExpression(_dialect()).to_sql() + assert "uuid.uuid4" in str(excinfo.value) + + +# --------------------------------------------------------------------------- +# A dialect that implements the operations +# --------------------------------------------------------------------------- + + +def test_capability_probes_reflect_the_table(): + dialect = _dialect(_FULL) + assert dialect.supports_uuid_generation() is True + assert dialect.supports_uuid_constant() is True + assert dialect.supports_uuid_cast() is True + + +def test_generation_renders_the_backends_own_function(): + assert UUIDGenerationExpression(_dialect(_FULL)).to_sql() == ("GEN_UUID()", ()) + + +def test_generation_carries_its_alias(): + assert UUIDGenerationExpression(_dialect(_FULL), alias="u").to_sql() == ( + 'GEN_UUID() AS "u"', + (), + ) + + +@pytest.mark.parametrize("which, expected", [("nil", "X'00'"), ("max", "X'FF'")]) +def test_constants_render_per_kind(which, expected): + assert UUIDConstantExpression(_dialect(_FULL), which).to_sql() == (expected, ()) + + +def test_constant_kind_is_case_insensitive(): + assert UUIDConstantExpression(_dialect(_FULL), "MAX").to_sql() == ("X'FF'", ()) + + +def test_constant_rejects_an_unknown_kind(): + """A typo must not silently render a literal.""" + with pytest.raises(ValueError, match="which must be one of"): + UUIDConstantExpression(_dialect(_FULL), "middle") + + +def test_cast_substitutes_the_operand_and_keeps_its_parameters(): + dialect = _dialect(_FULL) + expr = UUIDCastExpression(dialect, Literal(dialect, "not-a-uuid")) + assert expr.to_sql() == ("CAST(? AS UUID)", ("not-a-uuid",)) + + +def test_constant_and_cast_stay_unsupported_when_only_generation_is_declared(): + partial = {"generation": "GEN_UUID()"} + dialect = _dialect(partial) + assert dialect.supports_uuid_generation() is True + with pytest.raises(UnsupportedFeatureError, match="UUID constants"): + UUIDConstantExpression(dialect, "nil").to_sql() + with pytest.raises(UnsupportedFeatureError, match="UUID cast"): + UUIDCastExpression(dialect, Literal(dialect, "x")).to_sql() + + +# --------------------------------------------------------------------------- +# The expressions are ordinary value expressions +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "factory", + [ + lambda d: UUIDGenerationExpression(d), + lambda d: UUIDConstantExpression(d, "nil"), + lambda d: UUIDCastExpression(d, Literal(d, "x")), + ], + ids=["generation", "constant", "cast"], +) +def test_uuid_expressions_support_comparison_and_aliasing(factory): + from rhosocial.activerecord.backend.expression import SQLPredicate + + dialect = _dialect(_FULL) + expr = factory(dialect) + assert isinstance(expr == factory(dialect), SQLPredicate) + assert expr.as_("u").alias == "u" + + +def test_format_methods_are_declared_for_dispatch(): + assert UUIDGenerationExpression(_dialect()).format_method == "format_uuid_generation" + assert UUIDConstantExpression(_dialect(), "nil").format_method == "format_uuid_constant" + assert ( + UUIDCastExpression(_dialect(), Literal(_dialect(), "x")).format_method + == "format_uuid_cast" + ) diff --git a/tests/rhosocial/activerecord_test/feature/basic/fields/test_derived_field.py b/tests/rhosocial/activerecord_test/feature/basic/fields/test_derived_field.py index 540631b54..87b1cbd35 100644 --- a/tests/rhosocial/activerecord_test/feature/basic/fields/test_derived_field.py +++ b/tests/rhosocial/activerecord_test/feature/basic/fields/test_derived_field.py @@ -5,7 +5,7 @@ from rhosocial.activerecord.base import DerivedField, UseColumn from rhosocial.activerecord.model import ActiveRecord -from rhosocial.activerecord.backend.expression import Column, Literal +from rhosocial.activerecord.backend.expression import Literal, NumericColumn class TestDerivedFieldDeclaration: @@ -20,7 +20,7 @@ def test_descriptor_class_access(self, product_class): def test_derived_field_with_static_expression(self, product_class): """Test DerivedField constructed with a pre-built expression object (non-callable path).""" dialect = product_class.backend().dialect - static_expr = Column(dialect, "price") * Literal(dialect, 2) + static_expr = NumericColumn(dialect, "price") * Literal(dialect, 2) df = DerivedField(static_expr) resolved = df.resolve(dialect) assert resolved is static_expr @@ -137,7 +137,7 @@ def _insert(self, Model, name, price, quantity): def test_derived_dict_with_lambda(self, product_class): self._insert(product_class, "D1", 100.0, 4) results = product_class.find_all( - derived={"my_discount": lambda d: Column(d, "price") * Literal(d, 0.8)} + derived={"my_discount": lambda d: NumericColumn(d, "price") * Literal(d, 0.8)} ) assert results[0].__dict__["my_discount"] == pytest.approx(80.0) @@ -153,7 +153,7 @@ def test_derived_dict_with_derived_field_instance(self, product_class): def test_derived_dict_with_expression_object(self, product_class): self._insert(product_class, "D3", 80.0, 5) dialect = product_class.backend().dialect - expr = Column(dialect, "price") * Literal(dialect, 0.5) + expr = NumericColumn(dialect, "price") * Literal(dialect, 0.5) results = product_class.find_all( derived={"half_price": expr} ) @@ -185,7 +185,7 @@ def _insert(self, Model, name, price, quantity): def test_extra_derived_basic(self, product_class): self._insert(product_class, "F", 100.0, 10) results = product_class.find_all( - extra_derived={"triple_price": lambda d: Column(d, "price") * Literal(d, 3)} + extra_derived={"triple_price": lambda d: NumericColumn(d, "price") * Literal(d, 3)} ) assert len(results) == 1 assert results[0].__dict__["triple_price"] == pytest.approx(300.0) @@ -194,14 +194,14 @@ def test_extra_derived_conflict_raises(self, product_class): self._insert(product_class, "G", 50.0, 2) with pytest.raises(ValueError, match="conflicts with a declared derived field"): product_class.find_all( - extra_derived={"discounted_price": lambda d: Column(d, "price") * Literal(d, 0.5)} + extra_derived={"discounted_price": lambda d: NumericColumn(d, "price") * Literal(d, 0.5)} ) def test_derived_and_extra_derived_together(self, product_class): self._insert(product_class, "H", 40.0, 5) results = product_class.find_all( derived=True, - extra_derived={"double_qty": lambda d: Column(d, "quantity") * Literal(d, 2)} + extra_derived={"double_qty": lambda d: NumericColumn(d, "quantity") * Literal(d, 2)} ) assert results[0].discounted_price == pytest.approx(36.0) assert results[0].total_value == pytest.approx(200.0) @@ -315,7 +315,7 @@ class ConflictModel(ActiveRecord): id: Optional[int] = None discount_rate: Annotated[float, UseColumn("disc")] discounted: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), ), UseColumn("disc")]] def test_use_column_no_conflict_different_names(self): @@ -325,7 +325,7 @@ class NoConflict(ActiveRecord): id: Optional[int] = None discount_rate: Annotated[float, UseColumn("rate")] discounted: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), ), UseColumn("disc")]] assert NoConflict.__derived_fields__["discounted"].column_name == "disc" diff --git a/tests/rhosocial/activerecord_test/feature/basic/fields/test_derived_field_async.py b/tests/rhosocial/activerecord_test/feature/basic/fields/test_derived_field_async.py index 8720acd9d..7064b54af 100644 --- a/tests/rhosocial/activerecord_test/feature/basic/fields/test_derived_field_async.py +++ b/tests/rhosocial/activerecord_test/feature/basic/fields/test_derived_field_async.py @@ -5,7 +5,7 @@ from rhosocial.activerecord.base import DerivedField, UseColumn from rhosocial.activerecord.model import ActiveRecord -from rhosocial.activerecord.backend.expression import Column, Literal +from rhosocial.activerecord.backend.expression import Literal, NumericColumn class TestAsyncDerivedFieldDeclaration: @@ -20,7 +20,7 @@ async def test_descriptor_class_access(self, async_product_class): async def test_derived_field_with_static_expression(self, async_product_class): """Test DerivedField constructed with a pre-built expression object (non-callable path).""" dialect = async_product_class.backend().dialect - static_expr = Column(dialect, "price") * Literal(dialect, 2) + static_expr = NumericColumn(dialect, "price") * Literal(dialect, 2) df = DerivedField(static_expr) resolved = df.resolve(dialect) assert resolved is static_expr @@ -137,7 +137,7 @@ async def _insert(self, Model, name, price, quantity): async def test_derived_dict_with_lambda(self, async_product_class): await self._insert(async_product_class, "D1", 100.0, 4) results = await async_product_class.find_all( - derived={"my_discount": lambda d: Column(d, "price") * Literal(d, 0.8)} + derived={"my_discount": lambda d: NumericColumn(d, "price") * Literal(d, 0.8)} ) assert results[0].__dict__["my_discount"] == pytest.approx(80.0) @@ -153,7 +153,7 @@ async def test_derived_dict_with_derived_field_instance(self, async_product_clas async def test_derived_dict_with_expression_object(self, async_product_class): await self._insert(async_product_class, "D3", 80.0, 5) dialect = async_product_class.backend().dialect - expr = Column(dialect, "price") * Literal(dialect, 0.5) + expr = NumericColumn(dialect, "price") * Literal(dialect, 0.5) results = await async_product_class.find_all( derived={"half_price": expr} ) @@ -185,7 +185,7 @@ async def _insert(self, Model, name, price, quantity): async def test_extra_derived_basic(self, async_product_class): await self._insert(async_product_class, "F", 100.0, 10) results = await async_product_class.find_all( - extra_derived={"triple_price": lambda d: Column(d, "price") * Literal(d, 3)} + extra_derived={"triple_price": lambda d: NumericColumn(d, "price") * Literal(d, 3)} ) assert len(results) == 1 assert results[0].__dict__["triple_price"] == pytest.approx(300.0) @@ -194,14 +194,14 @@ async def test_extra_derived_conflict_raises(self, async_product_class): await self._insert(async_product_class, "G", 50.0, 2) with pytest.raises(ValueError, match="conflicts with a declared derived field"): await async_product_class.find_all( - extra_derived={"discounted_price": lambda d: Column(d, "price") * Literal(d, 0.5)} + extra_derived={"discounted_price": lambda d: NumericColumn(d, "price") * Literal(d, 0.5)} ) async def test_derived_and_extra_derived_together(self, async_product_class): await self._insert(async_product_class, "H", 40.0, 5) results = await async_product_class.find_all( derived=True, - extra_derived={"double_qty": lambda d: Column(d, "quantity") * Literal(d, 2)} + extra_derived={"double_qty": lambda d: NumericColumn(d, "quantity") * Literal(d, 2)} ) assert results[0].discounted_price == pytest.approx(36.0) assert results[0].total_value == pytest.approx(200.0) @@ -315,7 +315,7 @@ class ConflictModel(ActiveRecord): id: Optional[int] = None discount_rate: Annotated[float, UseColumn("disc")] discounted: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), ), UseColumn("disc")]] async def test_use_column_no_conflict_different_names(self): @@ -325,7 +325,7 @@ class NoConflict(ActiveRecord): id: Optional[int] = None discount_rate: Annotated[float, UseColumn("rate")] discounted: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), ), UseColumn("disc")]] assert NoConflict.__derived_fields__["discounted"].column_name == "disc" diff --git a/tests/rhosocial/activerecord_test/feature/basic/fixtures/models.py b/tests/rhosocial/activerecord_test/feature/basic/fixtures/models.py index ba5e9f0bf..2a1829c7c 100644 --- a/tests/rhosocial/activerecord_test/feature/basic/fixtures/models.py +++ b/tests/rhosocial/activerecord_test/feature/basic/fixtures/models.py @@ -767,7 +767,7 @@ class AsyncMappedOrderItem(CompositePKMixin, AsyncActiveRecord): # ============================================================================= from rhosocial.activerecord.base import DerivedField -from rhosocial.activerecord.backend.expression import Column, Literal +from rhosocial.activerecord.backend.expression import Literal, NumericColumn class Product(ActiveRecord): @@ -779,11 +779,11 @@ class Product(ActiveRecord): quantity: int discounted_price: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), )]] total_value: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Column(d, "quantity"), + lambda d: NumericColumn(d, "price") * NumericColumn(d, "quantity"), )]] @@ -796,11 +796,11 @@ class AsyncProduct(AsyncActiveRecord): quantity: int discounted_price: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), )]] total_value: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Column(d, "quantity"), + lambda d: NumericColumn(d, "price") * NumericColumn(d, "quantity"), )]] @@ -814,11 +814,11 @@ class ProductFormA(ActiveRecord): quantity: int discounted_price: ClassVar[DerivedField] = DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), ) total_value: ClassVar[DerivedField] = DerivedField( - lambda d: Column(d, "price") * Column(d, "quantity"), + lambda d: NumericColumn(d, "price") * NumericColumn(d, "quantity"), ) @@ -831,11 +831,11 @@ class AsyncProductFormA(AsyncActiveRecord): quantity: int discounted_price: ClassVar[DerivedField] = DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), ) total_value: ClassVar[DerivedField] = DerivedField( - lambda d: Column(d, "price") * Column(d, "quantity"), + lambda d: NumericColumn(d, "price") * NumericColumn(d, "quantity"), ) @@ -900,11 +900,11 @@ class ProductWithColumnAndAdapter(ActiveRecord): quantity: int discounted_price: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), ), UseColumn("disc")]] total_int: ClassVar[Annotated[int, DerivedField( - lambda d: Column(d, "price") * Column(d, "quantity"), + lambda d: NumericColumn(d, "price") * NumericColumn(d, "quantity"), ), UseAdapter(PriceToIntAdapter(), int)]] @@ -917,10 +917,10 @@ class AsyncProductWithColumnAndAdapter(AsyncActiveRecord): quantity: int discounted_price: ClassVar[Annotated[float, DerivedField( - lambda d: Column(d, "price") * Literal(d, 0.9), + lambda d: NumericColumn(d, "price") * Literal(d, 0.9), ), UseColumn("disc")]] total_int: ClassVar[Annotated[int, DerivedField( - lambda d: Column(d, "price") * Column(d, "quantity"), + lambda d: NumericColumn(d, "price") * NumericColumn(d, "quantity"), ), UseAdapter(PriceToIntAdapter(), int)]] diff --git a/tests/rhosocial/activerecord_test/feature/mixins/test_field_config_validation.py b/tests/rhosocial/activerecord_test/feature/mixins/test_field_config_validation.py new file mode 100644 index 000000000..5ba81ea74 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/mixins/test_field_config_validation.py @@ -0,0 +1,198 @@ +# tests/rhosocial/activerecord_test/feature/mixins/test_field_config_validation.py +"""Field-mixin configuration is validated at class-definition time. + +A semantics mixin (``SoftDeleteMixin`` / ``TimestampMixin`` / +``OptimisticLockMixin``) declares *knobs* — class attributes naming a model +field. If the model does not declare that field, every generated query +silently references a column that does not exist. + +The validation used to live in each mixin's ``__init__``, which never ran in +the documented declaration order:: + + class Order(ActiveRecord, SoftDeleteMixin): # mixin's __init__ is skipped + +so a misconfigured model was accepted and only failed much later, at query +time. It now runs from the metaclass feature-handler hook +(``ActiveRecordMetaclass.__new__`` step 4), which fires after the class +object exists and ``model_fields`` is complete. These tests pin that +contract: the check must be independent of base-class order, and it must +reject the class as soon as the class statement is evaluated. + +No database is involved, so no provider fixture is required. +""" + +# tests/rhosocial/activerecord_test/feature/mixins/test_field_config_validation.py +from datetime import datetime +from typing import ClassVar, Optional + +import pytest +from pydantic import Field + +from rhosocial.activerecord.field import ( + DefaultSoftDeleteMixin, + OptimisticLockMixin, + SoftDeleteMixin, + TimestampMixin, +) +from rhosocial.activerecord.model import ActiveRecord + +# --------------------------------------------------------------------------- +# Rejection — a misconfigured model must not become a class +# --------------------------------------------------------------------------- + + +def test_soft_delete_rejects_missing_field_with_active_record_first(): + """The documented order (mixin last) must still be validated. + + This is the regression: with validation in ``__init__`` this class + statement succeeded and the model broke at query time instead. + """ + + with pytest.raises(TypeError, match="__deleted_at_field__"): + type( # noqa: F841 -- the statement itself is the assertion + "Order", + (ActiveRecord, SoftDeleteMixin), + { + "__table_name__": "rej_soft_a", + "__primary_key__": "id", + "__annotations__": {"id": Optional[int]}, + "__deleted_at_field__": "no_such_field", + }, + ) + + +def test_soft_delete_rejects_missing_field_with_mixin_first(): + """The other base order must behave identically.""" + with pytest.raises(TypeError, match="__deleted_at_field__"): + type( # noqa: F841 + "Order", + (SoftDeleteMixin, ActiveRecord), + { + "__table_name__": "rej_soft_b", + "__primary_key__": "id", + "__annotations__": {"id": Optional[int]}, + "__deleted_at_field__": "no_such_field", + }, + ) + + +def test_timestamp_rejects_missing_field(): + with pytest.raises(TypeError, match="__created_at_field__"): + type( # noqa: F841 + "Article", + (ActiveRecord, TimestampMixin), + { + "__table_name__": "rej_ts", + "__primary_key__": "id", + "__annotations__": {"id": Optional[int]}, + "__created_at_field__": "no_such_field", + }, + ) + + +def test_optimistic_lock_rejects_missing_field(): + with pytest.raises(TypeError, match="__version_field__"): + type( # noqa: F841 + "Account", + (ActiveRecord, OptimisticLockMixin), + { + "__table_name__": "rej_lock", + "__primary_key__": "id", + "__annotations__": {"id": Optional[int]}, + "__version_field__": "no_such_field", + }, + ) + + +def test_optimistic_lock_rejects_non_positive_increment(): + with pytest.raises(ValueError, match="__version_increment_by__"): + type( # noqa: F841 + "Account", + (ActiveRecord, OptimisticLockMixin), + { + "__table_name__": "rej_lock_inc", + "__primary_key__": "id", + "__annotations__": {"id": Optional[int], "version": int}, + "version": 1, + "__version_increment_by__": 0, + }, + ) + + +# --------------------------------------------------------------------------- +# Acceptance — correct configuration must be unaffected +# --------------------------------------------------------------------------- + + +def test_soft_delete_accepts_declared_field(): + class Doc(ActiveRecord, SoftDeleteMixin): + __table_name__ = "ok_soft" + __primary_key__: ClassVar[str] = "id" + + id: Optional[int] = None + deleted_at: Optional[datetime] = Field(default=None) + + assert Doc.__deleted_at_field__ in Doc.model_fields + + +def test_timestamp_accepts_declared_fields(): + class Post(ActiveRecord, TimestampMixin): + __table_name__ = "ok_ts" + __primary_key__: ClassVar[str] = "id" + + id: Optional[int] = None + created_at: datetime = Field(default_factory=datetime.now) + updated_at: datetime = Field(default_factory=datetime.now) + + assert Post.__created_at_field__ in Post.model_fields + assert Post.__updated_at_field__ in Post.model_fields + + +def test_optimistic_lock_accepts_declared_field(): + class Account(ActiveRecord, OptimisticLockMixin): + __table_name__ = "ok_lock" + __primary_key__: ClassVar[str] = "id" + + id: Optional[int] = None + version: int = 1 + + assert Account.__version_field__ in Account.model_fields + + +def test_default_soft_delete_mixin_declares_its_own_field(): + """The ``Default*`` mixins ship the field, so they validate themselves.""" + + class Doc(ActiveRecord, DefaultSoftDeleteMixin): + __table_name__ = "ok_default_soft" + __primary_key__: ClassVar[str] = "id" + + id: Optional[int] = None + + assert "deleted_at" in Doc.model_fields + + +def test_validation_does_not_mask_other_feature_handlers(): + """Adding the mixin's handler must not displace the inherited ones. + + ``get_feature_handlers`` merges ``_feature_handlers`` across the MRO; a + mixin contributing its own entry must leave the core handlers (DDL + annotations, derived fields, adapters, column names) in place, or a model + would silently lose them. + """ + + class Doc(ActiveRecord, SoftDeleteMixin): + __table_name__ = "ok_handlers" + __primary_key__: ClassVar[str] = "id" + + id: Optional[int] = None + deleted_at: Optional[datetime] = Field(default=None) + + names = {h.__name__ for h in Doc.get_feature_handlers()} + assert "FieldConfigValidationHandler" in names + for inherited in ( + "DDLAnnotationHandler", + "DerivedFieldHandler", + "AdapterAnnotationHandler", + "ColumnNameAnnotationHandler", + ): + assert inherited in names, f"{inherited} was displaced" diff --git a/tests/rhosocial/activerecord_test/feature/query/column_helpers.py b/tests/rhosocial/activerecord_test/feature/query/column_helpers.py new file mode 100644 index 000000000..902c0280b --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/column_helpers.py @@ -0,0 +1,112 @@ +# tests/rhosocial/activerecord_test/feature/query/column_helpers.py +"""Test-side helpers for the column-class selection path, and its canonical list. + +The production path is ``base/field_proxy.py``: ``Model.c.`` asks the +model for the field's column-type declaration (dialect-free), then +``FieldAccessor`` selects the class the model's backend answers. This module +mirrors that selection step for a bare annotation, so a test can build a column +without declaring a model. + +``COMMON_TYPES`` is the contract-test-side canonical list of the common +Python types every backend must answer for. It lives here, not in the +framework: the framework resolves by walking whatever keys a backend's table +declares, and the required key set is a contract the tests state and hold each +backend to. + +Deliberately **not** a fallback: an annotation the selection cannot classify +raises :class:`ColumnTypeResolutionError` exactly as ``Model.c.`` +would, so a test that builds a column from a bad annotation fails here for the +same reason the model would, and the two cannot drift apart. +""" + +import datetime +import decimal +import enum +import uuid +from typing import Any, Optional, Tuple, Type + +from rhosocial.activerecord.backend.expression.column_types import ColumnBase +from rhosocial.activerecord.backend.expression.core import Column +from rhosocial.activerecord.base.field_proxy import ( + ColumnTypeResolutionError, + FieldAccessor, +) + +#: The common Python types, in declared reading order. The order matters where +#: a subclass walk meets an ambiguous annotation: ``bool`` ahead of ``int``, +#: and ``enum.Enum`` tested before the walk (a ``(int, Enum)`` stays an enum). +COMMON_TYPES: Tuple[Any, ...] = ( + bool, + int, + float, + decimal.Decimal, + str, + bytes, + bytearray, + datetime.date, + datetime.time, + datetime.datetime, + datetime.timedelta, + uuid.UUID, + dict, + list, + tuple, + set, + frozenset, + enum.Enum, +) + + +def resolve_column_class(dialect: Any, annotation: Any, declared: Any = None) -> Type[ColumnBase]: + """The class *dialect* selects for *annotation*. + + The field accessor's own selection step, invoked without a model. *declared* + is the field's column-type declaration when a test exercises one; ``None`` + asks the backend's tables. + """ + return FieldAccessor._select_column_class(dialect, annotation, declared) + + +def build_column( + dialect: Any, + column_name: str, + annotation: Any, + table: Optional[str] = None, + schema_name: Optional[str] = None, + column_type: Any = None, +) -> ColumnBase: + """Build the column expression *dialect* selects for *annotation*. + + Args: + dialect: The dialect to select through. Selection is per-backend by + design, so a test that wants a specific column class must say which + backend's answer it is asking for. + column_name: The SQL name to render. + annotation: The Python annotation, ``Annotated`` / ``Optional`` included. + table: Optional table qualifier. + schema_name: Optional schema qualifier. + column_type: A ``UseColumnType`` when the test is exercising an explicit + declaration; ``None`` asks the backend's tables. + + Returns: + The constructed column expression. + + Raises: + ColumnTypeResolutionError: The backend's tables have no column class for + *annotation*, or answered ``None`` for its entry. + """ + column_class = resolve_column_class(dialect, annotation, column_type) + if column_class is Column: + # The untyped column keeps its own narrower constructor and can only + # arrive by being declared explicitly, so this is a shape difference + # rather than a fallback. + return Column(dialect, column_name, table=table, schema_name=schema_name) + return column_class(dialect, column_name, table=table, schema_name=schema_name) + + +__all__ = [ + "COMMON_TYPES", + "ColumnTypeResolutionError", + "build_column", + "resolve_column_class", +] diff --git a/tests/rhosocial/activerecord_test/feature/query/sqlite/test_collation_expression.py b/tests/rhosocial/activerecord_test/feature/query/sqlite/test_collation_expression.py index eca66ce81..1b1f7eaa0 100644 --- a/tests/rhosocial/activerecord_test/feature/query/sqlite/test_collation_expression.py +++ b/tests/rhosocial/activerecord_test/feature/query/sqlite/test_collation_expression.py @@ -11,6 +11,7 @@ from rhosocial.activerecord.backend.dialect.mixins import CollationMixin, ExpressionMixin, DDLColumnMixin from rhosocial.activerecord.backend.expression import Column, Literal, collate from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.backend.expression.types import TextType class StandardCollationDialect(SQLDialectBase, ExpressionMixin, DDLColumnMixin, CollationMixin): @@ -69,7 +70,7 @@ def test_collate_participates_in_comparison(self, dialect): assert params == ("alice",) def test_collate_supports_alias_and_cast(self, dialect): - expr = Column(dialect, "name").collate("NOCASE").cast("TEXT").as_("normalized_name") + expr = Column(dialect, "name").collate("NOCASE").cast(TextType(dialect)).as_("normalized_name") sql, params = expr.to_sql() diff --git a/tests/rhosocial/activerecord_test/feature/query/test_aggregate_window_families.py b/tests/rhosocial/activerecord_test/feature/query/test_aggregate_window_families.py new file mode 100644 index 000000000..336488991 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_aggregate_window_families.py @@ -0,0 +1,209 @@ +# tests/rhosocial/activerecord_test/feature/query/test_aggregate_window_families.py +"""What aggregating and windowing a value gives back. + +COUNT and SUM look alike and are not: one counts, the other adds, and the +count is a whole number however wide the thing being counted is. MIN and MAX +are the opposite — they hand back something of the input's kind, so the +minimum of a string column is a string and can still be compared and matched. + +A window function is either a count or a value from another row, and confusing +the two is how a name column ends up arithmetic. ROW_NUMBER counts; LAG +borrows. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_aggregate_window_families.py +import pytest + +from rhosocial.activerecord.backend.expression import FunctionCall +from rhosocial.activerecord.backend.expression import functions as F + + +@pytest.fixture +def dialect(): + from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + d = SQLiteDialect() + d._version = (3, 46, 1) + return d + + +@pytest.fixture +def columns(dialect): + from rhosocial.activerecord_test.feature.query.column_helpers import build_column + + return { + "int": build_column(dialect, "i", int), + "float": build_column(dialect, "f", float), + "str": build_column(dialect, "s", str), + "json": build_column(dialect, "j", dict), + } + + +# --------------------------------------------------------------------------- +# Counting +# --------------------------------------------------------------------------- + + +def test_count_is_always_a_whole_number(dialect, columns): + """However wide the thing counted, the answer is a number of rows.""" + for column in columns.values(): + assert isinstance(F.count(dialect, column), IntegerValueExpression) + + +def test_count_takes_arithmetic_and_not_string_operations(dialect, columns): + count = F.count(dialect, columns["int"]) + assert hasattr(count, "__add__") + assert not hasattr(count, "upper") + + +# --------------------------------------------------------------------------- +# Averaging widens +# --------------------------------------------------------------------------- + + +def test_avg_is_numeric_whatever_it_averages(dialect, columns): + """Averaging whole numbers gives a fraction, so the family has to allow + one. SQL Server is the exception that returns an integer here, which is + exactly why it is not something to build an operation surface on.""" + for column in columns.values(): + assert isinstance(F.avg(dialect, column), NumericValueExpression) + + +# --------------------------------------------------------------------------- +# Adding, minimising and maximising keep the input's kind +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("factory", ["sum_", "min_", "max_"]) +def test_a_reduction_keeps_the_input_family(dialect, columns, factory): + """SUM of a float column is fractional and MIN of a string column is a + string, which can still be compared and matched.""" + reduce_it = getattr(F, factory) + assert isinstance(reduce_it(dialect, columns["int"]), IntegerValueExpression) + assert isinstance(reduce_it(dialect, columns["float"]), NumericValueExpression) + assert isinstance(reduce_it(dialect, columns["str"]), StringValueExpression) + + +@pytest.mark.parametrize("factory", ["sum_", "min_", "max_"]) +def test_a_literal_input_has_no_family_to_keep(dialect, factory): + """A literal does not declare a kind, so the result is unknown rather than + guessed. Unknown is safe: the node is handed back untouched.""" + result = getattr(F, factory)(dialect, 1) + assert not isinstance(result, ArrayValueExpression) and not isinstance(result, BinaryValueExpression) and not isinstance(result, BooleanValueExpression) and not isinstance(result, DateValueExpression) and not isinstance(result, IntegerValueExpression) and not isinstance(result, IntervalValueExpression) and not isinstance(result, JSONValueExpression) and not isinstance(result, NumericValueExpression) and not isinstance(result, StringValueExpression) and not isinstance(result, TimeValueExpression) and not isinstance(result, TimestampValueExpression) and not isinstance(result, UUIDValueExpression) + assert isinstance(result, FunctionCall) + + +def test_min_of_a_string_column_is_still_a_string(dialect, columns): + result = F.min_(dialect, columns["str"]) + assert hasattr(result, "like") + assert not hasattr(result, "sqrt") + + +# --------------------------------------------------------------------------- +# Building a document or a sequence +# --------------------------------------------------------------------------- + + +def test_building_a_json_aggregate_gives_json(dialect, columns): + assert isinstance(F.json_objectagg(dialect, columns["int"], columns["str"]), JSONValueExpression) + assert isinstance(F.json_arrayagg(dialect, columns["json"]), JSONValueExpression) + + +def test_collecting_into_an_array_gives_an_array(dialect, columns): + assert isinstance(F.array_agg(dialect, columns["int"]), ArrayValueExpression) + + +# --------------------------------------------------------------------------- +# Windowing: a count, or a value from another row +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("factory", ["row_number", "rank", "dense_rank"]) +def test_a_rank_is_a_whole_number(dialect, factory): + for windowed in (getattr(F, factory)(dialect),): + assert isinstance(windowed, IntegerValueExpression) + assert hasattr(windowed, "__add__") + assert not hasattr(windowed, "upper") + + +@pytest.mark.parametrize( + "factory, extra", + [("lag", ()), ("lead", ()), ("first_value", ()), ("last_value", ()), ("nth_value", (2,))], +) +def test_a_value_from_another_row_keeps_its_family(dialect, columns, factory, extra): + """LAG over a name column is a name, not a count. + + Which is asserted by the arithmetic that is *absent*: a name is not a + number, so no ``sqrt``. The string operations are present, because the + result genuinely is a string -- it was ``not hasattr(windowed, "upper")`` + before the class replaced the tag, and that assertion is what the tag was + costing: the node carried ``family="string"`` while offering none of the + string surface, so a caller could not tell from the object which operations + it had. Now the class says it, and the operations come with it. + """ + windowed = getattr(F, factory)(dialect, columns["str"], *extra) + assert isinstance(windowed, StringValueExpression) + assert hasattr(windowed, "like") + assert not hasattr(windowed, "sqrt") + + +def test_lag_over_a_float_column_is_fractional(dialect, columns): + assert isinstance(F.lag(dialect, columns["float"]), NumericValueExpression) + + +# --------------------------------------------------------------------------- +# The node states its family, and the round trip survives it +# --------------------------------------------------------------------------- + + +def test_a_typed_aggregate_reports_its_family_for_introspection(dialect, columns): + """Introspection has to see what a result is, or nothing downstream can + read it. + + It used to read ``get_params()["family"]``. That keyword is gone: it + duplicated the class, and a tag that can disagree with the class it sits on + is worse than no tag at all. The class is the introspection surface now, so + this asserts the class -- which is what a caller would have branched on + anyway. + """ + result = F.count(dialect, columns["int"]) + assert isinstance(result, IntegerValueExpression) + + +def test_a_typed_window_reports_its_family_for_introspection(dialect, columns): + """Same for a window function: the class, not the removed ``family`` tag.""" + result = F.lag(dialect, columns["int"]) + assert isinstance(result, IntegerValueExpression) + + +def test_an_untyped_aggregate_reports_no_family(dialect, columns): + """A node constructed directly is the untyped one, and says so by being it. + + ``get_params()["family"] is None`` was how this used to be checked. There is + no ``family`` parameter to be ``None`` now, so the assertion is the class: + a bare ``FunctionCall`` is not a typed value, which is the same + statement without the tag that could contradict it. + """ + result = FunctionCall(dialect, "COUNT", columns["int"], is_aggregate=True) + assert not isinstance(result, ArrayValueExpression) and not isinstance(result, BinaryValueExpression) and not isinstance(result, BooleanValueExpression) and not isinstance(result, DateValueExpression) and not isinstance(result, IntegerValueExpression) and not isinstance(result, IntervalValueExpression) and not isinstance(result, JSONValueExpression) and not isinstance(result, NumericValueExpression) and not isinstance(result, StringValueExpression) and not isinstance(result, TimeValueExpression) and not isinstance(result, TimestampValueExpression) and not isinstance(result, UUIDValueExpression) + + + +from rhosocial.activerecord.backend.expression.core import ( + NumericValueExpression, + IntegerValueExpression, + StringValueExpression, + BooleanValueExpression, + BinaryValueExpression, + UUIDValueExpression, + JSONValueExpression, + ArrayValueExpression, + TimestampValueExpression, + DateValueExpression, + TimeValueExpression, + IntervalValueExpression, +) +def test_declaring_a_family_does_not_change_the_sql(dialect, columns): + """Typing is a surface decision, never a rendering one.""" + assert F.count(dialect, columns["int"]).to_sql()[0] == "COUNT(\"i\")" + assert F.lag(dialect, columns["int"]).to_sql()[0] == "LAG(\"i\", ?)" diff --git a/tests/rhosocial/activerecord_test/feature/query/test_boolean_connectives.py b/tests/rhosocial/activerecord_test/feature/query/test_boolean_connectives.py new file mode 100644 index 000000000..b36a1ec81 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_boolean_connectives.py @@ -0,0 +1,82 @@ +# tests/rhosocial/activerecord_test/feature/query/test_boolean_connectives.py +"""A value's connectives keep the value type; a predicate's stay predicates. + +``p1 & p2`` combines predicates for a WHERE clause. A truth *value* needs the +same three operators with a different result: ``(flag & other)`` must be +something a SELECT list can carry, so it stays a boolean value +(:class:`BooleanLogicExpression`) with the same SQL. One implementation, +dispatched by the receiver, which is what these tests pin. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_boolean_connectives.py +import pytest + +from rhosocial.activerecord.backend.expression import BooleanColumn +from rhosocial.activerecord.backend.expression.bases import SQLPredicate, SQLValueExpression +from rhosocial.activerecord.backend.expression.core import BooleanLogicExpression +from rhosocial.activerecord.backend.expression.predicates import LogicalPredicate + + +@pytest.fixture +def dialect(): + from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + return SQLiteDialect() + + +def test_a_boolean_values_connectives_keep_the_value_type(dialect): + flag = BooleanColumn(dialect, "flag") + other = BooleanColumn(dialect, "other") + + combined = flag & other + assert isinstance(combined, BooleanLogicExpression) + assert isinstance(combined, SQLValueExpression) + assert not isinstance(combined, SQLPredicate) + + sql, params = combined.to_sql() + assert "AND" in sql and params == () + + +def test_a_value_can_be_negated_and_chained(dialect): + flag = BooleanColumn(dialect, "flag") + other = BooleanColumn(dialect, "other") + + assert isinstance(~flag, BooleanLogicExpression) + + chained = (flag & other) | flag + assert isinstance(chained, BooleanLogicExpression) + assert "OR" in chained.to_sql()[0] + + +def test_a_predicate_combination_stays_a_predicate(dialect): + flag = BooleanColumn(dialect, "flag") + other = BooleanColumn(dialect, "other") + + combined = flag.is_true() & other.is_true() + assert isinstance(combined, LogicalPredicate) + assert isinstance(combined, SQLPredicate) + assert not isinstance(combined, SQLValueExpression) + + assert isinstance(~flag.is_true(), LogicalPredicate) + + +def test_a_value_expression_can_be_aliased_into_a_select_list(dialect): + flag = BooleanColumn(dialect, "flag") + aliased = (flag & flag).as_("both") + sql, params = aliased.to_sql() + assert "AND" in sql and "both" in sql + + +def test_a_boolean_value_can_be_compared(dialect): + flag = BooleanColumn(dialect, "flag") + predicate = (flag & flag) == flag + assert isinstance(predicate, SQLPredicate) + + +def test_both_receivers_render_the_same_connective(dialect): + flag = BooleanColumn(dialect, "flag") + other = BooleanColumn(dialect, "other") + + value_sql = (flag & other).to_sql()[0] + predicate_sql = (flag.is_true() & other.is_true()).to_sql()[0] + assert "AND" in value_sql and "AND" in predicate_sql diff --git a/tests/rhosocial/activerecord_test/feature/query/test_column_type_support.py b/tests/rhosocial/activerecord_test/feature/query/test_column_type_support.py new file mode 100644 index 000000000..173324928 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_column_type_support.py @@ -0,0 +1,717 @@ +# tests/rhosocial/activerecord_test/feature/query/test_column_type_support.py +"""The column-type support protocol: entry contract, backend authority, failures. + +Four questions, and nothing here needs a database to answer them: + +1. **Is the entry contract kept?** Every backend answers the common Python + types the tests enumerate, so a model never meets a table with a hole. +2. **Whose answer is it?** The backend's own tables, always: a dialect that + overrides one entry changes exactly that entry, and a backend's extra table + carries its own Python types without touching the common ones. +3. **What does a declared column type look like, and what fails loudly?** + ``Model.column_type()`` presents the declaration as written (a + ``UseColumnType`` marker, a class, or a sequence); the field accessor + selects from it; ``Any``, a bare ``Union``, an unregistered custom class + and a ``None`` table entry all raise. +4. **What do the declaration accessors present?** ``column_type`` and + ``column_data_type`` are dialect-free declarations -- no fallback, no + selection -- and the batch method mirrors the data-type one. + +Plus the boolean algebra surface and its literal discipline: ``TRUE``/``FALSE`` +as keywords, never ``1``/``0``, which PostgreSQL rejects outright +(``operator does not exist: boolean = integer``). +""" + +import datetime +import decimal +import enum +import typing +import uuid +from typing import Any, ClassVar, Dict, List, Optional, Type, Union + +import pytest + +from rhosocial.activerecord.backend.dialect.mixins import ColumnTypeMixin +from rhosocial.activerecord.backend.dialect.protocols import ColumnTypeSupport +from rhosocial.activerecord.backend.expression.column_types import ( + ArrayColumn, + ColumnBase, + TimestampColumn, + IntegerColumn, + JSONColumn, + NumericColumn, + StringColumn, + UUIDColumn, +) +from rhosocial.activerecord.backend.expression.types import JsonType +from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect +from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.backend.impl.sqlite.mixins.column_type import ( + SQLITE_COLUMN_TYPES, +) +from rhosocial.activerecord.base.field_proxy import ( + ColumnTypeResolutionError, + FieldProxy, +) +from rhosocial.activerecord.base.fields import DDLAnnotation, UseColumnType, UseSqlType +from rhosocial.activerecord.model import ActiveRecord + +from rhosocial.activerecord_test.feature.query.column_helpers import ( + COMMON_TYPES, + build_column, + resolve_column_class, +) + + +def sqlite_dialect(version=(3, 46, 1)): + """A version-adapted SQLite dialect. + + ``supports_json_type`` reads ``self.version``, and an unadapted dialect + raises rather than answering -- so every test that renders needs a version. + 3.46 is a real release well past the 3.38.0 line where the JSON functions + became part of SQLite proper. + """ + return SQLiteDialect(version=version) + + +def dummy_dialect(): + """An adapted dummy dialect: the dialect-less baseline, not a server.""" + dialect = DummyDialect() + dialect._version = (3, 46, 1) + return dialect + + +def resolve(dialect, annotation, declared=None): + """The selection step, for the cases below that read as "resolve this".""" + return resolve_column_class(dialect, annotation, declared) + + +_ENTRY_IDS = [getattr(entry, "__name__", str(entry)) for entry in COMMON_TYPES] + + +# --------------------------------------------------------------------------- +# 1. The entry contract +# --------------------------------------------------------------------------- + + +def test_the_canonical_entry_list_is_the_declared_order(): + """Order is the protocol's reading order, and the tests are where it lives. + + The framework resolves by walking whatever keys a backend declares, so the + canonical list is not a runtime constant: it is this contract, stated once + and held against every backend's table. + """ + assert _ENTRY_IDS == [ + "bool", + "int", + "float", + "Decimal", + "str", + "bytes", + "bytearray", + "date", + "time", + "datetime", + "timedelta", + "UUID", + "dict", + "list", + "tuple", + "set", + "frozenset", + "Enum", + ] + + +def test_entry_list_has_no_duplicates(): + """A duplicate would make 'answer every entry' ambiguous.""" + assert len(set(COMMON_TYPES)) == len(COMMON_TYPES) + + +def test_the_protocol_is_structural(): + """A dialect satisfies it by answering the two tables, nothing else.""" + dialect = sqlite_dialect() + assert isinstance(dialect, ColumnTypeSupport) + assert callable(dialect.suggested_column_types) + assert callable(dialect.suggested_extra_column_types) + + +@pytest.mark.parametrize("entry", COMMON_TYPES, ids=_ENTRY_IDS) +def test_every_entry_resolves_through_sqlite(entry): + assert issubclass(resolve(sqlite_dialect(), entry), ColumnBase) + + +@pytest.mark.parametrize("entry", COMMON_TYPES, ids=_ENTRY_IDS) +def test_every_entry_resolves_through_the_dummy_baseline(entry): + assert issubclass(resolve(dummy_dialect(), entry), ColumnBase) + + +def test_boolean_is_its_own_entry_not_an_integer(): + """``bool`` is an ``int`` subclass; the entry order is what keeps them apart. + + Without the order, ``bool`` would walk to ``int`` and a truth-value field + would offer integer arithmetic -- which MySQL and SQLite would happily + execute on a column holding 0/1. + """ + assert COMMON_TYPES.index(bool) < COMMON_TYPES.index(int) + assert resolve(sqlite_dialect(), bool) is not resolve(sqlite_dialect(), int) + + +def test_date_and_time_are_separate_entries_sharing_a_column_class(): + """They are distinct entries because the framework asks about each of them. + + They answer the same column class today, which is a modelling gap the entry + list is what will eventually close (splitting ``TimestampColumn`` by operation + set). Asserting the shared answer keeps that gap visible: when one of them + splits, this test is what notices. + """ + assert resolve(sqlite_dialect(), datetime.date) is TimestampColumn + assert resolve(sqlite_dialect(), datetime.time) is TimestampColumn + + +# --------------------------------------------------------------------------- +# 2. The backend is the authority +# --------------------------------------------------------------------------- + + +class OverridingDialect(SQLiteDialect): + """A backend that disagrees with SQLite about exactly one entry. + + Its table is SQLite's own with one entry replaced, so "the seventeen other + answers are untouched" is a statement about this dialect versus the backend + it extends. ``str`` answers with a class neither would have picked, which is + what makes the authority observable: a core-side table consulted first would + ignore this. + """ + + def suggested_column_types(self): + table = super().suggested_column_types() + table[str] = NumericColumn + return table + + +class RefusingDialect(SQLiteDialect): + """A backend with no column class for one entry. + + The honest "this backend has none", which is what MySQL 5.6 and Firebird + would have to say about a value family they cannot carry. It must reach the + caller as a failure rather than as a fallback to another table. + """ + + def suggested_column_types(self): + table = super().suggested_column_types() + table[dict] = None + return table + + +class Complex: + """A user type the framework does not model; carried by the extra table.""" + + +class ExtendingDialect(SQLiteDialect): + """A backend with a Python type of its own, in its own table.""" + + def suggested_extra_column_types(self): + return {Complex: JSONColumn} + + +def test_backend_override_changes_only_its_own_entry(): + """One overridden entry, one changed answer, seventeen untouched.""" + dialect = OverridingDialect(version=(3, 46, 1)) + + assert resolve(dialect, str) is NumericColumn + assert resolve(sqlite_dialect(), str) is StringColumn + + for entry in COMMON_TYPES: + if entry is str: + continue + assert resolve(dialect, entry) is resolve(sqlite_dialect(), entry) + + +def test_a_backend_may_extend_with_an_entry_of_its_own(): + """The extension path for a Python type the framework does not model.""" + dialect = ExtendingDialect(version=(3, 46, 1)) + + assert resolve(dialect, Complex) is JSONColumn + assert resolve(dialect, Optional[Complex]) is JSONColumn + # ...and the common entries keep working alongside it. + assert resolve(dialect, int) is IntegerColumn + + +def test_the_returned_tables_are_copies(): + """A caller walking a table must not mutate what the next field reads.""" + dialect = sqlite_dialect() + table = dialect.suggested_column_types() + table.clear() + assert set(dialect.suggested_column_types()) == set(COMMON_TYPES) + + +def test_the_mixin_withholds_the_common_table(): + """There is no inherited table: a dialect that does not answer is told so.""" + + class Bare(ColumnTypeMixin): + pass + + with pytest.raises(NotImplementedError): + Bare().suggested_column_types() + assert Bare().suggested_extra_column_types() == {} + + +def test_sqlite_answers_exactly_the_common_types(): + """Its table is complete and has nothing beyond the contract (for now).""" + assert set(SQLITE_COLUMN_TYPES) == set(COMMON_TYPES) + assert None not in SQLITE_COLUMN_TYPES.values() + + +def test_the_dummy_dialect_states_its_own_baseline(): + """It stands for no server, so it states no backend's answers. + + SQLite is built into core and the dummy is the other dialect core ships, so + the two are easy to conflate. They are deliberately different: the dummy is + the dialect-less default a test reads, and copying a real backend's table + into it would make "what does the portable baseline say" unanswerable. + """ + dummy = dummy_dialect() + assert set(dummy.suggested_column_types()) == set(COMMON_TYPES) + assert resolve(dummy, list) is ArrayColumn + assert resolve(sqlite_dialect(), list) is JSONColumn + # ``Decimal`` was merged into NumericColumn on both sides; asserting the + # shared answer keeps the merge deliberate. + assert resolve(dummy, decimal.Decimal) is NumericColumn + assert resolve(sqlite_dialect(), decimal.Decimal) is NumericColumn + + +# --------------------------------------------------------------------------- +# 3. Declared column types: three forms, and what is refused +# --------------------------------------------------------------------------- + + +def test_use_column_type_overrides_the_tables(): + """Naming a class bypasses the recommendation, and only the recommendation.""" + assert resolve(sqlite_dialect(), int, UseColumnType(StringColumn)) is StringColumn + + +def test_a_bare_class_declaration_answers(): + """``column_type`` may present a class directly; the selector accepts it.""" + assert resolve(sqlite_dialect(), int, StringColumn) is StringColumn + + +def test_a_single_candidate_sequence_answers(): + """A one-element sequence is a declaration with one candidate.""" + assert resolve(sqlite_dialect(), int, [StringColumn]) is StringColumn + + +def test_a_multi_candidate_sequence_is_refused(): + """Choosing among candidates needs the capability declaration, which is not here. + + Taking the first silently would make the declaration a lie the caller + cannot see. + """ + with pytest.raises(ColumnTypeResolutionError, match="capability"): + resolve(sqlite_dialect(), int, [StringColumn, JSONColumn]) + + +def test_an_empty_sequence_is_refused(): + with pytest.raises(ColumnTypeResolutionError, match="empty sequence"): + resolve(sqlite_dialect(), int, []) + + +def test_a_non_declaration_is_refused(): + with pytest.raises(ColumnTypeResolutionError, match="not a column-type declaration"): + resolve(sqlite_dialect(), int, "StringColumn") + + +def test_use_column_type_saves_an_annotation_no_table_could_classify(): + """The escape hatch is what makes every other failure actionable.""" + assert resolve(sqlite_dialect(), Any, UseColumnType(StringColumn)) is StringColumn + + +def test_use_column_type_with_several_classes_is_refused(): + """Multi-candidate selection needs the capability declaration, which is not here. + + Declaring two classes is a request to negotiate with the backend, and there + is nothing to ask yet. Taking the first silently would make the declaration + a lie the caller cannot see. + """ + with pytest.raises(TypeError, match="capability"): + UseColumnType(StringColumn, JSONColumn) + + +def test_use_column_type_with_no_classes_is_refused(): + with pytest.raises(TypeError, match="at least one"): + UseColumnType() + + +@pytest.mark.parametrize( + "bad_factory, why", + [ + (str, "builtin"), + (lambda: "StringColumn", "name"), + (lambda: StringColumn(sqlite_dialect(), "x"), "instance"), + ], + ids=["builtin", "string", "instance"], +) +def test_use_column_type_rejects_non_column_classes(bad_factory, why): + """A column class is a type, never an instance -- an instance carries state. + + Built through factories because a column instance needs a dialect, and + constructing one at collection time would put a database-free object in the + module preamble. + """ + with pytest.raises(TypeError, match="ColumnBase"): + UseColumnType(bad_factory()) + + +def test_use_column_type_is_not_a_ddl_annotation(): + """Strict independence: the DDL collector must never see it. + + ``UseSqlType`` is a ``DDLAnnotation``; this one deliberately is not. If it + were, the DDL layer would be one refactor away from inferring a storage type + from a column declaration -- the exact coupling the independence ruling + forbids. + """ + assert not isinstance(UseColumnType(StringColumn), DDLAnnotation) + + +def test_use_column_type_is_independent_of_use_sql_type(): + """Both declared, and neither is inferred from the other.""" + Annotated = getattr(typing, "Annotated", None) + if Annotated is None: + pytest.skip("typing.Annotated requires Python 3.9+") + + annotation = Annotated[int, UseSqlType(JsonType()), UseColumnType(StringColumn)] + declared = [m for m in annotation.__metadata__ if isinstance(m, UseColumnType)][0] + + assert resolve(sqlite_dialect(), annotation, declared) is StringColumn + # The DDL side still sees only its own candidate. + assert [type(d).__name__ for d in annotation.__metadata__] == [ + "UseSqlType", + "UseColumnType", + ] + assert UseSqlType(JsonType()).data_type.name == "json" + + +# --------------------------------------------------------------------------- +# 4. The model-side declaration accessors (dialect-free) +# --------------------------------------------------------------------------- + + +def _declared_model(dialect): + Annotated = getattr(typing, "Annotated", None) + if Annotated is None: + pytest.skip("typing.Annotated requires Python 3.9+") + + class Declared(ActiveRecord): + __table_name__ = "declared_types" + __primary_key__: ClassVar[str] = "id" + c: ClassVar[FieldProxy] = FieldProxy() + + id: int + label: Annotated[str, UseColumnType(JSONColumn)] + payload: Annotated[dict, UseSqlType(JsonType())] + + Declared.__backend__ = type("B", (), {"dialect": dialect})() + return Declared + + +def test_column_type_presents_the_declaration_or_none(): + """``column_type`` presents; it does not resolve and does not fall back.""" + Model = _declared_model(sqlite_dialect()) + + declared = Model.column_type("label") + assert isinstance(declared, UseColumnType) + assert declared.column_class is JSONColumn + assert Model.column_type("id") is None + + +def test_two_column_type_declarations_on_one_field_are_refused(): + Annotated = getattr(typing, "Annotated", None) + if Annotated is None: + pytest.skip("typing.Annotated requires Python 3.9+") + + class Bad(ActiveRecord): + __table_name__ = "bad_declarations" + __primary_key__: ClassVar[str] = "id" + c: ClassVar[FieldProxy] = FieldProxy() + + id: int + broken: Annotated[ + Any, + UseColumnType(StringColumn), + UseColumnType(JSONColumn), + ] + + Bad.__backend__ = type("B", (), {"dialect": sqlite_dialect()})() + with pytest.raises(TypeError, match="UseColumnType declarations"): + Bad.column_type("broken") + + +def test_column_data_type_presents_the_declaration_or_none(): + """The renamed accessor: dialect-free declaration, no inference.""" + Model = _declared_model(sqlite_dialect()) + + assert Model.column_data_type("id") is None + marker = Model.column_data_type("payload") + assert isinstance(marker, UseSqlType) + assert isinstance(marker.data_types[0], JsonType) + + +def test_columns_data_type_batches(): + Model = _declared_model(sqlite_dialect()) + + batch = Model.columns_data_type() + assert set(batch) == {"id", "label", "payload"} + assert batch["payload"] is Model.column_data_type("payload") + + +def test_the_accessor_path_end_to_end(): + """The declared class wins where the table would have answered otherwise.""" + Model = _declared_model(sqlite_dialect()) + + assert type(Model.c.label) is JSONColumn # declared + assert type(Model.c.id) is IntegerColumn # selected from the table + assert type(Model.c.payload) is JSONColumn # table, not the DDL declaration + + +# --------------------------------------------------------------------------- +# 5. Failures: tables with holes, refused entries, unclassifiable annotations +# --------------------------------------------------------------------------- + + +def test_a_missing_entry_is_reported_against_the_backends_table(): + class PartialDialect(SQLiteDialect): + def suggested_column_types(self): + return {str: StringColumn} + + with pytest.raises(ColumnTypeResolutionError, match="Cannot choose a column class"): + resolve(PartialDialect(version=(3, 46, 1)), int) + + +def test_a_none_entry_fails_and_names_the_declaration_that_fixes_it(): + with pytest.raises(ColumnTypeResolutionError) as excinfo: + resolve(RefusingDialect(version=(3, 46, 1)), dict) + message = str(excinfo.value) + assert "no column class for" in message + assert "UseColumnType" in message + + +def test_a_none_entry_does_not_leak_into_other_entries(): + """One refusal must not make the whole backend unusable.""" + dialect = RefusingDialect(version=(3, 46, 1)) + assert resolve(dialect, str) is StringColumn + assert resolve(dialect, int) is IntegerColumn + + +def test_a_table_entry_that_is_not_a_column_class_raises(): + """A malformed table is a backend bug, caught where it is written down.""" + + class WrongDialect(SQLiteDialect): + def suggested_column_types(self): + table = super().suggested_column_types() + table[str] = "StringColumn" + return table + + with pytest.raises(ColumnTypeResolutionError, match="not a ColumnBase subclass"): + resolve(WrongDialect(version=(3, 46, 1)), str) + + +@pytest.mark.parametrize( + "annotation", + [Any, Union[int, str], List[int], Dict[str, int]], + ids=["Any", "bare-union", "parameterised-list", "parameterised-dict"], +) +def test_unclassifiable_annotations_fail(annotation): + """``Any``, a bare ``Union``, a parameterised container: no entry, no answer. + + Each of these used to become the permissive ``Column``. Now it is a + definition-time failure naming what to write instead, which is the change + the ruling asked for: a field the framework cannot type is a mistake in the + model, and a silent fallback hides it until the database complains. + """ + with pytest.raises(ColumnTypeResolutionError) as excinfo: + resolve(sqlite_dialect(), annotation) + assert "UseColumnType" in str(excinfo.value) + + +def test_an_unregistered_custom_class_fails(): + """A class the framework does not model is unclassifiable, not a string.""" + + class Money: + pass + + with pytest.raises(ColumnTypeResolutionError, match="Cannot choose a column class"): + resolve(sqlite_dialect(), Money) + + +def test_a_subclass_of_an_entry_resolves_through_the_walk(): + """``class MyStr(str)`` is a string; the walk is what says so.""" + assert resolve(sqlite_dialect(), type("Code", (str,), {})) is StringColumn + + +def test_an_enum_subclass_resolves_to_the_enum_entry(): + """Before the subclass walk, so a ``(int, Enum)`` is not filed as an int.""" + assert resolve(sqlite_dialect(), enum.Enum) is StringColumn + + class Weekday(enum.IntEnum): + MONDAY = 1 + + assert resolve(sqlite_dialect(), Weekday) is StringColumn + + +def test_optional_and_annotated_still_resolve(): + Annotated = getattr(typing, "Annotated", None) + if Annotated is None: + pytest.skip("typing.Annotated requires Python 3.9+") + + assert resolve(sqlite_dialect(), Optional[dict]) is JSONColumn + # An unrelated marker is simply not a UseColumnType; the selector resolves + # from the peeled annotation and the declaration is read by the model layer. + assert resolve(sqlite_dialect(), Annotated[str, "marker"]) is StringColumn + + +# --------------------------------------------------------------------------- +# 6. Boolean algebra and the literal discipline +# --------------------------------------------------------------------------- + + +def _flag(name="flag"): + return build_column(sqlite_dialect(), name, bool) + + +def test_is_true_and_is_false_render_keywords(): + """``IS TRUE`` / ``IS FALSE``, three-valued-logic correct. + + ``= TRUE`` would match differently under three-valued logic, and ``= 1`` + is not portable at all: PostgreSQL rejects ``boolean = integer`` outright. + """ + assert _flag().is_true().to_sql() == ('"flag" IS TRUE', ()) + assert _flag().is_false().to_sql() == ('"flag" IS FALSE', ()) + + +def test_and_or_not_render_connectives_not_bitwise_operators(): + """``AND`` / ``OR`` / ``NOT`` — MySQL accepts bitwise ``&`` / ``|`` too, and + on a boolean column those compute something else entirely.""" + column = _flag() + assert (column.is_true() & column.is_false()).to_sql() == ( + '"flag" IS TRUE AND "flag" IS FALSE', + (), + ) + assert (column.is_true() | column.is_false()).to_sql() == ( + '"flag" IS TRUE OR "flag" IS FALSE', + (), + ) + assert (~column.is_true()).to_sql() == ('NOT ("flag" IS TRUE)', ()) + + +def test_boolean_algebra_never_renders_one_or_zero(): + """The rendering discipline, asserted rather than described. + + ``1`` / ``0`` as a boolean literal is the one thing that works on SQLite and + MySQL and fails on PostgreSQL, so a regression that renders it would pass on + two backends and break on a third. The literal has to be the keyword. + """ + column = _flag() + rendered = [ + column.is_true().to_sql()[0], + column.is_false().to_sql()[0], + (column.is_true() & column.is_false()).to_sql()[0], + (column.is_true() | column.is_false()).to_sql()[0], + (~column.is_true()).to_sql()[0], + ] + for sql in rendered: + assert " TRUE" in sql or "FALSE" in sql + # No integer literal standing in for the value. + assert " IS 1" not in sql + assert " IS 0" not in sql + assert "= 1" not in sql + assert "= 0" not in sql + + +def test_boolean_columns_only_carry_the_boolean_surface(): + """``str`` has no ``AND``; that is what the narrow classes are for. + + The mixin is composed into :class:`BooleanColumn` rather than inherited + from :class:`ColumnBase` precisely so that these three operators stay off + every other family — giving ``str`` an ``AND`` would be the guess the narrow + classes exist to avoid. + """ + assert hasattr(build_column(sqlite_dialect(), "f", bool), "__and__") + assert hasattr(build_column(sqlite_dialect(), "f", bool), "__or__") + assert hasattr(build_column(sqlite_dialect(), "f", bool), "__invert__") + assert not hasattr(build_column(sqlite_dialect(), "s", str), "__and__") + assert not hasattr(build_column(sqlite_dialect(), "n", int), "__invert__") + + +def test_negating_the_column_is_not_the_same_as_is_false(): + """``~flag`` is NOT; three-valued logic makes ``NOT NULL`` unknown. + + Callers asking "is it false?" say ``is_false()``. ``~`` is the connective. + """ + column = _flag() + assert column.is_false().to_sql()[0] != f"NOT ({column.to_sql()[0]})" + + +def test_boolean_algebra_composes_with_other_predicates(): + """The connectives are the same ones predicates use, so they interleave.""" + column = _flag() + name = build_column(sqlite_dialect(), "name", str) + combined = (column.is_true() & name.like("a%")) | column.is_false() + sql, params = combined.to_sql() + assert " AND " in sql and " OR " in sql + assert params == ("a%",) + + +# --------------------------------------------------------------------------- +# 7. Two backends, one contract -- and no free resolvers +# --------------------------------------------------------------------------- + + +def test_two_dialects_differ_only_where_stated(): + """The dummy and SQLite differ exactly in the sequence entries. + + SQLite has no array type, so its four sequence entries are JSON documents; + the dummy keeps the portable ``ArrayColumn``. Every other entry agrees — + including ``float``/``Decimal``/``timedelta``, all ``NumericColumn`` on + both sides since the numeric merge. A backend that deviated anywhere else + would be changing an answer no decision asked it to change. + """ + dummy, sqlite = dummy_dialect(), sqlite_dialect() + deviated = {list, tuple, set, frozenset} + for entry in COMMON_TYPES: + if entry in deviated: + continue + assert resolve(dummy, entry) is resolve(sqlite, entry) + assert resolve(sqlite, list) is JSONColumn + assert resolve(dummy, list) is ArrayColumn + + +def test_the_public_surface_has_no_free_resolvers(): + """Resolution belongs to the field accessor; there is no module function.""" + import rhosocial.activerecord.base as base_package + + assert not hasattr(base_package, "build_column") + assert not hasattr(base_package, "column_class_for") + assert not hasattr(base_package, "column_dispatch") + + +def test_the_permissive_column_is_still_constructible_by_hand(): + """Retiring the fallback did not retire the class. + + ``Column(dialect, "x")`` is how a caller with a bare column name gets an + expression; what is gone is the framework deciding that an unclassifiable + annotation becomes one. + """ + from rhosocial.activerecord.backend.expression import Column + + column = Column(sqlite_dialect(), "anything") + assert column.to_sql() == ('"anything"', ()) + + +def test_uuid_stays_its_own_column_family(): + """A UUID has no portable operator, but it is still not a string.""" + assert resolve(sqlite_dialect(), uuid.UUID) is UUIDColumn + assert resolve(sqlite_dialect(), uuid.UUID) is not StringColumn + + +def test_decimal_is_a_number_and_not_a_string(): + assert issubclass(resolve(sqlite_dialect(), decimal.Decimal), NumericColumn) diff --git a/tests/rhosocial/activerecord_test/feature/query/test_document_and_conversion_families.py b/tests/rhosocial/activerecord_test/feature/query/test_document_and_conversion_families.py new file mode 100644 index 000000000..5473924d2 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_document_and_conversion_families.py @@ -0,0 +1,447 @@ +# tests/rhosocial/activerecord_test/feature/query/test_document_and_conversion_families.py +"""The families that carry documents, sequences, casts and XML. + +A JSON extraction is not always a document: `->` hands back JSON and `->>` +hands back text, so the same node class reports two families and the chain +narrows. A cast states its result in the target type, which is the only place +it can come from. And an operation over several values — GREATEST, a CASE — +answers with their common kind, or with nothing when they disagree. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_document_and_conversion_families.py +import pytest + +from rhosocial.activerecord.backend.expression import functions as F, FunctionCall, Literal, XMLColumn +from rhosocial.activerecord.backend.expression.bases import SQLValueExpression +from rhosocial.activerecord.backend.expression.advanced_functions import CaseExpression +from rhosocial.activerecord.backend.expression.core import ( + ArrayValueExpression, + BinaryValueExpression, + BooleanValueExpression, + DateValueExpression, + IntegerValueExpression, + IntervalValueExpression, + JSONValueExpression, + NumericValueExpression, + StringValueExpression, + TimeValueExpression, + TimestampValueExpression, + UUIDValueExpression, + XMLValueExpression, +) + +#: Every value class the lattice holds. "No typed result" is asserted by saying +#: the result is none of these, so the list has to be the whole set: an +#: assertion that forgets a class would pass for the wrong reason. +TYPED_VALUE_CLASSES = ( + ArrayValueExpression, + BinaryValueExpression, + BooleanValueExpression, + DateValueExpression, + IntegerValueExpression, + IntervalValueExpression, + JSONValueExpression, + NumericValueExpression, + StringValueExpression, + TimeValueExpression, + TimestampValueExpression, + UUIDValueExpression, + XMLValueExpression, +) + + +def is_typed_as_one_of_these(result): + """Whether *result* is any of the typed value classes. + + A node that declares no type is honest about it: it is none of these. This + is the shape the tests that want "unknown" assert, and it is why the list + above is spelled out rather than imported wholesale -- a class added to the + lattice has to be added here too, or these assertions would go on passing + while the answer they are about became possible. + """ + return isinstance(result, TYPED_VALUE_CLASSES) +from rhosocial.activerecord.backend.expression.column_types import value_class_of +from rhosocial.activerecord.backend.expression.type_name import is_valid_type_name +from rhosocial.activerecord.backend.expression.types import VarCharType, JsonType, CustomType, XmlType + + +@pytest.fixture +def dialect(): + from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + d = SQLiteDialect() + d._version = (3, 46, 1) + return d + + +@pytest.fixture +def columns(dialect): + from rhosocial.activerecord_test.feature.query.column_helpers import build_column + + return { + "int": build_column(dialect, "i", int), + "float": build_column(dialect, "f", float), + "str": build_column(dialect, "s", str), + "json": build_column(dialect, "j", dict), + "array": build_column(dialect, "l", list), + } + + +# --------------------------------------------------------------------------- +# The same node, two families +# --------------------------------------------------------------------------- + + +def test_arrow_extraction_gives_a_document(dialect, columns): + assert isinstance(F.json_extract(dialect, columns["json"], Literal(dialect, "$.a")), JSONValueExpression) + + +def test_double_arrow_extraction_gives_text(dialect, columns): + """`->>` is a narrowing: a document becomes a string and cannot widen back.""" + assert isinstance(F.json_extract_text(dialect, columns["json"], "$.a"), StringValueExpression) + + +def test_a_built_document_is_a_document(dialect, columns): + assert isinstance(F.json_build_object(dialect, "k", 1), JSONValueExpression) + assert isinstance(F.json_array_elements(dialect, columns["json"]), JSONValueExpression) + + +def test_a_document_offers_the_json_accessors(dialect, columns): + built = F.json_build_object(dialect, "k", 1) + assert isinstance(built, JSONValueExpression) + assert hasattr(built, "json_path") + assert not hasattr(built, "upper") + + +def test_text_reports_a_string_family(dialect, columns): + """Narrowing is reported, which is what propagation reads. + + The JSON accessors stay, because one node class serves both arrow + directions and the wrapper cannot hide what it forwards — that is a known + over-offer on this one class, not a claim that text is a document. + """ + text = F.json_extract_text(dialect, columns["json"], "$.a") + assert isinstance(text, StringValueExpression) + assert text.to_sql()[0].endswith("->>'$.a'") + + +# --------------------------------------------------------------------------- +# Sequences +# --------------------------------------------------------------------------- + + +def test_a_sequence_is_a_sequence(dialect, columns): + assert isinstance(F.unnest(dialect, columns["array"]), ArrayValueExpression) + assert isinstance(F.unnest(dialect, columns["array"]), ArrayValueExpression) + + +def test_measuring_a_sequence_gives_a_whole_number(dialect, columns): + assert isinstance(F.array_length(dialect, columns["array"], 1), IntegerValueExpression) + + +# --------------------------------------------------------------------------- +# Operations over several values +# --------------------------------------------------------------------------- + + +def test_greatest_answers_with_what_its_arguments_answer_with(dialect, columns): + assert isinstance(F.greatest(dialect, columns["int"], columns["int"]), IntegerValueExpression) + + +def test_greatest_of_mixed_kinds_is_unknown(dialect, columns): + """The comparison is legal SQL and the answer is neither kind, so neither + surface may be offered. Guessing the first or the widest would be wrong.""" + assert not is_typed_as_one_of_these(F.greatest(dialect, columns["int"], columns["str"])) + + +def test_least_agrees_with_greatest(dialect, columns): + assert isinstance(F.least(dialect, columns["float"], columns["float"]), NumericValueExpression) + + +def test_nullif_keeps_the_value_it_tests(dialect, columns): + assert isinstance(F.nullif(dialect, columns["str"], None), StringValueExpression) + + +# --------------------------------------------------------------------------- +# what an operation over several values keeps +# --------------------------------------------------------------------------- + + +def test_a_consensus_needs_exactly_one(dialect, columns): + """A CASE over disagreeing branches is legal SQL that answers with neither + kind, so neither surface may be offered.""" + mixed = CaseExpression(dialect, cases=[(columns["int"], columns["int"])], + else_result=columns["float"]) + assert not is_typed_as_one_of_these(mixed) + + +def test_an_argument_without_a_family_does_not_break_a_consensus(dialect, columns): + """A literal says nothing, so it neither agrees nor disagrees.""" + with_literal = CaseExpression(dialect, cases=[(columns["int"], Literal(dialect, 1))], + else_result=columns["int"]) + assert isinstance(with_literal, IntegerValueExpression) + + +# --------------------------------------------------------------------------- +# A cast states its result in the target type +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "sql_type", + [ + "VARCHAR(255)", + "TEXT", + "NVARCHAR2(10)", + "INTEGER", + "BIGINT", + "DECIMAL(10,2)", + "DOUBLE PRECISION", + "BOOLEAN", + "TIMESTAMP", + "JSONB", + "BLOB", + "UUID", + "XML", + ], +) +def test_real_sql_type_names_are_names(sql_type): + """These are all type names a database has. + + They used to be pinned to the value family a cast to them produces. There is + no such table now: ``cast`` answers with the class of the ``DataType`` it + was handed, so the name carries no type of its own to be right about. What + remains is that the name is recognised -- the grammar, not a meaning. + """ + assert is_valid_type_name(sql_type) + + +def test_an_unknown_sql_type_is_still_a_name(): + """A name nobody here knows is still shaped like a name. + + What it means is the dialect's business, decided when the dialect is + asked to render it, not something this package guesses at here. + """ + assert is_valid_type_name("GEOMETRY") + assert is_valid_type_name("POINT") + assert not is_valid_type_name(None) + + +def test_cast_takes_its_type_from_the_target_type(dialect, columns): + """The cast answers with the class of the type it was handed.""" + assert isinstance( + F.cast(dialect, columns["int"], VarCharType(dialect, length=10)), + StringValueExpression, + ) + assert isinstance( + F.cast(dialect, columns["int"], JsonType(dialect)), JSONValueExpression + ) + + +def test_an_unmodelled_target_type_yields_no_typed_result(dialect, columns): + """A user-defined type has no value class to answer with. + + Offering JSON navigation on a type nobody here has heard of would be worse + than saying nothing, so the cast comes back untyped and the caller says what + they meant with ``as_*``. + """ + result = F.cast(dialect, columns["int"], CustomType(dialect, raw="GEOMETRY")) + assert not is_typed_as_one_of_these(result) + + +# --------------------------------------------------------------------------- +# Formatting and parsing +# --------------------------------------------------------------------------- + + +def test_to_char_gives_text(dialect, columns): + assert isinstance(F.to_char(dialect, columns["int"]), StringValueExpression) + + +def test_to_number_gives_a_number(dialect, columns): + assert isinstance(F.to_number(dialect, columns["int"]), NumericValueExpression) + + +def test_to_date_gives_a_timestamp(dialect, columns): + assert isinstance(F.to_date(dialect, columns["int"]), TimestampValueExpression) + + +# --------------------------------------------------------------------------- +# Session identity is a name +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("factory", ["current_user", "session_user", "system_user"]) +def test_the_session_identity_is_a_name(dialect, factory): + result = getattr(F, factory)(dialect) + assert isinstance(result, StringValueExpression) + assert hasattr(result, "upper") + + +# --------------------------------------------------------------------------- +# XML +# --------------------------------------------------------------------------- + + +def test_the_xml_document_nodes_are_xml_values(dialect): + """An XML constructor declares the XML value class, and nothing else. + + This used to assert the opposite -- that no class in the lattice covered + XML -- because the value family was a tag in a closed table and no tag + existed. The class is the statement now: every constructor that builds a + document derives from ``XMLValueExpression``, so ``isinstance`` answers + from the object. What the class carries is the XML surface — the null + tests and casting, and no comparison (see the refusal test below). + """ + from rhosocial.activerecord.backend.expression import xml as X + + document_nodes = ( + X.XMLParseExpression, + X.XMLElementExpression, + X.XMLForestExpression, + X.XMLConcatExpression, + X.XMLCommentExpression, + X.XMLPIExpression, + X.XMLRootExpression, + X.XMLAggExpression, + X.XMLQueryExpression, + ) + other_families = tuple( + cls for cls in TYPED_VALUE_CLASSES if cls is not XMLValueExpression + ) + for cls in document_nodes: + assert issubclass(cls, XMLValueExpression), cls.__name__ + assert issubclass(cls, SQLValueExpression), cls.__name__ + # It is an XML value and none of the other typed classes: a document + # is not text that can be upper-cased, not JSON to navigate, not a + # sequence to unnest. + assert not issubclass(cls, other_families), cls.__name__ + + +def test_xmlserialize_yields_the_character_value_it_names(dialect): + """Serialization leaves the XML family: the result is the text asked for. + + ``XMLSERIALIZE(... AS VARCHAR(100))`` answers with a character value, so + the node declares ``StringValueExpression`` and the string operations + follow it out of the XML surface. + """ + from rhosocial.activerecord.backend.expression import xml as X + + assert issubclass(X.XMLSerializeExpression, StringValueExpression) + serialized = F.xmlserialize(dialect, "", "VARCHAR(100)") + assert isinstance(serialized, StringValueExpression) + assert not isinstance(serialized, XMLValueExpression) + + +def test_xmlexists_is_a_predicate_not_a_value(): + """It answers a WHERE clause, so it has no value family to declare.""" + from rhosocial.activerecord.backend.expression import xml as X + from rhosocial.activerecord.backend.expression.bases import SQLPredicate + + assert issubclass(X.XMLExistsExpression, SQLPredicate) + assert not issubclass(X.XMLExistsExpression, XMLValueExpression) + + +def test_a_cast_to_xml_is_an_xml_value(dialect, columns): + """The cast takes its type from the target: ``CAST(x AS XML)`` is XML.""" + result = F.cast(dialect, columns["str"], XmlType(dialect)) + assert isinstance(result, XMLValueExpression) + assert not isinstance(result, StringValueExpression) + + +def test_a_function_that_declares_no_result_can_say_xml(dialect): + """``as_xml()`` is how a caller states what a generic call yields.""" + call = FunctionCall(dialect, "MYSTERY_FUNC") + typed = call.as_xml() + assert isinstance(typed, XMLValueExpression) + assert typed.to_sql() == call.to_sql() + + +def test_an_xml_column_refuses_comparison_and_keeps_the_null_tests(dialect): + """The XML column surface, exactly as every XML backend defines it. + + PostgreSQL refuses ``xml = xml`` ("operator does not exist: xml = xml"), + SQL Server documents that the xml data type "cannot be compared or + sorted", and Oracle's ``XMLType`` has no comparison operators. Refusing + here names the operation at the call; without the declaration Python + would silently answer with identity equality. ``IS NULL`` is accepted by + all three, so the null tests stay. + """ + column = XMLColumn(dialect, "doc") + + for operation, dunder in [ + (lambda c: c == 1, "__eq__"), + (lambda c: c != 1, "__ne__"), + (lambda c: c < 1, "__lt__"), + (lambda c: c <= 1, "__le__"), + (lambda c: c > 1, "__gt__"), + (lambda c: c >= 1, "__ge__"), + ]: + with pytest.raises(AttributeError, match=dunder): + operation(column) + + assert "IS NULL" in column.is_null().to_sql()[0] + assert "IS NOT NULL" in column.is_not_null().to_sql()[0] + + +# --------------------------------------------------------------------------- +# Every family has a wrapper +# --------------------------------------------------------------------------- + + +def test_a_type_the_core_does_not_hold_is_reported_unknown(): + """The lattice is closed. An extension type a backend models fully is still + unknown here, because the core does not know which backends exist and cannot + say what such a type means for the operations its own results offer. + + Declaring one used to look like it worked -- the attribute was there, and + reading it gave the name back -- so nothing pinned the difference between a + type that is honoured and one that is quietly dropped. A tag could claim a + name the core held no class for; a class cannot, because the operations it + offers come with it. + """ + class ExtensionValue(SQLValueExpression): + # A name on the class, which is what declaring a type used to mean. It + # confers nothing: nothing reads it, and value_class_of answers from the + # MRO, where this class appears under no mapped name. + declared_type = "network" + + instance = ExtensionValue.__new__(ExtensionValue) + assert ExtensionValue.declared_type == "network" + assert value_class_of(instance) is None + assert not is_typed_as_one_of_these(instance) + + +def test_every_typed_expression_declares_a_family_from_the_lattice(): + """Each result class states its own family, and it has to be one the + lattice knows -- otherwise it offers operations nothing downstream expects. + + This replaced a test that every family but XML had a wrapper in a registry. + There is no registry now: a factory constructs the class it means, so there + is no table left to be complete.""" + import inspect + + from rhosocial.activerecord.backend.expression import core + + declared = { + name: cls + for name, cls in inspect.getmembers(core, inspect.isclass) + if name.endswith("ValueExpression") and name != "SQLValueExpression" + } + assert declared, "the typed expressions moved" + # Every typed expression declares its type by being a class, so the only + # thing left to check is that each one is still reachable and distinct. + assert len(set(declared.values())) == len(declared), "two names bind one class" + + +def test_every_temporal_type_is_reachable(): + """The four temporal classes exist and are distinct. + + They were one class with a label saying which it was; now each is its own, + so this pins that they are all still there. + """ + from rhosocial.activerecord.backend.expression import core + + for name in ("TimestampValueExpression", "DateValueExpression", + "TimeValueExpression", "IntervalValueExpression"): + assert hasattr(core, name), name diff --git a/tests/rhosocial/activerecord_test/feature/query/test_operation_boundaries.py b/tests/rhosocial/activerecord_test/feature/query/test_operation_boundaries.py new file mode 100644 index 000000000..b12784bae --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_operation_boundaries.py @@ -0,0 +1,390 @@ +# tests/rhosocial/activerecord_test/feature/query/test_operation_boundaries.py +"""The four string boundaries the 2026-10-09 ruling settled, plus the NULL-safe +comparison it added to the surface. + +``operation-groups-matrix.md`` section F records the measurement: what the ten +backends answer for a negative count, an empty pad, a position below 1 and a +multi-character trim set, and which answer -- if any -- is common ground. This +file pins the outcome. Edges every backend agrees on render; the rest are +refused at construction instead of rendered into whatever the dialect happens +to do. ``is_distinct_from`` is here too: its spelling varies by backend, so it +is a dialect hook with a gate, and the gate refuses rather than substitutes a +different question. So are the function version floors SQLite records: they +used to be answerable through ``supports_functions()`` and ignorable at render +time, and now rendering a call the dialect's version predates refuses. +""" + +import pytest + +from rhosocial.activerecord.backend.dialect.exceptions import UnsupportedFeatureError +from rhosocial.activerecord.backend.expression.column_types import NumericColumn, StringColumn +from rhosocial.activerecord.backend.expression.core import FunctionCall, Literal +from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect +from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + +@pytest.fixture +def sqlite_dialect(): + dialect = SQLiteDialect() + dialect.version = (3, 46, 1) + return dialect + + +@pytest.fixture +def name(sqlite_dialect): + return StringColumn(sqlite_dialect, "name") + + +@pytest.fixture +def portable_name(): + """A column on the portable baseline, where the common spellings render.""" + return StringColumn(DummyDialect(), "name") + + +REFUSALS = [ + ("left", (-1,)), + ("right", (-1,)), + ("lpad", (-1,)), + ("lpad", (5, "")), + ("rpad", (-1,)), + ("rpad", (5, "")), + ("substr", (0,)), + ("substr", (-2, 3)), + ("substr", (1, -1)), + ("trim", ("xy",)), + ("trim", ("",)), +] + + +@pytest.mark.parametrize( + "method,args", + [("left", (-1,)), ("right", (-1,)), ("lpad", (-1,)), ("lpad", (5, "")), + ("rpad", (-1,)), ("rpad", (5, "")), ("substr", (0,)), ("substr", (-2, 3)), + ("substr", (1, -1)), ("trim", ("xy",)), ("trim", ("",))], + ids=("left", "right", "lpad_negative", "lpad_empty_pad", + "rpad_negative", "rpad_empty_pad", "substr_start0", "substr_negative_start", + "substr_negative_length", "trim_two_chars", "trim_empty_set"), +) +def test_the_edge_where_the_backends_disagree_is_refused(name, method, args): + """No two backends answer these the same way, so the answer is a refusal + at construction rather than a silent coin flip at render time.""" + with pytest.raises(ValueError): + getattr(name, method)(*args) + + +@pytest.mark.parametrize( + "method,args,expected_sql,expected_params", + [ + ("left", (0,), 'LEFT("name", ?)', (0,)), + ("repeat", (0,), 'REPEAT("name", ?)', (0,)), + ("substr", (1, 0), 'SUBSTRING("name", ?, ?)', (1, 0)), + ], +) +def test_the_edge_every_backend_agrees_on_renders(portable_name, method, args, expected_sql, expected_params): + """The inside of the contract: zero-length results, the empty substring, + the whole-string over-length read and a one-character trim set behave the + same on every backend, so they render. Asserted on the portable baseline + because what is under test is the core spelling, not a dialect's.""" + sql, params = getattr(portable_name, method)(*args).to_sql() + assert sql == expected_sql + assert params == expected_params + + +@pytest.mark.parametrize( + "direction,expected_sql,expected_params", + [ + ("BOTH", 'TRIM("name", ?)', ("x",)), + ("LEADING", 'LTRIM("name", ?)', ("x",)), + ("TRAILING", 'RTRIM("name", ?)', ("x",)), + ], +) +def test_sqlite_spells_trim_as_its_function_form(direction, expected_sql, expected_params): + """SQLite parses no ``trim( from )`` syntax, so the node + renders as the function form there. Same node, dialect-chosen spelling -- + which is why the factory builds a TrimExpression and not a SQL string.""" + dialect = SQLiteDialect() + dialect.version = (3, 46, 1) + column = StringColumn(dialect, "name") + sql, params = column.trim("x", direction).to_sql() + assert sql == expected_sql + assert params == expected_params + + +def test_the_default_spelling_is_the_standard_form(): + """A dialect that speaks the standard form renders it, unchanged from what + the raw SQL used to produce.""" + column = StringColumn(DummyDialect(), "name") + assert column.trim().to_sql() == ('TRIM(BOTH FROM "name")', ()) + assert column.trim("x").to_sql() == ('TRIM(BOTH ? FROM "name")', ("x",)) + + +def test_lpad_defaults_to_a_space_and_passes_it_explicitly(portable_name): + """MySQL raises 1582 without a pad and MariaDB supplies one, so the core + always spells it out instead of letting the backend choose.""" + sql, params = portable_name.lpad(3).to_sql() + assert sql == 'LPAD("name", ?, ?)' + assert params == (3, " ") + + +def test_a_negative_repeat_is_the_empty_string(name): + """PostgreSQL, MySQL, MariaDB and ClickHouse all answer ``''`` for a + negative count; SQL Server answers NULL and Oracle, Firebird and SQLite + lack the function, so the core answers once instead of four times.""" + expr = name.repeat(-1) + assert "REPEAT" not in expr.to_sql()[0] + assert expr.to_sql() == ("?", ("",)) + + +def test_is_distinct_from_renders_the_null_safe_comparison(): + """The default rendering is the standard spelling; backends that spell it + differently override the hook instead of every call site writing dialect + SQL.""" + column = StringColumn(DummyDialect(), "age") + assert column.is_distinct_from(0).to_sql() == ('"age" IS DISTINCT FROM ?', (0,)) + assert column.is_not_distinct_from(0).to_sql() == ('"age" IS NOT DISTINCT FROM ?', (0,)) + + +@pytest.mark.parametrize("version,expected", [((3, 39, 0), True), ((3, 38, 0), False)]) +def test_sqlite_gates_the_spelling_on_its_version(version, expected): + dialect = SQLiteDialect() + dialect.version = version + assert dialect.supports_distinct_from() is expected + + +def test_sqlite_below_the_gate_refuses_rather_than_substituting(): + dialect = SQLiteDialect() + dialect.version = (3, 38, 0) + column = StringColumn(dialect, "age") + with pytest.raises(UnsupportedFeatureError): + column.is_distinct_from(0).to_sql() + + +# --------------------------------------------------------------------------- +# A recorded function version floor is a gate, not a footnote +# --------------------------------------------------------------------------- + + +SQLITE_FUNCTION_FLOORS = [ + ("iif", (3, 32, 0)), + ("pow", (3, 35, 0)), + # json_extract is deliberately absent: the JSON1 functions predate their + # 3.38.0 promotion into core (they exist since 3.9.0 behind a compile-time + # option), so availability depends on how SQLite was built, not on the + # version -- CI's own 3.35.0 server executes json_extract. A recorded floor + # there would refuse SQL the server accepts. + ("unhex", (3, 45, 0)), + ("json_array_insert", (3, 53, 0)), + ("jsonb_array_insert", (3, 53, 0)), +] + + +def _gated_call(dialect, func_name): + """One call to *func_name*, as the renderer meets it: the name the caller + handed over, spelled upper-case in the SQL.""" + return FunctionCall(dialect, func_name, Literal(dialect, "x")) + + +def _one_patch_below(floor): + """The release before *floor*: same major and minor, one patch short.""" + return (floor[0], floor[1], floor[2] - 1) + + +@pytest.mark.parametrize( + "func_name,floor", + SQLITE_FUNCTION_FLOORS, + ids=[func_name for func_name, _floor in SQLITE_FUNCTION_FLOORS], +) +def test_a_floor_the_dialect_is_below_refuses_instead_of_rendering(func_name, floor): + """SQLite records when each function arrived. Rendering one anyway emits + SQL this SQLite will reject, so the floor is a refusal at render time + rather than an observation in a table nobody reads.""" + dialect = SQLiteDialect() + dialect.version = _one_patch_below(floor) + with pytest.raises(UnsupportedFeatureError): + _gated_call(dialect, func_name).to_sql() + + +@pytest.mark.parametrize( + "func_name,floor", + SQLITE_FUNCTION_FLOORS, + ids=[func_name for func_name, _floor in SQLITE_FUNCTION_FLOORS], +) +def test_a_floor_the_dialect_meets_renders(func_name, floor): + """The gate is a floor, not a ban: at the recorded version the same call + renders exactly as it does on a newer one -- the version changes what is + refused, never what is spelled.""" + dialect = SQLiteDialect() + dialect.version = floor + assert _gated_call(dialect, func_name).to_sql() == (f"{func_name.upper()}(?)", ("x",)) + + +def test_the_refusal_names_the_function_the_floor_and_the_version(): + """A refusal the caller cannot act on is only a different way of failing, + so the message says which function, which version it arrived in and which + one is in force: the choice is between a newer server and another + spelling.""" + dialect = SQLiteDialect() + dialect.version = (3, 52, 0) + call = FunctionCall( + dialect, + "json_array_insert", + Literal(dialect, "[]"), + Literal(dialect, "$[0]"), + Literal(dialect, 1), + ) + with pytest.raises(UnsupportedFeatureError) as excinfo: + call.to_sql() + message = str(excinfo.value) + assert "JSON_ARRAY_INSERT" in message + assert "3.53.0" in message + assert "3.52.0" in message + + +def test_the_query_surface_and_the_gate_answer_the_same_thing(): + """``supports_functions`` keeps its shape and stays the query surface; what + changed is that a False in it is no longer advisory. Below the floor both + answer no, at it both answer yes.""" + for version, expected in ((3, 52, 0), False), ((3, 53, 0), True): + dialect = SQLiteDialect() + dialect.version = version + assert dialect.supports_functions()["json_array_insert"] is expected + call = _gated_call(dialect, "json_array_insert") + if expected: + assert call.to_sql() == ("JSON_ARRAY_INSERT(?)", ("x",)) + else: + with pytest.raises(UnsupportedFeatureError): + call.to_sql() + + +def test_a_name_no_floor_is_recorded_for_renders_on_the_oldest_dialect(): + """No floor is not a floor of zero. A name nobody has measured is not + gated here, so it renders on a dialect that predates every gate in the + table -- the gate only ever refuses what a backend declared.""" + dialect = SQLiteDialect() + dialect.version = (3, 8, 0) + assert dialect.function_version_floor("lower") is None + column = StringColumn(dialect, "name") + assert column.lower().to_sql() == ('LOWER("name")', ()) + assert dialect.function_version_floor("pow") == (3, 35, 0) + + +# --------------------------------------------------------------------------- +# The per-dialect spellings, and the emulations behind them +# --------------------------------------------------------------------------- + + +SQLITE_SPELLINGS = [ + ("left", (2,), 'SUBSTR("name", ?, ?)', (1, 2)), + ("right", (2,), 'SUBSTR("name", MAX(LENGTH("name") - ? + ?, ?), ?)', (2, 1, 1, 2)), + ( + "lpad", + (4, "xy"), + 'CASE WHEN ? <= LENGTH("name") THEN SUBSTR("name", ?, ?) ' + 'ELSE SUBSTR(REPLACE(HEX(ZEROBLOB(?)), ?, ?) || "name", - ?) END', + (4, 1, 4, 4, "00", "xy", 4), + ), + ( + "rpad", + (4, "-"), + 'SUBSTR("name" || REPLACE(HEX(ZEROBLOB(?)), ?, ?), ?, ?)', + (4, "00", "-", 1, 4), + ), + ("repeat", (3,), 'REPLACE(HEX(ZEROBLOB(?)), ?, "name")', (3, "00")), + ("ascii", (), 'UNICODE("name")', ()), + ("strpos", ("cd",), 'INSTR("name", ?)', ("cd",)), + ("position", ("cd",), 'INSTR("name", ?)', ("cd",)), +] + + +@pytest.mark.parametrize("method,args,expected_sql,expected_params", SQLITE_SPELLINGS) +def test_sqlite_spells_what_it_lacks(sqlite_dialect, method, args, expected_sql, expected_params): + """SQLite has none of these functions and no ``trim(... from ...)`` syntax, + so each is either renamed, reordered, or emulated out of ordinary nodes -- + measured 2026-10-09 and verified against a real database below. Nothing + here is assembled as a SQL string.""" + column = StringColumn(sqlite_dialect, "name") + sql, params = getattr(column, method)(*args).to_sql() + assert sql == expected_sql + assert params == expected_params + + +def test_sqlite_truncates_with_arithmetic_because_trunc_takes_one_argument(sqlite_dialect): + """SQLite's ``TRUNC`` is unary, so a precision is carried by scaling, + truncating toward zero, and scaling back -- exact for negatives, which + rounding would not be.""" + column = NumericColumn(sqlite_dialect, "n") + sql, params = column.truncate(2).to_sql() + assert sql == 'TRUNC("n" * POW(?, ?)) / POW(?, ?)' + assert params == (10, 2, 10, 2) + assert column.truncate().to_sql() == ('TRUNC("n")', ()) + + +def test_sqlite_takes_the_log_base_first(sqlite_dialect): + """SQLite spells ``log(base, x)`` where the core order is ``log(x, base)``; + the one-argument form is the natural logarithm on both.""" + column = NumericColumn(sqlite_dialect, "n") + assert column.log(10).to_sql() == ("LOG(?, \"n\")", (10,)) + assert column.log().to_sql() == ('LOG("n")', ()) + + +STRING_ROUNDTRIPS = [ + ("left(2)", lambda c: c.left(2), "abcdef", "ab"), + ("left(0)", lambda c: c.left(0), "abcdef", ""), + ("left(99)", lambda c: c.left(99), "abcdef", "abcdef"), + ("right(2)", lambda c: c.right(2), "abcdef", "ef"), + ("right(0)", lambda c: c.right(0), "abcdef", ""), + ("right(99)", lambda c: c.right(99), "abcdef", "abcdef"), + ("lpad(8, 'xy')", lambda c: c.lpad(8, "xy"), "abcdef", "xyabcdef"), + ("lpad(3, 'xy')", lambda c: c.lpad(3, "xy"), "abcdef", "abc"), + ("lpad(4)", lambda c: c.lpad(4), "ab", " ab"), + ("rpad(8, '-')", lambda c: c.rpad(8, "-"), "abcdef", "abcdef--"), + ("rpad(3, '-')", lambda c: c.rpad(3, "-"), "abcdef", "abc"), + ("repeat(3)", lambda c: c.repeat(3), "ab", "ababab"), + ("repeat(0)", lambda c: c.repeat(0), "ab", ""), + ("trim('f')", lambda c: c.trim("f"), "abcdef", "abcde"), + ("trim()", lambda c: c.trim(), " abc ", "abc"), +] + +NUMERIC_ROUNDTRIPS = [ + ("truncate(2)", lambda c: c.truncate(2), 3.14159, 3.14), + ("truncate(2) negative", lambda c: c.truncate(2), -3.14159, -3.14), + ("truncate(0)", lambda c: c.truncate(0), 3.7, 3.0), + ("truncate()", lambda c: c.truncate(), -3.7, -3.0), +] + + +@pytest.mark.parametrize( + "label,build,value,expected", + STRING_ROUNDTRIPS, + ids=[label for label, _build, _value, _expected in STRING_ROUNDTRIPS], +) +def test_the_sqlite_emulation_answers_what_the_function_answers(sqlite_dialect, label, build, value, expected): + """The spelling checks above prove the SQL is *shaped* right; this proves it + *means* right -- each expression is executed against a real SQLite and must + produce the answer PostgreSQL, MySQL and ClickHouse give for the same call. + A spelling that looks correct and answers something else is the failure this + test exists for.""" + import sqlite3 + + connection = sqlite3.connect(":memory:") + connection.execute("CREATE TABLE t (s TEXT)") + connection.execute("INSERT INTO t VALUES (?)", (value,)) + column = StringColumn(sqlite_dialect, "s") + sql, params = build(column).to_sql() + got = connection.execute(f"SELECT {sql} FROM t", tuple(params)).fetchone()[0] + assert got == expected, f"{label}: SQLite answered {got!r}, the function answers {expected!r}" + + +@pytest.mark.parametrize("label,build,value,expected", NUMERIC_ROUNDTRIPS) +def test_the_sqlite_numeric_emulation_answers_what_the_function_answers( + sqlite_dialect, label, build, value, expected +): + import sqlite3 + + connection = sqlite3.connect(":memory:") + connection.execute("CREATE TABLE t (n REAL)") + connection.execute("INSERT INTO t VALUES (?)", (value,)) + column = NumericColumn(sqlite_dialect, "n") + sql, params = build(column).to_sql() + got = connection.execute(f"SELECT {sql} FROM t", tuple(params)).fetchone()[0] + assert got == expected, f"{label}: SQLite answered {got!r}, the function answers {expected!r}" diff --git a/tests/rhosocial/activerecord_test/feature/query/test_operation_symmetry.py b/tests/rhosocial/activerecord_test/feature/query/test_operation_symmetry.py new file mode 100644 index 000000000..3b6e39ca5 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_operation_symmetry.py @@ -0,0 +1,104 @@ +# tests/rhosocial/activerecord_test/feature/query/test_operation_symmetry.py +"""Same-family column and value classes must offer the same operations. + +The P1 unification says a family is one thing on both sides: the class a +``Model.c.`` builds (a column) and the class an operation result builds +(a value) attach the same operation groups, so a value that came out of an +expression can be used exactly like the column it came from. Drift between the +two sides is invisible until a caller hits it -- ``name.length()`` returning a +number that lost an operation the string column still has, say -- so the sets +are asserted equal here. + +Definition of the compared set: + +* public callables plus the operator dunders (``__add__`` ... ``__and__``); +* minus the names provided by :class:`NotANumberMixin`. The refusal set is a + separate axis -- it answers "is this family a number", and whether a side + declares the refusal or merely lacks the operator is pinned where it + belongs (the family's own tests). Comparing the *offered* operations is + what "same family, same groups" means. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_operation_symmetry.py +import pytest + +from rhosocial.activerecord.backend.expression import ( + ArrayColumn, + BinaryColumn, + BooleanColumn, + TimestampColumn, + IntegerColumn, + JSONColumn, + NumericColumn, + StringColumn, + UUIDColumn, + XMLColumn, +) +from rhosocial.activerecord.backend.expression.core import ( + ArrayValueExpression, + BinaryValueExpression, + BooleanValueExpression, + IntegerValueExpression, + JSONValueExpression, + NumericValueExpression, + StringValueExpression, + TimestampValueExpression, + UUIDValueExpression, + XMLValueExpression, +) +from rhosocial.activerecord.backend.expression.mixins import NotANumberMixin + +OPERATORS = { + "__add__", + "__sub__", + "__mul__", + "__truediv__", + "__mod__", + "__and__", + "__or__", + "__invert__", + "__eq__", + "__ne__", + "__lt__", + "__le__", + "__gt__", + "__ge__", +} + +_REFUSALS = {name for name, value in vars(NotANumberMixin).items() if callable(value)} + + +def _operations(cls): + """The operation names *cls* offers: public callables + operator dunders.""" + names = set() + for name in dir(cls): + if name.startswith("_") and name not in OPERATORS: + continue + if callable(getattr(cls, name, None)): + names.add(name) + return names - _REFUSALS + + +FAMILIES = [ + (StringColumn, StringValueExpression), + (NumericColumn, NumericValueExpression), + (IntegerColumn, IntegerValueExpression), + (BooleanColumn, BooleanValueExpression), + (TimestampColumn, TimestampValueExpression), + (BinaryColumn, BinaryValueExpression), + (UUIDColumn, UUIDValueExpression), + (JSONColumn, JSONValueExpression), + (ArrayColumn, ArrayValueExpression), + (XMLColumn, XMLValueExpression), +] + + +@pytest.mark.parametrize("column_class, value_class", FAMILIES, ids=lambda c: c.__name__) +def test_the_two_sides_of_a_family_offer_the_same_operations(column_class, value_class): + column_ops = _operations(column_class) + value_ops = _operations(value_class) + assert column_ops == value_ops, ( + f"{column_class.__name__} and {value_class.__name__} drifted apart:\n" + f" only on the column: {sorted(column_ops - value_ops)}\n" + f" only on the value: {sorted(value_ops - column_ops)}" + ) diff --git a/tests/rhosocial/activerecord_test/feature/query/test_predicate_alias.py b/tests/rhosocial/activerecord_test/feature/query/test_predicate_alias.py new file mode 100644 index 000000000..b682acba9 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_predicate_alias.py @@ -0,0 +1,166 @@ +# tests/rhosocial/activerecord_test/feature/query/test_predicate_alias.py +"""Predicates must be able to carry an alias. + +A predicate is not confined to a WHERE clause. ``LIKE`` and its relatives also +appear in a SELECT list, inside ``CASE WHEN``, in a ``JOIN ... ON`` condition, +and in DDL as a ``CHECK`` constraint or a partial-index predicate. In the +projection case the boolean is a column like any other and needs a name. + +None of the predicate formatters honoured an alias, and ``SQLPredicate`` did +not even offer ``as_()``, so an aliased predicate silently rendered a bare +boolean — or could not be aliased at all. These tests pin the behaviour for +every predicate family, and pin the equally important inverse: no alias means +no ``AS`` in the output. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_predicate_alias.py +import pytest + +from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.backend.expression import Column, Literal, NumericColumn, StringColumn +from rhosocial.activerecord.backend.expression.predicates import ( + IsBooleanPredicate, + IsNullPredicate, +) + + +@pytest.fixture +def dialect(): + d = SQLiteDialect() + d._version = (3, 46, 1) + return d + + +@pytest.fixture +def name(dialect): + # Typed: the families below are exercised through the capability mixins + # (``LIKE`` / ``ILIKE``), which live on the typed classes only. + return StringColumn(dialect, "name", table="t") + + +@pytest.fixture +def qty(dialect): + return NumericColumn(dialect, "qty", table="t") + + +def ident(dialect, alias): + return dialect.format_identifier(alias) + + +# --------------------------------------------------------------------------- +# Every predicate family honours the alias +# --------------------------------------------------------------------------- + + +def _families(dialect, name, qty): + """One aliased predicate per family, keyed by name.""" + return { + "comparison": (name == Literal(dialect, "x")).as_("a"), + "like": name.like("a%").as_("a"), + "ilike": name.ilike("a%").as_("a"), + "logical_and": ((name == Literal(dialect, "x")) & (qty > Literal(dialect, 0))).as_("a"), + "logical_or": ((name == Literal(dialect, "x")) | (qty > Literal(dialect, 0))).as_("a"), + "not": (~(name == Literal(dialect, "x"))).as_("a"), + "in": name.in_([1, 2]).as_("a"), + "between": name.between(Literal(dialect, "a"), Literal(dialect, "z")).as_("a"), + "is_null": IsNullPredicate(dialect, name).as_("a"), + "is_boolean": IsBooleanPredicate(dialect, name, True).as_("a"), + } + + +@pytest.mark.parametrize( + "family", + [ + "comparison", + "like", + "ilike", + "logical_and", + "logical_or", + "not", + "in", + "between", + "is_null", + "is_boolean", + ], +) +def test_predicate_alias_reaches_the_sql(dialect, name, qty, family): + """The alias must appear in the rendered statement.""" + expr = _families(dialect, name, qty)[family] + sql, _ = expr.to_sql() + assert sql.endswith(f"AS {ident(dialect, 'a')}") + assert sql.count("AS ") == 1, f"alias applied more than once: {sql!r}" + + +@pytest.mark.parametrize( + "family", + [ + "comparison", + "like", + "ilike", + "logical_and", + "logical_or", + "not", + "in", + "between", + "is_null", + "is_boolean", + ], +) +def test_unaliased_predicate_has_no_as_clause(dialect, name, qty, family): + """The inverse: no alias must not introduce a stray ``AS``. + + A formatter that appended an empty ``AS`` would be just as broken as one + that dropped the alias, and the regression is invisible unless it is + pinned separately. + """ + expr = _families(dialect, name, qty)[family] + expr = type(expr).as_(expr, expr.alias) + expr.alias = None + sql, _ = expr.to_sql() + assert " AS " not in sql, f"unexpected AS without an alias: {sql!r}" + + +# --------------------------------------------------------------------------- +# The reason this matters: a predicate used as a projected column +# --------------------------------------------------------------------------- + + +def test_projected_predicate_is_named_like_a_column(dialect, name): + """``SELECT name LIKE 'a%' AS is_apple`` is the motivating case.""" + sql, params = name.like("a%").as_("is_apple").to_sql() + assert sql == f'"t"."name" LIKE {dialect.get_parameter_placeholder()} AS {ident(dialect, "is_apple")}' + assert params == ("a%",) + + +def test_alias_works_for_a_bare_column_too(dialect): + """The base behaviour must be unchanged by the predicate change. + + Deliberately a bare ``Column``: the ``name`` fixture is typed now, and this + case is specifically about the untyped reference still aliasing. + """ + sql, _ = Column(dialect, "name", table="t").as_("n").to_sql() + assert sql == f'"t"."name" AS {ident(dialect, "n")}' + + +# --------------------------------------------------------------------------- +# Empty value list: a branch of the IN formatter with its own return +# --------------------------------------------------------------------------- + + +def test_empty_in_list_keeps_its_alias(dialect, name): + """``IN ()`` is a separate return path in the IN formatter.""" + sql, params = name.in_([]).as_("none").to_sql() + assert sql.endswith(f"AS {ident(dialect, 'none')}") + assert params == () + + +# --------------------------------------------------------------------------- +# Parameters are unaffected by aliasing +# --------------------------------------------------------------------------- + + +def test_aliasing_preserves_parameters(dialect, name, qty): + """The alias is pure SQL decoration; bind order must not shift.""" + expr = (name.like("a%") & (qty > Literal(dialect, 5))).as_("both") + _, params = expr.to_sql() + assert params == ("a%", 5) diff --git a/tests/rhosocial/activerecord_test/feature/query/test_string_concatenation_operator.py b/tests/rhosocial/activerecord_test/feature/query/test_string_concatenation_operator.py new file mode 100644 index 000000000..96ec5bfac --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_string_concatenation_operator.py @@ -0,0 +1,158 @@ +# tests/rhosocial/activerecord_test/feature/query/test_string_concatenation_operator.py +"""``||`` is concatenation in SQL and logical OR in several backends. + +PostgreSQL, Oracle, Snowflake, Firebird and ClickHouse read ``||`` as string +concatenation. MySQL and MariaDB read it as logical OR unless the server runs +with ``PIPES_AS_CONCAT``, and SQL Server reads it as logical OR outright. +Emitting the bare token on those backends returns a boolean where a string was +meant — a wrong answer rather than a syntax error, which is why it can survive +a test suite. + +So the node records the *intent* and the dialect picks the spelling. These +tests pin the contract: the intent survives the round trip, the default is the +standard operator, and a dialect that declares a function gets one. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_string_concatenation_operator.py +import pytest + +from rhosocial.activerecord.backend.expression import StringColumn +from rhosocial.activerecord.backend.expression import functions as string_functions +from rhosocial.activerecord.backend.expression.operators import ( + BinaryExpression, + StringConcatExpression, +) + + +@pytest.fixture +def dialect(): + from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + d = SQLiteDialect() + d._version = (3, 46, 1) + return d + + +@pytest.fixture +def operands(dialect): + """Two string columns. + + StringColumn rather than Column: the point of the round trip is that the + result is still a string, and a bare Column carries no string surface to + lose. + """ + return ( + StringColumn(dialect, "a", table="t"), + StringColumn(dialect, "b", table="t"), + ) + + +# --------------------------------------------------------------------------- +# The node carries intent, not an operator +# --------------------------------------------------------------------------- + + +def test_concat_op_builds_an_intent_node(dialect, operands): + left, right = operands + expr = string_functions.concat_op(dialect, left, right) + assert isinstance(expr, StringConcatExpression) + + +def test_intent_node_is_a_binary_expression(dialect, operands): + """Existing BinaryExpression handling must keep working.""" + left, right = operands + expr = string_functions.concat_op(dialect, left, right) + assert isinstance(expr, BinaryExpression) + assert expr.left is left and expr.right is right + + +def test_the_operator_is_not_chosen_by_the_expression(dialect, operands): + """``op`` is fixed, but it is the *node type* that carries the meaning. + + A bare BinaryExpression with op ``||`` says nothing about intent, which is + exactly why concat_op stopped producing one. + """ + left, right = operands + assert StringConcatExpression(dialect, left, right).op == "||" + + +# --------------------------------------------------------------------------- +# The default spelling +# --------------------------------------------------------------------------- + + +def test_default_dialect_uses_the_standard_operator(dialect, operands): + """SQLite and PostgreSQL both read ``||`` as concatenation.""" + left, right = operands + assert dialect.string_concatenation_function() is None + assert string_functions.concat_op(dialect, left, right).to_sql()[ + 0 + ] == '"t"."a" || "t"."b"' + + +def test_a_declared_function_replaces_the_operator(dialect, operands): + """The declaration is consulted, so the same node renders differently.""" + left, right = operands + dialect.STRING_CONCATENATION = "CONCAT" + assert dialect.string_concatenation_function() == "CONCAT" + assert string_functions.concat_op(dialect, left, right).to_sql()[0] == ( + 'CONCAT("t"."a", "t"."b")' + ) + + +def test_declaration_must_be_a_string(dialect): + """A non-string declaration is ignored rather than interpolated.""" + dialect.STRING_CONCATENATION = None + assert dialect.string_concatenation_function() is None + dialect.STRING_CONCATENATION = 42 + assert dialect.string_concatenation_function() is None + + +# --------------------------------------------------------------------------- +# Chaining: the result is a string +# --------------------------------------------------------------------------- + + +def test_result_keeps_the_string_value_surface(operands): + left, _ = operands + result = left.concat_using_operator("x") + for method in ("upper", "substr", "like", "trim", "concat_using_operator"): + assert hasattr(result, method), f"concatenation lost {method}" + + +def test_chaining_after_concatenation(operands): + left, right = operands + sql, _ = left.concat_using_operator(right).upper().to_sql() + assert "UPPER" in sql + assert "||" in sql or "CONCAT" in sql + + +def test_alias_reaches_the_sql(operands): + left, right = operands + sql, _ = left.concat_using_operator(right).as_("joined").to_sql() + assert " AS " in sql + + +def test_no_alias_means_no_as(operands): + left, right = operands + sql, _ = left.concat_using_operator(right).to_sql() + assert " AS " not in sql + + +def test_parameters_are_preserved(operands): + left, right = operands + _, params = left.concat_using_operator(right).to_sql() + assert params == () + + +# --------------------------------------------------------------------------- +# concat_op is not the path for logical OR +# --------------------------------------------------------------------------- + + +def test_logical_or_does_not_go_through_concatenation(operands): + """OR has its own node and formatter, so the two never meet.""" + left, _ = operands + predicate = left.like("a%") | left.like("b%") + assert not isinstance(predicate, StringConcatExpression) + assert " OR " in predicate.to_sql()[0] diff --git a/tests/rhosocial/activerecord_test/feature/query/test_string_value_operations.py b/tests/rhosocial/activerecord_test/feature/query/test_string_value_operations.py new file mode 100644 index 000000000..06f0ac600 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_string_value_operations.py @@ -0,0 +1,207 @@ +# tests/rhosocial/activerecord_test/feature/query/test_string_value_operations.py +"""String value operations belong on the string column, and chain. + +``StringMixin`` used to hold exactly two methods, ``like`` and ``ilike``, and +both returned a predicate. A class named ``StringColumn`` therefore offered no +string operations at all — only the ability to be LIKE-matched — while the 26 +string functions that did exist sat unused in ``functions/string.py``. + +The split this file pins: + +- :class:`StringValueMixin` derives new strings and chains. +- :class:`StringPatternPredicateMixin` answers questions and ends the chain. +- Numeric results stay off the string surface, because ``LENGTH(x) LIKE '3'`` + is a type error in every backend. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_string_value_operations.py +import pytest + +from rhosocial.activerecord.backend.expression import ( + LikePredicate, + StringValueExpression, + build_json_path, +) +from rhosocial.activerecord.backend.expression import functions as string_functions + +from rhosocial.activerecord_test.feature.query.column_helpers import build_column + + +@pytest.fixture +def dialect(): + # The portable baseline dialect, not SQLite: what this file pins is the + # *core* layer -- each operation reaches its factory and the result is a + # typed string. Which spelling a given backend then writes is a per-dialect + # question and lives in test_operation_boundaries.py, where SQLite's + # INSTR/SUBSTR/TRUNC and its pad and repeat emulations are checked against + # a real database. + from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect + + return DummyDialect() + + +@pytest.fixture +def name(dialect): + return build_column(dialect, "name", str) + + +# --------------------------------------------------------------------------- +# The string surface exists and derives +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "method, args, expected_function", + [ + ("upper", (), "UPPER"), + ("lower", (), "LOWER"), + ("initcap", (), "INITCAP"), + ("reverse", (), "REVERSE"), + ("left", (2,), "LEFT"), + ("right", (2,), "RIGHT"), + ("lpad", (5,), "LPAD"), + ("rpad", (5,), "RPAD"), + ("repeat", (2,), "REPEAT"), + ("trim", (), "TRIM"), + ("substr", (1, 3), "SUBSTRING"), + ("replace", ("a", "b"), "REPLACE"), + ("translate", ("ab", "cd"), "TRANSLATE"), + ("overlay", ("x", 2), "OVERLAY"), + ], + ids=lambda v: v if isinstance(v, str) else "", +) +def test_string_operation_renders_its_function( + name, method, args, expected_function +): + """Each operation must reach the factory that already existed.""" + result = getattr(name, method)(*args) + sql, _ = result.to_sql() + assert expected_function in sql + + +def test_string_operations_return_a_typed_string_value(name): + """The result must be a string value, not a bare function call.""" + assert isinstance(name.upper(), StringValueExpression) + + +# --------------------------------------------------------------------------- +# Chaining — the reason the result is typed +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "build, expected_functions", + [ + (lambda c: c.upper(), ["UPPER"]), + (lambda c: c.upper().substr(1, 3), ["UPPER", "SUBSTRING"]), + (lambda c: c.upper().left(2).lower(), ["UPPER", "LEFT", "LOWER"]), + (lambda c: c.trim().replace("a", "b"), ["TRIM", "REPLACE"]), + (lambda c: c.substr(1, 2).upper().lower(), ["SUBSTRING", "UPPER", "LOWER"]), + ], + ids=["one", "two", "three", "trim-replace", "substr-upper-lower"], +) +def test_string_operations_chain(name, build, expected_functions): + """A derived string is still a string, so the next operation exists.""" + sql, _ = build(name).to_sql() + for function in expected_functions: + assert function in sql, f"{function} missing from {sql!r}" + + +def test_chained_result_keeps_the_whole_string_surface(name): + """Three levels deep, the value operations are all still available.""" + result = name.upper().left(2).lower() + for method in ("upper", "lower", "substr", "trim", "concat", "replace"): + assert hasattr(result, method), f"chain lost {method}" + + +def test_chained_result_keeps_the_pattern_predicates(name): + """String-ness is what makes LIKE legal on the result.""" + result = name.upper().left(2) + sql, _ = result.like("A%").to_sql() + assert "LIKE" in sql + assert "UPPER" in sql + + +# --------------------------------------------------------------------------- +# Crossing into the predicate domain ends the value chain +# --------------------------------------------------------------------------- + + +def test_pattern_predicate_terminates_the_chain(name): + """A predicate is a boolean; it never becomes a string again.""" + predicate = name.upper().like("A%") + assert isinstance(predicate, LikePredicate) + for method in ("upper", "substr", "trim", "concat"): + assert not hasattr(predicate, method), ( + f"predicate wrongly offers {method}; the value chain should have ended" + ) + + +def test_predicate_still_combines(name): + """Ending the value chain does not end the predicate chain.""" + combined = (name.like("A%") | name.like("B%")) & name.ilike("%x%") + sql, _ = combined.to_sql() + assert " OR " in sql and " AND " in sql + + +# --------------------------------------------------------------------------- +# Numeric results are not on the string surface +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "factory", ["length", "ascii", "octet_length", "bit_length"] +) +def test_numeric_result_is_not_a_string_value(dialect, name, factory): + """``LENGTH(x) LIKE '3'`` is a type error; the surface must not offer it.""" + result = getattr(string_functions, factory)(dialect, name) + assert not isinstance(result, StringValueExpression) + + +@pytest.mark.parametrize( + "method, args", + [("length", ()), ("ascii", ()), ("strpos", ("x",)), ("position", ("x",))], +) +def test_string_column_offers_them_but_the_result_is_not_a_string(name, method, args): + """A legal string operation whose *result* is a number. + + ``LENGTH(s) LIKE '3'`` is still a type error, but it is caught by the + result's type rather than by hiding the method. Hiding it would be wrong: + these are well-defined on every backend, and ``strpos`` and ``position`` + differ in availability, so "does a string offer it" is not the same + question as "is the answer a string". + """ + assert hasattr(name, method), f"StringColumn lost a legal operation {method}()" + result = getattr(name, method)(*args) + assert not isinstance(result, StringValueExpression) + + +# --------------------------------------------------------------------------- +# Existing behaviour is preserved +# --------------------------------------------------------------------------- + + +def test_free_functions_still_work_and_are_now_typed(dialect, name): + """Existing call sites keep working; they gain the string type.""" + result = string_functions.upper(dialect, name) + assert isinstance(result, StringValueExpression) + assert result.like("A%").to_sql()[0].endswith("LIKE ?") + + +def test_concat_includes_the_receiver(dialect, name): + """A variadic factory must receive the column as an operand. + + Passing the operand list as a single argument would bind the whole list to + one placeholder, which is what an earlier version of the mixin did. + """ + other = build_column(dialect, "other", str) + sql, params = name.concat(other, "x").to_sql() + assert sql.count("?") == 1 + assert params == ("x",) + assert '"other"' in sql + + +def test_json_path_builder_is_untouched(): + """The integer-index rule is a separate concern and must not regress.""" + assert build_json_path("tags", 0) == "$.tags[0]" + assert build_json_path("tags", "0") == "$.tags.0" diff --git a/tests/rhosocial/activerecord_test/feature/query/test_temporal_value_families.py b/tests/rhosocial/activerecord_test/feature/query/test_temporal_value_families.py new file mode 100644 index 000000000..936d79ccb --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_temporal_value_families.py @@ -0,0 +1,261 @@ +# tests/rhosocial/activerecord_test/feature/query/test_temporal_value_families.py +"""What each temporal operation answers with. + +A datetime is not one type. ``YEAR(ts)`` is a whole number, ``EXTRACT`` is a +number, ``NOW() + interval`` is a timestamp again, and ``NOW() - NOW()`` is an +interval. Getting these confused is silent — the SQL is still valid and +the answer is simply the wrong kind of thing — so each one is pinned here. + +The result's family is what decides the next operation, so the surface is +asserted too: a year may be added to, a timestamp may not be upper-cased. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_temporal_value_families.py +import datetime + +import pytest + +from rhosocial.activerecord.backend.expression import functions as datetime_functions +from rhosocial.activerecord.backend.expression.core import ( + DateValueExpression, + TimeValueExpression, + TimestampValueExpression, + IntervalValueExpression, + NumericValueExpression, + IntegerValueExpression, +) +from rhosocial.activerecord.backend.expression.datetime import ( + DateTimeAddExpression, + DateTimeSubtractExpression, +) +from rhosocial.activerecord.backend.expression.operators import BinaryArithmeticExpression + + +@pytest.fixture +def dialect(): + from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + d = SQLiteDialect() + d._version = (3, 46, 1) + return d + + +@pytest.fixture +def timestamp(dialect): + from rhosocial.activerecord_test.feature.query.column_helpers import build_column + + return build_column(dialect, "ts", datetime.datetime) + + +# --------------------------------------------------------------------------- +# The present, in each of its precisions +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "factory, cls", + [ + ("now", TimestampValueExpression), + ("current_timestamp", TimestampValueExpression), + ("localtimestamp", TimestampValueExpression), + ("current_date", DateValueExpression), + ("current_time", TimeValueExpression), + ], +) +def test_the_present_keeps_its_precision(dialect, factory, cls): + """A date is not a timestamp and a time is not either. + + Four separate classes now, where there was one class and a label saying + which it was standing in for. Each factory returns the class its own + precision calls for, and that is readable off the result. + """ + assert isinstance(getattr(datetime_functions, factory)(dialect), cls) + + +# --------------------------------------------------------------------------- +# Pulling a component out of a timestamp gives a whole number +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "factory", ["year", "month", "day", "hour", "minute", "second"] +) +def test_a_component_is_a_whole_number(dialect, timestamp, factory): + assert isinstance(getattr(datetime_functions, factory)(dialect, timestamp), IntegerValueExpression) + + +def test_a_component_takes_arithmetic_and_not_string_operations(dialect, timestamp): + """A year is a number, so the number surface follows and the string one + does not. Getting this wrong is how ``str(year(ts))`` sneaks in.""" + year = datetime_functions.year(dialect, timestamp) + assert hasattr(year, "__add__") + assert not hasattr(year, "upper") + + +# --------------------------------------------------------------------------- +# Extraction is numeric because the unit decides it +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("factory", ["extract", "date_part"]) +def test_extraction_is_numeric(dialect, timestamp, factory): + """``EXTRACT(EPOCH FROM ts)`` is fractional, so the family is too wide to + be a whole number. Widening here is deliberate: claiming integer would + offer ``bit_length`` on a value that may be a million and a half.""" + assert isinstance(getattr(datetime_functions, factory)(dialect, "year", timestamp), NumericValueExpression) + + +def test_date_diff_counts_whole_units(dialect): + now = datetime_functions.now(dialect) + assert isinstance(now.date_diff("day", now), IntegerValueExpression) + + +# --------------------------------------------------------------------------- +# Arithmetic on time stays time +# --------------------------------------------------------------------------- + + +def test_truncation_stays_a_timestamp(dialect): + assert isinstance(datetime_functions.now(dialect).date_trunc("day"), TimestampValueExpression) + + +@pytest.mark.parametrize("method", ["date_add", "date_sub"]) +def test_shifting_time_stays_a_timestamp(dialect, method): + now = datetime_functions.now(dialect) + result = getattr(now, method)(1, "days") + assert isinstance(result, TimestampValueExpression) + assert isinstance(result, (DateTimeAddExpression, DateTimeSubtractExpression)) + + +def test_an_interval_is_its_own_family(dialect): + """A span is not a point in time, which is why date_add takes one.""" + assert isinstance(datetime_functions.interval(dialect, 1, "day"), IntervalValueExpression) + + +# --------------------------------------------------------------------------- +# The operators are interval-based; a point in time has no sum +# --------------------------------------------------------------------------- + + +def test_a_timestamp_moves_by_an_interval(dialect): + """Constructed, not rendered: SQLite has no interval node yet (the + emulation belongs to the data-type step), and what this test pins is the + gate that lets the combination through at all.""" + now = datetime_functions.now(dialect) + one_day = datetime_functions.interval(dialect, 1, "day") + expression = now + one_day + assert isinstance(expression, BinaryArithmeticExpression) + + +def test_two_points_subtract_to_an_interval(dialect): + now = datetime_functions.now(dialect) + sql, params = (now - now).to_sql() + assert "-" in sql + + +def test_two_points_have_no_sum(dialect): + """``created_at + created_at`` used to render and fail only in SQL.""" + now = datetime_functions.now(dialect) + with pytest.raises(AttributeError, match="no sum"): + now + now + + +def test_interval_arithmetic_stays_between_intervals(dialect): + one_day = datetime_functions.interval(dialect, 1, "day") + two_days = datetime_functions.interval(dialect, 2, "day") + for expression in (one_day + two_days, one_day - two_days, one_day * 2): + assert isinstance(expression, BinaryArithmeticExpression) + + +def test_a_number_does_not_move_a_point_in_time(dialect): + now = datetime_functions.now(dialect) + with pytest.raises(AttributeError): + now + 1 + + +def test_a_span_is_not_divided(dialect): + one_day = datetime_functions.interval(dialect, 1, "day") + with pytest.raises(AttributeError): + one_day / 2 + + +def test_a_temporal_column_follows_the_same_gate(dialect, timestamp): + """The column and the value are the same expression layer, so the gate + has to see a temporal *column* as a temporal operand too.""" + one_day = datetime_functions.interval(dialect, 1, "day") + assert isinstance(timestamp + one_day, BinaryArithmeticExpression) + assert isinstance(timestamp - timestamp, BinaryArithmeticExpression) + with pytest.raises(AttributeError, match="no sum"): + timestamp + timestamp + + +# --------------------------------------------------------------------------- +# A node with a class of its own is its type; there is nothing to declare +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "factory, args, result_cls", + [ + ("extract", ("year",), NumericValueExpression), + ("date_part", ("year",), NumericValueExpression), + ("interval", (1, "day"), IntervalValueExpression), + ("date_diff", ("day",), IntegerValueExpression), + ], +) +def test_a_temporal_operation_yields_its_own_type(dialect, timestamp, factory, args, result_cls): + """What a temporal operation yields is decided where it is built. + + ``EXTRACT`` yields a number and ``DATE_DIFF`` a whole number; each is + decided by the factory that builds the node, and neither needed a label to + say so afterwards. + """ + if factory == "interval": + result = getattr(datetime_functions, factory)(dialect, *args) + elif factory == "date_diff": + result = getattr(datetime_functions, factory)(dialect, *args, timestamp, timestamp) + else: + result = getattr(datetime_functions, factory)(dialect, *args, timestamp) + assert isinstance(result, result_cls) + + +def test_a_temporal_value_offers_temporal_operations(dialect): + now = datetime_functions.now(dialect) + for method in ("date_add", "date_sub", "date_diff", "date_part", "extract"): + assert hasattr(now, method), f"a timestamp lost {method}" + + +def test_a_temporal_value_does_not_offer_string_operations(dialect): + assert not hasattr(datetime_functions.now(dialect), "upper") + + +@pytest.mark.parametrize( + "cls", + [TimestampValueExpression, DateValueExpression, TimeValueExpression, + IntervalValueExpression], +) +def test_each_temporal_type_is_its_own_class(dialect, cls): + """They offer the same operations, so they share a base -- but they are four + different types, and each says so with its own class.""" + from rhosocial.activerecord.backend.expression import FunctionCall + from rhosocial.activerecord.backend.expression.core import TemporalValueExpression + + wrapped = cls(dialect, FunctionCall(dialect, "SOME_FUNC")) + assert isinstance(wrapped, cls) + assert isinstance(wrapped, TemporalValueExpression) + assert hasattr(wrapped, "date_add") + + +def test_the_sql_does_not_change_when_a_value_is_wrapped(dialect, timestamp): + """Typing is a surface decision, never a rendering one.""" + from rhosocial.activerecord.backend.expression import FunctionCall + + call = FunctionCall(dialect, "MY_FUNC", timestamp) + assert TimestampValueExpression(dialect, call).to_sql() == call.to_sql() + + +def test_an_alias_survives_wrapping(dialect, timestamp): + from rhosocial.activerecord.backend.expression import FunctionCall + + call = FunctionCall(dialect, "MY_FUNC", timestamp) + assert " AS " in TimestampValueExpression(dialect, call).as_("when").to_sql()[0] diff --git a/tests/rhosocial/activerecord_test/feature/query/test_typed_columns.py b/tests/rhosocial/activerecord_test/feature/query/test_typed_columns.py new file mode 100644 index 000000000..4a4289517 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_typed_columns.py @@ -0,0 +1,396 @@ +# tests/rhosocial/activerecord_test/feature/query/test_typed_columns.py +"""Type-narrowed column expressions. + +The column a model field resolves to depends on the field's Python +annotation, so a numeric field offers arithmetic and no ``.like()``, a JSON +field offers path access, and so on. These tests pin the selection the field +accessor makes, the narrowing it produces, and the guarantees that make it +safe to rely on. + +No database is involved — every assertion is on the expression tree or the +SQL a dialect produces from it — so no provider fixture is required. +""" + +import datetime +import decimal +import typing +import uuid +from typing import Any, ClassVar, Dict, List, Optional, Union + +import pytest + +from rhosocial.activerecord.backend.expression import ( + ArrayColumn, + BinaryColumn, + BooleanColumn, + Column, + ColumnBase, + TimestampColumn, + IntegerColumn, + JSONColumn, + NumericColumn, + StringColumn, + UUIDColumn, + build_json_path, +) +from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect +from rhosocial.activerecord.base.field_proxy import ( + ColumnTypeResolutionError, + FieldAccessor, + FieldProxy, +) +from rhosocial.activerecord.base.fields import UseColumnType +from rhosocial.activerecord.model import ActiveRecord + +from rhosocial.activerecord_test.feature.query.column_helpers import ( + build_column, + resolve_column_class, +) + + +def column_class_for(annotation, dialect=None): + """The class the field accessor's selection picks for *annotation*. + + A one-line shim so the cases below read as "resolve this annotation" the + way ``Model.c.`` does it. The selection lives on + :class:`FieldAccessor`; a free framework-level function would have to + invent a backend or reach for a core-side table, which is the + core-authority shape the architecture removed. + """ + if dialect is None: + dialect = sqlite_dialect() + return resolve_column_class(dialect, annotation) + + +def sqlite_dialect(): + """A version-adapted SQLite dialect. + + ``supports_json_*`` reads ``self.version``, so the dialect must be + adapted before any rendering; 3.46 satisfies every gate these tests + exercise (JSON arrows need 3.38). + """ + dialect = SQLiteDialect() + dialect._version = (3, 46, 1) + return dialect + + +# --------------------------------------------------------------------------- +# Selection: annotation -> column class +# --------------------------------------------------------------------------- + +_DISPATCH = [ + (str, StringColumn), + (int, IntegerColumn), + (float, NumericColumn), + (bool, BooleanColumn), + (bytes, BinaryColumn), + (dict, JSONColumn), + # No array type exists in SQLite, so a `list` field is a JSON document here + # rather than an ArrayColumn. The same model on PostgreSQL gets a real array; + # that divergence is the protocol working, not a bug (see + # `test_column_type_support.py`). + (list, JSONColumn), + (decimal.Decimal, NumericColumn), + (datetime.datetime, TimestampColumn), + (datetime.date, TimestampColumn), + (datetime.timedelta, NumericColumn), + (uuid.UUID, UUIDColumn), +] + + +@pytest.mark.parametrize("annotation, expected", _DISPATCH, ids=lambda v: getattr(v, "__name__", str(v))) +def test_dispatch_by_annotation(annotation, expected): + assert column_class_for(annotation) is expected + + +@pytest.mark.parametrize( + "annotation", + [ + Optional[str], + Optional[dict], + ], + ids=lambda v: str(v), +) +def test_optional_annotations_resolve_to_the_inner_entry(annotation): + assert column_class_for(annotation) in {StringColumn, JSONColumn} + + +@pytest.mark.parametrize( + "annotation", + [ + List[int], # a parameterised container is not classifiable + Dict[str, int], + Union[int, str], # genuinely ambiguous + Any, + ], + ids=lambda v: str(v), +) +def test_unclassifiable_annotations_fail(annotation): + """No guessing, and no escape: each of these raises at build time. + + This is the "全量或失败" ruling. These four used to become the permissive + ``Column``, which offered every operation to a value whose type nothing was + known about — so ``Model.c.meta.like('%x%')`` rendered happily and failed at + the database, with the error pointing at the SQL rather than at the + annotation that caused it. Narrowing exists to catch that at the point the + field is declared, so a hole in it is a hole in the guarantee. + + ``UseColumnType`` is the way through: it says which operations the value + carries, which is a statement the framework can honour on any backend. + """ + with pytest.raises(ColumnTypeResolutionError) as excinfo: + column_class_for(annotation) + assert "UseColumnType" in str(excinfo.value) + + +def test_optional_and_annotated_are_stripped(): + # typing.Annotated arrived in 3.9 and this project supports 3.8, so the + # alias is built the way the runtime marks one on every version. + Annotated = getattr(typing, "Annotated", None) + if Annotated is None: + pytest.skip("typing.Annotated requires Python 3.9+") + + strip = FieldAccessor._strip_annotation + assert strip(Optional[dict]) is dict + assert strip(Annotated[str, "some-marker"]) is str + assert strip(Optional[Annotated[str, "m"]]) is str + + +# --------------------------------------------------------------------------- +# Narrowing: each family offers only what its value type supports +# --------------------------------------------------------------------------- + + +def test_string_column_has_like_but_no_arithmetic(): + col = build_column(sqlite_dialect(), "name", str) + assert isinstance(col, StringColumn) + assert hasattr(col, "like") and hasattr(col, "ilike") + assert not hasattr(col, "__add__") + + +def test_integer_column_has_arithmetic_but_no_like(): + col = build_column(sqlite_dialect(), "age", int) + assert isinstance(col, IntegerColumn) + assert hasattr(col, "__add__") and hasattr(col, "__mul__") + assert not hasattr(col, "like") + + +def test_json_column_has_path_access_only(): + col = build_column(sqlite_dialect(), "settings", dict) + assert isinstance(col, JSONColumn) + assert hasattr(col, "json_path") and hasattr(col, "json_value") + assert not hasattr(col, "like") + assert not hasattr(col, "__add__") + + +def test_uuid_column_offers_no_uuid_specific_operator(): + """Portable SQL has none, so a UUID column is just a value column.""" + col = build_column(sqlite_dialect(), "uid", uuid.UUID) + assert isinstance(col, UUIDColumn) + assert not hasattr(col, "like") + assert not hasattr(col, "__add__") + assert not hasattr(col, "json_path") + + +def test_bare_column_offers_no_operation(): + """The hand-built ``Column`` is a reference, and references do not guess. + + Nothing established what the column holds, so offering an operation + would be a promise the database never made — and the previous shape had + the failure the typed classes exist to prevent: comparing two of them + answered Python's identity question silently. The class renders (its one + job), the shared surface answers questions about the *reference* itself, + and predicates are built explicitly where the column's type is unknown. + """ + col = Column(sqlite_dialect(), "anything") + assert col.to_sql() == ('"anything"', ()) + for operation in ("like", "__add__", "json_path", "in_", "upper"): + assert not hasattr(col, operation), f"a bare column wrongly offers {operation}" + + +# --------------------------------------------------------------------------- +# Rendering: unchanged SQL, and a common format_column +# --------------------------------------------------------------------------- + +_RENDER_CLASSES = [ + Column, StringColumn, NumericColumn, TimestampColumn, BooleanColumn, + BinaryColumn, UUIDColumn, JSONColumn, ArrayColumn, +] + + +@pytest.mark.parametrize("column_class", _RENDER_CLASSES, ids=lambda c: c.__name__) +def test_every_column_class_renders_identically(column_class): + """Narrowing changed the API, not the SQL.""" + dialect = sqlite_dialect() + col = column_class(dialect, "settings", table="t", schema_name="s") + assert col.to_sql() == ('"s"."t"."settings"', ()) + + +@pytest.mark.parametrize("column_class", _RENDER_CLASSES, ids=lambda c: c.__name__) +def test_every_column_class_is_a_column_base(column_class): + """The 8 isinstance() consumers test for ColumnBase, so all must match.""" + assert isinstance(column_class(sqlite_dialect(), "x"), ColumnBase) + + +@pytest.mark.parametrize("column_class", _RENDER_CLASSES, ids=lambda c: c.__name__) +def test_qualified_and_aliased_rendering(column_class): + dialect = sqlite_dialect() + assert column_class(dialect, "c").to_sql() == ('"c"', ()) + assert column_class(dialect, "c", table="t").to_sql() == ('"t"."c"', ()) + assert column_class(dialect, "c", alias="a").to_sql() == ('"c" AS "a"', ()) + + +# --------------------------------------------------------------------------- +# JSON path building +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "keys, expected", + [ + ((), "$"), + (("a",), "$.a"), + (("a", "b"), "$.a.b"), + (("tags", 0), "$.tags[0]"), + (("a", 0, "b"), "$.a[0].b"), + (("tags", "[0]"), "$.tags[0]"), + ], + ids=lambda v: str(v), +) +def test_build_json_path(keys, expected): + assert build_json_path(*keys) == expected + + +def test_string_zero_is_a_key_not_an_index(): + """``"0"`` names a key; only an int is an index. + + ``$.tags.0`` is a key literally named ``0`` and matches nothing, so the + distinction is carried by the type rather than the spelling. + """ + assert build_json_path("tags", "0") == "$.tags.0" + assert build_json_path("tags", 0) == "$.tags[0]" + + +def test_bool_is_rejected_as_a_path_segment(): + """bool is an int subclass; silently treating True as index 1 is a trap.""" + with pytest.raises(TypeError, match="bool"): + build_json_path("a", True) + + +def test_json_path_renders_bracket_for_integer_index(): + dialect = sqlite_dialect() + col = build_column(dialect, "settings", dict) + assert col.json_path("tags", 0).to_sql() == ('"settings"->>\'$.tags[0]\'', ()) + + +def test_json_path_chains_without_renesting_the_path(): + """Chaining accumulates; it must not re-anchor the second path at ``$``.""" + dialect = sqlite_dialect() + col = build_column(dialect, "settings", dict) + assert col.json_value("a").json_value("b").to_sql() == ( + '"settings"->\'$.a\'->\'$.b\'', + (), + ) + + +def test_json_path_alias_lands_on_the_outermost_form(): + dialect = sqlite_dialect() + col = build_column(dialect, "settings", dict) + assert col.as_("j").json_path("a").to_sql() == ('"settings"->>\'$.a\' AS "j"', ()) + + +# --------------------------------------------------------------------------- +# End to end through FieldProxy +# --------------------------------------------------------------------------- + + +def _annotated(): + """``typing.Annotated``, or a skip — the alias is 3.9+ and this file is 3.8-safe.""" + alias = getattr(typing, "Annotated", None) + if alias is None: + pytest.skip("typing.Annotated requires Python 3.9+") + return alias + + +def _model(dialect): + Annotated = _annotated() + + class Widget(ActiveRecord): + __table_name__ = "typed_widget" + __primary_key__: ClassVar[str] = "id" + c: ClassVar[FieldProxy] = FieldProxy() + + id: int + name: str + qty: int + price: decimal.Decimal + created: datetime.datetime + settings: dict + tags: list + uid: uuid.UUID + flag: bool + # `Any` is not classifiable, so this field has to say what its value can + # do. The declaration is the whole point: without it the field does not + # resolve at all, which is the "全量或失败" ruling applied to a model. + meta: Annotated[Any, UseColumnType(JSONColumn)] + + Widget.__backend__ = type("B", (), {"dialect": dialect})() + return Widget + + +@pytest.mark.parametrize( + "field, expected", + [ + ("id", IntegerColumn), + ("name", StringColumn), + ("qty", IntegerColumn), + ("price", NumericColumn), + ("created", TimestampColumn), + ("settings", JSONColumn), + ("tags", JSONColumn), + ("uid", UUIDColumn), + ("flag", BooleanColumn), + ("meta", JSONColumn), # Any, resolved through UseColumnType + ], +) +def test_field_proxy_returns_the_matching_class(field, expected): + Widget = _model(sqlite_dialect()) + assert type(getattr(Widget.c, field)) is expected + + +def test_field_proxy_refuses_an_undeclared_any(): + """A model field typed ``Any`` with no declaration fails where it is read. + + The proxy is where a column is built, so this is the earliest point at which + the model can be told — and telling it here beats a driver error naming a + column at query time. + """ + + class Loose(ActiveRecord): + __table_name__ = "typed_loose" + __primary_key__: ClassVar[str] = "id" + c: ClassVar[FieldProxy] = FieldProxy() + + id: int + meta: Any + + Loose.__backend__ = type("B", (), {"dialect": sqlite_dialect()})() + with pytest.raises(ColumnTypeResolutionError, match="UseColumnType"): + # The proxy builds the column on attribute access, so the bare + # expression is the call under test -- the same shape as the + # AttributeError case below it. + Loose.c.meta # noqa: B018 + + +def test_field_proxy_query_uses_narrowed_operations(): + dialect = sqlite_dialect() + Widget = _model(dialect) + sql, params = Widget.query().where(Widget.c.settings.json_path("lang") == "en").to_sql() + assert sql == """SELECT * FROM "typed_widget" WHERE "typed_widget"."settings"->>'$.lang' = ?""" + assert params == ("en",) + + +def test_field_proxy_unknown_field_still_raises_attribute_error(): + Widget = _model(sqlite_dialect()) + with pytest.raises(AttributeError, match="does not exist on model"): + Widget.c.no_such_field diff --git a/tests/rhosocial/activerecord_test/feature/query/test_value_family_inference.py b/tests/rhosocial/activerecord_test/feature/query/test_value_family_inference.py new file mode 100644 index 000000000..e572e85db --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_value_family_inference.py @@ -0,0 +1,235 @@ +# tests/rhosocial/activerecord_test/feature/query/test_value_family_inference.py +"""Result families, and the lattice they add up to. + +A family is what decides an expression's operation surface, and it has to be +accurate in both directions. Over-narrowing removes a legal operation; +over-widening offers an illegal one. Both failures are silent — the SQL is +still produced, it is just wrong — so the families are pinned here. + +The distinction that matters most is whole number against fraction. ``int`` and +``float`` share a column class, so the family has to come from the annotation +rather than the class, or "integer in, integer out" cannot be expressed and +``ceil`` of an integer claims to be fractional. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_value_family_inference.py +import datetime +import decimal +import uuid + +import pytest + +from rhosocial.activerecord.backend.expression import Column, FunctionCall, Literal +from rhosocial.activerecord.backend.expression import functions as F +from rhosocial.activerecord.backend.expression import IntegerColumn, NumericColumn +from rhosocial.activerecord.backend.expression.column_types import value_class_of +from rhosocial.activerecord.backend.expression.core import ( + ArrayValueExpression, + BinaryValueExpression, + BooleanValueExpression, + DateValueExpression, + IntegerValueExpression, + IntervalValueExpression, + JSONValueExpression, + NumericValueExpression, + StringValueExpression, + TimeValueExpression, + TimestampValueExpression, + UUIDValueExpression, + XMLValueExpression, +) +from rhosocial.activerecord.backend.expression import functions as math_functions + +#: Every value class the lattice holds, for the "declares nothing" assertions. +TYPED_VALUE_CLASSES = ( + ArrayValueExpression, + BinaryValueExpression, + BooleanValueExpression, + DateValueExpression, + IntegerValueExpression, + IntervalValueExpression, + JSONValueExpression, + NumericValueExpression, + StringValueExpression, + TimeValueExpression, + TimestampValueExpression, + UUIDValueExpression, + XMLValueExpression, +) + + +@pytest.fixture +def dialect(): + from rhosocial.activerecord.backend.impl.sqlite.dialect import SQLiteDialect + + d = SQLiteDialect() + d._version = (3, 46, 1) + return d + + +@pytest.fixture +def columns(dialect): + from rhosocial.activerecord_test.feature.query.column_helpers import build_column + + return { + "string": build_column(dialect, "s", str), + "int": build_column(dialect, "i", int), + "float": build_column(dialect, "f", float), + "bool": build_column(dialect, "b", bool), + "json": build_column(dialect, "j", dict), + "bytes": build_column(dialect, "y", bytes), + "uuid": build_column(dialect, "u", uuid.UUID), + "datetime": build_column(dialect, "d", datetime.datetime), + } + + +# --------------------------------------------------------------------------- +# A column's family comes from its annotation +# --------------------------------------------------------------------------- + + +def test_every_column_class_has_a_value_class(columns): + """The map is complete, so no column class is silently untyped. + + There is no registry of family *names* to be complete any more -- a type is + a class. But there is a table from column class to value class (see + ``column_types.value_class_of``), and a column class missing from it would + make every operation over that column quietly untyped, which is the failure + this file exists to catch. So it is checked here instead of assumed. + """ + import inspect + + from rhosocial.activerecord.backend.expression import column_types as CT + + declared = { + name + for name, klass in vars(CT).items() + if inspect.isclass(klass) + and issubclass(klass, CT.ColumnBase) + and klass is not CT.ColumnBase + } + assert declared, "the typed column classes moved" + for name in sorted(declared): + column = getattr(CT, name).__new__(getattr(CT, name)) + assert value_class_of(column) is not None, f"{name} has no value class" + # The base is now an ABC, so there is no "untyped column object" left to + # map -- not being able to build one is the stronger form of the same + # invariant. The untyped column that *can* be built is the bare ``Column``, + # which lives outside this module, and staying unmapped is still the point. + assert inspect.isabstract(CT.ColumnBase), "the typed base must not be instantiable" + from rhosocial.activerecord.backend.expression import Column as BareColumn + + assert value_class_of(BareColumn.__new__(BareColumn)) is None + + +def test_every_core_data_type_has_a_value_class_or_is_explicitly_impossible(): + """The DDL-type -> value-class map is closed, so a cast cannot go silently + untyped. + + There is a second completeness question beside the column one above, and it + is asked of the *target* side of a cast: ``cast`` answers from the class of + the ``DataType`` it was handed (``type_conversion._type_value_classes()``), + so a core type missing from that table would make every cast to it come + back untyped and the operations its value supports invisible. A type added + to the core without a map entry must therefore be a test failure here, not + a quiet degradation. + + The loop walks every concrete core ``DataType`` currently loaded rather + than a hand-kept list, so a new core type file cannot dodge it by not being + imported. + + ``CustomType`` is the one deliberate exception and is asserted as such: it + is the escape hatch for a name this library does not model, so there is no + family it could honestly promise operations on (see its docstring), and the + map deliberately leaves it out. + """ + import inspect + + from rhosocial.activerecord.backend.expression import types as core_types + from rhosocial.activerecord.backend.expression.functions.type_conversion import ( + _type_value_classes, + ) + + core_prefix = "rhosocial.activerecord.backend.expression.types" + seen = set() + stack = [core_types.DataType] + while stack: + klass = stack.pop() + if klass in seen: + continue + seen.add(klass) + stack.extend(klass.__subclasses__()) + declared = { + klass.__name__: klass + for klass in seen + if klass is not core_types.DataType + and not inspect.isabstract(klass) + and klass.__module__.startswith(core_prefix) + } + assert declared, "the core types moved" + + mapping = _type_value_classes() + # The exception, stated rather than merely skipped. ``CustomType`` is the + # escape hatch for a type nobody here has heard of; mapping it to any value + # class would offer operations the database may reject. Asserting it stays + # unmapped is what keeps the exception the only one. + assert core_types.CustomType in declared.values() + assert core_types.CustomType not in mapping, ( + "CustomType must not map to a value class: it exists precisely because " + "nothing here knows what the type is, so no value surface can be " + "claimed for it" + ) + + for name, klass in sorted(declared.items()): + if klass is core_types.CustomType: + continue + assert any(base in mapping for base in klass.__mro__), ( + f"{name} has no value class: add it to " + f"functions/type_conversion._type_value_classes(), or add it to " + f"the deliberate-exception list here with the reason it cannot " + f"honestly have one" + ) + + +def test_a_bare_function_call_has_no_family(dialect, columns): + """It says nothing about what a database would return.""" + call = FunctionCall(dialect, "MY_FUNC", columns["string"]) + assert not isinstance(call, TYPED_VALUE_CLASSES) + + +def test_a_hand_written_column_has_no_family(dialect): + """A permissive Column means "unknown type", which is not the same as any.""" + assert not isinstance(Column(dialect, "x", table="t"), TYPED_VALUE_CLASSES) + + +@pytest.mark.parametrize( + "key, expected", + [ + ("string", StringValueExpression), + ("int", IntegerValueExpression), + ("float", NumericValueExpression), + ("bool", BooleanValueExpression), + ("json", JSONValueExpression), + ("bytes", BinaryValueExpression), + ("uuid", UUIDValueExpression), + ("datetime", TimestampValueExpression), + ], +) +def test_each_annotation_lands_in_its_type(columns, key, expected): + """The annotation picks the column class, and the class picks the value class. + + This used to compare against a family *name* read off an attribute. The + attribute is gone and the class is the whole of it, so the assertion is the + class an operation over that column now returns. + """ + assert value_class_of(columns[key]) is expected + + +def test_a_disagreement_yields_no_type(dialect, columns): + """GREATEST of an integer and a string is legal SQL and is neither, so the + call stays generic rather than promising the first or the widest.""" + mixed = F.greatest(dialect, columns["int"], columns["string"]) + assert not isinstance(mixed, TYPED_VALUE_CLASSES) + assert mixed.to_sql() == FunctionCall( + dialect, "GREATEST", columns["int"], columns["string"] + ).to_sql() diff --git a/tests/rhosocial/activerecord_test/feature/query/test_value_type_lattice.py b/tests/rhosocial/activerecord_test/feature/query/test_value_type_lattice.py new file mode 100644 index 000000000..72680c8a7 --- /dev/null +++ b/tests/rhosocial/activerecord_test/feature/query/test_value_type_lattice.py @@ -0,0 +1,197 @@ +# tests/rhosocial/activerecord_test/feature/query/test_value_type_lattice.py +"""Every operation declares a result type, and the type gates the next operation. + +The rule this file pins: an operation's result determines which operations are +available next. ``upper()`` returns a string, so ``substr()`` follows. +``length()`` is a legal string operation whose result is a *number*, so +``upper()`` does not — and that falls out of the types rather than out of a +check somewhere. + +The two halves that are easy to get wrong are both pinned here: a result must +not lose its own surface, and it must not gain a surface belonging to another +family. +""" + +# tests/rhosocial/activerecord_test/feature/query/test_value_type_lattice.py +import pytest + +from rhosocial.activerecord.backend.expression import ( + IntegerValueExpression, +) + + +@pytest.fixture +def dialect(): + # The portable baseline: this file pins result *types* and the core + # spellings. Which spelling a backend writes is checked in + # test_operation_boundaries.py, against SQLite and a real database. + from rhosocial.activerecord.backend.impl.dummy.dialect import DummyDialect + + return DummyDialect() + + +@pytest.fixture +def name(dialect): + from rhosocial.activerecord_test.feature.query.column_helpers import build_column + + return build_column(dialect, "name", str) + + +# --------------------------------------------------------------------------- +# A string operation whose result is a number +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "method, args, function", + [ + ("length", (), "LENGTH"), + ("ascii", (), "ASCII"), + ("octet_length", (), "OCTET_LENGTH"), + ("bit_length", (), "BIT_LENGTH"), + ("strpos", ("a",), "STRPOS"), + ("position", ("a",), "POSITION"), + ], + ids=["length", "ascii", "octet_length", "bit_length", "strpos", "position"], +) +def test_number_returning_operation_yields_an_integer(name, method, args, function): + """These read a string and produce a count or a code.""" + result = getattr(name, method)(*args) + assert isinstance(result, IntegerValueExpression) + assert function in result.to_sql()[0] + + +def test_the_whole_string_surface_offers_them(name): + """They are string operations, so they belong on the string surface. + + Their absence earlier was a gap in the surface, not a rule that only + string-to-string operations exist. + """ + for method in ("length", "ascii", "strpos", "position", "octet_length", "bit_length"): + assert hasattr(name, method), f"StringColumn is missing {method}" + + +# --------------------------------------------------------------------------- +# The result type gates the next operation +# --------------------------------------------------------------------------- + + +#: How many arguments each string operation *requires*, so the parametrized +#: test can call them all the same way. `substr` also takes an optional length +#: and `trim` optional characters and a direction; passing the minimum is +#: enough to reach the return, which is what is under test here. +_REQUIRED_ARGS = { + "upper": 0, "lower": 0, "trim": 0, "initcap": 0, + "substr": 1, "left": 1, "right": 1, "concat": 1, + "replace": 2, +} + + +def _call(name, method): + return getattr(name, method)(*(["x"] * _REQUIRED_ARGS[method])) + + +@pytest.mark.parametrize( + "method", ["upper", "lower", "substr", "trim", "concat", "replace", "left", "initcap"] +) +def test_string_result_keeps_the_string_surface(name, method): + """The result is a string and *says* so by offering the next operation. + + What is asserted is the surface, not one class: most of these return a + StringValueExpression, but a node with its own dialect hook -- TRIM, whose + standard spelling is a syntax error on SQLite -- is its own class and + carries the same mixins, which is what makes ``col.trim().upper()`` legal. + """ + result = _call(name, method) + assert hasattr(result, "upper"), f"{method} did not return a string value" + assert hasattr(result, "substr"), f"{method} did not return a string value" + + +@pytest.mark.parametrize( + "chained, expected_functions", + [ + (lambda c: c.upper().substr(1, 3), ["UPPER", "SUBSTRING"]), + (lambda c: c.trim().replace("a", "b"), ["TRIM", "REPLACE"]), + (lambda c: c.upper().lower().initcap(), ["UPPER", "LOWER", "INITCAP"]), + ], + ids=["upper-substr", "trim-replace", "case-chain"], +) +def test_string_chain_stays_string(name, chained, expected_functions): + sql, _ = chained(name).to_sql() + for function in expected_functions: + assert function in sql + + +def test_number_result_loses_the_string_surface(name): + """A length has no case, so ``upper()`` must not exist on it.""" + result = name.length() + for method in ("upper", "lower", "substr", "trim", "initcap", "reverse"): + assert not hasattr(result, method), ( + f"an integer result wrongly offers {method}" + ) + + +def test_number_result_keeps_integer_operations(name): + """Arithmetic is legal on an integer, and stays an integer.""" + result = name.length() + assert hasattr(result, "__add__") + assert hasattr(result, "__sub__") + assert hasattr(result, "__mul__") + + +# --------------------------------------------------------------------------- +# The chain crosses families correctly +# --------------------------------------------------------------------------- + + +def test_string_then_number(name): + """upper() is a string, length() of it is a number.""" + result = name.upper().length() + assert isinstance(result, IntegerValueExpression) + assert "LENGTH" in result.to_sql()[0] and "UPPER" in result.to_sql()[0] + + +def test_number_comparison_chains(name): + sql, _ = (name.length() > 5).to_sql() + assert "LENGTH" in sql and ">" in sql + + +def test_arithmetic_on_a_number_result(name): + """``length + 1`` is an arithmetic expression over an integer value.""" + sql, params = (name.length() + 1).to_sql() + assert "LENGTH" in sql + assert params == (1,) + + +def test_a_number_result_can_be_compared_but_not_matched(name): + """Comparison is universal; ``LIKE`` is not. + + Every value can be compared, so ``length() > 5`` is offered. ``LIKE`` is + text matching and a whole number is not text, so the operation is not + offered — it fails here, at the point of the call, rather than at the + database. This used to be the other way round and the reason the typed + column classes exist at all. + """ + result = name.length() + assert " > " in (result > 0).to_sql()[0] + with pytest.raises(AttributeError): + result.like("1%") + + +# --------------------------------------------------------------------------- +# Crossing into a predicate ends the value chain +# --------------------------------------------------------------------------- + + +def test_predicate_ends_the_chain(name): + """A predicate is the end of the value chain whatever produced it.""" + predicate = name.upper().like("A%") + for method in ("upper", "length", "substr"): + assert not hasattr(predicate, method), ( + f"predicate wrongly offers {method}; the value chain should have ended" + ) + + +def test_integer_value_can_be_aliased(name): + sql, _ = name.length().as_("n").to_sql() + assert " AS " in sql diff --git a/tests/rhosocial/activerecord_test/feature/relation/fixtures/models.py b/tests/rhosocial/activerecord_test/feature/relation/fixtures/models.py index 3e1f957f3..722cbcf68 100644 --- a/tests/rhosocial/activerecord_test/feature/relation/fixtures/models.py +++ b/tests/rhosocial/activerecord_test/feature/relation/fixtures/models.py @@ -13,7 +13,7 @@ from rhosocial.activerecord.model import ActiveRecord, AsyncActiveRecord from rhosocial.activerecord.base import DerivedField, FieldProxy -from rhosocial.activerecord.backend.expression import Column, Literal +from rhosocial.activerecord.backend.expression import BinaryArithmeticExpression, Column, Literal from rhosocial.activerecord.backend.expression.functions import ( json_extract_text, length, coalesce ) @@ -159,7 +159,7 @@ class Post(ActiveRecord): # DerivedField: hotness score hotness: ClassVar[Annotated[int, DerivedField( - lambda d: Column(d, "view_count") + Literal(d, 1), + lambda d: BinaryArithmeticExpression(d, "+", Column(d, "view_count"), Literal(d, 1)), )]] # DerivedField (JSON): first tag from metadata @@ -254,7 +254,7 @@ class AsyncPost(AsyncActiveRecord): )]] hotness: ClassVar[Annotated[int, DerivedField( - lambda d: Column(d, "view_count") + Literal(d, 1), + lambda d: BinaryArithmeticExpression(d, "+", Column(d, "view_count"), Literal(d, 1)), )]] first_tag: ClassVar[Annotated[str, DerivedField(