Mike Bayer avatar Mike Bayer committed b2c40e2

update query.update(), query.delete(), sessionevents.after_bulk_update(), sessionevents.after_bulk_delete() docstirngs, [ticket:2324]

Comments (0)

Files changed (2)

lib/sqlalchemy/orm/events.py

     def before_flush( self, session, flush_context, instances):
         """Execute before flush process has started.
 
-        `instances` is an optional list of objects which were passed to
-        the ``flush()`` method. 
-        
         :param session: The target :class:`.Session`.
         :param flush_context: Internal :class:`.UOWTransaction` object
          which handles the details of the flush.
     def after_begin( self, session, transaction, connection):
         """Execute after a transaction is begun on a connection
 
-        `transaction` is the SessionTransaction. This method is called
-        after an engine level transaction is begun on a connection. 
-        
         :param session: The target :class:`.Session`.
         :param transaction: The :class:`.SessionTransaction`.
         :param connection: The :class:`~.engine.base.Connection` object 
     def after_bulk_update( self, session, query, query_context, result):
         """Execute after a bulk update operation to the session.
 
-        This is called after a session.query(...).update()
+        This is called as a result of the :meth:`.Query.update` method.
 
-        `query` is the query object that this update operation was
-        called on. `query_context` was the query context object.
-        `result` is the result object returned from the bulk operation.
+        :param query: the :class:`.Query` object that this update operation was
+         called upon. 
+        :param query_context: The :class:`.QueryContext` object, corresponding
+         to the invocation of an ORM query.
+        :param result: the :class:`.ResultProxy` returned as a result of the
+         bulk UPDATE operation.
+
         """
 
     def after_bulk_delete( self, session, query, query_context, result):
         """Execute after a bulk delete operation to the session.
 
-        This is called after a session.query(...).delete()
+        This is called as a result of the :meth:`.Query.delete` method.
 
-        `query` is the query object that this delete operation was
-        called on. `query_context` was the query context object.
-        `result` is the result object returned from the bulk operation.
+        :param query: the :class:`.Query` object that this update operation was
+         called upon. 
+        :param query_context: The :class:`.QueryContext` object, corresponding
+         to the invocation of an ORM query.
+        :param result: the :class:`.ResultProxy` returned as a result of the
+         bulk DELETE operation.
+
         """
 
 

lib/sqlalchemy/orm/query.py

         :param synchronize_session: chooses the strategy for the removal of
             matched objects from the session. Valid values are:
 
-            False - don't synchronize the session. This option is the most
+            ``False`` - don't synchronize the session. This option is the most
             efficient and is reliable once the session is expired, which
             typically occurs after a commit(), or explicitly using
             expire_all(). Before the expiration, objects may still remain in
             results if they are accessed via get() or already loaded
             collections.
 
-            'fetch' - performs a select query before the delete to find
+            ``'fetch'`` - performs a select query before the delete to find
             objects that are matched by the delete query and need to be
             removed from the session. Matched objects are removed from the
             session.
 
-            'evaluate' - Evaluate the query's criteria in Python straight on
+            ``'evaluate'`` - Evaluate the query's criteria in Python straight on
             the objects in the session. If evaluation of the criteria isn't
             implemented, an error is raised.  In that case you probably 
             want to use the 'fetch' strategy as a fallback.
         state of dependent objects subject to delete or delete-orphan cascade
         to be correctly represented.
 
-        Also, the ``before_delete()`` and ``after_delete()``
-        :class:`~sqlalchemy.orm.interfaces.MapperExtension` methods are not
-        called from this method. For a delete hook here, use the
-        :meth:`.SessionExtension.after_bulk_delete()` event hook.
+        Note that the :meth:`.MapperEvents.before_delete` and 
+        :meth:`.MapperEvents.after_delete`
+        events are **not** invoked from this method.  It instead
+        invokes :meth:`.SessionEvents.after_bulk_delete`.
 
         """
         #TODO: lots of duplication and ifs - probably needs to be 
         :param synchronize_session: chooses the strategy to update the
             attributes on objects in the session. Valid values are:
 
-            False - don't synchronize the session. This option is the most
+            ``False`` - don't synchronize the session. This option is the most
             efficient and is reliable once the session is expired, which
             typically occurs after a commit(), or explicitly using
             expire_all(). Before the expiration, updated objects may still
             remain in the session with stale values on their attributes, which
             can lead to confusing results.
 
-            'fetch' - performs a select query before the update to find
+            ``'fetch'`` - performs a select query before the update to find
             objects that are matched by the update query. The updated
             attributes are expired on matched objects.
 
-            'evaluate' - Evaluate the Query's criteria in Python straight on
+            ``'evaluate'`` - Evaluate the Query's criteria in Python straight on
             the objects in the session. If evaluation of the criteria isn't
             implemented, an exception is raised.
 
         or call expire_all()) in order for the state of dependent objects
         subject foreign key cascade to be correctly represented.
 
-        Also, the ``before_update()`` and ``after_update()``
-        :class:`~sqlalchemy.orm.interfaces.MapperExtension` methods are not
-        called from this method. For an update hook here, use the
-        :meth:`.SessionExtension.after_bulk_update()` event hook.
+        Note that the :meth:`.MapperEvents.before_update` and 
+        :meth:`.MapperEvents.after_update`
+        events are **not** invoked from this method.  It instead
+        invokes :meth:`.SessionEvents.after_bulk_update`.
 
         """
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.