- fix the index, [ticket:2366]

- the most explicit warning ever about mapper events

diff --git a/doc/build/templates/genindex.mako b/doc/build/templates/genindex.mako
index b8f776dd260277ad81f20fafc9ed7c75d4fcac62..b1a44f56d0224e78097590e618cf2e21ebdd48cc 100644 (file)
--- a/doc/build/templates/genindex.mako
+++ b/doc/build/templates/genindex.mako
@@ -23,8 +23,8 @@
 
 <dt>
     % if links:
-        <a href="${links[0]}">${entryname|h}</a>
-        % for link in links[1:]:
+        <a href="${links[0][1]}">${entryname|h}</a>
+        % for unknown, link in links[1:]:
             , <a href="${link}">[${i}]</a>
         % endfor
     % else:
@@ -34,8 +34,8 @@
     % if subitems:
   <dd><dl>
     % for subentryname, subentrylinks in subitems:
-    <dt><a href="${subentrylinks[0]}">${subentryname|h}</a>
-            % for j, link in enumerate(subentrylinks[1:]):
+    <dt><a href="${subentrylinks[0][1]}">${subentryname|h}</a>
+            % for j, (unknown, link) in enumerate(subentrylinks[1:]):
                 <a href="${link}">[${j}]</a>
             % endfor
     </dt>

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index bb8e531092a001b8c62e0011787af12c6f2351e5..dd948bb1aa98521d608d9f5da333e885701804c6 100644 (file)
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -550,13 +550,29 @@ class MapperEvents(event.Events):
         (and more poorly performing) event->persist->event
         steps.
 
-        Handlers should **not** modify any attributes which are
-        mapped by :func:`.relationship`, nor should they attempt
-        to make any modifications to the :class:`.Session` in
-        this hook (including :meth:`.Session.add`, 
-        :meth:`.Session.delete`, etc.) - such changes will not
-        take effect. For overall changes to the "flush plan",
-        use :meth:`.SessionEvents.before_flush`.
+        .. warning::
+            Mapper-level flush events are designed to operate **on attributes
+            local to the immediate object being handled  
+            and via SQL operations with the given** :class:`.Connection` **only.**
+            Handlers here should **not** make alterations to the state of 
+            the :class:`.Session` overall, and in general should not
+            affect any :func:`.relationship` -mapped attributes, as 
+            session cascade rules will not function properly, nor is it
+            always known if the related class has already been handled.  
+            Operations that **are not supported in mapper events** include:
+        
+            * :meth:`.Session.add`
+            * :meth:`.Session.delete`
+            * Mapped collection append, add, remove, delete, discard, etc.
+            * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject``
+        
+            Operations which manipulate the state of the object
+            relative to other objects are better handled:
+        
+            * In the ``__init__()`` method of the mapped object itself, or another method
+              designed to establish some particular state.
+            * In a ``@validates`` handler, see :ref:`simple_validators`
+            * Within the  :meth:`.SessionEvents.before_flush` event.
 
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
@@ -590,14 +606,30 @@ class MapperEvents(event.Events):
         into individual (and more poorly performing)
         event->persist->event steps.
 
-        Handlers should **not** alter mapped attributes on the objects
-        just flushed or on other objects of the same class, nor
-        should any other ORM-based operation such as :class:`.Session.add`
-        take place here.   Attribute changes on objects that were
-        already flushed will be discarded, and changes to the flush
-        plan will also not take place.  Use :meth:`.SessionEvents.before_flush`
-        to change the flush plan on flush.
+        .. warning::
+            Mapper-level flush events are designed to operate **on attributes
+            local to the immediate object being handled  
+            and via SQL operations with the given** :class:`.Connection` **only.**
+            Handlers here should **not** make alterations to the state of 
+            the :class:`.Session` overall, and in general should not
+            affect any :func:`.relationship` -mapped attributes, as 
+            session cascade rules will not function properly, nor is it
+            always known if the related class has already been handled.  
+            Operations that **are not supported in mapper events** include:
+        
+            * :meth:`.Session.add`
+            * :meth:`.Session.delete`
+            * Mapped collection append, add, remove, delete, discard, etc.
+            * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject``
+        
+            Operations which manipulate the state of the object
+            relative to other objects are better handled:
         
+            * In the ``__init__()`` method of the mapped object itself, or another method
+              designed to establish some particular state.
+            * In a ``@validates`` handler, see :ref:`simple_validators`
+            * Within the  :meth:`.SessionEvents.before_flush` event.
+
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
         :param connection: the :class:`.Connection` being used to 
@@ -649,13 +681,29 @@ class MapperEvents(event.Events):
         (and more poorly performing) event->persist->event
         steps.
 
-        Handlers should **not** modify any attributes which are
-        mapped by :func:`.relationship`, nor should they attempt
-        to make any modifications to the :class:`.Session` in
-        this hook (including :meth:`.Session.add`, 
-        :meth:`.Session.delete`, etc.) - such changes will not
-        take effect. For overall changes to the "flush plan",
-        use :meth:`.SessionEvents.before_flush`.
+        .. warning::
+            Mapper-level flush events are designed to operate **on attributes
+            local to the immediate object being handled  
+            and via SQL operations with the given** :class:`.Connection` **only.**
+            Handlers here should **not** make alterations to the state of 
+            the :class:`.Session` overall, and in general should not
+            affect any :func:`.relationship` -mapped attributes, as 
+            session cascade rules will not function properly, nor is it
+            always known if the related class has already been handled.  
+            Operations that **are not supported in mapper events** include:
+        
+            * :meth:`.Session.add`
+            * :meth:`.Session.delete`
+            * Mapped collection append, add, remove, delete, discard, etc.
+            * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject``
+        
+            Operations which manipulate the state of the object
+            relative to other objects are better handled:
+        
+            * In the ``__init__()`` method of the mapped object itself, or another method
+              designed to establish some particular state.
+            * In a ``@validates`` handler, see :ref:`simple_validators`
+            * Within the  :meth:`.SessionEvents.before_flush` event.
 
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
@@ -706,13 +754,29 @@ class MapperEvents(event.Events):
         (and more poorly performing) event->persist->event
         steps.
 
-        Handlers should **not** alter mapped attributes on the objects
-        just flushed or on other objects of the same class, nor
-        should any other ORM-based operation such as :class:`.Session.add`
-        take place here.   Attribute changes on objects that were
-        already flushed will be discarded, and changes to the flush
-        plan will also not take place.  Use :meth:`.SessionEvents.before_flush`
-        to change the flush plan on flush.
+        .. warning::
+            Mapper-level flush events are designed to operate **on attributes
+            local to the immediate object being handled  
+            and via SQL operations with the given** :class:`.Connection` **only.**
+            Handlers here should **not** make alterations to the state of 
+            the :class:`.Session` overall, and in general should not
+            affect any :func:`.relationship` -mapped attributes, as 
+            session cascade rules will not function properly, nor is it
+            always known if the related class has already been handled.  
+            Operations that **are not supported in mapper events** include:
+        
+            * :meth:`.Session.add`
+            * :meth:`.Session.delete`
+            * Mapped collection append, add, remove, delete, discard, etc.
+            * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject``
+        
+            Operations which manipulate the state of the object
+            relative to other objects are better handled:
+        
+            * In the ``__init__()`` method of the mapped object itself, or another method
+              designed to establish some particular state.
+            * In a ``@validates`` handler, see :ref:`simple_validators`
+            * Within the  :meth:`.SessionEvents.before_flush` event.
 
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
@@ -740,13 +804,29 @@ class MapperEvents(event.Events):
         same class before their DELETE statements are emitted at
         once in a later step. 
 
-        Handlers should **not** modify any attributes which are
-        mapped by :func:`.relationship`, nor should they attempt
-        to make any modifications to the :class:`.Session` in
-        this hook (including :meth:`.Session.add`, 
-        :meth:`.Session.delete`, etc.) - such changes will not
-        take effect. For overall changes to the "flush plan",
-        use :meth:`.SessionEvents.before_flush`.
+        .. warning::
+            Mapper-level flush events are designed to operate **on attributes
+            local to the immediate object being handled  
+            and via SQL operations with the given** :class:`.Connection` **only.**
+            Handlers here should **not** make alterations to the state of 
+            the :class:`.Session` overall, and in general should not
+            affect any :func:`.relationship` -mapped attributes, as 
+            session cascade rules will not function properly, nor is it
+            always known if the related class has already been handled.  
+            Operations that **are not supported in mapper events** include:
+        
+            * :meth:`.Session.add`
+            * :meth:`.Session.delete`
+            * Mapped collection append, add, remove, delete, discard, etc.
+            * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject``
+        
+            Operations which manipulate the state of the object
+            relative to other objects are better handled:
+        
+            * In the ``__init__()`` method of the mapped object itself, or another method
+              designed to establish some particular state.
+            * In a ``@validates`` handler, see :ref:`simple_validators`
+            * Within the  :meth:`.SessionEvents.before_flush` event.
 
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
@@ -774,13 +854,29 @@ class MapperEvents(event.Events):
         same class after their DELETE statements have been emitted at
         once in a previous step. 
 
-        Handlers should **not** alter mapped attributes on the objects
-        just flushed or on other objects of the same class, nor
-        should any other ORM-based operation such as :class:`.Session.add`
-        take place here.   Attribute changes on objects that were
-        already flushed will be discarded, and changes to the flush
-        plan will also not take place.  Use :meth:`.SessionEvents.before_flush`
-        to change the flush plan on flush.
+        .. warning::
+            Mapper-level flush events are designed to operate **on attributes
+            local to the immediate object being handled  
+            and via SQL operations with the given** :class:`.Connection` **only.**
+            Handlers here should **not** make alterations to the state of 
+            the :class:`.Session` overall, and in general should not
+            affect any :func:`.relationship` -mapped attributes, as 
+            session cascade rules will not function properly, nor is it
+            always known if the related class has already been handled.  
+            Operations that **are not supported in mapper events** include:
+        
+            * :meth:`.Session.add`
+            * :meth:`.Session.delete`
+            * Mapped collection append, add, remove, delete, discard, etc.
+            * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject``
+        
+            Operations which manipulate the state of the object
+            relative to other objects are better handled:
+        
+            * In the ``__init__()`` method of the mapped object itself, or another method
+              designed to establish some particular state.
+            * In a ``@validates`` handler, see :ref:`simple_validators`
+            * Within the  :meth:`.SessionEvents.before_flush` event.
 
         :param mapper: the :class:`.Mapper` which is the target
          of this event.