Using the changelog

This tutorial will guide you through inspecting the history of a media object using the changelog in tator-py. We assume you already have a project with media in it.

Get the changelogs for a media object

We will use project id 2 and media id 19 for this example. Start by setting up imports we will need later and the api:

import tator
from tator.openapi.tator_openapi import ChangeLogDescriptionOfChangeNew
api = tator.get_api(host="https://cloud.tator.io", token="YOUR_TOKEN")
change_log_list = api.get_change_log_list(2, entity_id=19)

Let's take a look at the first entry in the list:

{'description_of_change': {'new': [{'name': '_id', 'value': 19},
                                   {'name': '_project', 'value': 3},
                                   {'name': '_meta', 'value': 4},
                                   {'name': '_created_by', 'value': 1},
                                   {'name': '_modified_by', 'value': 1},
                                   {'name': '_version', 'value': 3},
                                   {'name': '_modified', 'value': True},
                                   {'name': '_segments', 'value': {}},
                                   {'name': '_deleted', 'value': False},
                                   {'name': 'test_bool', 'value': False},
                                   {'name': 'test_string',
                                    'value': '7fd713b6-e67f-11ec-a768-9f268ffc924d'}],
                           'old': [{'name': '_id', 'value': None},
                                   {'name': '_project', 'value': None},
                                   {'name': '_meta', 'value': None},
                                   {'name': '_created_by', 'value': None},
                                   {'name': '_modified_by', 'value': None},
                                   {'name': '_version', 'value': None},
                                   {'name': '_modified', 'value': None},
                                   {'name': '_segments', 'value': None},
                                   {'name': '_deleted', 'value': None},
                                   {'name': 'test_bool', 'value': None},
                                   {'name': 'test_string', 'value': None}]},
 'id': 111,
 'modified_datetime': datetime.datetime(2022, 6, 7, 16, 33, 15, 672000, tzinfo=tzutc()),
 'project': 3,
 'user': 1}

The description_of_change field is where we'll focus, which is made of two parts: the old values that where changed when this changelog was created and the new values that replaced them. They are both lists of ChangeLogDescriptionOfChangeNew objects, which is important for filtering this list to find change events.

For other options to filter the list of changelogs, see the API documentation.

Filter the changelogs to find when values changed

It is possible to filter the list of changelogs to find when an attribute's value changed from a known value or when it changed to a known value.

For example, if we want to find the first time the value of the test_string attribute was changed from 7fd713b6-e67f-11ec-a768-9f268ffc924d to something else, we would do the following:

# Create the object that represents the desired attribute name and value
old_change = ChangeLogDescriptionOfChangeNew(name="test_string", value="7fd713b6-e67f-11ec-a768-9f268ffc924d")
# Check to see if the desired old value is in the list of old changes for each changelog, return the
# first one found or None
cl = next((cl for cl in change_log_list if old_change in cl.description_of_change.old), None)

And here's the changelog it identified:

{'description_of_change': {'new': [{'name': 'test_bool', 'value': True},
                                   {'name': 'test_string',
                                    'value': 'f67ef0cc-e67f-11ec-a768-9f268ffc924d'}],
                           'old': [{'name': 'test_bool', 'value': False},
                                   {'name': 'test_string', ### here is the value we wanted ###
                                    'value': '7fd713b6-e67f-11ec-a768-9f268ffc924d'}]},
 'id': 5329,
 'modified_datetime': datetime.datetime(2022, 6, 7, 16, 36, 22, 185000, tzinfo=tzutc()),
 'project': 3,
 'user': 1}

And if we want to find the first time an attribute changed to a know value, we could do the following:

# Create the object that represents the desired attribute name and value
new_change = ChangeLogDescriptionOfChangeNew(name="test_bool", value=True)
# Check to see if the desired new value is in the list of new changes for each changelog, return the
# first one found or None
cl = next((cl for cl in change_log_list if new_change in cl.description_of_change.new), None)

And here's the changelog it identified:

{'description_of_change': {'new': [{'name': 'test_bool', 'value': True}, # here is the value we wanted
                                   {'name': 'test_string',
                                    'value': 'f67ef0cc-e67f-11ec-a768-9f268ffc924d'}],
                           'old': [{'name': 'test_bool', 'value': False},
                                   {'name': 'test_string',
                                    'value': '7fd713b6-e67f-11ec-a768-9f268ffc924d'}]},
 'id': 5329,
 'modified_datetime': datetime.datetime(2022, 6, 7, 16, 36, 22, 185000, tzinfo=tzutc()),
 'project': 3,
 'user': 1}