rest25/library/filecmp.rst => rest262/library/filecmp.rst
3=================================================
4
5.. module:: filecmp
6   :synopsis: Compare files efficiently.
7.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
8
9
10The :mod:`filecmp` module defines functions to compare files and directories,
n11-with various optional time/correctness trade-offs.
n11+with various optional time/correctness trade-offs. For comparing files,
12+see also the :mod:`difflib` module.
12
13The :mod:`filecmp` module defines the following functions:
14
15
16.. function:: cmp(f1, f2[, shallow])
17
18   Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
19   ``False`` otherwise.
25   their :func:`os.stat` signature changes.
26
27   Note that no external programs are called from this function, giving it
28   portability and efficiency.
29
30
31.. function:: cmpfiles(dir1, dir2, common[, shallow])
32
n33-   Returns three lists of file names: *match*, *mismatch*, *errors*.  *match*
n34+   Compare the files in the two directories *dir1* and *dir2* whose names are
34-   contains the list of files match in both directories, *mismatch* includes the
35+   given by *common*.
35-   names of those that don't, and *errros* lists the names of files which could not
36-   be compared.  Files may be listed in *errors* because the user may lack
37-   permission to read them or many other reasons, but always that the comparison
38-   could not be done for some reason.
39
n40-   The *common* parameter is a list of file names found in both directories. The
n37+   Returns three lists of file names: *match*, *mismatch*,
38+   *errors*.  *match* contains the list of files that match, *mismatch* contains
39+   the names of those that don't, and *errors* lists the names of files which
40+   could not be compared.  Files are listed in *errors* if they don't exist in
41+   one of the directories, the user lacks permission to read them or if the
42+   comparison could not be done for some other reason.
43+ 
41-   *shallow* parameter has the same meaning and default value as for
44+   The *shallow* parameter has the same meaning and default value as for
42   :func:`filecmp.cmp`.
n46+ 
47+   For example, ``cmpfiles('a', 'b', ['c', 'd/e'])`` will compare ``a/c`` with
48+   ``b/c`` and ``a/d/e`` with ``b/d/e``.  ``'c'`` and ``'d/e'`` will each be in
49+   one of the three returned lists.
50+ 
43
44Example::
45
46   >>> import filecmp
n47-   >>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
n55+   >>> filecmp.cmp('undoc.rst', 'undoc.rst')
48   True
n49-   >>> filecmp.cmp('libundoc.tex', 'lib.tex')
n57+   >>> filecmp.cmp('undoc.rst', 'index.rst')
50   False
51
52
53.. _dircmp-objects:
54
55The :class:`dircmp` class
56-------------------------
57
60
61.. class:: dircmp(a, b[, ignore[, hide]])
62
63   Construct a new directory comparison object, to compare the directories *a* and
64   *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
65   'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
66   os.pardir]``.
67
n68-The :class:`dircmp` class provides the following methods:
n76+   The :class:`dircmp` class provides the following methods:
69
70
n71-.. method:: dircmp.report()
n79+   .. method:: report()
72
n73-   Print (to ``sys.stdout``) a comparison between *a* and *b*.
n81+      Print (to ``sys.stdout``) a comparison between *a* and *b*.
74
75
n76-.. method:: dircmp.report_partial_closure()
n84+   .. method:: report_partial_closure()
77
n78-   Print a comparison between *a* and *b* and common immediate subdirectories.
n86+      Print a comparison between *a* and *b* and common immediate
87+      subdirectories.
79
80
n81-.. method:: dircmp.report_full_closure()
n90+   .. method:: report_full_closure()
82
n83-   Print a comparison between *a* and *b* and common  subdirectories (recursively).
n92+      Print a comparison between *a* and *b* and common subdirectories
93+      (recursively).
84
n85-The :class:`dircmp` offers a number of interesting attributes that may be used
n95+   The :class:`dircmp` offers a number of interesting attributes that may be
86-to get various bits of information about the directory trees being compared.
96+   used to get various bits of information about the directory trees being
97+   compared.
87
n88-Note that via :meth:`__getattr__` hooks, all attributes are computed lazily, so
n99+   Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
89-there is no speed penalty if only those attributes which are lightweight to
100+   so there is no speed penalty if only those attributes which are lightweight
90-compute are used.
101+   to compute are used.
91
92
n93-.. attribute:: dircmp.left_list
n104+   .. attribute:: left_list
94
n95-   Files and subdirectories in *a*, filtered by *hide* and *ignore*.
n106+      Files and subdirectories in *a*, filtered by *hide* and *ignore*.
96
97
n98-.. attribute:: dircmp.right_list
n109+   .. attribute:: right_list
99
n100-   Files and subdirectories in *b*, filtered by *hide* and *ignore*.
n111+      Files and subdirectories in *b*, filtered by *hide* and *ignore*.
101
102
n103-.. attribute:: dircmp.common
n114+   .. attribute:: common
104
n105-   Files and subdirectories in both *a* and *b*.
n116+      Files and subdirectories in both *a* and *b*.
106
107
n108-.. attribute:: dircmp.left_only
n119+   .. attribute:: left_only
109
n110-   Files and subdirectories only in *a*.
n121+      Files and subdirectories only in *a*.
111
112
n113-.. attribute:: dircmp.right_only
n124+   .. attribute:: right_only
114
n115-   Files and subdirectories only in *b*.
n126+      Files and subdirectories only in *b*.
116
117
n118-.. attribute:: dircmp.common_dirs
n129+   .. attribute:: common_dirs
119
n120-   Subdirectories in both *a* and *b*.
n131+      Subdirectories in both *a* and *b*.
121
122
n123-.. attribute:: dircmp.common_files
n134+   .. attribute:: common_files
124
n125-   Files in both *a* and *b*
n136+      Files in both *a* and *b*
126
127
n128-.. attribute:: dircmp.common_funny
n139+   .. attribute:: common_funny
129
n130-   Names in both *a* and *b*, such that the type differs between the directories,
n141+      Names in both *a* and *b*, such that the type differs between the
131-   or names for which :func:`os.stat` reports an error.
142+      directories, or names for which :func:`os.stat` reports an error.
132
133
n134-.. attribute:: dircmp.same_files
n145+   .. attribute:: same_files
135
n136-   Files which are identical in both *a* and *b*.
n147+      Files which are identical in both *a* and *b*.
137
138
n139-.. attribute:: dircmp.diff_files
n150+   .. attribute:: diff_files
140
n141-   Files which are in both *a* and *b*, whose contents differ.
n152+      Files which are in both *a* and *b*, whose contents differ.
142
143
n144-.. attribute:: dircmp.funny_files
n155+   .. attribute:: funny_files
145
n146-   Files which are in both *a* and *b*, but could not be compared.
n157+      Files which are in both *a* and *b*, but could not be compared.
147
148
n149-.. attribute:: dircmp.subdirs
n160+   .. attribute:: subdirs
150
t151-   A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
t162+      A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
152
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op