[IPython-dev] New display methods, should we fine-tune our naming decision?

[Brian Granger]

Robert,

On Tue, Feb 1, 2011 at 11:49 AM, Robert Kern <robert.kern at gmail.com> wrote:
> On 2/1/11 10:36 AM, Fernando Perez wrote:
>> Hi folks,
>>
>> I was just thinking, before the new display infrastructure starts
>> getting used too much, should we adjust our convention to use
>> __repr_html__, __repr_svg__, __repr_*__ as a naming pattern instead of
>> __html__, __svg__, etc?  My concern is two-fold:
>>
>> - the more generic names may be already in use by something else that
>> doesn't quite match our 'protocol',
>
> This is a pretty big problem particularly since there is currently no error
> recovery around the method call. There is a lot of room for error here. For
> example, the PlainTextFormatter, which uses pretty.py, specifies a
> print_method='__pretty__'. However, the __pretty__ method has a distinctly
> different signature that takes arguments. Fortunately, the __call__ was
> overridden to ignore the print_method and just use the pretty.py machinery
> directly. These kinds of mistakes are easy to make, and it bakes in a certain
> amount of brittleness into the system.

Yes, there is definitely some brittleness right now in the design.  We
should definitely add additional errors checking in appropriate
places.

>> or python may in the future
>> (though this is probably needless paranoia) choose to add them.
>
> Python reserves __foo__ names for itself and requests that third party packages
> do not make their own. Third party packages violate this pretty frequently, but
> that doesn't mean it's kosher. SAGE does something sensible and uses single
> underscores on either side.

I am aware of the official status of the __foo__ names, but it is
tempting as i) the chances of Python using these names in minimal and
ii) other products do this in a way that is consistent with our usage
(the __html__ examples I gave earlier).  But in terms of alternate
names that don't use the __foo__ notation:

_repr_html_
_html_ - problem is that SAGE uses this format with possibly different meaning.
_html   - problem is that sympy uses this format with possibly
different meaning.
???

> Personally, I don't want to ever change one of my classes to get it printed
> nicely for IPython. That's an inversion of responsibilities that I find
> difficult to swallow (especially for HTML and JSON that are best done using
> particular libraries). Instead, I want the to write formatter functions and
> register them for the appropriate class. Maybe a conventional print_method could
> be a default.

> In any case, the priority as implemented is inverted; we should check for the
> print_method *after* the registered functions are checked. I, the IPython user,
> should always be able to override what the class author thought was a good idea
> at the time. Or who implemented an __html__ method for a different system and a
> different calling convention.

I got the idea to look for the special print methods first and then
the print function from IPython.externals.pretty itself. The first
thing the pretty printer does is this:

            if hasattr(obj_class, '__pretty__'):
                return obj_class.__pretty__(obj, self, cycle)

When I implemented the other printers, I wanted to make them as
similar to pretty as possible, so I stuck with this ordering of
priorities.  I don't mind using the other priority order as long as we
are consistent and modify pretty to use the same order.  Is this what
you would recommend Robert?

Cheers,

Brian


> --
> Robert Kern
>
> "I have come to believe that the whole world is an enigma, a harmless enigma
>  that is made terrible by our own mad attempt to interpret it as though it had
>  an underlying truth."
>   -- Umberto Eco
>
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>



-- 
Brian E. Granger, Ph.D.
Assistant Professor of Physics
Cal Poly State University, San Luis Obispo
bgranger at calpoly.edu
ellisonbg at gmail.com