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

1 files changed, 86 insertions, 0 deletions

diff --git a/test/ext/mypy/plain_files/dynamic_rel.py b/test/ext/mypy/plain_files/dynamic_rel.py
new file mode 100644
index 000000000..78bf15f5f
--- /dev/null
+++ b/test/ext/mypy/plain_files/dynamic_rel.py
@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import typing
+
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm import DynamicMapped
+from sqlalchemy.orm import Mapped
+from sqlalchemy.orm import mapped_column
+from sqlalchemy.orm import relationship
+from sqlalchemy.orm import Session
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Address(Base):
+    __tablename__ = "address"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("user.id"))
+    email_address: Mapped[str]
+
+
+class User(Base):
+    __tablename__ = "user"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    addresses: DynamicMapped[Address] = relationship(
+        cascade="all,delete-orphan"
+    )
+
+
+with Session() as session:
+    u = User()
+    session.add(u)
+    session.commit()
+
+    if typing.TYPE_CHECKING:
+
+        # EXPECTED_TYPE: AppenderQuery[Address]
+        reveal_type(u.addresses)
+
+    count = u.addresses.count()
+    if typing.TYPE_CHECKING:
+
+        # EXPECTED_TYPE: int
+        reveal_type(count)
+
+    address = u.addresses.filter(Address.email_address.like("xyz")).one()
+
+    if typing.TYPE_CHECKING:
+
+        # EXPECTED_TYPE: Address
+        reveal_type(address)
+
+    u.addresses.append(Address())
+    u.addresses.extend([Address(), Address()])
+
+    current_addresses = list(u.addresses)
+
+    if typing.TYPE_CHECKING:
+
+        # EXPECTED_TYPE: list[Address]
+        reveal_type(current_addresses)
+
+    # can assign plain list
+    u.addresses = []
+
+    # or anything
+    u.addresses = set()
+
+    if typing.TYPE_CHECKING:
+        # still an AppenderQuery
+        # EXPECTED_TYPE: AppenderQuery[Address]
+        reveal_type(u.addresses)
+
+    u.addresses = set([Address(), Address()])
+
+    if typing.TYPE_CHECKING:
+        # still an AppenderQuery
+        # EXPECTED_TYPE: AppenderQuery[Address]
+        reveal_type(u.addresses)
+
+    u.addresses.append(Address())
+
+    session.commit()