Remove all remaining removed_in_20 warnings slated for removal

Finalize all remaining removed-in-2.0 changes so that we
can begin doing pep-484 typing without old things
getting in the way (we will also have to do public_factory).

note there are a few "moved_in_20()" and "became_legacy_in_20()"
warnings still in place.  The SQLALCHEMY_WARN_20 variable
is now removed.

Also removed here are the legacy "in place mutators" for Select
statements, and some keyword-only argument signatures in Core
have been added.

Also in the big change department, the ORM mapper() function
is removed entirely; the Mapper class is otherwise unchanged,
just the public-facing API function.  Mappers are now always
given a registry in which to participate, however the
argument signature of Mapper is not changed. ideally "registry"
would be the first positional argument.

Fixes: #7257

Change-Id: Ic70c57b9f1cf7eb996338af5183b11bdeb3e1623

1 files changed, 30 insertions, 18 deletions

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index a66bf64d8..03e3796a6 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -152,8 +152,8 @@ class InstanceEvents(event.Events):
     * unmapped superclasses of mapped or to-be-mapped classes
       (using the ``propagate=True`` flag)
     * :class:`_orm.Mapper` objects
-    * the :class:`_orm.Mapper` class itself and the :func:`.mapper`
-      function indicate listening for all mappers.
+    * the :class:`_orm.Mapper` class itself indicates listening for all
+      mappers.
 
     Instance events are closely related to mapper events, but
     are more specific to the instance and its instrumentation,
@@ -200,6 +200,12 @@ class InstanceEvents(event.Events):
         elif isinstance(target, mapperlib.Mapper):
             return target.class_manager
         elif target is orm.mapper:
+            util.warn_deprecated(
+                "The `sqlalchemy.orm.mapper()` symbol is deprecated and "
+                "will be removed in a future release. For the mapper-wide "
+                "event target, use the 'sqlalchemy.orm.Mapper' class.",
+                "2.0",
+            )
             return instrumentation.ClassManager
         elif isinstance(target, type):
             if issubclass(target, mapperlib.Mapper):
@@ -638,8 +644,8 @@ class MapperEvents(event.Events):
     * unmapped superclasses of mapped or to-be-mapped classes
       (using the ``propagate=True`` flag)
     * :class:`_orm.Mapper` objects
-    * the :class:`_orm.Mapper` class itself and the :func:`.mapper`
-      function indicate listening for all mappers.
+    * the :class:`_orm.Mapper` class itself indicates listening for all
+      mappers.
 
     Mapper events provide hooks into critical sections of the
     mapper, including those related to object instrumentation,
@@ -692,6 +698,12 @@ class MapperEvents(event.Events):
         orm = util.preloaded.orm
 
         if target is orm.mapper:
+            util.warn_deprecated(
+                "The `sqlalchemy.orm.mapper()` symbol is deprecated and "
+                "will be removed in a future release. For the mapper-wide "
+                "event target, use the 'sqlalchemy.orm.Mapper' class.",
+                "2.0",
+            )
             return mapperlib.Mapper
         elif isinstance(target, type):
             if issubclass(target, mapperlib.Mapper):
@@ -721,7 +733,7 @@ class MapperEvents(event.Events):
         ):
             util.warn(
                 "'before_configured' and 'after_configured' ORM events "
-                "only invoke with the mapper() function or Mapper class "
+                "only invoke with the Mapper class "
                 "as the target."
             )
 
@@ -896,13 +908,13 @@ class MapperEvents(event.Events):
         new mappers have been made available and new mapper use is
         detected.
 
-        This event can **only** be applied to the :class:`_orm.Mapper` class
-        or :func:`.mapper` function, and not to individual mappings or
-        mapped classes.  It is only invoked for all mappings as a whole::
+        This event can **only** be applied to the :class:`_orm.Mapper` class,
+        and not to individual mappings or mapped classes. It is only invoked
+        for all mappings as a whole::
 
-            from sqlalchemy.orm import mapper
+            from sqlalchemy.orm import Mapper
 
-            @event.listens_for(mapper, "before_configured")
+            @event.listens_for(Mapper, "before_configured")
             def go():
                 # ...
 
@@ -959,13 +971,13 @@ class MapperEvents(event.Events):
         Also contrast to :meth:`.MapperEvents.before_configured`,
         which is invoked before the series of mappers has been configured.
 
-        This event can **only** be applied to the :class:`_orm.Mapper` class
-        or :func:`.mapper` function, and not to individual mappings or
+        This event can **only** be applied to the :class:`_orm.Mapper` class,
+        and not to individual mappings or
         mapped classes.  It is only invoked for all mappings as a whole::
 
-            from sqlalchemy.orm import mapper
+            from sqlalchemy.orm import Mapper
 
-            @event.listens_for(mapper, "after_configured")
+            @event.listens_for(Mapper, "after_configured")
             def go():
                 # ...
 
@@ -1005,7 +1017,7 @@ class MapperEvents(event.Events):
         The event is often called for a batch of objects of the
         same class before their INSERT statements are emitted at
         once in a later step. In the extremely rare case that
-        this is not desirable, the :func:`.mapper` can be
+        this is not desirable, the :class:`_orm.Mapper` object can be
         configured with ``batch=False``, which will cause
         batches of instances to be broken up into individual
         (and more poorly performing) event->persist->event
@@ -1052,7 +1064,7 @@ class MapperEvents(event.Events):
         same class after their INSERT statements have been
         emitted at once in a previous step. In the extremely
         rare case that this is not desirable, the
-        :func:`.mapper` can be configured with ``batch=False``,
+        :class:`_orm.Mapper` object can be configured with ``batch=False``,
         which will cause batches of instances to be broken up
         into individual (and more poorly performing)
         event->persist->event steps.
@@ -1116,7 +1128,7 @@ class MapperEvents(event.Events):
         The event is often called for a batch of objects of the
         same class before their UPDATE statements are emitted at
         once in a later step. In the extremely rare case that
-        this is not desirable, the :func:`.mapper` can be
+        this is not desirable, the :class:`_orm.Mapper` can be
         configured with ``batch=False``, which will cause
         batches of instances to be broken up into individual
         (and more poorly performing) event->persist->event
@@ -1180,7 +1192,7 @@ class MapperEvents(event.Events):
         The event is often called for a batch of objects of the
         same class after their UPDATE statements have been emitted at
         once in a previous step. In the extremely rare case that
-        this is not desirable, the :func:`.mapper` can be
+        this is not desirable, the :class:`_orm.Mapper` can be
         configured with ``batch=False``, which will cause
         batches of instances to be broken up into individual
         (and more poorly performing) event->persist->event