or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-manipulation.mderror-handling.mdhigh-level-interface.mdindex.mdindexing-search.mdkey-value-access.mdmessage-operations.md
tile.json

tessl/pypi-eccodes

Python interface to the ecCodes GRIB and BUFR decoder/encoder library for meteorological data processing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/eccodes@2.43.x

To install, run

npx @tessl/cli install tessl/pypi-eccodes@2.43.0

index.mddocs/

eccodes

A comprehensive Python interface to the ecCodes GRIB and BUFR decoder/encoder library for meteorological data processing. eccodes enables reading, writing, and manipulating weather and climate data in standard meteorological formats used by weather services, research institutions, and climate modeling centers worldwide.

Package Information

  • Package Name: eccodes
  • Language: Python
  • Installation: pip install eccodes
  • System Dependencies: ecCodes C library (automatically installed via eccodeslib dependency)

Core Imports

High-level interface (recommended for most users):

import eccodes

Direct access to specific modules:

from eccodes import codes_grib_new_from_file, codes_get, codes_set
from eccodes.highlevel import Message, FileReader

Legacy/low-level interface:

import gribapi

Basic Usage

Reading GRIB Files

import eccodes

# Open and read GRIB file
with open('example.grib', 'rb') as f:
    # Read first message
    msg = eccodes.codes_grib_new_from_file(f)
    
    # Extract metadata
    param_name = eccodes.codes_get(msg, 'paramId')
    level = eccodes.codes_get(msg, 'level') 
    date = eccodes.codes_get(msg, 'dataDate')
    time = eccodes.codes_get(msg, 'dataTime')
    
    # Get data values
    values = eccodes.codes_get_values(msg)
    
    # Get grid information
    ni = eccodes.codes_get(msg, 'Ni')  # number of points along longitude
    nj = eccodes.codes_get(msg, 'Nj')  # number of points along latitude
    
    print(f"Parameter: {param_name}, Level: {level}")
    print(f"Date: {date}, Time: {time}")
    print(f"Grid: {ni}x{nj}, Values: {len(values)}")
    
    # Clean up
    eccodes.codes_release(msg)

High-Level Object Interface

from eccodes.highlevel import FileReader

# Iterate through messages in a file
for msg in FileReader('example.grib'):
    # Access data as attributes
    print(f"Parameter: {msg['paramId']}")
    print(f"Level: {msg['level']}")
    print(f"Grid shape: {msg.shape}")
    
    # Get data as numpy array
    data = msg.data
    print(f"Data range: {data.min()} to {data.max()}")

Architecture

eccodes provides a two-layer architecture optimized for different use cases:

High-Level Interface (eccodes module)

  • Object-oriented: Message, FileReader, and StreamReader classes
  • Pythonic: Dictionary-like access, automatic memory management
  • Convenient: Built-in iteration, numpy integration
  • Recommended: For most Python applications and data analysis

Low-Level Interface (gribapi module + eccodes functions)

  • Handle-based: Direct bindings to ecCodes C library
  • Performance: Minimal overhead for high-throughput applications
  • Complete: Access to all ecCodes functionality
  • Compatible: Drop-in replacement for legacy gribapi code

This dual approach enables both ease of use for typical data analysis tasks and maximum performance for specialized applications, while maintaining full compatibility with the complete ecCodes feature set.

Capabilities

Message Operations

Core functionality for creating, reading, writing, and managing GRIB/BUFR messages from files, samples, or memory buffers. Includes message lifecycle management, file I/O operations, and format detection.

def codes_new_from_file(fileobj, product_kind, headers_only=False):
    """Create message from file with explicit product type."""

def codes_grib_new_from_file(fileobj, headers_only=False):
    """Create GRIB message from file."""

def codes_bufr_new_from_file(fileobj, headers_only=False):
    """Create BUFR message from file."""

def codes_write(msgid, fileobj):
    """Write message to file."""

def codes_release(msgid):
    """Release message from memory."""

Message Operations

Key-Value Access

Comprehensive API for reading and writing meteorological parameters, metadata, and configuration values from GRIB/BUFR messages. Supports type-specific access with automatic conversion and validation.

def codes_get(msgid, key, ktype=None):
    """Get key value with automatic type detection."""

def codes_set(msgid, key, value):
    """Set key value with automatic type detection."""

def codes_get_array(msgid, key, ktype=None):
    """Get key as array."""

def codes_set_array(msgid, key, value):
    """Set key as array."""

Key-Value Access

Data Manipulation

Advanced operations for working with meteorological data grids, coordinate systems, and spatial data. Includes nearest neighbor searches, data extraction, and grid transformations.

def codes_get_values(msgid):
    """Get all data values from message."""

def codes_set_values(msgid, values):
    """Set all data values in message."""

def codes_grib_find_nearest(gribid, lat, lon):
    """Find nearest grid point to coordinates."""

def codes_grib_get_data(gribid):
    """Get data with coordinates."""

Data Manipulation

Indexing and Search

Efficient indexing system for fast querying and filtering of large meteorological datasets. Supports multi-key indexes and complex queries across message collections.

def codes_index_new_from_file(filename, keys):
    """Create index from file."""

def codes_index_select(indexid, key, value):
    """Select messages by key value."""

def codes_index_get(indexid, key):
    """Get unique values for key."""

Indexing and Search

High-Level Interface

Object-oriented interface providing Pythonic access to GRIB/BUFR data with automatic memory management, numpy integration, and iterator patterns for efficient data processing.

class Message:
    """High-level message interface."""
    
class FileReader:
    """Iterator for reading messages from files."""
    
class StreamReader:
    """Iterator for reading messages from streams."""

High-Level Interface

Error Handling

Comprehensive exception hierarchy for handling all types of errors that can occur during GRIB/BUFR processing, from file access issues to data validation failures.

class EcCodesError(Exception):
    """Base exception for ecCodes errors."""

class FileNotFoundError(EcCodesError):
    """File not found error."""

class KeyValueNotFoundError(EcCodesError):
    """Key not found in message."""

Error Handling

Constants and Enums

Product Types

CODES_PRODUCT_GRIB = 1      # GRIB format
CODES_PRODUCT_BUFR = 2      # BUFR format  
CODES_PRODUCT_METAR = 3     # METAR format
CODES_PRODUCT_GTS = 4       # GTS format
CODES_PRODUCT_ANY = 0       # Any format

Missing Values

CODES_MISSING_DOUBLE = -1e100      # Missing double value
CODES_MISSING_LONG = 2147483647    # Missing long value

Utilities

def bindings_version():
    """Get ecCodes library version."""

def codes_definition_path(definition_path=None):
    """Get or set definitions path."""

def codes_get_api_version():
    """Get ecCodes API version as integer."""

__version__: str  # Package version