[Yt-dev] Auto-registration of callbacks and change in Callback API

[Matthew Turk]

Hi guys,

I've been helping some people learn to use yt lately, and it is
becoming apparent to me that the plotting API might need some work.
I'm mostly okay with the way the PlotCollection stuff is handled (but
see http://yt.enzotools.org/ticket/158 for more on that) but the
callbacks specifically are not terribly intuitive.  The current API
is:

p = pc.add_projection(...)
p.add_callback(ContourCallback("Temperature"))

Currently the Callback metaclass auto-registers each callback
(http://yt.enzotools.org/browser/trunk/yt/raven/Callbacks.py#L38) so
that they get imported automatically in yt.mods
(http://yt.enzotools.org/browser/trunk/yt/mods.py#L55) but this can be
done in a substantially more straightforward fashion.  (However, the
AMRData subclasses are also nearly auto-registering, which is
something I intend to explore a bit more in the future.)

I'd like to propose that each callback be given a static attribute
_type_name -- i.e., "contour", "quiver" etc, and then this be used to
access that particular callback type.  I'm torn, however, on how this
should be handled.  There are three main ways I've considered for
implementing this:

==
1. Through a .modify(type_name, *args, **kwargs) command.  You would then do:

p.modify("contour", "Temperature")

for instance, and it would add that callback.

This has the downside that, while we could provide docstrings for all
the possible callbacks, we would have to implement some introspection
to do so.  Not a huge deal, but somewhat annoying.

2. Through dictionary-style lookup, similar to DerivedQuantities:

p.modify["contour"]("Temperature")

this would allow us to have docstrings without any introspection.

3. Through the current style used for generating data objects from the
hierarchy:

p.contour("Temperature")

This would also give us docstrings for free.
==

What do you think?  The first appeals to me the strongest for
aesthetic reasons, but the third appeals to me on the grounds of ease
of use and understanding.  Does anyone have any strong feelings?  This
would all be handled via an auto-registry situation, so the means of
adding new callbacks would change, but only in that they would all
require _type_name .  Additionally, I see no reason to get rid of the
current p.add_callback(...) method, which is more general that we're
looking at here.

-Matt