Using __repr__ or __str__ for own printable class?

[Steven Taschuk]

Quoth Donn Cave:
> Quoth Steven Taschuk <staschuk at telusplanet.net>:
> | Quoth Tim Peters:
> |> [...] What to do with each
> |> method is in large part art, and the teachable seem to do OK learning by
> |> example.  [...]
> |
> | I wonder, then, whether the docs would benefit from being
> | augmented with a few examples.
> |
> | Donn -- would that improve their clarity in your view?
> 
> No, but if _replaced_ with a few examples, maybe.  I mean, if you
> accept my contention that the documentation misrepresents the
> actual usage of these functions, it's hard to remedy that with
> an example.  Unless maybe hostile examples, like a repr that
> spews out pages of state, but I assume that would not be the idea.

*chuckle*  Indeed.  (Though in my coding "pages of state" is very
uncommon; it really only occurs for large containers, which have
very simple internal structure.)

Looking back over your posts in this thread, I see a few kinds of
objection to the current documentation.

First, there's the description of __repr__ and __str__ in terms of
fuzzy properties their output should have -- "informal" vs
"official", "convenient" vs "complete", and the like; you feel
that these descriptions are unclear.  For this problem, a few
examples would certainly help to clarify the intended meanings of
these terms.  It might also help to give examples of where these
representations would normally be used -- for debugging output,
for normal logging, for display to the user of the application.

Second, I have some sense that you feel these terms are not merely
unclear but misleading or wrong.  Is this true?  If so, do you
have alternative fuzzy terms in mind (the "data" vs the "object"),
or would you prefer that the documentation avoid fuzzy terms
entirely, and only give examples?

Third, you (and others) specifically object to the notion that if
possible one should have eval(repr(x)) == x.  Would you want this
notion to be omitted entirely?  Mentioned as possible and
sometimes good?  Described as highly desirable, though sometimes
infeasible?  (Imho the docs currently do this last, though perhaps
they could do so more clearly.)

Have I missed anything?

(I solicit comments from everybody, of course, not just Donn.)

  [...]

-- 
Steven Taschuk                                                 o- @
staschuk at telusplanet.net                                      7O   )
                                                               "  (