r"""Return ``True`` if the given instance has locally modified attributes. This method retrieves the history for each instrumented attribute on the instance and performs a comparison of the current value to its previously flushed or committed value, if any.
(
self, instance: object, include_collections: bool = True
)
| 4932 | self._flushing = False |
| 4933 | |
| 4934 | def is_modified( |
| 4935 | self, instance: object, include_collections: bool = True |
| 4936 | ) -> bool: |
| 4937 | r"""Return ``True`` if the given instance has locally |
| 4938 | modified attributes. |
| 4939 | |
| 4940 | This method retrieves the history for each instrumented |
| 4941 | attribute on the instance and performs a comparison of the current |
| 4942 | value to its previously flushed or committed value, if any. |
| 4943 | |
| 4944 | It is in effect a more expensive and accurate |
| 4945 | version of checking for the given instance in the |
| 4946 | :attr:`.Session.dirty` collection; a full test for |
| 4947 | each attribute's net "dirty" status is performed. |
| 4948 | |
| 4949 | E.g.:: |
| 4950 | |
| 4951 | return session.is_modified(someobject) |
| 4952 | |
| 4953 | A few caveats to this method apply: |
| 4954 | |
| 4955 | * Instances present in the :attr:`.Session.dirty` collection may |
| 4956 | report ``False`` when tested with this method. This is because |
| 4957 | the object may have received change events via attribute mutation, |
| 4958 | thus placing it in :attr:`.Session.dirty`, but ultimately the state |
| 4959 | is the same as that loaded from the database, resulting in no net |
| 4960 | change here. |
| 4961 | * Scalar attributes may not have recorded the previously set |
| 4962 | value when a new value was applied, if the attribute was not loaded, |
| 4963 | or was expired, at the time the new value was received - in these |
| 4964 | cases, the attribute is assumed to have a change, even if there is |
| 4965 | ultimately no net change against its database value. SQLAlchemy in |
| 4966 | most cases does not need the "old" value when a set event occurs, so |
| 4967 | it skips the expense of a SQL call if the old value isn't present, |
| 4968 | based on the assumption that an UPDATE of the scalar value is |
| 4969 | usually needed, and in those few cases where it isn't, is less |
| 4970 | expensive on average than issuing a defensive SELECT. |
| 4971 | |
| 4972 | The "old" value is fetched unconditionally upon set only if the |
| 4973 | attribute container has the ``active_history`` flag set to ``True``. |
| 4974 | This flag is set typically for primary key attributes and scalar |
| 4975 | object references that are not a simple many-to-one. To set this |
| 4976 | flag for any arbitrary mapped column, use the ``active_history`` |
| 4977 | argument with :func:`.column_property`. |
| 4978 | |
| 4979 | :param instance: mapped instance to be tested for pending changes. |
| 4980 | :param include_collections: Indicates if multivalued collections |
| 4981 | should be included in the operation. Setting this to ``False`` is a |
| 4982 | way to detect only local-column based properties (i.e. scalar columns |
| 4983 | or many-to-one foreign keys) that would result in an UPDATE for this |
| 4984 | instance upon flush. |
| 4985 | |
| 4986 | """ |
| 4987 | state = object_state(instance) |
| 4988 | |
| 4989 | if not state.modified: |
| 4990 | return False |
| 4991 |