Handle changed functions in check_units decorator

setup.cfg

@@ -77,15 +77,14 @@ copyright-check = True
 copyright-author = MetPy Developers
 inline-quotes = single
 multiline-quotes = double
-rst-roles = class, data, func, meth, mod
-rst-directives = plot
+rst-roles = class, data, doc, func, meth, mod
+rst-directives = plot, versionchanged
 docstring-convention = numpy
 exclude = docs build src/metpy/io/metar_parser.py
 select = A B C D E F H I M Q RST S T W B902
 ignore = F405 W503 RST902
 per-file-ignores = examples/*.py: D T003 T001
                    tutorials/*.py: D T003 T001
-                   tutorials/xarray_tutorial.py: D RST304
                    src/metpy/xarray.py: RST304
                    src/metpy/deprecation.py: C801
                    src/metpy/calc/*.py: RST306

src/metpy/calc/basic.py

@@ -139,6 +139,9 @@ def wind_components(speed, wind_direction):
     >>> metpy.calc.wind_components(10. * units('m/s'), 225. * units.deg)
      (<Quantity(7.07106781, 'meter / second')>, <Quantity(7.07106781, 'meter / second')>)
 
+    .. versionchanged:: 1.0
+       Renamed ``wdir`` parameter to ``wind_direction``
+
     """
     wind_direction = _check_radians(wind_direction, max_radians=4 * np.pi)
     u = -speed * np.sin(wind_direction)
@@ -185,7 +188,7 @@ def windchill(temperature, speed, face_level_winds=False, mask_undefined=True):
 
     See Also
     --------
-    heat_index
+    heat_index, apparent_temperature
 
     """
     # Correct for lower height measurement of winds if necessary
@@ -239,9 +242,13 @@ def heat_index(temperature, relative_humidity, mask_undefined=True):
         A flag indicating whether a masked array should be returned with
         values masked where the temperature < 80F. Defaults to `True`.
 
+
+    .. versionchanged:: 1.0
+       Renamed ``rh`` parameter to ``relative_humidity``
+
     See Also
     --------
-    windchill
+    windchill, apparent_temperature
 
     """
     temperature = np.atleast_1d(temperature)
@@ -352,6 +359,10 @@ def apparent_temperature(temperature, relative_humidity, speed, face_level_winds
     `pint.Quantity`
         Corresponding apparent temperature value(s)
 
+
+    .. versionchanged:: 1.0
+       Renamed ``rh`` parameter to ``relative_humidity``
+
     See Also
     --------
     heat_index, windchill
@@ -532,6 +543,9 @@ def geopotential_to_height(geopotential):
     (Prior to MetPy v0.11, this formula instead calculated :math:`g(z)` from Newton's Law of
     Gravitation assuming a spherical Earth and no centrifugal force effects.)
 
+    .. versionchanged:: 1.0
+       Renamed ``geopot`` parameter to ``geopotential``
+
     See Also
     --------
     height_to_geopotential
@@ -680,6 +694,9 @@ def sigma_to_pressure(sigma, pressure_sfc, pressure_top):
     * :math:`p_{sfc}` is pressure at the surface or model floor
     * :math:`p_{top}` is pressure at the top of the model domain
 
+    .. versionchanged:: 1.0
+       Renamed ``psfc``, ``ptop`` parameters to ``pressure_sfc``, ``pressure_top``
+
     """
     if np.any(sigma < 0) or np.any(sigma > 1):
         raise ValueError('Sigma values should be bounded by 0 and 1')

src/metpy/calc/cross_sections.py

@@ -287,6 +287,9 @@ def absolute_momentum(u, v, index='index'):
     -----
     The coordinates of `u` and `v` must match.
 
+    .. versionchanged:: 1.0
+       Renamed ``u_wind``, ``v_wind`` parameters to ``u``, ``v``
+
     """
     # Get the normal component of the wind
     norm_wind = normal_component(u, v, index=index).metpy.convert_units('m/s')

src/metpy/calc/indices.py

@@ -55,6 +55,9 @@ def precipitable_water(pressure, dewpoint, *, bottom=None, top=None):
     -----
     Only functions on 1D profiles (not higher-dimension vertical cross sections or grids).
 
+    .. versionchanged:: 1.0
+       Signature changed from ``(dewpt, pressure, bottom=None, top=None)``
+
     """
     # Sort pressure and dewpoint to be in decreasing pressure order (increasing height)
     sort_inds = np.argsort(pressure)[::-1]
@@ -120,6 +123,9 @@ def mean_pressure_weighted(pressure, *args, height=None, bottom=None, depth=None
     Since this function returns scalar values when given a profile, this will return Pint
     Quantities even when given xarray DataArray profiles.
 
+    .. versionchanged:: 1.0
+       Renamed ``heights`` parameter to ``height``
+
     """
     ret = []  # Returned variable means in layer
     layer_arg = get_layer(pressure, *args, height=height,
@@ -176,6 +182,9 @@ def bunkers_storm_motion(pressure, u, v, height):
     Since this function returns scalar values when given a profile, this will return Pint
     Quantities even when given xarray DataArray profiles.
 
+    .. versionchanged:: 1.0
+       Renamed ``heights`` parameter to ``height``
+
     """
     # mean wind from sfc-6km
     wind_mean = concatenate(mean_pressure_weighted(pressure, u, v, height=height,
@@ -252,6 +261,9 @@ def bulk_shear(pressure, u, v, height=None, bottom=None, depth=None):
     Since this function returns scalar values when given a profile, this will return Pint
     Quantities even when given xarray DataArray profiles.
 
+    .. versionchanged:: 1.0
+       Renamed ``heights`` parameter to ``height``
+
     """
     _, u_layer, v_layer = get_layer(pressure, u, v, height=height,
                                     bottom=bottom, depth=depth)
@@ -407,6 +419,9 @@ def critical_angle(pressure, u, v, height, u_storm, v_storm):
     Since this function returns scalar values when given a profile, this will return Pint
     Quantities even when given xarray DataArray profiles.
 
+    .. versionchanged:: 1.0
+       Renamed ``heights`` parameter to ``height``
+
     """
     # Convert everything to m/s
     u = u.to('m/s')

src/metpy/calc/kinematics.py

@@ -47,6 +47,10 @@ def vorticity(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2):
     (..., M, N) `xarray.DataArray` or `pint.Quantity`
         vertical vorticity
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(u, v, dx, dy)``
+
     See Also
     --------
     divergence
@@ -90,6 +94,10 @@ def divergence(u, v, *, dx=None, dy=None, x_dim=-1, y_dim=-2):
     (..., M, N) `xarray.DataArray` or `pint.Quantity`
         The horizontal divergence
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(u, v, dx, dy)``
+
     See Also
     --------
     vorticity
@@ -133,6 +141,10 @@ def shearing_deformation(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2):
     (..., M, N) `xarray.DataArray` or `pint.Quantity`
         Shearing Deformation
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(u, v, dx, dy)``
+
     See Also
     --------
     stretching_deformation, total_deformation
@@ -176,6 +188,10 @@ def stretching_deformation(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2):
     (..., M, N) `xarray.DataArray` or `pint.Quantity`
         Stretching Deformation
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(u, v, dx, dy)``
+
     See Also
     --------
     shearing_deformation, total_deformation
@@ -219,15 +235,18 @@ def total_deformation(u, v, dx=None, dy=None, x_dim=-1, y_dim=-2):
     (..., M, N) `xarray.DataArray` or `pint.Quantity`
         Total Deformation
 
-    See Also
-    --------
-    shearing_deformation, stretching_deformation
-
     Notes
     -----
     If inputs have more than two dimensions, they are assumed to have either leading dimensions
     of (x, y) or trailing dimensions of (y, x), depending on the value of ``dim_order``.
 
+    .. versionchanged:: 1.0
+       Changed signature from ``(u, v, dx, dy)``
+
+    See Also
+    --------
+    shearing_deformation, stretching_deformation
+
     """
     dudy, dudx = gradient(u, deltas=(dy, dx), axes=(y_dim, x_dim))
     dvdy, dvdx = gradient(v, deltas=(dy, dx), axes=(y_dim, x_dim))
@@ -286,6 +305,10 @@ def advection(
     `pint.Quantity` or `xarray.DataArray`
         An N-dimensional array containing the advection at all grid points.
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(scalar, wind, deltas)``
+
     """
     return -sum(
         wind * first_derivative(scalar, axis=axis, delta=delta)
@@ -352,6 +375,9 @@ def frontogenesis(potential_temperature, u, v, dx=None, dy=None, x_dim=-1, y_dim
     Conversion factor to go from [temperature units]/m/s to [temperature units/100km/3h]
     :math:`1.08e4*1.e5`
 
+    .. versionchanged:: 1.0
+       Changed signature from ``(thta, u, v, dx, dy, dim_order='yx')``
+
     """
     # Get gradients of potential temperature in both x and y
     ddy_thta = first_derivative(potential_temperature, delta=dy, axis=y_dim)
@@ -411,6 +437,10 @@ def geostrophic_wind(height, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2
     A 2-item tuple of arrays
         A tuple of the u-component and v-component of the geostrophic wind.
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(heights, f, dx, dy)``
+
     """
     f = coriolis_parameter(latitude)
     if height.dimensionality['[length]'] == 2.0:
@@ -472,6 +502,10 @@ def ageostrophic_wind(height, u, v, dx=None, dy=None, latitude=None, x_dim=-1, y
     A 2-item tuple of arrays
         A tuple of the u-component and v-component of the ageostrophic wind
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(heights, f, dx, dy, u, v, dim_order='yx')``
+
     """
     u_geostrophic, v_geostrophic = geostrophic_wind(
         height,
@@ -583,6 +617,10 @@ def storm_relative_helicity(height, u, v, depth, *, bottom=0 * units.m,
     Since this function returns scalar values when given a profile, this will return Pint
     Quantities even when given xarray DataArray profiles.
 
+    .. versionchanged:: 1.0
+       Renamed ``heights`` parameter to ``height`` and converted ``bottom``, ``storm_u``, and
+       ``storm_v`` parameters to keyword-only arguments
+
     """
     _, u, v = get_layer_heights(height, depth, u, v, with_agl=True, bottom=bottom)
 
@@ -643,6 +681,10 @@ def absolute_vorticity(u, v, dx=None, dy=None, latitude=None, x_dim=-1, y_dim=-2
     (..., M, N) `xarray.DataArray` or `pint.Quantity`
         absolute vorticity
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(u, v, dx, dy, lats, dim_order='yx')``
+
     """
     f = coriolis_parameter(latitude)
     relative_vorticity = vorticity(u, v, dx=dx, dy=dy, x_dim=x_dim, y_dim=y_dim)
@@ -728,6 +770,9 @@ def potential_vorticity_baroclinic(
     one-dimensional, and not given as `xarray.DataArray`, p[:, None, None] can be used to make
     it appear multi-dimensional.)
 
+    .. versionchanged:: 1.0
+       Changed signature from ``(potential_temperature, pressure, u, v, dx, dy, lats)``
+
     """
     if (
         np.shape(potential_temperature)[vertical_dim] < 3
@@ -809,6 +854,10 @@ def potential_vorticity_barotropic(
     (..., M, N) `xarray.DataArray` or `pint.Quantity`
         barotropic potential vorticity
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(heights, u, v, dx, dy, lats, dim_order='yx')``
+
     """
     avor = absolute_vorticity(u, v, dx, dy, latitude, x_dim=x_dim, y_dim=y_dim)
     return (avor / height).to('meter**-1 * second**-1')
@@ -890,6 +939,9 @@ def inertial_advective_wind(
     wind to both be the geostrophic wind. To do so, pass the x and y components
     of the geostrophic wind for u and u_geostrophic/v and v_geostrophic.
 
+    .. versionchanged:: 1.0
+       Changed signature from ``(u, v, u_geostrophic, v_geostrophic, dx, dy, lats)``
+
     """
     f = coriolis_parameter(latitude)
 
@@ -970,6 +1022,10 @@ def q_vector(
     tuple of (..., M, N) `xarray.DataArray` or `pint.Quantity`
         The components of the Q-vector in the u- and v-directions respectively
 
+
+    .. versionchanged:: 1.0
+       Changed signature from ``(u, v, temperature, pressure, dx, dy, static_stability=1)``
+
     See Also
     --------
     static_stability