iris.common.metadata

Provides the infrastructure to support the common metadata API.

class iris.common.metadata.AncillaryVariableMetadata(standard_name, long_name, var_name, units, attributes)

Bases: AncillaryVariableMetadataNamedtuple, BaseMetadata

Metadata container for a AncillaryVariableMetadata.

Create new instance of AncillaryVariableMetadataNamedtuple(standard_name, long_name, var_name, units, attributes)

__eq__(other)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Returns:

Boolean.

combine(other, lenient=None)

Return a new metadata instance created by combining each of the associated metadata members.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance.

difference(other, lenient=None)

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance of member differences or None.

equal(other, lenient=None)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Boolean.

class iris.common.metadata.BaseMetadata(standard_name, long_name, var_name, units, attributes)

Bases: BaseMetadataNamedtuple

Container for common metadata.

Create new instance of BaseMetadataNamedtuple(standard_name, long_name, var_name, units, attributes)

__eq__(other)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Returns:

Boolean.

combine(other, lenient=None)

Return a new metadata instance created by combining each of the associated metadata members.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance.

difference(other, lenient=None)

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance of member differences or None.

equal(other, lenient=None)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Boolean.

classmethod from_metadata(other)

Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.

Non-common metadata members are set to None.

Args:

• other (metadata):

  A metadata instance of any type.

Returns:

New metadata instance.

name(default=None, token=False)

Returns a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Kwargs:

• default:

  The fall-back string representing the default name. Defaults to the string ‘unknown’.

• token:

  If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Returns:

String.

classmethod token(name)

Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.

Args:

• name:

  The string name to verify

Returns:

The provided name if valid, otherwise None.

DEFAULT_NAME = 'unknown'

class iris.common.metadata.CellMeasureMetadata(standard_name, long_name, var_name, units, attributes, measure)

Bases: CellMeasureMetadataNamedtuple, BaseMetadata

Metadata container for a CellMeasure.

Create new instance of CellMeasureMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, measure)

__eq__(other)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Returns:

Boolean.

combine(other, lenient=None)

Return a new metadata instance created by combining each of the associated metadata members.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance.

difference(other, lenient=None)

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance of member differences or None.

equal(other, lenient=None)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Boolean.

class iris.common.metadata.CoordMetadata(standard_name, long_name, var_name, units, attributes, coord_system, climatological)

Bases: CoordMetadataNamedtuple, BaseMetadata

Metadata container for a Coord.

Create new instance of CoordMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, coord_system, climatological)

__eq__(other)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Returns:

Boolean.

combine(other, lenient=None)

Return a new metadata instance created by combining each of the associated metadata members.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance.

difference(other, lenient=None)

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance of member differences or None.

equal(other, lenient=None)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Boolean.

class iris.common.metadata.CubeMetadata(standard_name, long_name, var_name, units, attributes, cell_methods)

Bases: CubeMetadataNamedtuple, BaseMetadata

Metadata container for a Cube.

Create new instance of CubeMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, cell_methods)

__eq__(other)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Returns:

Boolean.

combine(other, lenient=None)

Return a new metadata instance created by combining each of the associated metadata members.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance.

difference(other, lenient=None)

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance of member differences or None.

equal(other, lenient=None)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Boolean.

name(default=None, token=False)

Returns a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Kwargs:

• default:

  The fall-back string representing the default name. Defaults to the string ‘unknown’.

• token:

  If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Returns:

String.

class iris.common.metadata.DimCoordMetadata(standard_name, long_name, var_name, units, attributes, coord_system, climatological, circular)

Bases: DimCoordMetadataNamedtuple, CoordMetadata

Metadata container for a DimCoord

Create new instance of DimCoordMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, coord_system, climatological, circular)

__eq__(other)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Returns:

Boolean.

combine(other, lenient=None)

Return a new metadata instance created by combining each of the associated metadata members.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance.

difference(other, lenient=None)

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Metadata instance of member differences or None.

equal(other, lenient=None)

Determine whether the associated metadata members are equivalent.

Args:

• other (metadata):

  A metadata instance of the same type.

Kwargs:

• lenient (boolean):

  Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns:

Boolean.

iris.common.metadata.hexdigest(item)

Calculate a hexadecimal string hash representation of the provided item.

Calculates a 64-bit non-cryptographic hash of the provided item, using the extremely fast xxhash hashing algorithm, and returns the hexdigest string representation of the hash.

This provides a means to compare large and/or complex objects through simple string hexdigest comparison.

Args:

• item (object):

  The item that requires to have its hexdigest calculated.

Returns:

The string hexadecimal representation of the item’s 64-bit hash.

iris.common.metadata.metadata_filter(instances, item=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None)

Filter a collection of objects by their metadata to fit the given metadata criteria.

Criteria can be either specific properties or other objects with metadata to be matched.

Args:

• instances:

  One or more objects to be filtered.

Kwargs:

• item:

  Either,

  • a standard_name, long_name, or var_name which is compared against the name().

  • a coordinate or metadata instance equal to that of the desired objects e.g., DimCoord or CoordMetadata.

• standard_name:

  The CF standard name of the desired object. If None, does not check for standard_name.

• long_name:

  An unconstrained description of the object. If None, does not check for long_name.

• var_name:

  The NetCDF variable name of the desired object. If None, does not check for var_name.

• attributes:

  A dictionary of attributes desired on the object. If None, does not check for attributes.

• axis:

  The desired object’s axis, see guess_coord_axis(). If None, does not check for axis. Accepts the values X, Y, Z and T (case-insensitive).

Returns:

A list of the objects supplied in the instances argument, limited to only those that matched the given criteria.

iris.common.metadata.metadata_manager_factory(cls, **kwargs)

A class instance factory function responsible for manufacturing metadata instances dynamically at runtime.

The factory instances returned by the factory are capable of managing their metadata state, which can be proxied by the owning container.

Args:

• cls:

  A subclass of BaseMetadata, defining the metadata to be managed.

Kwargs:

• kwargs:

  Initial values for the manufactured metadata instance. Unspecified fields will default to a value of ‘None’.

Returns:

A manager instance for the provided metadata cls.

iris.common.metadata.SERVICES = [<function AncillaryVariableMetadata.combine>, <function BaseMetadata.combine>, <function CellMeasureMetadata.combine>, <function CoordMetadata.combine>, <function CubeMetadata.combine>, <function DimCoordMetadata.combine>, <function AncillaryVariableMetadata.difference>, <function BaseMetadata.difference>, <function CellMeasureMetadata.difference>, <function CoordMetadata.difference>, <function CubeMetadata.difference>, <function DimCoordMetadata.difference>, <function AncillaryVariableMetadata.__eq__>, <function AncillaryVariableMetadata.equal>, <function BaseMetadata.__eq__>, <function BaseMetadata.equal>, <function CellMeasureMetadata.__eq__>, <function CellMeasureMetadata.equal>, <function CoordMetadata.__eq__>, <function CoordMetadata.equal>, <function CubeMetadata.__eq__>, <function CubeMetadata.equal>, <function DimCoordMetadata.__eq__>, <function DimCoordMetadata.equal>, <function ConnectivityMetadata.combine>, <function ConnectivityMetadata.difference>, <function ConnectivityMetadata.__eq__>, <function ConnectivityMetadata.equal>, <function MeshMetadata.combine>, <function MeshMetadata.difference>, <function MeshMetadata.__eq__>, <function MeshMetadata.equal>, <function MeshCoordMetadata.combine>, <function MeshCoordMetadata.difference>, <function MeshCoordMetadata.__eq__>, <function MeshCoordMetadata.equal>]

Convenience collection of lenient metadata services.

iris.common.metadata.SERVICES_DIFFERENCE = [<function AncillaryVariableMetadata.difference>, <function BaseMetadata.difference>, <function CellMeasureMetadata.difference>, <function CoordMetadata.difference>, <function CubeMetadata.difference>, <function DimCoordMetadata.difference>, <function ConnectivityMetadata.difference>, <function MeshMetadata.difference>, <function MeshCoordMetadata.difference>]

Convenience collection of lenient metadata difference services.

iris.common.metadata.SERVICES_EQUAL = [<function AncillaryVariableMetadata.__eq__>, <function AncillaryVariableMetadata.equal>, <function BaseMetadata.__eq__>, <function BaseMetadata.equal>, <function CellMeasureMetadata.__eq__>, <function CellMeasureMetadata.equal>, <function CoordMetadata.__eq__>, <function CoordMetadata.equal>, <function CubeMetadata.__eq__>, <function CubeMetadata.equal>, <function DimCoordMetadata.__eq__>, <function DimCoordMetadata.equal>, <function ConnectivityMetadata.__eq__>, <function ConnectivityMetadata.equal>, <function MeshMetadata.__eq__>, <function MeshMetadata.equal>, <function MeshCoordMetadata.__eq__>, <function MeshCoordMetadata.equal>]

Convenience collection of lenient metadata equality services.