From 0bfaf6ef76c2c8401b51eabe0bf9282fff291438 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Thu, 19 Dec 2019 09:19:53 -0500 Subject: [PATCH] Improve documentation for refresh_flush event This event does not include INSERTed primary key columns and additionally will always be limited to default/onupdate columns. Note better choices for interception of INSERT events. Change-Id: I22b71ca1b336d4b098af075cc4694c55387b64f3 (cherry picked from commit 944fa6952157651faae53a12a92782b4265ddc8d) --- lib/sqlalchemy/orm/events.py | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index 74b075c899..d434a59909 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -340,14 +340,27 @@ class InstanceEvents(event.Events): """ def refresh_flush(self, target, flush_context, attrs): - """Receive an object instance after one or more attributes have - been refreshed within the persistence of the object. + """Receive an object instance after one or more attributes that + contain a column-level default or onupdate handler have been refreshed + during persistence of the object's state. This event is the same as :meth:`.InstanceEvents.refresh` except - it is invoked within the unit of work flush process, and the values - here typically come from the process of handling an INSERT or - UPDATE, such as via the RETURNING clause or from Python-side default - values. + it is invoked within the unit of work flush process, and includes + only non-primary-key columns that have column level default or + onupdate handlers, including Python callables as well as server side + defaults and triggers which may be fetched via the RETURNING clause. + + .. note:: + + While the :meth:`.InstanceEvents.refresh_flush` event is triggered + for an object that was INSERTed as well as for an object that was + UPDATEd, the event is geared primarily towards the UPDATE process; + it is mostly an internal artifact that INSERT actions can also + trigger this event, and note that **primary key columns for an + INSERTed row are explicitly omitted** from this event. In order to + intercept the newly INSERTed state of an object, the + :meth:`.SessionEvents.pending_to_persistent` and + :meth:`.MapperEvents.after_insert` are better choices. .. versionadded:: 1.0.5 @@ -360,6 +373,12 @@ class InstanceEvents(event.Events): :param attrs: sequence of attribute names which were populated. + .. seealso:: + + :ref:`orm_server_defaults` + + :ref:`metadata_defaults_toplevel` + """ def expire(self, target, attrs): -- 2.39.5