Let's keep all the attributes private for now. Assigning to one of these would not update the underlying polygon. If you want to expose them, we'd probably need to make them properties, like Polygon.xy.

Attributes still need to be made private.

This is not how we manage updates in Artists within Matplotlib.

While it's not 100% consistent:

• We don't have update_*() methods taking keyword arguments.
• Usually we set individual properties via set_*() and that marks the Artist as _stale.
• There's Artist.update(props), but that's just a convenience wrapper calling set_*() methods internally, and (for some reason) the single argument is a dict.

So my understanding is that when an artist has _stale=True then on the next fig.canvas.draw event it will be asked to re-render itself, is that correct?

I was trying to avoid having to call _make_verts multiple times if someone wanted to update the width and the xy positions all at once. Two ideas:

1. call _make_verts in whatever gets called on account of _stale. Like this:

def method_I_dont_know_the_name_of(self):
    self._make_verts()
    super().method_I_dont_know_the_name_of()

2. There are both styling (e.g. color) args and args that are analogous to to data. So maybe we can take inspiration from the set_data methods for lines? i.e. have a set_data(x,y,dx,dy,width) and set_color, set_... methods?

1. I've never dug into the exact stale mechanism. Maybe someone else can help here. (Also just found out, that you should use the property Artist.stale instead of the private attribute Artist._stale.

2. set_data(x, y, dx, dy, width) seems a good choice. Possibly with all parameters defaulting to None. I think in that case, it's also feasible to leave out the stale-mechanism and run _make_verts() in set_data().

What about properties like length_includes_head or shape? They aren't as exactly analogous to data, but there doesn't seem to be a good reason to exclude them. Should they get their own methods or be included in a set_data method?

One could take the "pure" standpoint at data is only the position and length and everything else is styling. But then you'd also need to handle width separately. For simplicity, let's put all parameters that affect the polygon shape in set_data, so that we can compute the polygon right there.

Thinking again, the styling-related parameters are typically not modified in animations. So we can leave them as separate setters and explicitly let them call _make_verts as well. That's a bit more clean API-wise and not a significant performance limitation. (One could later still introduce stale if one wants to delay generation of the polygon). What do you think?

To my eye the break down of data vs style is this:
data:

• x
• y
• dx
• dy
• width
• head_width
• head_length

style:

• length_includes_head
• shape
• head_starts_at_zero
• overhang (arguably data)

Ok by me. I'm not sure about width, head_width, and head_length. But then again, it's not too invasive having them in set_data because they will be optional.

Should the style setters have a single setter. i.e. set_style(overhang=None...) or each get their own? Each their own can lead to clunky names like set_head_starts_at_zero

I'm somewhat opposed to set_style(). We're not using it currently and "style" is a heavily overloaded name.

If you don't need to set styles for your use case, I'm fine with not adding any setters for them for now. It's probably very rare that one wants to change them.