- mark translate_row, create_instance, populate_instance, append_result as legacy

2 files changed, 25 insertions, 3 deletions

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 996e04edb..e64cb8c92 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -472,9 +472,7 @@ class MapperEvents(event.Events):
          processing normally.
        * ``sqlalchemy.orm.interfaces.EXT_STOP`` - cancel all subsequent
          event handlers in the chain.
-       * other values - the return value specified by specific listeners,
-         such as :meth:`~.MapperEvents.translate_row` or
-         :meth:`~.MapperEvents.create_instance`.
+       * other values - the return value specified by specific listeners.
 
     """
 
@@ -663,6 +661,13 @@ class MapperEvents(event.Events):
         """Perform pre-processing on the given result row and return a
         new row instance.
 
+        .. deprecated:: 0.9 the :meth:`.translate_row` event should
+           be considered as legacy.  The row as delivered in a mapper
+           load operation typically requires that highly technical
+           details be accommodated in order to identity the correct
+           column keys are present in the row, rendering this particular
+           event hook as difficult to use and unreliable.
+
         This listener is typically registered with ``retval=True``.
         It is called when the mapper first receives a row, before
         the object identity or the instance itself has been derived
@@ -691,6 +696,10 @@ class MapperEvents(event.Events):
         """Receive a row when a new object instance is about to be
         created from that row.
 
+        .. deprecated:: 0.9 the :meth:`.create_instance` event should
+           be considered as legacy.  Manipulation of the object construction
+           mechanics during a load should not be necessary.
+
         The method can choose to create the instance itself, or it can return
         EXT_CONTINUE to indicate normal object creation should take place.
         This listener is typically registered with ``retval=True``.
@@ -716,6 +725,11 @@ class MapperEvents(event.Events):
         """Receive an object instance before that instance is appended
         to a result list.
 
+        .. deprecated:: 0.9 the :meth:`.append_result` event should
+           be considered as legacy.  It is a difficult to use method
+           whose original purpose is better suited by custom collection
+           classes.
+
         This is a rarely used hook which can be used to alter
         the construction of a result list returned by :class:`.Query`.
 
@@ -748,6 +762,11 @@ class MapperEvents(event.Events):
         """Receive an instance before that instance has
         its attributes populated.
 
+        .. deprecated:: 0.9 the :meth:`.populate_instance` event should
+           be considered as legacy.  The mechanics of instance population
+           should not need modification; special "on load" rules can as always
+           be accommodated by the :class:`.InstanceEvents.load` event.
+
         This usually corresponds to a newly loaded instance but may
         also correspond to an already-loaded instance which has
         unloaded attributes to be populated.  The method may be called
diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py
index 7ea54d4cd..1fe924d96 100644
--- a/lib/sqlalchemy/orm/loading.py
+++ b/lib/sqlalchemy/orm/loading.py
@@ -312,10 +312,13 @@ def instance_processor(mapper, context, path, adapter,
 
     listeners = mapper.dispatch
 
+    ### legacy events - I'd very much like to yank these totally
     translate_row = listeners.translate_row or None
     create_instance = listeners.create_instance or None
     populate_instance = listeners.populate_instance or None
     append_result = listeners.append_result or None
+    ####
+
     populate_existing = context.populate_existing or mapper.always_refresh
     invoke_all_eagers = context.invoke_all_eagers
     load_evt = mapper.class_manager.dispatch.load or None