eccodes Python Interface

2.46.0 · active · verified Sun Apr 12

The eccodes library provides a Python interface to the ECMWF ecCodes GRIB and BUFR decoder/encoder. It allows users to read, write, and manipulate GRIB and BUFR meteorological data files, providing both a low-level API mapping directly to the C library and a higher-level object-oriented interface. It is actively maintained by ECMWF with frequent releases, typically every 1-2 months, mirroring the underlying ecCodes C library.

Warnings

Install

Imports

Quickstart

This quickstart demonstrates how to open a GRIB file, iterate through its messages using the high-level `GribFile` context manager, and access common keys from individual `GribMessage` objects. It includes robust error handling and setup to create a dummy GRIB file if a real one isn't provided, ensuring the example is runnable out-of-the-box.

import eccodes
import os

# --- Quickstart setup: Ensure a GRIB file exists for demonstration ---
# In a real scenario, you would point to your actual GRIB file.
grib_filepath = "quickstart_sample.grib"

if not os.path.exists(grib_filepath):
    print(f"Creating a dummy GRIB file '{grib_filepath}' for quickstart.")
    try:
        # Create a basic GRIB message from a sample.
        # This requires the eccodes sample data to be accessible.
        # If ECCODES_SAMPLES_PATH is not set, this might fail.
        gid = eccodes.codes_grib_new_from_samples("GRIB2")
        eccodes.codes_set(gid, "discipline", 0) # Meteorology
        eccodes.codes_set(gid, "parameterCategory", 0) # Temperature
        eccodes.codes_set(gid, "parameterNumber", 0) # Temperature (K)
        eccodes.codes_set_array(gid, "values", [273.15, 274.15, 275.15]) # Dummy data
        with open(grib_filepath, 'wb') as f:
            eccodes.codes_write(gid, f)
        eccodes.codes_release(gid)
        print(f"Successfully created a basic GRIB file: {grib_filepath}")
    except eccodes.CodesInternalError as e:
        print(f"Warning: Could not create a valid GRIB sample using eccodes ({e}).")
        print("Falling back to an empty dummy file. Quickstart may not show full functionality.")
        with open(grib_filepath, 'w') as f:
            f.write("DUMMY_FILE_CONTENT_NOT_GRIB")
    except Exception as e:
        print(f"An unexpected error occurred during GRIB sample creation: {e}")
        with open(grib_filepath, 'w') as f:
            f.write("DUMMY_FILE_CONTENT_NOT_GRIB")
# --- End of Quickstart setup ---

# Main Quickstart logic: Reading GRIB messages
try:
    message_count = 0
    with eccodes.GribFile(grib_filepath) as gf:
        print(f"\nOpened GRIB file: {grib_filepath}")
        for i, msg in enumerate(gf):
            message_count += 1
            print(f"  Processing Message {i+1}:")
            try:
                # Access common keys using the high-level interface
                centre = msg.get("centre", "N/A")
                param = msg.get("shortName", "N/A")
                level = msg.get("level", "N/A")
                date = msg.get("date", "N/A")
                time = msg.get("time", "N/A")
                print(f"    Centre: {centre}, Parameter: {param}, Level: {level}, Date: {date}, Time: {time}")

                # Access values (can be a large array). Avoid printing all.
                values = msg.get("values", [])
                if values:
                    print(f"    First 5 values: {values[:min(5, len(values))]}")
                else:
                    print("    No values found or dummy file used.")

            except eccodes.KeyError as e:
                print(f"    Warning: Key not found in message: {e}")
            except Exception as e:
                print(f"    An error occurred while processing message: {e}")

            if message_count >= 1: # Process only the first message for brevity
                break

    if message_count == 0:
        print(f"No GRIB messages found in {grib_filepath}. (Might be a dummy file or empty).")

except eccodes.WrongElementException as e:
    print(f"\nError: '{grib_filepath}' is not a valid GRIB file or corrupted. Details: {e}")
except FileNotFoundError:
    print(f"\nError: GRIB file '{grib_filepath}' not found.")
except Exception as e:
    print(f"\nAn unexpected error occurred during GRIB file processing: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(grib_filepath) and grib_filepath == "quickstart_sample.grib":
        os.remove(grib_filepath)
        print(f"Cleaned up dummy file: {grib_filepath}")

view raw JSON →