Implemented the cache replacement.

  Changed:

  - Replaced the homegrown linked-list LFU implementation in deepdiff/lfucache.py with a small
    DistanceCache wrapper over native cachebox.LRUCache.
  - Kept LFUCache = DistanceCache and DummyLFU compatibility names so internal imports keep
    working.
  - Updated deepdiff/diff.py cache hot paths to avoid contains + get double lookups.
  - Moved cachebox>=5.2,<6 into core dependencies in pyproject.toml, since DeepDiff now imports it
    unconditionally.
  - Updated tests/test_lfucache.py to validate the new bounded distance-cache behavior instead of
    LFU frequency internals.

  Benchmark result from the same 1,000,000 operation local microbenchmark:

  - Old homegrown LFUCache: 1.901302s
  - Direct cachebox.LFUCache: 5.846142s
  - Direct cachebox.LRUCache: 0.537102s
  - New DistanceCache wrapper: 1.153068s

  So I used cachebox.LRUCache, not cachebox.LFUCache, because cachebox’s LFU policy is slower for
  this workload.

Author: seperman

deepdiff/diff.py

@@ -13,13 +13,13 @@
 from enum import Enum
 from copy import deepcopy
 from math import isclose as is_close
-from typing import List, Dict, Callable, Union, Any, Pattern, Tuple, Optional, Set, FrozenSet, TYPE_CHECKING, Protocol, Literal
+from typing import List, Dict, Callable, Union, Any, Pattern, Tuple, Optional, Set, FrozenSet, TYPE_CHECKING, Protocol, Literal, cast
 from collections.abc import Mapping, Iterable, Sequence
 from collections import defaultdict
 from inspect import getmembers
 from itertools import zip_longest
 from functools import lru_cache
-from deepdiff.helper import (strings, bytes_type, numbers, uuids, ListItemRemovedOrAdded, notpresent,
+from deepdiff.helper import (strings, bytes_type, numbers, uuids, ListItemRemovedOrAdded, notpresent, not_found,
                              IndexedHash, unprocessed, add_to_frozen_set, basic_types,
                              convert_item_or_items_into_set_else_none, get_type,
                              convert_item_or_items_into_compiled_regexes_else_none,
@@ -1210,9 +1210,12 @@ def _get_rough_distance_of_hashed_objs(
         _distance = cache_key = None
         if self._stats[DISTANCE_CACHE_ENABLED]:
             cache_key = self._get_distance_cache_key(added_hash, removed_hash)
-            if cache_key in self._distance_cache:
+            cached_distance = self._distance_cache.get(cache_key)
+            if cached_distance is not_found:
+                _distance = None
+            else:
                 self._stats[DISTANCE_CACHE_HIT_COUNT] += 1
-                _distance = self._distance_cache.get(cache_key)
+                _distance = cast(float, cached_distance)
         if _distance is None:
             # We can only cache the rough distance and not the actual diff result for reuse.
             # The reason is that we have modified the parameters explicitly so they are different and can't
@@ -1254,8 +1257,11 @@ def _get_most_in_common_pairs_in_iterables(
         cache_key = None
         if self._stats[DISTANCE_CACHE_ENABLED]:
             cache_key = combine_hashes_lists(items=[hashes_added, hashes_removed], prefix='pairs_cache')
-            if cache_key in self._distance_cache:
-                return self._distance_cache.get(cache_key).copy()
+            cached_pairs = self._distance_cache.get(cache_key)
+            if cached_pairs is not_found:
+                cached_pairs = None
+            else:
+                return cast(dict, cached_pairs).copy()
 
         # A dictionary of hashes to distances and each distance to an ordered set of hashes.
         # It tells us about the distance of each object from other objects.
@@ -1296,6 +1302,7 @@ def defaultdict_orderedset():
                 if _distance is None:
                     _distance = self._get_rough_distance_of_hashed_objs(
                         added_hash, removed_hash, added_hash_obj, removed_hash_obj, _original_type)
+                _distance = cast(float, _distance)
                 # Left for future debugging
                 # print(f'{Fore.RED}distance of {added_hash_obj.item} and {removed_hash_obj.item}: {_distance}{Style.RESET_ALL}')
                 # Discard potential pairs that are too far.

deepdiff/lfucache.py

@@ -1,208 +1,39 @@
-"""
-LFU cache Written by Shane Wang
-https://medium.com/@epicshane/a-python-implementation-of-lfu-least-frequently-used-cache-with-o-1-time-complexity-e16b34a3c49b
-https://github.com/luxigner/lfu_cache
-Modified by Sep Dehpour
-"""
 from collections import defaultdict
-from threading import Lock
-from statistics import mean
-from deepdiff.helper import not_found, dict_, SetOrdered
+from cachebox import LRUCache
+from deepdiff.helper import SetOrdered, not_found
 
 
-class CacheNode:
-    def __init__(self, key, report_type, value, freq_node, pre, nxt):
-        self.key = key
-        if report_type:
-            self.content = defaultdict(SetOrdered)
-            self.content[report_type].add(value)
-        else:
-            self.content = value
-        self.freq_node = freq_node
-        self.pre = pre  # previous CacheNode
-        self.nxt = nxt  # next CacheNode
-
-    def free_myself(self):
-        if self.freq_node.cache_head == self.freq_node.cache_tail:  # type: ignore
-            self.freq_node.cache_head = self.freq_node.cache_tail = None  # type: ignore
-        elif self.freq_node.cache_head == self:  # type: ignore
-            self.nxt.pre = None  # type: ignore
-            self.freq_node.cache_head = self.nxt  # type: ignore
-        elif self.freq_node.cache_tail == self:  # type: ignore
-            self.pre.nxt = None  # type: ignore
-            self.freq_node.cache_tail = self.pre  # type: ignore
-        else:
-            self.pre.nxt = self.nxt  # type: ignore
-            self.nxt.pre = self.pre  # type: ignore
-
-        self.pre = None
-        self.nxt = None
-        self.freq_node = None
-
-
-class FreqNode:
-    def __init__(self, freq, pre, nxt):
-        self.freq = freq
-        self.pre = pre  # previous FreqNode
-        self.nxt = nxt  # next FreqNode
-        self.cache_head = None  # CacheNode head under this FreqNode
-        self.cache_tail = None  # CacheNode tail under this FreqNode
-
-    def count_caches(self):
-        if self.cache_head is None and self.cache_tail is None:
-            return 0
-        elif self.cache_head == self.cache_tail:
-            return 1
-        else:
-            return '2+'
-
-    def remove(self):
-        if self.pre is not None:
-            self.pre.nxt = self.nxt
-        if self.nxt is not None:
-            self.nxt.pre = self.pre
-
-        pre = self.pre
-        nxt = self.nxt
-        self.pre = self.nxt = self.cache_head = self.cache_tail = None
-
-        return (pre, nxt)
-
-    def pop_head_cache(self):
-        if self.cache_head is None and self.cache_tail is None:
-            return None
-        elif self.cache_head == self.cache_tail:
-            cache_head = self.cache_head
-            self.cache_head = self.cache_tail = None
-            return cache_head
-        else:
-            cache_head = self.cache_head
-            self.cache_head.nxt.pre = None  # type: ignore
-            self.cache_head = self.cache_head.nxt  # type: ignore
-            return cache_head
-
-    def append_cache_to_tail(self, cache_node):
-        cache_node.freq_node = self
-
-        if self.cache_head is None and self.cache_tail is None:
-            self.cache_head = self.cache_tail = cache_node
-        else:
-            cache_node.pre = self.cache_tail
-            cache_node.nxt = None
-            self.cache_tail.nxt = cache_node  # type: ignore
-            self.cache_tail = cache_node
-
-    def insert_after_me(self, freq_node):
-        freq_node.pre = self
-        freq_node.nxt = self.nxt
-
-        if self.nxt is not None:
-            self.nxt.pre = freq_node
-
-        self.nxt = freq_node
-
-    def insert_before_me(self, freq_node):
-        if self.pre is not None:
-            self.pre.nxt = freq_node
-
-        freq_node.pre = self.pre
-        freq_node.nxt = self
-        self.pre = freq_node
+class DistanceCache:
+    """
+    Native bounded cache used by DeepDiff's distance calculations.
 
-
-class LFUCache:
+    DeepDiff historically used a pure Python LFU cache here. The distance-cache
+    hot path benefits more from cachebox's native mapping operations than from
+    preserving LFU eviction semantics.
+    """
 
     def __init__(self, capacity):
-        self.cache = dict_()  # {key: cache_node}
         if capacity <= 0:
-            raise ValueError('Capacity of LFUCache needs to be positive.')  # pragma: no cover.
-        self.capacity = capacity
-        self.freq_link_head = None
-        self.lock = Lock()
+            raise ValueError('Capacity of DistanceCache needs to be positive.')  # pragma: no cover.
+        self.cache = LRUCache(capacity)
 
     def get(self, key):
-        with self.lock:
-            if key in self.cache:
-                cache_node = self.cache[key]
-                freq_node = cache_node.freq_node
-                content = cache_node.content
-
-                self.move_forward(cache_node, freq_node)
-
-                return content
-            else:
-                return not_found
+        return self.cache.get(key, not_found)
 
     def set(self, key, report_type=None, value=None):
-        with self.lock:
-            if key in self.cache:
-                cache_node = self.cache[key]
-                if report_type:
-                    cache_node.content[report_type].add(value)
-                else:
-                    cache_node.content = value
-            else:
-                if len(self.cache) >= self.capacity:
-                    self.dump_cache()
-
-                self.create_cache_node(key, report_type, value)
+        if report_type:
+            content = self.cache.get(key, None)
+            if content is None:
+                content = defaultdict(SetOrdered)
+            content[report_type].add(value)
+            value = content
+        self.cache.insert(key, value)
 
     def __contains__(self, key):
         return key in self.cache
 
-    def move_forward(self, cache_node, freq_node):
-        if freq_node.nxt is None or freq_node.nxt.freq != freq_node.freq + 1:
-            target_freq_node = FreqNode(freq_node.freq + 1, None, None)
-            target_empty = True
-        else:
-            target_freq_node = freq_node.nxt
-            target_empty = False
-
-        cache_node.free_myself()
-        target_freq_node.append_cache_to_tail(cache_node)
-
-        if target_empty:
-            freq_node.insert_after_me(target_freq_node)
-
-        if freq_node.count_caches() == 0:
-            if self.freq_link_head == freq_node:
-                self.freq_link_head = target_freq_node
-
-            freq_node.remove()
 
-    def dump_cache(self):
-        head_freq_node = self.freq_link_head
-        self.cache.pop(head_freq_node.cache_head.key)  # type: ignore
-        head_freq_node.pop_head_cache()  # type: ignore
-
-        if head_freq_node.count_caches() == 0:  # type: ignore
-            self.freq_link_head = head_freq_node.nxt  # type: ignore
-            head_freq_node.remove()  # type: ignore
-
-    def create_cache_node(self, key, report_type, value):
-        cache_node = CacheNode(
-            key=key, report_type=report_type,
-            value=value, freq_node=None, pre=None, nxt=None)
-        self.cache[key] = cache_node
-
-        if self.freq_link_head is None or self.freq_link_head.freq != 0:
-            new_freq_node = FreqNode(0, None, None)
-            new_freq_node.append_cache_to_tail(cache_node)
-
-            if self.freq_link_head is not None:
-                self.freq_link_head.insert_before_me(new_freq_node)
-
-            self.freq_link_head = new_freq_node
-        else:
-            self.freq_link_head.append_cache_to_tail(cache_node)
-
-    def get_sorted_cache_keys(self):
-        result = [(i, freq.freq_node.freq) for i, freq in self.cache.items()]
-        result.sort(key=lambda x: -x[1])
-        return result
-
-    def get_average_frequency(self):
-        return mean(freq.freq_node.freq for freq in self.cache.values())
+LFUCache = DistanceCache
 
 
 class DummyLFU:
@@ -211,7 +42,9 @@ def __init__(self, *args, **kwargs):
         pass
 
     set = __init__
-    get = __init__
+
+    def get(self, *args, **kwargs):
+        return not_found
 
     def __contains__(self, key):
         return False

pyproject.toml

@@ -6,6 +6,7 @@ build-backend = "flit_core.buildapi"
 name = "deepdiff"
 version = "9.0.0"
 dependencies = [
+  "cachebox>=5.2,<6",
   "orderly-set>=5.5.0,<6",
 ]
 requires-python = ">=3.10"

tests/test_lfucache.py

@@ -1,33 +1,35 @@
 import random
-import pytest
 import concurrent.futures
-from deepdiff.lfucache import LFUCache
-
-
-class TestLFUcache:
-
-    @pytest.mark.parametrize("items, size, expected_results, expected_freq", [
-        (['a', 'a', 'b', 'a', 'c', 'b', 'd'], 3, [('b', 2), ('c', 1), ('d', 1)], '1.333'),
-        (['a', 'a', 'b', 'a', 'c', 'b', 'd', 'e', 'c', 'b'], 3, [('b', 3), ('d', 1), ('e', 1)], '1.666'),
-        (['a', 'a', 'b', 'a', 'c', 'b', 'd', 'e', 'c', 'b', 'b', 'c', 'd', 'b'], 3, [('b', 5), ('c', 3), ('d', 2)], '3.333'),
-    ])
-    def test_lfu(self, items, size, expected_results, expected_freq, benchmark):
-        benchmark(self._test_lfu, items, size, expected_results, expected_freq)
-
-    def _test_lfu(self, items, size, expected_results, expected_freq):
-        lfucache = LFUCache(size)
-        for item in items:
-            lfucache.set(item, value='{}_cached'.format(item))
-        for item in items:
-            lfucache.get(item)
-        results = lfucache.get_sorted_cache_keys()
-        assert expected_results == results
-        freq = lfucache.get_average_frequency()
-        assert expected_freq == str(freq)[:5]
+from deepdiff.helper import not_found
+from deepdiff.lfucache import DistanceCache
+
+
+class TestDistanceCache:
+
+    def test_lru_cache(self, benchmark):
+        benchmark(self._test_lru_cache)
+
+    def _test_lru_cache(self):
+        cache = DistanceCache(2)
+        cache.set('a', value='a_cached')
+        cache.set('b', value='b_cached')
+        assert 'a' in cache
+        assert cache.get('a') == 'a_cached'
+        cache.set('c', value='c_cached')
+        assert cache.get('a') == 'a_cached'
+        assert cache.get('b') is not_found
+        assert cache.get('c') == 'c_cached'
+        assert cache.get('missing') is not_found
+
+    def test_report_type_values_are_accumulated(self):
+        cache = DistanceCache(2)
+        cache.set('a', report_type='values_changed', value='root[0]')
+        cache.set('a', report_type='values_changed', value='root[1]')
+        assert cache.get('a') == {'values_changed': {'root[0]', 'root[1]'}}
 
     def test_get_multithreading(self):
         keys = 'aaaaaaaaaaaaaaaaaaaaaaaaaaabbc'
-        lfucache = LFUCache(2)
+        cache = DistanceCache(2)
 
         def _do_set(cache, key):
             cache.set(key, value='{}_cached'.format(key))
@@ -45,6 +47,6 @@ def _random_func(cache, key):
             return random.choice([_do_get, _do_get, _do_set])(cache, key)
 
         with concurrent.futures.ThreadPoolExecutor(max_workers=30) as executor:
-            futures = (executor.submit(_random_func, lfucache, key) for key in _key_gen())
+            futures = (executor.submit(_random_func, cache, key) for key in _key_gen())
             for future in concurrent.futures.as_completed(futures):
                 future.result()