199 lines
5.5 KiB
ReStructuredText
199 lines
5.5 KiB
ReStructuredText
:mod:`filecmp` --- File and Directory Comparisons
|
|
=================================================
|
|
|
|
.. module:: filecmp
|
|
:synopsis: Compare files efficiently.
|
|
|
|
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
|
|
|
|
**Source code:** :source:`Lib/filecmp.py`
|
|
|
|
--------------
|
|
|
|
The :mod:`filecmp` module defines functions to compare files and directories,
|
|
with various optional time/correctness trade-offs. For comparing files,
|
|
see also the :mod:`difflib` module.
|
|
|
|
The :mod:`filecmp` module defines the following functions:
|
|
|
|
|
|
.. function:: cmp(f1, f2, shallow=True)
|
|
|
|
Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
|
|
``False`` otherwise.
|
|
|
|
If *shallow* is true, files with identical :func:`os.stat` signatures are
|
|
taken to be equal. Otherwise, the contents of the files are compared.
|
|
|
|
Note that no external programs are called from this function, giving it
|
|
portability and efficiency.
|
|
|
|
This function uses a cache for past comparisons and the results,
|
|
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)
|
|
|
|
Compare the files in the two directories *dir1* and *dir2* whose names are
|
|
given by *common*.
|
|
|
|
Returns three lists of file names: *match*, *mismatch*,
|
|
*errors*. *match* contains the list of files that match, *mismatch* contains
|
|
the names of those that don't, and *errors* lists the names of files which
|
|
could not be compared. Files are listed in *errors* if they don't exist in
|
|
one of the directories, the user lacks permission to read them or if the
|
|
comparison could not be done for some other reason.
|
|
|
|
The *shallow* parameter has the same meaning and default value as for
|
|
:func:`filecmp.cmp`.
|
|
|
|
For example, ``cmpfiles('a', 'b', ['c', 'd/e'])`` will compare ``a/c`` with
|
|
``b/c`` and ``a/d/e`` with ``b/d/e``. ``'c'`` and ``'d/e'`` will each be in
|
|
one of the three returned lists.
|
|
|
|
|
|
.. function:: clear_cache()
|
|
|
|
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:
|
|
|
|
The :class:`dircmp` class
|
|
-------------------------
|
|
|
|
.. class:: dircmp(a, b, ignore=None, hide=None)
|
|
|
|
Construct a new directory comparison object, to compare the directories *a*
|
|
and *b*. *ignore* is a list of names to ignore, and defaults to
|
|
:attr:`filecmp.DEFAULT_IGNORES`. *hide* is a list of names to hide, and
|
|
defaults to ``[os.curdir, os.pardir]``.
|
|
|
|
The :class:`dircmp` class compares files by doing *shallow* comparisons
|
|
as described for :func:`filecmp.cmp`.
|
|
|
|
The :class:`dircmp` class provides the following methods:
|
|
|
|
.. method:: report()
|
|
|
|
Print (to :data:`sys.stdout`) a comparison between *a* and *b*.
|
|
|
|
.. method:: report_partial_closure()
|
|
|
|
Print a comparison between *a* and *b* and common immediate
|
|
subdirectories.
|
|
|
|
.. method:: report_full_closure()
|
|
|
|
Print a comparison between *a* and *b* and common subdirectories
|
|
(recursively).
|
|
|
|
The :class:`dircmp` class offers a number of interesting attributes that may be
|
|
used to get various bits of information about the directory trees being
|
|
compared.
|
|
|
|
Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
|
|
so there is no speed penalty if only those attributes which are lightweight
|
|
to compute are used.
|
|
|
|
|
|
.. attribute:: left
|
|
|
|
The directory *a*.
|
|
|
|
|
|
.. attribute:: right
|
|
|
|
The directory *b*.
|
|
|
|
|
|
.. attribute:: left_list
|
|
|
|
Files and subdirectories in *a*, filtered by *hide* and *ignore*.
|
|
|
|
|
|
.. attribute:: right_list
|
|
|
|
Files and subdirectories in *b*, filtered by *hide* and *ignore*.
|
|
|
|
|
|
.. attribute:: common
|
|
|
|
Files and subdirectories in both *a* and *b*.
|
|
|
|
|
|
.. attribute:: left_only
|
|
|
|
Files and subdirectories only in *a*.
|
|
|
|
|
|
.. attribute:: right_only
|
|
|
|
Files and subdirectories only in *b*.
|
|
|
|
|
|
.. attribute:: common_dirs
|
|
|
|
Subdirectories in both *a* and *b*.
|
|
|
|
|
|
.. attribute:: common_files
|
|
|
|
Files in both *a* and *b*.
|
|
|
|
|
|
.. attribute:: common_funny
|
|
|
|
Names in both *a* and *b*, such that the type differs between the
|
|
directories, or names for which :func:`os.stat` reports an error.
|
|
|
|
|
|
.. attribute:: same_files
|
|
|
|
Files which are identical in both *a* and *b*, using the class's
|
|
file comparison operator.
|
|
|
|
|
|
.. attribute:: diff_files
|
|
|
|
Files which are in both *a* and *b*, whose contents differ according
|
|
to the class's file comparison operator.
|
|
|
|
|
|
.. attribute:: funny_files
|
|
|
|
Files which are in both *a* and *b*, but could not be compared.
|
|
|
|
|
|
.. attribute:: subdirs
|
|
|
|
A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp`
|
|
objects.
|
|
|
|
.. attribute:: DEFAULT_IGNORES
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
List of directories ignored by :class:`dircmp` by default.
|
|
|
|
|
|
Here is a simplified example of using the ``subdirs`` attribute to search
|
|
recursively through two directories to show common different files::
|
|
|
|
>>> from filecmp import dircmp
|
|
>>> def print_diff_files(dcmp):
|
|
... for name in dcmp.diff_files:
|
|
... print("diff_file %s found in %s and %s" % (name, dcmp.left,
|
|
... dcmp.right))
|
|
... for sub_dcmp in dcmp.subdirs.values():
|
|
... print_diff_files(sub_dcmp)
|
|
...
|
|
>>> dcmp = dircmp('dir1', 'dir2') # doctest: +SKIP
|
|
>>> print_diff_files(dcmp) # doctest: +SKIP
|
|
|