Skip to content

Commit 3229109

Browse files
sepermanseperman
committed
adding docs
1 parent 507d994 commit 3229109

File tree

8 files changed

+159
-6
lines changed

8 files changed

+159
-6
lines changed

‎deepdiff/model.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ def _from_tree_value_changed(self, tree):
191191
the_changed.update({'diff': change.additional['diff']})
192192

193193
def _from_tree_iterable_item_moved(self, tree):
194-
if 'iterable_item_moved' in tree:
194+
if 'iterable_item_moved' in tree and self.verbose_level > 1:
195195
for change in tree['iterable_item_moved']:
196196
the_changed = {'new_path': change.path(use_t2=True), 'value': change.t2}
197197
self['iterable_item_moved'][change.path(

‎docs/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@
132132
'extra_nav_links': {
133133
'Zepworks': 'https://zepworks.com', 'Github': 'https://github.com/seperman/deepdiff'},
134134
'show_relbars': True,
135-
'github_repo': 'deepdiff',
135+
# 'github_repo': 'deepdiff',
136136
'anchor': '#DDD',
137137
'touch_icon': 'logo.svg',
138138
'github_button': True,

‎docs/diff.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ DeepDiff
2323
serialization
2424
optimizations
2525
stats
26+
other
2627
troubleshoot
2728

2829
Back to :doc:`/index`

‎docs/diff_doc.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,10 @@ ignore_nan_inequality: Boolean, default = False
9191
:ref:`ignore_nan_inequality_label`
9292
Whether to ignore float('nan') inequality in Python.
9393

94+
iterable_compare_func:
95+
:ref:`iterable_compare_func_label`:
96+
There are times that we want to guide DeepDiff as to what items to compare with other items. In such cases we can pass a iterable_compare_func that takes a function pointer to compare two items. It function takes two parameters 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.
97+
9498
ignore_private_variables: Boolean, default = True
9599
:ref:`ignore_private_variables_label`
96100
Whether to exclude the private variables in the calculations or not. It only affects variables that start with double underscores (__).
@@ -116,7 +120,6 @@ number_format_notation : string, default="f"
116120
number_to_string_func : function, default=None
117121
:ref:`number_to_string_func_label` is an advanced feature to give the user the full control into overriding how numbers are converted to strings for comparison. The default function is defined in https://github.com/seperman/deepdiff/blob/master/deepdiff/helper.py and is called number_to_string. You can define your own function to do that.
118122

119-
120123
progress_logger: log function, default = logger.info
121124
:ref:`progress_logger_label` defines what logging function to use specifically for progress reporting. This function is only used when progress logging is enabled which happens by setting log_frequency_in_sec to anything above zero.
122125

‎docs/ignore_order.rst‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,4 +219,71 @@ So 2.0 and 2.01 are paired together for example.
219219

220220
As an example of how much this parameter can affect the results in deeply nested objects, please take a look at :ref:`distance_and_diff_granularity_label`.
221221

222+
223+
.. _iterable_compare_func_label2:
224+
225+
Iterable Compare Func
226+
---------------------
227+
228+
New in DeepDiff 5.5.0
229+
230+
There are times that we want to guide DeepDiff as to what items to compare with other items. In such cases we can pass a `iterable_compare_func` that takes a function pointer to compare two items. It function takes two parameters 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.
231+
232+
233+
For example take the following objects:
234+
235+
>>> from deepdiff import DeepDiff
236+
>>> from deepdiff.helper import CannotCompare
237+
>>>
238+
>>> t1 = [
239+
... {
240+
... 'id': 1,
241+
... 'value': [1]
242+
... },
243+
... {
244+
... 'id': 2,
245+
... 'value': [7, 8, 1]
246+
... },
247+
... {
248+
... 'id': 3,
249+
... 'value': [7, 8],
250+
... },
251+
... ]
252+
>>>
253+
>>> t2 = [
254+
... {
255+
... 'id': 2,
256+
... 'value': [7, 8]
257+
... },
258+
... {
259+
... 'id': 3,
260+
... 'value': [7, 8, 1],
261+
... },
262+
... {
263+
... 'id': 1,
264+
... 'value': [1]
265+
... },
266+
... ]
267+
>>>
268+
>>> DeepDiff(t1, t2, ignore_order=True)
269+
{'values_changed': {"root[2]['id']": {'new_value': 2, 'old_value': 3}, "root[1]['id']": {'new_value': 3, 'old_value': 2}}}
270+
271+
272+
Now let's define a compare_func that takes 3 parameters: x, y and level.
273+
274+
>>> def compare_func(x, y, level=None):
275+
... try:
276+
... return x['id'] == y['id']
277+
... except Exception:
278+
... raise CannotCompare() from None
279+
...
280+
>>> DeepDiff(t1, t2, ignore_order=True, iterable_compare_func=compare_func)
281+
{'iterable_item_added': {"root[2]['value'][2]": 1}, 'iterable_item_removed': {"root[1]['value'][2]": 1}}
282+
283+
As you can see the results are different. Now items with the same ids are compared with each other.
284+
285+
.. note::
286+
287+
The level parameter of the iterable_compare_func is only used when ignore_order=False.
288+
222289
Back to :doc:`/index`

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ NOTE: Python 2 is not supported any more. DeepDiff v3.3.0 was the last version t
3939
What is New
4040
***********
4141

42-
DeepDiff 5.4.0
42+
DeepDiff 5.5.0
4343
--------------
4444

4545
1. New option called `iterable_compare_func` that takes a function pointer to compare two items. It function takes two parameters 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.

‎docs/other.rst‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
:doc:`/index`
2+
3+
Other Parameters
4+
================
5+
6+
.. _iterable_compare_func_label:
7+
8+
Iterable Compare Func
9+
---------------------
10+
11+
New in DeepDiff 5.5.0
12+
13+
There are times that we want to guide DeepDiff as to what items to compare with other items. In such cases we can pass a `iterable_compare_func` that takes a function pointer to compare two items. It function takes two parameters 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.
14+
15+
16+
For example take the following objects:
17+
18+
19+
20+
Now let's define a compare_func that takes 3 parameters: x, y and level.
21+
22+
>>> from deepdiff import DeepDiff
23+
>>> from deepdiff.helper import CannotCompare
24+
>>>
25+
>>> t1 = [
26+
... {
27+
... 'id': 1,
28+
... 'value': [1]
29+
... },
30+
... {
31+
... 'id': 2,
32+
... 'value': [7, 8, 1]
33+
... },
34+
... {
35+
... 'id': 3,
36+
... 'value': [7, 8],
37+
... },
38+
... ]
39+
>>>
40+
>>> t2 = [
41+
... {
42+
... 'id': 2,
43+
... 'value': [7, 8]
44+
... },
45+
... {
46+
... 'id': 3,
47+
... 'value': [7, 8, 1],
48+
... },
49+
... {
50+
... 'id': 1,
51+
... 'value': [1]
52+
... },
53+
... ]
54+
>>>
55+
>>> DeepDiff(t1, t2)
56+
{'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}}
57+
58+
As you can see the results are different. Now items with the same ids are compared with each other.
59+
60+
>>> def compare_func(x, y, level=None):
61+
... try:
62+
... return x['id'] == y['id']
63+
... except Exception:
64+
... raise CannotCompare() from None
65+
...
66+
>>> DeepDiff(t1, t2, iterable_compare_func=compare_func)
67+
{'iterable_item_added': {"root[2]['value'][2]": 1}, 'iterable_item_removed': {"root[1]['value'][2]": 1}}
68+
69+
If we set the verbose_level=2, we can see more details.
70+
71+
>>> DeepDiff(t1, t2, iterable_compare_func=compare_func, verbose_level=2)
72+
{'iterable_item_added': {"root[2]['value'][2]": 1}, 'iterable_item_removed': {"root[1]['value'][2]": 1}, 'iterable_item_moved': {'root[0]': {'new_path': 'root[2]', 'value': {'id': 1, 'value': [1]}}, 'root[1]': {'new_path': 'root[0]', 'value': {'id': 2, 'value': [7, 8]}}, 'root[2]': {'new_path': 'root[1]', 'value': {'id': 3, 'value': [7, 8, 1]}}}}
73+
74+
75+
We can also use the level parameter.
76+
77+
.. note::
78+
79+
The level parameter of the iterable_compare_func is only used when ignore_order=False which is the default.
80+
81+
82+
Back to :doc:`/index`

‎tests/test_ignore_order.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -811,7 +811,7 @@ def test_ignore_order_with_compare_func_to_guide_comparison(self):
811811
},
812812
]
813813

814-
ddiff = DeepDiff(t1, t2, ignore_order=True, verbose_level=2, cache_size=5000, cutoff_intersection_for_pairs=1)
814+
ddiff = DeepDiff(t1, t2, ignore_order=True)
815815
expected = {
816816
'values_changed': {
817817
"root[2]['id']": {
@@ -841,6 +841,6 @@ def compare_func(x, y, level=None):
841841
}
842842
}
843843

844-
ddiff2 = DeepDiff(t1, t2, ignore_order=True, iterable_compare_func=compare_func, verbose_level=2, cache_size=5000, cutoff_intersection_for_pairs=1)
844+
ddiff2 = DeepDiff(t1, t2, ignore_order=True, iterable_compare_func=compare_func)
845845
assert expected2 == ddiff2
846846
assert ddiff != ddiff2

0 commit comments

Comments
 (0)