core
/
eccodes
mirror of https://github.com/ecmwf/eccodes.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ECC-200: Python docs updates

This commit is contained in:
Shahram Najm 2016-07-13 13:47:21 +01:00
parent d8b0c75f01
commit e12a686edf
1 changed files with 202 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

392
python/gribapi.py
View File

@ -171,18 +171,9 @@ def gts_new_from_file(fileobj, headers_only=False):
""" """
@brief Load in memory a GTS message from a file. @brief Load in memory a GTS message from a file.
The message can be accessed through its id and it will be available\n The message can be accessed through its id and will be available\n
until @ref grib_release is called.\n until @ref grib_release is called.\n
The message can be loaded headers only by using the headers_only argument.
Default is to have the headers only option grib_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.
\b Examples: \ref grib_get_keys.py "grib_get_keys.py"
@param fileobj python file object @param fileobj python file object
@param headers_only whether or not to load the message with the headers only @param headers_only whether or not to load the message with the headers only
@return id of the GTS loaded in memory @return id of the GTS loaded in memory
@ -202,18 +193,9 @@ def metar_new_from_file(fileobj, headers_only = False):
""" """
@brief Load in memory a METAR message from a file. @brief Load in memory a METAR message from a file.
The message can be accessed through its id and it will be available\n The message can be accessed through its id and will be available\n
until @ref grib_release is called.\n until @ref grib_release is called.\n
The message can be loaded headers only by using the headers_only argument.
Default is to have the headers only option grib_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.
\b Examples: \ref grib_get_keys.py "grib_get_keys.py"
@param fileobj python file object @param fileobj python file object
@param headers_only whether or not to load the message with the headers only @param headers_only whether or not to load the message with the headers only
@return id of the METAR loaded in memory @return id of the METAR loaded in memory
@ -230,6 +212,20 @@ def metar_new_from_file(fileobj, headers_only = False):
@require(fileobj=file,product_kind=int) @require(fileobj=file,product_kind=int)
def codes_new_from_file(fileobj, product_kind, headers_only = False): def codes_new_from_file(fileobj, product_kind, headers_only = False):
"""
@brief Load in memory a message from a file for a given product.
The message can be accessed through its id and will be available\n
until @ref grib_release is called.\n
\b Examples: \ref get_product_kind.py "get_product_kind.py"
@param fileobj python file object
@param product_kind one of CODES_PRODUCT_GRIB, CODES_PRODUCT_BUFR, CODES_PRODUCT_METAR or CODES_PRODUCT_GTS
@param headers_only whether or not to load the message with the headers only
@return id of the message loaded in memory
@exception GribInternalError
"""
if product_kind == CODES_PRODUCT_GRIB: if product_kind == CODES_PRODUCT_GRIB:
return grib_new_from_file(fileobj, headers_only) return grib_new_from_file(fileobj, headers_only)
if product_kind == CODES_PRODUCT_BUFR: if product_kind == CODES_PRODUCT_BUFR:
@ -247,7 +243,7 @@ def any_new_from_file(fileobj, headers_only = False):
""" """
@brief Load in memory a message from a file. @brief Load in memory a message from a file.
The message can be accessed through its id and it will be available\n The message can be accessed through its id and will be available\n
until @ref grib_release is called.\n until @ref grib_release is called.\n
\b Examples: \ref grib_get_keys.py "grib_get_keys.py" \b Examples: \ref grib_get_keys.py "grib_get_keys.py"
@ -271,17 +267,10 @@ def bufr_new_from_file(fileobj, headers_only=False):
""" """
@brief Load in memory a BUFR message from a file. @brief Load in memory a BUFR message from a file.
The message can be accessed through its id and it will be available\n The message can be accessed through its id and will be available\n
until @ref grib_release is called.\n until @ref grib_release is called.\n
The message can be loaded headers only by using the headers_only argument. \b Examples: \ref bufr_get_keys.py "bufr_get_keys.py"
Default is to have the headers only option grib_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.
\b Examples: \ref grib_get_keys.py "grib_get_keys.py"
@param fileobj python file object @param fileobj python file object
@param headers_only whether or not to load the message with the headers only @param headers_only whether or not to load the message with the headers only
@ -303,7 +292,7 @@ def grib_new_from_file(fileobj, headers_only=False):
""" """
@brief Load in memory a grib message from a file. @brief Load in memory a grib message from a file.
The message can be accessed through its gribid and it will be available\n The message can be accessed through its gribid and will be available\n
until @ref grib_release is called.\n until @ref grib_release is called.\n
The message can be loaded headers only by using the headers_only argument. The message can be loaded headers only by using the headers_only argument.
@ -364,31 +353,31 @@ def grib_multi_support_off():
_internal.grib_c_multi_support_off() _internal.grib_c_multi_support_off()
@require(gribid=int) @require(msgid=int)
def grib_release(gribid): def grib_release(msgid):
""" """
@brief Free the memory for the message referred as gribid. @brief Free the memory for the message referred as msgid.
\b Examples: \ref grib_get_keys.py "grib_get_keys.py" \b Examples: \ref grib_get_keys.py "grib_get_keys.py"
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@exception GribInternalError @exception GribInternalError
""" """
GRIB_CHECK(_internal.grib_c_release(gribid)) GRIB_CHECK(_internal.grib_c_release(msgid))
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_string(gribid, key): def grib_get_string(msgid, key):
""" """
@brief Get the string value of a key from a grib message. @brief Get the string value of a key from a message.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@return string value of key @return string value of key
@exception GribInternalError @exception GribInternalError
""" """
length = grib_get_string_length(gribid, key) length = grib_get_string_length(msgid, key)
err, value = _internal.grib_c_get_string(gribid, key, length) err, value = _internal.grib_c_get_string(msgid, key, length)
GRIB_CHECK(err) GRIB_CHECK(err)
stpos = value.find('\0') stpos = value.find('\0')
@ -398,17 +387,17 @@ def grib_get_string(gribid, key):
return value return value
@require(gribid=int, key=str, value=str) @require(msgid=int, key=str, value=str)
def grib_set_string(gribid, key, value): def grib_set_string(msgid, key, value):
""" """
@brief Set the value for a string key in a grib message. @brief Set the value for a string key in a grib message.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@param value string value @param value string value
@exception GribInternalError @exception GribInternalError
""" """
GRIB_CHECK(_internal.grib_c_set_string(gribid, key, value, len(value))) GRIB_CHECK(_internal.grib_c_set_string(msgid, key, value, len(value)))
def grib_gribex_mode_on(): def grib_gribex_mode_on():
@ -429,18 +418,18 @@ def grib_gribex_mode_off():
_internal.grib_c_gribex_mode_off() _internal.grib_c_gribex_mode_off()
@require(gribid=int, fileobj=file) @require(msgid=int, fileobj=file)
def grib_write(gribid, fileobj): def grib_write(msgid, fileobj):
""" """
@brief Write a message to a file. @brief Write a message to a file.
\b Examples: \ref grib_set_keys.py "grib_set_keys.py" \b Examples: \ref grib_set_keys.py "grib_set_keys.py"
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param fileobj python file object @param fileobj python file object
@exception GribInternalError @exception GribInternalError
""" """
GRIB_CHECK(_internal.grib_c_write(gribid, fileobj)) GRIB_CHECK(_internal.grib_c_write(msgid, fileobj))
@require(multigribid=int, fileobj=file) @require(multigribid=int, fileobj=file)
@ -476,32 +465,32 @@ def grib_multi_append(ingribid, startsection, multigribid):
GRIB_CHECK(_internal.grib_c_multi_append(ingribid, startsection, multigribid)) GRIB_CHECK(_internal.grib_c_multi_append(ingribid, startsection, multigribid))
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_size(gribid, key): def grib_get_size(msgid, key):
""" """
@brief Get the size of an array key. @brief Get the size of an array key.
\b Examples: \ref grib_get_keys.py "grib_get_keys.py",\ref count_messages.py "count_messages.py" \b Examples: \ref grib_get_keys.py "grib_get_keys.py",\ref count_messages.py "count_messages.py"
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key name of the key @param key name of the key
@exception GribInternalError @exception GribInternalError
""" """
err, result = _internal.grib_c_get_size_long(gribid, key) err, result = _internal.grib_c_get_size_long(msgid, key)
GRIB_CHECK(err) GRIB_CHECK(err)
return result return result
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_string_length(gribid, key): def grib_get_string_length(msgid, key):
""" """
@brief Get the length of the string version of a key. @brief Get the length of the string version of a key.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key name of the key @param key name of the key
@exception GribInternalError @exception GribInternalError
""" """
err, result = _internal.grib_c_get_string_length(gribid, key) err, result = _internal.grib_c_get_string_length(msgid, key)
GRIB_CHECK(err) GRIB_CHECK(err)
return result return result
@ -643,8 +632,8 @@ def grib_iterator_next(iterid):
return (lat, lon, value) return (lat, lon, value)
@require(gribid=int) @require(msgid=int)
def grib_keys_iterator_new(gribid, namespace=None): def grib_keys_iterator_new(msgid, namespace=None):
""" """
@brief Create a new iterator on the keys. @brief Create a new iterator on the keys.
@ -661,12 +650,12 @@ def grib_keys_iterator_new(gribid, namespace=None):
\b Examples: \ref grib_iterator.py "grib_iterator.py" \b Examples: \ref grib_iterator.py "grib_iterator.py"
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param namespace the namespace of the keys to search for (all the keys if None) @param namespace the namespace of the keys to search for (all the keys if None)
@return keys iterator id to be used in the keys iterator functions @return keys iterator id to be used in the keys iterator functions
@exception GribInternalError @exception GribInternalError
""" """
err, iterid = _internal.grib_c_keys_iterator_new(gribid, namespace) err, iterid = _internal.grib_c_keys_iterator_new(msgid, namespace)
GRIB_CHECK(err) GRIB_CHECK(err)
return iterid return iterid
@ -727,45 +716,45 @@ def grib_keys_iterator_rewind(iterid):
GRIB_CHECK(_internal.grib_c_keys_iterator_rewind(iterid)) GRIB_CHECK(_internal.grib_c_keys_iterator_rewind(iterid))
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_long(gribid, key): def grib_get_long(msgid, key):
""" """
@brief Get the value of a key in a grib message as an int. @brief Get the value of a key in a grib message as an int.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@return value of key as int @return value of key as int
@exception GribInternalError @exception GribInternalError
""" """
err, value = _internal.grib_c_get_long(gribid, key) err, value = _internal.grib_c_get_long(msgid, key)
GRIB_CHECK(err) GRIB_CHECK(err)
return value return value
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_double(gribid, key): def grib_get_double(msgid, key):
""" """
@brief Get the value of a key in a grib message as a float. @brief Get the value of a key in a grib message as a float.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@return value of key as float @return value of key as float
@exception GribInternalError @exception GribInternalError
""" """
err, value = _internal.grib_c_get_double(gribid, key) err, value = _internal.grib_c_get_double(msgid, key)
GRIB_CHECK(err) GRIB_CHECK(err)
return value return value
@require(gribid=int, key=str, value=(int, long, float, str)) @require(msgid=int, key=str, value=(int, long, float, str))
def grib_set_long(gribid, key, value): def grib_set_long(msgid, key, value):
""" """
@brief Set the integer value for a key in a grib message. @brief Set the integer value for a key in a grib message.
A TypeError exception will be thrown if value cannot be represented A TypeError exception will be thrown if value cannot be represented
as an integer. as an integer.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@param value value to set @param value value to set
@exception GribInternalError,TypeError @exception GribInternalError,TypeError
@ -778,18 +767,18 @@ def grib_set_long(gribid, key, value):
if value > sys.maxint: if value > sys.maxint:
raise TypeError("Invalid type") raise TypeError("Invalid type")
GRIB_CHECK(_internal.grib_c_set_long(gribid, key, value)) GRIB_CHECK(_internal.grib_c_set_long(msgid, key, value))
@require(gribid=int, key=str, value=(int, long, float, str)) @require(msgid=int, key=str, value=(int, long, float, str))
def grib_set_double(gribid, key, value): def grib_set_double(msgid, key, value):
""" """
@brief Set the double value for a key in a grib message. @brief Set the double value for a key in a grib message.
A TypeError exception will be thrown if value cannot be represented A TypeError exception will be thrown if value cannot be represented
as a float. as a float.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@param value float value to set @param value float value to set
@exception GribInternalError,TypeError @exception GribInternalError,TypeError
@ -799,13 +788,13 @@ def grib_set_double(gribid, key, value):
except (ValueError, TypeError): except (ValueError, TypeError):
raise TypeError("Invalid type") raise TypeError("Invalid type")
GRIB_CHECK(_internal.grib_c_set_double(gribid, key, value)) GRIB_CHECK(_internal.grib_c_set_double(msgid, key, value))
@require(samplename=str) @require(samplename=str)
def grib_new_from_samples(samplename): def grib_new_from_samples(samplename):
""" """
@brief Create a new valid gribid from a sample. @brief Create a new valid message from a sample.
The available samples are picked up from the directory pointed to The available samples are picked up from the directory pointed to
by the environment variable ECCODES_SAMPLES_PATH. by the environment variable ECCODES_SAMPLES_PATH.
@ -814,35 +803,35 @@ def grib_new_from_samples(samplename):
\b Examples: \ref samples.py "samples.py" \b Examples: \ref samples.py "samples.py"
@param samplename name of the sample to be used @param samplename name of the sample to be used
@return id of the grib loaded in memory @return id of the message loaded in memory
@exception GribInternalError @exception GribInternalError
""" """
err, gribid = _internal.grib_c_new_from_samples(0, samplename) err, msgid = _internal.grib_c_new_from_samples(0, samplename)
GRIB_CHECK(err) GRIB_CHECK(err)
return gribid return msgid
@require(gribid_src=int) @require(msgid_src=int)
def grib_clone(gribid_src): def grib_clone(msgid_src):
""" """
@brief Create a copy of a message. @brief Create a copy of a message.
Create a copy of a given message (\em gribid_src) resulting in a new Create a copy of a given message (\em msgid_src) resulting in a new
message in memory (\em gribid_dest) identical to the original one. message in memory (\em msgid_dest) identical to the original one.
\b Examples: \ref grib_clone.py "grib_clone.py" \b Examples: \ref grib_clone.py "grib_clone.py"
@param gribid_src id of grib to be cloned @param msgid_src id of message to be cloned
@return id of clone @return id of clone
@exception GribInternalError @exception GribInternalError
""" """
err, newgribid_src = _internal.grib_c_clone(gribid_src, 0) err, newmsgid_src = _internal.grib_c_clone(msgid_src, 0)
GRIB_CHECK(err) GRIB_CHECK(err)
return newgribid_src return newmsgid_src
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_set_double_array(gribid, key, inarray): def grib_set_double_array(msgid, key, inarray):
""" """
@brief Set the value of the key to a double array. @brief Set the value of the key to a double array.
@ -854,13 +843,13 @@ def grib_set_double_array(gribid, key, inarray):
The elements of the input sequence need to be convertible to a double. The elements of the input sequence need to be convertible to a double.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@param inarray tuple,list,array,numpy.ndarray @param inarray tuple,list,array,numpy.ndarray
@exception GribInternalError @exception GribInternalError
""" """
if with_numpy(): if with_numpy():
GRIB_CHECK(_internal.grib_set_double_ndarray(gribid, key, inarray)) GRIB_CHECK(_internal.grib_set_double_ndarray(msgid, key, inarray))
else: else:
nval = len(inarray) nval = len(inarray)
a = _internal.new_doubleArray(nval) a = _internal.new_doubleArray(nval)
@ -870,36 +859,36 @@ def grib_set_double_array(gribid, key, inarray):
for i in range(nval): for i in range(nval):
_internal.doubleArray_setitem(a, i, inarray[i]) _internal.doubleArray_setitem(a, i, inarray[i])
GRIB_CHECK(_internal.grib_c_set_real8_array(gribid, key, a, s)) GRIB_CHECK(_internal.grib_c_set_real8_array(msgid, key, a, s))
_internal.delete_doubleArray(a) _internal.delete_doubleArray(a)
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_double_array(gribid, key): def grib_get_double_array(msgid, key):
""" """
@brief Get the value of the key as a double array. @brief Get the value of the key as a double array.
If NumPy is enabled, the double array will be stored in a NumPy ndarray. If NumPy is enabled, the double array will be stored in a NumPy ndarray.
Otherwise, Python's native array type will be used. Otherwise, Python's native array type will be used.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@return numpy.ndarray or array @return numpy.ndarray or array
@exception GribInternalError @exception GribInternalError
""" """
if with_numpy(): if with_numpy():
nval = grib_get_size(gribid, key) nval = grib_get_size(msgid, key)
err, result = _internal.grib_get_double_ndarray(gribid, key, nval) err, result = _internal.grib_get_double_ndarray(msgid, key, nval)
GRIB_CHECK(err) GRIB_CHECK(err)
return result return result
else: else:
nval = grib_get_size(gribid, key) nval = grib_get_size(msgid, key)
a = _internal.new_doubleArray(nval) a = _internal.new_doubleArray(nval)
s = _internal.intp() s = _internal.intp()
s.assign(nval) s.assign(nval)
GRIB_CHECK(_internal.grib_c_get_real8_array(gribid, key, a, s)) GRIB_CHECK(_internal.grib_c_get_real8_array(msgid, key, a, s))
result = array("d") result = array("d")
for i in range(nval): for i in range(nval):
@ -909,22 +898,22 @@ def grib_get_double_array(gribid, key):
return result return result
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_string_array(gribid, key): def grib_get_string_array(msgid, key):
""" """
@brief Get the value of the key as an array of strings. @brief Get the value of the key as an array of strings.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@return numpy.ndarray or array @return numpy.ndarray or array
@exception GribInternalError @exception GribInternalError
""" """
nval = grib_get_size(gribid,key) nval = grib_get_size(msgid,key)
a = _internal.new_stringArray(nval) a = _internal.new_stringArray(nval)
s = _internal.sizetp() s = _internal.sizetp()
s.assign(nval) s.assign(nval)
GRIB_CHECK(_internal.grib_c_get_string_array(gribid,key,a,s)) GRIB_CHECK(_internal.grib_c_get_string_array(msgid,key,a,s))
result = list() result = list()
for i in range(nval): for i in range(nval):
@ -934,8 +923,8 @@ def grib_get_string_array(gribid, key):
return result return result
@require(gribid=int,key=str) @require(msgid=int,key=str)
def grib_set_long_array(gribid, key, inarray): def grib_set_long_array(msgid, key, inarray):
""" """
@brief Set the value of the key to an integer array. @brief Set the value of the key to an integer array.
@ -945,13 +934,13 @@ def grib_set_long_array(gribid, key, inarray):
The elements of the input sequence need to be convertible to an int. The elements of the input sequence need to be convertible to an int.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@param inarray tuple,list,python array,numpy array @param inarray tuple,list,python array,numpy array
@exception GribInternalError @exception GribInternalError
""" """
if with_numpy(): if with_numpy():
GRIB_CHECK(_internal.grib_set_long_ndarray(gribid, key, inarray)) GRIB_CHECK(_internal.grib_set_long_ndarray(msgid, key, inarray))
else: else:
nval = len(inarray) nval = len(inarray)
a = _internal.new_longArray(nval) a = _internal.new_longArray(nval)
@ -961,36 +950,36 @@ def grib_set_long_array(gribid, key, inarray):
for i in range(nval): for i in range(nval):
_internal.longArray_setitem(a, i, inarray[i]) _internal.longArray_setitem(a, i, inarray[i])
GRIB_CHECK(_internal.grib_c_set_long_array(gribid, key, a, s)) GRIB_CHECK(_internal.grib_c_set_long_array(msgid, key, a, s))
_internal.delete_longArray(a) _internal.delete_longArray(a)
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_long_array(gribid, key): def grib_get_long_array(msgid, key):
""" """
@brief Get the integer array of values for a key from a grib message. @brief Get the integer array of values for a key from a grib message.
If NumPy is enabled, the integer array will be stored in a NumPy ndarray. If NumPy is enabled, the integer array will be stored in a NumPy ndarray.
Otherwise, Python's native array type will be used. Otherwise, Python's native array type will be used.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@return numpy.ndarray or array @return numpy.ndarray or array
@exception GribInternalError @exception GribInternalError
""" """
if with_numpy(): if with_numpy():
nval = grib_get_size(gribid, key) nval = grib_get_size(msgid, key)
err, result = _internal.grib_get_long_ndarray(gribid, key, nval) err, result = _internal.grib_get_long_ndarray(msgid, key, nval)
GRIB_CHECK(err) GRIB_CHECK(err)
return result return result
else: else:
nval = grib_get_size(gribid, key) nval = grib_get_size(msgid, key)
a = _internal.new_longArray(nval) a = _internal.new_longArray(nval)
s = _internal.intp() s = _internal.intp()
s.assign(nval) s.assign(nval)
GRIB_CHECK(_internal.grib_c_get_long_array(gribid, key, a, s)) GRIB_CHECK(_internal.grib_c_get_long_array(msgid, key, a, s))
result = array("l") result = array("l")
for i in range(nval): for i in range(nval):
@ -1091,7 +1080,8 @@ def grib_index_release(indexid):
@require(indexid=int, key=str) @require(indexid=int, key=str)
def grib_index_get_size(indexid, key): def grib_index_get_size(indexid, key):
""" """
@brief Get the number of distinct values for the index key. The key must belong to the index. @brief Get the number of distinct values for the index key.
The key must belong to the index.
\b Examples: \ref grib_index.py "grib_index.py" \b Examples: \ref grib_index.py "grib_index.py"
@ -1108,7 +1098,8 @@ def grib_index_get_size(indexid, key):
@require(indexid=int, key=str) @require(indexid=int, key=str)
def grib_index_get_long(indexid, key): def grib_index_get_long(indexid, key):
""" """
@brief Get the distinct values of the key in argument contained in the index. The key must belong to the index. @brief 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. 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.
@ -1138,7 +1129,8 @@ def grib_index_get_long(indexid, key):
def grib_index_get_string(indexid, key): def grib_index_get_string(indexid, key):
""" """
@brief Get the distinct values of the key in argument contained in the index. The key must belong to the index. @brief 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. 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.
@ -1146,7 +1138,7 @@ def grib_index_get_string(indexid, key):
@param indexid id of an index created from a file. The index must have been created with the key in argument. @param indexid id of an index created from a file. The index must have been created with the key in argument.
@param key key for wich the values are returned @param key key for wich the values are returned
@param return tuple with values of key in index @return tuple with values of key in index
@exception GribInternalError @exception GribInternalError
""" """
nval = grib_index_get_size(indexid, key) nval = grib_index_get_size(indexid, key)
@ -1170,13 +1162,14 @@ def grib_index_get_string(indexid, key):
@require(iid=int, key=str) @require(iid=int, key=str)
def grib_index_get_double(iid, key): def grib_index_get_double(iid, key):
""" """
@brief Get the distinct values of the key in argument contained in the index. The key must belong to the index. @brief 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. 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.
\b Examples: \ref grib_index.py "grib_index.py" \b Examples: \ref grib_index.py "grib_index.py"
@param indexid id of an index created from a file. The index must have been created with the key in argument. @param iid id of an index created from a file. The index must have been created with the key in argument.
@param key key for wich the values are returned @param key key for wich the values are returned
@return tuple with values of key in index @return tuple with values of key in index
@exception GribInternalError @exception GribInternalError
@ -1198,10 +1191,11 @@ def grib_index_get_double(iid, key):
return tuple(result) return tuple(result)
@require(indexid=int, key=str, val=int) @require(indexid=int, key=str, value=int)
def grib_index_select_long(indexid, key, val): def grib_index_select_long(indexid, key, value):
""" """
@brief Select the message subset with key==value. The value is an integer. @brief 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. 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.
@ -1212,37 +1206,35 @@ def grib_index_select_long(indexid, key, val):
@param value value of the key to select @param value value of the key to select
@exception GribInternalError @exception GribInternalError
""" """
GRIB_CHECK(_internal.grib_c_index_select_long(indexid, key, val)) GRIB_CHECK(_internal.grib_c_index_select_long(indexid, key, value))
@require(iid=int, key=str, val=float) @require(iid=int, key=str, value=float)
def grib_index_select_double(iid, key, val): def grib_index_select_double(iid, key, value):
""" """
@brief Select the message subset with key==value. The value is a double. @brief 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. 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.
\b Examples: \ref grib_index.py "grib_index.py" \b Examples: \ref grib_index.py "grib_index.py"
@param indexid id of an index created from a file. The index must have been created with the key in argument. @param iid id of an index created from a file. The index must have been created with the key in argument.
@param key key to be selected @param key key to be selected
@param value value of the key to select @param value value of the key to select
@exception GribInternalError @exception GribInternalError
""" """
GRIB_CHECK(_internal.grib_c_index_select_real8(iid, key, val)) GRIB_CHECK(_internal.grib_c_index_select_real8(iid, key, value))
@require(indexid=int, key=str, val=str) @require(indexid=int, key=str, value=str)
def grib_index_select_string(indexid, key, val): def grib_index_select_string(indexid, key, value):
""" """
@brief Select the message subset with key==value. The value is a integer. @brief 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. 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.
In case of error, if the status parameter (optional) is not given, the program will
exit with an error message.\n Otherwise the error message can be
gathered with @ref grib_get_error_string.
\b Examples: \ref grib_index.py "grib_index.py" \b Examples: \ref grib_index.py "grib_index.py"
@param indexid id of an index created from a file. The index must have been created with the key in argument. @param indexid id of an index created from a file. The index must have been created with the key in argument.
@ -1250,7 +1242,7 @@ def grib_index_select_string(indexid, key, val):
@param value value of the key to select @param value value of the key to select
@exception GribInternalError @exception GribInternalError
""" """
GRIB_CHECK(_internal.grib_c_index_select_string(indexid, key, val)) GRIB_CHECK(_internal.grib_c_index_select_string(indexid, key, value))
def grib_new_from_index(indexid): def grib_new_from_index(indexid):
@ -1260,12 +1252,12 @@ def grib_new_from_index(indexid):
All the keys belonging to the index must be selected before calling this function. 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. 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 it will be available until @ref grib_release is called. The message can be accessed through its gribid and will be available until @ref grib_release is called.
\b Examples: \ref grib_index.py "grib_index.py" \b Examples: \ref grib_index.py "grib_index.py"
@param indexid id of an index created from a file. @param indexid id of an index created from a file.
@return id of the grib loaded in memory or None if end of index @return id of the message loaded in memory or None if end of index
@exception GribInternalError @exception GribInternalError
""" """
err, gribid = _internal.grib_c_new_from_index(indexid, 0) err, gribid = _internal.grib_c_new_from_index(indexid, 0)
@ -1279,30 +1271,30 @@ def grib_new_from_index(indexid):
return gribid return gribid
@require(gribid=int) @require(msgid=int)
def grib_get_message_size(gribid): def grib_get_message_size(msgid):
""" """
@brief Get the size of a coded message. @brief Get the size of a coded message.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@return size in bytes of the message @return size in bytes of the message
@exception GribInternalError @exception GribInternalError
""" """
err, value = _internal.grib_c_get_message_size(gribid) err, value = _internal.grib_c_get_message_size(msgid)
GRIB_CHECK(err) GRIB_CHECK(err)
return value return value
@require(gribid=int) @require(msgid=int)
def grib_get_message_offset(gribid): def grib_get_message_offset(msgid):
""" """
@brief Get the offset of a coded message. @brief Get the offset of a coded message.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@return offset in bytes of the message @return offset in bytes of the message
@exception GribInternalError @exception GribInternalError
""" """
err, value = _internal.grib_c_get_message_offset(gribid) err, value = _internal.grib_c_get_message_offset(msgid)
GRIB_CHECK(err) GRIB_CHECK(err)
return value return value
@ -1386,8 +1378,8 @@ def grib_get_elements(gribid, key, indexes):
return result return result
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_set_missing(gribid, key): def grib_set_missing(msgid, key):
""" """
@brief Set as missing the value for a key in a grib message. @brief Set as missing the value for a key in a grib message.
@ -1396,11 +1388,11 @@ def grib_set_missing(gribid, key):
\b Examples: \ref set_missing.py "set_missing.py" \b Examples: \ref set_missing.py "set_missing.py"
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@exception GribInternalError @exception GribInternalError
""" """
GRIB_CHECK(_internal.grib_c_set_missing(gribid, key)) GRIB_CHECK(_internal.grib_c_set_missing(msgid, key))
@require(gribid=int) @require(gribid=int)
@ -1442,8 +1434,8 @@ def grib_set_key_vals(gribid, key_vals):
GRIB_CHECK(_internal.grib_c_set_key_vals(gribid, key_vals_str)) GRIB_CHECK(_internal.grib_c_set_key_vals(gribid, key_vals_str))
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_is_missing(gribid, key): def grib_is_missing(msgid, key):
""" """
@brief Check if the value of a key is MISSING. @brief Check if the value of a key is MISSING.
@ -1452,26 +1444,26 @@ def grib_is_missing(gribid, key):
The value of a key MISSING has a special significance and that can be read about The value of a key MISSING has a special significance and that can be read about
in the WMO documentation. in the WMO documentation.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@return 0->not missing, 1->missing @return 0->not missing, 1->missing
@exception GribInternalError @exception GribInternalError
""" """
err, value = _internal.grib_c_is_missing(gribid, key) err, value = _internal.grib_c_is_missing(msgid, key)
GRIB_CHECK(err) GRIB_CHECK(err)
return value return value
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_is_defined(gribid, key): def grib_is_defined(msgid, key):
""" """
@brief Check if a key is defined (exists) @brief Check if a key is defined (exists)
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key key name @param key key name
@return 0->not defined, 1->defined @return 0->not defined, 1->defined
@exception GribInternalError @exception GribInternalError
""" """
err, value = _internal.grib_c_is_defined(gribid, key) err, value = _internal.grib_c_is_defined(msgid, key)
GRIB_CHECK(err) GRIB_CHECK(err)
return value return value
@ -1545,8 +1537,8 @@ def grib_get_native_type(gribid, key):
return None return None
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get(gribid, key, ktype=None): def grib_get(msgid, key, ktype=None):
""" """
@brief Get the value of a key in a grib message. @brief Get the value of a key in a grib message.
@ -1554,34 +1546,34 @@ def grib_get(gribid, key, ktype=None):
The type of value returned can be forced by using the type argument of the 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. function. The type argument can be int, float or str.
The \em gribid references a grib message loaded in memory. The \em msgid references a grib message loaded in memory.
\b Examples: \ref grib_get_keys.py "grib_get_keys.py", \ref print_data.py "print_data.py" \b Examples: \ref grib_get_keys.py "grib_get_keys.py", \ref print_data.py "print_data.py"
@see grib_new_from_file, grib_release, grib_set @see grib_new_from_file, grib_release, grib_set
@param gribid id of the grib loaded in memory @param msgid id of the grib loaded in memory
@param key key name @param key key name
@param ktype the type we want the output in (int, float or str), native type if not specified @param ktype the type we want the output in (int, float or str), native type if not specified
@return scalar value of key as int, float or str @return scalar value of key as int, float or str
@exception GribInternalError @exception GribInternalError
""" """
if ktype is None: if ktype is None:
ktype = grib_get_native_type(gribid, key) ktype = grib_get_native_type(msgid, key)
result = None result = None
if ktype is int: if ktype is int:
result = grib_get_long(gribid, key) result = grib_get_long(msgid, key)
elif ktype is float: elif ktype is float:
result = grib_get_double(gribid, key) result = grib_get_double(msgid, key)
elif ktype is str: elif ktype is str:
result = grib_get_string(gribid, key) result = grib_get_string(msgid, key)
return result return result
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_get_array(gribid, key, ktype=None): def grib_get_array(msgid, key, ktype=None):
""" """
@brief Get the contents of an array key. @brief Get the contents of an array key.
@ -1590,22 +1582,22 @@ def grib_get_array(gribid, key, ktype=None):
The type of value returned can be forced by using the type argument of the function. The type of value returned can be forced by using the type argument of the function.
The type argument can be int or float. The type argument can be int or float.
@param gribid id of the grib loaded in memory @param msgid id of the message loaded in memory
@param key the key to get the value for @param key the key to get the value for
@param ktype the type we want the output in (can be int or float), native type if not specified @param ktype the type we want the output in (can be int or float), native type if not specified
@return numpy.ndarray or array @return numpy.ndarray or array
@exception GribInternalError @exception GribInternalError
""" """
if ktype is None: if ktype is None:
ktype = grib_get_native_type(gribid, key) ktype = grib_get_native_type(msgid, key)
result = None result = None
if ktype is int: if ktype is int:
result = grib_get_long_array(gribid, key) result = grib_get_long_array(msgid, key)
elif ktype is float: elif ktype is float:
result = grib_get_double_array(gribid, key) result = grib_get_double_array(msgid, key)
elif ktype is str: elif ktype is str:
result = grib_get_string_array(gribid, key) result = grib_get_string_array(msgid, key)
return result return result
@ -1647,8 +1639,8 @@ def grib_set_values(gribid, values):
grib_set_double_array(gribid, "values", values) grib_set_double_array(gribid, "values", values)
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_set(gribid, key, value): def grib_set(msgid, key, value):
""" """
@brief Set the value for a scalar key in a grib message. @brief Set the value for a scalar key in a grib message.
@ -1658,23 +1650,23 @@ def grib_set(gribid, key, value):
@see grib_new_from_file, grib_release, grib_get @see grib_new_from_file, grib_release, grib_get
@param gribid id of the grib loaded in memory @param msgid id of the grib loaded in memory
@param key key name @param key key name
@param value scalar value to set for key @param value scalar value to set for key
@exception GribInternalError @exception GribInternalError
""" """
if isinstance(value, int): if isinstance(value, int):
grib_set_long(gribid, key, value) grib_set_long(msgid, key, value)
elif isinstance(value, float): elif isinstance(value, float):
grib_set_double(gribid, key, value) grib_set_double(msgid, key, value)
elif isinstance(value, str): elif isinstance(value, str):
grib_set_string(gribid, key, value) grib_set_string(msgid, key, value)
else: else:
raise GribInternalError("Invalid type of value when setting key '%s'." % key) raise GribInternalError("Invalid type of value when setting key '%s'." % key)
@require(gribid=int, key=str) @require(msgid=int, key=str)
def grib_set_array(gribid, key, value): def grib_set_array(msgid, key, value):
""" """
@brief Set the value for an array key in a grib message. @brief Set the value for an array key in a grib message.
@ -1688,7 +1680,7 @@ def grib_set_array(gribid, key, value):
before extracting its data and length. This is possible as NumPy before extracting its data and length. This is possible as NumPy
allows the construction of arrays from arbitrary python sequences. allows the construction of arrays from arbitrary python sequences.
@param gribid id of the grib loaded in memory @param msgid id of the grib loaded in memory
@param key key name @param key key name
@param value array value to set for key @param value array value to set for key
@exception GribInternalError @exception GribInternalError
@ -1701,9 +1693,9 @@ def grib_set_array(gribid, key, value):
pass pass
if isinstance(val0, float): if isinstance(val0, float):
grib_set_double_array(gribid, key, value) grib_set_double_array(msgid, key, value)
elif isinstance(val0, int): elif isinstance(val0, int):
grib_set_long_array(gribid, key, value) grib_set_long_array(msgid, key, value)
else: else:
raise GribInternalError("Invalid type of value when setting key '%s'." % key) raise GribInternalError("Invalid type of value when setting key '%s'." % key)
@ -1711,12 +1703,14 @@ def grib_set_array(gribid, key, value):
@require(indexid=int, key=str) @require(indexid=int, key=str)
def grib_index_get(indexid, key, ktype=str): def grib_index_get(indexid, key, ktype=str):
""" """
@brief Get the distinct values of an index key. The key must belong to the index. @brief Get the distinct values of an index key.
The key must belong to the index.
\b Examples: \ref grib_index.py "grib_index.py" \b Examples: \ref grib_index.py "grib_index.py"
@param indexid id of an index created from a file. The index must have been created on the given key. @param indexid id of an index created from a file. The index must have been created on the given key.
@param key key for which the values are returned @param key key for which the values are returned
@param ktype the type we want the output in (int, float or str), str if not specified
@return array of values @return array of values
@exception GribInternalError @exception GribInternalError
""" """
@ -1835,20 +1829,20 @@ def grib_get_api_version():
__version__ = grib_get_api_version() __version__ = grib_get_api_version()
@require(gribid=int) @require(msgid=int)
def grib_get_message(gribid): def grib_get_message(msgid):
""" """
@brief Get the binary message. @brief Get the binary message.
Returns the binary string message associated with the grib identified by gribid. Returns the binary string message associated with the grib identified by msgid.
@see grib_new_from_message @see grib_new_from_message
@param gribid id of the grib loaded in memory @param msgid id of the grib loaded in memory
@return binary string message associated with gribid @return binary string message associated with msgid
@exception GribInternalError @exception GribInternalError
""" """
error, message = _internal.grib_c_get_message(gribid) error, message = _internal.grib_c_get_message(msgid)
GRIB_CHECK(error) GRIB_CHECK(error)
return message return message
@ -1863,12 +1857,12 @@ def grib_new_from_message(message):
@see grib_get_message @see grib_get_message
@param message binary string message @param message binary string message
@return gribid of the newly created grib message @return msgid of the newly created grib message
@exception GribInternalError @exception GribInternalError
""" """
error, gribid = _internal.grib_c_new_from_message(0, message, len(message)) error, msgid = _internal.grib_c_new_from_message(0, message, len(message))
GRIB_CHECK(error) GRIB_CHECK(error)
return gribid return msgid
@require(defs_path=str) @require(defs_path=str)