more abstractconcretebase clarity

Change-Id: I9ddb6b1a2e0c0be1fe355a7ea714d0e16aa93b47

1 files changed, 23 insertions, 22 deletions

diff --git a/lib/sqlalchemy/ext/declarative/extensions.py b/lib/sqlalchemy/ext/declarative/extensions.py
index 87fc702cf..29eb76e82 100644
--- a/lib/sqlalchemy/ext/declarative/extensions.py
+++ b/lib/sqlalchemy/ext/declarative/extensions.py
@@ -134,8 +134,8 @@ class AbstractConcreteBase(ConcreteBase):
 
     .. note::
 
-        The :class:`.AbstractConcreteBase` class does not intend to set up  the
-        mapping for the base class until all the subclasses have been defined,
+        The :class:`.AbstractConcreteBase` delays the mapper creation of the
+        base class until all the subclasses have been defined,
         as it needs to create a mapping against a selectable that will include
         all subclass tables.  In order to achieve this, it waits for the
         **mapper configuration event** to occur, at which point it scans
@@ -145,23 +145,22 @@ class AbstractConcreteBase(ConcreteBase):
         While this event is normally invoked automatically, in the case of
         :class:`.AbstractConcreteBase`, it may be necessary to invoke it
         explicitly after **all** subclass mappings are defined, if the first
-        operation is to be a query against this base class.  To do so, invoke
-        :func:`.configure_mappers` once all the desired classes have been
-        configured::
-
-            from sqlalchemy.orm import configure_mappers
-
-            configure_mappers()
-
-        .. seealso::
-
-            :func:`_orm.configure_mappers`
+        operation is to be a query against this base class. To do so, once all
+        the desired classes have been configured, the
+        :meth:`_orm.registry.configure` method on the :class:`_orm.registry`
+        in use can be invoked, which is available in relation to a particular
+        declarative base class::
 
+            Base.registry.configure()
 
     Example::
 
+        from sqlalchemy.orm import DeclarativeBase
         from sqlalchemy.ext.declarative import AbstractConcreteBase
 
+        class Base(DeclarativeBase):
+            pass
+
         class Employee(AbstractConcreteBase, Base):
             pass
 
@@ -173,9 +172,10 @@ class AbstractConcreteBase(ConcreteBase):
 
             __mapper_args__ = {
                 'polymorphic_identity':'manager',
-                'concrete':True}
+                'concrete':True
+            }
 
-        configure_mappers()
+        Base.registry.configure()
 
     The abstract base class is handled by declarative in a special way;
     at class configuration time, it behaves like a declarative mixin
@@ -211,18 +211,17 @@ class AbstractConcreteBase(ConcreteBase):
 
             __mapper_args__ = {
                 'polymorphic_identity':'manager',
-                'concrete':True}
+                'concrete':True
+            }
 
-        configure_mappers()
+        Base.registry.configure()
 
     When we make use of our mappings however, both ``Manager`` and
     ``Employee`` will have an independently usable ``.company`` attribute::
 
-        session.query(Employee).filter(Employee.company.has(id=5))
-
-    .. versionchanged:: 1.0.0 - The mechanics of :class:`.AbstractConcreteBase`
-       have been reworked to support relationships established directly
-       on the abstract base, without any special configurational steps.
+        session.execute(
+            select(Employee).filter(Employee.company.has(id=5))
+        )
 
     .. seealso::
 
@@ -230,6 +229,8 @@ class AbstractConcreteBase(ConcreteBase):
 
         :ref:`concrete_inheritance`
 
+        :ref:`abstract_concrete_base`
+
     """
 
     __no_table__ = True