whatsnew: filecmp.clear_cache, and reword description of cache in docs.
diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst
index 8471a72..06d3f21 100644
--- a/Doc/library/filecmp.rst
+++ b/Doc/library/filecmp.rst
@@ -28,8 +28,8 @@
portability and efficiency.
This function uses a cache for past comparisons and the results,
- with a cache invalidation mechanism relying on stale signatures
- or by explicitly calling :func:`clear_cache`.
+ with cache entries invalidated if the :func:`os.stat` information for the
+ file changes. The entire cache may be cleared using :func:`clear_cache`.
.. function:: cmpfiles(dir1, dir2, common, shallow=True)
@@ -54,12 +54,12 @@
.. function:: clear_cache()
- .. versionadded:: 3.4
-
Clear the filecmp cache. This may be useful if a file is compared so quickly
after it is modified that it is within the mtime resolution of
the underlying filesystem.
+ .. versionadded:: 3.4
+
.. _dircmp-objects:
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index 2292297..4417f74 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -675,6 +675,17 @@
(Contributed by R. David Murray in :issue:`18891`.)
+filecmp
+-------
+
+A new :func:`~filecmp.clear_cache` function provides the ability to clear the
+:mod:`filecmp` comparison cache, which uses :func:`os.stat` information to
+determine if the file has changed since the last compare. This can be used,
+for example, if the file might have been changed and re-checked in less time
+than the resolution of a particular filesystem's file modification time field.
+(Contributed by Mark Levitt in :issue:`18149`.)
+
+
functools
---------
diff --git a/Lib/filecmp.py b/Lib/filecmp.py
index 3285288..dd5a2af 100644
--- a/Lib/filecmp.py
+++ b/Lib/filecmp.py
@@ -43,8 +43,8 @@
True if the files are the same, False otherwise.
This function uses a cache for past comparisons and the results,
- with a cache invalidation mechanism relying on stale signatures
- or by explicitly calling clear_cache().
+ with cache entries invalidated if their stat information
+ changes. The cache may be cleared by calling clear_cache().
"""