This package is the Python interface to ecCodes. 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 message from a sample for a given product. More...

def	codes_grib_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_bufr_copy_data
	Copy data values from a BUFR message msgid_src to another message msgid_dst. 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	codes_get_string_array
	Get the value of the key as a list of strings. More...

def	codes_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 for a GRIB message. 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 message. Numpy is a package used for scientific computing in Python and an efficient container for generic data.

The Python interface can be added via:

    pip3 install eccodes
or
    pip3 install --install-option="--prefix=/path/to/where/you/install/eccodes" eccodes

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

Requirements:

- Python 3.5 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_copy_data	(	msgid_src,
		msgid_dst
	)

Copy data values from a BUFR message msgid_src to another message msgid_dst.

Copies all the values in the data section that are present in the same position in the data tree and with the same number of values to the output handle.

Parameters

msgid_src	id of the message from which the data are copied
msgid_dst	id of the message to which the data are copied

Returns: id of new message

Exceptions

CodesInternalError

References codes_get_double_array(), codes_get_size(), and codes_get_string_array().

Referenced by codes_new_from_samples().

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: bufr_copy_data.py

Parameters

samplename name of the BUFR sample to be used

Returns: id of the message loaded in memory

Exceptions

CodesInternalError

References codes_set_double_array().

Referenced by codes_set_double(), and 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().

Referenced by codes_grib_new_from_samples().

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

References codes_index_get_long().

Referenced by codes_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().

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_copy_data(), 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

References codes_is_missing().

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().

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_get_string_array(), and codes_grib_find_nearest().

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(), 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

References codes_skip_computed().

Referenced by codes_bufr_copy_data(), codes_clone(), codes_get_string_array(), and codes_grib_multi_write().

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_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_bufr_copy_data(), and codes_grib_find_nearest().

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 for a GRIB message.

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 codes_set_string_array().

Referenced by codes_grib_find_nearest().

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(), codes_get_string_array(), and codes_get_values().

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().

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 codes_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 codes_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_grib_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_clone().

Referenced by codes_set_long().

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_copy_namespace(), 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_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_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_double_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(), and codes_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(), codes_gts_new_from_file(), and codes_metar_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,
		product_kind
	)

Create a new valid message from a sample for a given product.

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
product_kind	CODES_PRODUCT_GRIB or CODES_PRODUCT_BUFR

Returns: id of the message loaded in memory

Exceptions

CodesInternalError

References codes_bufr_copy_data().

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_bufr_new_from_samples().

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 codes_set_string_array().

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

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(), and codes_grib_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_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().

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