← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/filecmp.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/filecmp.rst
 
1
 
 
2
:mod:`filecmp` --- File and Directory Comparisons
 
3
=================================================
 
4
 
 
5
.. module:: filecmp
 
6
   :synopsis: Compare files efficiently.
 
7
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
8
 
 
9
 
 
10
The :mod:`filecmp` module defines functions to compare files and directories,
 
11
with various optional time/correctness trade-offs. For comparing files,
 
12
see also the :mod:`difflib` module.
 
13
 
 
14
The :mod:`filecmp` module defines the following functions:
 
15
 
 
16
 
 
17
.. function:: cmp(f1, f2[, shallow])
 
18
 
 
19
   Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
 
20
   ``False`` otherwise.
 
21
 
 
22
   Unless *shallow* is given and is false, files with identical :func:`os.stat`
 
23
   signatures are taken to be equal.
 
24
 
 
25
   Files that were compared using this function will not be compared again unless
 
26
   their :func:`os.stat` signature changes.
 
27
 
 
28
   Note that no external programs are called from this function, giving it
 
29
   portability and efficiency.
 
30
 
 
31
 
 
32
.. function:: cmpfiles(dir1, dir2, common[, shallow])
 
33
 
 
34
   Returns three lists of file names: *match*, *mismatch*, *errors*.  *match*
 
35
   contains the list of files match in both directories, *mismatch* includes the
 
36
   names of those that don't, and *errros* lists the names of files which could not
 
37
   be compared.  Files may be listed in *errors* because the user may lack
 
38
   permission to read them or many other reasons, but always that the comparison
 
39
   could not be done for some reason.
 
40
 
 
41
   The *common* parameter is a list of file names found in both directories. The
 
42
   *shallow* parameter has the same meaning and default value as for
 
43
   :func:`filecmp.cmp`.
 
44
 
 
45
Example::
 
46
 
 
47
   >>> import filecmp
 
48
   >>> filecmp.cmp('undoc.rst', 'undoc.rst')
 
49
   True
 
50
   >>> filecmp.cmp('undoc.rst', 'index.rst')
 
51
   False
 
52
 
 
53
 
 
54
.. _dircmp-objects:
 
55
 
 
56
The :class:`dircmp` class
 
57
-------------------------
 
58
 
 
59
:class:`dircmp` instances are built using this constructor:
 
60
 
 
61
 
 
62
.. class:: dircmp(a, b[, ignore[, hide]])
 
63
 
 
64
   Construct a new directory comparison object, to compare the directories *a* and
 
65
   *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
 
66
   'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
 
67
   os.pardir]``.
 
68
 
 
69
   The :class:`dircmp` class provides the following methods:
 
70
 
 
71
 
 
72
   .. method:: report()
 
73
 
 
74
      Print (to ``sys.stdout``) a comparison between *a* and *b*.
 
75
 
 
76
 
 
77
   .. method:: report_partial_closure()
 
78
 
 
79
      Print a comparison between *a* and *b* and common immediate
 
80
      subdirectories.
 
81
 
 
82
 
 
83
   .. method:: report_full_closure()
 
84
 
 
85
      Print a comparison between *a* and *b* and common subdirectories
 
86
      (recursively).
 
87
 
 
88
   The :class:`dircmp` offers a number of interesting attributes that may be
 
89
   used to get various bits of information about the directory trees being
 
90
   compared.
 
91
 
 
92
   Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
 
93
   so there is no speed penalty if only those attributes which are lightweight
 
94
   to compute are used.
 
95
 
 
96
 
 
97
   .. attribute:: left_list
 
98
 
 
99
      Files and subdirectories in *a*, filtered by *hide* and *ignore*.
 
100
 
 
101
 
 
102
   .. attribute:: right_list
 
103
 
 
104
      Files and subdirectories in *b*, filtered by *hide* and *ignore*.
 
105
 
 
106
 
 
107
   .. attribute:: common
 
108
 
 
109
      Files and subdirectories in both *a* and *b*.
 
110
 
 
111
 
 
112
   .. attribute:: left_only
 
113
 
 
114
      Files and subdirectories only in *a*.
 
115
 
 
116
 
 
117
   .. attribute:: right_only
 
118
 
 
119
      Files and subdirectories only in *b*.
 
120
 
 
121
 
 
122
   .. attribute:: common_dirs
 
123
 
 
124
      Subdirectories in both *a* and *b*.
 
125
 
 
126
 
 
127
   .. attribute:: common_files
 
128
 
 
129
      Files in both *a* and *b*
 
130
 
 
131
 
 
132
   .. attribute:: common_funny
 
133
 
 
134
      Names in both *a* and *b*, such that the type differs between the
 
135
      directories, or names for which :func:`os.stat` reports an error.
 
136
 
 
137
 
 
138
   .. attribute:: same_files
 
139
 
 
140
      Files which are identical in both *a* and *b*.
 
141
 
 
142
 
 
143
   .. attribute:: diff_files
 
144
 
 
145
      Files which are in both *a* and *b*, whose contents differ.
 
146
 
 
147
 
 
148
   .. attribute:: funny_files
 
149
 
 
150
      Files which are in both *a* and *b*, but could not be compared.
 
151
 
 
152
 
 
153
   .. attribute:: subdirs
 
154
 
 
155
      A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
 
156