README

========================
Deprecated: PythonicGrib
========================

The code for this package was pulled into ECMWF's 
`ecCodes library <https://software.ecmwf.int/wiki/display/ECC/ecCodes+Home>`_
since February 2018. Further information can be found
`on the ecCodes website. <https://confluence.ecmwf.int/display/ECC/High-level+Pythonic+Interface+in+ecCodes>`_

For this reason, this package is no longer maintained and is considered deprecated.

Old README contents
###################

PythonicGrib is a Python wrapper for the `ECMWF's GRIB API  
<https://software.ecmwf.int/wiki/display/GRIB/Releases>`_
which allows interaction with GRIB messages in a pythonic way and allows the
user to be sure their code is free of memory leaks by transfering bookkeeping
tasks to a context manager. It provides high-level access to the procedural
Python calls inherent to the GRIB API and requires a GRIB API installation on
the system.

Working with GRIB files in a context manager like this::

    >>> with GribFile(filename) as grib:
    ...     # Print number of messages in file
    ...     len(grib)
    ...     # Open all messages in file
    ...     for i in range(len(grib)):
    ...         msg = GribMessage(grib)
    ...         print(msg["shortName"])
    ...     len(grib.open_messages)
    >>> # When the file is closed, any open messages are closed
    >>> len(grib.open_messages)

Treat messages as a key-value pair::

    >>> with GribFile(filename) as grib:
    ...     # Access shortNames of all messages
    ...     for i in range(len(grib)):
    ...         msg = GribMessage(grib)
    ...         print(msg["shortName"])
    ...     # Report number of keys in message
    ...     len(msg)
    ...     # Report message size in bytes
    ...     msg.size
    ...     # Report keys in message
    ...     msg.keys()
    ...     # Check if value is missing
    ...     msg.missing("scaleFactorOfSecondFixedSurface")
    ...     # Set scalar value
    ...     msg["scaleFactorOfSecondFixedSurface"] = 5
    ...     # Check key's value
    ...     msg["scaleFactorOfSecondFixedSurface"]
    ...     # Set value to missing
    ...     msg.set_missing("scaleFactorOfSecondFixedSurface")
    ...     # Missing values raise exception when read with dict notation
    ...     msg["scaleFactorOfSecondFixedSurface"]
    ...     # Array values are set transparently
    ...     msg["values"] = [1, 2, 3]
    ...     # Messages can be written to file
    ...     with open(testfile, "w") as test:
    ...         msg.write(test)
    ...     # Messages can be cloned from other messages
    ...     msg2 = GribMessage(clone=msg)
    ...     # If desired, messages can be closed manually or used in with
    ...     msg.close()
        
Let indexes worry about taking care of themselves::

    >>> # Create index from file with keys
    >>> with GribIndex(filename, keys) as idx:
    ...     # Write index to file
    ...     idx.write(index_file)
    >>> # Read index from file
    >>> with GribIndex(file_index=index_file) as idx:
    ...     # Add new file to index
    ...     idx.add(other_filename)
    ...     # Report number of unique values for given key
    ...     idx.size(key)
    ...     # Report unique values indexed by key
    ...     idx.values(key)
    ...     # Request GribMessage matching key, value
    ...     msg = idx.select({key: value})
    ... # No messages are left open after index closes
    ... idx.open_messages
        
Install from PyPI with::

    pip install PythonicGRIB

Or manually from the sources with::

    python setup.py install

Author: `Daniel Lee <Daniel.Lee@dwd.de>`_