eccodes: ecCodes Namespace Reference

eccodes

- Main Page
- C Interface
- F90 Interface
- Python Interface

- Namespace List
- Namespace Members

All Data Structures Namespaces Files Functions Groups Pages
Data Structures | Functions
ecCodes Namespace Reference

This package is the Python interface to ecCodes. More...

## Data Structures
class | CodesInternalError
| Wrap errors coming from the C API in a Python exception object. More...

## Functions
def | codes_gts_new_from_file
| Load in memory a GTS message from a file. More...
def | codes_metar_new_from_file
| Load in memory a METAR message from a file. More...
def | codes_new_from_file
| Load in memory a message from a file for a given product. More...
def | codes_any_new_from_file
| Load in memory a message from a file. More...
def | codes_bufr_new_from_file
| Load in memory a BUFR message from a file. More...
def | codes_grib_new_from_file
| Load in memory a grib message from a file. More...
def | codes_count_in_file
| Count the messages in a file. More...
def | codes_grib_multi_support_on
| Turn on the support for multiple fields in a single message. More...
def | codes_grib_multi_support_off
| Turn off the support for multiple fields in a single message. More...
def | codes_release
| Free the memory for the message referred as msgid. More...
def | codes_get_string
| Get the string value of a key from a message. More...
def | codes_set_string
| Set the value for a string key in a grib message. More...
def | codes_gribex_mode_on
| Turn on the compatibility mode with gribex. More...
def | codes_gribex_mode_off
| Turn off the compatibility mode with gribex. More...
def | codes_write
| Write a message to a file. More...
def | codes_grib_multi_write
| Write a multi field message to a file. More...
def | codes_grib_multi_append
| Append a single field grib message to a multi field grib message. More...
def | codes_get_size
| Get the size of an array key. More...
def | codes_get_string_length
| Get the length of the string version of a key. More...
def | codes_skip_computed
| Skip the computed keys in a keys iterator. More...
def | codes_skip_coded
| Skip the coded keys in a keys iterator. More...
def | codes_skip_edition_specific
| Skip the edition specific keys in a keys iterator. More...
def | codes_skip_duplicates
| Skip the duplicate keys in a keys iterator. More...
def | codes_skip_read_only
| Skip the read_only keys in a keys iterator. More...
def | codes_skip_function
| Skip the function keys in a keys iterator. More...
def | codes_grib_iterator_new
| Create a new geoiterator for the given message, using its geometry and values. More...
def | codes_grib_iterator_delete
| Delete a geoiterator and free memory. More...
def | codes_grib_iterator_next
| Retrieve the next value from a geoiterator. More...
def | codes_keys_iterator_new
| Create a new iterator on the keys. More...
def | codes_keys_iterator_next
| Advance to the next keys iterator value. More...
def | codes_keys_iterator_delete
| Delete a keys iterator and free memory. More...
def | codes_keys_iterator_get_name
| Get the name of a key from a keys iterator. More...
def | codes_keys_iterator_rewind
| Rewind a keys iterator. More...
def | codes_get_long
| Get the value of a key in a grib message as an int. More...
def | codes_get_double
| Get the value of a key in a grib message as a float. More...
def | codes_set_long
| Set the integer value for a key in a grib message. More...
def | codes_set_double
| Set the double value for a key in a grib message. More...
def | codes_new_from_samples
| Create a new valid GRIB message from a sample. More...
def | codes_bufr_new_from_samples
| Create a new valid BUFR message from a sample. More...
def | codes_clone
| Create a copy of a message. More...
def | codes_set_double_array
| Set the value of the key to a double array. More...
def | codes_get_double_array
| Get the value of the key as a NumPy array of doubles. More...
def | grib_get_string_array
| Get the value of the key as a list of strings. More...
def | grib_set_string_array
| Set the value of the key to a string array. More...
def | codes_set_long_array
| Set the value of the key to an integer array. More...
def | codes_get_long_array
| Get the integer array of values for a key from a grib message. More...
def | codes_grib_multi_new
| Create a new multi field and return its id. More...
def | codes_grib_multi_release
| Release a multi field from memory. More...
def | codes_copy_namespace
| Copy the value of all the keys belonging to a namespace from the source message to the destination message. More...
def | codes_index_new_from_file
| Create a new index from a file. More...
def | codes_index_add_file
| Add a file to an index. More...
def | codes_index_release
| Delete an index. More...
def | codes_index_get_size
| Get the number of distinct values for the index key. More...
def | codes_index_get_long
| Get the distinct values of the key in argument contained in the index. More...
def | codes_index_get_string
| Get the distinct values of the key in argument contained in the index. More...
def | codes_index_get_double
| Get the distinct values of the key in argument contained in the index. More...
def | codes_index_select_long
| Select the message subset with key==value. More...
def | codes_index_select_double
| Select the message subset with key==value. More...
def | codes_index_select_string
| Select the message subset with key==value. More...
def | codes_new_from_index
| Create a new handle from an index after having selected the key values. More...
def | codes_get_message_size
| Get the size of a coded message. More...
def | codes_get_message_offset
| Get the offset of a coded message. More...
def | codes_get_double_element
| Get as double the i-th element of the "key" array. More...
def | codes_get_double_elements
| Get as double array the elements of the "key" array whose indexes are listed in the input array. More...
def | codes_get_elements
| Retrieve the elements of the key array for the indexes specified in the input. More...
def | codes_set_missing
| Set as missing the value for a key in a grib message. More...
def | codes_set_key_vals
| Set the values for several keys at once in a grib message. More...
def | codes_is_missing
| Check if the value of a key is MISSING. More...
def | codes_is_defined
| Check if a key is defined (exists) More...
def | codes_grib_find_nearest
| Find the nearest grid point or the nearest four grid points to a given latitude/longitude. More...
def | codes_get_native_type
| Retrieve the native type of a key. More...
def | codes_get
| Get the value of a key in a grib message. More...
def | codes_get_array
| Get the contents of an array key. More...
def | codes_get_values
| Retrieve the contents of the 'values' key. More...
def | codes_set_values
| Set the contents of the 'values' key. More...
def | codes_set
| Set the value for a scalar key in a grib message. More...
def | codes_set_array
| Set the value for an array key in a message. More...
def | codes_index_get
| Get the distinct values of an index key. More...
def | codes_index_select
| Select the message subset with key==value. More...
def | codes_index_write
| Write an index to a file for later reuse. More...
def | codes_index_read
| Loads an index previously saved with codes_index_write to a file. More...
def | codes_no_fail_on_wrong_length
| Do not fail if the message has the wrong length. More...
def | codes_gts_header
| Set the GTS header on/off. More...
def | codes_get_api_version
| Get the api version. More...
def | codes_get_message
| Get the binary message. More...
def | codes_new_from_message
| Create a grib handle from a message in memory. More...
def | codes_set_definitions_path
| Set the definitions path. More...
def | codes_set_samples_path
| Set the samples path. More...

## Detailed Description

This package is the Python interface to ecCodes.

It offers almost one to one bindings to the C API functions.

The Python interface to ecCodes uses the NumPy package as the container of choice for the possible arrays of values that can be encoded/decoded in and from a grib message. Numpy is a package used for scientific computing in Python and an efficient container for generic data.

The Python interface can be enabled/disabled from CMake by using the following flag:

-DENABLE_PYTHON=ON
or
-DENABLE_PYTHON=OFF

When this is enabed, then the system Python will be used to build the interface.

Requirements:

    - Python 2.6 or higher
    - NumPy

## Function Documentation

def ecCodes.codes_any_new_from_file | ( |  | fileobj,
|  |  | headers_only = `False`
| ) |  |

Load in memory a message from a file.

The message can be accessed through its id and will be available
until codes_release is called.
Examples: grib_get_keys.py

Parameters

  fileobj | python file object
  headers_only | whether or not to load the message with the headers only

Returns
  id of the message loaded in memory

Exceptions

  CodesInternalError |

References codes_bufr_new_from_file().

Referenced by codes_new_from_file().

def ecCodes.codes_bufr_new_from_file | ( |  | fileobj,
|  |  | headers_only = `False`
| ) |  |

Load in memory a BUFR message from a file.

The message can be accessed through its id and will be available
until codes_release is called.
Examples: bufr_get_keys.py

Parameters

  fileobj | python file object
  headers_only | whether or not to load the message with the headers only

Returns
  id of the BUFR loaded in memory

Exceptions

  CodesInternalError |

References codes_grib_new_from_file().

Referenced by codes_any_new_from_file(), and codes_metar_new_from_file().

def ecCodes.codes_bufr_new_from_samples | ( |  | samplename | ) |

Create a new valid BUFR message from a sample.

The available samples are picked up from the directory pointed to by the environment variable ECCODES_SAMPLES_PATH. To know where the samples directory is run the codes_info tool.
Examples: grib_samples.py

Parameters

  samplename | name of the BUFR sample to be used

Returns
  id of the message loaded in memory

Exceptions

  CodesInternalError |

References codes_get_double_array(), and codes_get_size().

Referenced by codes_set_long().

def ecCodes.codes_clone | ( |  | msgid_src | ) |

Create a copy of a message.

Create a copy of a given message (msgid_src) resulting in a new message in memory (msgid_dest) identical to the original one.

Examples: grib_clone.py

Parameters

  msgid_src | id of message to be cloned

Returns
  id of clone

Exceptions

  CodesInternalError |

References codes_get_size(), and grib_get_string_array().

Referenced by codes_set_double().

def ecCodes.codes_copy_namespace | ( |  | gribid_src,
|  |  | namespace,
|  |  | gribid_dest
| ) |  |

Copy the value of all the keys belonging to a namespace from the source message to the destination message.

Parameters

  gribid_src | id of source message
  gribid_dest | id of destination message
  namespace | namespace to be copied

Exceptions

  CodesInternalError |

Referenced by grib_set_string_array().

def ecCodes.codes_count_in_file | ( |  | fileobj | ) |

Count the messages in a file.

Examples: count_messages.py

Parameters

  fileobj | python file object

Returns
  number of messages in the file

Exceptions

  CodesInternalError |

References codes_grib_multi_support_off().

Referenced by codes_grib_new_from_file().

def ecCodes.codes_get | ( |  | msgid,
|  |  | key,
|  |  | ktype = `None`
| ) |  |

Get the value of a key in a grib message.

The type of value returned depends on the native type of the requested key. The type of value returned can be forced by using the type argument of the function. The type argument can be int, float or str.

The msgid references a grib message loaded in memory.

Examples: grib_get_keys.py, grib_print_data.py

See Also
  codes_grib_new_from_file, codes_release, codes_set

Parameters

  msgid | id of the grib loaded in memory
  key | key name
  ktype | the type we want the output in (int, float or str), native type if not specified

Returns
  scalar value of key as int, float or str

Exceptions

  CodesInternalError |

References codes_set(), codes_set_double(), codes_set_double_array(), codes_set_long(), and codes_set_string().

Referenced by codes_is_defined().

def ecCodes.codes_get_api_version | ( | void |  | ) |

Get the api version.

Get the API version.

Returns the version of the api as a string in the format "major.minor.revision".

Referenced by codes_index_get(), and codes_index_select().

def ecCodes.codes_get_array | ( |  | msgid,
|  |  | key,
|  |  | ktype = `None`
| ) |  |

Get the contents of an array key.

The output array will be stored in a NumPy ndarray. The type of the array returned depends on the native type of the requested key. The type of value returned can be forced by using the type argument of the function. The type argument can be int, float or string.

Parameters

  msgid | id of the message loaded in memory
  key | the key to get the value for
  ktype | the type we want the output in (can be int, float or string), native type if not specified

Returns
  numpy.ndarray

Exceptions

  CodesInternalError |

References codes_set_array().

Referenced by codes_grib_find_nearest().

def ecCodes.codes_get_double | ( |  | msgid,
|  |  | key
| ) |  |

Get the value of a key in a grib message as a float.

Parameters

  msgid | id of the message loaded in memory
  key | key name

Returns
  value of key as float

Exceptions

  CodesInternalError |

References codes_new_from_samples().

Referenced by codes_grib_find_nearest(), and codes_keys_iterator_delete().

def ecCodes.codes_get_double_array | ( |  | msgid,
|  |  | key
| ) |  |

Get the value of the key as a NumPy array of doubles.

Parameters

  msgid | id of the message loaded in memory
  key | key name

Returns
  numpy.ndarray

Exceptions

  CodesInternalError |

References codes_set_long_array().

Referenced by codes_bufr_new_from_samples(), codes_get_native_type(), and codes_grib_find_nearest().

def ecCodes.codes_get_double_element | ( |  | gribid,
|  |  | key,
|  |  | index
| ) |  |

Get as double the i-th element of the "key" array.

Parameters

  gribid | id of the grib loaded in memory
  key | the key to be searched
  index | zero based index of value to retrieve

Returns
  value

Exceptions

  CodesInternalError |

Referenced by codes_index_select_double().

def ecCodes.codes_get_double_elements | ( |  | gribid,
|  |  | key,
|  |  | indexes
| ) |  |

Get as double array the elements of the "key" array whose indexes are listed in the input array.

Parameters

  gribid | id of the grib loaded in memory
  key | the key to be searched
  indexes | list or tuple of indexes

Returns
  numpy.ndarray

Exceptions

  CodesInternalError |

Referenced by codes_index_select_string().

def ecCodes.codes_get_elements | ( |  | gribid,
|  |  | key,
|  |  | indexes
| ) |  |

Retrieve the elements of the key array for the indexes specified in the input.

Parameters

  gribid | id of the grib loaded in memory
  key | the key to be searched
  indexes | single index or a list of indexes

Returns
  numpy.ndarray containing the values of key for the given indexes

Exceptions

  CodesInternalError |

References codes_is_defined(), and codes_is_missing().

Referenced by codes_new_from_index().

def ecCodes.codes_get_long | ( |  | msgid,
|  |  | key
| ) |  |

Get the value of a key in a grib message as an int.

Parameters

  msgid | id of the message loaded in memory
  key | key name

Returns
  value of key as int

Exceptions

  CodesInternalError |

References codes_set_double().

Referenced by codes_grib_find_nearest(), and codes_keys_iterator_next().

def ecCodes.codes_get_long_array | ( |  | msgid,
|  |  | key
| ) |  |

Get the integer array of values for a key from a grib message.

Parameters

  msgid | id of the message loaded in memory
  key | key name

Returns
  numpy.ndarray

Exceptions

  CodesInternalError |

Referenced by codes_grib_find_nearest(), and grib_get_string_array().

def ecCodes.codes_get_message | ( |  | msgid | ) |

Get the binary message.

Returns the binary string message associated with the grib identified by msgid.

See Also
  codes_new_from_message

Parameters

  msgid | id of the grib loaded in memory

Returns
  binary string message associated with msgid

Exceptions

  CodesInternalError |

Referenced by codes_index_select().

def ecCodes.codes_get_message_offset | ( |  | msgid | ) |

Get the offset of a coded message.

Parameters

  msgid | id of the message loaded in memory

Returns
  offset in bytes of the message

Exceptions

  CodesInternalError |

References codes_set_key_vals().

Referenced by codes_index_select_double().

def ecCodes.codes_get_message_size | ( |  | msgid | ) |

Get the size of a coded message.

Parameters

  msgid | id of the message loaded in memory

Returns
  size in bytes of the message

Exceptions

  CodesInternalError |

References codes_set_missing().

Referenced by codes_index_select_long().

def ecCodes.codes_get_native_type | ( |  | gribid,
|  |  | key
| ) |  |

Retrieve the native type of a key.

Possible values can be int, float or string.

Parameters

  gribid | id of the grib loaded in memory
  key | key we want to find out the type for

Returns
  type of key given as input or None if not determined

Exceptions

  CodesInternalError |

References codes_get_double_array(), codes_get_values(), and codes_set_values().

Referenced by codes_grib_find_nearest(), and codes_set_key_vals().

def ecCodes.codes_get_size | ( |  | msgid,
|  |  | key
| ) |  |

Get the size of an array key.

Examples: grib_get_keys.py,count_messages.py

Parameters

  msgid | id of the message loaded in memory
  key | name of the key

Exceptions

  CodesInternalError |

Referenced by codes_bufr_new_from_samples(), codes_clone(), codes_grib_multi_write(), and grib_get_string_array().

def ecCodes.codes_get_string | ( |  | msgid,
|  |  | key
| ) |  |

Get the string value of a key from a message.

Parameters

  msgid | id of the message loaded in memory
  key | key name

Returns
  string value of key

Exceptions

  CodesInternalError |

References codes_gribex_mode_off(), and codes_gribex_mode_on().

Referenced by codes_grib_find_nearest(), and codes_grib_multi_support_off().

def ecCodes.codes_get_string_length | ( |  | msgid,
|  |  | key
| ) |  |

Get the length of the string version of a key.

Parameters

  msgid | id of the message loaded in memory
  key | name of the key

Exceptions

  CodesInternalError |

References codes_skip_coded(), and codes_skip_edition_specific().

Referenced by codes_grib_multi_append(), and codes_release().

def ecCodes.codes_get_values | ( |  | gribid | ) |

Retrieve the contents of the 'values' key.

A NumPy ndarray containing the values in the message is returned.

Examples: grib_print_data.py, grib_samples.py

Parameters

  gribid | id of the grib loaded in memory

Returns
  numpy.ndarray

Exceptions

  CodesInternalError |

References codes_index_get(), codes_set_double_array(), codes_set_long_array(), and grib_set_string_array().

Referenced by codes_get_native_type().

def ecCodes.codes_grib_find_nearest | ( |  | gribid,
|  |  | inlat,
|  |  | inlon,
|  |  | is_lsm = `False`,
|  |  | npoints = `1`
| ) |  |

Find the nearest grid point or the nearest four grid points to a given latitude/longitude.

The number of nearest points returned can be controled through the npoints function argument.

Examples: grib_nearest.py

Parameters

  gribid | id of the grib loaded in memory
  inlat | latitude of the point
  inlon | longitude of the point
  is_lsm | True if the nearest land point is required otherwise False.
  npoints | 1 or 4 nearest grid points

Returns
  (npoints*(outlat,outlon,value,dist,index))

Exceptions

  CodesInternalError |

References codes_get_array(), codes_get_double(), codes_get_double_array(), codes_get_long(), codes_get_long_array(), codes_get_native_type(), codes_get_string(), and grib_get_string_array().

Referenced by codes_set_missing().

def ecCodes.codes_grib_iterator_delete | ( |  | iterid | ) |

Delete a geoiterator and free memory.

Examples: grib_iterator.py

Parameters

  iterid | geoiterator id

Exceptions

  CodesInternalError |

Referenced by codes_skip_read_only().

def ecCodes.codes_grib_iterator_new | ( |  | gribid,
|  |  | mode
| ) |  |

Create a new geoiterator for the given message, using its geometry and values.

The geoiterator can be used to go through all the geopoints in a message and retrieve the values corresponding to those geopoints.

Examples: grib_iterator.py

Parameters

  gribid | id of the grib loaded in memory
  mode | flags for future use

Returns
  geoiterator id

References codes_keys_iterator_new().

Referenced by codes_skip_duplicates().

def ecCodes.codes_grib_iterator_next | ( |  | iterid | ) |

Retrieve the next value from a geoiterator.

Examples: grib_iterator.py

Parameters

  iterid | geoiterator id

Returns
  tuple with the latitude, longitude and value

Exceptions

  CodesInternalError |

References codes_keys_iterator_delete(), and codes_keys_iterator_next().

Referenced by codes_skip_function().

def ecCodes.codes_grib_multi_append | ( |  | ingribid,
|  |  | startsection,
|  |  | multigribid
| ) |  |

Append a single field grib message to a multi field grib message.

Only the sections with section number greather or equal "startsection" are copied from the input single message to the multi field output grib.

Examples: grib_multi_write.py

Parameters

  ingribid | id of the input single grib
  startsection | starting from startsection (included) all the sections are copied from the input single grib to the output multi grib
  multigribid | id of the output multi filed grib

Exceptions

  CodesInternalError |

References codes_get_string_length(), and codes_skip_computed().

Referenced by codes_write().

def ecCodes.codes_grib_multi_new | ( |  | ) |

Create a new multi field and return its id.

Examples: grib_multi_write.py

Returns
  id of the multi field

Exceptions

  CodesInternalError |

References codes_index_add_file().

Referenced by grib_get_string_array().

def ecCodes.codes_grib_multi_release | ( |  | gribid | ) |

Release a multi field from memory.

Examples: grib_multi_write.py

Parameters

  gribid | id of the multi field we want to release the memory for

Exceptions

  CodesInternalError |

References codes_index_get_size(), and codes_index_release().

Referenced by grib_set_string_array().

def ecCodes.codes_grib_multi_support_off | ( |  | ) |

Turn off the support for multiple fields in a single message.

Exceptions

  CodesInternalError |

References codes_get_string().

Referenced by codes_count_in_file().

def ecCodes.codes_grib_multi_support_on | ( |  | ) |

Turn on the support for multiple fields in a single message.

Exceptions

  CodesInternalError |

References codes_release().

Referenced by codes_grib_new_from_file().

def ecCodes.codes_grib_multi_write | ( |  | multigribid,
|  |  | fileobj
| ) |  |

Write a multi field message to a file.

Examples: grib_multi_write.py

Parameters

  multigribid | id of the multi field grib loaded in memory
  fileobj | python file object

Exceptions

  CodesInternalError |

References codes_get_size().

Referenced by codes_gribex_mode_off().

def ecCodes.codes_grib_new_from_file | ( |  | fileobj,
|  |  | headers_only = `False`
| ) |  |

Load in memory a grib message from a file.

The message can be accessed through its gribid and will be available
until codes_release is called.
The message can be loaded headers only by using the headers_only argument. Default is to have the headers only option set to off (False). If set to on (True), data values will be skipped. This will result in a significant performance gain if one is only interested in browsing through messages to retrieve metadata. Any attempt to retrieve data values keys when in the headers only mode will result in a key not found error.

Examples: grib_get_keys.py

Parameters

  fileobj | python file object
  headers_only | whether or not to load the message with the headers only

Returns
  id of the grib loaded in memory

Exceptions

  CodesInternalError |

References codes_count_in_file(), and codes_grib_multi_support_on().

Referenced by codes_bufr_new_from_file(), and codes_metar_new_from_file().

def ecCodes.codes_gribex_mode_off | ( |  | ) |

Turn off the compatibility mode with gribex.

Exceptions

  CodesInternalError |

References codes_grib_multi_write().

Referenced by codes_get_string().

def ecCodes.codes_gribex_mode_on | ( |  | ) |

Turn on the compatibility mode with gribex.

Exceptions

  CodesInternalError |

Referenced by codes_get_string().

def ecCodes.codes_gts_header | ( |  | flag | ) |

Set the GTS header on/off.

Parameters

  flag | True/False

Referenced by codes_index_get().

def ecCodes.codes_gts_new_from_file | ( |  | fileobj,
|  |  | headers_only = `False`
| ) |  |

Load in memory a GTS message from a file.

The message can be accessed through its id and will be available
until codes_release is called.

Parameters

  fileobj | python file object
  headers_only | whether or not to load the message with the headers only

Returns
  id of the GTS loaded in memory

Exceptions

  CodesInternalError |

References codes_metar_new_from_file().

Referenced by codes_new_from_file().

def ecCodes.codes_index_add_file | ( |  | indexid,
|  |  | filename
| ) |  |

Add a file to an index.

Examples: grib_index.py

Parameters

  indexid | id of the index to add the file to
  filename | path of the file to be added to index

Exceptions

  CodesInternalError |

References codes_index_get_string().

Referenced by codes_grib_multi_new().

def ecCodes.codes_index_get | ( |  | indexid,
|  |  | key,
|  |  | ktype = `str`
| ) |  |

Get the distinct values of an index key.

The key must belong to the index.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created on the given key.
  key | key for which the values are returned
  ktype | the type we want the output in (int, float or str), str if not specified

Returns
  array of values

Exceptions

  CodesInternalError |

References codes_get_api_version(), and codes_gts_header().

Referenced by codes_get_values().

def ecCodes.codes_index_get_double | ( |  | indexid,
|  |  | key
| ) |  |

Get the distinct values of the key in argument contained in the index.

The key must belong to the index.

This function is used when the type of the key was explicitly defined as double or when the native type of the key is double.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created with the key in argument.
  key | key for wich the values are returned

Returns
  tuple with values of key in index

Exceptions

  CodesInternalError |

References codes_new_from_index().

Referenced by codes_index_get_size(), and codes_set_values().

def ecCodes.codes_index_get_long | ( |  | indexid,
|  |  | key
| ) |  |

Get the distinct values of the key in argument contained in the index.

The key must belong to the index.

This function is used when the type of the key was explicitly defined as long or when the native type of the key is long.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created with the key in argument.
  key | key for wich the values are returned

Returns
  tuple with values of key in index

Exceptions

  CodesInternalError |

References codes_index_get_size(), and codes_index_select_long().

Referenced by codes_index_new_from_file(), and codes_set_values().

def ecCodes.codes_index_get_size | ( |  | indexid,
|  |  | key
| ) |  |

Get the number of distinct values for the index key.

The key must belong to the index.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created on the given key.
  key | key for which the number of values is computed

Returns
  number of distinct values for key in index

Exceptions

  CodesInternalError |

References codes_index_get_double().

Referenced by codes_grib_multi_release(), codes_index_get_long(), codes_index_new_from_file(), and codes_index_release().

def ecCodes.codes_index_get_string | ( |  | indexid,
|  |  | key
| ) |  |

Get the distinct values of the key in argument contained in the index.

The key must belong to the index.

This function is used when the type of the key was explicitly defined as string or when the native type of the key is string.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created with the key in argument.
  key | key for wich the values are returned

Returns
  tuple with values of key in index

Exceptions

  CodesInternalError |

References codes_index_select_double(), and codes_index_select_string().

Referenced by codes_index_add_file(), and codes_set_values().

def ecCodes.codes_index_new_from_file | ( |  | filename,
|  |  | keys
| ) |  |

Create a new index from a file.

Examples: grib_index.py

Parameters

  filename | path of the file to index on
  keys | sequence of keys to index on. The type of the key can be explicitly declared appending :l for long (or alternatively :i), :d for double, :s for string to the key name.

Returns
  index id

Exceptions

  CodesInternalError |

References codes_index_get_long(), and codes_index_get_size().

Referenced by codes_set_long_array().

def ecCodes.codes_index_read | ( |  | filename | ) |

Loads an index previously saved with codes_index_write to a file.

Examples: grib_index.py

Parameters

  filename | path of file to load the index from

Returns
  id of the loaded index

Exceptions

  CodesInternalError |

References codes_set_definitions_path(), and codes_set_samples_path().

Referenced by codes_set_array().

def ecCodes.codes_index_release | ( |  | indexid | ) |

Delete an index.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file.

Exceptions

  CodesInternalError |

References codes_index_get_size().

Referenced by codes_grib_multi_release().

def ecCodes.codes_index_select | ( |  | indexid,
|  |  | key,
|  |  | value
| ) |  |

Select the message subset with key==value.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created with the key in argument.
  key | key to be selected
  value | value of the key to select

Exceptions

  CodesInternalError |

References codes_get_api_version(), codes_get_message(), and codes_new_from_message().

Referenced by codes_set().

def ecCodes.codes_index_select_double | ( |  | indexid,
|  |  | key,
|  |  | value
| ) |  |

Select the message subset with key==value.

The value is a double.

The key must have been created with integer type or have integer as native type if the type was not explicitly defined in the index creation.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created with the key in argument.
  key | key to be selected
  value | value of the key to select

Exceptions

  CodesInternalError |

References codes_get_double_element(), and codes_get_message_offset().

Referenced by codes_index_get_string(), and codes_set().

def ecCodes.codes_index_select_long | ( |  | indexid,
|  |  | key,
|  |  | value
| ) |  |

Select the message subset with key==value.

The value is an integer.

The key must have been created with integer type or have integer as native type if the type was not explicitly defined in the index creation.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created with the key in argument.
  key | key to be selected
  value | value of the key to select

Exceptions

  CodesInternalError |

References codes_get_message_size().

Referenced by codes_index_get_long(), and codes_set().

def ecCodes.codes_index_select_string | ( |  | indexid,
|  |  | key,
|  |  | value
| ) |  |

Select the message subset with key==value.

The value is an integer.

The key must have been created with string type or have string as native type if the type was not explicitly defined in the index creation.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file. The index must have been created with the key in argument.
  key | key to be selected
  value | value of the key to select

Exceptions

  CodesInternalError |

References codes_get_double_elements().

Referenced by codes_index_get_string(), and codes_set().

def ecCodes.codes_index_write | ( |  | indexid,
|  |  | filename
| ) |  |

Write an index to a file for later reuse.

An index can be loaded back from an index file with codes_index_read.

Examples: grib_index.py

Parameters

  indexid | id of the index
  filename | path of file to save the index to

Exceptions

  CodesInternalError |

Referenced by codes_set().

def ecCodes.codes_is_defined | ( |  | msgid,
|  |  | key
| ) |  |

Check if a key is defined (exists)

Parameters

  msgid | id of the message loaded in memory
  key | key name

Returns
  0->not defined, 1->defined

Exceptions

  CodesInternalError |

References codes_get().

Referenced by codes_get_elements().

def ecCodes.codes_is_missing | ( |  | msgid,
|  |  | key
| ) |  |

Check if the value of a key is MISSING.

The value of a key is considered as MISSING when all the bits assigned to it are set to 1. This is different from the actual key missing from the grib message. The value of a key MISSING has a special significance and that can be read about in the WMO documentation.

Parameters

  msgid | id of the message loaded in memory
  key | key name

Returns
  0->not missing, 1->missing

Exceptions

  CodesInternalError |

Referenced by codes_get_elements().

def ecCodes.codes_keys_iterator_delete | ( |  | iterid | ) |

Delete a keys iterator and free memory.

Examples: grib_keys_iterator.py

Parameters

  iterid | keys iterator id created with codes_keys_iterator_new

Exceptions

  CodesInternalError |

References codes_get_double().

Referenced by codes_grib_iterator_next().

def ecCodes.codes_keys_iterator_get_name | ( |  | iterid | ) |

Get the name of a key from a keys iterator.

Examples: grib_keys_iterator.py

Parameters

  iterid | keys iterator id created with codes_keys_iterator_new

Returns
  key name to be retrieved

Exceptions

  CodesInternalError |

References codes_set_long().

Referenced by codes_keys_iterator_new().

def ecCodes.codes_keys_iterator_new | ( |  | msgid,
|  |  | namespace = `None`
| ) |  |

Create a new iterator on the keys.

The keys iterator can be navigated to give all the key names which can then be used to get or set the key values with codes_get or codes_set. The set of keys returned can be controlled with the input variable namespace or using the functions codes_skip_read_only, codes_skip_duplicates, codes_skip_coded,codes_skip_computed. If namespace is a non empty string only the keys belonging to that namespace are returned. Example namespaces are "ls" (to get the same default keys as the grib_ls) and "mars" to get the keys used by mars.

Examples: grib_iterator.py

Parameters

  msgid | id of the message loaded in memory
  namespace | the namespace of the keys to search for (all the keys if None)

Returns
  keys iterator id to be used in the keys iterator functions

Exceptions

  CodesInternalError |

References codes_keys_iterator_get_name().

Referenced by codes_grib_iterator_new().

def ecCodes.codes_keys_iterator_next | ( |  | iterid | ) |

Advance to the next keys iterator value.

Examples: grib_keys_iterator.py

Parameters

  iterid | keys iterator id created with codes_keys_iterator_new

Exceptions

  CodesInternalError |

References codes_get_long(), and codes_keys_iterator_rewind().

Referenced by codes_grib_iterator_next().

def ecCodes.codes_keys_iterator_rewind | ( |  | iterid | ) |

Rewind a keys iterator.

Parameters

  iterid | keys iterator id created with codes_keys_iterator_new

Exceptions

  CodesInternalError |

Referenced by codes_keys_iterator_next().

def ecCodes.codes_metar_new_from_file | ( |  | fileobj,
|  |  | headers_only = `False`
| ) |  |

Load in memory a METAR message from a file.

The message can be accessed through its id and will be available
until codes_release is called.

Parameters

  fileobj | python file object
  headers_only | whether or not to load the message with the headers only

Returns
  id of the METAR loaded in memory

Exceptions

  CodesInternalError |

References codes_bufr_new_from_file(), codes_grib_new_from_file(), and codes_new_from_file().

Referenced by codes_gts_new_from_file().

def ecCodes.codes_new_from_file | ( |  | fileobj,
|  |  | product_kind,
|  |  | headers_only = `False`
| ) |  |

Load in memory a message from a file for a given product.

The message can be accessed through its id and will be available
until codes_release is called.
Examples: get_product_kind.py

Parameters

  fileobj | python file object
  product_kind | one of CODES_PRODUCT_GRIB, CODES_PRODUCT_BUFR, CODES_PRODUCT_METAR or CODES_PRODUCT_GTS
  headers_only | whether or not to load the message with the headers only

Returns
  id of the message loaded in memory

Exceptions

  CodesInternalError |

References codes_any_new_from_file(), and codes_gts_new_from_file().

Referenced by codes_metar_new_from_file().

def ecCodes.codes_new_from_index | ( |  | indexid | ) |

Create a new handle from an index after having selected the key values.

All the keys belonging to the index must be selected before calling this function. Successive calls to this function will return all the handles compatible with the constraints defined selecting the values of the index keys.

The message can be accessed through its gribid and will be available until codes_release is called.

Examples: grib_index.py

Parameters

  indexid | id of an index created from a file.

Returns
  id of the message loaded in memory or None if end of index

Exceptions

  CodesInternalError |

References codes_get_elements().

Referenced by codes_index_get_double().

def ecCodes.codes_new_from_message | ( |  | message | ) |

Create a grib handle from a message in memory.

Create a new grib message from the input binary string and return its grib id.

See Also
  codes_get_message

Parameters

  message | binary string message

Returns
  msgid of the newly created grib message

Exceptions

  CodesInternalError |

Referenced by codes_index_select().

def ecCodes.codes_new_from_samples | ( |  | samplename | ) |

Create a new valid GRIB message from a sample.

The available samples are picked up from the directory pointed to by the environment variable ECCODES_SAMPLES_PATH. To know where the samples directory is run the codes_info tool.
Examples: grib_samples.py

Parameters

  samplename | name of the sample to be used

Returns
  id of the message loaded in memory

Exceptions

  CodesInternalError |

References codes_set_double_array().

Referenced by codes_get_double().

def ecCodes.codes_no_fail_on_wrong_length | ( |  | flag | ) |

Do not fail if the message has the wrong length.

Parameters

  flag | True/False

Referenced by codes_set_array().

def ecCodes.codes_release | ( |  | msgid | ) |

Free the memory for the message referred as msgid.

Examples: grib_get_keys.py

Parameters

  msgid | id of the message loaded in memory

Exceptions

  CodesInternalError |

References codes_get_string_length(), and codes_set_string().

Referenced by codes_grib_multi_support_on().

def ecCodes.codes_set | ( |  | msgid,
|  |  | key,
|  |  | value
| ) |  |

Set the value for a scalar key in a grib message.

The input value can be a python int, float or str.

Examples: grib_set_keys.py

See Also
  codes_grib_new_from_file, codes_release, codes_get

Parameters

  msgid | id of the grib loaded in memory
  key | key name
  value | scalar value to set for key

Exceptions

  CodesInternalError |

References codes_index_select(), codes_index_select_double(), codes_index_select_long(), codes_index_select_string(), and codes_index_write().

Referenced by codes_get().

def ecCodes.codes_set_array | ( |  | msgid,
|  |  | key,
|  |  | value
| ) |  |

Set the value for an array key in a message.

Examples of array keys: "values" - data values "pl" - list of number of points for each latitude in a reduced grid "pv" - list of vertical levels

The input array can be a numpy.ndarray or a python sequence like tuple, list, array, ...

The wrapper will internally try to convert the input to a NumPy array before extracting its data and length. This is possible as NumPy allows the construction of arrays from arbitrary python sequences.

Parameters

  msgid | id of the message loaded in memory
  key | key name
  value | array to set for key

Exceptions

  CodesInternalError |

References codes_index_read(), and codes_no_fail_on_wrong_length().

Referenced by codes_get_array().

def ecCodes.codes_set_definitions_path | ( |  | defs_path | ) |

Set the definitions path.

Parameters

  defs_path | definitions path

Referenced by codes_index_read().

def ecCodes.codes_set_double | ( |  | msgid,
|  |  | key,
|  |  | value
| ) |  |

Set the double value for a key in a grib message.

A TypeError exception will be thrown if value cannot be represented as a float.

Parameters

  msgid | id of the message loaded in memory
  key | key name
  value | float value to set

Exceptions

  CodesInternalError,TypeError |

References codes_clone().

Referenced by codes_get(), and codes_get_long().

def ecCodes.codes_set_double_array | ( |  | msgid,
|  |  | key,
|  |  | inarray
| ) |  |

Set the value of the key to a double array.

The input array can be a numpy.ndarray or a python sequence like tuple, list, array, ...

The wrapper will internally try to convert the input to a NumPy array before extracting its data and length. This is possible as NumPy allows the construction of arrays from arbitrary python sequences.

The elements of the input sequence need to be convertible to a double.

Parameters

  msgid | id of the message loaded in memory
  key | key name
  inarray | tuple,list,array,numpy.ndarray

Exceptions

  CodesInternalError |

References grib_set_string_array().

Referenced by codes_get(), codes_get_values(), and codes_new_from_samples().

def ecCodes.codes_set_key_vals | ( |  | gribid,
|  |  | key_vals
| ) |  |

Set the values for several keys at once in a grib message.

Parameters

  gribid | id of the grib loaded in memory
  key_vals | can be a string, list/tuple or dictionary. If a string, format must be "key1=val1,key2=val2" If a list, it must contain strings of the form "key1=val1"

Exceptions

  CodesInternalError |

References codes_get_native_type().

Referenced by codes_get_message_offset().

def ecCodes.codes_set_long | ( |  | msgid,
|  |  | key,
|  |  | value
| ) |  |

Set the integer value for a key in a grib message.

A TypeError exception will be thrown if value cannot be represented as an integer.

Parameters

  msgid | id of the message loaded in memory
  key | key name
  value | value to set

Exceptions

  CodesInternalError,TypeError |

References codes_bufr_new_from_samples().

Referenced by codes_get(), and codes_keys_iterator_get_name().

def ecCodes.codes_set_long_array | ( |  | msgid,
|  |  | key,
|  |  | inarray
| ) |  |

Set the value of the key to an integer array.

The input array can be a numpy.ndarray or a python sequence like tuple, list, array, ...

The wrapper will internally try to convert the input to a NumPy array before extracting its data and length. This is possible as NumPy allows the construction of arrays from arbitrary python sequences.

The elements of the input sequence need to be convertible to an int.

Parameters

  msgid | id of the message loaded in memory
  key | key name
  inarray | tuple,list,python array,numpy.ndarray

Exceptions

  CodesInternalError |

References codes_index_new_from_file().

Referenced by codes_get_double_array(), and codes_get_values().

def ecCodes.codes_set_missing | ( |  | msgid,
|  |  | key
| ) |  |

Set as missing the value for a key in a grib message.

It can be used to set a missing value in the grib header but not in the data values.

Examples: grib_set_missing.py

Parameters

  msgid | id of the message loaded in memory
  key | key name

Exceptions

  CodesInternalError |

References codes_grib_find_nearest().

Referenced by codes_get_message_size().

def ecCodes.codes_set_samples_path | ( |  | samples_path | ) |

Set the samples path.

Parameters

  samples_path | samples path

Referenced by codes_index_read().

def ecCodes.codes_set_string | ( |  | msgid,
|  |  | key,
|  |  | value
| ) |  |

Set the value for a string key in a grib message.

Parameters

  msgid | id of the message loaded in memory
  key | key name
  value | string value

Exceptions

  CodesInternalError |

References codes_write().

Referenced by codes_get(), and codes_release().

def ecCodes.codes_set_values | ( |  | gribid,
|  |  | values
| ) |  |

Set the contents of the 'values' key.

The input array can be a numpy.ndarray or a python sequence like tuple, list, array, ...

The wrapper will internally try to convert the input to a NumPy array before extracting its data and length. This is possible as NumPy allows the construction of arrays from arbitrary python sequences.

The elements of the input sequence need to be convertible to a double.

Examples: grib_clone.py, grib_samples.py

Parameters

  gribid | id of the grib loaded in memory
  values | array of values to set as tuple, list, array or numpy.ndarray

References codes_index_get_double(), codes_index_get_long(), and codes_index_get_string().

Referenced by codes_get_native_type().

def ecCodes.codes_skip_coded | ( |  | iterid | ) |

Skip the coded keys in a keys iterator.

The coded keys are actually coded in the message.

See Also
  codes_keys_iterator_new,codes_keys_iterator_next,codes_keys_iterator_delete

Parameters

  iterid | keys iterator id

Exceptions

  CodesInternalError |

References codes_skip_read_only().

Referenced by codes_get_string_length().

def ecCodes.codes_skip_computed | ( |  | iterid | ) |

Skip the computed keys in a keys iterator.

The computed keys are not coded in the message, they are computed from other keys.

See Also
  codes_keys_iterator_new,codes_keys_iterator_next,codes_keys_iterator_delete

Parameters

  iterid | keys iterator id

Exceptions

  CodesInternalError |

References codes_skip_duplicates().

Referenced by codes_grib_multi_append().

def ecCodes.codes_skip_duplicates | ( |  | iterid | ) |

Skip the duplicate keys in a keys iterator.

See Also
  codes_keys_iterator_new,codes_keys_iterator_next,codes_keys_iterator_delete

Parameters

  iterid | keys iterator id

Exceptions

  CodesInternalError |

References codes_grib_iterator_new().

Referenced by codes_skip_computed().

def ecCodes.codes_skip_edition_specific | ( |  | iterid | ) |

Skip the edition specific keys in a keys iterator.

See Also
  codes_keys_iterator_new,codes_keys_iterator_next,codes_keys_iterator_delete

Parameters

  iterid | keys iterator id

Exceptions

  CodesInternalError |

References codes_skip_function().

Referenced by codes_get_string_length().

def ecCodes.codes_skip_function | ( |  | iterid | ) |

Skip the function keys in a keys iterator.

See Also
  codes_keys_iterator_new,codes_keys_iterator_next,codes_keys_iterator_delete

Parameters

  iterid | keys iterator id

Exceptions

  CodesInternalError |

References codes_grib_iterator_next().

Referenced by codes_skip_edition_specific().

def ecCodes.codes_skip_read_only | ( |  | iterid | ) |

Skip the read_only keys in a keys iterator.

Read only keys cannot be set.

See Also
  codes_keys_iterator_new,codes_keys_iterator_next,codes_keys_iterator_delete

Parameters

  iterid | keys iterator id

Exceptions

  CodesInternalError |

References codes_grib_iterator_delete().

Referenced by codes_skip_coded().

def ecCodes.codes_write | ( |  | msgid,
|  |  | fileobj
| ) |  |

Write a message to a file.

Examples: grib_set_keys.py

Parameters

  msgid | id of the message loaded in memory
  fileobj | python file object

Exceptions

  CodesInternalError |

References codes_grib_multi_append().

Referenced by codes_set_string().

def ecCodes.grib_get_string_array | ( |  | msgid,
|  |  | key
| ) |  |

Get the value of the key as a list of strings.

Parameters

  msgid | id of the message loaded in memory
  key | key name

Returns
  list

Exceptions

  CodesInternalError |

References codes_get_long_array(), codes_get_size(), and codes_grib_multi_new().

Referenced by codes_clone(), and codes_grib_find_nearest().

def ecCodes.grib_set_string_array | ( |  | msgid,
|  |  | key,
|  |  | inarray
| ) |  |

Set the value of the key to a string array.

The input array can be a python sequence like tuple, list, array, ...

The wrapper will internally try to convert the input to a NumPy array before extracting its data and length. This is possible as NumPy allows the construction of arrays from arbitrary python sequences.

The elements of the input sequence need to be convertible to a double.

Parameters

  msgid | id of the message loaded in memory
  key | key name
  inarray | tuple,list,array

Exceptions

  CodesInternalError |

References codes_copy_namespace(), and codes_grib_multi_release().

Referenced by codes_get_values(), and codes_set_double_array().