pep-484: ORM public API, constructors

for the moment, abandoning using @overload with
relationship() and mapped_column().  The overloads
are very difficult to get working at all, and
the overloads that were there all wouldn't pass on
mypy.  various techniques of getting them to
"work", meaning having right hand side dictate
what's legal on the left, have mixed success
and wont give consistent results; additionally,
it's legal to have Optional / non-optional
independent of nullable in any case for columns.
relationship cases are less ambiguous but mypy
was not going along with things.

we have a comprehensive system of allowing
left side annotations to drive the right side,
in the absense of explicit settings on the right.
so type-centric SQLAlchemy will be left-side
driven just like dataclasses, and the various flags
and switches on the right side will just not be
needed very much.

in other matters, one surprise, forgot to remove string support
from orm.join(A, B, "somename") or do deprecations
for it in 1.4.   This is a really not-directly-used
structure barely
mentioned in the docs for many years, the example
shows a relationship being used, not a string, so
we will just change it to raise the usual error here.

Change-Id: Iefbbb8d34548b538023890ab8b7c9a5d9496ec6e

1 files changed, 15 insertions, 17 deletions

diff --git a/test/ext/mypy/plain_files/mapped_column.py b/test/ext/mypy/plain_files/mapped_column.py
index b20beeb3a..14f4ad845 100644
--- a/test/ext/mypy/plain_files/mapped_column.py
+++ b/test/ext/mypy/plain_files/mapped_column.py
@@ -14,68 +14,67 @@ class Base(DeclarativeBase):
 class X(Base):
     __tablename__ = "x"
 
+    # these are fine - pk, column is not null, have the attribute be
+    # non-optional, fine
     id: Mapped[int] = mapped_column(primary_key=True)
     int_id: Mapped[int] = mapped_column(Integer, primary_key=True)
 
-    # EXPECTED_MYPY: No overload variant of "mapped_column" matches argument types
+    # but this is also "fine" because the developer may wish to have the object
+    # in a pending state with None for the id for some period of time.
+    # "primary_key=True" will still be interpreted correctly in DDL
     err_int_id: Mapped[Optional[int]] = mapped_column(
         Integer, primary_key=True
     )
 
-    id_name: Mapped[int] = mapped_column("id_name", primary_key=True)
-    int_id_name: Mapped[int] = mapped_column(
-        "int_id_name", Integer, primary_key=True
-    )
-
-    # EXPECTED_MYPY: No overload variant of "mapped_column" matches argument types
+    # also fine, X(err_int_id_name) is None when you first make the
+    # object
     err_int_id_name: Mapped[Optional[int]] = mapped_column(
         "err_int_id_name", Integer, primary_key=True
     )
 
-    # note we arent getting into primary_key=True / nullable=True here.
-    # leaving that as undefined for now
+    id_name: Mapped[int] = mapped_column("id_name", primary_key=True)
+    int_id_name: Mapped[int] = mapped_column(
+        "int_id_name", Integer, primary_key=True
+    )
 
     a: Mapped[str] = mapped_column()
     b: Mapped[Optional[str]] = mapped_column()
 
-    # can't detect error because no SQL type is present
+    # this can't be detected because we don't know the type
     c: Mapped[str] = mapped_column(nullable=True)
     d: Mapped[str] = mapped_column(nullable=False)
 
     e: Mapped[Optional[str]] = mapped_column(nullable=True)
 
-    # can't detect error because no SQL type is present
     f: Mapped[Optional[str]] = mapped_column(nullable=False)
 
     g: Mapped[str] = mapped_column(String)
     h: Mapped[Optional[str]] = mapped_column(String)
 
-    # EXPECTED_MYPY: No overload variant of "mapped_column" matches argument types
+    # this probably is wrong.  however at the moment it seems better to
+    # decouple the right hand arguments from declaring things about the
+    # left side since it mostly doesn't work in any case.
     i: Mapped[str] = mapped_column(String, nullable=True)
 
     j: Mapped[str] = mapped_column(String, nullable=False)
 
     k: Mapped[Optional[str]] = mapped_column(String, nullable=True)
 
-    # EXPECTED_MYPY_RE: Argument \d to "mapped_column" has incompatible type
     l: Mapped[Optional[str]] = mapped_column(String, nullable=False)
 
     a_name: Mapped[str] = mapped_column("a_name")
     b_name: Mapped[Optional[str]] = mapped_column("b_name")
 
-    # can't detect error because no SQL type is present
     c_name: Mapped[str] = mapped_column("c_name", nullable=True)
     d_name: Mapped[str] = mapped_column("d_name", nullable=False)
 
     e_name: Mapped[Optional[str]] = mapped_column("e_name", nullable=True)
 
-    # can't detect error because no SQL type is present
     f_name: Mapped[Optional[str]] = mapped_column("f_name", nullable=False)
 
     g_name: Mapped[str] = mapped_column("g_name", String)
     h_name: Mapped[Optional[str]] = mapped_column("h_name", String)
 
-    # EXPECTED_MYPY: No overload variant of "mapped_column" matches argument types
     i_name: Mapped[str] = mapped_column("i_name", String, nullable=True)
 
     j_name: Mapped[str] = mapped_column("j_name", String, nullable=False)
@@ -86,7 +85,6 @@ class X(Base):
 
     l_name: Mapped[Optional[str]] = mapped_column(
         "l_name",
-        # EXPECTED_MYPY_RE: Argument \d to "mapped_column" has incompatible type
         String,
         nullable=False,
     )