The cleanup is reasonable. However, I'm stumbling a bit about the changed semantics. format_ticks() does not obviously imply that the internal state is changed (or that it even exists). set_locs() was explicit about that.

Can we get a more clear API? One can have two views on the formatter:

• simple: The formatter does only format single values.
• aligned: The format of a tick depends on the properties of all the ticks to be formatted.

fmt.format_ticks(values) feels like the simple formatter, but actually is an aligned formatter. It may be surprising that fmt.format_ticks(values) != [fmt.format_ticks([v])[0] for v in values].

Do we actually need the state? If not one could do something like

def format_ticks(values, context=None):
    """"
    Format *values* in a consistent way.

    The output format of a single value depends on the values in *context*.
    If not given, the context are the values themselves.
    """"
    if context is None:
        context = values

These are just quick thoughts so far. They probably need a bit more consideration.

We already pass the state - thats how ticks = [1, 1.125, 1.25, 1.5] are labeled with the same precision (1.00, 1.125, 1.250, 1.500). Its really makes little sense to not just format all the ticks at once. #10682 is a concrete example of where this is even more useful, and you can think of others. This PR just makes that logic less convoluted.

The issue is that we secretly introduce state.

fmt.set_locs(values)
a = fmt.format_data_short(v)
b = fmt.format_ticks(values)
c = fmt.format_data_short(v)

is explicit and a and c will have the same result.

However, after this PR is in, the code would be

a = fmt.format_data_short(v)
b = fmt.format_ticks(values)
c = fmt.format_data_short(v)

and a and c may be different. That doesn't look like a sane API to me.

Are there contexts where you would set the locs, but not format the ticks? If not, I'm fine with format_data_short having a dependence on what the major ticks are...

As @jklymak mentioned, hoping that ticks can be formatted independently from one another is a long-lost battle; there are pretty good reasons why they're interdependent.
I think changing format_data_short (which should really be named format_data_for_cursor, as that's what's it's for) to take the tick locs as argument (and thusly making the formatters stateless) would be a very good idea, but that won't be this PR.
Note that as of now, the calls to set_locs are very, very far apart from the calls to format_data_short (that's effectively in the event handlers for the GUIs...), which makes the statefulness quite hidden too unless you already know about set_locs.

I agree that the required tick format must depends on all ticks.

I think changing format_data_short (which should really be named format_data_for_cursor, as that's what's it's for) to take the tick locs as argument (and thusly making the formatters stateless) would be a very good idea, but that won't be this PR.

If we get this to work, I'm fine with the present PR, because then the hidden state magic will be gone. I want to look into this before dismissing my change request.

Just to clarify; are you saying you want the other PR (which doesn't exist right now, we're just discussing design) to be made before unblocking this one?

Not necessarily. I want to be sure that it can be done and I would like to have it at least soon after this one.

Actually, the easiest is probably just to lookup the tick locations on the axis instance rather than passing it in as argument (otherwise that's what you'll have to do at the call site anyways...), so something like

    def format_data_short(self, value):  # May or may not go through a rename deprecation cycle.
    # or def format_data_short(self, value, ticklocs=None):
        """
        Return a short string version of the tick value.

        Defaults to the position-independent long value.
        """
        # Actually, needs to know whether we are the major or minor formatter,
        # but that's just a matter of `self is self.major.formatter`.
        self.set_locs(self.axis.get_majorticklocs())
        # or
        self.set_locs(ticklocs if ticklocs is not None
                      else self.axis.get_majorticklocs())
        return self.format_data(value)

then slowly move through the different formatter classes to make them independent of set_locs.

Hm, the dependence on the axis is another hidden state, and may actually cause incorrect behavior:

formatter = FuncFormatter(lambda x, pos: '_%s_' % x)
ax = plt.gca()
ax.xaxis.set_major_formatter(formatter)
ax.yaxis.set_major_formatter(formatter)

ax.xaxis.get_major_formatter().axis == ax.xaxis   # False!

I wouldn't want to use the axis in the formatter unless really necessary.

Well, again locators and formatters have known their axis since forever; I guess it would be reasonable to make set_axis raise an error if the axis has already been set (similarly to how artists cannot be reassigned from one axes to another).

Well, again locators and formatters have known their axis since forever; I guess it would be reasonable to make set_axis raise an error if the axis has already been set (similarly to how artists cannot be reassigned from one axes to another).

That would make sense.

Well, except that ThetaLocator is of course doing funky stuff like

class ThetaLocator(mticker.Locator):
    def __init__(self, base):
        self.base = base
        self.axis = self.base.axis = _AxisWrapper(self.base.axis)

    def set_axis(self, axis):
        self.axis = _AxisWrapper(axis)
        self.base.set_axis(self.axis)

Probably can easily be worked around, but will take a bit longer than expected.

Also, there's a bunch of formatters which actually do not care about the axis (NullFormatter, FixedFormatter, FuncFormatter, FormatStrFormatter, StrMethodFormatter) and these do get used across multiple axes in examples and tests; it also seems like gratuitious breakage to forbid their sharing :/

ping @timhoffm ...

Target state:

1. Tick formats must depend on all ticks.
2. A formatter is attached to a single axis (and locator). Adding it to mutliple axes must raise an error.
3. Formatters should not hold a list of tick locs themselves. They should obtain the locs from the axis.

Edit:

Implementation detail:

To maintain the major/minor aspect, formatter should have a flag if they are major or minor. The state should only contain the attibutes axis an is_major.

Alternative B: Pass in the relevant Axis method loc_getter=axis.get_majorticklocs.

Alternative C: Determine is_major = self.axis.major.formatter is self.

I tend to favor alternative C, it's a bit indirect but does not store redundant information.

Well, I'm not sure what's the best way forward with 2) given my comment just above.

Can we make that optional? The axis is passed in to the formatter, but the formatter can decide not to use axis information, in which case it can be attached to multiple axes. The check for multiple connections would be in the formatter.

Add a class-level flag uses_axis_context

def set_axis(self, axis):
    if not self.uses_axis_context:
        return
    elif: self.axis is not None:
        raise ValueError('XYZFormatter cannot be attached to more than one axis/locator').
    else:
        self.axis = axis

OK, that's one possible design.

Alternatively, we could make set_axis (.axis.setter) internally store a list of all axises this formatter has been assigned to, and error out when accessing the .axis attribute (if it has been set to multiple values), which would have the benefit of not requiring third-party formatters to change, and staying automatically correct for all formatter classes.

However that'll likely be a separate PR (the problem of setting a formatter to multiple axises is not new).

Marking this PR as release critical as it changes the semantics of the new format_ticks API and it would be much more of a pain to change this after it has been released.