Using __repr__ or __str__ for own printable class?

[Donn Cave]

Quoth Steven Taschuk <staschuk at telusplanet.net>:
| Quoth Donn Cave:
| > Quoth Steven Taschuk <staschuk at telusplanet.net>:
|   [...]
|>| 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?
|> 
|> The data vs. object distinction is the best I can do so far.  It
|> isn't all that fuzzy, either.  It's vague, in that it applies to
|> a very high level of generality, but it does not seem ambiguous
|> to me.
|
| Calling for __str__ to return the data of the object might imply,
| undesirably imho, that, for example, str(file('foo')) should
| return a string containing the contents of the file.  Likewise
| for, e.g., database connection objects.
|
| So it seems a little fuzzy to me, in that it needs qualification
| to avoid such implications.

That's interesting, that example sort of occurred to me as one
that demonstrates the principle.  I wasn't thinking of "file",
actually, rather some hypothetical object that represents a file
("file" represents an I/O stream.)  But we're definitely on the
same page here.  Your objection is probably reasonable, though
arguable, but the thing is, we're on ground here that we can
reason about.  It may be underspecified, but it isn't the kind
of thing I call fuzzy.  I agree that it's worth a brief sentence
or two, but at some point one has to leave it to the programmer's
judgement what's actually going to be desirable.

| Reading this thread has made me wonder whether current practice is
| uniform.  It would not be desirable imho for the language
| reference to say, "people do different things with __repr__,
| including <list of three things>", and not endow one of them with
| some normative weight.
|
| ... How about this?  (Draft.)
|
| __repr__(self)
|
|     Called by the repr() built-in function and by string conversions
|     (reverse quotes) to compute a string representation of the object.
|     The return value must be a string object.
|
|     The primary audience of this representation is programmers seeking
|     detailed information about the object for debugging or inspection
|     purposes; thus it is important that the representation be
|     information-rich and unambiguous.  This representation should not
|     usually be parsed or manipulated by other code.
|
|     In some cases the best information-rich and unambiguous
|     representation is a Python expression which evaluates to the
|     object, that is, for eval(repr(x)) to return an object which is
|     equal to x (given an appropriate environment).  For example, the
|     built-in numeric, sequence, and mapping types all have such
|     __repr__ implementations.  Where such a representation is
|     infeasible or undesirable, this method should return a string of
|     the form "<...some useful description...>".
|
|     (... examples ...)
|
| __str__(self)
|
|     Called by the str() built-in function and by the print statement
|     to compute a string representation of an object.  The return value
|     must be a string object.
|
|     This differs from __repr__() in that its primary audience is not a
|     programmer inspecting the object during debugging.  What the
|     primary audience is depends on the object: the __str__
|     representation might, for example, be designed for display to a
|     user of the application, or for processing by other code which
|     requires a string.  Thus this representation might be less
|     detailed, less precise, or in some way more convenient than that
|     computed by __repr__.
|
|     (... examples ...)

That's a big improvement over the current documentation.  The __str__
section could use more work.  I really think the last sentence is as
wrong as it is right - sure it might be, or it might be more detailed
etc.  Cf. rfc822.Message.__str__ - complete contents of the header.
In what way is that less detailed or precise, or more convenient?
It is however exactly the ``data''.

Your __repr__ draft works fine for me.

	Donn Cave, donn at drizzle.com