implement write-only colletions, typing for dynamic

For 2.0, we provide a truly "larger than memory collection"
implementation, a write-only collection that will never
under any circumstances implicitly load the entire
collection, even during flush.

This is essentially a much more "strict" version
of the "dynamic" loader, which in fact has a lot of
scenarios that it loads the full backing collection
into memory, mostly defeating its purpose.

Typing constructs are added that support
both the new feature WriteOnlyMapping as well as the
legacy feature DynamicMapping.  These have been
integrated with "annotion based mapping" so that
relationship() uses these annotations to configure
the loader strategy as well.

additional changes:

* the docs triggered a conflict in hybrid's
  "transformers" section, this section is hard-coded
  to Query using a pattern that doesnt seem to have
  any use and isn't part of the current select()
  interface, so just removed this section

* As the docs for WriteOnlyMapping are very long,
  collections.rst is broken up into two pages now.

Fixes: #6229
Fixes: #7123
Change-Id: I6929f3da6e441cad92285e7309030a9bac4e429d

2 files changed, 9 insertions, 0 deletions

diff --git a/lib/sqlalchemy/testing/assertsql.py b/lib/sqlalchemy/testing/assertsql.py
index b3a71dbff..2fda1e9cb 100644
--- a/lib/sqlalchemy/testing/assertsql.py
+++ b/lib/sqlalchemy/testing/assertsql.py
@@ -371,6 +371,10 @@ class EachOf(AssertRule):
         self.rules = list(rules)
 
     def process_statement(self, execute_observed):
+        if not self.rules:
+            self.is_consumed = True
+            self.consume_statement = False
+
         while self.rules:
             rule = self.rules[0]
             rule.process_statement(execute_observed)
diff --git a/lib/sqlalchemy/testing/entities.py b/lib/sqlalchemy/testing/entities.py
index cf3138835..15352c8c8 100644
--- a/lib/sqlalchemy/testing/entities.py
+++ b/lib/sqlalchemy/testing/entities.py
@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import sqlalchemy as sa
 from .. import exc as sa_exc
+from ..orm.writeonly import WriteOnlyCollection
 
 _repr_stack = set()
 
@@ -82,8 +83,12 @@ class ComparableMixin:
             for attr in list(a.__dict__):
                 if attr.startswith("_"):
                     continue
+
                 value = getattr(a, attr)
 
+                if isinstance(value, WriteOnlyCollection):
+                    continue
+
                 try:
                     # handle lazy loader errors
                     battr = getattr(b, attr)