diff --git a/.ruff.toml b/.ruff.toml index 8d65204a28..f9e3770410 100644 --- a/.ruff.toml +++ b/.ruff.toml @@ -48,7 +48,6 @@ lint.ignore = [ "D407", # Missing dashed underline after section "D409", # Section underline should match the length of its name "D410", # Missing blank line after section - "D412", # No blank lines allowed between a section header and its content # pyupgrade (UP) # https://docs.astral.sh/ruff/rules/#pyupgrade-up diff --git a/docs/gallery_code/general/plot_SOI_filtering.py b/docs/gallery_code/general/plot_SOI_filtering.py index 9c4fad51bd..5082162068 100644 --- a/docs/gallery_code/general/plot_SOI_filtering.py +++ b/docs/gallery_code/general/plot_SOI_filtering.py @@ -11,7 +11,6 @@ References ---------- - Duchon C. E. (1979) Lanczos Filtering in One and Two Dimensions. Journal of Applied Meteorology, Vol 18, pp 1016-1022. diff --git a/docs/gallery_code/meteorology/plot_COP_1d.py b/docs/gallery_code/meteorology/plot_COP_1d.py index 1f56a7b293..d5ef2a9990 100644 --- a/docs/gallery_code/meteorology/plot_COP_1d.py +++ b/docs/gallery_code/meteorology/plot_COP_1d.py @@ -11,7 +11,6 @@ References ---------- - Johns T.C., et al. (2011) Climate change under aggressive mitigation: the ENSEMBLES multi-model experiment. Climate Dynamics, Vol 37, No. 9-10, doi:10.1007/s00382-011-1005-5. diff --git a/docs/gallery_code/meteorology/plot_COP_maps.py b/docs/gallery_code/meteorology/plot_COP_maps.py index 714ee8896b..eda8a3a53a 100644 --- a/docs/gallery_code/meteorology/plot_COP_maps.py +++ b/docs/gallery_code/meteorology/plot_COP_maps.py @@ -9,7 +9,6 @@ References ---------- - Johns T.C., et al. (2011) Climate change under aggressive mitigation: the ENSEMBLES multi-model experiment. Climate Dynamics, Vol 37, No. 9-10, doi:10.1007/s00382-011-1005-5. diff --git a/lib/iris/analysis/_grid_angles.py b/lib/iris/analysis/_grid_angles.py index 6a0ba3e1a4..d50f55125f 100644 --- a/lib/iris/analysis/_grid_angles.py +++ b/lib/iris/analysis/_grid_angles.py @@ -22,9 +22,9 @@ def _3d_xyz_from_latlon(lon, lat): Arrays of longitudes and latitudes, in degrees. Both the same shape. - Returns: - - * xyz : (array, dtype=float64) + Returns + ------- + xyz : array, dtype=float64 Cartesian coordinates on a unit sphere. Shape is (3, ). The x / y / z coordinates are in xyz[0 / 1 / 2]. @@ -52,9 +52,9 @@ def _latlon_from_xyz(xyz): Shape (3, ). x / y / z values are in xyz[0 / 1 / 2], - Returns: - - * lonlat : (array) + Returns + ------- + lonlat : array longitude and latitude position angles, in degrees. Shape (2, ). The longitudes / latitudes are in lonlat[0 / 1]. @@ -104,9 +104,9 @@ def _angle(p, q, r): Shape is (2, ). Longitudes / latitudes are in array[0 / 1]. - Returns: - - * angle : (float array) + Returns + ------- + angle : float array Grid angles relative to true-East, in degrees. Positive when grid-East is anticlockwise from true-East. Shape is same as . @@ -178,23 +178,22 @@ def gridcell_angles(x, y=None, cell_angle_boundpoints="mid-lhs, mid-rhs"): takes an angles between the average of the left-hand and right-hand pairs of corners. The default is 'mid-lhs, mid-rhs'. - Returns: - - angles : (2-dimensional cube) - - Cube of angles of grid-x vector from true Eastward direction for - each gridcell, in degrees. - It also has "true" longitude and latitude coordinates, with no - coordinate system. - When the input has coords, then the output ones are identical if - the inputs are true-latlons, otherwise they are transformed - true-latlon versions. - When the input has bounded coords, then the output coords have - matching bounds and centrepoints (possibly transformed). - When the input is 2d arrays, or has unbounded coords, then the - output coords have matching points and no bounds. - When the input is 3d arrays, then the output coords have matching - bounds, and the centrepoints are an average of the 4 boundpoints. + Returns + ------- + angles : 2-dimensional cube + Cube of angles of grid-x vector from true Eastward direction for + each gridcell, in degrees. + It also has "true" longitude and latitude coordinates, with no + coordinate system. + When the input has coords, then the output ones are identical if + the inputs are true-latlons, otherwise they are transformed + true-latlon versions. + When the input has bounded coords, then the output coords have + matching bounds and centrepoints (possibly transformed). + When the input is 2d arrays, or has unbounded coords, then the + output coords have matching points and no bounds. + When the input is 3d arrays, then the output coords have matching + bounds, and the centrepoints are an average of the 4 boundpoints. """ cube = None @@ -423,15 +422,17 @@ def rotate_grid_vectors(u_cube, v_cube, grid_angles_cube=None, grid_angles_kwarg Additional keyword args to be passed to the :func:`gridcell_angles` method, if it is used. - Returns: - - true_u, true_v : (cube) - Cubes of true-north oriented vector components. - Units are same as inputs. + Returns + ------- + true_u, true_v : cube + Cubes of true-north oriented vector components. + Units are same as inputs. - .. Note:: + Notes + ----- + .. note:: - Vector magnitudes will always be the same as the inputs. + Vector magnitudes will always be the same as the inputs. .. note:: diff --git a/lib/iris/analysis/_interpolation.py b/lib/iris/analysis/_interpolation.py index 7c28d24efa..b6e443c95c 100644 --- a/lib/iris/analysis/_interpolation.py +++ b/lib/iris/analysis/_interpolation.py @@ -296,9 +296,10 @@ def _interpolate(self, data, interp_points): The other (leading) dimensions index over the different required sample points. - Returns: - - A :class:`np.ndarray`. Its shape is "points_shape + extra_shape", + Returns + ------- + :class:`np.ndarray`. + Its shape is "points_shape + extra_shape", where "extra_shape" is the remaining non-interpolated dimensions of the data array (i.e. 'data.shape[N:]'), and "points_shape" is the leading dimensions of interp_points, diff --git a/lib/iris/analysis/cartography.py b/lib/iris/analysis/cartography.py index 4da4e32ad7..c4a71e97e8 100644 --- a/lib/iris/analysis/cartography.py +++ b/lib/iris/analysis/cartography.py @@ -482,8 +482,8 @@ def cosine_latitude_weights(cube): w_l = \cos \phi_l - Examples: - + Examples + -------- Compute weights suitable for averaging type operations:: from iris.analysis.cartography import cosine_latitude_weights diff --git a/lib/iris/analysis/maths.py b/lib/iris/analysis/maths.py index 1042b145de..dc0b2158b6 100644 --- a/lib/iris/analysis/maths.py +++ b/lib/iris/analysis/maths.py @@ -218,7 +218,6 @@ def add(cube, other, dim=None, in_place=False): Parameters ---------- - cube : iris.cube.Cube First operand to add. @@ -234,7 +233,6 @@ def add(cube, other, dim=None, in_place=False): Returns ------- - iris.cube.Cube Notes @@ -273,7 +271,6 @@ def subtract(cube, other, dim=None, in_place=False): Parameters ---------- - cube : iris.cube.Cube Cube from which to subtract. @@ -289,7 +286,6 @@ def subtract(cube, other, dim=None, in_place=False): Returns ------- - iris.cube.Cube Notes @@ -378,7 +374,6 @@ def multiply(cube, other, dim=None, in_place=False): Parameters ---------- - cube : iris.cube.Cube First operand to multiply. @@ -394,7 +389,6 @@ def multiply(cube, other, dim=None, in_place=False): Returns ------- - iris.cube.Cube Notes @@ -464,7 +458,6 @@ def divide(cube, other, dim=None, in_place=False): Parameters ---------- - cube : iris.cube.Cube Numerator. @@ -480,7 +473,6 @@ def divide(cube, other, dim=None, in_place=False): Returns ------- - iris.cube.Cube Notes diff --git a/lib/iris/coord_systems.py b/lib/iris/coord_systems.py index 60124044f1..33214ef5e0 100644 --- a/lib/iris/coord_systems.py +++ b/lib/iris/coord_systems.py @@ -999,7 +999,6 @@ def __init__( Parameters ---------- - central_lat : float The latitude of the pole. @@ -1113,7 +1112,6 @@ def __init__( Parameters ---------- - central_lat : {90, -90} The latitude of the pole. diff --git a/lib/iris/cube.py b/lib/iris/cube.py index 44ca2777bb..3b53eaee9d 100644 --- a/lib/iris/cube.py +++ b/lib/iris/cube.py @@ -772,7 +772,6 @@ class CubeAttrsDict(MutableMapping): Examples -------- - >>> from iris.cube import Cube >>> cube = Cube([0]) >>> # CF defines 'history' as global by default. @@ -829,7 +828,6 @@ def __init__( Examples -------- - >>> from iris.cube import CubeAttrsDict >>> # CF defines 'history' as global by default. >>> CubeAttrsDict({'history': 'data-story', 'comment': 'this-cube'}) @@ -2364,11 +2362,11 @@ def mesh(self): :class:`~iris.experimental.ugrid.MeshCoord`\\ s, or ``None`` if it has none. - Returns: - - * mesh (:class:`iris.experimental.ugrid.mesh.Mesh` or None): + Returns + ------- + mesh : :class:`iris.experimental.ugrid.mesh.Mesh` or None The mesh of the cube - :class:`~iris.experimental.ugrid.MeshCoord`\\s, + :class:`~iris.experimental.ugrid.MeshCoord`'s, or ``None``. """ @@ -2383,13 +2381,12 @@ def location(self): :class:`~iris.experimental.ugrid.MeshCoord`\\ s, or ``None`` if it has none. - Returns: - - * location (str or None): + Returns + ------- + location : str or None The mesh location of the cube - :class:`~iris.experimental.ugrid.MeshCoord`\\s - (i.e. one of 'face' / 'edge' / 'node'), - or ``None``. + :class:`~iris.experimental.ugrid.MeshCoord`'s + (i.e. one of 'face' / 'edge' / 'node'), or ``None``. """ result = self._any_meshcoord() @@ -2402,10 +2399,10 @@ def mesh_dim(self): :class:`~iris.experimental.ugrid.MeshCoord`\\ s, or ``None`` if it has none. - Returns: - - * mesh_dim (int, or None): - the cube dimension which the cube + Returns + ------- + mesh_dim : int or None + The cube dimension which the cube :class:`~iris.experimental.ugrid.MeshCoord`\\s map to, or ``None``. @@ -4191,7 +4188,6 @@ def aggregated_by(self, coords, aggregator, climatological=False, **kwargs): Examples -------- - >>> import iris >>> import iris.analysis >>> import iris.coord_categorisation as cat diff --git a/lib/iris/fileformats/_nc_load_rules/helpers.py b/lib/iris/fileformats/_nc_load_rules/helpers.py index 288161deb6..ce379a204e 100644 --- a/lib/iris/fileformats/_nc_load_rules/helpers.py +++ b/lib/iris/fileformats/_nc_load_rules/helpers.py @@ -266,10 +266,10 @@ def _split_cell_methods(nc_cell_methods: str) -> List[re.Match]: * nc_cell_methods: The value of the cell methods attribute to be split. - Returns: - - * nc_cell_methods_matches: A list of the re.Match objects associated with - each parsed cell method + Returns + ------- + nc_cell_methods_matches: list of re.Match objects + A list of re.Match objects associated with each parsed cell method Splitting is done based on words followed by colons outside of any brackets. Validation of anything other than being laid out in the expected format is @@ -337,10 +337,9 @@ def parse_cell_methods(nc_cell_methods): * nc_cell_methods (str): The value of the cell methods attribute to be parsed. - Returns: - - * cell_methods - An iterable of :class:`iris.coords.CellMethod`. + Returns + ------- + iterable of :class:`iris.coords.CellMethod`. Multiple coordinates, intervals and comments are supported. If a method has a non-standard name a warning will be issued, but the diff --git a/lib/iris/fileformats/cf.py b/lib/iris/fileformats/cf.py index 0acc03967b..737955b9a7 100644 --- a/lib/iris/fileformats/cf.py +++ b/lib/iris/fileformats/cf.py @@ -6,9 +6,8 @@ according to the 'NetCDF Climate and Forecast (CF) Metadata Conventions'. References: - -[CF] NetCDF Climate and Forecast (CF) Metadata conventions. -[NUG] NetCDF User's Guide, https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/ + [CF] NetCDF Climate and Forecast (CF) Metadata conventions. + [NUG] NetCDF User's Guide, https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/ """ diff --git a/lib/iris/fileformats/pp_load_rules.py b/lib/iris/fileformats/pp_load_rules.py index f3ed22377e..10da402520 100644 --- a/lib/iris/fileformats/pp_load_rules.py +++ b/lib/iris/fileformats/pp_load_rules.py @@ -317,9 +317,9 @@ def _reshape_vector_args(values_and_dims): Input arrays with associated mapping dimension numbers. The length of each 'dims' must match the ndims of the 'value'. - Returns: - - * reshaped_arrays (iterable of arrays). + Returns + ------- + reshaped_arrays : iterable of arrays The inputs, transposed and reshaped onto common target dimensions. """ @@ -371,9 +371,9 @@ def _collapse_degenerate_points_and_bounds(points, bounds=None, rtol=1.0e-7): dimension (typically of length 2) when compared to the points array i.e. bounds.shape = points.shape + (nvertex,) - Returns: - - A (points, bounds) tuple. + Returns + ------- + (points, bounds) tuple. """ array = points @@ -634,9 +634,10 @@ def _convert_time_coords( to (). The length of each dims tuple should equal the dimensionality of the corresponding array of values. - Returns: - - A list of (coordinate, dims) tuples. The coordinates are instance of + Returns + ------- + list of (coordinate, dims) tuples. + The coordinates are instance of :class:`iris.coords.DimCoord` if possible, otherwise they are instance of :class:`iris.coords.AuxCoord`. When the coordinate is of length one, the `dims` value is None rather than an empty tuple. diff --git a/lib/iris/fileformats/um/_optimal_array_structuring.py b/lib/iris/fileformats/um/_optimal_array_structuring.py index b43c4a2e50..ce2cba7d5c 100644 --- a/lib/iris/fileformats/um/_optimal_array_structuring.py +++ b/lib/iris/fileformats/um/_optimal_array_structuring.py @@ -28,8 +28,9 @@ def _optimal_dimensioning_structure(structure, element_priorities): A dictionary mapping structure element names to their priority as defined by their input order to :func:`~optimal_array_structure`. - Returns: - + Returns + ------- + array structure or an empty list The determined optimal array structure or an empty list if no structure options were determined. @@ -69,7 +70,6 @@ def optimal_array_structure(ordering_elements, actual_values_elements=None): priority when associating dimensions with specific elements. Returns: - dims_shape, primary_elements, element_arrays_and_dims, where: * 'dims_shape' is the shape of the vector dimensions chosen. diff --git a/lib/iris/util.py b/lib/iris/util.py index 458fc3b8b2..ae26b77539 100644 --- a/lib/iris/util.py +++ b/lib/iris/util.py @@ -51,8 +51,8 @@ def broadcast_to_shape(array, shape, dim_map): to, so the first element of *dim_map* gives the index of *shape* that corresponds to the first dimension of *array* etc. - Examples: - + Examples + -------- Broadcasting an array of shape (2, 3) to the shape (5, 2, 6, 3) where the first dimension of the array corresponds to the second element of the desired shape and the second dimension of the array @@ -303,7 +303,6 @@ def rolling_window(a, window=1, step=1, axis=-1): Axis to take the rolling window over Returns: - Array that is a view of the original array with an added dimension of the size of the given window at axis + 1. @@ -590,15 +589,13 @@ def monotonic(array, strict=False, return_direction=False): or -1 for negative. The direction is meaningless if the array is not monotonic. - Returns: - - * monotonic_status (boolean) + Returns + ------- + monotonic_status : bool Whether the array was monotonic. If the return_direction flag was given then the returned value - will be: - - ``(monotonic_status, direction)`` + will be: ``(monotonic_status, direction)`` Notes ------ @@ -1761,16 +1758,18 @@ def find_discontiguities(cube, rel_tol=1e-5, abs_tol=1e-8): The absolute value tolerance to apply in coordinate bounds checking. - Returns: - - * result (`numpy.ndarray` of bool) : + Returns + ------- + result : `numpy.ndarray` of bool true/false map of which cells in the cube XY grid have discontiguities in the coordinate points array. This can be used as the input array for :func:`iris.util.mask_cube`. - Examples:: + Examples + -------- + :: # Find any unknown discontiguities in your cube's x and y arrays: discontiguities = iris.util.find_discontiguities(cube) @@ -1896,7 +1895,6 @@ def mask_cube(cube, points_to_mask, in_place=False, dim=None): Parameters ---------- - cube : iris.cube.Cube Cube containing data that requires masking. @@ -1913,13 +1911,11 @@ def mask_cube(cube, points_to_mask, in_place=False, dim=None): Returns ------- - iris.cube.Cube A cube whose data array is masked at points specified by ``points_to_mask``. Notes ----- - If either ``cube`` or ``points_to_mask`` is lazy, the result will be lazy. This function maintains laziness when called; it does not realise data. @@ -1966,9 +1962,9 @@ def equalise_attributes(cubes): * cubes (iterable of :class:`iris.cube.Cube`): A collection of cubes to compare and adjust. - Returns: - - * removed (list): + Returns + ------- + list A list of dicts holding the removed attributes. Notes