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)[source]#

Bases: AncillaryVariableMetadataNamedtuple, BaseMetadata

Metadata container for a AncillaryVariableMetadata.

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

DEFAULT_NAME = 'unknown'#

__eq__(other)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:: other (metadata) – A metadata instance of the same type.
Return type:: bool

attributes#: Alias for field number 4

combine(other, lenient=None)[source]#

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

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance.

count(value, /)#: Return number of occurrences of value.

difference(other, lenient=None)[source]#

Perform lenient metadata difference operation.

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.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance of member differences or None.

equal(other, lenient=None)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Return type:

bool

classmethod from_metadata(other)#

Convert metadata instance to this metadata type.

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.

Parameters:: other (metadata) – A metadata instance of any type.
Return type:: New metadata instance.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

long_name#: Alias for field number 1

name(default=None, token=False)#

Return 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’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – 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.

Return type:

str

standard_name#: Alias for field number 0

classmethod token(name)#

Verify validity of provided NetCDF name.

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

Parameters:: name (str) – The string name to verify.
Return type:: The provided name if valid, otherwise None.

units#: Alias for field number 3

var_name#: Alias for field number 2

class iris.common.metadata.BaseMetadata(standard_name, long_name, var_name, units, attributes)[source]#

Bases: BaseMetadataNamedtuple

Container for common metadata.

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

DEFAULT_NAME = 'unknown'#

__eq__(other)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:: other (metadata) – A metadata instance of the same type.
Return type:: bool

attributes#: Alias for field number 4

combine(other, lenient=None)[source]#

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

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance.

count(value, /)#: Return number of occurrences of value.

difference(other, lenient=None)[source]#

Perform lenient metadata difference operation.

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.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance of member differences or None.

equal(other, lenient=None)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Return type:

bool

classmethod from_metadata(other)[source]#

Convert metadata instance to this metadata type.

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.

Parameters:: other (metadata) – A metadata instance of any type.
Return type:: New metadata instance.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

long_name#: Alias for field number 1

name(default=None, token=False)[source]#

Return 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’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – 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.

Return type:

str

standard_name#: Alias for field number 0

classmethod token(name)[source]#

Verify validity of provided NetCDF name.

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

Parameters:: name (str) – The string name to verify.
Return type:: The provided name if valid, otherwise None.

units#: Alias for field number 3

var_name#: Alias for field number 2

class iris.common.metadata.CellMeasureMetadata(standard_name, long_name, var_name, units, attributes, measure)[source]#

Bases: CellMeasureMetadataNamedtuple, BaseMetadata

Metadata container for a CellMeasure.

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

DEFAULT_NAME = 'unknown'#

__eq__(other)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:: other (metadata) – A metadata instance of the same type.
Return type:: bool

attributes#: Alias for field number 4

combine(other, lenient=None)[source]#

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

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance.

count(value, /)#: Return number of occurrences of value.

difference(other, lenient=None)[source]#

Perform lenient metadata difference operation.

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.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance of member differences or None.

equal(other, lenient=None)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Return type:

bool

classmethod from_metadata(other)#

Convert metadata instance to this metadata type.

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.

Parameters:: other (metadata) – A metadata instance of any type.
Return type:: New metadata instance.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

long_name#: Alias for field number 1

measure#: Alias for field number 5

name(default=None, token=False)#

Return 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’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – 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.

Return type:

str

standard_name#: Alias for field number 0

classmethod token(name)#

Verify validity of provided NetCDF name.

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

Parameters:: name (str) – The string name to verify.
Return type:: The provided name if valid, otherwise None.

units#: Alias for field number 3

var_name#: Alias for field number 2

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

Bases: CoordMetadataNamedtuple, BaseMetadata

Metadata container for a Coord.

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

DEFAULT_NAME = 'unknown'#

__eq__(other)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:: other (metadata) – A metadata instance of the same type.
Return type:: bool

attributes#: Alias for field number 4

climatological#: Alias for field number 6

combine(other, lenient=None)[source]#

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

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance.

coord_system#: Alias for field number 5

count(value, /)#: Return number of occurrences of value.

difference(other, lenient=None)[source]#

Perform lenient metadata difference operation.

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.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance of member differences or None.

equal(other, lenient=None)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Return type:

bool

classmethod from_metadata(other)#

Convert metadata instance to this metadata type.

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.

Parameters:: other (metadata) – A metadata instance of any type.
Return type:: New metadata instance.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

long_name#: Alias for field number 1

name(default=None, token=False)#

Return 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’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – 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.

Return type:

str

standard_name#: Alias for field number 0

classmethod token(name)#

Verify validity of provided NetCDF name.

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

Parameters:: name (str) – The string name to verify.
Return type:: The provided name if valid, otherwise None.

units#: Alias for field number 3

var_name#: Alias for field number 2

class iris.common.metadata.CubeMetadata(standard_name, long_name, var_name, units, attributes, cell_methods)[source]#

Bases: CubeMetadataNamedtuple, BaseMetadata

Metadata container for a Cube.

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

DEFAULT_NAME = 'unknown'#

__eq__(other)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:: other (metadata) – A metadata instance of the same type.
Return type:: bool

attributes#: Alias for field number 4

cell_methods#: Alias for field number 5

combine(other, lenient=None)[source]#

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

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance.

count(value, /)#: Return number of occurrences of value.

difference(other, lenient=None)[source]#

Perform lenient metadata difference operation.

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.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance of member differences or None.

equal(other, lenient=None)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Return type:

bool

classmethod from_metadata(other)#

Convert metadata instance to this metadata type.

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.

Parameters:: other (metadata) – A metadata instance of any type.
Return type:: New metadata instance.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

long_name#: Alias for field number 1

name(default=None, token=False)[source]#

Return 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’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – 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.

Return type:

str

standard_name#: Alias for field number 0

classmethod token(name)#

Verify validity of provided NetCDF name.

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

Parameters:: name (str) – The string name to verify.
Return type:: The provided name if valid, otherwise None.

units#: Alias for field number 3

var_name#: Alias for field number 2

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

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)

DEFAULT_NAME = 'unknown'#

__eq__(other)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:: other (metadata) – A metadata instance of the same type.
Return type:: bool

attributes#: Alias for field number 4

circular#: Alias for field number 7

climatological#: Alias for field number 6

combine(other, lenient=None)[source]#

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

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance.

coord_system#: Alias for field number 5

count(value, /)#: Return number of occurrences of value.

difference(other, lenient=None)[source]#

Perform lenient metadata difference operation.

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.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Return type:

Metadata instance of member differences or None.

equal(other, lenient=None)[source]#

Determine whether the associated metadata members are equivalent.

Parameters:

other (metadata) – A metadata instance of the same type.
lenient (bool, optional) – Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Return type:

bool

classmethod from_metadata(other)#

Convert metadata instance to this metadata type.

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.

Parameters:: other (metadata) – A metadata instance of any type.
Return type:: New metadata instance.

index(value, start=0, stop=9223372036854775807, /)#

Return first index of value.

Raises ValueError if the value is not present.

long_name#: Alias for field number 1

name(default=None, token=False)#

Return 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’.

Parameters:

default (optional) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool, default=False) – 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.

Return type:

str

standard_name#: Alias for field number 0

classmethod token(name)#

Verify validity of provided NetCDF name.

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

Parameters:: name (str) – The string name to verify.
Return type:: The provided name if valid, otherwise None.

units#: Alias for field number 3

var_name#: Alias for field number 2

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.

iris.common.metadata.hexdigest(item)[source]#

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.

Parameters:: item (object) – The item that requires to have its hexdigest calculated.
Returns:: The string hexadecimal representation of the item’s 64-bit hash.
Return type:: str

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

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.

Parameters:

instances – One or more objects to be filtered.
item (optional) –
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 (optional) – The CF standard name of the desired object. If None, does not check for standard_name.
long_name (optional) – An unconstrained description of the object. If None, does not check for long_name.
var_name (optional) – The NetCDF variable name of the desired object. If None, does not check for var_name.
attributes (dict, optional) – A dictionary of attributes desired on the object. If None, does not check for attributes.
axis (optional) – 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.

Return type:

list of the objects

iris.common.metadata.metadata_manager_factory(cls, **kwargs)[source]#

Manufacturing metadata instances.

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.

Parameters:

cls – A subclass of BaseMetadata, defining the metadata to be managed.
**kwargs (dict, optional) – Initial values for the manufactured metadata instance. Unspecified fields will default to a value of ‘None’.

Return type:

A manager instance for the provided metadata cls.