Merge branch 'develop'

Author: shahramn

CHANGELOG.rst

@@ -2,6 +2,10 @@
 Changelog for eccodes-python
 ============================
 
+1.3.2 (2021-04-16)
+--------------------
+
+- Restore the experimental high-level interface
 
 1.3.1 (2021-04-16)
 --------------------

eccodes/eccodes.py

@@ -210,13 +210,20 @@
     WrongTypeError,
 )
 
+from .high_level.bufr import BufrFile, BufrMessage
+from .high_level.gribfile import GribFile
+from .high_level.gribindex import GribIndex
+from .high_level.gribmessage import GribMessage
+
 __all__ = [
     "__version__",
     "ArrayTooSmallError",
     "AttributeClashError",
     "AttributeNotFoundError",
     "bindings_version",
     "BufferTooSmallError",
+    "BufrFile",
+    "BufrMessage",
     "CodeNotFoundInTableError",
     "codes_any_new_from_file",
     "codes_bufr_copy_data",
@@ -353,7 +360,10 @@
     "FunctionalityNotEnabledError",
     "FunctionNotImplementedError",
     "GeocalculusError",
+    "GribFile",
+    "GribIndex",
     "GribInternalError",
+    "GribMessage",
     "HashArrayNoMatchError",
     "InternalArrayTooSmallError",
     "InternalError",

eccodes/high_level/__init__.py

@@ -0,0 +1,100 @@
+"""
+
+Note: The high-level Python interface is currently experimental and may change in a future release.
+
+Classes for handling BUFR with a high level interface.
+
+``BufrFiles`` can be treated mostly as regular files and used as context
+managers, as can ``BufrMessages``. Each of these classes destructs itself and
+any child instances appropriately.
+
+Author: Daniel Lee, DWD, 2016
+"""
+
+from .. import eccodes
+from .codesfile import CodesFile
+from .codesmessage import CodesMessage
+
+
+class BufrMessage(CodesMessage):
+
+    __doc__ = "\n".join(CodesMessage.__doc__.splitlines()[4:]).format(
+        prod_type="BUFR", classname="BufrMessage", parent="BufrFile", alias="bufr"
+    )
+
+    product_kind = eccodes.CODES_PRODUCT_BUFR
+
+    # Arguments included explicitly to support introspection
+    # TODO: Can we get this to work with an index?
+    def __init__(self, codes_file=None, clone=None, sample=None, headers_only=False):
+        """
+        Open a message and inform the GRIB file that it's been incremented.
+
+        The message is taken from ``codes_file``, cloned from ``clone`` or
+        ``sample``, or taken from ``index``, in that order of precedence.
+        """
+        super(self.__class__, self).__init__(codes_file, clone, sample, headers_only)
+        # self._unpacked = False
+
+    # def get(self, key, ktype=None):
+    #    """Return requested value, unpacking data values if necessary."""
+    #    # TODO: Only do this if accessing arrays that need unpacking
+    #    if not self._unpacked:
+    #        self.unpacked = True
+    #    return super(self.__class__, self).get(key, ktype)
+
+    # def missing(self, key):
+    #    """
+    #    Report if key is missing.#
+    #
+    #    Overloaded due to confusing behaviour in ``codes_is_missing`` (SUP-1874).
+    #    """
+    #    return not bool(eccodes.codes_is_defined(self.codes_id, key))
+
+    def unpack(self):
+        """Decode data section"""
+        eccodes.codes_set(self.codes_id, "unpack", 1)
+
+    def pack(self):
+        """Encode data section"""
+        eccodes.codes_set(self.codes_id, "pack", 1)
+
+    def keys(self, namespace=None):
+        # self.unpack()
+        # return super(self.__class__, self).keys(namespace)
+        iterator = eccodes.codes_bufr_keys_iterator_new(self.codes_id)
+        keys = []
+        while eccodes.codes_bufr_keys_iterator_next(iterator):
+            key = eccodes.codes_bufr_keys_iterator_get_name(iterator)
+            keys.append(key)
+        eccodes.codes_bufr_keys_iterator_delete(iterator)
+        return keys
+
+    # @property
+    # def unpacked(self):
+    #    return self._unpacked
+
+    # @unpacked.setter
+    # def unpacked(self, val):
+    #    eccodes.codes_set(self.codes_id, "unpack", val)
+    #    self._unpacked = val
+
+    # def __setitem__(self, key, value):
+    #    """Set item and pack BUFR."""
+    #    if not self._unpacked:
+    #        self.unpacked = True
+    #    super(self.__class__, self).__setitem__(key, value)
+    #    eccodes.codes_set(self.codes_id, "pack", True)
+
+    def copy_data(self, destMsg):
+        """Copy data values from this message to another message"""
+        return eccodes.codes_bufr_copy_data(self.codes_id, destMsg.codes_id)
+
+
+class BufrFile(CodesFile):
+
+    __doc__ = "\n".join(CodesFile.__doc__.splitlines()[4:]).format(
+        prod_type="BUFR", classname="BufrFile", alias="bufr"
+    )
+
+    MessageClass = BufrMessage

eccodes/high_level/bufr.py

@@ -0,0 +1,80 @@
+"""
+Note: The high-level Python interface is currently experimental and may change in a future release.
+
+``CodesFile`` class that implements a file that is readable by ecCodes and
+closes itself and its messages when it is no longer needed.
+
+Author: Daniel Lee, DWD, 2016
+"""
+
+import io
+
+from .. import eccodes
+
+
+class CodesFile(io.FileIO):
+
+    """
+    An abstract class to specify and/or implement common behaviour that files
+    read by ecCodes should implement.
+
+    A {prod_type} file handle meant for use in a context manager.
+
+    Individual messages can be accessed using the ``next`` method. Of course,
+    it is also possible to iterate over each message in the file::
+
+        >>> with {classname}(filename) as {alias}:
+        ...     # Print number of messages in file
+        ...     len({alias})
+        ...     # Open all messages in file
+        ...     for msg in {alias}:
+        ...         print(msg[key_name])
+        ...     len({alias}.open_messages)
+        >>> # When the file is closed, any open messages are closed
+        >>> len({alias}.open_messages)
+    """
+
+    #: Type of messages belonging to this file
+    MessageClass = None
+
+    def __init__(self, filename, mode="rb"):
+        """Open file and receive codes file handle."""
+        #: File handle for working with actual file on disc
+        #: The class holds the file it works with because ecCodes'
+        # typechecking does not allow using inherited classes.
+        self.file_handle = open(filename, mode)
+        #: Number of message in file currently being read
+        self.message = 0
+        #: Open messages
+        self.open_messages = []
+        self.name = filename
+
+    def __exit__(self, exception_type, exception_value, traceback):
+        """Close all open messages, release file handle and close file."""
+        while self.open_messages:
+            # Note: if the message was manually closed, this has no effect
+            self.open_messages.pop().close()
+        self.file_handle.close()
+
+    def __len__(self):
+        """Return total number of messages in file."""
+        return eccodes.codes_count_in_file(self.file_handle)
+
+    def __enter__(self):
+        return self
+
+    def close(self):
+        """Possibility to manually close file."""
+        self.__exit__(None, None, None)
+
+    def __iter__(self):
+        return self
+
+    def next(self):
+        try:
+            return self.MessageClass(self)
+        except IOError:
+            raise StopIteration()
+
+    def __next__(self):
+        return self.next()