:doc:`/index`

Basics
======


Importing
    >>> from deepdiff import DeepDiff
    >>> from pprint import pprint

Same object returns empty
    >>> t1 = {1:1, 2:2, 3:3}
    >>> t2 = t1
    >>> print(DeepDiff(t1, t2))
    {}

Type of an item has changed
    >>> t1 = {1:1, 2:2, 3:3}
    >>> t2 = {1:1, 2:"2", 3:3}
    >>> pprint(DeepDiff(t1, t2), indent=2)
    { 'type_changes': { 'root[2]': { 'new_type': <class 'str'>,
                                     'new_value': '2',
                                     'old_type': <class 'int'>,
                                     'old_value': 2}}}

Value of an item has changed
    >>> t1 = {1:1, 2:2, 3:3}
    >>> t2 = {1:1, 2:4, 3:3}
    >>> pprint(DeepDiff(t1, t2, verbose_level=0), indent=2)
    {'values_changed': {'root[2]': {'new_value': 4, 'old_value': 2}}}

Item added and/or removed
    >>> t1 = {1:1, 3:3, 4:4}
    >>> t2 = {1:1, 3:3, 5:5, 6:6}
    >>> ddiff = DeepDiff(t1, t2)
    >>> pprint (ddiff)
    {'dictionary_item_added': [root[5], root[6]],
     'dictionary_item_removed': [root[4]]}

Set verbose level to 2 in order to see the added or removed items with their values
    >>> t1 = {1:1, 3:3, 4:4}
    >>> t2 = {1:1, 3:3, 5:5, 6:6}
    >>> ddiff = DeepDiff(t1, t2, verbose_level=2)
    >>> pprint(ddiff, indent=2)
    { 'dictionary_item_added': {'root[5]': 5, 'root[6]': 6},
      'dictionary_item_removed': {'root[4]': 4}}

Set verbose level to 2 includes new_path when the path has changed for a report between t1 and t2:
    >>> t1 = [1, 3]
    >>> t2 = [3, 2]
    >>>
    >>>
    >>> diff = DeepDiff(t1, t2, ignore_order=True, verbose_level=2)
    >>> pprint(diff)
    {'values_changed': {'root[0]': {'new_path': 'root[1]',
                                    'new_value': 2,
                                    'old_value': 1}}}

String difference
    >>> t1 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":"world"}}
    >>> t2 = {1:1, 2:4, 3:3, 4:{"a":"hello", "b":"world!"}}
    >>> ddiff = DeepDiff(t1, t2)
    >>> pprint (ddiff, indent = 2)
    { 'values_changed': { 'root[2]': {'new_value': 4, 'old_value': 2},
                          "root[4]['b']": { 'new_value': 'world!',
                                            'old_value': 'world'}}}


String difference 2
    >>> t1 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":"world!\nGoodbye!\n1\n2\nEnd"}}
    >>> t2 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":"world\n1\n2\nEnd"}}
    >>> ddiff = DeepDiff(t1, t2)
    >>> pprint (ddiff, indent = 2)
    { 'values_changed': { "root[4]['b']": { 'diff': '--- \n'
                                                    '+++ \n'
                                                    '@@ -1,5 +1,4 @@\n'
                                                    '-world!\n'
                                                    '-Goodbye!\n'
                                                    '+world\n'
                                                    ' 1\n'
                                                    ' 2\n'
                                                    ' End',
                                            'new_value': 'world\n1\n2\nEnd',
                                            'old_value': 'world!\n'
                                                         'Goodbye!\n'
                                                         '1\n'
                                                         '2\n'
                                                         'End'}}}

    >>>
    >>> print (ddiff['values_changed']["root[4]['b']"]["diff"])
    ---
    +++
    @@ -1,5 +1,4 @@
    -world!
    -Goodbye!
    +world
     1
     2
     End

List difference
    >>> t1 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 2, 3, 4]}}
    >>> t2 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 2]}}
    >>> ddiff = DeepDiff(t1, t2)
    >>> pprint (ddiff, indent = 2)
    {'iterable_item_removed': {"root[4]['b'][2]": 3, "root[4]['b'][3]": 4}}

List that contains dictionary:
    >>> t1 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 2, {1:1, 2:2}]}}
    >>> t2 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 2, {1:3}]}}
    >>> ddiff = DeepDiff(t1, t2)
    >>> pprint (ddiff, indent = 2)
    { 'dictionary_item_removed': [root[4]['b'][2][2]],
      'values_changed': {"root[4]['b'][2][1]": {'new_value': 3, 'old_value': 1}}}

Sets:
    >>> t1 = {1, 2, 8}
    >>> t2 = {1, 2, 3, 5}
    >>> ddiff = DeepDiff(t1, t2)
    >>> pprint(ddiff)
    {'set_item_added': [root[3], root[5]], 'set_item_removed': [root[8]]}

Named Tuples:
    >>> from collections import namedtuple
    >>> Point = namedtuple('Point', ['x', 'y'])
    >>> t1 = Point(x=11, y=22)
    >>> t2 = Point(x=11, y=23)
    >>> pprint (DeepDiff(t1, t2))
    {'values_changed': {'root.y': {'new_value': 23, 'old_value': 22}}}

Custom objects:
    >>> class ClassA(object):
    ...     a = 1
    ...     def __init__(self, b):
    ...         self.b = b
    ...
    >>> t1 = ClassA(1)
    >>> t2 = ClassA(2)
    >>>
    >>> pprint(DeepDiff(t1, t2))
    {'values_changed': {'root.b': {'new_value': 2, 'old_value': 1}}}

Object attribute added:
    >>> t2.c = "new attribute"
    >>> pprint(DeepDiff(t1, t2))
    {'attribute_added': [root.c],
     'values_changed': {'root.b': {'new_value': 2, 'old_value': 1}}}


Datetime
    DeepDiff converts all datetimes into UTC. If a datetime is timezone naive, we assume it is in UTC too.
    That is different than what Python does. Python assumes your timezone naive datetime is in your local timezone.
    >>> from deepdiff import DeepDiff
    >>> from datetime import datetime, timezone
    >>> d1 = datetime(2020, 8, 31, 13, 14, 1)
    >>> d2 = datetime(2020, 8, 31, 13, 14, 1, tzinfo=timezone.utc)
    >>> d1 == d2
    False
    >>> DeepDiff(d1, d2)
    {}


.. note::
    All the examples above use the default :ref:`text_view_label`.
    If you want traversing functionality in the results, use the :ref:`tree_view_label`.
    You just need to set view='tree' to get it in tree form.


.. _group_by_label:

Group By
--------

group_by can be used when dealing with the list of dictionaries. It converts them from lists to a single dictionary with the key defined by group_by. The common use case is when reading data from a flat CSV, and the primary key is one of the columns in the CSV. We want to use the primary key instead of the CSV row number to group the rows. The group_by can do 2D group_by by passing a list of 2 keys. It is also possible to have a callable group_by, which can be used to access keys in more nested data structures.

For example:
    >>> [
    ...     {'id': 'AA', 'name': 'Joe', 'last_name': 'Nobody'},
    ...     {'id': 'BB', 'name': 'James', 'last_name': 'Blue'},
    ...     {'id': 'CC', 'name': 'Mike', 'last_name': 'Apple'},
    ... ]

Becomes:
    >>> t1 = {
    ...     'AA': {'name': 'Joe', 'last_name': 'Nobody'},
    ...     'BB': {'name': 'James', 'last_name': 'Blue'},
    ...     'CC': {'name': 'Mike', 'last_name': 'Apple'},
    ... }


With that in mind, let's take a look at the following:
    >>> from deepdiff import DeepDiff
    >>> t1 = [
    ...     {'id': 'AA', 'name': 'Joe', 'last_name': 'Nobody'},
    ...     {'id': 'BB', 'name': 'James', 'last_name': 'Blue'},
    ...     {'id': 'CC', 'name': 'Mike', 'last_name': 'Apple'},
    ... ]
    >>>
    >>> t2 = [
    ...     {'id': 'AA', 'name': 'Joe', 'last_name': 'Nobody'},
    ...     {'id': 'BB', 'name': 'James', 'last_name': 'Brown'},
    ...     {'id': 'CC', 'name': 'Mike', 'last_name': 'Apple'},
    ... ]
    >>>
    >>> DeepDiff(t1, t2)
    {'values_changed': {"root[1]['last_name']": {'new_value': 'Brown', 'old_value': 'Blue'}}}


Now we use group_by='id':
    >>> DeepDiff(t1, t2, group_by='id')
    {'values_changed': {"root['BB']['last_name']": {'new_value': 'Brown', 'old_value': 'Blue'}}}

.. note::
    group_by actually changes the structure of the t1 and t2. You can see this by using the tree view:

    >>> diff = DeepDiff(t1, t2, group_by='id', view='tree')
    >>> diff
    {'values_changed': [<root['BB']['last_name'] t1:'Blue', t2:'Brown'>]}
    >>> diff['values_changed'][0]
    <root['BB']['last_name'] t1:'Blue', t2:'Brown'>
    >>> diff['values_changed'][0].up
    <root['BB'] t1:{'name': 'Ja...}, t2:{'name': 'Ja...}>
    >>> diff['values_changed'][0].up.up
    <root t1:{'AA': {'nam...}, t2:{'AA': {'nam...}>
    >>> diff['values_changed'][0].up.up.t1
    {'AA': {'name': 'Joe', 'last_name': 'Nobody'}, 'BB': {'name': 'James', 'last_name': 'Blue'}, 'CC': {'name': 'Mike', 'last_name': 'Apple'}}

2D Example:
    >>> from pprint import pprint
    >>> from deepdiff import DeepDiff
    >>>
    >>> t1 = [
    ...     {'id': 'AA', 'name': 'Joe', 'last_name': 'Nobody'},
    ...     {'id': 'BB', 'name': 'James', 'last_name': 'Blue'},
    ...     {'id': 'BB', 'name': 'Jimmy', 'last_name': 'Red'},
    ...     {'id': 'CC', 'name': 'Mike', 'last_name': 'Apple'},
    ... ]
    >>>
    >>> t2 = [
    ...     {'id': 'AA', 'name': 'Joe', 'last_name': 'Nobody'},
    ...     {'id': 'BB', 'name': 'James', 'last_name': 'Brown'},
    ...     {'id': 'CC', 'name': 'Mike', 'last_name': 'Apple'},
    ... ]
    >>>
    >>> diff = DeepDiff(t1, t2, group_by=['id', 'name'])
    >>> pprint(diff)
    {'dictionary_item_removed': [root['BB']['Jimmy']],
     'values_changed': {"root['BB']['James']['last_name']": {'new_value': 'Brown',
                                                             'old_value': 'Blue'}}}

Callable group_by Example:
    >>> from deepdiff import DeepDiff
    >>>
    >>> t1 = [
    ...     {'id': 'AA', 'demographics': {'names': {'first': 'Joe', 'middle': 'John', 'last': 'Nobody'}}},
    ...     {'id': 'BB', 'demographics': {'names': {'first': 'James', 'middle': 'Joyce', 'last': 'Blue'}}},
    ...     {'id': 'CC', 'demographics': {'names': {'first': 'Mike', 'middle': 'Mark', 'last': 'Apple'}}},
    ... ]
    >>>
    >>> t2 = [
    ...     {'id': 'AA', 'demographics': {'names': {'first': 'Joe', 'middle': 'John', 'last': 'Nobody'}}},
    ...     {'id': 'BB', 'demographics': {'names': {'first': 'James', 'middle': 'Joyce', 'last': 'Brown'}}},
    ...     {'id': 'CC', 'demographics': {'names': {'first': 'Mike', 'middle': 'Charles', 'last': 'Apple'}}},
    ... ]
    >>>
    >>> diff = DeepDiff(t1, t2, group_by=lambda x: x['demographics']['names']['first'])
    >>> pprint(diff)
    {'values_changed': {"root['James']['demographics']['names']['last']": {'new_value': 'Brown',
                                                                           'old_value': 'Blue'},
                        "root['Mike']['demographics']['names']['middle']": {'new_value': 'Charles',
                                                                            'old_value': 'Mark'}}}

.. _group_by_sort_key_label:

Group By - Sort Key
-------------------

group_by_sort_key is used to define how dictionaries are sorted if multiple ones fall under one group. When this parameter is used, group_by converts the lists of dictionaries into a dictionary of keys to lists of dictionaries. Then, group_by_sort_key is used to sort between the list.

For example, there are duplicate id values. If we only use group_by='id', one of the dictionaries with id of 'BB' will overwrite the other. However, if we also set group_by_sort_key='name', we keep both dictionaries with the id of 'BB'.

Example:
    >>> [{'id': 'AA', 'int_id': 2, 'last_name': 'Nobody', 'name': 'Joe'},
    ...  {'id': 'BB', 'int_id': 20, 'last_name': 'Blue', 'name': 'James'},
    ...  {'id': 'BB', 'int_id': 3, 'last_name': 'Red', 'name': 'Jimmy'},
    ...  {'id': 'CC', 'int_id': 4, 'last_name': 'Apple', 'name': 'Mike'}]


Becomes:
    >>> {'AA': [{'int_id': 2, 'last_name': 'Nobody', 'name': 'Joe'}],
    ...  'BB': [{'int_id': 20, 'last_name': 'Blue', 'name': 'James'},
    ...         {'int_id': 3, 'last_name': 'Red', 'name': 'Jimmy'}],
    ...  'CC': [{'int_id': 4, 'last_name': 'Apple', 'name': 'Mike'}]}


Example of using group_by_sort_key
    >>> t1 = [
    ...     {'id': 'AA', 'name': 'Joe', 'last_name': 'Nobody', 'int_id': 2},
    ...     {'id': 'BB', 'name': 'James', 'last_name': 'Blue', 'int_id': 20},
    ...     {'id': 'BB', 'name': 'Jimmy', 'last_name': 'Red', 'int_id': 3},
    ...     {'id': 'CC', 'name': 'Mike', 'last_name': 'Apple', 'int_id': 4},
    ... ]
    >>>
    >>> t2 = [
    ...     {'id': 'AA', 'name': 'Joe', 'last_name': 'Nobody', 'int_id': 2},
    ...     {'id': 'BB', 'name': 'James', 'last_name': 'Brown', 'int_id': 20},
    ...     {'id': 'CC', 'name': 'Mike', 'last_name': 'Apple', 'int_id': 4},
    ... ]
    >>>
    >>> diff = DeepDiff(t1, t2, group_by='id', group_by_sort_key='name')
    >>>
    >>> pprint(diff)
    {'iterable_item_removed': {"root['BB'][1]": {'int_id': 3,
                                                 'last_name': 'Red',
                                                 'name': 'Jimmy'}},
     'values_changed': {"root['BB'][0]['last_name']": {'new_value': 'Brown',
                                                       'old_value': 'Blue'}}}


.. _default_timezone_label:

Default Time Zone
-----------------

default_timezone defines the default timezone. If a datetime is timezone naive, which means it doesn't have a timezone, we assume the datetime is in this timezone. Also any datetime that has a timezone will be converted to this timezone so the datetimes can be compared properly all in the same timezone. Note that Python's default behavior assumes the default timezone is your local timezone. DeepDiff's default is UTC, not your local time zone.


Note that if we change the default_timezone, the output timezone changes accordingly
    >>> from deepdiff import DeepDiff
    >>> import pytz
    >>> from datetime import date, datetime, time, timezone
    >>> dt_utc = datetime(2025, 2, 3, 12, 0, 0, tzinfo=pytz.utc)  # UTC timezone
    >>> dt_utc2 = datetime(2025, 2, 3, 11, 0, 0, tzinfo=pytz.utc)  # UTC timezone
    >>> dt_ny = dt_utc.astimezone(pytz.timezone('America/New_York'))
    >>> dt_ny2 = dt_utc2.astimezone(pytz.timezone('America/New_York'))
    >>> diff = DeepDiff(dt_ny, dt_ny2)
    >>> diff
    {'values_changed': {'root': {'new_value': datetime.datetime(2025, 2, 3, 11, 0, tzinfo=datetime.timezone.utc), 'old_value': datetime.datetime(2025, 2, 3, 12, 0, tzinfo=datetime.timezone.utc)}}}
    >>> diff2 = DeepDiff(dt_ny, dt_ny2, default_timezone=pytz.timezone('America/New_York'))
    >>> diff2
    {'values_changed': {'root': {'new_value': datetime.datetime(2025, 2, 3, 6, 0, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>), 'old_value': datetime.datetime(2025, 2, 3, 7, 0, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>)}}}


Back to :doc:`/index`
