half-orm 1.1.0__tar.gz → 1.2.0__tar.gz
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.
- {half_orm-1.1.0/half_orm.egg-info → half_orm-1.2.0}/PKG-INFO +6 -1
- {half_orm-1.1.0 → half_orm-1.2.0}/README.md +5 -0
- half_orm-1.2.0/half_orm/_predicate.py +56 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/fkey.py +8 -1
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/model.py +65 -1
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/relation.py +139 -2
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/relation_factory.py +1 -1
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/testing.py +16 -35
- half_orm-1.2.0/half_orm/transaction.py +473 -0
- half_orm-1.2.0/half_orm/version.txt +1 -0
- {half_orm-1.1.0 → half_orm-1.2.0/half_orm.egg-info}/PKG-INFO +6 -1
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/SOURCES.txt +1 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/pyproject.toml +1 -1
- half_orm-1.1.0/half_orm/transaction.py +0 -236
- half_orm-1.1.0/half_orm/version.txt +0 -1
- {half_orm-1.1.0 → half_orm-1.2.0}/AUTHORS +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/LICENSE +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/__init__.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/__main__.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/cli.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/cli_utils.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/field.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/field_errors.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/hotest.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/migrations/BREAKING_CHANGES-1.0.0.md +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/migrations/__init__.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/model_errors.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/null.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/pg_meta.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/py.typed +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/relation_errors.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/sql_adapter.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/sql_ast.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/utils.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/dependency_links.txt +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/entry_points.txt +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/requires.txt +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/top_level.txt +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/setup.cfg +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/test/test_cli.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/test/test_main.py +0 -0
- {half_orm-1.1.0 → half_orm-1.2.0}/test/test_sql_ast.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: half_orm
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.2.0
|
|
4
4
|
Summary: A database-first ORM for PostgreSQL
|
|
5
5
|
Author-email: Joël Maïzi <joel.maizi@collorg.org>
|
|
6
6
|
License-Expression: GPL-3.0-or-later
|
|
@@ -164,6 +164,11 @@ Author(id=alice['id']).ho_delete()
|
|
|
164
164
|
|
|
165
165
|
- [Learn halfORM in half an hour](https://half-orm.github.io/half-orm/dev/half-an-hour/)
|
|
166
166
|
- [API Reference](https://half-orm.github.io/half-orm/dev/api/relation/)
|
|
167
|
+
- [Breaking changes](https://half-orm.github.io/half-orm/latest/breaking-changes/) — and
|
|
168
|
+
what to do coming from a 0.x release, all of which were published as Beta
|
|
169
|
+
- [Security](https://half-orm.github.io/half-orm/latest/security/) — advisories by
|
|
170
|
+
release line, and how to report a vulnerability
|
|
171
|
+
- [What halfORM defends, and what it cannot](https://half-orm.github.io/half-orm/latest/security-model/)
|
|
167
172
|
|
|
168
173
|
## Extensions
|
|
169
174
|
|
|
@@ -135,6 +135,11 @@ Author(id=alice['id']).ho_delete()
|
|
|
135
135
|
|
|
136
136
|
- [Learn halfORM in half an hour](https://half-orm.github.io/half-orm/dev/half-an-hour/)
|
|
137
137
|
- [API Reference](https://half-orm.github.io/half-orm/dev/api/relation/)
|
|
138
|
+
- [Breaking changes](https://half-orm.github.io/half-orm/latest/breaking-changes/) — and
|
|
139
|
+
what to do coming from a 0.x release, all of which were published as Beta
|
|
140
|
+
- [Security](https://half-orm.github.io/half-orm/latest/security/) — advisories by
|
|
141
|
+
release line, and how to report a vulnerability
|
|
142
|
+
- [What halfORM defends, and what it cannot](https://half-orm.github.io/half-orm/latest/security-model/)
|
|
138
143
|
|
|
139
144
|
## Extensions
|
|
140
145
|
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# -*- coding: utf-8 -*-
|
|
3
|
+
|
|
4
|
+
"""Canonicalisation of the predicate structure returned by
|
|
5
|
+
:meth:`~half_orm.relation.Relation.ho_where_display`.
|
|
6
|
+
|
|
7
|
+
Kept in a dependency-free leaf module so that both
|
|
8
|
+
:mod:`half_orm.relation` and :mod:`half_orm.testing` can use it without
|
|
9
|
+
either importing the other, and so that importing the testing helpers
|
|
10
|
+
does not pull in the database driver.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
__all__ = ['canonical_predicate']
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def canonical_predicate(node):
|
|
17
|
+
"""Return a hashable, alias-free, canonical form of a predicate node.
|
|
18
|
+
|
|
19
|
+
The form produced is a nested tuple, so it can be used as a dictionary
|
|
20
|
+
key or a set member. Relation aliases (``r{ho_id}``), which differ
|
|
21
|
+
between instances of the same query, are dropped, and the operands of
|
|
22
|
+
the commutative operators (``or``, ``and``) are ordered, so that
|
|
23
|
+
``A | B`` and ``B | A`` canonicalise identically. ``and not`` is not
|
|
24
|
+
commutative and keeps its operand order.
|
|
25
|
+
|
|
26
|
+
Args:
|
|
27
|
+
node (dict | None): a node as returned by
|
|
28
|
+
:meth:`~half_orm.relation.Relation.ho_where_display`.
|
|
29
|
+
|
|
30
|
+
Returns:
|
|
31
|
+
tuple | None: the canonical form, or ``None`` for an unconstrained
|
|
32
|
+
predicate. Note that ``None`` says nothing about *which* relation
|
|
33
|
+
is unconstrained; callers needing to tell two unconstrained
|
|
34
|
+
relations apart must tag the result with the relation itself, as
|
|
35
|
+
:meth:`~half_orm.relation.Relation.ho_structural_key` does.
|
|
36
|
+
"""
|
|
37
|
+
if node is None:
|
|
38
|
+
return None
|
|
39
|
+
op = node.get('operator')
|
|
40
|
+
if op == 'neg':
|
|
41
|
+
return ('neg', canonical_predicate(node['operand']))
|
|
42
|
+
if op:
|
|
43
|
+
left = canonical_predicate(node['left'])
|
|
44
|
+
right = canonical_predicate(node.get('right'))
|
|
45
|
+
if op in ('or', 'and'):
|
|
46
|
+
return (op, *sorted([left, right], key=repr))
|
|
47
|
+
return (op, left, right) # 'and not' is not commutative
|
|
48
|
+
tables = frozenset(node.get('tables', set()))
|
|
49
|
+
constraints = tuple(sorted(
|
|
50
|
+
(c['relation'][0], c['field'], c['comp'], str(c['value']))
|
|
51
|
+
for c in node.get('constraints', [])
|
|
52
|
+
))
|
|
53
|
+
leaf = (tables, constraints)
|
|
54
|
+
# A negated compound arrives as a 'neg' node; a negated leaf carries the
|
|
55
|
+
# flag instead. Both canonicalise to the same shape.
|
|
56
|
+
return ('neg', leaf) if node.get('neg') else leaf
|
|
@@ -42,10 +42,17 @@ class FKey:
|
|
|
42
42
|
class Post(blog.get_relation_class('blog.post')):
|
|
43
43
|
Fkeys = {
|
|
44
44
|
'author_fk': 'post_author_id_fkey',
|
|
45
|
-
'comment_rfk': '
|
|
45
|
+
'comment_rfk': '_reverse_fkey_blog_blog_comment_post_id',
|
|
46
46
|
}
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
+
A direct FK carries the constraint name PostgreSQL gave it. A reverse FK
|
|
50
|
+
has no constraint of its own, so one is built from the referencing side:
|
|
51
|
+
``_reverse_fkey_<database>_<schema>_<table>_<field>``. The database name
|
|
52
|
+
is part of it, which is why ``blog`` appears twice above -- the database
|
|
53
|
+
and the schema happen to share a name. It is not a typo, and dropping the
|
|
54
|
+
component yields a name no relation answers to.
|
|
55
|
+
|
|
49
56
|
Use a FK attribute in two ways:
|
|
50
57
|
|
|
51
58
|
* **Call it** (``post.author_fk()``) to navigate: returns the related
|
|
@@ -298,6 +298,7 @@ class Model:
|
|
|
298
298
|
self.__thread_local = threading.local()
|
|
299
299
|
self.__with_half_orm_meta = _normalize_with_half_orm_meta(with_half_orm_meta)
|
|
300
300
|
self.__schema_generation = 0
|
|
301
|
+
self.__read_sets = {}
|
|
301
302
|
self.__aconn = None
|
|
302
303
|
self.__connect()
|
|
303
304
|
|
|
@@ -423,6 +424,7 @@ class Model:
|
|
|
423
424
|
self.__pg_meta = pg_meta.PgMeta(conn, self.__with_half_orm_meta, reload)
|
|
424
425
|
if reload:
|
|
425
426
|
self.__schema_generation += 1
|
|
427
|
+
self.__read_sets = {}
|
|
426
428
|
self._classes_[self._dbname] = {}
|
|
427
429
|
self.__deja_vu[self.__dbname] = self
|
|
428
430
|
self.__thread_local.conn = conn
|
|
@@ -554,7 +556,7 @@ class Model:
|
|
|
554
556
|
# Preferred: subclass and register
|
|
555
557
|
@register
|
|
556
558
|
class Author(blog.get_relation_class('blog.author')):
|
|
557
|
-
Fkeys = {'post_rfk': '
|
|
559
|
+
Fkeys = {'post_rfk': '_reverse_fkey_blog_blog_post_author_id'}
|
|
558
560
|
```
|
|
559
561
|
|
|
560
562
|
"""
|
|
@@ -741,6 +743,68 @@ class Model:
|
|
|
741
743
|
"Connection closed. Call model.reconnect() to re-establish.")
|
|
742
744
|
return conn
|
|
743
745
|
|
|
746
|
+
__READ_SET_QUERY = """
|
|
747
|
+
WITH RECURSIVE root AS (
|
|
748
|
+
SELECT (quote_ident(%s) || '.' || quote_ident(%s))::regclass AS oid
|
|
749
|
+
), reads(oid) AS (
|
|
750
|
+
SELECT oid FROM root
|
|
751
|
+
UNION
|
|
752
|
+
SELECT x.oid
|
|
753
|
+
FROM reads r
|
|
754
|
+
CROSS JOIN LATERAL (
|
|
755
|
+
SELECT d.refobjid AS oid
|
|
756
|
+
FROM pg_rewrite rw
|
|
757
|
+
JOIN pg_depend d ON d.objid = rw.oid
|
|
758
|
+
AND d.classid = 'pg_rewrite'::regclass
|
|
759
|
+
AND d.refclassid = 'pg_class'::regclass
|
|
760
|
+
AND d.refobjid <> r.oid
|
|
761
|
+
WHERE rw.ev_class = r.oid
|
|
762
|
+
UNION ALL
|
|
763
|
+
SELECT i.inhrelid
|
|
764
|
+
FROM pg_inherits i
|
|
765
|
+
WHERE i.inhparent = r.oid
|
|
766
|
+
AND NOT (%s AND r.oid = (SELECT oid FROM root))
|
|
767
|
+
) x
|
|
768
|
+
)
|
|
769
|
+
SELECT n.nspname AS schema, c.relname AS name
|
|
770
|
+
FROM reads r
|
|
771
|
+
JOIN pg_class c ON c.oid = r.oid
|
|
772
|
+
JOIN pg_namespace n ON n.oid = c.relnamespace
|
|
773
|
+
WHERE c.relkind IN ('r', 'p', 'm', 'f')
|
|
774
|
+
"""
|
|
775
|
+
|
|
776
|
+
def _read_set(self, schema, relname, only=False):
|
|
777
|
+
"""Returns the physical relations a read of ``schema.relname`` touches.
|
|
778
|
+
|
|
779
|
+
A view contributes the relations it is defined over, recursively, and
|
|
780
|
+
a table contributes its inheritance children, also recursively, since
|
|
781
|
+
a query without ``ONLY`` returns their rows too. The two expansions
|
|
782
|
+
compose: a view over an inherited table reaches the children of that
|
|
783
|
+
table. Views themselves are left out of the result, having no rows of
|
|
784
|
+
their own.
|
|
785
|
+
|
|
786
|
+
The answer depends only on the schema, so it is computed once per
|
|
787
|
+
``(schema, relname, only)`` and dropped by
|
|
788
|
+
``reconnect(reload=True)``.
|
|
789
|
+
|
|
790
|
+
Args:
|
|
791
|
+
schema (str): schema name.
|
|
792
|
+
relname (str): relation name.
|
|
793
|
+
only (bool): ``True`` when the read uses ``ONLY``, which excludes
|
|
794
|
+
the inheritance children of this relation, though not those
|
|
795
|
+
reached through a view it is defined over.
|
|
796
|
+
|
|
797
|
+
Returns:
|
|
798
|
+
frozenset[str]: ``'schema.name'`` for each physical relation read.
|
|
799
|
+
"""
|
|
800
|
+
key = (schema, relname, only)
|
|
801
|
+
if key not in self.__read_sets:
|
|
802
|
+
self.__read_sets[key] = frozenset(
|
|
803
|
+
f"{row['schema']}.{row['name']}"
|
|
804
|
+
for row in self.execute_query(
|
|
805
|
+
self.__READ_SET_QUERY, (schema, relname, only)))
|
|
806
|
+
return self.__read_sets[key]
|
|
807
|
+
|
|
744
808
|
def _fields_metadata(self, sfqrn):
|
|
745
809
|
"Proxy to PgMeta.fields_meta"
|
|
746
810
|
return self.__pg_meta.fields_meta(self.__dbname, sfqrn)
|
|
@@ -35,6 +35,7 @@ from psycopg.rows import dict_row
|
|
|
35
35
|
from half_orm import relation_errors
|
|
36
36
|
from half_orm.transaction import Transaction, AsyncTransaction
|
|
37
37
|
from half_orm.field import Field
|
|
38
|
+
from half_orm._predicate import canonical_predicate
|
|
38
39
|
from half_orm import utils
|
|
39
40
|
from half_orm.sql_ast import (
|
|
40
41
|
Select as ASTSelect, Insert as ASTInsert, Update as ASTUpdate,
|
|
@@ -1338,7 +1339,13 @@ class Relation:
|
|
|
1338
1339
|
keys ``relation``, ``field``, ``comp``, ``value``
|
|
1339
1340
|
(leaf: own fields; compound/neg: concatenation of children).
|
|
1340
1341
|
|
|
1341
|
-
A **leaf** node additionally has ``'joins'``, ``'where'``, ``'values'
|
|
1342
|
+
A **leaf** node additionally has ``'joins'``, ``'where'``, ``'values'``,
|
|
1343
|
+
``'table_path'`` and ``'neg'``. The last is ``True`` when the relation
|
|
1344
|
+
itself is negated (``~r`` on an operand carrying no set operator);
|
|
1345
|
+
a negated *compound* is reported as a negation node instead, so
|
|
1346
|
+
consumers that ignore ``'neg'`` would read a negated leaf as if it
|
|
1347
|
+
were not negated.
|
|
1348
|
+
|
|
1342
1349
|
|
|
1343
1350
|
A **compound** node (``|``, ``&``, ``-``) additionally has
|
|
1344
1351
|
``'operator'`` (``'or'``, ``'and'``, ``'and not'``),
|
|
@@ -1425,8 +1432,138 @@ class Relation:
|
|
|
1425
1432
|
'constraints': self._ho_collect_constraints(),
|
|
1426
1433
|
'tables': tables,
|
|
1427
1434
|
'table_path': table_path,
|
|
1435
|
+
'neg': self._ho_neg,
|
|
1428
1436
|
}
|
|
1429
1437
|
|
|
1438
|
+
def ho_read_set(self):
|
|
1439
|
+
"""Returns the physical relations whose contents can change this result.
|
|
1440
|
+
|
|
1441
|
+
Reading a view reads the relations it is defined over, and reading a
|
|
1442
|
+
table without ``ONLY`` reads its inheritance children as well. The two
|
|
1443
|
+
compose, so a view over an inherited table reaches that table's
|
|
1444
|
+
children. Foreign-key navigation adds the relations it joins. Views
|
|
1445
|
+
are absent from the result, having no rows of their own.
|
|
1446
|
+
|
|
1447
|
+
An application cache can index its entries by these names and drop the
|
|
1448
|
+
ones a write touches. Note the boundary: this catches writes issued by
|
|
1449
|
+
this process. Another client writing to the database leaves the cache
|
|
1450
|
+
stale, so the scheme suits data that changes rarely and through one
|
|
1451
|
+
application. Cross-process invalidation needs ``LISTEN``/``NOTIFY``
|
|
1452
|
+
and triggers, which is the application's business, not the library's.
|
|
1453
|
+
|
|
1454
|
+
The answer depends only on the schema. It is computed once per
|
|
1455
|
+
relation and dropped by ``reconnect(reload=True)``.
|
|
1456
|
+
|
|
1457
|
+
Returns:
|
|
1458
|
+
frozenset[str]: ``'schema.name'`` for each physical relation read.
|
|
1459
|
+
|
|
1460
|
+
Example:
|
|
1461
|
+
Drop the cache entries a write invalidates:
|
|
1462
|
+
```python
|
|
1463
|
+
class QueryCache:
|
|
1464
|
+
def __init__(self):
|
|
1465
|
+
self._rows, self._by_table = {}, {}
|
|
1466
|
+
|
|
1467
|
+
def rows(self, rel):
|
|
1468
|
+
key = rel.ho_structural_key()
|
|
1469
|
+
if key not in self._rows:
|
|
1470
|
+
self._rows[key] = list(rel.ho_select())
|
|
1471
|
+
for table in rel.ho_read_set():
|
|
1472
|
+
self._by_table.setdefault(table, set()).add(key)
|
|
1473
|
+
return self._rows[key]
|
|
1474
|
+
|
|
1475
|
+
def invalidate(self, table):
|
|
1476
|
+
for key in self._by_table.pop(table, ()):
|
|
1477
|
+
self._rows.pop(key, None)
|
|
1478
|
+
|
|
1479
|
+
cache.invalidate('blog.post') # after a write on blog.post
|
|
1480
|
+
```
|
|
1481
|
+
|
|
1482
|
+
*New in version 1.2.0.*
|
|
1483
|
+
"""
|
|
1484
|
+
_, schema, relname = self._t_fqrn
|
|
1485
|
+
read = set(self._ho_model._read_set(schema, relname, self._ho_only))
|
|
1486
|
+
node = self.ho_where_display()
|
|
1487
|
+
if node:
|
|
1488
|
+
for qualified in node.get('tables', ()):
|
|
1489
|
+
# 'schema.name', and a schema may itself contain a dot.
|
|
1490
|
+
other_schema, _, other_name = qualified.rpartition('.')
|
|
1491
|
+
if (other_schema, other_name) != (schema, relname):
|
|
1492
|
+
read |= self._ho_model._read_set(other_schema, other_name)
|
|
1493
|
+
return frozenset(read)
|
|
1494
|
+
|
|
1495
|
+
def ho_structural_key(self):
|
|
1496
|
+
"""Returns a hashable, canonical key for this relation's structure.
|
|
1497
|
+
|
|
1498
|
+
The key identifies *how the question was asked*: the relation, and the
|
|
1499
|
+
shape of the predicate built on it. It is a pure function of the
|
|
1500
|
+
object, issues no query, and can be used as a dictionary key or a set
|
|
1501
|
+
member, which a ``Relation`` itself cannot be: defining ``__eq__`` as
|
|
1502
|
+
set equality makes instances unhashable, since no pure function of the
|
|
1503
|
+
object can track an equality that depends on the current state of the
|
|
1504
|
+
database.
|
|
1505
|
+
|
|
1506
|
+
Two relations with the same key always denote the same query. The
|
|
1507
|
+
converse does not hold: ``Person(last_name='Martin')`` and
|
|
1508
|
+
``Person(first_name='Jo')`` may match the same rows today and still
|
|
1509
|
+
have different keys. The error is therefore always on the safe side —
|
|
1510
|
+
a cache keyed this way may miss, never return the wrong rows.
|
|
1511
|
+
|
|
1512
|
+
Operand order is normalised for the commutative operators, so ``a | b``
|
|
1513
|
+
and ``b | a`` share a key. No attempt is made to reconcile predicates
|
|
1514
|
+
that are logically equivalent but structurally different; that is query
|
|
1515
|
+
equivalence, which is NP-complete for conjunctive queries under set
|
|
1516
|
+
semantics, and not the business of a hash key.
|
|
1517
|
+
|
|
1518
|
+
The key is recomputed on each call, in time proportional to the size of
|
|
1519
|
+
the predicate: a ``Relation`` is mutable, so caching it would be wrong
|
|
1520
|
+
without invalidation.
|
|
1521
|
+
|
|
1522
|
+
Arguments passed to the terminal method are **not** part of the key.
|
|
1523
|
+
``ho_select()`` and ``ho_select(limit=10)`` run on the same relation
|
|
1524
|
+
and share a key, so a cache must be keyed on the call, not on the
|
|
1525
|
+
relation alone, whenever those arguments vary.
|
|
1526
|
+
|
|
1527
|
+
Returns:
|
|
1528
|
+
tuple: ``((fqrn, only), canonical_predicate)``, where *fqrn* is the
|
|
1529
|
+
``(database, schema, relation)`` triple, *only* says whether the
|
|
1530
|
+
query reads the relation with ``ONLY``, excluding the rows of its
|
|
1531
|
+
inheritance children, and the last member is ``None`` when the
|
|
1532
|
+
relation is unconstrained.
|
|
1533
|
+
|
|
1534
|
+
Example:
|
|
1535
|
+
Memoise results in the application, since halfORM keeps no cache
|
|
1536
|
+
of its own:
|
|
1537
|
+
```python
|
|
1538
|
+
cache = {}
|
|
1539
|
+
|
|
1540
|
+
def rows(rel):
|
|
1541
|
+
key = rel.ho_structural_key()
|
|
1542
|
+
if key not in cache:
|
|
1543
|
+
cache[key] = list(rel.ho_select())
|
|
1544
|
+
return cache[key]
|
|
1545
|
+
|
|
1546
|
+
rows(Post(published=True)) # one query
|
|
1547
|
+
rows(Post(published=True)) # served from cache
|
|
1548
|
+
rows(Author(name='Alice').rfk_posts()) # other key, one query
|
|
1549
|
+
```
|
|
1550
|
+
|
|
1551
|
+
Issue each query once when several code paths build predicates
|
|
1552
|
+
independently:
|
|
1553
|
+
```python
|
|
1554
|
+
wanted, seen = [], set()
|
|
1555
|
+
for spec in report_specs:
|
|
1556
|
+
rel = build_predicate(spec)
|
|
1557
|
+
if (key := rel.ho_structural_key()) not in seen:
|
|
1558
|
+
seen.add(key)
|
|
1559
|
+
wanted.append(rel)
|
|
1560
|
+
```
|
|
1561
|
+
|
|
1562
|
+
*New in version 1.2.0.*
|
|
1563
|
+
"""
|
|
1564
|
+
return ((self._t_fqrn, self._ho_only),
|
|
1565
|
+
canonical_predicate(self.ho_where_display()))
|
|
1566
|
+
|
|
1430
1567
|
def __repr__(self):
|
|
1431
1568
|
|
|
1432
1569
|
fkeys_usage = """\
|
|
@@ -2403,7 +2540,7 @@ def singleton(fct):
|
|
|
2403
2540
|
```python
|
|
2404
2541
|
@register
|
|
2405
2542
|
class Author(blog.get_relation_class('blog.author')):
|
|
2406
|
-
Fkeys = {'post_rfk': '
|
|
2543
|
+
Fkeys = {'post_rfk': '_reverse_fkey_blog_blog_post_author_id'}
|
|
2407
2544
|
|
|
2408
2545
|
@singleton
|
|
2409
2546
|
def publish(self, title: str, content: str):
|
|
@@ -318,40 +318,21 @@ def assertConstraintsMatch(relation, *, table=None, field=None, comp='=', value=
|
|
|
318
318
|
)
|
|
319
319
|
|
|
320
320
|
|
|
321
|
-
def _canonical(node):
|
|
322
|
-
"""Return a normalised, alias-free representation of a ho_where_display node.
|
|
323
|
-
|
|
324
|
-
Used by :func:`assertSamePredicate` to compare predicates structurally,
|
|
325
|
-
ignoring relation aliases (``r{ho_id}``) and the left/right ordering of
|
|
326
|
-
commutative operators (``or``, ``and``).
|
|
327
|
-
"""
|
|
328
|
-
if node is None:
|
|
329
|
-
return None
|
|
330
|
-
op = node.get('operator')
|
|
331
|
-
if op == 'neg':
|
|
332
|
-
return ('neg', _canonical(node['operand']))
|
|
333
|
-
if op:
|
|
334
|
-
left = _canonical(node['left'])
|
|
335
|
-
right = _canonical(node.get('right'))
|
|
336
|
-
if op in ('or', 'and'):
|
|
337
|
-
return (op, *sorted([left, right], key=repr))
|
|
338
|
-
return (op, left, right) # 'and not' is not commutative
|
|
339
|
-
tables = frozenset(node.get('tables', set()))
|
|
340
|
-
constraints = tuple(sorted(
|
|
341
|
-
(c['relation'][0], c['field'], c['comp'], str(c['value']))
|
|
342
|
-
for c in node.get('constraints', [])
|
|
343
|
-
))
|
|
344
|
-
return (tables, constraints)
|
|
345
|
-
|
|
346
|
-
|
|
347
321
|
def assertSamePredicate(rel1, rel2, msg=None):
|
|
348
322
|
"""Assert that two relations produce the same logical predicate.
|
|
349
323
|
|
|
350
|
-
Compares
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
324
|
+
Compares the relations' structural keys
|
|
325
|
+
(:meth:`~half_orm.relation.Relation.ho_structural_key`), ignoring relation
|
|
326
|
+
aliases (``r{ho_id}``) which differ between object instances even for
|
|
327
|
+
equivalent queries. Commutative operators (``or``, ``and``) are normalised
|
|
328
|
+
so that ``A | B`` and ``B | A`` are considered equal; ``and not`` is not
|
|
329
|
+
commutative and is compared as-is. Relations on different tables never
|
|
330
|
+
match, including when both are unconstrained.
|
|
331
|
+
|
|
332
|
+
*Changed in version 1.2.0: two unconstrained relations on different tables
|
|
333
|
+
used to compare equal, because both yielded an empty predicate, and a
|
|
334
|
+
predicate compared equal to its complement. The relation and the negation
|
|
335
|
+
are now part of the comparison.*
|
|
355
336
|
|
|
356
337
|
Args:
|
|
357
338
|
rel1: first halfORM relation object.
|
|
@@ -370,11 +351,11 @@ def assertSamePredicate(rel1, rel2, msg=None):
|
|
|
370
351
|
post.rfk_comments().author_fk(),
|
|
371
352
|
)
|
|
372
353
|
"""
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
if
|
|
354
|
+
k1 = rel1.ho_structural_key()
|
|
355
|
+
k2 = rel2.ho_structural_key()
|
|
356
|
+
if k1 != k2:
|
|
376
357
|
raise AssertionError(
|
|
377
|
-
msg or f"predicates differ:\n left: {
|
|
358
|
+
msg or f"predicates differ:\n left: {k1}\n right: {k2}"
|
|
378
359
|
)
|
|
379
360
|
|
|
380
361
|
|
|
@@ -0,0 +1,473 @@
|
|
|
1
|
+
#-*- coding: utf-8 -*-
|
|
2
|
+
# pylint: disable=too-few-public-methods, protected-access
|
|
3
|
+
|
|
4
|
+
"""This module provides the Transaction class."""
|
|
5
|
+
|
|
6
|
+
import inspect
|
|
7
|
+
import sys
|
|
8
|
+
import threading
|
|
9
|
+
import traceback
|
|
10
|
+
|
|
11
|
+
import psycopg
|
|
12
|
+
|
|
13
|
+
from half_orm import utils
|
|
14
|
+
|
|
15
|
+
class Transaction:
|
|
16
|
+
"""Context manager for atomic database operations.
|
|
17
|
+
|
|
18
|
+
Wraps one or more SQL operations in a single transaction: commits on
|
|
19
|
+
success, rolls back on exception. Transactions are per-thread and
|
|
20
|
+
per-model instance.
|
|
21
|
+
|
|
22
|
+
Nested ``with Transaction(model)`` blocks use PostgreSQL savepoints
|
|
23
|
+
automatically: an exception in an inner block rolls back only that inner
|
|
24
|
+
block, leaving the outer transaction intact.
|
|
25
|
+
|
|
26
|
+
Args:
|
|
27
|
+
model (Model): the :class:`~half_orm.model.Model` instance whose
|
|
28
|
+
connection should be used.
|
|
29
|
+
|
|
30
|
+
Example:
|
|
31
|
+
Atomic insert of two related rows:
|
|
32
|
+
```python
|
|
33
|
+
from half_orm.transaction import Transaction
|
|
34
|
+
|
|
35
|
+
with Transaction(blog):
|
|
36
|
+
alice = Author(
|
|
37
|
+
first_name='Alice', last_name='Martin',
|
|
38
|
+
email='alice@example.com',
|
|
39
|
+
).ho_insert()
|
|
40
|
+
Post(
|
|
41
|
+
title='First post', content='Hello world',
|
|
42
|
+
author_id=alice['id'],
|
|
43
|
+
).ho_insert()
|
|
44
|
+
# both rows are committed, or neither is
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Nested transactions use savepoints:
|
|
48
|
+
```python
|
|
49
|
+
with Transaction(blog):
|
|
50
|
+
alice = Author(...).ho_insert()
|
|
51
|
+
with Transaction(blog): # savepoint
|
|
52
|
+
Post(...).ho_insert()
|
|
53
|
+
# exception here rolls back only the post, not Alice
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Work that must wait for the COMMIT (see :meth:`after_commit`):
|
|
57
|
+
```python
|
|
58
|
+
with Transaction(blog):
|
|
59
|
+
post = Post(title='First post').ho_insert()
|
|
60
|
+
Transaction(blog).after_commit(lambda: notify(post['id']))
|
|
61
|
+
# notify() runs here, the COMMIT having succeeded
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
*New in version 0.18.0:* nested ``Transaction`` blocks use savepoints.
|
|
65
|
+
|
|
66
|
+
*New in version 1.2.0:* :meth:`after_commit` and :meth:`after_rollback`.
|
|
67
|
+
"""
|
|
68
|
+
|
|
69
|
+
__tls = threading.local()
|
|
70
|
+
|
|
71
|
+
def __call__(self, model):
|
|
72
|
+
if not hasattr(self.__class__.__tls, 'transactions'):
|
|
73
|
+
self.__class__.__tls.transactions = {}
|
|
74
|
+
transactions = self.__class__.__tls.transactions
|
|
75
|
+
self.__id = id(model)
|
|
76
|
+
self.__transaction = None
|
|
77
|
+
if self.__id not in transactions:
|
|
78
|
+
transactions[self.__id] = {
|
|
79
|
+
'level': 0, 'model': model,
|
|
80
|
+
'sp_counter': 0, 'sp_stack': [],
|
|
81
|
+
'on_commit': [], 'on_rollback': [],
|
|
82
|
+
}
|
|
83
|
+
self.__transaction = transactions[self.__id]
|
|
84
|
+
|
|
85
|
+
__init__ = __call__
|
|
86
|
+
|
|
87
|
+
def __enter__(self):
|
|
88
|
+
conn = self.__transaction['model']._connection
|
|
89
|
+
if conn.autocommit:
|
|
90
|
+
conn.autocommit = False
|
|
91
|
+
if self.__transaction['level'] > 0:
|
|
92
|
+
self.__transaction['sp_counter'] += 1
|
|
93
|
+
sp_name = f'sp_{self.__transaction["sp_counter"]}'
|
|
94
|
+
self.__transaction['sp_stack'].append(sp_name)
|
|
95
|
+
with conn.cursor() as cur:
|
|
96
|
+
cur.execute(f'SAVEPOINT {sp_name}')
|
|
97
|
+
self.__transaction['level'] += 1
|
|
98
|
+
# One frame of callbacks per open scope. Pushed last: nothing may fail
|
|
99
|
+
# after this point, or `__exit__` would never pop them.
|
|
100
|
+
self.__transaction['on_commit'].append([])
|
|
101
|
+
self.__transaction['on_rollback'].append([])
|
|
102
|
+
|
|
103
|
+
def __exit__(self, exc_type, exc_val, exc_tb):
|
|
104
|
+
self.__transaction['level'] -= 1
|
|
105
|
+
conn = self.__transaction['model']._connection
|
|
106
|
+
on_commit = self.__transaction['on_commit'].pop()
|
|
107
|
+
on_rollback = self.__transaction['on_rollback'].pop()
|
|
108
|
+
if self.__transaction['level'] > 0:
|
|
109
|
+
sp_name = self.__transaction['sp_stack'].pop()
|
|
110
|
+
with conn.cursor() as cur:
|
|
111
|
+
if exc_type is not None:
|
|
112
|
+
cur.execute(f'ROLLBACK TO SAVEPOINT {sp_name}')
|
|
113
|
+
cur.execute(f'RELEASE SAVEPOINT {sp_name}')
|
|
114
|
+
self.__settle(exc_type is None, on_commit, on_rollback)
|
|
115
|
+
else:
|
|
116
|
+
committed = False
|
|
117
|
+
try:
|
|
118
|
+
if exc_type is not None:
|
|
119
|
+
conn.rollback()
|
|
120
|
+
else:
|
|
121
|
+
conn.commit()
|
|
122
|
+
committed = True
|
|
123
|
+
except psycopg.Error:
|
|
124
|
+
# A failed COMMIT must reach the caller: silently rolling back
|
|
125
|
+
# would leave the application believing its work was persisted.
|
|
126
|
+
# A failed ROLLBACK, on the other hand, must not displace the
|
|
127
|
+
# exception the caller is already handling.
|
|
128
|
+
if exc_type is None:
|
|
129
|
+
raise
|
|
130
|
+
finally:
|
|
131
|
+
_restore_autocommit(conn)
|
|
132
|
+
# In the `finally`: the callbacks of a transaction whose COMMIT
|
|
133
|
+
# failed are those of a rollback, and they must run on the way
|
|
134
|
+
# out of the error too.
|
|
135
|
+
self.__settle(committed, on_commit, on_rollback)
|
|
136
|
+
return False
|
|
137
|
+
|
|
138
|
+
def after_commit(self, callback):
|
|
139
|
+
"""Register `callback` to run once the transaction has committed.
|
|
140
|
+
|
|
141
|
+
A mutation only becomes a fact when the COMMIT succeeds: anything
|
|
142
|
+
whose effect leaves the database — a notification, a cache eviction,
|
|
143
|
+
a websocket event — has to wait for it, or it announces rows that a
|
|
144
|
+
rollback has taken back.
|
|
145
|
+
|
|
146
|
+
Outside a transaction, a mutation commits on its own and the callback
|
|
147
|
+
runs immediately. Inside one, it is queued and runs after the COMMIT
|
|
148
|
+
of the outermost block, in registration order, with the connection
|
|
149
|
+
back in autocommit mode. Rolling back a savepoint drops the callbacks
|
|
150
|
+
registered inside it; releasing one hands them to the enclosing scope,
|
|
151
|
+
whose own outcome then decides.
|
|
152
|
+
|
|
153
|
+
Registration is bound to the model and the current thread, not to this
|
|
154
|
+
instance: ``Transaction(model).after_commit(...)`` reaches the open
|
|
155
|
+
transaction from anywhere in the call stack, with no reference to the
|
|
156
|
+
object that opened it.
|
|
157
|
+
|
|
158
|
+
A callback failure is reported on stderr, and the callbacks that
|
|
159
|
+
follow still run. It is never raised to the caller: the COMMIT has
|
|
160
|
+
already succeeded, and an exception here would describe the
|
|
161
|
+
transaction as having failed.
|
|
162
|
+
|
|
163
|
+
Args:
|
|
164
|
+
callback: a callable taking no argument. Its return value is
|
|
165
|
+
ignored.
|
|
166
|
+
|
|
167
|
+
Example:
|
|
168
|
+
Publish an event only if the whole unit of work lands:
|
|
169
|
+
```python
|
|
170
|
+
@transaction
|
|
171
|
+
def publish(self, title):
|
|
172
|
+
post = self.post_rfk(title=title).ho_insert()
|
|
173
|
+
Transaction(self._ho_model).after_commit(
|
|
174
|
+
lambda: broadcast('post', 'create', post['id']))
|
|
175
|
+
self.index(post) # may raise — nothing is broadcast
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
*New in version 1.2.0.*
|
|
179
|
+
"""
|
|
180
|
+
frames = self.__transaction['on_commit']
|
|
181
|
+
if frames:
|
|
182
|
+
frames[-1].append(callback)
|
|
183
|
+
else:
|
|
184
|
+
_run_callbacks([callback])
|
|
185
|
+
|
|
186
|
+
def after_rollback(self, callback):
|
|
187
|
+
"""Register `callback` to run if the transaction is rolled back.
|
|
188
|
+
|
|
189
|
+
The mirror of :meth:`after_commit`: the callback runs when the scope
|
|
190
|
+
it was registered in is undone — the rollback of the outermost block,
|
|
191
|
+
the rollback of the savepoint it belongs to, or a COMMIT that fails.
|
|
192
|
+
Releasing a savepoint hands its callbacks to the enclosing scope,
|
|
193
|
+
which may still roll back.
|
|
194
|
+
|
|
195
|
+
Outside a transaction there is nothing to undo and the callback is
|
|
196
|
+
dropped — the symmetric case of :meth:`after_commit` running it at
|
|
197
|
+
once.
|
|
198
|
+
|
|
199
|
+
As with :meth:`after_commit`, a callback failure is reported on stderr
|
|
200
|
+
and never raised: here it would displace the exception the caller is
|
|
201
|
+
already handling.
|
|
202
|
+
|
|
203
|
+
Args:
|
|
204
|
+
callback: a callable taking no argument. Its return value is
|
|
205
|
+
ignored.
|
|
206
|
+
|
|
207
|
+
*New in version 1.2.0.*
|
|
208
|
+
"""
|
|
209
|
+
frames = self.__transaction['on_rollback']
|
|
210
|
+
if frames:
|
|
211
|
+
frames[-1].append(callback)
|
|
212
|
+
|
|
213
|
+
def __settle(self, committed, on_commit, on_rollback):
|
|
214
|
+
"""Dispose of the callbacks of the scope that just ended.
|
|
215
|
+
|
|
216
|
+
A released savepoint hands them to the enclosing scope instead of
|
|
217
|
+
running them: nothing is committed until the outermost block is.
|
|
218
|
+
"""
|
|
219
|
+
enclosing = self.__transaction['on_commit']
|
|
220
|
+
if committed and enclosing:
|
|
221
|
+
enclosing[-1].extend(on_commit)
|
|
222
|
+
self.__transaction['on_rollback'][-1].extend(on_rollback)
|
|
223
|
+
elif committed:
|
|
224
|
+
_run_callbacks(on_commit)
|
|
225
|
+
else:
|
|
226
|
+
_run_callbacks(on_rollback)
|
|
227
|
+
|
|
228
|
+
@property
|
|
229
|
+
def level(self):
|
|
230
|
+
return self.__transaction.get('level')
|
|
231
|
+
|
|
232
|
+
def is_set(self):
|
|
233
|
+
return self.__transaction.get('level', 0) > 0
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def _restore_autocommit(conn):
|
|
237
|
+
"""Put `conn` back in autocommit mode after the outermost block.
|
|
238
|
+
|
|
239
|
+
Best-effort: if the connection is broken, the failure is irrelevant here —
|
|
240
|
+
``Model._connection`` reconnects on the next use — and must not mask the
|
|
241
|
+
exception on its way out of ``__exit__``.
|
|
242
|
+
"""
|
|
243
|
+
try:
|
|
244
|
+
conn.autocommit = True
|
|
245
|
+
except psycopg.Error:
|
|
246
|
+
pass
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
async def _arestore_autocommit(conn):
|
|
250
|
+
"Async counterpart of :func:`_restore_autocommit`."
|
|
251
|
+
try:
|
|
252
|
+
await conn.set_autocommit(True)
|
|
253
|
+
except psycopg.Error:
|
|
254
|
+
pass
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
def _run_callbacks(callbacks):
|
|
258
|
+
"""Run each callback in registration order, reporting any failure.
|
|
259
|
+
|
|
260
|
+
A callback must not raise here: the outcome of the transaction is already
|
|
261
|
+
decided, and the exception would misrepresent it — as a failure after a
|
|
262
|
+
successful COMMIT, or in place of the error being handled after a
|
|
263
|
+
rollback. Each failure is reported on stderr and the callbacks that follow
|
|
264
|
+
still run: one broken listener must not silence the others.
|
|
265
|
+
"""
|
|
266
|
+
for callback in callbacks:
|
|
267
|
+
try:
|
|
268
|
+
callback()
|
|
269
|
+
except Exception: # pylint: disable=broad-except
|
|
270
|
+
_report_failure(callback)
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
async def _arun_callbacks(callbacks):
|
|
274
|
+
"""Async counterpart of :func:`_run_callbacks`.
|
|
275
|
+
|
|
276
|
+
Awaits whatever a callback returns, so a coroutine function and a plain
|
|
277
|
+
one are both acceptable.
|
|
278
|
+
"""
|
|
279
|
+
for callback in callbacks:
|
|
280
|
+
try:
|
|
281
|
+
result = callback()
|
|
282
|
+
if inspect.isawaitable(result):
|
|
283
|
+
await result
|
|
284
|
+
except Exception: # pylint: disable=broad-except
|
|
285
|
+
_report_failure(callback)
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def _report_failure(callback):
|
|
289
|
+
"Report on stderr the failure of a transaction callback."
|
|
290
|
+
name = getattr(callback, '__qualname__', None) or repr(callback)
|
|
291
|
+
utils.warning(f'{name} transaction callback failed:\n{traceback.format_exc()}')
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
class AsyncTransaction:
|
|
295
|
+
"""Async context manager for atomic database operations.
|
|
296
|
+
|
|
297
|
+
Async counterpart of :class:`Transaction`: drives the model's async
|
|
298
|
+
connection (``model._aconnection``, set up via ``await
|
|
299
|
+
model.aconnect()``) instead of the sync one. Wraps one or more
|
|
300
|
+
``ho_a*`` operations in a single transaction: commits on success, rolls
|
|
301
|
+
back on exception. Transactions are tracked per-model-instance (keyed
|
|
302
|
+
by ``id(model)``) — unlike :class:`Transaction`, there is no per-thread
|
|
303
|
+
isolation, since asyncio concurrency is task-based rather than
|
|
304
|
+
thread-based and a model's async connection is only ever driven from
|
|
305
|
+
one place at a time regardless of which thread runs the event loop.
|
|
306
|
+
|
|
307
|
+
Nested ``async with AsyncTransaction(model)`` blocks use PostgreSQL
|
|
308
|
+
savepoints automatically: an exception in an inner block rolls back
|
|
309
|
+
only that inner block, leaving the outer transaction intact.
|
|
310
|
+
|
|
311
|
+
Args:
|
|
312
|
+
model (Model): the :class:`~half_orm.model.Model` instance whose
|
|
313
|
+
async connection should be used.
|
|
314
|
+
|
|
315
|
+
Example:
|
|
316
|
+
Atomic insert of two related rows:
|
|
317
|
+
```python
|
|
318
|
+
from half_orm.transaction import AsyncTransaction
|
|
319
|
+
|
|
320
|
+
async with AsyncTransaction(blog):
|
|
321
|
+
alice = await Author(
|
|
322
|
+
first_name='Alice', last_name='Martin',
|
|
323
|
+
email='alice@example.com',
|
|
324
|
+
).ho_ainsert()
|
|
325
|
+
await Post(
|
|
326
|
+
title='First post', content='Hello world',
|
|
327
|
+
author_id=alice['id'],
|
|
328
|
+
).ho_ainsert()
|
|
329
|
+
# both rows are committed, or neither is
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
*New in version 0.18.0.*
|
|
333
|
+
|
|
334
|
+
*New in version 1.2.0:* :meth:`after_commit` and :meth:`after_rollback`.
|
|
335
|
+
"""
|
|
336
|
+
|
|
337
|
+
__transactions: dict = {}
|
|
338
|
+
|
|
339
|
+
def __call__(self, model):
|
|
340
|
+
transactions = self.__class__.__transactions
|
|
341
|
+
self.__id = id(model)
|
|
342
|
+
self.__transaction = None
|
|
343
|
+
if self.__id not in transactions:
|
|
344
|
+
transactions[self.__id] = {
|
|
345
|
+
'level': 0, 'model': model,
|
|
346
|
+
'sp_counter': 0, 'sp_stack': [],
|
|
347
|
+
'on_commit': [], 'on_rollback': [],
|
|
348
|
+
}
|
|
349
|
+
self.__transaction = transactions[self.__id]
|
|
350
|
+
|
|
351
|
+
__init__ = __call__
|
|
352
|
+
|
|
353
|
+
async def __aenter__(self):
|
|
354
|
+
conn = self.__transaction['model']._aconnection
|
|
355
|
+
if conn.autocommit:
|
|
356
|
+
await conn.set_autocommit(False)
|
|
357
|
+
if self.__transaction['level'] > 0:
|
|
358
|
+
self.__transaction['sp_counter'] += 1
|
|
359
|
+
sp_name = f'sp_{self.__transaction["sp_counter"]}'
|
|
360
|
+
self.__transaction['sp_stack'].append(sp_name)
|
|
361
|
+
async with conn.cursor() as cur:
|
|
362
|
+
await cur.execute(f'SAVEPOINT {sp_name}')
|
|
363
|
+
self.__transaction['level'] += 1
|
|
364
|
+
# See Transaction.__enter__: one frame per open scope, pushed last.
|
|
365
|
+
self.__transaction['on_commit'].append([])
|
|
366
|
+
self.__transaction['on_rollback'].append([])
|
|
367
|
+
|
|
368
|
+
async def __aexit__(self, exc_type, exc_val, exc_tb):
|
|
369
|
+
self.__transaction['level'] -= 1
|
|
370
|
+
conn = self.__transaction['model']._aconnection
|
|
371
|
+
on_commit = self.__transaction['on_commit'].pop()
|
|
372
|
+
on_rollback = self.__transaction['on_rollback'].pop()
|
|
373
|
+
if self.__transaction['level'] > 0:
|
|
374
|
+
sp_name = self.__transaction['sp_stack'].pop()
|
|
375
|
+
async with conn.cursor() as cur:
|
|
376
|
+
if exc_type is not None:
|
|
377
|
+
await cur.execute(f'ROLLBACK TO SAVEPOINT {sp_name}')
|
|
378
|
+
await cur.execute(f'RELEASE SAVEPOINT {sp_name}')
|
|
379
|
+
await self.__settle(exc_type is None, on_commit, on_rollback)
|
|
380
|
+
else:
|
|
381
|
+
committed = False
|
|
382
|
+
try:
|
|
383
|
+
if exc_type is not None:
|
|
384
|
+
await conn.rollback()
|
|
385
|
+
else:
|
|
386
|
+
await conn.commit()
|
|
387
|
+
committed = True
|
|
388
|
+
except psycopg.Error:
|
|
389
|
+
# See Transaction.__exit__ for why COMMIT and ROLLBACK
|
|
390
|
+
# failures are treated differently.
|
|
391
|
+
if exc_type is None:
|
|
392
|
+
raise
|
|
393
|
+
finally:
|
|
394
|
+
await _arestore_autocommit(conn)
|
|
395
|
+
await self.__settle(committed, on_commit, on_rollback)
|
|
396
|
+
return False
|
|
397
|
+
|
|
398
|
+
async def after_commit(self, callback):
|
|
399
|
+
"""Register `callback` to run once the transaction has committed.
|
|
400
|
+
|
|
401
|
+
Async counterpart of :meth:`Transaction.after_commit`, with the same
|
|
402
|
+
semantics: queued inside a transaction and run after the COMMIT of
|
|
403
|
+
the outermost block in registration order, dropped by the rollback of
|
|
404
|
+
the savepoint it belongs to, handed to the enclosing scope when that
|
|
405
|
+
savepoint is released.
|
|
406
|
+
|
|
407
|
+
Awaiting registration is what lets the callback run outside any
|
|
408
|
+
transaction: there is nothing to defer it to, so it runs — and is
|
|
409
|
+
awaited — on the spot, rather than becoming a background task nobody
|
|
410
|
+
holds a reference to.
|
|
411
|
+
|
|
412
|
+
Args:
|
|
413
|
+
callback: a callable taking no argument, coroutine function or
|
|
414
|
+
not. What it returns is awaited if awaitable, and otherwise
|
|
415
|
+
ignored.
|
|
416
|
+
|
|
417
|
+
Example:
|
|
418
|
+
Publish an event only if the whole unit of work lands:
|
|
419
|
+
```python
|
|
420
|
+
async with AsyncTransaction(blog):
|
|
421
|
+
post = await Post(title='First post').ho_ainsert()
|
|
422
|
+
await AsyncTransaction(blog).after_commit(
|
|
423
|
+
lambda: publish('post', 'create', post['id']))
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
*New in version 1.2.0.*
|
|
427
|
+
"""
|
|
428
|
+
frames = self.__transaction['on_commit']
|
|
429
|
+
if frames:
|
|
430
|
+
frames[-1].append(callback)
|
|
431
|
+
else:
|
|
432
|
+
await _arun_callbacks([callback])
|
|
433
|
+
|
|
434
|
+
async def after_rollback(self, callback):
|
|
435
|
+
"""Register `callback` to run if the transaction is rolled back.
|
|
436
|
+
|
|
437
|
+
Async counterpart of :meth:`Transaction.after_rollback`, with the same
|
|
438
|
+
semantics. A coroutine like :meth:`after_commit`, for symmetry — it
|
|
439
|
+
has nothing to await, a callback registered outside a transaction
|
|
440
|
+
being dropped.
|
|
441
|
+
|
|
442
|
+
Args:
|
|
443
|
+
callback: a callable taking no argument, coroutine function or
|
|
444
|
+
not. What it returns is awaited if awaitable, and otherwise
|
|
445
|
+
ignored.
|
|
446
|
+
|
|
447
|
+
*New in version 1.2.0.*
|
|
448
|
+
"""
|
|
449
|
+
frames = self.__transaction['on_rollback']
|
|
450
|
+
if frames:
|
|
451
|
+
frames[-1].append(callback)
|
|
452
|
+
|
|
453
|
+
async def __settle(self, committed, on_commit, on_rollback):
|
|
454
|
+
"""Dispose of the callbacks of the scope that just ended.
|
|
455
|
+
|
|
456
|
+
Async counterpart of ``Transaction.__settle``: a released savepoint
|
|
457
|
+
hands them to the enclosing scope instead of running them.
|
|
458
|
+
"""
|
|
459
|
+
enclosing = self.__transaction['on_commit']
|
|
460
|
+
if committed and enclosing:
|
|
461
|
+
enclosing[-1].extend(on_commit)
|
|
462
|
+
self.__transaction['on_rollback'][-1].extend(on_rollback)
|
|
463
|
+
elif committed:
|
|
464
|
+
await _arun_callbacks(on_commit)
|
|
465
|
+
else:
|
|
466
|
+
await _arun_callbacks(on_rollback)
|
|
467
|
+
|
|
468
|
+
@property
|
|
469
|
+
def level(self):
|
|
470
|
+
return self.__transaction.get('level')
|
|
471
|
+
|
|
472
|
+
def is_set(self):
|
|
473
|
+
return self.__transaction.get('level', 0) > 0
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
1.2.0
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: half_orm
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.2.0
|
|
4
4
|
Summary: A database-first ORM for PostgreSQL
|
|
5
5
|
Author-email: Joël Maïzi <joel.maizi@collorg.org>
|
|
6
6
|
License-Expression: GPL-3.0-or-later
|
|
@@ -164,6 +164,11 @@ Author(id=alice['id']).ho_delete()
|
|
|
164
164
|
|
|
165
165
|
- [Learn halfORM in half an hour](https://half-orm.github.io/half-orm/dev/half-an-hour/)
|
|
166
166
|
- [API Reference](https://half-orm.github.io/half-orm/dev/api/relation/)
|
|
167
|
+
- [Breaking changes](https://half-orm.github.io/half-orm/latest/breaking-changes/) — and
|
|
168
|
+
what to do coming from a 0.x release, all of which were published as Beta
|
|
169
|
+
- [Security](https://half-orm.github.io/half-orm/latest/security/) — advisories by
|
|
170
|
+
release line, and how to report a vulnerability
|
|
171
|
+
- [What halfORM defends, and what it cannot](https://half-orm.github.io/half-orm/latest/security-model/)
|
|
167
172
|
|
|
168
173
|
## Extensions
|
|
169
174
|
|
|
@@ -1,236 +0,0 @@
|
|
|
1
|
-
#-*- coding: utf-8 -*-
|
|
2
|
-
# pylint: disable=too-few-public-methods, protected-access
|
|
3
|
-
|
|
4
|
-
"""This module provides the Transaction class."""
|
|
5
|
-
|
|
6
|
-
import sys
|
|
7
|
-
import threading
|
|
8
|
-
|
|
9
|
-
import psycopg
|
|
10
|
-
|
|
11
|
-
class Transaction:
|
|
12
|
-
"""Context manager for atomic database operations.
|
|
13
|
-
|
|
14
|
-
Wraps one or more SQL operations in a single transaction: commits on
|
|
15
|
-
success, rolls back on exception. Transactions are per-thread and
|
|
16
|
-
per-model instance.
|
|
17
|
-
|
|
18
|
-
Nested ``with Transaction(model)`` blocks use PostgreSQL savepoints
|
|
19
|
-
automatically: an exception in an inner block rolls back only that inner
|
|
20
|
-
block, leaving the outer transaction intact.
|
|
21
|
-
|
|
22
|
-
Args:
|
|
23
|
-
model (Model): the :class:`~half_orm.model.Model` instance whose
|
|
24
|
-
connection should be used.
|
|
25
|
-
|
|
26
|
-
Example:
|
|
27
|
-
Atomic insert of two related rows:
|
|
28
|
-
```python
|
|
29
|
-
from half_orm.transaction import Transaction
|
|
30
|
-
|
|
31
|
-
with Transaction(blog):
|
|
32
|
-
alice = Author(
|
|
33
|
-
first_name='Alice', last_name='Martin',
|
|
34
|
-
email='alice@example.com',
|
|
35
|
-
).ho_insert()
|
|
36
|
-
Post(
|
|
37
|
-
title='First post', content='Hello world',
|
|
38
|
-
author_id=alice['id'],
|
|
39
|
-
).ho_insert()
|
|
40
|
-
# both rows are committed, or neither is
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Nested transactions use savepoints:
|
|
44
|
-
```python
|
|
45
|
-
with Transaction(blog):
|
|
46
|
-
alice = Author(...).ho_insert()
|
|
47
|
-
with Transaction(blog): # savepoint
|
|
48
|
-
Post(...).ho_insert()
|
|
49
|
-
# exception here rolls back only the post, not Alice
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
*New in version 0.18.0:* nested ``Transaction`` blocks use savepoints.
|
|
53
|
-
"""
|
|
54
|
-
|
|
55
|
-
__tls = threading.local()
|
|
56
|
-
|
|
57
|
-
def __call__(self, model):
|
|
58
|
-
if not hasattr(self.__class__.__tls, 'transactions'):
|
|
59
|
-
self.__class__.__tls.transactions = {}
|
|
60
|
-
transactions = self.__class__.__tls.transactions
|
|
61
|
-
self.__id = id(model)
|
|
62
|
-
self.__transaction = None
|
|
63
|
-
if self.__id not in transactions:
|
|
64
|
-
transactions[self.__id] = {
|
|
65
|
-
'level': 0, 'model': model,
|
|
66
|
-
'sp_counter': 0, 'sp_stack': [],
|
|
67
|
-
}
|
|
68
|
-
self.__transaction = transactions[self.__id]
|
|
69
|
-
|
|
70
|
-
__init__ = __call__
|
|
71
|
-
|
|
72
|
-
def __enter__(self):
|
|
73
|
-
conn = self.__transaction['model']._connection
|
|
74
|
-
if conn.autocommit:
|
|
75
|
-
conn.autocommit = False
|
|
76
|
-
if self.__transaction['level'] > 0:
|
|
77
|
-
self.__transaction['sp_counter'] += 1
|
|
78
|
-
sp_name = f'sp_{self.__transaction["sp_counter"]}'
|
|
79
|
-
self.__transaction['sp_stack'].append(sp_name)
|
|
80
|
-
with conn.cursor() as cur:
|
|
81
|
-
cur.execute(f'SAVEPOINT {sp_name}')
|
|
82
|
-
self.__transaction['level'] += 1
|
|
83
|
-
|
|
84
|
-
def __exit__(self, exc_type, exc_val, exc_tb):
|
|
85
|
-
self.__transaction['level'] -= 1
|
|
86
|
-
conn = self.__transaction['model']._connection
|
|
87
|
-
if self.__transaction['level'] > 0:
|
|
88
|
-
sp_name = self.__transaction['sp_stack'].pop()
|
|
89
|
-
with conn.cursor() as cur:
|
|
90
|
-
if exc_type is not None:
|
|
91
|
-
cur.execute(f'ROLLBACK TO SAVEPOINT {sp_name}')
|
|
92
|
-
cur.execute(f'RELEASE SAVEPOINT {sp_name}')
|
|
93
|
-
else:
|
|
94
|
-
try:
|
|
95
|
-
if exc_type is not None:
|
|
96
|
-
conn.rollback()
|
|
97
|
-
else:
|
|
98
|
-
conn.commit()
|
|
99
|
-
except psycopg.Error:
|
|
100
|
-
# A failed COMMIT must reach the caller: silently rolling back
|
|
101
|
-
# would leave the application believing its work was persisted.
|
|
102
|
-
# A failed ROLLBACK, on the other hand, must not displace the
|
|
103
|
-
# exception the caller is already handling.
|
|
104
|
-
if exc_type is None:
|
|
105
|
-
raise
|
|
106
|
-
finally:
|
|
107
|
-
_restore_autocommit(conn)
|
|
108
|
-
return False
|
|
109
|
-
|
|
110
|
-
@property
|
|
111
|
-
def level(self):
|
|
112
|
-
return self.__transaction.get('level')
|
|
113
|
-
|
|
114
|
-
def is_set(self):
|
|
115
|
-
return self.__transaction.get('level', 0) > 0
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
def _restore_autocommit(conn):
|
|
119
|
-
"""Put `conn` back in autocommit mode after the outermost block.
|
|
120
|
-
|
|
121
|
-
Best-effort: if the connection is broken, the failure is irrelevant here —
|
|
122
|
-
``Model._connection`` reconnects on the next use — and must not mask the
|
|
123
|
-
exception on its way out of ``__exit__``.
|
|
124
|
-
"""
|
|
125
|
-
try:
|
|
126
|
-
conn.autocommit = True
|
|
127
|
-
except psycopg.Error:
|
|
128
|
-
pass
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
async def _arestore_autocommit(conn):
|
|
132
|
-
"Async counterpart of :func:`_restore_autocommit`."
|
|
133
|
-
try:
|
|
134
|
-
await conn.set_autocommit(True)
|
|
135
|
-
except psycopg.Error:
|
|
136
|
-
pass
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
class AsyncTransaction:
|
|
140
|
-
"""Async context manager for atomic database operations.
|
|
141
|
-
|
|
142
|
-
Async counterpart of :class:`Transaction`: drives the model's async
|
|
143
|
-
connection (``model._aconnection``, set up via ``await
|
|
144
|
-
model.aconnect()``) instead of the sync one. Wraps one or more
|
|
145
|
-
``ho_a*`` operations in a single transaction: commits on success, rolls
|
|
146
|
-
back on exception. Transactions are tracked per-model-instance (keyed
|
|
147
|
-
by ``id(model)``) — unlike :class:`Transaction`, there is no per-thread
|
|
148
|
-
isolation, since asyncio concurrency is task-based rather than
|
|
149
|
-
thread-based and a model's async connection is only ever driven from
|
|
150
|
-
one place at a time regardless of which thread runs the event loop.
|
|
151
|
-
|
|
152
|
-
Nested ``async with AsyncTransaction(model)`` blocks use PostgreSQL
|
|
153
|
-
savepoints automatically: an exception in an inner block rolls back
|
|
154
|
-
only that inner block, leaving the outer transaction intact.
|
|
155
|
-
|
|
156
|
-
Args:
|
|
157
|
-
model (Model): the :class:`~half_orm.model.Model` instance whose
|
|
158
|
-
async connection should be used.
|
|
159
|
-
|
|
160
|
-
Example:
|
|
161
|
-
Atomic insert of two related rows:
|
|
162
|
-
```python
|
|
163
|
-
from half_orm.transaction import AsyncTransaction
|
|
164
|
-
|
|
165
|
-
async with AsyncTransaction(blog):
|
|
166
|
-
alice = await Author(
|
|
167
|
-
first_name='Alice', last_name='Martin',
|
|
168
|
-
email='alice@example.com',
|
|
169
|
-
).ho_ainsert()
|
|
170
|
-
await Post(
|
|
171
|
-
title='First post', content='Hello world',
|
|
172
|
-
author_id=alice['id'],
|
|
173
|
-
).ho_ainsert()
|
|
174
|
-
# both rows are committed, or neither is
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
*New in version 0.18.0.*
|
|
178
|
-
"""
|
|
179
|
-
|
|
180
|
-
__transactions: dict = {}
|
|
181
|
-
|
|
182
|
-
def __call__(self, model):
|
|
183
|
-
transactions = self.__class__.__transactions
|
|
184
|
-
self.__id = id(model)
|
|
185
|
-
self.__transaction = None
|
|
186
|
-
if self.__id not in transactions:
|
|
187
|
-
transactions[self.__id] = {
|
|
188
|
-
'level': 0, 'model': model,
|
|
189
|
-
'sp_counter': 0, 'sp_stack': [],
|
|
190
|
-
}
|
|
191
|
-
self.__transaction = transactions[self.__id]
|
|
192
|
-
|
|
193
|
-
__init__ = __call__
|
|
194
|
-
|
|
195
|
-
async def __aenter__(self):
|
|
196
|
-
conn = self.__transaction['model']._aconnection
|
|
197
|
-
if conn.autocommit:
|
|
198
|
-
await conn.set_autocommit(False)
|
|
199
|
-
if self.__transaction['level'] > 0:
|
|
200
|
-
self.__transaction['sp_counter'] += 1
|
|
201
|
-
sp_name = f'sp_{self.__transaction["sp_counter"]}'
|
|
202
|
-
self.__transaction['sp_stack'].append(sp_name)
|
|
203
|
-
async with conn.cursor() as cur:
|
|
204
|
-
await cur.execute(f'SAVEPOINT {sp_name}')
|
|
205
|
-
self.__transaction['level'] += 1
|
|
206
|
-
|
|
207
|
-
async def __aexit__(self, exc_type, exc_val, exc_tb):
|
|
208
|
-
self.__transaction['level'] -= 1
|
|
209
|
-
conn = self.__transaction['model']._aconnection
|
|
210
|
-
if self.__transaction['level'] > 0:
|
|
211
|
-
sp_name = self.__transaction['sp_stack'].pop()
|
|
212
|
-
async with conn.cursor() as cur:
|
|
213
|
-
if exc_type is not None:
|
|
214
|
-
await cur.execute(f'ROLLBACK TO SAVEPOINT {sp_name}')
|
|
215
|
-
await cur.execute(f'RELEASE SAVEPOINT {sp_name}')
|
|
216
|
-
else:
|
|
217
|
-
try:
|
|
218
|
-
if exc_type is not None:
|
|
219
|
-
await conn.rollback()
|
|
220
|
-
else:
|
|
221
|
-
await conn.commit()
|
|
222
|
-
except psycopg.Error:
|
|
223
|
-
# See Transaction.__exit__ for why COMMIT and ROLLBACK
|
|
224
|
-
# failures are treated differently.
|
|
225
|
-
if exc_type is None:
|
|
226
|
-
raise
|
|
227
|
-
finally:
|
|
228
|
-
await _arestore_autocommit(conn)
|
|
229
|
-
return False
|
|
230
|
-
|
|
231
|
-
@property
|
|
232
|
-
def level(self):
|
|
233
|
-
return self.__transaction.get('level')
|
|
234
|
-
|
|
235
|
-
def is_set(self):
|
|
236
|
-
return self.__transaction.get('level', 0) > 0
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
1.1.0
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|