[docs] [issue15269] Document dircmp.left and dircmp.right

Chris Jerdonek report at bugs.python.org
Sun Jul 22 01:11:37 CEST 2012

Chris Jerdonek <chris.jerdonek at gmail.com> added the comment:

> Given that we have self.left_list and self.left_only ( and self.right_list and self.right_only), I am not sure how adding self.left/self.right is going to add more meaning?

It adds more meaning because you can't construct self.left and self.right from self.left_list, self.left_only, etc.  The latter are children inside the two directories (expressed relatively), while the former are the parent directories.  So it's strictly different information.

As I said, there are cases where being able to access the left and right directories simplifies the calling code in a way that is not otherwise possible.

For example, if you are recursively comparing directories, it is natural to recurse on the dircmp.subdirs attribute, whose values are dircmp instances.  The caller did not construct these instances, so there is no other way to obtain the left and right directories that were used to construct those instances.  Otherwise, the caller has to construct the dircmp instances manually from common_dirs, which reduces the usefulness of the subdirs attribute and the scenarios in which it can be used.

Secondly, there are cases where it is natural to pass dircmp instances around between functions.  If one cannot recover the left and right directories from the dircmp instances, then one would also have to pass the left and right directories to those functions, along with the dircmp instances, or else pass just the left and right directories and then reconstruct the dircmp instances from those arguments, which leads to uglier code.

Thirdly, it is better to reuse existing dircmp instances where possible rather than create new ones, because of the penalty after creating a new instance of needing to recalculate the attributes.  As the documentation notes, attributes are computed lazily and cached using __getattr__(), so it's better to hold onto existing instances.

If you are still not convinced, I would like the opportunity to provide actual code examples before you close this issue.  Then you can tell me if there is an equally simple alternative that does not involve accessing left and right.

I don't see how it hurts to be able to access left and right as attributes and why you would consider concealing this information from the caller behind private attributes.  It's a common idiom for constructor arguments to be stored as public attributes.

In this case, I think it's worth documenting because the names of the attributes ("left" and "right") used to store the constructor arguments don't match the names of the constructor arguments themselves ("a" and "b").


Python tracker <report at bugs.python.org>

More information about the docs mailing list