Skip to content

Commit 770c0d8

Browse files
committed
StoredColumn subclass of GeneratedColumn
StoredColumn(expression) replaces GeneratedColumn(expression, stored=True) as the way to ask for a STORED generated column, and is what table.generated_columns now returns for them. The two compare equal. add_column() loses its stored= argument in favour of generated=StoredColumn(expression). Refs #411 Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016Bvfq9dTNP6TwQRHBoE14Y
1 parent e066f0d commit 770c0d8

4 files changed

Lines changed: 99 additions & 66 deletions

File tree

‎docs/python-api.rst‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1888,7 +1888,7 @@ Generated columns
18881888

18891889
If you rename a column that is used by a generated column the expression will be rewritten to use the new name. Dropping a column that a generated column depends on raises a ``TransformError`` unless the generated column is dropped at the same time. Generated columns can be renamed, re-ordered and dropped like any other column, but cannot be used as a primary key.
18901890

1891-
The ``table.generated_columns`` property returns a dictionary describing the generated columns for a table:
1891+
The ``table.generated_columns`` property returns a dictionary describing the generated columns for a table. Values are ``GeneratedColumn`` objects for ``VIRTUAL`` columns and ``StoredColumn`` - a subclass of ``GeneratedColumn`` - for ``STORED`` ones. Both have ``.expression`` and ``.stored`` attributes:
18921892

18931893
.. code-block:: python
18941894
@@ -1901,7 +1901,7 @@ The ``table.generated_columns`` property returns a dictionary describing the gen
19011901
)
19021902
""")
19031903
print(db["items"].generated_columns)
1904-
# {'total': GeneratedColumn(expression='price * qty', stored=True)}
1904+
# {'total': StoredColumn(expression='price * qty')}
19051905
19061906
Generated columns are also included in ``table.columns`` and ``table.columns_dict``.
19071907

@@ -1914,16 +1914,16 @@ Pass ``generated=`` to ``table.create()`` or ``db.create_table()`` to create gen
19141914

19151915
.. code-block:: python
19161916
1917-
from sqlite_utils.db import GeneratedColumn
1917+
from sqlite_utils.db import StoredColumn
19181918
19191919
db["items"].create(
19201920
{"id": int, "price": float, "qty": int, "total": float, "label": str},
19211921
pk="id",
19221922
generated={
19231923
# A string creates a VIRTUAL column, calculated when it is read
19241924
"total": "price * qty",
1925-
# Use GeneratedColumn() for a STORED column
1926-
"label": GeneratedColumn("'#' || id", stored=True),
1925+
# Use StoredColumn() for a STORED column
1926+
"label": StoredColumn("'#' || id"),
19271927
},
19281928
)
19291929
@@ -1932,9 +1932,9 @@ To add a generated column to an existing table use ``table.add_column()``:
19321932
.. code-block:: python
19331933
19341934
db["items"].add_column("total", float, generated="price * qty")
1935-
db["items"].add_column("tax", float, generated="price * 0.2", stored=True)
1935+
db["items"].add_column("tax", float, generated=StoredColumn("price * 0.2"))
19361936
1937-
SQLite's ``ALTER TABLE`` can only add ``VIRTUAL`` generated columns, so ``stored=True`` rebuilds the table using ``.transform()``.
1937+
SQLite's ``ALTER TABLE`` can only add ``VIRTUAL`` generated columns, so adding a ``StoredColumn`` rebuilds the table using ``.transform()``.
19381938

19391939
The expression is included in the SQL as-is, so it should never be constructed from untrusted input.
19401940

‎sqlite_utils/create_table_parser.py‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,13 +50,42 @@ class Unique:
5050
end: int = field(default=-1, compare=False, repr=False)
5151

5252

53-
@dataclass(frozen=True)
53+
@dataclass(frozen=True, eq=False)
5454
class GeneratedColumn:
55-
"A ``GENERATED ALWAYS AS (expression)`` column definition."
55+
"""
56+
A ``GENERATED ALWAYS AS (expression)`` column definition. These are
57+
``VIRTUAL`` - calculated when read - unless ``stored`` is true, see
58+
:class:`StoredColumn`.
59+
"""
5660

5761
expression: str
5862
stored: bool = False
5963

64+
# StoredColumn("x") and GeneratedColumn("x", stored=True) are the same
65+
# thing, so equality ignores which of the two classes was used
66+
def __eq__(self, other: object) -> bool:
67+
if not isinstance(other, GeneratedColumn):
68+
return NotImplemented
69+
return (self.expression, self.stored) == (other.expression, other.stored)
70+
71+
def __hash__(self) -> int:
72+
return hash((self.expression, self.stored))
73+
74+
75+
class StoredColumn(GeneratedColumn):
76+
"A ``GENERATED ALWAYS AS (expression) STORED`` column definition."
77+
78+
def __init__(self, expression: str):
79+
super().__init__(expression, stored=True)
80+
81+
def __repr__(self) -> str:
82+
return f"StoredColumn(expression={self.expression!r})"
83+
84+
85+
def make_generated_column(expression: str, stored: bool = False) -> GeneratedColumn:
86+
"Returns a StoredColumn if stored, otherwise a GeneratedColumn"
87+
return StoredColumn(expression) if stored else GeneratedColumn(expression)
88+
6089

6190
class ParseError(ValueError):
6291
pass
@@ -834,7 +863,7 @@ def parse_generated_columns(create_sql: str) -> dict[str, GeneratedColumn]:
834863
stored = close + 1 < len(item_tokens) and item_tokens[
835864
close + 1
836865
].is_keyword("STORED")
837-
generated[column] = GeneratedColumn(expression, stored=stored)
866+
generated[column] = make_generated_column(expression, stored)
838867
break
839868
index += 1
840869
return generated

‎sqlite_utils/db.py‎

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,11 @@
3131
ColumnComments,
3232
GeneratedColumn,
3333
ParseError,
34+
StoredColumn,
3435
Unique,
3536
UniqueColumn,
3637
check_references_identifier,
38+
make_generated_column,
3739
parse_autoincrement,
3840
parse_checks,
3941
parse_column_comments,
@@ -105,16 +107,15 @@ def quote_identifier(identifier: str) -> str:
105107
GeneratedType = Mapping[str, "str | GeneratedColumn"]
106108

107109

108-
def _resolve_generated(
109-
generated: "str | GeneratedColumn", stored: bool = False
110-
) -> GeneratedColumn:
110+
def _resolve_generated(generated: "str | GeneratedColumn") -> GeneratedColumn:
111111
"Accepts an expression string or a GeneratedColumn, returns a GeneratedColumn"
112+
stored = False
112113
if isinstance(generated, GeneratedColumn):
113-
expression, stored = generated.expression, generated.stored or stored
114+
expression, stored = generated.expression, generated.stored
114115
else:
115116
expression = generated
116117
try:
117-
return GeneratedColumn(validate_generated_expression(expression), stored)
118+
return make_generated_column(validate_generated_expression(expression), stored)
118119
except ParseError as ex:
119120
raise AlterError(str(ex)) from ex
120121

@@ -1482,7 +1483,7 @@ def create_table_sql(
14821483
:param if_not_exists: Use ``CREATE TABLE IF NOT EXISTS``
14831484
:param strict: Apply STRICT mode to table
14841485
:param generated: Dictionary of generated columns, mapping column names to
1485-
a SQL expression string or a ``GeneratedColumn(expression, stored=True)``
1486+
a SQL expression string or a ``StoredColumn(expression)``
14861487
"""
14871488
if hash_id_columns and (hash_id is None):
14881489
hash_id = "id"
@@ -1793,7 +1794,7 @@ def create_table(
17931794
:param transform: If table already exists transform it to fit the specified schema
17941795
:param strict: Apply STRICT mode to table
17951796
:param generated: Dictionary of generated columns, mapping column names to
1796-
a SQL expression string or a ``GeneratedColumn(expression, stored=True)``
1797+
a SQL expression string or a ``StoredColumn(expression)``
17971798
"""
17981799
# Transform table to match the new definition if table already exists:
17991800
if self[name].exists():
@@ -2491,7 +2492,7 @@ def generated_columns(self) -> dict[str, GeneratedColumn]:
24912492
f"Could not find expression for generated column {name!r}"
24922493
)
24932494
# table_xinfo is authoritative for stored vs. virtual
2494-
generated_columns[name] = GeneratedColumn(
2495+
generated_columns[name] = make_generated_column(
24952496
generated.expression, stored=hidden_value == 3
24962497
)
24972498
return generated_columns
@@ -2698,7 +2699,7 @@ def create(
26982699
:param transform: If table already exists transform it to fit the specified schema
26992700
:param strict: Apply STRICT mode to table
27002701
:param generated: Dictionary of generated columns, mapping column names to
2701-
a SQL expression string or a ``GeneratedColumn(expression, stored=True)``
2702+
a SQL expression string or a ``StoredColumn(expression)``
27022703
"""
27032704
# Resolve defaults from _defaults (issue #655)
27042705
pk = self.value_or_default("pk", pk)
@@ -3014,9 +3015,11 @@ def transform_sql(
30143015
f"Cannot drop column {dropped_column!r}: it is used by "
30153016
f"generated column {column!r}"
30163017
)
3017-
create_table_generated[rename.get(column) or column] = GeneratedColumn(
3018-
rewrite_check_expression(generated.expression, rename),
3019-
stored=generated.stored,
3018+
create_table_generated[rename.get(column) or column] = (
3019+
make_generated_column(
3020+
rewrite_check_expression(generated.expression, rename),
3021+
stored=generated.stored,
3022+
)
30203023
)
30213024

30223025
create_table_uniques: list[Unique] = []
@@ -3149,7 +3152,7 @@ def fk_with_renamed_columns(fk: ForeignKey) -> ForeignKey:
31493152
del copy_from_to[name]
31503153
else:
31513154
copy_from_to[name] = new_name
3152-
# New generated columns, used by add_column(generated=, stored=True)
3155+
# New generated columns, used by add_column(generated=StoredColumn(...))
31533156
# since ALTER TABLE ADD COLUMN cannot add a STORED generated column
31543157
for name, (type_, generated_column) in (_add_generated or {}).items():
31553158
if name in dict(new_column_pairs):
@@ -3642,7 +3645,6 @@ def add_column(
36423645
fk_col: str | None = None,
36433646
not_null_default: Any | None = None,
36443647
generated: "str | GeneratedColumn | None" = None,
3645-
stored: bool = False,
36463648
):
36473649
"""
36483650
Add a column to this table. See :ref:`python_api_add_column`.
@@ -3652,19 +3654,16 @@ def add_column(
36523654
:param fk: Name of a table that this column should be a foreign key reference to
36533655
:param fk_col: Column in the foreign key table that this should reference
36543656
:param not_null_default: Set this column to ``not null`` and give it this default value
3655-
:param generated: SQL expression to make this a generated column, or a
3656-
``GeneratedColumn(expression, stored=True)``
3657-
:param stored: Make the generated column ``STORED`` rather than ``VIRTUAL``.
3658-
SQLite cannot add a stored column to an existing table, so this
3659-
rebuilds the table using ``.transform()``
3657+
:param generated: Make this a generated column. A SQL expression string
3658+
adds a ``VIRTUAL`` column. Pass ``StoredColumn(expression)`` for a
3659+
``STORED`` column - SQLite cannot add one of those to an existing
3660+
table, so this rebuilds the table using ``.transform()``
36603661
"""
36613662
generated_column = None
36623663
if generated is not None:
36633664
if not_null_default is not None:
36643665
raise AlterError("A generated column cannot have a default value")
3665-
generated_column = _resolve_generated(generated, stored)
3666-
elif stored:
3667-
raise AlterError("stored=True requires generated=")
3666+
generated_column = _resolve_generated(generated)
36683667
fk_col_type = None
36693668
if fk is not None:
36703669
# fk must be a valid table

‎tests/test_generated_columns.py‎

Lines changed: 39 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
from sqlite_utils import Database
44
from sqlite_utils.create_table_parser import (
55
GeneratedColumn,
6+
StoredColumn,
67
parse_generated_columns,
78
)
89
from sqlite_utils.db import AlterError, TransformError
@@ -46,8 +47,8 @@ def rows(db):
4647
SCHEMA,
4748
{
4849
"total": GeneratedColumn("price * qty"),
49-
"total_s": GeneratedColumn("price * qty * 2", stored=True),
50-
"label": GeneratedColumn("name || '!'", stored=True),
50+
"total_s": StoredColumn("price * qty * 2"),
51+
"label": StoredColumn("name || '!'"),
5152
},
5253
),
5354
# No VIRTUAL/STORED keyword means virtual
@@ -58,7 +59,7 @@ def rows(db):
5859
"check (cast(a as integer) > 0), "
5960
"\"b c\" text generated always as (cast(a as text) || ')') stored, "
6061
"check (a as_of))",
61-
{"b c": GeneratedColumn("cast(a as text) || ')'", stored=True)},
62+
{"b c": StoredColumn("cast(a as text) || ')'")},
6263
),
6364
(
6465
"create table t (a, -- as (nope)\n b /* as (x) */ as (a) virtual)",
@@ -85,8 +86,8 @@ def test_introspection(db):
8586
assert table.columns_dict["total"] is float
8687
assert table.generated_columns == {
8788
"total": GeneratedColumn("price * qty", stored=False),
88-
"total_s": GeneratedColumn("price * qty * 2", stored=True),
89-
"label": GeneratedColumn("name || '!'", stored=True),
89+
"total_s": StoredColumn("price * qty * 2"),
90+
"label": StoredColumn("name || '!'"),
9091
}
9192
assert db["nope"].generated_columns == {}
9293

@@ -97,8 +98,8 @@ def test_transform_preserves_generated_columns(db):
9798
assert rows(db) == before
9899
assert db["items"].generated_columns == {
99100
"total": GeneratedColumn("price * qty", stored=False),
100-
"total_s": GeneratedColumn("price * qty * 2", stored=True),
101-
"label": GeneratedColumn("name || '!'", stored=True),
101+
"total_s": StoredColumn("price * qty * 2"),
102+
"label": StoredColumn("name || '!'"),
102103
}
103104
assert [c.name for c in db["items"].columns if c.notnull] == ["label"]
104105
# The index on the generated column survives
@@ -142,8 +143,8 @@ def test_transform_rename_rewrites_expressions(db):
142143
db["items"].transform(rename={"price": "unit price", "total": "grand"})
143144
assert db["items"].generated_columns == {
144145
"grand": GeneratedColumn('"unit price" * qty', stored=False),
145-
"total_s": GeneratedColumn('"unit price" * qty * 2', stored=True),
146-
"label": GeneratedColumn("name || '!'", stored=True),
146+
"total_s": StoredColumn('"unit price" * qty * 2'),
147+
"label": StoredColumn("name || '!'"),
147148
}
148149
assert rows(db)[0]["grand"] == 10.0
149150
assert db["items"].indexes[0].columns == ["grand"]
@@ -234,7 +235,7 @@ def test_create_table_with_generated_columns():
234235
pk="id",
235236
generated={
236237
"total": "price * qty",
237-
"label": GeneratedColumn("'#' || id", stored=True),
238+
"label": StoredColumn("'#' || id"),
238239
},
239240
not_null={"label"},
240241
)
@@ -249,7 +250,7 @@ def test_create_table_with_generated_columns():
249250
)
250251
assert table.generated_columns == {
251252
"total": GeneratedColumn("price * qty"),
252-
"label": GeneratedColumn("'#' || id", stored=True),
253+
"label": StoredColumn("'#' || id"),
253254
}
254255
table.insert({"price": 2.5, "qty": 4})
255256
assert list(table.rows) == [
@@ -282,15 +283,13 @@ def test_create_table_generated_errors(kwargs, error):
282283
assert not db["t"].exists()
283284

284285

285-
@pytest.mark.parametrize("stored", (False, True))
286-
def test_add_generated_column(db, stored):
286+
@pytest.mark.parametrize("cls", (GeneratedColumn, StoredColumn, str))
287+
def test_add_generated_column(db, cls):
287288
before = rows(db)
288-
table = db["items"].add_column(
289-
"double_qty", int, generated="qty * 2", stored=stored
290-
)
291-
assert table.generated_columns["double_qty"] == GeneratedColumn(
292-
"qty * 2", stored=stored
293-
)
289+
table = db["items"].add_column("double_qty", int, generated=cls("qty * 2"))
290+
expected = cls("qty * 2") if cls is not str else GeneratedColumn("qty * 2")
291+
assert table.generated_columns["double_qty"] == expected
292+
assert table.generated_columns["double_qty"].stored is (cls is StoredColumn)
294293
assert table.columns_dict["double_qty"] is int
295294
assert rows(db) == [dict(row, double_qty=row["qty"] * 2) for row in before]
296295
# Existing generated columns and indexes survive the stored rebuild
@@ -303,29 +302,35 @@ def test_add_generated_column(db, stored):
303302
assert [i.name for i in table.indexes] == ["idx_total"]
304303

305304

306-
def test_add_generated_column_using_generated_column_object(db):
307-
db["items"].add_column("x", float, generated=GeneratedColumn("price", True))
308-
assert db["items"].generated_columns["x"] == GeneratedColumn("price", True)
309-
310-
311-
@pytest.mark.parametrize("stored", (False, True))
312-
def test_add_generated_column_errors(db, stored):
305+
@pytest.mark.parametrize("cls", (GeneratedColumn, StoredColumn))
306+
def test_add_generated_column_errors(db, cls):
313307
with pytest.raises(AlterError):
314-
db["items"].add_column(
315-
"x", int, generated="1", stored=stored, not_null_default=1
316-
)
308+
db["items"].add_column("x", int, generated=cls("1"), not_null_default=1)
317309
with pytest.raises(AlterError):
318-
db["items"].add_column("x", int, generated="1) --", stored=stored)
310+
db["items"].add_column("x", int, generated=cls("1) --"))
319311
with pytest.raises((AlterError, sqlite3.OperationalError)):
320-
db["items"].add_column("total", int, generated="1", stored=stored)
312+
db["items"].add_column("total", int, generated=cls("1"))
321313
with pytest.raises(sqlite3.OperationalError):
322-
db["items"].add_column("x", int, generated="no_such_col", stored=stored)
323-
with pytest.raises(AlterError):
324-
db["items"].add_column("x", int, stored=True)
314+
db["items"].add_column("x", int, generated=cls("no_such_col"))
325315
assert "x" not in db["items"].columns_dict
326316
assert rows(db)[0]["total"] == 10.0
327317

328318

319+
def test_stored_column_class():
320+
stored = StoredColumn("a + 1")
321+
assert isinstance(stored, GeneratedColumn)
322+
assert stored.stored is True
323+
assert repr(stored) == "StoredColumn(expression='a + 1')"
324+
# Equivalent however it was constructed
325+
assert stored == GeneratedColumn("a + 1", stored=True)
326+
assert hash(stored) == hash(GeneratedColumn("a + 1", stored=True))
327+
assert stored != GeneratedColumn("a + 1")
328+
db = Database(memory=True)
329+
db["t"].create({"a": int, "b": int, "c": int}, generated={"b": stored, "c": "a"})
330+
assert type(db["t"].generated_columns["b"]) is StoredColumn
331+
assert type(db["t"].generated_columns["c"]) is GeneratedColumn
332+
333+
329334
def test_create_table_transform_adds_generated_column(db):
330335
db["items"].create(
331336
{"id": int, "price": float, "qty": int, "name": str, "half": float},

0 commit comments

Comments
 (0)