[Python-checkins] cpython: whatsnew: filecmp.clear_cache, and reword description of cache in docs.

Sun Feb 2 17:33:13 CET 2014

http://hg.python.org/cpython/rev/31b37e72b98d
changeset: 88895:31b37e72b98d
user: R David Murray <rdmurray at bitdance.com>
date: Sun Feb 02 11:11:01 2014 -0500
summary:
 whatsnew: filecmp.clear_cache, and reword description of cache in docs.
files:
 Doc/library/filecmp.rst | 8 ++++----
 Doc/whatsnew/3.4.rst | 11 +++++++++++
 Lib/filecmp.py | 4 ++--
 3 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst
--- 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
--- 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
--- 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().
 
 """
 
-- 
Repository URL: http://hg.python.org/cpython
