cf.Field.construct_item

Field.construct_item(*identity, default=ValueError(), **filter_kwargs)

Return a metadata construct and its identifier.

If zero or two or more constructs are selected then an exception is raised, or the default parameter is returned.

f.construct_item(*args, **kwargs) is an alias for f.construct(*args, item=True, **kwargs). See construct for details.

New in version (cfdm): 1.8.9.0

See also

construct, construct_key

Parameters

identity: optional

Select constructs that have an identity, defined by their identities methods, that matches any of the given values.

Additionally, the values are matched against construct identifiers, with or without the 'key%' prefix.

If no values are provided then all constructs are selected.

A value may be any object that can match via the == operator, or a re.Pattern object that matches via its search method.

Note that in the output of a dump method or print call, a construct is always described by an identity that will select it.

default: optional

Return the value of the default parameter if there is no unique construct.

If set to an Exception instance then it will be raised instead.

filter_kwargs: optional

Keyword arguments as accepted by Constructs.filter that define additional construct selection criteria.

New in version (cfdm): 1.8.9.0

Returns

tuple

The selected construct and its construct identifier.

Examples

>>> f = cf.example_field(0)

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

>>> print(f.constructs.filter_by_property(standard_name=None))
Constructs:
{'dimensioncoordinate0': <CF DimensionCoordinate: latitude(5) degrees_north>,
 'dimensioncoordinate1': <CF DimensionCoordinate: longitude(8) degrees_east>,
 'dimensioncoordinate2': <CF DimensionCoordinate: long_name=time(1) days since 2018-12-01 >}
>>> f.construct_item('latitude')
('dimensioncoordinate1', <CF DimensionCoordinate: latitude(5) degrees_north>)

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

>>> import re
>>> f.construct(re.compile('^l'))
Traceback
    ...
ValueError: Field.construct() can't return 2 constructs
>>> f.construct(re.compile('^l'), default='no unique construct')
'no unique construct'