tessl/pypi-eccodes
Python interface to the ecCodes GRIB and BUFR decoder/encoder library for meteorological data processing
—
Pending
key-value-access.mddocs/
Key-Value Access
Comprehensive API for reading and writing meteorological parameters, metadata, and configuration values from GRIB/BUFR messages. The key-value system enables access to all message properties using standardized key names with automatic type conversion and validation.
Capabilities
Generic Get Operations
Universal functions for retrieving values with automatic type detection.
def codes_get(msgid, key, ktype=None):
"""
Get key value with automatic type detection.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name (e.g., 'paramId', 'level', 'dataDate')
- ktype (int, optional): Force specific type conversion
Returns:
int|float|str: Key value in appropriate Python type
"""
def codes_get_array(msgid, key, ktype=None):
"""
Get key as array with automatic type detection.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- ktype (int, optional): Force specific type conversion
Returns:
list: Array of values
"""Type-Specific Get Operations
Functions for retrieving values with explicit type conversion.
def codes_get_long(msgid, key):
"""
Get key as long integer.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
int: Key value as integer
"""
def codes_get_double(msgid, key):
"""
Get key as double precision float.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
float: Key value as float
"""
def codes_get_string(msgid, key):
"""
Get key as string.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
str: Key value as string
"""
def codes_get_long_array(msgid, key):
"""
Get key as long integer array.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
list[int]: Array of integers
"""
def codes_get_double_array(msgid, key):
"""
Get key as double precision array.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
list[float]: Array of floats
"""
def codes_get_float_array(msgid, key):
"""
Get key as float array.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
list[float]: Array of floats
"""
def codes_get_string_array(msgid, key):
"""
Get key as string array.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
list[str]: Array of strings
"""Element Access Operations
Functions for accessing specific elements within array keys.
def codes_get_elements(msgid, key, indexes):
"""
Get specific array elements by index.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- indexes (list[int]): List of element indexes
Returns:
list: Selected array elements
"""
def codes_get_double_element(msgid, key, index):
"""
Get single double element by index.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- index (int): Element index
Returns:
float: Element value as float
"""
def codes_get_double_elements(msgid, key, indexes):
"""
Get multiple double elements by index.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- indexes (list[int]): List of element indexes
Returns:
list[float]: Selected elements as floats
"""Generic Set Operations
Universal functions for setting values with automatic type detection.
def codes_set(msgid, key, value):
"""
Set key value with automatic type detection.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- value: Value to set (int, float, str, or list)
"""
def codes_set_array(msgid, key, value):
"""
Set key as array with automatic type detection.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- value (list): Array values to set
"""Type-Specific Set Operations
Functions for setting values with explicit type conversion.
def codes_set_long(msgid, key, value):
"""
Set key as long integer.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- value (int): Integer value to set
"""
def codes_set_double(msgid, key, value):
"""
Set key as double precision float.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- value (float): Float value to set
"""
def codes_set_string(msgid, key, value):
"""
Set key as string.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- value (str): String value to set
"""
def codes_set_long_array(msgid, key, inarray):
"""
Set key as long integer array.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- inarray (list[int]): Array of integers to set
"""
def codes_set_double_array(msgid, key, inarray):
"""
Set key as double precision array.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- inarray (list[float]): Array of floats to set
"""
def codes_set_string_array(msgid, key, stringarray):
"""
Set key as string array.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
- stringarray (list[str]): Array of strings to set
"""Key Iteration
Functions for iterating through message keys.
def codes_keys_iterator_new(msgid, namespace=None):
"""
Create keys iterator.
Parameters:
- msgid (int): Message handle ID
- namespace (str, optional): Key namespace filter
Returns:
int: Iterator handle ID
"""
def codes_keys_iterator_next(iterid):
"""
Move to next key.
Parameters:
- iterid (int): Iterator handle ID
Returns:
bool: True if next key exists, False if at end
"""
def codes_keys_iterator_get_name(iterid):
"""
Get current key name.
Parameters:
- iterid (int): Iterator handle ID
Returns:
str: Current key name
"""
def codes_keys_iterator_rewind(iterid):
"""Reset iterator to beginning."""
def codes_keys_iterator_delete(iterid):
"""Delete iterator and free memory."""Key Information and Validation
Functions for checking key properties and availability.
def codes_is_defined(msgid, key):
"""
Check if key is defined in message.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
bool: True if key exists, False otherwise
"""
def codes_is_missing(msgid, key):
"""
Check if key value is missing.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
bool: True if value is missing, False otherwise
"""
def codes_get_size(msgid, key):
"""
Get size of key (array length or string length).
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
int: Size of key value
"""
def codes_get_length(msgid, key):
"""
Get length of key value.
Parameters:
- msgid (int): Message handle ID
- key (str): Key name
Returns:
int: Length of key value
"""Usage Examples
Reading Common Meteorological Parameters
import eccodes
with open('forecast.grib', 'rb') as f:
msg = eccodes.codes_grib_new_from_file(f)
# Read basic metadata
param_id = eccodes.codes_get(msg, 'paramId')
param_name = eccodes.codes_get(msg, 'name')
level = eccodes.codes_get(msg, 'level')
level_type = eccodes.codes_get(msg, 'levelType')
# Read time information
date = eccodes.codes_get(msg, 'dataDate')
time = eccodes.codes_get(msg, 'dataTime')
step = eccodes.codes_get(msg, 'step')
# Read grid information
grid_type = eccodes.codes_get(msg, 'gridType')
ni = eccodes.codes_get(msg, 'Ni') # longitude points
nj = eccodes.codes_get(msg, 'Nj') # latitude points
print(f"Parameter: {param_name} (ID: {param_id})")
print(f"Level: {level} {level_type}")
print(f"Date/Time: {date} {time:04d}Z + {step}h")
print(f"Grid: {grid_type} {ni}x{nj}")
eccodes.codes_release(msg)Modifying Message Parameters
import eccodes
# Create new message from sample
msg = eccodes.codes_grib_new_from_samples('regular_ll_sfc_grib2')
# Set meteorological parameter
eccodes.codes_set(msg, 'paramId', 130) # Temperature
eccodes.codes_set(msg, 'name', 'Temperature')
# Set level information
eccodes.codes_set(msg, 'level', 850)
eccodes.codes_set(msg, 'levelType', 'isobaricInhPa')
# Set time information
eccodes.codes_set(msg, 'dataDate', 20231215)
eccodes.codes_set(msg, 'dataTime', 1200)
eccodes.codes_set(msg, 'step', 24)
# Set grid configuration
eccodes.codes_set(msg, 'Ni', 360) # 1 degree resolution
eccodes.codes_set(msg, 'Nj', 181) # 1 degree resolution
eccodes.codes_set(msg, 'iDirectionIncrement', 1000000) # in micro-degrees
eccodes.codes_set(msg, 'jDirectionIncrement', 1000000)
# Write modified message
with open('modified.grib', 'wb') as f:
eccodes.codes_write(msg, f)
eccodes.codes_release(msg)Working with Array Keys
import eccodes
import numpy as np
with open('analysis.grib', 'rb') as f:
msg = eccodes.codes_grib_new_from_file(f)
# Check if key is an array
if eccodes.codes_get_size(msg, 'values') > 1:
# Get all data values
values = eccodes.codes_get_double_array(msg, 'values')
print(f"Data shape: {len(values)} points")
# Get grid coordinates if available
if eccodes.codes_is_defined(msg, 'latitudes'):
lats = eccodes.codes_get_double_array(msg, 'latitudes')
lons = eccodes.codes_get_double_array(msg, 'longitudes')
print(f"Coordinate arrays: {len(lats)} points")
# Get specific data points by index
sample_indices = [0, 100, 200]
sample_values = eccodes.codes_get_elements(msg, 'values', sample_indices)
print(f"Sample values: {sample_values}")
eccodes.codes_release(msg)Handling Missing Values
import eccodes
with open('observations.bufr', 'rb') as f:
msg = eccodes.codes_bufr_new_from_file(f)
# Check key availability
temp_key = 'airTemperature'
if eccodes.codes_is_defined(msg, temp_key):
if not eccodes.codes_is_missing(msg, temp_key):
temperature = eccodes.codes_get(msg, temp_key)
print(f"Temperature: {temperature}°C")
else:
print("Temperature value is missing")
else:
print("Temperature key not available in this message")
eccodes.codes_release(msg)Install with Tessl CLI
npx tessl i tessl/pypi-eccodes