0
# eccodes
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: eccodes
7
- **Language**: Python
8
- **Installation**: `pip install eccodes`
9
- **System Dependencies**: ecCodes C library (automatically installed via eccodeslib dependency)
10

11
## Core Imports
12

13
High-level interface (recommended for most users):
14

15
```python
16
import eccodes
17
```
18

19
Direct access to specific modules:
20

21
```python
22
from eccodes import codes_grib_new_from_file, codes_get, codes_set
23
from eccodes.highlevel import Message, FileReader
24
```
25

26
Legacy/low-level interface:
27

28
```python
29
import gribapi
30
```
31

32
## Basic Usage
33

34
### Reading GRIB Files
35

36
```python
37
import eccodes
38

39
# Open and read GRIB file
40
with open('example.grib', 'rb') as f:
41
    # Read first message
42
    msg = eccodes.codes_grib_new_from_file(f)
43
    
44
    # Extract metadata
45
    param_name = eccodes.codes_get(msg, 'paramId')
46
    level = eccodes.codes_get(msg, 'level') 
47
    date = eccodes.codes_get(msg, 'dataDate')
48
    time = eccodes.codes_get(msg, 'dataTime')
49
    
50
    # Get data values
51
    values = eccodes.codes_get_values(msg)
52
    
53
    # Get grid information
54
    ni = eccodes.codes_get(msg, 'Ni')  # number of points along longitude
55
    nj = eccodes.codes_get(msg, 'Nj')  # number of points along latitude
56
    
57
    print(f"Parameter: {param_name}, Level: {level}")
58
    print(f"Date: {date}, Time: {time}")
59
    print(f"Grid: {ni}x{nj}, Values: {len(values)}")
60
    
61
    # Clean up
62
    eccodes.codes_release(msg)
63
```
64

65
### High-Level Object Interface
66

67
```python
68
from eccodes.highlevel import FileReader
69

70
# Iterate through messages in a file
71
for msg in FileReader('example.grib'):
72
    # Access data as attributes
73
    print(f"Parameter: {msg['paramId']}")
74
    print(f"Level: {msg['level']}")
75
    print(f"Grid shape: {msg.shape}")
76
    
77
    # Get data as numpy array
78
    data = msg.data
79
    print(f"Data range: {data.min()} to {data.max()}")
80
```
81

82
## Architecture
83

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

86
### High-Level Interface (eccodes module)
87
- **Object-oriented**: Message, FileReader, and StreamReader classes
88
- **Pythonic**: Dictionary-like access, automatic memory management
89
- **Convenient**: Built-in iteration, numpy integration
90
- **Recommended**: For most Python applications and data analysis
91

92
### Low-Level Interface (gribapi module + eccodes functions) 
93
- **Handle-based**: Direct bindings to ecCodes C library
94
- **Performance**: Minimal overhead for high-throughput applications
95
- **Complete**: Access to all ecCodes functionality
96
- **Compatible**: Drop-in replacement for legacy gribapi code
97

98
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.
99

100
## Capabilities
101

102
### Message Operations
103

104
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.
105

106
```python { .api }
107
def codes_new_from_file(fileobj, product_kind, headers_only=False):
108
    """Create message from file with explicit product type."""
109

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

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

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

119
def codes_release(msgid):
120
    """Release message from memory."""
121
```
122

123
[Message Operations](./message-operations.md)
124

125
### Key-Value Access
126

127
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.
128

129
```python { .api }
130
def codes_get(msgid, key, ktype=None):
131
    """Get key value with automatic type detection."""
132

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

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

139
def codes_set_array(msgid, key, value):
140
    """Set key as array."""
141
```
142

143
[Key-Value Access](./key-value-access.md)
144

145
### Data Manipulation
146

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

149
```python { .api }
150
def codes_get_values(msgid):
151
    """Get all data values from message."""
152

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

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

159
def codes_grib_get_data(gribid):
160
    """Get data with coordinates."""
161
```
162

163
[Data Manipulation](./data-manipulation.md)
164

165
### Indexing and Search
166

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

169
```python { .api }
170
def codes_index_new_from_file(filename, keys):
171
    """Create index from file."""
172

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

176
def codes_index_get(indexid, key):
177
    """Get unique values for key."""
178
```
179

180
[Indexing and Search](./indexing-search.md)
181

182
### High-Level Interface
183

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

186
```python { .api }
187
class Message:
188
    """High-level message interface."""
189
    
190
class FileReader:
191
    """Iterator for reading messages from files."""
192
    
193
class StreamReader:
194
    """Iterator for reading messages from streams."""
195
```
196

197
[High-Level Interface](./high-level-interface.md)
198

199
### Error Handling
200

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

203
```python { .api }
204
class EcCodesError(Exception):
205
    """Base exception for ecCodes errors."""
206

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

210
class KeyValueNotFoundError(EcCodesError):
211
    """Key not found in message."""
212
```
213

214
[Error Handling](./error-handling.md)
215

216
## Constants and Enums
217

218
### Product Types
219

220
```python { .api }
221
CODES_PRODUCT_GRIB = 1      # GRIB format
222
CODES_PRODUCT_BUFR = 2      # BUFR format  
223
CODES_PRODUCT_METAR = 3     # METAR format
224
CODES_PRODUCT_GTS = 4       # GTS format
225
CODES_PRODUCT_ANY = 0       # Any format
226
```
227

228
### Missing Values
229

230
```python { .api }
231
CODES_MISSING_DOUBLE = -1e100      # Missing double value
232
CODES_MISSING_LONG = 2147483647    # Missing long value
233
```
234

235
## Utilities
236

237
```python { .api }
238
def bindings_version():
239
    """Get ecCodes library version."""
240

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

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

247
__version__: str  # Package version
248
```