cf.Field.construct_key

Field.construct_key(identity, default=ValueError())[source]

Select the key of a metadata construct by its identity.

New in version 1.7.0.

See also

construct, constructs, Constructs.filter_by_identity, Constructs.key

Parameters:

identity: optional

Select constructs that have the given identity. If exactly one construct is selected then it is returned, otherwise an exception is raised.

The identity is specified by a string (e.g. 'latitude', 'long_name=time', etc.); or a compiled regular expression (e.g. re.compile('^atmosphere')), for which all constructs whose identities match (via re.search) are selected.

Each construct has a number of identities, and is selected if any of them match any of those provided. A construct’s identities are those returned by its identities method. In the following example, the construct c has four identities:

>>> c.identities()
['time', 'long_name=Time', 'foo=bar', 'ncvar%T']

In addition, each construct also has an identity based its construct key (e.g. 'key%dimensioncoordinate2')

Note that in the output of a print call or dump method, a construct is always described by one of its identities, and so this description may always be used as an identity argument.

default: optional

Return the value of the default parameter if the property has not been set. If set to an Exception instance then it will be raised instead.
Returns:
str

The key of the selected construct.

Examples:

>>> print(f.constructs)
Constructs:
{'cellmethod0': <CellMethod: area: mean>,
 'dimensioncoordinate0': <DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <DimensionCoordinate: long_name=time(1) days since 2018-12-01 >,
 'domainaxis0': <DomainAxis: size(5)>,
 'domainaxis1': <DomainAxis: size(8)>,
 'domainaxis2': <DomainAxis: size(1)>}

Select the construct that has the “standard_name” property of ‘latitude’:

>>> f.construct_key('latitude')
 'dimensioncoordinate0'

Select the cell method construct that has a “method” of ‘mean’:

>>> f.construct_key('method:mean')
'cellmethod0'

Attempt to select the construct whose “standard_name” start with the letter ‘l’:

>>> import re
>>> f.construct_key(re.compile('^l'))
ValueError: Can't return the key of 2 constructs
>>> f.construct_key(re.compile('^l'), default='no construct')
'no construct'