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.
Files changed (42) hide show
  1. {half_orm-1.1.0/half_orm.egg-info → half_orm-1.2.0}/PKG-INFO +6 -1
  2. {half_orm-1.1.0 → half_orm-1.2.0}/README.md +5 -0
  3. half_orm-1.2.0/half_orm/_predicate.py +56 -0
  4. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/fkey.py +8 -1
  5. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/model.py +65 -1
  6. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/relation.py +139 -2
  7. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/relation_factory.py +1 -1
  8. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/testing.py +16 -35
  9. half_orm-1.2.0/half_orm/transaction.py +473 -0
  10. half_orm-1.2.0/half_orm/version.txt +1 -0
  11. {half_orm-1.1.0 → half_orm-1.2.0/half_orm.egg-info}/PKG-INFO +6 -1
  12. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/SOURCES.txt +1 -0
  13. {half_orm-1.1.0 → half_orm-1.2.0}/pyproject.toml +1 -1
  14. half_orm-1.1.0/half_orm/transaction.py +0 -236
  15. half_orm-1.1.0/half_orm/version.txt +0 -1
  16. {half_orm-1.1.0 → half_orm-1.2.0}/AUTHORS +0 -0
  17. {half_orm-1.1.0 → half_orm-1.2.0}/LICENSE +0 -0
  18. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/__init__.py +0 -0
  19. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/__main__.py +0 -0
  20. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/cli.py +0 -0
  21. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/cli_utils.py +0 -0
  22. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/field.py +0 -0
  23. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/field_errors.py +0 -0
  24. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/hotest.py +0 -0
  25. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/migrations/BREAKING_CHANGES-1.0.0.md +0 -0
  26. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/migrations/__init__.py +0 -0
  27. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/model_errors.py +0 -0
  28. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/null.py +0 -0
  29. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/pg_meta.py +0 -0
  30. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/py.typed +0 -0
  31. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/relation_errors.py +0 -0
  32. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/sql_adapter.py +0 -0
  33. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/sql_ast.py +0 -0
  34. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm/utils.py +0 -0
  35. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/dependency_links.txt +0 -0
  36. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/entry_points.txt +0 -0
  37. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/requires.txt +0 -0
  38. {half_orm-1.1.0 → half_orm-1.2.0}/half_orm.egg-info/top_level.txt +0 -0
  39. {half_orm-1.1.0 → half_orm-1.2.0}/setup.cfg +0 -0
  40. {half_orm-1.1.0 → half_orm-1.2.0}/test/test_cli.py +0 -0
  41. {half_orm-1.1.0 → half_orm-1.2.0}/test/test_main.py +0 -0
  42. {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.1.0
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': '_reverse_fkey_blog_comment_post_id',
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': '_reverse_fkey_blog_post_author_id'}
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': '_reverse_fkey_blog_post_author_id'}
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):
@@ -34,7 +34,7 @@ def register_class(relation_class):
34
34
 
35
35
  @register
36
36
  class Author(blog.get_relation_class('blog.author')):
37
- Fkeys = {'post_rfk': '_reverse_fkey_blog_post_author_id'}
37
+ Fkeys = {'post_rfk': '_reverse_fkey_blog_blog_post_author_id'}
38
38
  ```
39
39
  """
40
40
  try:
@@ -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 predicates structurally, ignoring relation aliases (``r{ho_id}``)
351
- which differ between object instances even for equivalent queries.
352
- Commutative operators (``or``, ``and``) are normalised so that
353
- ``A | B`` and ``B | A`` are considered equal; ``and not`` is not
354
- commutative and is compared as-is.
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
- c1 = _canonical(rel1.ho_where_display())
374
- c2 = _canonical(rel2.ho_where_display())
375
- if c1 != c2:
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: {c1}\n right: {c2}"
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.1.0
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
 
@@ -4,6 +4,7 @@ README.md
4
4
  pyproject.toml
5
5
  half_orm/__init__.py
6
6
  half_orm/__main__.py
7
+ half_orm/_predicate.py
7
8
  half_orm/cli.py
8
9
  half_orm/cli_utils.py
9
10
  half_orm/field.py
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta:__legacy__"
4
4
 
5
5
  [project]
6
6
  name = "half_orm"
7
- version = "1.1.0"
7
+ version = "1.2.0"
8
8
  description = "A database-first ORM for PostgreSQL"
9
9
  readme = "README.md"
10
10
  license = "GPL-3.0-or-later"
@@ -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