DeepDiff Reference¶
-
class
deepdiff.diff.DeepDiff(t1, t2, ignore_order=False, report_repetition=False, significant_digits=None, exclude_paths=set([]), exclude_types=set([]), verbose_level=1, view='text', **kwargs)¶ DeepDiff
Deep Difference of dictionaries, iterables, strings and almost any other object. It will recursively look for all the changes.
DeepDiff 3.0 added the concept of views. There is a default “text” view and a “tree” view.
Parameters
- t1 : A dictionary, list, string or any python object that has __dict__ or __slots__
- This is the first item to be compared to the second item
- t2 : dictionary, list, string or almost any python object that has __dict__ or __slots__
- The second item is to be compared to the first one
- ignore_order : Boolean, defalt=False ignores orders for iterables.
- Note that if you have iterables contatining any unhashable, ignoring order can be expensive. Normally ignore_order does not report duplicates and repetition changes. In order to report repetitions, set report_repetition=True in addition to ignore_order=True
- report_repetition : Boolean, default=False reports repetitions when set True
- ONLY when ignore_order is set True too. This works for iterables. This feature currently is experimental and is not production ready.
- significant_digits : int >= 0, default=None.
If it is a non negative integer, it compares only that many digits AFTER the decimal point.
This only affects floats, decimal.Decimal and complex.
Internally it uses “{:.Xf}”.format(Your Number) to compare numbers where X=significant_digits
Note that “{:.3f}”.format(1.1135) = 1.113, but “{:.3f}”.format(1.11351) = 1.114
For Decimals, Python’s format rounds 2.5 to 2 and 3.5 to 4 (to the closest even number)
- verbose_level : int >= 0, default = 1.
- Higher verbose level shows you more details. For example verbose level 1 shows what dictionary item are added or removed. And verbose level 2 shows the value of the items that are added or removed too.
- exclude_paths: list, default = None.
- List of paths to exclude from the report.
- exclude_types: list, default = None.
- List of object types to exclude from the report.
- view: string, default = text
- Starting the version 3 you can choosethe view into the deepdiff results. The default is the text view which has been the only view up until now. The new view is called the tree view which allows you to traverse through the tree of changed items.
Returns
A DeepDiff object that has already calculated the difference of the 2 items.Supported data types
int, string, unicode, dictionary, list, tuple, set, frozenset, OrderedDict, NamedTuple and custom objects!
Text View
Text view is the original and currently the default view of DeepDiff.
It is called text view because the results contain texts that represent the path to the data:
- Example of using the text view.
>>> from deepdiff import DeepDiff >>> t1 = {1:1, 3:3, 4:4} >>> t2 = {1:1, 3:3, 5:5, 6:6} >>> ddiff = DeepDiff(t1, t2) >>> print(ddiff) {'dictionary_item_added': {'root[5]', 'root[6]'}, 'dictionary_item_removed': {'root[4]'}}
So for example ddiff[‘dictionary_item_removed’] is a set if strings thus this is called the text view.
See also
The following examples are using the default text view. The Tree View is introduced in DeepDiff v3 and provides traversing capabilitie through your diffed data and more! Read more about the Tree View at the bottom of this page.
- 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}}
- 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
- Type change
>>> t1 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 2, 3]}} >>> t2 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":"world\n\n\nEnd"}} >>> ddiff = DeepDiff(t1, t2) >>> pprint (ddiff, indent = 2) { 'type_changes': { "root[4]['b']": { 'new_type': <class 'str'>, 'new_value': 'world\n\n\nEnd', 'old_type': <class 'list'>, 'old_value': [1, 2, 3]}}}
- And if you don’t care about the value of items that have changed type, please set verbose level to 0
>>> t1 = {1:1, 2:2, 3:3} >>> t2 = {1:1, 2:"2", 3:3} >>> pprint(DeepDiff(t1, t2, verbose_level=0), indent=2) { 'type_changes': { 'root[2]': { 'new_type': <class 'str'>, 'old_type': <class 'int'>}}}
- 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 difference 2:
>>> t1 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 2, 3]}} >>> t2 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 3, 2, 3]}} >>> ddiff = DeepDiff(t1, t2) >>> pprint (ddiff, indent = 2) { 'iterable_item_added': {"root[4]['b'][3]": 3}, 'values_changed': { "root[4]['b'][1]": {'new_value': 3, 'old_value': 2}, "root[4]['b'][2]": {'new_value': 2, 'old_value': 3}}}
- List difference ignoring order or duplicates: (with the same dictionaries as above)
>>> t1 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 2, 3]}} >>> t2 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 3, 2, 3]}} >>> ddiff = DeepDiff(t1, t2, ignore_order=True) >>> print (ddiff) {}
- List difference ignoring order but reporting repetitions:
>>> from deepdiff import DeepDiff >>> from pprint import pprint >>> t1 = [1, 3, 1, 4] >>> t2 = [4, 4, 1] >>> ddiff = DeepDiff(t1, t2, ignore_order=True, report_repetition=True) >>> pprint(ddiff, indent=2) { 'iterable_item_removed': {'root[1]': 3}, 'repetition_change': { 'root[0]': { 'new_indexes': [2], 'new_repeat': 1, 'old_indexes': [0, 2], 'old_repeat': 2, 'value': 1}, 'root[3]': { 'new_indexes': [0, 1], 'new_repeat': 2, 'old_indexes': [3], 'old_repeat': 1, 'value': 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[5]', 'root[3]'}, '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}}}
- Approximate decimals comparison (Significant digits after the point):
>>> t1 = Decimal('1.52') >>> t2 = Decimal('1.57') >>> DeepDiff(t1, t2, significant_digits=0) {} >>> DeepDiff(t1, t2, significant_digits=1) {'values_changed': {'root': {'old_value': Decimal('1.52'), 'new_value': Decimal('1.57')}}}
- Approximate float comparison (Significant digits after the point):
>>> t1 = [ 1.1129, 1.3359 ] >>> t2 = [ 1.113, 1.3362 ] >>> pprint(DeepDiff(t1, t2, significant_digits=3)) {} >>> pprint(DeepDiff(t1, t2)) {'values_changed': {'root[0]': {'new_value': 1.113, 'old_value': 1.1129}, 'root[1]': {'new_value': 1.3362, 'old_value': 1.3359}}} >>> pprint(DeepDiff(1.23*10**20, 1.24*10**20, significant_digits=1)) {'values_changed': {'root': {'new_value': 1.24e+20, 'old_value': 1.23e+20}}}
Note
All the examples for the text view work for the tree view too. You just need to set view=’tree’ to get it in tree form.
Tree View
Starting the version 3 You can chooe the view into the deepdiff results. The tree view provides you with tree objects that you can traverse through to find the parents of the objects that are diffed and the actual objects that are being diffed. This view is very useful when dealing with nested objects. Note that tree view always returns results in the form of Python sets.
You can traverse through the tree elements!
Note
The Tree view is just a different representation of the diffed data. Behind the scene, DeepDiff creates the tree view first and then converts it to textual representation for the text view.
+---------------------------------------------------------------+ | | | parent(t1) parent node parent(t2) | | + ^ + | +------|--------------------------|---------------------|-------+ | | | up | | Child | | | ChildRelationship | Relationship | | | | down | | | +------|----------------------|-------------------------|-------+ | v v v | | child(t1) child node child(t2) | | | +---------------------------------------------------------------+
Up: Move up to the parent node Down: Move down to the child node Path(): Get the path to the current node T1: The first item in the current node that is being diffed T2: The second item in the current node that is being diffed Additional: Additional information about the node i.e. repetition Repetition: Shortcut to get the repetition report The tree view allows you to have more than mere textual representaion of the diffed objects. It gives you the actual objects (t1, t2) throughout the tree of parents and children.
Examples Tree View
Note
The Tree View is introduced in DeepDiff 3. Set view=’tree’ in order to use this view.
- Value of an item has changed (Tree View)
>>> from deepdiff import DeepDiff >>> from pprint import pprint >>> t1 = {1:1, 2:2, 3:3} >>> t2 = {1:1, 2:4, 3:3} >>> ddiff_verbose0 = DeepDiff(t1, t2, verbose_level=0, view='tree') >>> ddiff_verbose0 {'values_changed': {<root[2]>}} >>> >>> ddiff_verbose1 = DeepDiff(t1, t2, verbose_level=1, view='tree') >>> ddiff_verbose1 {'values_changed': {<root[2] t1:2, t2:4>}} >>> set_of_values_changed = ddiff_verbose1['values_changed'] >>> # since set_of_values_changed includes only one item in a set >>> # in order to get that one item we can: >>> (changed,) = set_of_values_changed >>> changed # Another way to get this is to do: changed=list(set_of_values_changed)[0] <root[2] t1:2, t2:4> >>> changed.t1 2 >>> changed.t2 4 >>> # You can traverse through the tree, get to the parents! >>> changed.up <root t1:{1: 1, 2: 2,...}, t2:{1: 1, 2: 4,...}>
- List difference (Tree View)
>>> 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, view='tree') >>> ddiff {'iterable_item_removed': {<root[4]['b'][3] t1:4, t2:Not Present>, <root[4]['b'][2] t1:3, t2:Not Present>}} >>> # Note that the iterable_item_removed is a set. In this case it has 2 items in it. >>> # One way to get one item from the set is to convert it to a list >>> # And then get the first item of the list: >>> removed = list(ddiff['iterable_item_removed'])[0] >>> removed <root[4]['b'][2] t1:3, t2:Not Present> >>> >>> parent = removed.up >>> parent <root[4]['b'] t1:[1, 2, 3, 4], t2:[1, 2]> >>> parent.path() "root[4]['b']" >>> parent.t1 [1, 2, 3, 4] >>> parent.t2 [1, 2] >>> parent.up <root[4] t1:{'a': 'hello...}, t2:{'a': 'hello...}> >>> parent.up.up <root t1:{1: 1, 2: 2,...}, t2:{1: 1, 2: 2,...}> >>> parent.up.up.t1 {1: 1, 2: 2, 3: 3, 4: {'a': 'hello', 'b': [1, 2, 3, 4]}} >>> parent.up.up.t1 == t1 # It is holding the original t1 that we passed to DeepDiff True
- List difference 2 (Tree View)
>>> t1 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 2, 3]}} >>> t2 = {1:1, 2:2, 3:3, 4:{"a":"hello", "b":[1, 3, 2, 3]}} >>> ddiff = DeepDiff(t1, t2, view='tree') >>> pprint(ddiff, indent = 2) { 'iterable_item_added': {<root[4]['b'][3] t1:Not Present, t2:3>}, 'values_changed': { <root[4]['b'][1] t1:2, t2:3>, <root[4]['b'][2] t1:3, t2:2>}} >>> >>> # Note that iterable_item_added is a set with one item. >>> # So in order to get that one item from it, we can do: >>> >>> (added,) = ddiff['iterable_item_added'] >>> added <root[4]['b'][3] t1:Not Present, t2:3> >>> added.up.up <root[4] t1:{'a': 'hello...}, t2:{'a': 'hello...}> >>> added.up.up.path() 'root[4]' >>> added.up.up.down <root[4]['b'] t1:[1, 2, 3], t2:[1, 3, 2, 3]> >>> >>> # going up twice and then down twice gives you the same node in the tree: >>> added.up.up.down.down == added True
- List difference ignoring order but reporting repetitions (Tree View)
>>> t1 = [1, 3, 1, 4] >>> t2 = [4, 4, 1] >>> ddiff = DeepDiff(t1, t2, ignore_order=True, report_repetition=True, view='tree') >>> pprint(ddiff, indent=2) { 'iterable_item_removed': {<root[1] t1:3, t2:Not Present>}, 'repetition_change': { <root[3] {'repetition': {'old_repeat': 1,...}>, <root[0] {'repetition': {'old_repeat': 2,...}>}} >>> >>> # repetition_change is a set with 2 items. >>> # in order to get those 2 items, we can do the following. >>> # or we can convert the set to list and get the list items. >>> # or we can iterate through the set items >>> >>> (repeat1, repeat2) = ddiff['repetition_change'] >>> repeat1 # the default verbosity is set to 1. <root[0] {'repetition': {'old_repeat': 2,...}> >>> # The actual data regarding the repetitions can be found in the repetition attribute: >>> repeat1.repetition {'old_repeat': 1, 'new_repeat': 2, 'old_indexes': [3], 'new_indexes': [0, 1]} >>> >>> # If you change the verbosity, you will see less: >>> ddiff = DeepDiff(t1, t2, ignore_order=True, report_repetition=True, view='tree', verbose_level=0) >>> ddiff {'repetition_change': {<root[3]>, <root[0]>}, 'iterable_item_removed': {<root[1]>}} >>> (repeat1, repeat2) = ddiff['repetition_change'] >>> repeat1 <root[0]> >>> >>> # But the verbosity level does not change the actual report object. >>> # It only changes the textual representaion of the object. We get the actual object here: >>> repeat1.repetition {'old_repeat': 1, 'new_repeat': 2, 'old_indexes': [3], 'new_indexes': [0, 1]} >>> repeat1.t1 4 >>> repeat1.t2 4 >>> repeat1.up <root>
- List that contains dictionary (Tree View)
>>> 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, view='tree') >>> pprint (ddiff, indent = 2) { 'dictionary_item_removed': {<root[4]['b'][2][2] t1:2, t2:Not Present>}, 'values_changed': {<root[4]['b'][2][1] t1:1, t2:3>}}
- Sets (Tree View):
>>> t1 = {1, 2, 8} >>> t2 = {1, 2, 3, 5} >>> ddiff = DeepDiff(t1, t2, view='tree') >>> print(ddiff) {'set_item_removed': {<root: t1:8, t2:Not Present>}, 'set_item_added': {<root: t1:Not Present, t2:5>, <root: t1:Not Present, t2:3>}} >>> # grabbing one item from set_item_removed set which has one item only >>> (item,) = ddiff['set_item_removed'] >>> item.up <root t1:{8, 1, 2}, t2:{1, 2, 3, 5}> >>> item.up.t1 == t1 True
- Named Tuples (Tree View):
>>> from collections import namedtuple >>> Point = namedtuple('Point', ['x', 'y']) >>> t1 = Point(x=11, y=22) >>> t2 = Point(x=11, y=23) >>> print(DeepDiff(t1, t2, view='tree')) {'values_changed': {<root.y t1:22, t2:23>}}
- Custom objects (Tree View):
>>> class ClassA(object): ... a = 1 ... def __init__(self, b): ... self.b = b ... >>> t1 = ClassA(1) >>> t2 = ClassA(2) >>> >>> print(DeepDiff(t1, t2, view='tree')) {'values_changed': {<root.b t1:1, t2:2>}}
- Object attribute added (Tree View):
>>> t2.c = "new attribute" >>> pprint(DeepDiff(t1, t2, view='tree')) {'attribute_added': {<root.c t1:Not Present, t2:'new attribute'>}, 'values_changed': {<root.b t1:1, t2:2>}}
- Approximate decimals comparison (Significant digits after the point) (Tree View):
>>> t1 = Decimal('1.52') >>> t2 = Decimal('1.57') >>> DeepDiff(t1, t2, significant_digits=0, view='tree') {} >>> ddiff = DeepDiff(t1, t2, significant_digits=1, view='tree') >>> ddiff {'values_changed': {<root t1:Decimal('1.52'), t2:Decimal('1.57')>}} >>> (change1,) = ddiff['values_changed'] >>> change1 <root t1:Decimal('1.52'), t2:Decimal('1.57')> >>> change1.t1 Decimal('1.52') >>> change1.t2 Decimal('1.57') >>> change1.path() 'root'
- Approximate float comparison (Significant digits after the point) (Tree View):
>>> t1 = [ 1.1129, 1.3359 ] >>> t2 = [ 1.113, 1.3362 ] >>> ddiff = DeepDiff(t1, t2, significant_digits=3, view='tree') >>> ddiff {} >>> ddiff = DeepDiff(t1, t2, view='tree') >>> pprint(ddiff, indent=2) { 'values_changed': { <root[0] t1:1.1129, t2:1.113>, <root[1] t1:1.3359, t2:1.3362>}} >>> ddiff = DeepDiff(1.23*10**20, 1.24*10**20, significant_digits=1, view='tree') >>> ddiff {'values_changed': {<root t1:1.23e+20, t2:1.24e+20>}}
Note
All the examples for the text view work for the tree view too. You just need to set view=’tree’ to get it in tree form.
Serialization
DeepDiff uses jsonpickle in order to serialize and deserialize its results into json.
- Serialize and then deserialize back to deepdiff
>>> t1 = {1: 1, 2: 2, 3: 3} >>> t2 = {1: 1, 2: "2", 3: 3} >>> ddiff = DeepDiff(t1, t2) >>> jsoned = ddiff.json >>> jsoned '{"type_changes": {"root[2]": {"py/object": "deepdiff.helper.RemapDict", "new_type": {"py/type": "__builtin__.str"}, "new_value": "2", "old_type": {"py/type": "__builtin__.int"}, "old_value": 2}}}' >>> ddiff_new = DeepDiff.from_json(jsoned) >>> ddiff == ddiff_new True
Pycon 2016 Talk I gave a talk about how DeepDiff does what it does at Pycon 2016. Diff it to Dig it Pycon 2016 video
And here is more info: http://zepworks.com/blog/diff-it-to-digg-it/
Back to DeepDiff 3.3.0 documentation!