I'm -0.8 on this. There is a difference between the user API (set_facecolor()) and the internal data represenation. While a user can use set_facecolor('red'), we convert it into a (1, 4) array. The plural makes it clear that it is an iterable over the colors (which, yes, may contain only one element). Also internal expressions like len(self._facecolors) read better than len(self._facecolor).

There is a difference between the user API (set_facecolor()) and the internal data represenation

But get_facecolor is gonna return __facecolors so if someone needed the private variable for whatever reason, that's what they'd have to pull. I think 'especially since we have the color/colors mean different things API, it's a lot clearer when reading the code if the internal matches the public - otherwise I'd be double checking wait do we have another color parameter in the signature?

I cannot follow your argument. facecolors is an alias to facecolor. These are equivalent for the public API. There'll be always one of the two that won't match the internal naming. In fact, Collection.__init__ even uses the plural versions.

@timhoffm sorry should have double checked and now I'm annoyed at the public API and feel like the singular should get discouraged (the three ways to access the same thing is giving me hives).

@timhoffm, I think that I might have been the originator of the plurals long ago, so I am sympathetic to the argument that names for plural things should be plural, but over time there have been complaints about having some things plural and other similar thing singular, and the consensus at the time of #18592 was to shift the private variables to singular, and to use aliases so that collection kwargs could be singular or plural. The aliases were implemented, but not the private variable changes. The singular form was used in a change in mplot3d, however. So right now we have a bit of a mess. On balance, I think that moving everything to favor the singular will reduce confusion. The grammatical ugliness is an unfortunate side effect, but is outweighed by the simplification. Also, note that some of these sorts of variables can be singular or plural for the same object; and something originally designed as singular (like alpha) can end up being extended to be optionally plural.

The plural can be pretty ugly, too: "antialiaseds"? Really? And in general that can be plural for collections, but it is singular in QuadMesh.

now I'm annoyed at the public API and feel like the singular should get discouraged

OTOH the singular versions are inherited from Artist.

On the public API we're torn between

• the "singular" inheritance from Artist
• the somewhat justifiyable plural semantics
• the constructor arguments
• the aliasing

Overall, it's best to leave everything there as is.

In the internals, we can do whatever we want. I have no overview here, but if we have a singular-plural mixture we should definitively have a clear policy and unify this. The direction of the change may be open to discussion.

On a side-note: If I was to design this from scratch, the public API would be all-singular. You could have single values used as broadcast CircleCollection(..., facecolor="red") and CircleCollection(..., facecolor=["red", "green", "blue"]) work.

Internal naming would depend on normalization: If we carry the element around as is, it would be the public name (self._facecolor="red" / self._facecolor=["red", "green", "blue"]). If we normalize the parameter to an iterable I'd go with the plural self._facecolors.

In another PR the public API could be nudged toward the singular by changing examples, docstrings, kwarg defaults and the alias table.

Thank you, @dstansby. I botched a rebase, so the current state of this PR is broken. Personally, I still think what it is trying to do is a step in the right direction--though a very minor improvement. @timhoffm, your last comment was not entirely clear to me: are you OK with this internal change, or not? I won't try to fix the PR unless it is clear it will go in.