adding docs

Author: seperman

deepdiff/diff.py

@@ -158,7 +158,7 @@ def __init__(self,
                  report_repetition: bool=False,
                  significant_digits: Optional[int]=None,
                  use_log_scale: bool=False,
-                 log_scale_similarity_threshold: int=0.1,
+                 log_scale_similarity_threshold: float=0.1,
                  threshold_to_diff_deeper: float = 0.33,
                  truncate_datetime: Optional[str]=None,
                  use_enum_value: bool=False,

docs/diff_doc.rst

@@ -151,6 +151,9 @@ log_frequency_in_sec: Integer, default = 0
     If you set it to 20, it will log every 20 seconds. This is useful only when running DeepDiff
     on massive objects that will take a while to run. If you are only dealing with small objects, keep it at 0 to disable progress logging.
 
+log_scale_similarity_threshold: float, default = 0.1
+    :ref:`use_log_scale_label` along with :ref:`log_scale_similarity_threshold_label` can be used to ignore small changes in numbers by comparing their differences in logarithmic space. This is different than ignoring the difference based on significant digits.
+
 max_passes: Integer, default = 10000000
     :ref:`max_passes_label` defined the maximum number of passes to run on objects to pin point what exactly is different. This is only used when ignore_order=True. A new pass is started each time 2 iterables are compared in a way that every single item that is different from the first one is compared to every single item that is different in the second iterable.
 
@@ -179,6 +182,15 @@ significant_digits : int >= 0, default=None
 truncate_datetime: string, default = None
     :ref:`truncate_datetime_label` can take value one of 'second', 'minute', 'hour', 'day' and truncate with this value datetime objects before hashing it
 
+threshold_to_diff_deeper: float, default = 0.33
+    :ref:`threshold_to_diff_deeper_label` is a number between 0 and 1. When comparing dictionaries that have a small intersection of keys, we will report the dictionary as a new_value instead of reporting individual keys changed. If you set it to zero, you get the same results as DeepDiff 7.0.1 and earlier, which means this feature is disabled. The new default is 0.33 which means if less that one third of keys between dictionaries intersect, report it as a new object.
+
+use_enum_value: Boolean, default=False
+    :ref:`use_enum_value_label` makes it so when diffing enum, we use the enum's value. It makes it so comparing an enum to a string or any other value is not reported as a type change.
+
+use_log_scale: Boolean, default=False
+    :ref:`use_log_scale_label` along with :ref:`log_scale_similarity_threshold_label` can be used to ignore small changes in numbers by comparing their differences in logarithmic space. This is different than ignoring the difference based on significant digits.
+
 verbose_level: 2 >= int >= 0, default = 1
     Higher verbose level shows you more details.
     For example verbose level 1 shows what dictionary item are added or removed.

docs/ignore_types_or_values.rst

@@ -362,4 +362,26 @@ truncate_datetime: string, default = None
     {}
 
 
+.. _use_enum_value_label:
+
+Use Enum Value
+--------------
+
+use_enum_value: Boolean, default=False
+    Makes it so when diffing enum, we use the enum's value. It makes it so comparing an enum to a string or any other value is not reported as a type change.
+
+    >>> from enum import Enum
+    >>> from deepdiff import DeepDiff
+
+    >>>
+    >>> class MyEnum2(str, Enum):
+    ...     book = "book"
+    ...     cake = "cake"
+    ...
+    >>> DeepDiff("book", MyEnum2.book)
+    {'type_changes': {'root': {'old_type': <class 'str'>, 'new_type': <enum 'MyEnum2'>, 'old_value': 'book', 'new_value': <MyEnum2.book: 'book'>}}}
+    >>> DeepDiff("book", MyEnum2.book, use_enum_value=True)
+    {}
+
+
 Back to :doc:`/index`

docs/numbers.rst

@@ -142,6 +142,39 @@ Example:
     math_epsilon cannot currently handle the hashing of values, which is done when :ref:`ignore_order_label` is True.
 
 
+.. _use_log_scale_label:
+
+Use Log Scale
+-------------
+
+use_log_scale: Boolean, default=False
+    use_log_scale along with :ref:`log_scale_similarity_threshold_label` can be used to ignore small changes in numbers by comparing their differences in logarithmic space. This is different than ignoring the difference based on significant digits.
+
+
+    >>> from deepdiff import DeepDiff
+
+    >>> t1 = {'foo': 110, 'bar': 306}
+    >>> t2 = {'foo': 140, 'bar': 298}
+    >>>
+    >>> DeepDiff(t1, t2)
+    {'values_changed': {"root['foo']": {'new_value': 140, 'old_value': 110}, "root['bar']": {'new_value': 298, 'old_value': 306}}}
+    >>> DeepDiff(t1, t2, use_log_scale=True, log_scale_similarity_threshold=0.01)
+    {'values_changed': {"root['foo']": {'new_value': 140, 'old_value': 110}, "root['bar']": {'new_value': 298, 'old_value': 306}}}
+    >>> DeepDiff(t1, t2, use_log_scale=True, log_scale_similarity_threshold=0.1)
+    {'values_changed': {"root['foo']": {'new_value': 140, 'old_value': 110}}}
+    >>> DeepDiff(t1, t2, use_log_scale=True, log_scale_similarity_threshold=0.3)
+    {
+
+
+.. _log_scale_similarity_threshold_label:
+
+Log Scale Similarity Threshold
+------------
+
+log_scale_similarity_threshold: float, default = 0.1
+    :ref:`use_log_scale_label` along with log_scale_similarity_threshold can be used to ignore small changes in numbers by comparing their differences in logarithmic space. This is different than ignoring the difference based on significant digits. See above example.
+
+
 Performance Improvement of Numbers diffing
 ------------------------------------------
 

docs/optimizations.rst

@@ -266,5 +266,23 @@ zip_ordered_iterables: Boolean, default = False
                         'root[3]': {'new_value': 'd', 'old_value': 'e'}}}
 
 
+.. _threshold_to_diff_deeper_label:
+
+Threshold To Diff Deeper
+------------------------
+
+threshold_to_diff_deeper: float, default = 0.33
+    threshold_to_diff_deeper is a number between 0 and 1. When comparing dictionaries that have a small intersection of keys, we will report the dictionary as a new_value instead of reporting individual keys changed. If you set it to zero, you get the same results as DeepDiff 7.0.1 and earlier, which means this feature is disabled. The new default is 0.33 which means if less that one third of keys between dictionaries intersect, report it as a new object.
+
+
+    >>> from deepdiff import DeepDiff
+    >>> t1 = {"veggie": "carrots"}
+    >>> t2 = {"meat": "carrots"}
+    >>>
+    >>> DeepDiff(t1, t2, threshold_to_diff_deeper=0)
+    {'dictionary_item_added': ["root['meat']"], 'dictionary_item_removed': ["root['veggie']"]}
+    >>> DeepDiff(t1, t2, threshold_to_diff_deeper=0.33)
+    {'values_changed': {'root': {'new_value': {'meat': 'carrots'}, 'old_value': {'veggie': 'carrots'}}}}
+
 
 Back to :doc:`/index`