velocity-python 0.10.2__py3-none-any.whl → 0.11.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. velocity/__init__.py +1 -1
  2. velocity/db/core/column.py +33 -3
  3. velocity/db/core/database.py +83 -25
  4. velocity/db/core/decorators.py +36 -18
  5. velocity/db/core/engine.py +421 -105
  6. velocity/db/core/lazy_engine.py +13 -4
  7. velocity/db/core/result.py +54 -1
  8. velocity/db/core/row.py +133 -24
  9. velocity/db/core/sequence.py +72 -44
  10. velocity/db/core/table.py +416 -109
  11. velocity/db/core/transaction.py +439 -18
  12. velocity/db/core/view.py +19 -1
  13. velocity/db/maintenance.py +125 -15
  14. velocity/db/servers/mysql/operators.py +2 -3
  15. velocity/db/servers/mysql/sql.py +1334 -251
  16. velocity/db/servers/postgres/__init__.py +60 -0
  17. velocity/db/servers/postgres/reserved.py +122 -1
  18. velocity/db/servers/postgres/sql.py +200 -76
  19. velocity/db/servers/sqlite/__init__.py +114 -1
  20. velocity/db/servers/sqlite/operators.py +2 -2
  21. velocity/db/servers/sqlite/sql.py +886 -201
  22. velocity/db/servers/sqlserver/sql.py +11 -0
  23. velocity/db/servers/tablehelper.py +109 -7
  24. velocity/db/utils.py +33 -8
  25. velocity/testing/fake_db.py +25 -25
  26. {velocity_python-0.10.2.dist-info → velocity_python-0.11.0.dist-info}/METADATA +1 -1
  27. {velocity_python-0.10.2.dist-info → velocity_python-0.11.0.dist-info}/RECORD +31 -31
  28. {velocity_python-0.10.2.dist-info → velocity_python-0.11.0.dist-info}/WHEEL +0 -0
  29. {velocity_python-0.10.2.dist-info → velocity_python-0.11.0.dist-info}/entry_points.txt +0 -0
  30. {velocity_python-0.10.2.dist-info → velocity_python-0.11.0.dist-info}/licenses/LICENSE +0 -0
  31. {velocity_python-0.10.2.dist-info → velocity_python-0.11.0.dist-info}/top_level.txt +0 -0
velocity/__init__.py CHANGED
@@ -1,4 +1,4 @@
1
- __version__ = version = "0.10.2"
1
+ __version__ = version = "0.11.0"
2
2
 
3
3
  import importlib as _importlib
4
4
 
@@ -1,6 +1,10 @@
1
+ import re
2
+
1
3
  from velocity.db import exceptions
2
4
  from velocity.db.core.decorators import return_default
3
5
 
6
+ _PLAIN_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
7
+
4
8
 
5
9
  class Column:
6
10
  """
@@ -23,7 +27,21 @@ class Column:
23
27
  call in a savepoint (``create``/``rollback``/``release``) on ``self.cursor()``.
24
28
  Delegates to the owning table so the savepoint shares the table's cursor —
25
29
  the same one ``self.tx.execute`` runs the statement on.
30
+
31
+ Public: a raw cursor marks the connection session-dirty (closed at
32
+ the end, never pooled), like ``tx.cursor()``.
26
33
  """
34
+ cursor = self._internal_cursor()
35
+ mark = getattr(self.tx, "mark_session_dirty", None)
36
+ if callable(mark):
37
+ mark()
38
+ return cursor
39
+
40
+ def _internal_cursor(self):
41
+ """The owning table's cursor, without marking the connection."""
42
+ internal = getattr(type(self.table), "_internal_cursor", None)
43
+ if callable(internal):
44
+ return self.table._internal_cursor()
27
45
  return self.table.cursor()
28
46
 
29
47
  def __str__(self):
@@ -121,16 +139,28 @@ class Column:
121
139
  self.tx.execute(sql, vals)
122
140
  self.name = name
123
141
 
142
+ def _plain_name(self):
143
+ """The column as a validated, lower-case identifier (it went into
144
+ the SELECT list and ORDER BY as written)."""
145
+ if not isinstance(self.name, str) or not _PLAIN_IDENT.match(self.name):
146
+ raise ValueError(f"Invalid column name: {self.name!r}")
147
+ return self.name.lower()
148
+
124
149
  @return_default(default_factory=list, read=True)
125
150
  def distinct(self, order="asc", qty=None):
126
151
  """
127
152
  Returns the distinct values in this column, optionally ordered and/or limited in quantity.
153
+ ``order`` is ``"asc"`` or ``"desc"``.
128
154
  """
155
+ name = self._plain_name()
156
+ direction = str(order).strip().upper()
157
+ if direction not in ("ASC", "DESC"):
158
+ raise ValueError(f"order must be 'asc' or 'desc', got {order!r}")
129
159
  sql, vals = self.sql.select(
130
160
  self.tx,
131
- columns=f"distinct {self.name}",
161
+ columns=f"distinct {name}",
132
162
  table=self.table.name,
133
- orderby=f"{self.name} {order}",
163
+ orderby=f"{name} {direction}",
134
164
  qty=qty,
135
165
  )
136
166
  return self.tx.execute(sql, vals).as_simple_list().all()
@@ -140,7 +170,7 @@ class Column:
140
170
  Returns the MAX() of this column, or 0 if table/column is missing.
141
171
  """
142
172
  try:
143
- qcol = self.sql.quote_identifier(self.name)
173
+ qcol = self.sql.quote_identifier(self._plain_name())
144
174
  sql, vals = self.sql.select(
145
175
  self.tx, columns=f"max({qcol})", table=self.table.name, where=where
146
176
  )
@@ -1,6 +1,16 @@
1
+ from velocity.db import exceptions
1
2
  from velocity.db.core.source_policy import refuse_read_only_source
2
3
 
3
4
 
5
+ def _tx_cursor(tx):
6
+ """The transaction's internal cursor (``Transaction._cursor``: not
7
+ marked session-dirty like the public ``tx.cursor()``); a test double
8
+ without it gets ``tx.cursor()``."""
9
+ if callable(getattr(type(tx), "_cursor", None)):
10
+ return tx._cursor()
11
+ return tx.cursor()
12
+
13
+
4
14
  class Database:
5
15
  """
6
16
  Represents a database within a transaction context.
@@ -9,9 +19,21 @@ class Database:
9
19
  def __init__(self, tx, name=None):
10
20
  refuse_read_only_source(tx, "Database")
11
21
  self.tx = tx
12
- self.name = name or self.tx.engine.config["database"]
22
+ self.name = name or self._configured_name(tx)
13
23
  self.sql = tx.engine.sql
14
24
 
25
+ @staticmethod
26
+ def _configured_name(tx):
27
+ """The engine's database: ``dbname`` (psycopg 3 / PostgreSQL) or
28
+ ``database`` (legacy, other dialects) in the config, else asked of
29
+ the server."""
30
+ config = tx.engine.config
31
+ if isinstance(config, dict):
32
+ name = config.get("dbname") or config.get("database")
33
+ if name:
34
+ return name
35
+ return tx.current_database()
36
+
15
37
  def __str__(self):
16
38
  return (
17
39
  f"Engine: {self.tx.engine.sql.server}\n"
@@ -37,35 +59,47 @@ class Database:
37
59
  pass
38
60
 
39
61
  def cursor(self):
62
+ """A raw driver cursor. Statements run on it bypass velocity's
63
+ bookkeeping, so the connection is marked session-dirty (closed at
64
+ the end, never pooled), like ``tx.cursor()``."""
65
+ cursor = self._internal_cursor()
66
+ mark = getattr(self.tx, "mark_session_dirty", None)
67
+ if callable(mark):
68
+ mark()
69
+ return cursor
70
+
71
+ def _internal_cursor(self):
40
72
  """
41
73
  Lazy-initialize the cursor on first use.
42
74
  """
43
75
  try:
44
76
  return self._cursor
45
77
  except AttributeError:
46
- self._cursor = self.tx.cursor()
78
+ self._cursor = _tx_cursor(self.tx)
47
79
  return self._cursor
48
80
 
49
81
  def drop(self):
50
82
  """
51
- Drops this database.
83
+ Drops this database. Refused when the engine's schema is locked.
52
84
  """
85
+ self._refuse_when_locked("DROP")
53
86
  sql, vals = self.tx.engine.sql.drop_database(self.name)
54
- self.tx.execute(sql, vals, single=True, cursor=self.cursor())
87
+ self.tx.execute(sql, vals, single=True, cursor=self._internal_cursor())
55
88
 
56
89
  def create(self):
57
90
  """
58
- Creates this database.
91
+ Creates this database. Refused when the engine's schema is locked.
59
92
  """
93
+ self._refuse_when_locked("CREATE")
60
94
  sql, vals = self.tx.engine.sql.create_database(self.name)
61
- self.tx.execute(sql, vals, single=True, cursor=self.cursor())
95
+ self.tx.execute(sql, vals, single=True, cursor=self._internal_cursor())
62
96
 
63
97
  def exists(self):
64
98
  """
65
99
  Returns True if the database exists, else False.
66
100
  """
67
101
  sql, vals = self.sql.databases()
68
- result = self.tx.execute(sql, vals, cursor=self.cursor())
102
+ result = self.tx.execute(sql, vals, cursor=self._internal_cursor())
69
103
  return bool(self.name in [x[0] for x in result.as_tuple()])
70
104
 
71
105
  @property
@@ -74,20 +108,33 @@ class Database:
74
108
  Returns a list of 'schema.table' strings representing tables in this database.
75
109
  """
76
110
  sql, vals = self.sql.tables()
77
- result = self.tx.execute(sql, vals, cursor=self.cursor())
111
+ result = self.tx.execute(sql, vals, cursor=self._internal_cursor())
78
112
  return [f"{x[0]}.{x[1]}" for x in result.as_tuple()]
79
113
 
80
114
  def reindex(self):
81
115
  """
82
- Re-indexes this database.
116
+ Re-indexes this database. Refused when the engine's schema is locked.
83
117
  """
84
- sql = f"REINDEX DATABASE {self.name}"
118
+ self._refuse_when_locked("REINDEX")
119
+ sql = f"REINDEX DATABASE {self.sql.quote_identifier(self.name)}"
85
120
  vals = ()
86
- self.tx.execute(sql, vals, cursor=self.cursor())
121
+ self.tx.execute(sql, vals, cursor=self._internal_cursor())
122
+
123
+ def _refuse_when_locked(self, operation):
124
+ """Maintenance (CREATE / DROP / VACUUM / REINDEX) never runs on an
125
+ engine whose schema is locked (production)."""
126
+ if self.tx.engine.schema_locked:
127
+ raise exceptions.DbSchemaLockedError(
128
+ f"Cannot {operation} database: the schema is locked."
129
+ )
87
130
 
88
131
  def switch(self):
89
132
  """
90
133
  Switches the parent transaction to this database.
134
+
135
+ Privileged operator API: it reaches any database the login can see
136
+ (``direct_connection``'s database check is not a boundary against
137
+ it). Never pass it a name that came from a request.
91
138
  """
92
139
  self.tx.switch_to_database(self.name)
93
140
  return self
@@ -96,10 +143,14 @@ class Database:
96
143
  """
97
144
  Performs VACUUM on this database, optionally FULL, optionally ANALYZE,
98
145
  optionally REINDEX.
146
+
147
+ Runs on its own direct connection to this database (``self.name``),
148
+ outside any transaction (PostgreSQL refuses VACUUM inside one), and
149
+ closes it: it never takes a pool slot.
99
150
  """
100
- # Manually open a separate connection to run VACUUM outside a transaction.
101
- conn = self.tx.engine.connect()
102
- old_autocommit = conn.autocommit
151
+ self._refuse_when_locked("VACUUM")
152
+ engine = self.tx.engine
153
+ conn = engine.direct_connection(database=self.name)
103
154
  try:
104
155
  # Postgres requires VACUUM to run outside a normal transaction block.
105
156
  conn.autocommit = True
@@ -111,15 +162,22 @@ class Database:
111
162
  if analyze:
112
163
  parts.append("ANALYZE")
113
164
 
114
- # Execute VACUUM
115
- with conn.cursor() as cur:
116
- cur.execute(" ".join(parts))
117
-
118
- # Optionally REINDEX the database
119
- if reindex:
120
- cur.execute(f"REINDEX DATABASE {self.name}")
121
-
165
+ sql = " ".join(parts)
166
+ try:
167
+ with conn.cursor() as cur:
168
+ cur.execute(sql)
169
+
170
+ # Optionally REINDEX the database (PostgreSQL reindexes
171
+ # only the database it is connected to: this one).
172
+ if reindex:
173
+ cur.execute("SELECT current_database()")
174
+ current = cur.fetchone()[0]
175
+ sql = f"REINDEX DATABASE {self.sql.quote_identifier(current)}"
176
+ cur.execute(sql)
177
+ except Exception as e:
178
+ raise engine.process_error(e, sql)
122
179
  finally:
123
- # Restore autocommit state and close the connection
124
- conn.autocommit = old_autocommit
125
- conn.close()
180
+ try:
181
+ conn.close()
182
+ except Exception:
183
+ pass
@@ -81,7 +81,7 @@ def _primary_key_constraint(table):
81
81
  return None
82
82
  try:
83
83
  sql, vals = builder(table.name)
84
- row = table.tx.execute(sql, vals, cursor=table.cursor()).as_tuple().one()
84
+ row = table.tx.execute(sql, vals, cursor=_cursor_of(table)).as_tuple().one()
85
85
  except Exception:
86
86
  return None
87
87
  if not row:
@@ -118,10 +118,10 @@ def _rollback_savepoint_safely(table, sp, error):
118
118
  if isinstance(error, exceptions.DbConnectionError) or _connection_dead(table.tx):
119
119
  return False
120
120
  try:
121
- table.tx.rollback_savepoint(sp, cursor=table.cursor())
121
+ table.tx.rollback_savepoint(sp, cursor=_cursor_of(table))
122
122
  # ROLLBACK TO keeps the savepoint open; release it so a long
123
123
  # transaction with many swallowed errors does not pile them up.
124
- table.tx.release_savepoint(sp, cursor=table.cursor(), defer=True)
124
+ table.tx.release_savepoint(sp, cursor=_cursor_of(table), defer=True)
125
125
  return True
126
126
  except Exception as cleanup_error:
127
127
  logger.warning(
@@ -150,10 +150,10 @@ def reset_id_on_dup_key(func):
150
150
  @wraps(func)
151
151
  def reset_decorator(self, *args, retries=0, **kwds):
152
152
  max_retries = 10
153
- sp = self.tx.create_savepoint(cursor=self.cursor(), defer=True)
153
+ sp = self.tx.create_savepoint(cursor=_cursor_of(self), defer=True)
154
154
  try:
155
155
  result = func(self, *args, **kwds)
156
- self.tx.release_savepoint(sp, cursor=self.cursor(), defer=True)
156
+ self.tx.release_savepoint(sp, cursor=_cursor_of(self), defer=True)
157
157
  return result
158
158
  except exceptions.DbDuplicateKeyError as error:
159
159
  if not _rollback_savepoint_safely(self, sp, error):
@@ -172,7 +172,9 @@ def reset_id_on_dup_key(func):
172
172
  # collisions. Run the aggregate directly so any error surfaces
173
173
  # instead of corrupting the sequence.
174
174
  sql, vals = self.max("sys_id", sql_only=True)
175
- current_max = self.tx.execute(sql, vals, cursor=self.cursor()).scalar()
175
+ current_max = self.tx.execute(
176
+ sql, vals, cursor=_cursor_of(self)
177
+ ).scalar()
176
178
  self.set_sequence((current_max or 0) + 1)
177
179
  return reset_decorator(self, *args, retries=retries + 1, **kwds)
178
180
  raise _max_retries_error(error) from error
@@ -207,6 +209,16 @@ def _is_uncastable_input(error):
207
209
  )
208
210
 
209
211
 
212
+ def _cursor_of(obj):
213
+ """*obj*'s cursor for velocity's own statements: ``_internal_cursor()``
214
+ (the public ``cursor()`` marks the connection session-dirty), or
215
+ ``cursor()`` on an object without it (a test double)."""
216
+ internal = getattr(type(obj), "_internal_cursor", None)
217
+ if callable(internal):
218
+ return obj._internal_cursor()
219
+ return obj.cursor()
220
+
221
+
210
222
  def _first_line(value):
211
223
  text = str(value or "")
212
224
  return text.splitlines()[0] if text else ""
@@ -278,7 +290,7 @@ def return_default(
278
290
 
279
291
  @wraps(func)
280
292
  def wrapper(self, *args, **kwds):
281
- sp = self.tx.create_savepoint(cursor=self.cursor(), defer=True)
293
+ sp = self.tx.create_savepoint(cursor=_cursor_of(self), defer=True)
282
294
  try:
283
295
  result = func(self, *args, **kwds)
284
296
  if result is None:
@@ -298,9 +310,15 @@ def return_default(
298
310
  # its parameter values. Class, SQLSTATE and the driver's own
299
311
  # first message line only.
300
312
  sqlstate = getattr(e, "sqlstate", None)
313
+ # A velocity error whose text was redacted (process_error):
314
+ # its own first line, not the driver's unredacted one.
315
+ source = (
316
+ e
317
+ if getattr(e, "redacted", False) is True
318
+ else (getattr(e, "original", None) or e)
319
+ )
301
320
  message = redact_data_exception_values(
302
- getattr(e, "sqlstate", None),
303
- _first_line(getattr(e, "original", None) or e),
321
+ getattr(e, "sqlstate", None), _first_line(source)
304
322
  )
305
323
  logger.log(
306
324
  (
@@ -335,7 +353,7 @@ def return_default(
335
353
  except Exception:
336
354
  pass
337
355
  return _make_default()
338
- self.tx.release_savepoint(sp, cursor=self.cursor(), defer=True)
356
+ self.tx.release_savepoint(sp, cursor=_cursor_of(self), defer=True)
339
357
  return result
340
358
 
341
359
  return wrapper
@@ -468,10 +486,10 @@ def create_missing(func):
468
486
  def wrapper(self, *args, **kwds):
469
487
  conflict_columns = _infer_conflict_columns(func, args, kwds)
470
488
 
471
- sp = self.tx.create_savepoint(cursor=self.cursor(), defer=True)
489
+ sp = self.tx.create_savepoint(cursor=_cursor_of(self), defer=True)
472
490
  try:
473
491
  result = func(self, *args, **kwds)
474
- self.tx.release_savepoint(sp, cursor=self.cursor(), defer=True)
492
+ self.tx.release_savepoint(sp, cursor=_cursor_of(self), defer=True)
475
493
  return result
476
494
  except exceptions.DbColumnMissingError as e:
477
495
  if not _rollback_savepoint_safely(self, sp, e):
@@ -503,12 +521,12 @@ def create_missing(func):
503
521
  self.tx.advisory_lock(f"velocity_ddl_{self.name}")
504
522
  except Exception:
505
523
  pass # advisory lock is best-effort (e.g. non-PostgreSQL)
506
- sp2 = self.tx.create_savepoint(cursor=self.cursor())
524
+ sp2 = self.tx.create_savepoint(cursor=_cursor_of(self))
507
525
  try:
508
526
  self.alter(data, mode="add")
509
- self.tx.release_savepoint(sp2, cursor=self.cursor())
527
+ self.tx.release_savepoint(sp2, cursor=_cursor_of(self))
510
528
  except exceptions.DbObjectExistsError:
511
- self.tx.rollback_savepoint(sp2, cursor=self.cursor())
529
+ self.tx.rollback_savepoint(sp2, cursor=_cursor_of(self))
512
530
 
513
531
  return func(self, *args, **kwds)
514
532
  except exceptions.DbTableMissingError as e:
@@ -539,12 +557,12 @@ def create_missing(func):
539
557
  self.tx.advisory_lock(f"velocity_ddl_{self.name}")
540
558
  except Exception:
541
559
  pass # advisory lock is best-effort
542
- sp2 = self.tx.create_savepoint(cursor=self.cursor())
560
+ sp2 = self.tx.create_savepoint(cursor=_cursor_of(self))
543
561
  try:
544
562
  self.create(data)
545
- self.tx.release_savepoint(sp2, cursor=self.cursor())
563
+ self.tx.release_savepoint(sp2, cursor=_cursor_of(self))
546
564
  except exceptions.DbObjectExistsError:
547
- self.tx.rollback_savepoint(sp2, cursor=self.cursor())
565
+ self.tx.rollback_savepoint(sp2, cursor=_cursor_of(self))
548
566
 
549
567
  if conflict_columns:
550
568
  self.create_index(conflict_columns, unique=True)