Clarify manifest cache reuse

Author: kevinjqliu

pyiceberg/manifest.py

@@ -892,9 +892,9 @@ def __hash__(self) -> int:
         return hash(self.manifest_path)
 
 
-# Global cache for ManifestFile objects, keyed by manifest_path. This
-# deduplicates ManifestFile objects across manifest lists, which commonly share
-# manifests after append operations.
+# Global cache for ManifestFile objects, keyed by manifest_path. This reuses
+# ManifestFile objects across manifest lists, which commonly share manifests
+# after append operations.
 class _ManifestCache:
     DEFAULT_SIZE = 128
 
@@ -921,7 +921,7 @@ def clear(self) -> None:
             if self._cache is not None:
                 self._cache.clear()
 
-    def deduplicate(self, manifest_files: list[ManifestFile]) -> tuple[ManifestFile, ...]:
+    def reuse_cached(self, manifest_files: list[ManifestFile]) -> tuple[ManifestFile, ...]:
         if self._cache is None:
             return tuple(manifest_files)
 
@@ -955,7 +955,7 @@ def clear_manifest_cache() -> None:
 
 
 def _manifests(io: FileIO, manifest_list: str) -> tuple[ManifestFile, ...]:
-    """Read manifests from a manifest list, deduplicating ManifestFile objects via cache.
+    """Read manifests from a manifest list, reusing cached ManifestFile objects.
 
     Caches individual ManifestFile objects by manifest_path. This is memory-efficient
     because consecutive manifest lists typically share most of their manifests:
@@ -981,7 +981,7 @@ def _manifests(io: FileIO, manifest_list: str) -> tuple[ManifestFile, ...]:
     file = io.new_input(manifest_list)
     manifest_files = list(read_manifest_list(file))
 
-    return _manifest_cache.deduplicate(manifest_files)
+    return _manifest_cache.reuse_cached(manifest_files)
 
 
 def read_manifest_list(input_file: InputFile) -> Iterator[ManifestFile]:

tests/benchmark/test_memory_benchmark.py

@@ -73,8 +73,8 @@ def clear_caches() -> None:
 def test_manifest_cache_memory_growth(memory_catalog: InMemoryCatalog) -> None:
     """Benchmark memory growth of manifest cache during repeated appends.
 
-    This test reproduces the issue from GitHub #2325 where each append creates
-    a new manifest list entry in the cache, causing memory to grow.
+    This test reproduces the issue from GitHub #2325 where the old cache stored
+    each manifest list result, causing memory to grow.
 
     With the old caching strategy (tuple per manifest list), memory grew as O(N²).
     With the new strategy (individual ManifestFile objects), memory grows as O(N).