data.readers.grib.metadata ========================== .. py:module:: data.readers.grib.metadata Classes ------- .. autoapisummary:: data.readers.grib.metadata.GribFieldMetadata data.readers.grib.metadata.GribMetadata data.readers.grib.metadata.RestrictedGribMetadata data.readers.grib.metadata.StandAloneGribMetadata Module Contents --------------- .. py:class:: GribFieldMetadata(field, **kwargs) Bases: :py:obj:`GribMetadata` Represent the metadata of a GRIB field. :obj:`GribFieldMetadata` is created internally by a :obj:`GribField`. It does not own the ecCodes GRIB handle but can access it through the :obj:`GribField`. Calling :meth:`metadata` without arguments on a :obj:`GribField` returns this object. .. py:method:: as_namespace(namespace=None) Return all the keys/values from a namespace. :param namespace: The :xref:`eccodes_namespace`. earthkit-data also defines the "default" namespace, which contains all the GRIB keys that ecCodes can access without specifying a 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(namespace=all, **kwargs) Generate dump with all the metadata keys belonging to ``namespace``. In a Jupyter notebook it is represented as a tabbed interface. :param namespace: The namespace to dump. Any :xref:`eccodes_namespace` can be used here. earthkit-data also defines the "default" namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. The following `namespace` values have a special meaning: - :obj:`all`: all the available namespaces will be used (including "default"). - None or empty str: the "default" namespace will be used. :type namespace: :obj:`str`, :obj:`list`, :obj:`tuple`, :obj:`None` or :obj:`all` :param \*\*kwargs: Other keyword arguments used for testing only :type \*\*kwargs: :class:`dict`, *optional* :returns: Dict-like object with one item per namespace. In a Jupyter notebook represented as a tabbed interface to browse the dump contents. :rtype: :class:`NamespaceDump` .. rubric:: Examples :ref:`/examples/grib_metadata.ipynb` .. py:method:: geography() :obj:`Geography`: Get geography description. If it is not available None is returned. .. 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:property:: grid_spec .. py:property:: gridspec .. py:method:: index_keys() Return the keys to be used with the :meth:`indices` method. .. py:method:: indexing_datetime() .. 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, headers_only_clone=True, **kwargs) Create a new metadata object by cloning a new GRIB handle and setting the keys in it. :param \*args: Positional arguments. When present must be a dict with the GRIB keys to set in the new GRIB handle. :type \*args: :class:`tuple` :param headers_only_clone: If True, the new GRIB handle will be created with headers_only=True to reduce the data section. With this the GRIB handle size will be significantly smaller, but the data section becomes unusable. Default is True. :type headers_only_clone: :class:`bool`, *optional* :param \*\*kwargs: Other keyword arguments specifying the GRIB keys to set. :type \*\*kwargs: :class:`dict`, *optional* :returns: The new metadata object. There is always a :class:`StandAloneGribMetadata` object created containing the new GRIB handle updated with the specified keys. It is then wrapped in a :class:`WrappedMetadata` object storing ``"bitsPerValue"`` as an extra key. :rtype: :class:`WrappedMetadata` .. rubric:: Notes - When ``"bitsPerValue"`` is a key to set it is not written to the new handle. Instead, it is stored as an extra key in the resulting :class:`WrappedMetadata` object. .. py:method:: param_level() .. py:method:: reference_datetime() .. py:method:: step_timedelta() .. py:method:: valid_datetime() .. py:class:: GribMetadata(cache=None, **kwargs) Bases: :py:obj:`earthkit.data.core.metadata.Metadata` GRIB metadata. :obj:`GribMetadata` is an abstract class and should not be instantiated directly. There are two concrete implementations: :class:`GribFieldMetadata` and :class:`StandAloneGribMetadata`. .. py:method:: as_namespace(namespace=None) Return all the keys/values from a namespace. :param namespace: The :xref:`eccodes_namespace`. earthkit-data also defines the "default" namespace, which contains all the GRIB keys that ecCodes can access without specifying a 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(namespace=all, **kwargs) Generate dump with all the metadata keys belonging to ``namespace``. In a Jupyter notebook it is represented as a tabbed interface. :param namespace: The namespace to dump. Any :xref:`eccodes_namespace` can be used here. earthkit-data also defines the "default" namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. The following `namespace` values have a special meaning: - :obj:`all`: all the available namespaces will be used (including "default"). - None or empty str: the "default" namespace will be used. :type namespace: :obj:`str`, :obj:`list`, :obj:`tuple`, :obj:`None` or :obj:`all` :param \*\*kwargs: Other keyword arguments used for testing only :type \*\*kwargs: :class:`dict`, *optional* :returns: Dict-like object with one item per namespace. In a Jupyter notebook represented as a tabbed interface to browse the dump contents. :rtype: :class:`NamespaceDump` .. rubric:: Examples :ref:`/examples/grib_metadata.ipynb` .. py:method:: geography() :obj:`Geography`: Get geography description. If it is not available None is returned. .. 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:property:: grid_spec .. py:property:: gridspec .. py:method:: index_keys() Return the keys to be used with the :meth:`indices` method. .. py:method:: indexing_datetime() .. 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, headers_only_clone=True, **kwargs) Create a new metadata object by cloning a new GRIB handle and setting the keys in it. :param \*args: Positional arguments. When present must be a dict with the GRIB keys to set in the new GRIB handle. :type \*args: :class:`tuple` :param headers_only_clone: If True, the new GRIB handle will be created with headers_only=True to reduce the data section. With this the GRIB handle size will be significantly smaller, but the data section becomes unusable. Default is True. :type headers_only_clone: :class:`bool`, *optional* :param \*\*kwargs: Other keyword arguments specifying the GRIB keys to set. :type \*\*kwargs: :class:`dict`, *optional* :returns: The new metadata object. There is always a :class:`StandAloneGribMetadata` object created containing the new GRIB handle updated with the specified keys. It is then wrapped in a :class:`WrappedMetadata` object storing ``"bitsPerValue"`` as an extra key. :rtype: :class:`WrappedMetadata` .. rubric:: Notes - When ``"bitsPerValue"`` is a key to set it is not written to the new handle. Instead, it is stored as an extra key in the resulting :class:`WrappedMetadata` object. .. py:method:: param_level() .. py:method:: reference_datetime() .. py:method:: step_timedelta() .. py:method:: valid_datetime() .. py:class:: RestrictedGribMetadata(metadata) Bases: :py:obj:`earthkit.data.core.metadata.WrappedMetadata` Hide internal keys and namespaces in GRIB metadata. .. rubric:: Examples :ref:`/examples/grib_metadata_object.ipynb` .. py:method:: as_namespace(namespace) .. py:method:: dump(namespace=all, **kwargs) .. py:method:: get(key, default=None, *, astype=None, raise_on_missing=False, **kwargs) .. 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:: merge_list(v1, v2) :staticmethod: .. py:method:: namespaces() .. py:method:: override(*args, **kwargs) .. py:class:: StandAloneGribMetadata(handle, **kwargs) Bases: :py:obj:`GribMetadata` Represent standalone GRIB metadata owning an ecCodes GRIB handle. :class:`StandAloneGribMetadata` possesses its own ecCodes handle. Calling :meth:`override` on :obj:`GribMetadata` always returns a :class:`StandAloneGribMetadata` object. >>> ds = earthkit.data.from_source("file", "docs/examples/test4.grib") >>> md = ds[0].metadata() >>> md["shortName"] 't' >>> md.get("shortName") 't' >>> md.get("nonExistentKey") >>> md.get("nonExistentKey", 12) 12 .. rubric:: Examples :ref:`/examples/grib_metadata_object.ipynb` .. py:method:: as_namespace(namespace=None) Return all the keys/values from a namespace. :param namespace: The :xref:`eccodes_namespace`. earthkit-data also defines the "default" namespace, which contains all the GRIB keys that ecCodes can access without specifying a 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(namespace=all, **kwargs) Generate dump with all the metadata keys belonging to ``namespace``. In a Jupyter notebook it is represented as a tabbed interface. :param namespace: The namespace to dump. Any :xref:`eccodes_namespace` can be used here. earthkit-data also defines the "default" namespace, which contains all the GRIB keys that ecCodes can access without specifying a namespace. The following `namespace` values have a special meaning: - :obj:`all`: all the available namespaces will be used (including "default"). - None or empty str: the "default" namespace will be used. :type namespace: :obj:`str`, :obj:`list`, :obj:`tuple`, :obj:`None` or :obj:`all` :param \*\*kwargs: Other keyword arguments used for testing only :type \*\*kwargs: :class:`dict`, *optional* :returns: Dict-like object with one item per namespace. In a Jupyter notebook represented as a tabbed interface to browse the dump contents. :rtype: :class:`NamespaceDump` .. rubric:: Examples :ref:`/examples/grib_metadata.ipynb` .. py:method:: geography() :obj:`Geography`: Get geography description. If it is not available None is returned. .. 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:property:: grid_spec .. py:property:: gridspec .. py:method:: index_keys() Return the keys to be used with the :meth:`indices` method. .. py:method:: indexing_datetime() .. 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, headers_only_clone=True, **kwargs) Create a new metadata object by cloning a new GRIB handle and setting the keys in it. :param \*args: Positional arguments. When present must be a dict with the GRIB keys to set in the new GRIB handle. :type \*args: :class:`tuple` :param headers_only_clone: If True, the new GRIB handle will be created with headers_only=True to reduce the data section. With this the GRIB handle size will be significantly smaller, but the data section becomes unusable. Default is True. :type headers_only_clone: :class:`bool`, *optional* :param \*\*kwargs: Other keyword arguments specifying the GRIB keys to set. :type \*\*kwargs: :class:`dict`, *optional* :returns: The new metadata object. There is always a :class:`StandAloneGribMetadata` object created containing the new GRIB handle updated with the specified keys. It is then wrapped in a :class:`WrappedMetadata` object storing ``"bitsPerValue"`` as an extra key. :rtype: :class:`WrappedMetadata` .. rubric:: Notes - When ``"bitsPerValue"`` is a key to set it is not written to the new handle. Instead, it is stored as an extra key in the resulting :class:`WrappedMetadata` object. .. py:method:: param_level() .. py:method:: reference_datetime() .. py:method:: step_timedelta() .. py:method:: valid_datetime()