A recent thread in comp.lang.python [1] suggests that there is some question whether the existing docs for the __str__ and __repr__ methods is clear, and whether what it says is good in the first place. The patch shows proposed changes based on the discussions in that thread. The new text treats __repr__ as a programmer-centric stringification (with eval(repr(x)) == x as a possibility, rather than a principle), and __str__ as a more general-purpose stringification-as-appropriate- to-the-object. [1] http://groups.google.com/groups?th=24b817d49ec3a59b
Logged In: YES user_id=357491 I agree with Raymond that it seems "wordy". For instance, the first changed paragraph is basically just trying to say "__repr__ should return something that can be past to 'eval' to return return the same object. If this is not possible then make its output useful to the programmer." Don't need to go on about it needing to be a "valid Python expression" and such.
Logged In: YES user_id=42839 In __str__, I would replace the whole commentary paragraph with "This string value is the result of converting the object data to string type, for use in applications that require a string and don't care about the original object per se."
Logged In: YES user_id=80475 Consider taking this back to the newsgroup to tease out some wording that everyone finds more palatable. The verbiage should be terse, factual, and general without being overly abstract or preachy. The most recent suggestion (below) is not one I would approve. The circularity and indirectness make the docs unhelpful, hard to read, and uninformative. Brett's suggestion is close to the mark.
