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

Python: Fix docstring errors

This commit is contained in:
Shahram Najm 2017-03-13 15:08:17 +00:00
parent a88506eab0
commit 84385844c9
1 changed files with 108 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
python/gribapi/gribapi.py
View File

@ -66,7 +66,9 @@ no_type_checks = os.environ.get('GRIB_API_PYTHON_NO_TYPE_CHECKS') is not None
# modified to support multiple allowed types and all types in the same decorator call
# This returns a decorator. _params_ is the dict with the type specs
def require(**_params_):
# The actual decorator. Receives the target function in _func_
"""
The actual decorator. Receives the target function in _func_
"""
def check_types(_func_, _params_=_params_):
if no_type_checks:
return _func_
@ -124,7 +126,7 @@ class Bunch(dict):
@require(errid=int)
def GRIB_CHECK(errid):
"""
Utility function checking the GRIB API error code and raising
Utility function checking the ecCodes error code and raising
an error if that was set.
@param errid the C interface error id to check
@ -145,17 +147,17 @@ def gts_new_from_file(fileobj, headers_only=False):
@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
@return id of the GTS loaded in memory
@exception GribInternalError
"""
err, gribid = _internal.grib_c_new_gts_from_file(fileobj, headers_only, 0)
err, gtsid = _internal.grib_c_new_gts_from_file(fileobj, headers_only, 0)
if err:
if err == _internal.GRIB_END_OF_FILE:
return None
else:
GRIB_CHECK(err)
else:
return gribid
return gtsid
@require(fileobj=file)
@ -168,17 +170,17 @@ def metar_new_from_file(fileobj, headers_only=False):
@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
@return id of the METAR loaded in memory
@exception GribInternalError
"""
err, gribid = _internal.grib_c_new_metar_from_file(fileobj, headers_only, 0)
err, metarid = _internal.grib_c_new_metar_from_file(fileobj, headers_only, 0)
if err:
if err == _internal.GRIB_END_OF_FILE:
return None
else:
GRIB_CHECK(err)
else:
return gribid
return metarid
@require(fileobj=file, product_kind=int)
@ -225,14 +227,14 @@ def any_new_from_file(fileobj, headers_only=False):
@return id of the message loaded in memory
@exception GribInternalError
"""
err, gribid = _internal.grib_c_new_any_from_file(fileobj, headers_only, 0)
err, msgid = _internal.grib_c_new_any_from_file(fileobj, headers_only, 0)
if err:
if err == _internal.GRIB_END_OF_FILE:
return None
else:
GRIB_CHECK(err)
else:
return gribid
return msgid
@require(fileobj=file)
@ -247,23 +249,23 @@ def bufr_new_from_file(fileobj, headers_only=False):
@param fileobj python file object
@param headers_only whether or not to load the message with the headers only
@return id of the BUFR loaded in memory
@return id of the BUFR loaded in memory
@exception GribInternalError
"""
err, gribid = _internal.grib_c_new_bufr_from_file(fileobj, headers_only, 0)
err, bufrid = _internal.grib_c_new_bufr_from_file(fileobj, headers_only, 0)
if err:
if err == _internal.GRIB_END_OF_FILE:
return None
else:
GRIB_CHECK(err)
else:
return gribid
return bufrid
@require(fileobj=file)
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 will be available\n
until @ref grib_release is called.\n
@ -279,7 +281,7 @@ def grib_new_from_file(fileobj, headers_only=False):
@param fileobj python file object
@param headers_only whether or not to load the message with the headers only
@return id of the grib loaded in memory
@return id of the grib loaded in memory
@exception GribInternalError
"""
err, gribid = _internal.grib_c_new_from_file(fileobj, 0, headers_only)
@ -300,7 +302,7 @@ def grib_count_in_file(fileobj):
\b Examples: \ref count_messages.py "count_messages.py"
@param fileobj python file object
@return number of messages in the file
@return number of messages in the file
@exception GribInternalError
"""
err, num = _internal.grib_c_count_in_file(fileobj)
@ -310,7 +312,7 @@ def grib_count_in_file(fileobj):
def grib_multi_support_on():
"""
@brief Turn on the support for multiple fields in a single message.
@brief Turn on the support for multiple fields in a single GRIB message.
@exception GribInternalError
"""
@ -319,7 +321,7 @@ def grib_multi_support_on():
def grib_multi_support_off():
"""
@brief Turn off the support for multiple fields in a single message.
@brief Turn off the support for multiple fields in a single GRIB message.
@exception GribInternalError
"""
@ -329,7 +331,7 @@ def grib_multi_support_off():
@require(msgid=int)
def grib_release(msgid):
"""
@brief Free the memory for the message referred as msgid.
@brief Free the memory for the message referred to by msgid.
\b Examples: \ref grib_get_keys.py "grib_get_keys.py"
@ -346,7 +348,7 @@ def grib_get_string(msgid, key):
@param msgid id of the message loaded in memory
@param key key name
@return string value of key
@return string value of key
@exception GribInternalError
"""
length = grib_get_string_length(msgid, key)
@ -363,11 +365,11 @@ def grib_get_string(msgid, key):
@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.
@brief Set the value for a string key in a message.
@param msgid id of the message loaded in memory
@param key key name
@param value string value
@param key key name
@param value string value
@exception GribInternalError
"""
GRIB_CHECK(_internal.grib_c_set_string(msgid, key, value, len(value)))
@ -375,7 +377,7 @@ def grib_set_string(msgid, key, value):
def grib_gribex_mode_on():
"""
@brief Turn on the compatibility mode with gribex.
@brief Turn on the compatibility mode with GRIBEX.
@exception GribInternalError
"""
@ -384,7 +386,7 @@ def grib_gribex_mode_on():
def grib_gribex_mode_off():
"""
@brief Turn off the compatibility mode with gribex.
@brief Turn off the compatibility mode with GRIBEX.
@exception GribInternalError
"""
@ -408,11 +410,11 @@ def grib_write(msgid, fileobj):
@require(multigribid=int, fileobj=file)
def grib_multi_write(multigribid, fileobj):
"""
@brief Write a multi field message to a file.
@brief Write a multi-field GRIB message to a file.
\b Examples: \ref grib_multi_write.py "grib_multi_write.py"
@param multigribid id of the multi field grib loaded in memory
@param multigribid id of the multi-field grib loaded in memory
@param fileobj python file object
@exception GribInternalError
"""
@ -422,17 +424,17 @@ def grib_multi_write(multigribid, fileobj):
@require(ingribid=int, startsection=int, multigribid=int)
def grib_multi_append(ingribid, startsection, multigribid):
"""
@brief Append a single field grib message to a multi field grib message.
@brief 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.
are copied from the input single message to the multi-field output grib.
\b Examples: \ref grib_multi_write.py "grib_multi_write.py"
@param ingribid id of the input single grib
@param ingribid id of the input single-field GRIB
@param startsection starting from startsection (included) all the sections are copied
from the input single grib to the output multi grib
@param multigribid id of the output multi filed grib
from the input single grib to the output multi-field grib
@param multigribid id of the output multi-field GRIB
@exception GribInternalError
"""
GRIB_CHECK(_internal.grib_c_multi_append(ingribid, startsection, multigribid))
@ -460,7 +462,7 @@ def grib_get_string_length(msgid, key):
@brief Get the length of the string version of a key.
@param msgid id of the message loaded in memory
@param key name of the key
@param key name of the key
@exception GribInternalError
"""
err, result = _internal.grib_c_get_string_length(msgid, key)
@ -556,16 +558,16 @@ def grib_skip_function(iterid):
@require(gribid=int, mode=int)
def grib_iterator_new(gribid, mode):
"""
@brief Create a new geoiterator for the given message, using its geometry and values.
@brief Create a new geoiterator for the given GRIB message, using its geometry and values.
The geoiterator can be used to go through all the geopoints in a message and
The geoiterator can be used to go through all the geopoints in a GRIB message and
retrieve the values corresponding to those geopoints.
\b Examples: \ref grib_iterator.py "grib_iterator.py"
@param gribid id of the grib loaded in memory
@param gribid id of the GRIB loaded in memory
@param mode flags for future use
@return geoiterator id
@return geoiterator id
"""
err, iterid = _internal.grib_c_iterator_new(gribid, mode)
GRIB_CHECK(err)
@ -592,8 +594,8 @@ def grib_iterator_next(iterid):
\b Examples: \ref grib_iterator.py "grib_iterator.py"
@param iterid geoiterator id
@return tuple with the latitude, longitude and value
@param iterid geoiterator id
@return tuple with the latitude, longitude and value
@exception GribInternalError
"""
err, lat, lon, value = _internal.grib_c_iterator_next(iterid)
@ -728,7 +730,7 @@ def codes_bufr_keys_iterator_next(iterid):
@require(iterid=int)
def codes_bufr_keys_iterator_delete(iterid):
"""
@brief Delete a keys iterator and free memory.
@brief Delete a BUFR keys iterator and free memory.
\b Examples: \ref bufr_keys_iterator.py "bufr_keys_iterator.py"
@ -769,11 +771,11 @@ def codes_bufr_keys_iterator_rewind(iterid):
@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.
@brief Get the value of a key in a message as an integer.
@param msgid id of the message loaded in memory
@param key key name
@return value of key as int
@return value of key as int
@exception GribInternalError
"""
err, value = _internal.grib_c_get_long(msgid, key)
@ -784,11 +786,11 @@ def grib_get_long(msgid, 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.
@brief Get the value of a key in a message as a float.
@param msgid id of the message loaded in memory
@param key key name
@return value of key as float
@param key key name
@return value of key as float
@exception GribInternalError
"""
err, value = _internal.grib_c_get_double(msgid, key)
@ -799,14 +801,14 @@ def grib_get_double(msgid, key):
@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.
@brief Set the integer value for a key in a message.
A TypeError exception will be thrown if value cannot be represented
as an integer.
@param msgid id of the message loaded in memory
@param key key name
@param value value to set
@param key key name
@param value value to set
@exception GribInternalError,TypeError
"""
try:
@ -823,7 +825,7 @@ def grib_set_long(msgid, 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.
@brief Set the double value for a key in a message.
A TypeError exception will be thrown if value cannot be represented
as a float.
@ -876,7 +878,7 @@ def grib_new_from_samples(samplename):
\b Examples: \ref grib_samples.py "grib_samples.py"
@param samplename name of the sample to be used
@return id of the message loaded in memory
@return id of the message loaded in memory
@exception GribInternalError
"""
err, msgid = _internal.grib_c_grib_new_from_samples(0, samplename)
@ -931,8 +933,8 @@ def grib_clone(msgid_src):
\b Examples: \ref grib_clone.py "grib_clone.py"
@param msgid_src id of message to be cloned
@return id of clone
@param msgid_src id of message to be cloned
@return id of clone
@exception GribInternalError
"""
err, newmsgid_src = _internal.grib_c_clone(msgid_src, 0)
@ -953,9 +955,9 @@ def grib_set_double_array(msgid, key, inarray):
The elements of the input sequence need to be convertible to a double.
@param msgid id of the message 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
"""
GRIB_CHECK(_internal.grib_set_double_ndarray(msgid, key, inarray))
@ -1048,7 +1050,7 @@ def grib_set_long_array(msgid, key, inarray):
@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.
@brief Get the integer array of values for a key from a message.
@param msgid id of the message loaded in memory
@param key key name
@ -1063,11 +1065,11 @@ def grib_get_long_array(msgid, key):
def grib_multi_new():
"""
@brief Create a new multi field and return its id.
@brief Create a new multi-field GRIB message and return its id.
\b Examples: \ref grib_multi_write.py "grib_multi_write.py"
@return id of the multi field
@return id of the multi-field message
@exception GribInternalError
"""
err, mgid = _internal.grib_c_multi_new()
@ -1078,11 +1080,11 @@ def grib_multi_new():
@require(gribid=int)
def grib_multi_release(gribid):
"""
@brief Release a multi field from memory.
@brief Release a multi-field message from memory.
\b Examples: \ref grib_multi_write.py "grib_multi_write.py"
@param gribid id of the multi field we want to release the memory for
@param gribid id of the multi-field we want to release the memory for
@exception GribInternalError
"""
GRIB_CHECK(_internal.grib_c_multi_release(gribid))
@ -1373,29 +1375,29 @@ def grib_get_message_offset(msgid):
return value
@require(gribid=int, key=str, index=int)
def grib_get_double_element(gribid, key, index):
@require(msgid=int, key=str, index=int)
def grib_get_double_element(msgid, key, index):
"""
@brief Get as double the i-th element of the "key" array.
@param gribid id of the grib loaded in memory
@param msgid id of the message loaded in memory
@param key the key to be searched
@param index zero based index of value to retrieve
@return value
@exception GribInternalError
"""
err, value = _internal.grib_c_get_real8_element(gribid, key, index)
err, value = _internal.grib_c_get_real8_element(msgid, key, index)
GRIB_CHECK(err)
return value
@require(gribid=int, key=str, indexes=(list, tuple))
def grib_get_double_elements(gribid, key, indexes):
@require(msgid=int, key=str, indexes=(list, tuple))
def grib_get_double_elements(msgid, key, indexes):
"""
@brief Get as double array the elements of the "key" array whose indexes are listed in the input array.
@param gribid id of the grib loaded in memory
@param msgid id of the message loaded in memory
@param key the key to be searched
@param indexes list or tuple of indexes
@return numpy.ndarray
@ -1403,17 +1405,17 @@ def grib_get_double_elements(gribid, key, indexes):
"""
nidx = len(indexes)
err, result = _internal.grib_get_double_ndelements(gribid, key, indexes, nidx)
err, result = _internal.grib_get_double_ndelements(msgid, key, indexes, nidx)
GRIB_CHECK(err)
return result
@require(gribid=int, key=str)
def grib_get_elements(gribid, key, indexes):
@require(msgid=int, key=str)
def grib_get_elements(msgid, key, indexes):
"""
@brief Retrieve the elements of the key array for the indexes specified in the input.
@param gribid id of the grib loaded in memory
@param msgid id of the message loaded in memory
@param key the key to be searched
@param indexes single index or a list of indexes
@return numpy.ndarray containing the values of key for the given indexes
@ -1425,7 +1427,7 @@ def grib_get_elements(gribid, key, indexes):
indexes = (indexes,)
nidx = len(indexes)
err, result = _internal.grib_get_double_ndelements(gribid, key, indexes, nidx)
err, result = _internal.grib_get_double_ndelements(msgid, key, indexes, nidx)
GRIB_CHECK(err)
return result
@ -1433,9 +1435,9 @@ def grib_get_elements(gribid, key, indexes):
@require(msgid=int, key=str)
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.
It can be used to set a missing value in the grib header but not in
It can be used to set a missing value in the GRIB header but not in
the data values.
\b Examples: \ref grib_set_missing.py "grib_set_missing.py"
@ -1497,8 +1499,8 @@ def grib_is_missing(msgid, key):
in the WMO documentation.
@param msgid id of the message loaded in memory
@param key key name
@return 0->not missing, 1->missing
@param key key name
@return 0->not missing, 1->missing
@exception GribInternalError
"""
err, value = _internal.grib_c_is_missing(msgid, key)
@ -1569,19 +1571,19 @@ def grib_find_nearest(gribid, inlat, inlon, is_lsm=False, npoints=1):
raise ValueError("Invalid value for npoints. Expecting 1 or 4.")
@require(gribid=int, key=str)
def grib_get_native_type(gribid, key):
@require(msgid=int, key=str)
def grib_get_native_type(msgid, key):
"""
@brief Retrieve the native type of a key.
Possible values can be int, float or string.
@param gribid id of the grib loaded in memory
@param key key we want to find out the type for
@return type of key given as input or None if not determined
@param msgid id of the message loaded in memory
@param key key we want to find out the type for
@return type of key given as input or None if not determined
@exception GribInternalError
"""
err, itype = _internal.grib_c_get_native_type(gribid, key)
err, itype = _internal.grib_c_get_native_type(msgid, key)
GRIB_CHECK(err)
if itype in KEYTYPES:
return KEYTYPES[itype]
@ -1592,21 +1594,21 @@ def grib_get_native_type(gribid, key):
@require(msgid=int, key=str)
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 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 \em msgid references a grib message loaded in memory.
The \em msgid references a message loaded in memory.
\b Examples: \ref grib_get_keys.py "grib_get_keys.py", \ref grib_print_data.py "grib_print_data.py"
@see grib_new_from_file, grib_release, grib_set
@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
@param msgid id of the message 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
"""
@ -1629,8 +1631,8 @@ def grib_get_array(msgid, key, ktype=None):
"""
@brief 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.
For numeric data, the output array will be stored in a NumPy ndarray.
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.
@ -1657,13 +1659,13 @@ def grib_get_array(msgid, key, ktype=None):
@require(gribid=int)
def grib_get_values(gribid):
"""
@brief Retrieve the contents of the 'values' key.
@brief Retrieve the contents of the 'values' key for a GRIB message.
A NumPy ndarray containing the values in the message is returned.
A NumPy ndarray containing the values in the GRIB message is returned.
\b Examples: \ref grib_print_data.py "grib_print_data.py", \ref grib_samples.py "grib_samples.py"
@param gribid id of the grib loaded in memory
@param gribid id of the GRIB loaded in memory
@return numpy.ndarray
@exception GribInternalError
"""
@ -1673,7 +1675,7 @@ def grib_get_values(gribid):
@require(gribid=int)
def grib_set_values(gribid, values):
"""
@brief Set the contents of the 'values' key.
@brief Set the contents of the 'values' key for a GRIB message.
The input array can be a numpy.ndarray or a python sequence like tuple, list, array, ...
@ -1685,7 +1687,7 @@ def grib_set_values(gribid, values):
\b Examples: \ref grib_clone.py "grib_clone.py", \ref grib_samples.py "grib_samples.py"
@param gribid id of the grib loaded in memory
@param gribid id of the GRIB loaded in memory
@param values array of values to set as tuple, list, array or numpy.ndarray
"""
grib_set_double_array(gribid, "values", values)
@ -1694,7 +1696,7 @@ def grib_set_values(gribid, values):
@require(msgid=int, key=str)
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 message.
The input value can be a python int, float or str.
@ -1702,9 +1704,9 @@ def grib_set(msgid, key, value):
@see grib_new_from_file, grib_release, grib_get
@param msgid id of the grib loaded in memory
@param key key name
@param value scalar value to set for key
@param msgid id of the message loaded in memory
@param key key name
@param value scalar value to set for key
@exception GribInternalError
"""
if isinstance(value, int):
@ -1871,9 +1873,9 @@ def grib_gts_header(flag):
def grib_get_api_version():
"""
@brief Get the api version.
@brief Get the API version.
Returns the version of the api as a string in the format "major.minor.revision".
Returns the version of the API as a string in the format "major.minor.revision".
"""
div = lambda v, d: (v / d, v % d)
v = _internal.grib_c_get_api_version()
@ -1891,12 +1893,12 @@ def grib_get_message(msgid):
"""
@brief Get the binary message.
Returns the binary string message associated with the grib identified by msgid.
Returns the binary string message associated with the message identified by msgid.
@see grib_new_from_message
@param msgid id of the grib loaded in memory
@return binary string message associated with msgid
@param msgid id of the message loaded in memory
@return binary string message associated with msgid
@exception GribInternalError
"""
error, message = _internal.grib_c_get_message(msgid)
@ -1907,14 +1909,14 @@ def grib_get_message(msgid):
@require(message=str)
def grib_new_from_message(message):
"""
@brief Create a grib handle from a message in memory.
@brief Create a handle from a message in memory.
Create a new grib message from the input binary string and return its grib id.
Create a new message from the input binary string and return its id.
@see grib_get_message
@param message binary string message
@return msgid of the newly created grib message
@param message binary string message
@return msgid of the newly created message
@exception GribInternalError
"""
error, msgid = _internal.grib_c_new_from_message(0, message, len(message))