Deprecate old lat/lon tick label formatters

[lbdreyer]

We have two (2) longitude and latitude tick formatters.

cartopy.mpl.gridliner.LONGITUDE_FORMATTER which is ~5 years old
and
cartopy.mpl.ticker.LongitudeFormatter which is ~ 4 years old

The newer one is better as it allows the user to modify the number format, etc.
I'm not sure why the old one wasn't removed when the new one was added, the code is so similar!

I think we should deprecate the older version in preference for the newer one and update all the places it gets used (e.g. in the cartopy course)

[stickler-ci]

E302 expected 2 blank lines, found 1
E501 line too long (80 > 79 characters)

[stickler-ci]

E305 expected 2 blank lines after class or function definition, found 1

[stickler-ci]

E501 line too long (80 > 79 characters)

[dopplershift]

Would it be better to use matplotlib's deprecation infrastructure rather than adding our own?

[ajdawson]

You should be wary because the two formatters are not entirely equivalent, and there are some potential pitfalls with the newer one (see #401 (comment)). The differences are subtle, but there may be use cases that the originals serve better.

There are also issues with your proposed deprecation implementation that need consideration.

[ajdawson]

You are calling the function immediately when the module is imported, so this warning will always be shown regardless of whether the user actually wants to use LONGITUDE_FORMATTER or LATITUDE_FORMATTER. I think this will create too much noise and not target those people you want to see the warning.

[pp-mo]

@dopplershift Would it be better to use matplotlib's deprecation infrastructure rather than adding our own?

Do you just mean using mplDeprecation, like matplotlib/matplotlib#7723 ?
Or is there more to it ?
I'm no expert, but I can't find anything about managing deprecation in their developer guide pages.

[dopplershift]

Matplotlib has a matplotlib.cbook.deprecated decorator for marking classes/functions as deprecated.

[pelson]

Thanks @lbdreyer! 👍 for deprecating this.

There are two issues that need to be addressed:

• DeprecationWarnings are hidden by default, thus unless you engage with them, you'll never know about this until they are actually removed from the codebase (in which case, we may as well just remove them now and be done with it). A UserWarning is fine with me.
• Don't invoke the deprecation warning on module import

[pelson]

@lbdreyer - any chance you've got some time to spin this back up? Would be good to target this for v0.18.

[lukelbd]

Wouldn't this PR be suitable for the next release?

I think the pitfall mentioned in #401 (comment) is no longer relevant in version 0.18:

cartopy/lib/cartopy/mpl/gridliner.py

Lines 194 to 208 in 178a15e

	if xformatter is None:
	if isinstance(crs, cartopy.crs.PlateCarree):
	xformatter = LongitudeFormatter(dms=dms)
	else:
	xformatter = classic_formatter()
	#: The :class:`~matplotlib.ticker.Formatter` to use for the lon labels.
	self.xformatter = xformatter
	if yformatter is None:
	if isinstance(crs, cartopy.crs.PlateCarree):
	yformatter = LatitudeFormatter(dms=dms)
	else:
	yformatter = classic_formatter()
	#: The :class:`~matplotlib.ticker.Formatter` to use for the lat labels.
	self.yformatter = yformatter

Matplotlib's ScalarFormatter has always had the same limitation (you cannot re-use ScalarFormatter on multiple axes), but since ScalarFormatter is meant to be enabled automatically / untouched by 99.9% of users very few people run into this problem (and presumably being axis-specific allows you to design a more intelligent auto-formatting algorithm).

Now that version 0.18 makes LatitudeFormatter and LongitudeFormatter the default formatters for gridline labels, very few users will have to work with them directly / run into this problem.

One thing you could also do is add xformatter_kw and yformatter_kw keyword argument dictionary-arguments to cartopy.mpl.GridLiner(). These arguments would get passed to LatitudeFormatter and LongitudeFormatter on instantiation, which lets users customize the tick format and further avoids requiring people to work with the classes directly. Matplotlib uses this _kw convention in several places, e.g. pyplot.subplots().

[CLAassistant]

All committers have signed the CLA.