Skip to main content

Extend pydantic models to also detect and record changes made to the model attributes.

Project description

Pydantic change detection

Installation

Just use pip install pydantic-changedetect to install the library.

Note: pydantic-changedetect is compatible with pydantic versions 1.9, 1.10 and even 2.x (🥳) on Python 3.8, 3.9, 3.10, 3.11 and 3.12. This is also ensured running all tests on all those versions using tox.

About

When working with database models it is pretty common to want to detect changes to the model attributes. The ChangeDetectionMixin just provides this mechanism to any pydantic models. Changes will be detected and stored after the model was constructed.

Using the ChangeDetectionMixin the pydantic models are extended, so:

  • obj.model_changed_fields contains a list of all changed fields
    • obj.model_self_changed_fields contains a list of all changed fields for the current object, ignoring all nested models.
    • obj.model_changed_fields_recursive contains a list of all changed fields and also include the named of the fields changed in nested models using a dotted field name syntax (like nested.field).
  • obj.model_original will include the original values of all changed fields in a dict.
  • obj.model_has_changed returns True if any field has changed.
  • obj.model_set_changed() manually sets fields as changed.
    • obj.model_set_changed("field_a", "field_b") will set multiple fields as changed.
    • obj.model_set_changed("field_a", original="old") will set a single field as changed and also store its original value.
  • obj.model_reset_changed() resets all changed fields.
  • obj.model_dump() and obj.model_dump_json() accept an additional parameter exclude_unchanged, which - when set to True - will only export the changed fields.
    Note: When using pydantic 1.x you need to use obj.dict() and obj.json(). Both also accept exclude_unchanged.
  • obj.model_restore_original() will create a new instance of the model containing its original state.
  • obj.model_get_original_field_value("field_name") will return the original value for just one field. It will call model_restore_original() on the current field value if the field is set to a ChangeDetectionMixin instance (or list/dict of those).
  • obj.model_mark_changed("marker_name") and obj.model_unmark_changed("marker_name") allow to add arbitrary change markers. An instance with a marker will be seen as changed (obj.model_has_changed == True). Markers are stored in obj.model_changed_markers as a set.

Example

import pydantic
from pydantic_changedetect import ChangeDetectionMixin

class Something(ChangeDetectionMixin, pydantic.BaseModel):
    name: str


something = Something(name="something")
something.model_has_changed  # = False
something.model_changed_fields  # = set()
something.name = "something else"
something.model_has_changed  # = True
something.model_changed_fields  # = {"name"}

original = something.model_restore_original()
original.name  # = "something"
original.model_has_changed  # = False

When will a change be detected

pydantic-changedetect will see changes when an attribute value is changes using an attribute assignment like something.name = "something else" in the example above. Such an assignment will be seen as a change unless the new value is the same and the type of the value is None or of type str, int, float, bool or decimal.Decimal.

Restrictions

ChangeDetectionMixin currently cannot detect changes inside lists, dicts and other structured objects. In those cases you are required to set the changed state yourself using model_set_changed(). It is recommended to pass the original value to model_set_changed() when you want to also keep track of the actual changes compared to the original value. Be advised to .copy() the original value as lists/dicts will always be changed in place.

import pydantic
from pydantic_changedetect import ChangeDetectionMixin

class TodoList(ChangeDetectionMixin, pydantic.BaseModel):
    items: list[str]


todos = TodoList(items=["release new version"])
original_items = todos.items.copy()
todos.items.append("create better docs")  # This change will NOT be seen yet
todos.model_has_changed  # = False
todos.model_set_changed("items", original=original_items)  # Mark field as changed and store original value
todos.model_has_changed  # = True

Changed markers

You may also just mark the model as changed. This can be done using changed markers. A change marker is just a string that is added as the marker, models with such an marker will also be seen as changed. Changed markers also allow to mark models as changed when related data was changed - for example to also update a parent object in the database when some children were changed.

import pydantic
from pydantic_changedetect import ChangeDetectionMixin

class Something(ChangeDetectionMixin, pydantic.BaseModel):
  name: str


something = Something(name="something")
something.model_has_changed  # = False
something.model_mark_changed("mood")
something.model_has_changed  # = True
something.model_changed_markers  # {"mood"}
something.model_unmark_changed("mood")  # also will be reset on something.model_reset_changed()
something.model_has_changed  # = False

Contributing

If you want to contribute to this project, feel free to just fork the project, create a dev branch in your fork and then create a pull request (PR). If you are unsure about whether your changes really suit the project please create an issue first, to talk about this.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pydantic_changedetect-0.7.3.tar.gz (11.8 kB view details)

Uploaded Source

Built Distribution

pydantic_changedetect-0.7.3-py3-none-any.whl (11.5 kB view details)

Uploaded Python 3

File details

Details for the file pydantic_changedetect-0.7.3.tar.gz.

File metadata

  • Download URL: pydantic_changedetect-0.7.3.tar.gz
  • Upload date:
  • Size: 11.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for pydantic_changedetect-0.7.3.tar.gz
Algorithm Hash digest
SHA256 dc5439ddd0492513e433836a3a62d103f15e780b2ea426e9a83bb76a0e5f1c17
MD5 610db617bde4f51ac51c88858a7365f4
BLAKE2b-256 9b0ac4a2fd643372518c87cb91b674df6606ce27f9be96775b302623b04afe7c

See more details on using hashes here.

File details

Details for the file pydantic_changedetect-0.7.3-py3-none-any.whl.

File metadata

File hashes

Hashes for pydantic_changedetect-0.7.3-py3-none-any.whl
Algorithm Hash digest
SHA256 bfa39ecbdb66148966197c78f03890e8edad0ad467aa8c054c0d0be1ebc6b14d
MD5 fa9ee2ea06cae6ae02766434b1004bb9
BLAKE2b-256 f156e91f4ece003ec36eba77b94e2ec8c82967ba8f2f20d9a97c60f694ee126f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page