PR Summary

Color handling in collections is confusing: there are faces and edges, each of which can have a fixed color or a mapped color. Fixed colors (which can be single specifications or arrays matching the elements in the collection) are always available via initialization with defaults. If the collection has a data array set, then it will be used to map colors for edges and/or faces, depending on how their respective fixed color attributes are set. The purpose of this PR is to clarify the logic by consolidating it in a private function. Thiscloses#1302, and is an alternative to#12226.

Edited, 2020-09-25

Working with the collections code is complicated by the aliasing combined with the subclassing. Here's how it looks to me:

1. The direct effect of the aliasing is to generate additional setters and getters for all of the aliases. This is done in the Collection base class when the module is imported. All of these additional getters and setters are inherited by subclasses.
2. The main motivation for the aliasing is to allow singular and plural forms of properties like colors, but abbreviations are also provided. We want to move, though, towards favoring thesingular forms, for consistency with things like Patches and Line2D objects. The directly coded setters and getters are all singular; the aliases are plural or abbreviated. Related private variables are a mixed bag, some singular (e.g.,_original_facecolor), others plural (e.g.,_facecolors).
3. The signature ofCollection.__init__ includes a trailing**kwargs after a long list of explicit keyword arguments, all of which are presently still theplural form. When keywords are supplied to the__init__ of a subclass, which always either inherits or callsCollection.__init__, any of those keywords that match the explicit signature are handled first, along with any un-supplied defaults from the signature. Then, any that remain are handled through theupdate method inherited fromArtist, which calls the setter, if any, matching the name of the kwarg. For example, if the supposedly favored 'facecolorkwarg is supplied, the initialization will first callset_facecolorwith the default from the signature (named 'facecolors'), and then it will callset_facecolor` again with the value supplied via the 'facecolor' kwarg.
4. The purpose of subclassing is to customize a base class, which by itself is typically not usable. The customization can be via adding functionality (new methods), by overriding methods to modify their behavior, or by changing default values. New methods lack aliases unless they are explicitly generated, either directly, or via a decorator on the subclass. Overridden methods are problematic because the aliases are still there, but they point to the implementations in the base class, not to the the overrides in the subclass.
5. Defaults usually fall into one of two categories: fixed values, like 'black', and values taken from rcParams. The former are unambiguous; the latter can be implemented so that the values are frozen at import time, or so that they are taken at or near the time of instantiation of an object. The latter is preferred. In the context of aliased collection properties, though, this means that they need to be retrieved by a method of the subclass, which is called by the setter defined in Collection.
6. The way to minimize confusion and clutter with argument handling in the subclass is to let**kwargs handle everything that does not require a subclass-specific fixed default.

I think this PR is now consistent with the above points with respect to LineCollection.

A possible objection is that by trimming down the signature ofLineCollection.__init__, we are breaking any code using positional calling for properties that were in the signature. I think we should move in this direction anyway, making such properties keyword-only. I have added a compatibility shim with a deprecation warning to handle existing code.

It also appears to me that confusion could be reduced with no backwards incompatibility forpublic attributes if we were to change all the signature forms to singular ('facecolors' -> 'facecolor'), and similarly for the private attributes that are still plural.

PR Checklist

• Has pytest style unit tests (andpytest passes).
• IsFlake 8 compliant (runflake8 on changed files to check).
• New features are documented, with examples if plot related.
• Documentation is sphinx and numpydoc compliant (the docs shouldbuild without error).
• Conforms to Matplotlib style conventions (installflake8-docstrings andpydocstyle<4 and runflake8 --docstring-convention=all).
• New features have an entry indoc/users/next_whats_new/ (follow instructions in README.rst there).
• API changes documented indoc/api/next_api_changes/ (follow instructions in README.rst there).