initial reorganize for static typing

start applying foundational annotations to key
elements.

two main elements addressed here:

1. removal of public_factory() and replacement with
   explicit functions.  this just works much better with
   typing.

2. typing support for column expressions and operators.
   The biggest part of this involves stubbing out all the
   ColumnOperators methods under ColumnElement in a
   TYPE_CHECKING section.  Took me a while to see this
   method vs. much more complicated things I thought
   I needed.

Also for this version implementing #7519, ColumnElement
types against the Python type and not TypeEngine.  it is
hoped this leads to easier transferrence between ORM/Core
as well as eventual support for result set typing.
Not clear yet how well this approach will work and what
new issues it may introduce.

given the current approach we now get full, rich typing for
scenarios like this:

from sqlalchemy import column, Integer, String, Boolean

c1 = column('a', String)

c2 = column('a', Integer)

expr1 = c2.in_([1, 2, 3])

expr2 = c2 / 5

expr3 = -c2

expr4_a = ~(c2 == 5)

expr4_b = ~column('q', Boolean)

expr5 = c1 + 'x'

expr6 = c2 + 10

Fixes: #7519
Fixes: #6810
Change-Id: I078d9f57955549f6f7868314287175f6c61c44cb

1 files changed, 21 insertions, 6 deletions

diff --git a/lib/sqlalchemy/dialects/postgresql/dml.py b/lib/sqlalchemy/dialects/postgresql/dml.py
index 48b180e81..09dbd9558 100644
--- a/lib/sqlalchemy/dialects/postgresql/dml.py
+++ b/lib/sqlalchemy/dialects/postgresql/dml.py
@@ -17,11 +17,31 @@ from ...sql.base import ColumnCollection
 from ...sql.dml import Insert as StandardInsert
 from ...sql.elements import ClauseElement
 from ...sql.expression import alias
-from ...util.langhelpers import public_factory
 
 
 __all__ = ("Insert", "insert")
 
+
+def insert(table):
+    """Construct a PostgreSQL-specific variant :class:`_postgresql.Insert`
+    construct.
+
+    .. container:: inherited_member
+
+        The :func:`sqlalchemy.dialects.postgresql.insert` function creates
+        a :class:`sqlalchemy.dialects.postgresql.Insert`.  This class is based
+        on the dialect-agnostic :class:`_sql.Insert` construct which may
+        be constructed using the :func:`_sql.insert` function in
+        SQLAlchemy Core.
+
+    The :class:`_postgresql.Insert` construct includes additional methods
+    :meth:`_postgresql.Insert.on_conflict_do_update`,
+    :meth:`_postgresql.Insert.on_conflict_do_nothing`.
+
+    """
+    return Insert(table)
+
+
 SelfInsert = typing.TypeVar("SelfInsert", bound="Insert")
 
 
@@ -183,11 +203,6 @@ class Insert(StandardInsert):
         return self
 
 
-insert = public_factory(
-    Insert, ".dialects.postgresql.insert", ".dialects.postgresql.Insert"
-)
-
-
 class OnConflictClause(ClauseElement):
     stringify_dialect = "postgresql"