classification
Title: document that filecmp.dircmp comparisons are "shallow"
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: chris.jerdonek, docs@python, orsenthil, python-dev
Priority: normal Keywords: easy, patch

Created on 2012-07-04 14:36 by chris.jerdonek, last changed 2012-07-23 03:58 by chris.jerdonek. This issue is now closed.

Files
File name Uploaded Description Edit
issue15250-1.patch chris.jerdonek, 2012-07-06 00:10 review
Issue15250.patch orsenthil, 2012-07-21 23:41 review
Messages (10)
msg164646 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-04 14:36
The documentation for the dircmp class doesn't say that the same_files and diff_files attributes are determined using the "shallow=True" rules described in the filecmp.cmp() and filecmp.cmpfiles().  It should say this.

For example, the documentation describes diff_files as, "Files which are in both a and b, whose contents differ."  But this isn't true since files whose contents differ aren't included if their os.stat() signatures are equal.

See also issue 12932 to allow dircmp to perform non-shallow comparisons.
msg166090 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2012-07-21 23:41
Thanks for this report. I saw that filecmp.rst could be improved a bit further too. I added some additional improvements to the docs in addition to the one you mentioned in the patch.
msg166094 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-22 00:13
For attribution purposes and to keep the issue focused, shouldn't those other changes be added as part of a separate issue?

The changes you added are much larger than mine, and address cosmetic issues and other issues unrelated to the original point about dircmp comparisons being "shallow".
msg166096 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2012-07-22 02:30
If by attribution, if you mean, proper mention of credits/ acks, during the
commit, I shall add it. Also, I agree that "shallow" should be documented.
But there were few more places which were lacking, so I ended up with
expanding docs after reading the code. I can commit in two phases, if it is
desired or commit yours and then make the other  documentation
improvements. Thanks!
msg166192 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-23 00:55
Thanks, Senthil.  I would prefer if you created a new issue in the tracker for your additional changes, and then committed your changes as part of that issue.  By attribution, I was referencing the "Patch by Chris Jerdonek" which can go in the commit message and Misc/NEWS for this issue.  I am already listed in Misc/ACKS.

To keep things simple, can you perhaps review my original patch as is?  If you would like, I would be happy to provide feedback separately on your own changes.
msg166194 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2012-07-23 01:50
Hi Chris, your patch looks good. I shall commit it now. The rest of the documentation changes can go in another patch. Thanks!
msg166198 - (view) Author: Roundup Robot (python-dev) Date: 2012-07-23 02:33
New changeset f6ce142c2fce by Senthil Kumaran in branch '3.2':
- Issue #15250: Document that filecmp.dircmp compares files shallowly. Patch contributed by Chris Jerdonek.
http://hg.python.org/cpython/rev/f6ce142c2fce

New changeset d2a49ee77b6f by Senthil Kumaran in branch 'default':
- Issue #15250: Document that filecmp.dircmp compares files shallowly. Patch contributed by Chris Jerdonek.
http://hg.python.org/cpython/rev/d2a49ee77b6f
msg166199 - (view) Author: Roundup Robot (python-dev) Date: 2012-07-23 02:36
New changeset 3921d3c71e64 by Senthil Kumaran in branch '2.7':
Issue #15250: Document that filecmp.dircmp compares files shallowly. Patch contributed by Chris Jerdonek.
http://hg.python.org/cpython/rev/3921d3c71e64
msg166201 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2012-07-23 02:40
This is taken care. Rest of documentation improvements could be dealt with in Issue15430. Thanks, Chris.
msg166204 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-07-23 03:58
Thanks a lot for committing this for me Senthil.  And thanks also for creating a separate issue for the other changes.  I appreciate it.
History
Date User Action Args
2012-07-23 03:58:05chris.jerdoneksetmessages: + msg166204
2012-07-23 02:40:22orsenthilsetstatus: open -> closed
resolution: fixed
messages: + msg166201

stage: patch review -> resolved
2012-07-23 02:36:57python-devsetmessages: + msg166199
2012-07-23 02:33:37python-devsetnosy: + python-dev
messages: + msg166198
2012-07-23 01:50:24orsenthilsetmessages: + msg166194
2012-07-23 00:55:51chris.jerdoneksetmessages: + msg166192
2012-07-22 02:30:14orsenthilsetmessages: + msg166096
2012-07-22 00:13:49chris.jerdoneksetmessages: + msg166094
2012-07-21 23:41:38orsenthilsetfiles: + Issue15250.patch

nosy: + orsenthil
messages: + msg166090

assignee: docs@python -> orsenthil
2012-07-06 00:10:59chris.jerdoneksetfiles: + issue15250-1.patch
keywords: + patch
stage: needs patch -> patch review
2012-07-05 03:23:59eric.araujosetstage: needs patch
versions: + Python 2.7, Python 3.2
2012-07-04 14:36:06chris.jerdonekcreate