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, 231 insertions, 0 deletions

diff --git a/lib/sqlalchemy/sql/_dml_constructors.py b/lib/sqlalchemy/sql/_dml_constructors.py
new file mode 100644
index 000000000..e62edf5e6
--- /dev/null
+++ b/lib/sqlalchemy/sql/_dml_constructors.py
@@ -0,0 +1,231 @@
+# sql/_dml_constructors.py
+# Copyright (C) 2005-2022 the SQLAlchemy authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: https://www.opensource.org/licenses/mit-license.php
+
+from .dml import Delete
+from .dml import Insert
+from .dml import Update
+
+
+def insert(table):
+    """Construct an :class:`_expression.Insert` object.
+
+    E.g.::
+
+        from sqlalchemy import insert
+
+        stmt = (
+            insert(user_table).
+            values(name='username', fullname='Full Username')
+        )
+
+    Similar functionality is available via the
+    :meth:`_expression.TableClause.insert` method on
+    :class:`_schema.Table`.
+
+    .. seealso::
+
+        :ref:`coretutorial_insert_expressions` - in the
+        :ref:`1.x tutorial <sqlexpression_toplevel>`
+
+        :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
+
+
+    :param table: :class:`_expression.TableClause`
+     which is the subject of the
+     insert.
+
+    :param values: collection of values to be inserted; see
+     :meth:`_expression.Insert.values`
+     for a description of allowed formats here.
+     Can be omitted entirely; a :class:`_expression.Insert` construct
+     will also dynamically render the VALUES clause at execution time
+     based on the parameters passed to :meth:`_engine.Connection.execute`.
+
+    :param inline: if True, no attempt will be made to retrieve the
+     SQL-generated default values to be provided within the statement;
+     in particular,
+     this allows SQL expressions to be rendered 'inline' within the
+     statement without the need to pre-execute them beforehand; for
+     backends that support "returning", this turns off the "implicit
+     returning" feature for the statement.
+
+    If both :paramref:`_expression.Insert.values` and compile-time bind
+    parameters are present, the compile-time bind parameters override the
+    information specified within :paramref:`_expression.Insert.values` on a
+    per-key basis.
+
+    The keys within :paramref:`_expression.Insert.values` can be either
+    :class:`~sqlalchemy.schema.Column` objects or their string
+    identifiers. Each key may reference one of:
+
+    * a literal data value (i.e. string, number, etc.);
+    * a Column object;
+    * a SELECT statement.
+
+    If a ``SELECT`` statement is specified which references this
+    ``INSERT`` statement's table, the statement will be correlated
+    against the ``INSERT`` statement.
+
+    .. seealso::
+
+        :ref:`coretutorial_insert_expressions` - SQL Expression Tutorial
+
+        :ref:`inserts_and_updates` - SQL Expression Tutorial
+
+    """
+    return Insert(table)
+
+
+def update(table):
+    r"""Construct an :class:`_expression.Update` object.
+
+    E.g.::
+
+        from sqlalchemy import update
+
+        stmt = (
+            update(user_table).
+            where(user_table.c.id == 5).
+            values(name='user #5')
+        )
+
+    Similar functionality is available via the
+    :meth:`_expression.TableClause.update` method on
+    :class:`_schema.Table`.
+
+    .. seealso::
+
+        :ref:`inserts_and_updates` - in the
+        :ref:`1.x tutorial <sqlexpression_toplevel>`
+
+        :ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
+
+
+
+    :param table: A :class:`_schema.Table`
+     object representing the database
+     table to be updated.
+
+    :param whereclause: Optional SQL expression describing the ``WHERE``
+     condition of the ``UPDATE`` statement; is equivalent to using the
+     more modern :meth:`~Update.where()` method to specify the ``WHERE``
+     clause.
+
+    :param values:
+      Optional dictionary which specifies the ``SET`` conditions of the
+      ``UPDATE``.  If left as ``None``, the ``SET``
+      conditions are determined from those parameters passed to the
+      statement during the execution and/or compilation of the
+      statement.   When compiled standalone without any parameters,
+      the ``SET`` clause generates for all columns.
+
+      Modern applications may prefer to use the generative
+      :meth:`_expression.Update.values` method to set the values of the
+      UPDATE statement.
+
+    :param inline:
+      if True, SQL defaults present on :class:`_schema.Column` objects via
+      the ``default`` keyword will be compiled 'inline' into the statement
+      and not pre-executed.  This means that their values will not
+      be available in the dictionary returned from
+      :meth:`_engine.CursorResult.last_updated_params`.
+
+    :param preserve_parameter_order: if True, the update statement is
+      expected to receive parameters **only** via the
+      :meth:`_expression.Update.values` method,
+      and they must be passed as a Python
+      ``list`` of 2-tuples. The rendered UPDATE statement will emit the SET
+      clause for each referenced column maintaining this order.
+
+      .. versionadded:: 1.0.10
+
+      .. seealso::
+
+        :ref:`updates_order_parameters` - illustrates the
+        :meth:`_expression.Update.ordered_values` method.
+
+    If both ``values`` and compile-time bind parameters are present, the
+    compile-time bind parameters override the information specified
+    within ``values`` on a per-key basis.
+
+    The keys within ``values`` can be either :class:`_schema.Column`
+    objects or their string identifiers (specifically the "key" of the
+    :class:`_schema.Column`, normally but not necessarily equivalent to
+    its "name").  Normally, the
+    :class:`_schema.Column` objects used here are expected to be
+    part of the target :class:`_schema.Table` that is the table
+    to be updated.  However when using MySQL, a multiple-table
+    UPDATE statement can refer to columns from any of
+    the tables referred to in the WHERE clause.
+
+    The values referred to in ``values`` are typically:
+
+    * a literal data value (i.e. string, number, etc.)
+    * a SQL expression, such as a related :class:`_schema.Column`,
+      a scalar-returning :func:`_expression.select` construct,
+      etc.
+
+    When combining :func:`_expression.select` constructs within the
+    values clause of an :func:`_expression.update`
+    construct, the subquery represented
+    by the :func:`_expression.select` should be *correlated* to the
+    parent table, that is, providing criterion which links the table inside
+    the subquery to the outer table being updated::
+
+        users.update().values(
+                name=select(addresses.c.email_address).\
+                        where(addresses.c.user_id==users.c.id).\
+                        scalar_subquery()
+            )
+
+    .. seealso::
+
+        :ref:`inserts_and_updates` - SQL Expression
+        Language Tutorial
+
+
+    """
+    return Update(table)
+
+
+def delete(table):
+    r"""Construct :class:`_expression.Delete` object.
+
+    E.g.::
+
+        from sqlalchemy import delete
+
+        stmt = (
+            delete(user_table).
+            where(user_table.c.id == 5)
+        )
+
+    Similar functionality is available via the
+    :meth:`_expression.TableClause.delete` method on
+    :class:`_schema.Table`.
+
+    .. seealso::
+
+        :ref:`inserts_and_updates` - in the
+        :ref:`1.x tutorial <sqlexpression_toplevel>`
+
+        :ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
+
+
+    :param table: The table to delete rows from.
+
+    :param whereclause: Optional SQL expression describing the ``WHERE``
+     condition of the ``DELETE`` statement; is equivalent to using the
+     more modern :meth:`~Delete.where()` method to specify the ``WHERE``
+     clause.
+
+    .. seealso::
+
+        :ref:`deletes` - SQL Expression Tutorial
+
+    """
+    return Delete(table)