data.core.metadata ================== .. py:module:: data.core.metadata Classes ------- .. autoapisummary:: data.core.metadata.Metadata data.core.metadata.RawMetadata Module Contents --------------- .. py:class:: Metadata Base class to represent metadata. Metadata is a dict-like immutable object. Modification is possible with :obj:`override`, which always creates a new object. Implemented in subclasses: :obj:`RawMetadata`, :obj:`GribMetadata`. :param cache: Enable caching of all the calls to :meth:`get`. Default is False. The cache is attached to the instance. :type cache: :class:`bool`, :class:`dict-like`, *optional* .. rubric:: Examples - :ref:`/examples/metadata.ipynb` .. py:method:: as_namespace(namespace=None) :abstractmethod: Return all the keys/values from a namespace. :param namespace: The namespace. When `namespace` is None or an empty :obj:`str` all the available keys/values are returned. :type namespace: :class:`str`, :obj:`None` :returns: All the keys/values from the `namespace`. :rtype: :class:`dict` .. py:method:: base_datetime() :abstractmethod: .. py:method:: data_format() :abstractmethod: Return the underlying data format. :rtype: :class:`str` .. py:method:: datetime() :abstractmethod: Return the date and time of the field. :returns: Dict with items "base_time" and "valid_time". :rtype: :class:`dict` of :class:`datatime.datetime` .. rubric:: Examples >>> import earthkit.data >>> ds = earthkit.data.from_source("file", "tests/data/t_time_series.grib") >>> ds[4].datetime() {'base_time': datetime.datetime(2020, 12, 21, 12, 0), 'valid_time': datetime.datetime(2020, 12, 21, 18, 0)} .. py:method:: describe_keys() :abstractmethod: Return the keys to be used with the :meth:`describe` method. .. py:method:: dump(**kwargs) :abstractmethod: Generate a dump from the metadata content. .. py:property:: geography :abstractmethod: Get geography description. If it is not available None is returned. :type: :obj:`Geography` .. py:method:: get(key, default=None, *, astype=None, raise_on_missing=False) :abstractmethod: Return the value for ``key``. :param key: Metadata key :type key: :class:`str` :param default: Specify the default value for ``key``. Returned when ``key`` is not found or its value is a missing value and raise_on_missing is ``False``. :type default: :class:`value` :param astype: Return/access type for ``key``. When it is supported ``astype`` is passed to the underlying metadata accessor as an option. Otherwise the value is cast to ``astype`` after it is taken from the accessor. :type astype: :class:`type as str`, :class:`int` or :class:`float` :param raise_on_missing: When it is True raises an exception if ``key`` is not found or it has a missing value. :type raise_on_missing: :class:`bool` :returns: Returns the ``key`` value. Returns ``default`` if ``key`` is not found or it has a missing value and ``raise_on_missing`` is False. :rtype: :class:`value` :raises KeyError: If ``raise_on_missing`` is True and ``key`` is not found or it has a missing value. .. py:method:: index_keys() :abstractmethod: Return the keys to be used with the :meth:`indices` method. .. py:method:: items() :abstractmethod: Return the metadata items. :rtype: :class:`Iterable` of :obj:`(key,value)` pairs .. py:method:: keys() :abstractmethod: Return the metadata keys. :rtype: :class:`Iterable` of :class:`str` .. py:method:: ls_keys() :abstractmethod: Return the keys to be used with the :meth:`ls` method. .. py:method:: namespaces() :abstractmethod: Return the available namespaces. :rtype: :class:`list` of :class:`str` .. py:method:: override(*args, **kwargs) :abstractmethod: Change the metadata values and return a new object. :obj:`override` accepts another :obj:`Metadata` or a dict or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the metadata is then updated with those key/value pairs. .. rubric:: Examples >>> other = RawMetadata({"key1": 1, "key2": 2}) >>> m1 = m.override(other) >>> m1 = m.override({"key1": 1, "key2": 2}) >>> m1 = m.override([("key1", 1), ("key2", 2)]) >>> m1 = m.override(key1=1, key2=2) .. py:method:: valid_datetime() :abstractmethod: .. py:class:: RawMetadata(*args, **kwargs) Bases: :py:obj:`Metadata` Metadata implementation based on key/value pairs. >>> from earthkit.data.core.metadata import RawMetadata >>> md = RawMetadata({"shortName": "2t", "perturbationNumber": 5}) >>> md = RawMetadata([("shortName", "2t"), ("perturbationNumber", 5)]) >>> md = RawMetadata(shortName="2t", perturbationNumber=5) >>> md RawMetadata({'shortName': '2t', 'perturbationNumber': 5}) >>> md2 = RawMetadata(md) >>> md2 RawMetadata({'shortName': '2t', 'perturbationNumber': 5}) Value access: >>> "shortName" in md True >>> md["shortName"] '2t' >>> md.get("shortName") '2t' >>> "step" in md False >>> md.get("step") >>> md.get("step", 0) 0 .. rubric:: Examples - :ref:`/examples/metadata.ipynb` .. py:method:: as_namespace(namespace) Return all the keys/values from a namespace. :param namespace: The namespace. When `namespace` is None or an empty :obj:`str` all the available keys/values are returned. :type namespace: :class:`str`, :obj:`None` :returns: All the keys/values from the `namespace`. :rtype: :class:`dict` .. py:method:: base_datetime() .. py:method:: data_format() Return the underlying data format. :rtype: :class:`str` .. py:method:: datetime() Return the date and time of the field. :returns: Dict with items "base_time" and "valid_time". :rtype: :class:`dict` of :class:`datatime.datetime` .. rubric:: Examples >>> import earthkit.data >>> ds = earthkit.data.from_source("file", "tests/data/t_time_series.grib") >>> ds[4].datetime() {'base_time': datetime.datetime(2020, 12, 21, 12, 0), 'valid_time': datetime.datetime(2020, 12, 21, 18, 0)} .. py:method:: describe_keys() Return the keys to be used with the :meth:`describe` method. .. py:method:: dump(**kwargs) Generate a dump from the metadata content. .. py:property:: geography Get geography description. If it is not available None is returned. :type: :obj:`Geography` .. py:method:: get(key, default=None, *, astype=None, raise_on_missing=False) Return the value for ``key``. :param key: Metadata key :type key: :class:`str` :param default: Specify the default value for ``key``. Returned when ``key`` is not found or its value is a missing value and raise_on_missing is ``False``. :type default: :class:`value` :param astype: Return/access type for ``key``. When it is supported ``astype`` is passed to the underlying metadata accessor as an option. Otherwise the value is cast to ``astype`` after it is taken from the accessor. :type astype: :class:`type as str`, :class:`int` or :class:`float` :param raise_on_missing: When it is True raises an exception if ``key`` is not found or it has a missing value. :type raise_on_missing: :class:`bool` :returns: Returns the ``key`` value. Returns ``default`` if ``key`` is not found or it has a missing value and ``raise_on_missing`` is False. :rtype: :class:`value` :raises KeyError: If ``raise_on_missing`` is True and ``key`` is not found or it has a missing value. .. py:method:: index_keys() Return the keys to be used with the :meth:`indices` method. .. py:method:: items() Return the metadata items. :rtype: :class:`Iterable` of :obj:`(key,value)` pairs .. py:method:: keys() Return the metadata keys. :rtype: :class:`Iterable` of :class:`str` .. py:method:: ls_keys() Return the keys to be used with the :meth:`ls` method. .. py:method:: namespaces() Return the available namespaces. :rtype: :class:`list` of :class:`str` .. py:method:: override(*args, **kwargs) Change the metadata values and return a new object. :obj:`override` accepts another :obj:`Metadata` or a dict or an iterable of key/value pairs (as tuples or other iterables of length two). If keyword arguments are specified, the metadata is then updated with those key/value pairs. .. rubric:: Examples >>> other = RawMetadata({"key1": 1, "key2": 2}) >>> m1 = m.override(other) >>> m1 = m.override({"key1": 1, "key2": 2}) >>> m1 = m.override([("key1", 1), ("key2", 2)]) >>> m1 = m.override(key1=1, key2=2) .. py:method:: valid_datetime()