API: inconsistent projection arguments in img_transform.regrid

[ellequelle]

While helping someone with their code I noticed this inconsistency in the img_transform.regrid API and docstring. The projection parameters are source_cs and target_proj, but in the docstring they're listed as source_cs and target_cs:

regrid excerpt

cartopy/lib/cartopy/img_transform.py

Lines 222 to 241 in 22cdafc

	def regrid(array, source_x_coords, source_y_coords, source_cs, target_proj,
	target_x_points, target_y_points, mask_extrapolated=False):
	"""
	Regrid the data array from the source projection to the target projection.
	Parameters
	----------
	array
	The :class:`numpy.ndarray` of data to be regridded to the
	target projection.
	source_x_coords
	A 2-dimensional source projection :class:`numpy.ndarray` of
	x-direction sample points.
	source_y_coords
	A 2-dimensional source projection :class:`numpy.ndarray` of
	y-direction sample points.
	source_cs
	The source :class:`~cartopy.crs.Projection` instance.
	target_cs
	The target :class:`~cartopy.crs.Projection` instance.

Could this be changed to match img_transform.wrap_array, with source_proj and target_proj?

wrap_array excerpt

cartopy/lib/cartopy/img_transform.py

Lines 124 to 141 in 22cdafc

	def warp_array(array, target_proj, source_proj=None, target_res=(400, 200),
	source_extent=None, target_extent=None,
	mask_extrapolated=False):
	"""
	Regrid the data array from the source projection to the target projection.
	Also see, :func:`~cartopy.img_transform.regrid`.
	Parameters
	----------
	array
	The :class:`numpy.ndarray` of data to be regridded to the target
	projection.
	target_proj
	The target :class:`~cartopy.crs.Projection` instance for the data.
	source_proj: optional
	The source :class:`~cartopy.crs.Projection' instance of the data.
	Defaults to a :class:`~cartopy.crs.PlateCarree` projection.

[greglucas]

I prefer consistency, so I would say yes that sounds like a great idea. A PR for the change would be great! There are probably other locations of mismatch as well, so if there are others you find don't hesitate to make PRs for them.

[dopplershift]

If we do that, it's technically an API change (since people passing via kwargs would be broken). That's fine, but we need to make sure it gets noted in the release notes.

[ellequelle]

I have two questions:

1. Does cartopy have a standard way of dealing with API deprecations?
2. Is there a whatsnew file or someplace to make note of the API change?

[dopplershift]

@ellequelle In some cases we'll warn for a change. I think this is minimally disruptive, and given our 0.x versioning, I feel fine just making the change. We generally don't have an on-going what's new file, but the release manager writes up the release notes from the PRs included in the release milestone. The easiest way to deal with this might be to just add an "api change" label.