wcps.service¶
Execute a WCPS query on a WCPS server, and save/return the result.
Attributes¶
Default timeout to establish a connection to the WCPS service: 10 seconds. |
|
Default timeout to wait for a query to execute: 10 minutes. |
Classes¶
A list of possible WCPS result types. |
|
Encapsulates a result from executing a WCPS query. |
|
Establish a connection to a WCPS service, send queries and retrieve results. |
Module Contents¶
- DEFAULT_CONN_TIMEOUT = 10[source]¶
Default timeout to establish a connection to the WCPS service: 10 seconds.
- class WCPSResultType[source]¶
Bases:
wcps.model.StrEnum
A list of possible WCPS result types.
Initialize self. See help(type(self)) for accurate signature.
- class WCPSResult[source]¶
Encapsulates a result from executing a WCPS query.
- value: any[source]¶
The result value: a scalar or list of scalars, a JSON list, or an array (encoded or numpy).
- type: WCPSResultType[source]¶
The result type.
- class Service(endpoint, username=None, password=None)[source]¶
Establish a connection to a WCPS service, send queries and retrieve results.
- Parameters:
endpoint – the WCPS server endpoint URL, e.g. https://ows.rasdaman.org/rasdaman/ows
username – optional username for basic authentication to the WCPS server
password – optional password for basic authentication to the WCPS server
Example usage:
service = Service("https://ows.rasdaman.org/rasdaman/ows") query = Datacube("NIR").encode("PNG") # save the response to a file output.png service.query(query, output_file='output.png') # or get the response object back response = service.query(query)
- execute(wcps_query, convert_to_numpy=False, conn_timeout=DEFAULT_CONN_TIMEOUT, read_timeout=DEFAULT_READ_TIMEOUT)[source]¶
Sends a WCPS query to the service. Depending on the result, it returns:
A single number (int or float) if the result was a single scalar value
A list of numbers (int or float) if the result was a multiband scalar value
A JSON array object if the result was a JSON array (the query did encode to “JSON”)
A string if the result was a CSV array (the query did encode to “CSV”)
A bytes object if the result was a binary data format, such as TIFF, netCDF, PNG.
- Parameters:
wcps_query (Union[str, wcps.model.WCPSExpr]) – the WCPS query to be executed on the server.
convert_to_numpy (bool) – if True an array result encoded to a data format will be automatically converted to a numpy array.
conn_timeout (int) – how long (seconds) to wait for the connection to be established
read_timeout (int) – how long (seconds) to wait for the query to execute
- Returns:
the response object from evaluating the query.
- Raise:
wcps.model.WCPSClientException
if the server returns an error status code.- Return type:
- download(wcps_query, output_file, conn_timeout=DEFAULT_CONN_TIMEOUT, read_timeout=DEFAULT_READ_TIMEOUT)[source]¶
Sends a WCPS query to the service and save the response into an
output_file
.- Parameters:
wcps_query (Union[str, wcps.model.WCPSExpr]) – the WCPS query to be executed on the server.
output_file (str) – a path where the response will be written to.
conn_timeout (int) – how long (seconds) to wait for the connection to be established
read_timeout (int) – how long (seconds) to wait for the query to execute
- Returns:
the response object from evaluating the query.
- Raise:
wcps.model.WCPSClientException
if the server returns an error status code.
- show(query_or_result, conn_timeout=DEFAULT_CONN_TIMEOUT, read_timeout=DEFAULT_READ_TIMEOUT)[source]¶
Displays the evaluation result of a WCPS query.
2D image results are shown with
PIL.Image.Image.show()
.scalar, JSON, and numpy array results are printed to stdout
netCDF results print the Dataset information to stdout
- Parameters:
query_or_result (Union[str, wcps.model.WCPSExpr, WCPSResult]) – If a WCPS query in string or as a
wcps.model.WCPSExpr
object is provided, then it will be executed first with theexecute()
method, and the returned result will be accordingly displayed. If instead aWCPSResult
object is provided, it will be just displayed.conn_timeout (int) – how long (seconds) to wait for the connection to be established
read_timeout (int) – how long (seconds) to wait for the query to execute
- Raise:
wcps.model.WCPSClientException
if the server returns an error status code, or the result cannot be handled.
- execute_raw(wcps_query, conn_timeout=DEFAULT_CONN_TIMEOUT, read_timeout=DEFAULT_READ_TIMEOUT, stream=False)[source]¶
Sends a WCPS query to the service and return the raw
requests.Response
object.The
execute()
anddownload()
are more user-friendly methods that return the response properly interpreted or download to a file.- Parameters:
wcps_query (Union[str, wcps.model.WCPSExpr]) – the WCPS query to be executed on the server.
conn_timeout (int) – how long (seconds) to wait for the connection to be established
read_timeout (int) – how long (seconds) to wait for the query to execute
stream (bool) – allow streaming the query result so it can be downloaded in chunks
- Returns:
the response object from evaluating the query.
- Raise:
wcps.model.WCPSClientException
if the server returns an error status code.- Return type:
- response_to_wcps_result(response, convert_to_numpy=False)[source]¶
Converts a
requests.Response
into aWCPSResult
.- Parameters:
response (requests.Response) – the response to be converted.
convert_to_numpy (bool) – if True an array result encoded to a data format will be automatically converted to a numpy array.
- Returns:
a
WCPSResult
with theWCPSResult.type
set to the response type, and theWCPSResult.value
set to the response value.- Return type: