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'