DeepDiff 5.5.0 documentation!

DeepDiff Overview

The DeepDiff library includes the following modules:

  • DeepDiff For Deep Difference of 2 objects. DeepDiff

    It return the deep Difference of python objects. It can also be used to take the distance between objects. Deep Distance

  • DeepSearch Search for objects within other objects. DeepSearch

  • DeepHash Hash any object based on their content even if they are not “hashable” in Python’s eyes. DeepHash

  • Delta Delta of objects that can be applied to other objects. Imagine git commits but for structured data. Delta

  • Extract For extracting a path from an object Extract

  • Commandline Most of the above functionality is also available via the commandline module Command Line

Supported Python Versions

DeepDiff is rigorously tested against Python 3.6, 3.7, 3.8, 3.9 and Pypy3

NOTE: Python 2 is not supported any more. DeepDiff v3.3.0 was the last version to supprt Python 2.

What is New

New In DeepDiff 5.5.0

  1. New option called iterable_compare_func that takes a function pointer to compare two items. The function takes three parameters (x, y, level) and should return True if it is a match, False if it is not a match or raise CannotCompare if it is unable to compare the two. If CannotCompare is raised then it will revert back to comparing in order. If iterable_compare_func is not provided or set to None the behavior defaults to comparing items in order. A new report item called iterable_item_moved this will only ever be added if there is a custom compare function.

    >>> from deepdiff import DeepDiff
    >>> from deepdiff.helper import CannotCompare
    >>>
    >>> t1 = [
    ...     {
    ...         'id': 2,
    ...         'value': [7, 8, 1]
    ...     },
    ...     {
    ...         'id': 3,
    ...         'value': [7, 8],
    ...     },
    ... ]
    >>>
    >>> t2 = [
    ...     {
    ...         'id': 2,
    ...         'value': [7, 8]
    ...     },
    ...     {
    ...         'id': 3,
    ...         'value': [7, 8, 1],
    ...     },
    ... ]
    >>>
    >>> DeepDiff(t1, t2)
    {'values_changed': {"root[0]['id']": {'new_value': 2, 'old_value': 1}, "root[0]['value'][0]": {'new_value': 7, 'old_value': 1}, "root[1]['id']": {'new_value': 3, 'old_value': 2}, "root[2]['id']": {'new_value': 1, 'old_value': 3}, "root[2]['value'][0]": {'new_value': 1, 'old_value': 7}}, 'iterable_item_added': {"root[0]['value'][1]": 8}, 'iterable_item_removed': {"root[2]['value'][1]": 8}}
    

Now let’s use the custom compare function to guide DeepDiff in what to compare with what:

>>> def compare_func(x, y, level=None):
...     try:
...         return x['id'] == y['id']
...     except Exception:
...         raise CannotCompare() from None
...
>>> DeepDiff(t1, t2, iterable_compare_func=compare_func)
{'iterable_item_added': {"root[2]['value'][2]": 1}, 'iterable_item_removed': {"root[1]['value'][2]": 1}}
  1. You can get the path() of item in the tree view in the list format instead of string representation by passing path(output_format=’list’)

>>> from deepdiff import DeepDiff
>>> 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'][2] t1:3, t2:not present>, <root[4]['b'][3] t1:4, t2:not present>]}
>>> removed = ddiff['iterable_item_removed'][0]
>>> removed.path()
"root[4]['b'][2]"
>>> removed.path(output_format='list')
[4, 'b', 2]

New In Deepdiff 5.3.0

Deepdiff 5.3.0 comes with regular expressions in the DeepSearch and grep modules:

>>> from deepdiff import grep
>>> from pprint import pprint
>>> obj = ["something here", {"long": "somewhere", "someone": 2, 0: 0, "somewhere": "around"}]
>>> ds = obj | grep("some.*", use_regexp=True)
{ 'matched_paths': ["root[1]['someone']", "root[1]['somewhere']"],
  'matched_values': ['root[0]', "root[1]['long']"]}

Tutorials

Tutorials can be found on Zepworks blog

Installation

Install from PyPi:

pip install deepdiff

If you want to use DeepDiff from commandline:

pip install "deepdiff[cli]"

Read about DeepDiff optimizations at Optimizations

>>> from deepdiff import DeepDiff  # For Deep Difference of 2 objects
>>> from deepdiff import grep, DeepSearch  # For finding if item exists in an object
>>> from deepdiff import DeepHash  # For hashing objects based on their contents
>>> from deepdiff import Delta  # For creating delta of objects that can be applied later to other objects.
>>> from deepdiff import extract  # For extracting a path from an object
Note: if you want to use DeepDiff via commandline, make sure to run::

pip install “deepdiff[cli]”

Then you can access the commands via:

  • DeepDiff

$ deep diff --help
  • Delta

$ deep patch --help
  • grep

$ deep grep --help
  • extract

$ deep extract --help

int, string, unicode, dictionary, list, tuple, set, frozenset, OrderedDict, NamedTuple, Numpy, custom objects and more!

Pycon

Pycon 2016 Talk A talk was given about the basics of how DeepDiff does what it does at Pycon 2016. Diff it to Dig it Pycon 2016 video

You can find more information about the contents of that Pycon talk here: http://zepworks.com/blog/diff-it-to-digg-it/

References

Indices and tables