add files

python-3.7.4-docs-html/_sources/library/filecmp.rst.txt

@@ -0,0 +1,198 @@
+: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
+