You are viewing the latest unreleased documentation v3.2.dev0. You may prefer a stable version.

iris.common.metadata

Provides the infrastructure to support the common metadata API.

In this module:

Metadata container for a AncillaryVariableMetadata.

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

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

__eq__(other)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Returns

Boolean.

combine(other, lenient=None)[source]

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.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

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

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.

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

Return first index of value.

Raises ValueError if the value is not present.

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'
attributes

Alias for field number 4

long_name

Alias for field number 1

standard_name

Alias for field number 0

units

Alias for field number 3

var_name

Alias for field number 2

↑ top ↑

Container for common metadata.

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

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

__eq__(other)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Returns

Boolean.

combine(other, lenient=None)[source]

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.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

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

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

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.

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

Return first index of value.

Raises ValueError if the value is not present.

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

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

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'
attributes

Alias for field number 4

long_name

Alias for field number 1

standard_name

Alias for field number 0

units

Alias for field number 3

var_name

Alias for field number 2

↑ top ↑

Metadata container for a CellMeasure.

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

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

__eq__(other)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Returns

Boolean.

combine(other, lenient=None)[source]

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.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

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

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.

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

Return first index of value.

Raises ValueError if the value is not present.

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'
attributes

Alias for field number 4

long_name

Alias for field number 1

measure

Alias for field number 5

standard_name

Alias for field number 0

units

Alias for field number 3

var_name

Alias for field number 2

↑ top ↑

Metadata container for a Coord.

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

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

__eq__(other)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Returns

Boolean.

combine(other, lenient=None)[source]

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.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

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

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.

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

Return first index of value.

Raises ValueError if the value is not present.

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'
attributes

Alias for field number 4

climatological

Alias for field number 6

coord_system

Alias for field number 5

long_name

Alias for field number 1

standard_name

Alias for field number 0

units

Alias for field number 3

var_name

Alias for field number 2

↑ top ↑

Metadata container for a Cube.

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

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

__eq__(other)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Returns

Boolean.

combine(other, lenient=None)[source]

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.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

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

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.

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

Return first index of value.

Raises ValueError if the value is not present.

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

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'
attributes

Alias for field number 4

cell_methods

Alias for field number 5

long_name

Alias for field number 1

standard_name

Alias for field number 0

units

Alias for field number 3

var_name

Alias for field number 2

↑ top ↑

Metadata container for a DimCoord

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

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

__eq__(other)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Returns

Boolean.

combine(other, lenient=None)[source]

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.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

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

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.

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

Return first index of value.

Raises ValueError if the value is not present.

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'
attributes

Alias for field number 4

circular

Alias for field number 7

climatological

Alias for field number 6

coord_system

Alias for field number 5

long_name

Alias for field number 1

standard_name

Alias for field number 0

units

Alias for field number 3

var_name

Alias for field number 2

↑ top ↑

iris.common.metadata.SERVICES

Convenience collection of lenient metadata services.

↑ top ↑

iris.common.metadata.SERVICES_COMBINE

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

↑ top ↑

iris.common.metadata.SERVICES_DIFFERENCE

Convenience collection of lenient metadata difference services.

↑ top ↑

iris.common.metadata.SERVICES_EQUAL

Convenience collection of lenient metadata equality services.

↑ top ↑

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

Calculate a hexidecimal 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 hexidecimal representation of the item’s 64-bit hash.

↑ top ↑

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.

Args:

  • instances:

    One or more objects to be filtered.

Kwargs:

  • item:

    Either,

  • 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.

↑ top ↑

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

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.