Just as a remark (not necessarily to be acted upon in this PR):

By making the cmap registry private, we don't have an official way to get the registered colormaps from thecm module, where I would expect such functionality. This is something we should take care of in followup PRs.

I'm not even sureplt.colormaps() is needed. First, It's essentially a lengthy description of colormaps, which should be somewhere in the docs but not in a pyplot docstring. Second, I don't see providing the colormaps as a core functionality of pyplot, but since there's a lot of historic colormap stuff in pyplot, that's maybe ok.

I had the same thought:#16991 (comment)

I'm not sure what the best step is to expose the access, but would agree that I don't want to have to go to pyplot if not necessary. Maybe rather than acmap_d, we could do something like your MutableMapping suggestion and then override the get/set methods to ensure copy/immutable return.

Sorry if this is a bit unstructured. I just stated typing and ideas unfolded along the way.

There would be two ways:

1. Thecm module currently uses simple functionsget_cmap() andregister_cmap(). In that spirit, you could add a functionget_cmap_names() (naming t.b.d.) but we have to make a distinction betweenget_cmap returning an instance and that function (probably?) returning strings.

2. The alternative would be to expose aColormapRegistry object, which provides all necessary functionality. That would likely be subclassingMutableMapping to look dict-like but still perform all relevant checks (maybe it would alternatively only implementMapping and provide an explicit register method if we feel the mutation should be more special (i.e. we don't wantdel registry['jet'] orregistry['jet'] = Colormap(...)).
   This would also replace the module level functions; at least their implementation. Whether they will additionally stay for backward compatibility is a separate topic.

In the end 2 is the more complex approach. However, I have a slight preference for it because it properly encapsulates the colormap handling. On the downside it changes the API from calling simple cm functions to an object. But then again, we could move the actual instance to a variablematplotlib.colormaps, which may make more sense and users would usually not need to import matplotlib.cm anymore; andpyplot.colormaps could later even point to the same instance (with some API compatibility because the keys of that mapping would then colormap names, sofor name in plt.colormaps() would still work.

I agree with pretty much everything you're saying. I also don't think 2 would be that hard to implement. An issue with naming will be found with:#11413 which is already proposing to rename cm to colormaps. This discussion is really more a part of the MEP:https://matplotlib.org/3.2.1/devel/MEP/MEP21.html
Maybe we should do some larger work on an overarching vision there and then decide on how best to get there?

If we provide colormap registry access frommatplotlib directly,cm.get_cmap andcm.register_cmap become obsolete. There won't be a need for the end user to importcm, which in turn reduces the need for renaming (#11413). But we could still find other names for that.

It would be reasonable to detail the overall vision.

This does not warn forlist(mpl.cm.cmap_d) but does warn forlist(mlp.cm.cmap_d.items()). Was this an oversight that__iter__ does not warn or a decision that because it is only giving a list of keys that could then go toget_cmap it should not wark?

Oversight, the iter still warns because of the getitem, but I didn't think of people just listing the colormaps and using it manually themselves elsewhere. I just added it here as well.

same for__len__ below? Sorry for the thousand paper cuts at the end...

No worries, easy enough to fix. Should have just done it myself ;)

Please document in the docstring that if passing a Colormap instance, that instance will become immutable.

I added in a Notes section to both theget_cmap andregister_cmap functions now. Let me know if you want any different wording there. It may be odd to talk about future behavior there considering you can't do anything to get that future behavior yet? But I can't think of any great wording off the top of my head.