cpython/Doc/library/filecmp.rst

169 lines
4.4 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
:mod:`filecmp` --- File and Directory Comparisons
=================================================
.. module:: filecmp
:synopsis: Compare files efficiently.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`filecmp` module defines functions to compare files and directories,
2007-10-19 09:48:17 -03:00
with various optional time/correctness trade-offs. For comparing files,
see also the :mod:`difflib` module.
2007-08-15 11:28:01 -03:00
.. seealso::
Latest version of the `filecmp Python source code
<http://svn.python.org/view/python/branches/release27-maint/Lib/filecmp.py?view=markup>`_
2007-08-15 11:28:01 -03:00
The :mod:`filecmp` module defines the following functions:
.. function:: cmp(f1, f2[, shallow])
Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
``False`` otherwise.
Unless *shallow* is given and is false, files with identical :func:`os.stat`
signatures are taken to be equal.
Files that were compared using this function will not be compared again unless
their :func:`os.stat` signature changes.
Note that no external programs are called from this function, giving it
portability and efficiency.
.. function:: cmpfiles(dir1, dir2, common[, shallow])
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
2007-08-15 11:28:01 -03:00
: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.
2007-08-15 11:28:01 -03:00
Example::
>>> import filecmp
>>> filecmp.cmp('undoc.rst', 'undoc.rst')
True
>>> filecmp.cmp('undoc.rst', 'index.rst')
False
.. _dircmp-objects:
The :class:`dircmp` class
-------------------------
:class:`dircmp` instances are built using this constructor:
.. class:: dircmp(a, b[, ignore[, hide]])
Construct a new directory comparison object, to compare the directories *a* and
*b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
os.pardir]``.
The :class:`dircmp` class provides the following methods:
2007-08-15 11:28:01 -03:00
.. method:: report()
2007-08-15 11:28:01 -03:00
Print (to ``sys.stdout``) a comparison between *a* and *b*.
2007-08-15 11:28:01 -03:00
.. method:: report_partial_closure()
2007-08-15 11:28:01 -03:00
Print a comparison between *a* and *b* and common immediate
subdirectories.
2007-08-15 11:28:01 -03:00
.. method:: report_full_closure()
2007-08-15 11:28:01 -03:00
Print a comparison between *a* and *b* and common subdirectories
(recursively).
2007-08-15 11:28:01 -03:00
The :class:`dircmp` offers a number of interesting attributes that may be
used to get various bits of information about the directory trees being
compared.
2007-08-15 11:28:01 -03:00
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.
2007-08-15 11:28:01 -03:00
.. attribute:: left_list
2007-08-15 11:28:01 -03:00
Files and subdirectories in *a*, filtered by *hide* and *ignore*.
2007-08-15 11:28:01 -03:00
.. attribute:: right_list
2007-08-15 11:28:01 -03:00
Files and subdirectories in *b*, filtered by *hide* and *ignore*.
2007-08-15 11:28:01 -03:00
.. attribute:: common
2007-08-15 11:28:01 -03:00
Files and subdirectories in both *a* and *b*.
2007-08-15 11:28:01 -03:00
.. attribute:: left_only
2007-08-15 11:28:01 -03:00
Files and subdirectories only in *a*.
2007-08-15 11:28:01 -03:00
.. attribute:: right_only
2007-08-15 11:28:01 -03:00
Files and subdirectories only in *b*.
2007-08-15 11:28:01 -03:00
.. attribute:: common_dirs
2007-08-15 11:28:01 -03:00
Subdirectories in both *a* and *b*.
2007-08-15 11:28:01 -03:00
.. attribute:: common_files
2007-08-15 11:28:01 -03:00
Files in both *a* and *b*
2007-08-15 11:28:01 -03:00
.. attribute:: common_funny
2007-08-15 11:28:01 -03:00
Names in both *a* and *b*, such that the type differs between the
directories, or names for which :func:`os.stat` reports an error.
2007-08-15 11:28:01 -03:00
.. attribute:: same_files
2007-08-15 11:28:01 -03:00
Files which are identical in both *a* and *b*.
2007-08-15 11:28:01 -03:00
.. attribute:: diff_files
2007-08-15 11:28:01 -03:00
Files which are in both *a* and *b*, whose contents differ.
2007-08-15 11:28:01 -03:00
.. attribute:: funny_files
2007-08-15 11:28:01 -03:00
Files which are in both *a* and *b*, but could not be compared.
2007-08-15 11:28:01 -03:00
.. attribute:: subdirs
2007-08-15 11:28:01 -03:00
A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
2007-08-15 11:28:01 -03:00