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
)
| 4768 | self._flushing = False |
| 4769 | |
| 4770 | def is_modified( |
| 4771 | self, instance: object, include_collections: bool = True |
| 4772 | ) -> bool: |
| 4773 | r"""Return ``True`` if the given instance has locally |
| 4774 | modified attributes. |
| 4775 | |
| 4776 | This method retrieves the history for each instrumented |
| 4777 | attribute on the instance and performs a comparison of the current |
| 4778 | value to its previously flushed or committed value, if any. |
| 4779 | |
| 4780 | It is in effect a more expensive and accurate |
| 4781 | version of checking for the given instance in the |
| 4782 | :attr:`.Session.dirty` collection; a full test for |
| 4783 | each attribute's net "dirty" status is performed. |
| 4784 | |
| 4785 | E.g.:: |
| 4786 | |
| 4787 | return session.is_modified(someobject) |
| 4788 | |
| 4789 | A few caveats to this method apply: |
| 4790 | |
| 4791 | * Instances present in the :attr:`.Session.dirty` collection may |
| 4792 | report ``False`` when tested with this method. This is because |
| 4793 | the object may have received change events via attribute mutation, |
| 4794 | thus placing it in :attr:`.Session.dirty`, but ultimately the state |
| 4795 | is the same as that loaded from the database, resulting in no net |
| 4796 | change here. |
| 4797 | * Scalar attributes may not have recorded the previously set |
| 4798 | value when a new value was applied, if the attribute was not loaded, |
| 4799 | or was expired, at the time the new value was received - in these |
| 4800 | cases, the attribute is assumed to have a change, even if there is |
| 4801 | ultimately no net change against its database value. SQLAlchemy in |
| 4802 | most cases does not need the "old" value when a set event occurs, so |
| 4803 | it skips the expense of a SQL call if the old value isn't present, |
| 4804 | based on the assumption that an UPDATE of the scalar value is |
| 4805 | usually needed, and in those few cases where it isn't, is less |
| 4806 | expensive on average than issuing a defensive SELECT. |
| 4807 | |
| 4808 | The "old" value is fetched unconditionally upon set only if the |
| 4809 | attribute container has the ``active_history`` flag set to ``True``. |
| 4810 | This flag is set typically for primary key attributes and scalar |
| 4811 | object references that are not a simple many-to-one. To set this |
| 4812 | flag for any arbitrary mapped column, use the ``active_history`` |
| 4813 | argument with :func:`.column_property`. |
| 4814 | |
| 4815 | :param instance: mapped instance to be tested for pending changes. |
| 4816 | :param include_collections: Indicates if multivalued collections |
| 4817 | should be included in the operation. Setting this to ``False`` is a |
| 4818 | way to detect only local-column based properties (i.e. scalar columns |
| 4819 | or many-to-one foreign keys) that would result in an UPDATE for this |
| 4820 | instance upon flush. |
| 4821 | |
| 4822 | """ |
| 4823 | state = object_state(instance) |
| 4824 | |
| 4825 | if not state.modified: |
| 4826 | return False |
| 4827 |