- re-document and fully cross link all of configure_mappers(),

mapper_configured(), after_configured(), and before_configured().

2 files changed, 111 insertions, 20 deletions

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 224c9c4dd..6d4aa039b 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -652,32 +652,67 @@ class MapperEvents(event.Events):
         """
 
     def mapper_configured(self, mapper, class_):
-        """Called when the mapper for the class is fully configured.
-
-        This event is the latest phase of mapper construction, and
-        is invoked when the mapped classes are first used, so that
-        relationships between mappers can be resolved.   When the event is
-        called, the mapper should be in its final state.
-
-        While the configuration event normally occurs automatically,
-        it can be forced to occur ahead of time, in the case where the event
-        is needed before any actual mapper usage,  by using the
-        :func:`.configure_mappers` function.
+        """Called when a specific mapper has completed its own configuration
+        within the scope of the :func:`.configure_mappers` call.
+
+        The :meth:`.MapperEvents.mapper_configured` event is invoked
+        for each mapper that is encountered when the
+        :func:`.orm.configure_mappers` function proceeds through the current
+        list of not-yet-configured mappers.
+        :func:`.orm.configure_mappers` is typically invoked
+        automatically as mappings are first used, as well as each time
+        new mappers have been made available and new mapper use is
+        detected.
+
+        When the event is called, the mapper should be in its final
+        state, but **not including backrefs** that may be invoked from
+        other mappers; they might still be pending within the
+        configuration operation.    Bidirectional relationships that
+        are instead configured via the
+        :paramref:`.orm.relationship.back_populates` argument
+        *will* be fully available, since this style of relationship does not
+        rely upon other possibly-not-configured mappers to know that they
+        exist.
 
+        For an event that is guaranteed to have **all** mappers ready
+        to go including backrefs that are defined only on other
+        mappings, use the :meth:`.MapperEvents.after_configured`
+        event; this event invokes only after all known mappings have been
+        fully configured.
+
+        The :meth:`.MapperEvents.mapper_configured` event, unlike
+        :meth:`.MapperEvents.before_configured` or
+        :meth:`.MapperEvents.after_configured`,
+        is called for each mapper/class individually, and the mapper is
+        passed to the event itself.  It also is called exactly once for
+        a particular mapper.  The event is therefore useful for
+        configurational steps that benefit from being invoked just once
+        on a specific mapper basis, which don't require that "backref"
+        configurations are necessarily ready yet.
 
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
         :param class\_: the mapped class.
 
+        .. seealso::
+
+            :meth:`.MapperEvents.before_configured`
+
+            :meth:`.MapperEvents.after_configured`
+
         """
         # TODO: need coverage for this event
 
     def before_configured(self):
         """Called before a series of mappers have been configured.
 
-        This corresponds to the :func:`.orm.configure_mappers` call, which
-        note is usually called automatically as mappings are first
-        used.
+        The :meth:`.MapperEvents.before_configured` event is invoked
+        each time the :func:`.orm.configure_mappers` function is
+        invoked, before the function has done any of its work.
+        :func:`.orm.configure_mappers` is typically invoked
+        automatically as mappings are first used, as well as each time
+        new mappers have been made available and new mapper use is
+        detected.
 
         This event can **only** be applied to the :class:`.Mapper` class
         or :func:`.mapper` function, and not to individual mappings or
@@ -689,11 +724,16 @@ class MapperEvents(event.Events):
             def go():
                 # ...
 
+        Constrast this event to :meth:`.MapperEvents.after_configured`,
+        which is invoked after the series of mappers has been configured,
+        as well as :meth:`.MapperEvents.mapper_configured`, which is invoked
+        on a per-mapper basis as each one is configured to the extent possible.
+
         Theoretically this event is called once per
         application, but is actually called any time new mappers
         are to be affected by a :func:`.orm.configure_mappers`
         call.   If new mappings are constructed after existing ones have
-        already been used, this event can be called again.  To ensure
+        already been used, this event will likely be called again.  To ensure
         that a particular event is only called once and no further, the
         ``once=True`` argument (new in 0.9.4) can be applied::
 
@@ -706,14 +746,33 @@ class MapperEvents(event.Events):
 
         .. versionadded:: 0.9.3
 
+
+        .. seealso::
+
+            :meth:`.MapperEvents.mapper_configured`
+
+            :meth:`.MapperEvents.after_configured`
+
         """
 
     def after_configured(self):
         """Called after a series of mappers have been configured.
 
-        This corresponds to the :func:`.orm.configure_mappers` call, which
-        note is usually called automatically as mappings are first
-        used.
+        The :meth:`.MapperEvents.after_configured` event is invoked
+        each time the :func:`.orm.configure_mappers` function is
+        invoked, after the function has completed its work.
+        :func:`.orm.configure_mappers` is typically invoked
+        automatically as mappings are first used, as well as each time
+        new mappers have been made available and new mapper use is
+        detected.
+
+        Contrast this event to the :meth:`.MapperEvents.mapper_configured`
+        event, which is called on a per-mapper basis while the configuration
+        operation proceeds; unlike that event, when this event is invoked,
+        all cross-configurations (e.g. backrefs) will also have been made
+        available for any mappers that were pending.
+        Also constrast 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:`.Mapper` class
         or :func:`.mapper` function, and not to individual mappings or
@@ -729,7 +788,7 @@ class MapperEvents(event.Events):
         application, but is actually called any time new mappers
         have been affected by a :func:`.orm.configure_mappers`
         call.   If new mappings are constructed after existing ones have
-        already been used, this event can be called again.  To ensure
+        already been used, this event will likely be called again.  To ensure
         that a particular event is only called once and no further, the
         ``once=True`` argument (new in 0.9.4) can be applied::
 
@@ -739,6 +798,12 @@ class MapperEvents(event.Events):
             def go():
                 # ...
 
+        .. seealso::
+
+            :meth:`.MapperEvents.mapper_configured`
+
+            :meth:`.MapperEvents.before_configured`
+
         """
 
     def before_insert(self, mapper, connection, target):
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 3efaa45ac..1a46667c5 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -2696,7 +2696,33 @@ def configure_mappers():
     have been constructed thus far.
 
     This function can be called any number of times, but in
-    most cases is handled internally.
+    most cases is invoked automatically, the first time mappings are used,
+    as well as whenever mappings are used and additional not-yet-configured
+    mappers have been constructed.
+
+    Points at which this occur include when a mapped class is instantiated
+    into an instance, as well as when the :meth:`.Session.query` method
+    is used.
+
+    The :func:`.configure_mappers` function provides several event hooks
+    that can be used to augment its functionality.  These methods include:
+
+    * :meth:`.MapperEvents.before_configured` - called once before
+      :func:`.configure_mappers` does any work; this can be used to establish
+      additional options, properties, or related mappings before the operation
+      proceeds.
+
+    * :meth:`.MapperEvents.mapper_configured` - called as each indivudal
+      :class:`.Mapper` is configured within the process; will include all
+      mapper state except for backrefs set up by other mappers that are still
+      to be configured.
+
+    * :meth:`.MapperEvents.after_configured` - called once after
+      :func:`.configure_mappers` is complete; at this stage, all
+      :class:`.Mapper` objects that are known  to SQLAlchemy will be fully
+      configured.  Note that the calling application may still have other
+      mappings that haven't been produced yet, such as if they are in modules
+      as yet unimported.
 
     """