#15269: document dircmp.left and right, and add tests for them.
Patch by Chris Jerdonek.
diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst
index f84cfa9..de20fb1 100644
--- a/Doc/library/filecmp.rst
+++ b/Doc/library/filecmp.rst
@@ -106,6 +106,16 @@
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*.
@@ -169,3 +179,18 @@
A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp`
objects.
+
+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')
+ >>> print_diff_files(dcmp)
+
diff --git a/Lib/test/test_filecmp.py b/Lib/test/test_filecmp.py
index 9b5725d..0959979 100644
--- a/Lib/test/test_filecmp.py
+++ b/Lib/test/test_filecmp.py
@@ -98,7 +98,10 @@
def test_dircmp(self):
# Check attributes for comparison of two identical directories
- d = filecmp.dircmp(self.dir, self.dir_same)
+ left_dir, right_dir = self.dir, self.dir_same
+ d = filecmp.dircmp(left_dir, right_dir)
+ self.assertEqual(d.left, left_dir)
+ self.assertEqual(d.right, right_dir)
if self.caseinsensitive:
self.assertEqual([d.left_list, d.right_list],[['file'], ['FiLe']])
else:
@@ -109,7 +112,10 @@
self.assertEqual(d.diff_files, [])
# Check attributes for comparison of two different directories
- d = filecmp.dircmp(self.dir, self.dir_diff)
+ left_dir, right_dir = self.dir, self.dir_diff
+ d = filecmp.dircmp(left_dir, right_dir)
+ self.assertEqual(d.left, left_dir)
+ self.assertEqual(d.right, right_dir)
self.assertEqual(d.left_list, ['file'])
self.assertTrue(d.right_list == ['file', 'file2'])
self.assertEqual(d.common, ['file'])