From e12a686edfbe5a6390a44a30bc78bb53dcc3cd5f Mon Sep 17 00:00:00 2001 From: Shahram Najm Date: Wed, 13 Jul 2016 13:47:21 +0100 Subject: [PATCH] ECC-200: Python docs updates --- python/gribapi.py | 410 +++++++++++++++++++++++----------------------- 1 file changed, 202 insertions(+), 208 deletions(-) diff --git a/python/gribapi.py b/python/gribapi.py index 7c7084722..3e761d478 100644 --- a/python/gribapi.py +++ b/python/gribapi.py @@ -171,18 +171,9 @@ def gts_new_from_file(fileobj, headers_only=False): """ @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 - 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 headers_only whether or not to load the message with the headers only @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. - 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 - 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 headers_only whether or not to load the message with the headers only @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) 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: return grib_new_from_file(fileobj, headers_only) 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. - 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 \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. - 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 - 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" + \b Examples: \ref bufr_get_keys.py "bufr_get_keys.py" @param fileobj python file object @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. - 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 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() -@require(gribid=int) -def grib_release(gribid): +@require(msgid=int) +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" - @param gribid id of the grib loaded in memory + @param msgid id of the message loaded in memory @exception GribInternalError """ - GRIB_CHECK(_internal.grib_c_release(gribid)) + GRIB_CHECK(_internal.grib_c_release(msgid)) -@require(gribid=int, key=str) -def grib_get_string(gribid, key): +@require(msgid=int, key=str) +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 @return string value of key @exception GribInternalError """ - length = grib_get_string_length(gribid, key) - err, value = _internal.grib_c_get_string(gribid, key, length) + length = grib_get_string_length(msgid, key) + err, value = _internal.grib_c_get_string(msgid, key, length) GRIB_CHECK(err) stpos = value.find('\0') @@ -398,17 +387,17 @@ def grib_get_string(gribid, key): return value -@require(gribid=int, key=str, value=str) -def grib_set_string(gribid, key, value): +@require(msgid=int, key=str, value=str) +def grib_set_string(msgid, key, value): """ @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 value string value @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(): @@ -429,18 +418,18 @@ def grib_gribex_mode_off(): _internal.grib_c_gribex_mode_off() -@require(gribid=int, fileobj=file) -def grib_write(gribid, fileobj): +@require(msgid=int, fileobj=file) +def grib_write(msgid, fileobj): """ @brief Write a message to a file. \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 @exception GribInternalError """ - GRIB_CHECK(_internal.grib_c_write(gribid, fileobj)) + GRIB_CHECK(_internal.grib_c_write(msgid, fileobj)) @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)) -@require(gribid=int, key=str) -def grib_get_size(gribid, key): +@require(msgid=int, key=str) +def grib_get_size(msgid, 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" - @param gribid id of the grib loaded in memory - @param key name of the key + @param msgid id of the message loaded in memory + @param key name of the key @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) return result -@require(gribid=int, key=str) -def grib_get_string_length(gribid, key): +@require(msgid=int, key=str) +def grib_get_string_length(msgid, 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 @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) return result @@ -643,8 +632,8 @@ def grib_iterator_next(iterid): return (lat, lon, value) -@require(gribid=int) -def grib_keys_iterator_new(gribid, namespace=None): +@require(msgid=int) +def grib_keys_iterator_new(msgid, namespace=None): """ @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" - @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) @return keys iterator id to be used in the keys iterator functions @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) return iterid @@ -727,45 +716,45 @@ def grib_keys_iterator_rewind(iterid): GRIB_CHECK(_internal.grib_c_keys_iterator_rewind(iterid)) -@require(gribid=int, key=str) -def grib_get_long(gribid, key): +@require(msgid=int, key=str) +def grib_get_long(msgid, key): """ @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 @return value of key as int @exception GribInternalError """ - err, value = _internal.grib_c_get_long(gribid, key) + err, value = _internal.grib_c_get_long(msgid, key) GRIB_CHECK(err) return value -@require(gribid=int, key=str) -def grib_get_double(gribid, key): +@require(msgid=int, key=str) +def grib_get_double(msgid, key): """ @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 @return value of key as float @exception GribInternalError """ - err, value = _internal.grib_c_get_double(gribid, key) + err, value = _internal.grib_c_get_double(msgid, key) GRIB_CHECK(err) return value -@require(gribid=int, key=str, value=(int, long, float, str)) -def grib_set_long(gribid, key, value): +@require(msgid=int, key=str, value=(int, long, float, str)) +def grib_set_long(msgid, key, value): """ @brief 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. - @param gribid id of the grib loaded in memory + @param msgid id of the message loaded in memory @param key key name @param value value to set @exception GribInternalError,TypeError @@ -778,18 +767,18 @@ def grib_set_long(gribid, key, value): if value > sys.maxint: 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)) -def grib_set_double(gribid, key, value): +@require(msgid=int, key=str, value=(int, long, float, str)) +def grib_set_double(msgid, key, value): """ @brief 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. - @param gribid id of the grib loaded in memory + @param msgid id of the message loaded in memory @param key key name @param value float value to set @exception GribInternalError,TypeError @@ -799,13 +788,13 @@ def grib_set_double(gribid, key, value): except (ValueError, TypeError): 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) 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 by the environment variable ECCODES_SAMPLES_PATH. @@ -814,35 +803,35 @@ def grib_new_from_samples(samplename): \b Examples: \ref samples.py "samples.py" @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 """ - err, gribid = _internal.grib_c_new_from_samples(0, samplename) + err, msgid = _internal.grib_c_new_from_samples(0, samplename) GRIB_CHECK(err) - return gribid + return msgid -@require(gribid_src=int) -def grib_clone(gribid_src): +@require(msgid_src=int) +def grib_clone(msgid_src): """ @brief Create a copy of a message. - Create a copy of a given message (\em gribid_src) resulting in a new - message in memory (\em gribid_dest) identical to the original one. + Create a copy of a given message (\em msgid_src) resulting in a new + message in memory (\em msgid_dest) identical to the original one. \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 @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) - return newgribid_src + return newmsgid_src -@require(gribid=int, key=str) -def grib_set_double_array(gribid, key, inarray): +@require(msgid=int, key=str) +def grib_set_double_array(msgid, key, inarray): """ @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. - @param gribid id of the grib loaded in memory - @param key key name - @param inarray tuple,list,array,numpy.ndarray + @param msgid id of the message loaded in memory + @param key key name + @param inarray tuple,list,array,numpy.ndarray @exception GribInternalError """ if with_numpy(): - GRIB_CHECK(_internal.grib_set_double_ndarray(gribid, key, inarray)) + GRIB_CHECK(_internal.grib_set_double_ndarray(msgid, key, inarray)) else: nval = len(inarray) a = _internal.new_doubleArray(nval) @@ -870,36 +859,36 @@ def grib_set_double_array(gribid, key, inarray): for i in range(nval): _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) -@require(gribid=int, key=str) -def grib_get_double_array(gribid, key): +@require(msgid=int, key=str) +def grib_get_double_array(msgid, key): """ @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. Otherwise, Python's native array type will be used. - @param gribid id of the grib loaded in memory - @param key key name + @param msgid id of the message loaded in memory + @param key key name @return numpy.ndarray or array @exception GribInternalError """ if with_numpy(): - nval = grib_get_size(gribid, key) - err, result = _internal.grib_get_double_ndarray(gribid, key, nval) + nval = grib_get_size(msgid, key) + err, result = _internal.grib_get_double_ndarray(msgid, key, nval) GRIB_CHECK(err) return result else: - nval = grib_get_size(gribid, key) + nval = grib_get_size(msgid, key) a = _internal.new_doubleArray(nval) s = _internal.intp() 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") for i in range(nval): @@ -909,22 +898,22 @@ def grib_get_double_array(gribid, key): return result -@require(gribid=int, key=str) -def grib_get_string_array(gribid, key): +@require(msgid=int, key=str) +def grib_get_string_array(msgid, key): """ @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 @return numpy.ndarray or array @exception GribInternalError """ - nval = grib_get_size(gribid,key) + nval = grib_get_size(msgid,key) a = _internal.new_stringArray(nval) s = _internal.sizetp() 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() for i in range(nval): @@ -934,8 +923,8 @@ def grib_get_string_array(gribid, key): return result -@require(gribid=int,key=str) -def grib_set_long_array(gribid, key, inarray): +@require(msgid=int,key=str) +def grib_set_long_array(msgid, key, inarray): """ @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. - @param gribid id of the grib loaded in memory + @param msgid id of the message loaded in memory @param key key name @param inarray tuple,list,python array,numpy array @exception GribInternalError """ if with_numpy(): - GRIB_CHECK(_internal.grib_set_long_ndarray(gribid, key, inarray)) + GRIB_CHECK(_internal.grib_set_long_ndarray(msgid, key, inarray)) else: nval = len(inarray) a = _internal.new_longArray(nval) @@ -961,36 +950,36 @@ def grib_set_long_array(gribid, key, inarray): for i in range(nval): _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) -@require(gribid=int, key=str) -def grib_get_long_array(gribid, key): +@require(msgid=int, key=str) +def grib_get_long_array(msgid, key): """ @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. 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 @return numpy.ndarray or array @exception GribInternalError """ if with_numpy(): - nval = grib_get_size(gribid, key) - err, result = _internal.grib_get_long_ndarray(gribid, key, nval) + nval = grib_get_size(msgid, key) + err, result = _internal.grib_get_long_ndarray(msgid, key, nval) GRIB_CHECK(err) return result else: - nval = grib_get_size(gribid, key) + nval = grib_get_size(msgid, key) a = _internal.new_longArray(nval) s = _internal.intp() 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") for i in range(nval): @@ -1091,7 +1080,8 @@ def grib_index_release(indexid): @require(indexid=int, key=str) 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" @@ -1108,7 +1098,8 @@ def grib_index_get_size(indexid, key): @require(indexid=int, key=str) 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. @@ -1138,7 +1129,8 @@ def grib_index_get_long(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. @@ -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 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 """ nval = grib_index_get_size(indexid, key) @@ -1170,14 +1162,15 @@ def grib_index_get_string(indexid, key): @require(iid=int, key=str) 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. \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 key key for wich the values are returned + @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 @return tuple with values of key in index @exception GribInternalError """ @@ -1198,10 +1191,11 @@ def grib_index_get_double(iid, key): return tuple(result) -@require(indexid=int, key=str, val=int) -def grib_index_select_long(indexid, key, val): +@require(indexid=int, key=str, value=int) +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. @@ -1212,37 +1206,35 @@ def grib_index_select_long(indexid, key, val): @param value value of the key to select @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) -def grib_index_select_double(iid, key, val): +@require(iid=int, key=str, value=float) +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. \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 value value of the key to select @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) -def grib_index_select_string(indexid, key, val): +@require(indexid=int, key=str, value=str) +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. - 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" @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 @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): @@ -1260,12 +1252,12 @@ def grib_new_from_index(indexid): 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 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" @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 """ err, gribid = _internal.grib_c_new_from_index(indexid, 0) @@ -1279,30 +1271,30 @@ def grib_new_from_index(indexid): return gribid -@require(gribid=int) -def grib_get_message_size(gribid): +@require(msgid=int) +def grib_get_message_size(msgid): """ @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 @exception GribInternalError """ - err, value = _internal.grib_c_get_message_size(gribid) + err, value = _internal.grib_c_get_message_size(msgid) GRIB_CHECK(err) return value -@require(gribid=int) -def grib_get_message_offset(gribid): +@require(msgid=int) +def grib_get_message_offset(msgid): """ @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 @exception GribInternalError """ - err, value = _internal.grib_c_get_message_offset(gribid) + err, value = _internal.grib_c_get_message_offset(msgid) GRIB_CHECK(err) return value @@ -1386,8 +1378,8 @@ def grib_get_elements(gribid, key, indexes): return result -@require(gribid=int, key=str) -def grib_set_missing(gribid, key): +@require(msgid=int, key=str) +def grib_set_missing(msgid, key): """ @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" - @param gribid id of the grib loaded in memory - @param key key name + @param msgid id of the message loaded in memory + @param key key name @exception GribInternalError """ - GRIB_CHECK(_internal.grib_c_set_missing(gribid, key)) + GRIB_CHECK(_internal.grib_c_set_missing(msgid, key)) @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)) -@require(gribid=int, key=str) -def grib_is_missing(gribid, key): +@require(msgid=int, key=str) +def grib_is_missing(msgid, key): """ @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 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 @return 0->not missing, 1->missing @exception GribInternalError """ - err, value = _internal.grib_c_is_missing(gribid, key) + err, value = _internal.grib_c_is_missing(msgid, key) GRIB_CHECK(err) return value -@require(gribid=int, key=str) -def grib_is_defined(gribid, key): +@require(msgid=int, key=str) +def grib_is_defined(msgid, key): """ @brief Check if a key is defined (exists) - @param gribid id of the grib loaded in memory - @param key key name - @return 0->not defined, 1->defined - @exception GribInternalError + @param msgid id of the message loaded in memory + @param key key name + @return 0->not defined, 1->defined + @exception GribInternalError """ - err, value = _internal.grib_c_is_defined(gribid, key) + err, value = _internal.grib_c_is_defined(msgid, key) GRIB_CHECK(err) return value @@ -1545,8 +1537,8 @@ def grib_get_native_type(gribid, key): return None -@require(gribid=int, key=str) -def grib_get(gribid, key, ktype=None): +@require(msgid=int, key=str) +def grib_get(msgid, key, ktype=None): """ @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 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" @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 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 @exception GribInternalError """ if ktype is None: - ktype = grib_get_native_type(gribid, key) + ktype = grib_get_native_type(msgid, key) result = None if ktype is int: - result = grib_get_long(gribid, key) + result = grib_get_long(msgid, key) elif ktype is float: - result = grib_get_double(gribid, key) + result = grib_get_double(msgid, key) elif ktype is str: - result = grib_get_string(gribid, key) + result = grib_get_string(msgid, key) return result -@require(gribid=int, key=str) -def grib_get_array(gribid, key, ktype=None): +@require(msgid=int, key=str) +def grib_get_array(msgid, key, ktype=None): """ @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 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 ktype the type we want the output in (can be int or float), native type if not specified @return numpy.ndarray or array @exception GribInternalError """ if ktype is None: - ktype = grib_get_native_type(gribid, key) + ktype = grib_get_native_type(msgid, key) result = None if ktype is int: - result = grib_get_long_array(gribid, key) + result = grib_get_long_array(msgid, key) elif ktype is float: - result = grib_get_double_array(gribid, key) + result = grib_get_double_array(msgid, key) elif ktype is str: - result = grib_get_string_array(gribid, key) + result = grib_get_string_array(msgid, key) return result @@ -1647,8 +1639,8 @@ def grib_set_values(gribid, values): grib_set_double_array(gribid, "values", values) -@require(gribid=int, key=str) -def grib_set(gribid, key, value): +@require(msgid=int, key=str) +def grib_set(msgid, key, value): """ @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 - @param gribid id of the grib loaded in memory + @param msgid id of the grib loaded in memory @param key key name @param value scalar value to set for key @exception GribInternalError """ if isinstance(value, int): - grib_set_long(gribid, key, value) + grib_set_long(msgid, key, value) elif isinstance(value, float): - grib_set_double(gribid, key, value) + grib_set_double(msgid, key, value) elif isinstance(value, str): - grib_set_string(gribid, key, value) + grib_set_string(msgid, key, value) else: raise GribInternalError("Invalid type of value when setting key '%s'." % key) -@require(gribid=int, key=str) -def grib_set_array(gribid, key, value): +@require(msgid=int, key=str) +def grib_set_array(msgid, key, value): """ @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 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 value array value to set for key @exception GribInternalError @@ -1701,9 +1693,9 @@ def grib_set_array(gribid, key, value): pass if isinstance(val0, float): - grib_set_double_array(gribid, key, value) + grib_set_double_array(msgid, key, value) elif isinstance(val0, int): - grib_set_long_array(gribid, key, value) + grib_set_long_array(msgid, key, value) else: 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) 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" @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 ktype the type we want the output in (int, float or str), str if not specified @return array of values @exception GribInternalError """ @@ -1835,20 +1829,20 @@ def grib_get_api_version(): __version__ = grib_get_api_version() -@require(gribid=int) -def grib_get_message(gribid): +@require(msgid=int) +def grib_get_message(msgid): """ @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 - @param gribid id of the grib loaded in memory - @return binary string message associated with gribid + @param msgid id of the grib loaded in memory + @return binary string message associated with msgid @exception GribInternalError """ - error, message = _internal.grib_c_get_message(gribid) + error, message = _internal.grib_c_get_message(msgid) GRIB_CHECK(error) return message @@ -1863,12 +1857,12 @@ def grib_new_from_message(message): @see grib_get_message @param message binary string message - @return gribid of the newly created grib message + @return msgid of the newly created grib message @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) - return gribid + return msgid @require(defs_path=str)