Using __repr__ or __str__ for own printable class?

[Steven Taschuk]

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.

> | 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.)
> 
> It would be fine to document current practice.  __repr__ sometimes
> supports that application, on purpose.  The problem is that the
> current documentation tries to make it a requirement, as if there
> might be some penalty for not supporting it.  On the contrary,
> there is little reason to actually do this, and plenty of reasons
> not to (can't, awkwardly large, requires introspection that breaks
> abstractions, etc.)  I don't think the documentation needs to get
> into that, just document current practice.

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 ...)

(It might even be preferable to split __str__ and __repr__ out
into their own section, "Customizing string representations", with
a more complete account.)

-- 
Steven Taschuk                                     staschuk at telusplanet.net
Receive them ignorant; dispatch them confused.  (Weschler's Teaching Motto)