From: Mike Bayer Date: Thu, 5 Jan 2012 21:33:14 +0000 (-0500) Subject: - fix the index, [ticket:2366] X-Git-Tag: rel_0_7_5~65 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=adf12556476d4430b55ce3918ed32c6cebe788e3;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - 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 b8f776dd26..b1a44f56d0 100644 --- a/doc/build/templates/genindex.mako +++ b/doc/build/templates/genindex.mako @@ -23,8 +23,8 @@
% if links: - ${entryname|h} - % for link in links[1:]: + ${entryname|h} + % for unknown, link in links[1:]: , [${i}] % endfor % else: @@ -34,8 +34,8 @@ % if subitems:
% for subentryname, subentrylinks in subitems: -
${subentryname|h} - % for j, link in enumerate(subentrylinks[1:]): +
${subentryname|h} + % for j, (unknown, link) in enumerate(subentrylinks[1:]): [${j}] % endfor
diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index bb8e531092..dd948bb1aa 100644 --- 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.