diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index f33e546dc3..0b1b8db1b6 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -43,6 +43,7 @@ This document explains the changes made to Iris for this release #. `@gcaria`_ fixed :meth:`~iris.cube.Cube.cell_measure_dims` to also accept the string name of a :class:`~iris.coords.CellMeasure`. (:pull:`3931`) + #. `@gcaria`_ fixed :meth:`~iris.cube.Cube.ancillary_variable_dims` to also accept the string name of a :class:`~iris.coords.AncillaryVariable`. (:pull:`3931`) @@ -68,10 +69,12 @@ This document explains the changes made to Iris for this release 📚 Documentation ================ -#. `@rcomer`_ updated the "Seasonal ensemble model plots" Gallery example. - (:pull:`3933`) -#. `@MHBalsmeier`_ Described non-conda installation on Debian-based distros. - (:pull:`3958`) +#. `@rcomer`_ updated the "Seasonal ensemble model plots" Gallery example. (:pull:`3933`) + +#. `@MHBalsmeier`_ described non-conda installation on Debian-based distros. (:pull:`3958`) + +#. `@bjlittle`_ clarified in the doc-string that :class:`~iris.coords.Coord` is now an `abstract base class`_ of + coordinates since ``v3.0.0``, and it is **not** possible to create an instance of it. (:pull:`3971`) 💼 Internal @@ -80,10 +83,19 @@ This document explains the changes made to Iris for this release #. `@rcomer`_ removed an old unused test file. (:pull:`3913`) +.. comment + What's new author names (@github name) in alphabetical order: -.. _GitHub: https://github.com/SciTools/iris/issues/new/choose -.. _@pelson: https://github.com/pelson -.. _@trexfeathers: https://github.com/trexfeathers +.. _@bjlittle: https://github.com/bjlittle .. _@gcaria: https://github.com/gcaria -.. _@rcomer: https://github.com/rcomer .. _@MHBalsmeier: https://github.com/MHBalsmeier +.. _@pelson: https://github.com/pelson +.. _@rcomer: https://github.com/rcomer +.. _@trexfeathers: https://github.com/trexfeathers + + +.. comment + What's new resources in alphabetical order: + +.. _abstract base class: https://docs.python.org/3/library/abc.html +.. _GitHub: https://github.com/SciTools/iris/issues/new/choose diff --git a/docs/iris/src/whatsnew/latest.rst.template b/docs/iris/src/whatsnew/latest.rst.template index 0dd7cc788b..75a1f8cd76 100644 --- a/docs/iris/src/whatsnew/latest.rst.template +++ b/docs/iris/src/whatsnew/latest.rst.template @@ -79,9 +79,16 @@ This document explains the changes made to Iris for this release 💼 Internal =========== -* N/A +#. N/A + + +.. comment + What's new author names (@github name) in alphabetical order: + +.. comment + What's new resources in alphabetical order: .. _GitHub: https://github.com/SciTools/iris/issues/new/choose diff --git a/lib/iris/coords.py b/lib/iris/coords.py index 76ca83cd96..cfeb24cdcb 100644 --- a/lib/iris/coords.py +++ b/lib/iris/coords.py @@ -12,7 +12,6 @@ from collections import namedtuple from collections.abc import Iterator import copy -from functools import wraps from itertools import chain, zip_longest import operator import warnings @@ -1272,7 +1271,7 @@ def contains_point(self, point): class Coord(_DimensionalMetadata): """ - Superclass for coordinates. + Abstract base class for coordinates. """ @@ -1291,7 +1290,7 @@ def __init__( ): """ - Constructs a single coordinate. + Coordinate abstract base class. As of ``v3.0.0`` you **cannot** create an instance of :class:`Coord`. Args: @@ -1313,17 +1312,17 @@ def __init__( * bounds An array of values describing the bounds of each cell. Given n bounds for each cell, the shape of the bounds array should be - points.shape + (n,). For example, a 1d coordinate with 100 points + points.shape + (n,). For example, a 1D coordinate with 100 points and two bounds per cell would have a bounds array of shape (100, 2) Note if the data is a climatology, `climatological` should be set. * attributes - A dictionary containing other cf and user-defined attributes. + A dictionary containing other CF and user-defined attributes. * coord_system A :class:`~iris.coord_systems.CoordSystem` representing the coordinate system of the coordinate, - e.g. a :class:`~iris.coord_systems.GeogCS` for a longitude Coord. + e.g., a :class:`~iris.coord_systems.GeogCS` for a longitude coordinate. * climatological (bool): When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a @@ -2250,7 +2249,8 @@ def _xml_id_extra(self, unique_value): class DimCoord(Coord): """ - A coordinate that is 1D, numeric, and strictly monotonic. + A coordinate that is 1D, and numeric, with values that have a strict monotonic ordering. Missing values are not + permitted in a :class:`DimCoord`. """ @@ -2275,7 +2275,7 @@ def from_regular( optionally bounds. The majority of the arguments are defined as for - :meth:`Coord.__init__`, but those which differ are defined below. + :class:`Coord`, but those which differ are defined below. Args: @@ -2336,8 +2336,9 @@ def __init__( climatological=False, ): """ - Create a 1D, numeric, and strictly monotonic :class:`Coord` with - read-only points and bounds. + Create a 1D, numeric, and strictly monotonic coordinate with **immutable** points and bounds. + + Missing values are not permitted. Args: @@ -2369,11 +2370,11 @@ def __init__( Note if the data is a climatology, `climatological` should be set. * attributes: - A dictionary containing other cf and user-defined attributes. + A dictionary containing other CF and user-defined attributes. * coord_system: A :class:`~iris.coord_systems.CoordSystem` representing the coordinate system of the coordinate, - e.g. a :class:`~iris.coord_systems.GeogCS` for a longitude Coord. + e.g., a :class:`~iris.coord_systems.GeogCS` for a longitude coordinate. * circular (bool): Whether the coordinate wraps by the :attr:`~iris.coords.DimCoord.units.modulus` i.e., the longitude coordinate wraps around the full great circle. @@ -2624,15 +2625,54 @@ class AuxCoord(Coord): """ A CF auxiliary coordinate. - .. note:: - - There are currently no specific properties of :class:`AuxCoord`, - everything is inherited from :class:`Coord`. - """ - @wraps(Coord.__init__, assigned=("__doc__",), updated=()) def __init__(self, *args, **kwargs): + """ + Create a coordinate with **mutable** points and bounds. + + Args: + + * points: + The values (or value in the case of a scalar coordinate) for each + cell of the coordinate. + + Kwargs: + + * standard_name: + CF standard name of the coordinate. + * long_name: + Descriptive name of the coordinate. + * var_name: + The netCDF variable name for the coordinate. + * units + The :class:`~cf_units.Unit` of the coordinate's values. + Can be a string, which will be converted to a Unit object. + * bounds + An array of values describing the bounds of each cell. Given n + bounds for each cell, the shape of the bounds array should be + points.shape + (n,). For example, a 1D coordinate with 100 points + and two bounds per cell would have a bounds array of shape + (100, 2) + Note if the data is a climatology, `climatological` + should be set. + * attributes + A dictionary containing other CF and user-defined attributes. + * coord_system + A :class:`~iris.coord_systems.CoordSystem` representing the + coordinate system of the coordinate, + e.g., a :class:`~iris.coord_systems.GeogCS` for a longitude coordinate. + * climatological (bool): + When True: the coordinate is a NetCDF climatological time axis. + When True: saving in NetCDF will give the coordinate variable a + 'climatology' attribute and will create a boundary variable called + '_climatology' in place of a standard bounds + attribute and bounds variable. + Will set to True when a climatological time axis is loaded + from NetCDF. + Always False if no bounds exist. + + """ super().__init__(*args, **kwargs) # Logically, :class:`Coord` is an abstract class and all actual coords must