eccodeslib Python Interface to ecCodes

Warnings

• breaking The `eccodeslib` Python package is a wrapper around the `ecCodes` C library. It requires the C library to be installed and accessible on your system. While pip wheels for Windows and macOS often bundle it, Linux users (and those installing from source) must install `ecCodes` separately (e.g., via `apt install libeccodes-dev` or `conda install -c conda-forge eccodes`). Installation or runtime will fail if the C library is not found.
  Fix: Before `pip install eccodeslib`, ensure the `ecCodes` C library is installed using your system's package manager or via a method like `conda install -c conda-forge eccodes`.
• gotcha Failing to explicitly release `codes_handle` objects will lead to memory leaks and potential application crashes, especially when processing many GRIB/BUFR messages. `ec.codes_handle_new_from_file` creates a handle that must be manually freed.
  Fix: Always call `eccodes.codes_release(handle)` after you are finished with a message handle. For file operations, ensure `with open(...)` is used, but this only closes the file, not the individual message handles.
• gotcha ecCodes keys have specific data types (e.g., `long`, `double`, `string`, `bytes`, `array`). Using the wrong getter/setter function (e.g., `ec.codes_get_long` for a string key) will result in `CodesInternalError` or incorrect data interpretation.
  Fix: Consult the ecCodes documentation (or use `codes_info -t` with the C library) to determine the correct type for each key. Use the appropriate `ec.codes_get_*` or `ec.codes_set_*` function, such as `ec.codes_get_string`, `ec.codes_get_long`, `ec.codes_get_double`, or `ec.codes_get_array`.

Install

• pip install eccodeslib Install via pip

Imports

• eccodes

  import eccodes

  The primary module for all ecCodes functions.

Quickstart

This quickstart demonstrates how to open a GRIB file, iterate through its messages, extract common metadata keys like 'shortName' and 'paramId', and properly release resources. It highlights the importance of having a sample GRIB file and handles potential `FileNotFoundError` or `CodesInternalError` if the C library is not correctly set up.

import eccodes as ec
import os

# --- This quickstart requires a sample GRIB file. ---
# You can download sample GRIB files from ECMWF's website or find them in
# ecCodes/eccodes-python test directories, e.g., 'tests/data/regular_latlon_surface.grib2'.
# Replace 'path/to/sample.grib' with the actual path to your GRIB file.
# For example, a small GRIB file could be 'https://github.com/ecmwf/eccodes/blob/develop/tests/data/sample.grib2'.

GRIB_FILE_PATH = os.environ.get('ECCODES_SAMPLE_GRIB_PATH', 'path/to/sample.grib')

try:
    print(f"Attempting to read GRIB file: {GRIB_FILE_PATH}")
    message_count = 0
    with open(GRIB_FILE_PATH, 'rb') as f:
        while True:
            # Get a new GRIB message handle from the file
            handle = ec.codes_handle_new_from_file(f, ec.CODES_PRODUCT_GRIB)
            if handle is None:
                break # End of file

            message_count += 1
            # Access common keys
            short_name = ec.codes_get(handle, 'shortName')
            param_id = ec.codes_get_long(handle, 'paramId')
            date = ec.codes_get_long(handle, 'dataDate')
            time = ec.codes_get_long(handle, 'dataTime')

            print(f"  Message {message_count}: shortName={short_name}, paramId={param_id}, Date={date}, Time={time}")

            # Release the handle to free memory
            ec.codes_release(handle)

    if message_count == 0:
        print("No GRIB messages found in the file.")
    else:
        print(f"Successfully processed {message_count} GRIB messages.")

except FileNotFoundError:
    print(f"Error: GRIB file not found at '{GRIB_FILE_PATH}'. Please ensure the file exists or set ECCODES_SAMPLE_GRIB_PATH.")
except ec.CodesInternalError as e:
    print(f"Error processing GRIB file: {e}. Ensure ecCodes C library is installed and the GRIB file is valid.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")