wcps.service

Execute a WCPS query on a WCPS server, and save/return the result.

Attributes

DEFAULT_CONN_TIMEOUT	Default timeout to establish a connection to the WCPS service: 10 seconds.
DEFAULT_READ_TIMEOUT	Default timeout to wait for a query to execute: 10 minutes.

Classes

WCPSResultType	A list of possible WCPS result types.
WCPSResult	Encapsulates a result from executing a WCPS query.
Service	Establish a connection to a WCPS service, send queries and retrieve results.

Module Contents

DEFAULT_CONN_TIMEOUT = 10

Default timeout to establish a connection to the WCPS service: 10 seconds.

DEFAULT_READ_TIMEOUT = 600

Default timeout to wait for a query to execute: 10 minutes.

class WCPSResultType

Bases: wcps.model.StrEnum

A list of possible WCPS result types.

Initialize self. See help(type(self)) for accurate signature.

SCALAR = 'scalar'

A scalar value such as 1, 1.55, etc.

MULTIBAND_SCALAR = 'multiband_scalar'

A multiband scalar value is a list of multiple numbers, e.g. [1, 2, 3]

JSON = 'json'

A JSON list

IMAGE = 'image'

An array encoded to an image data format such as TIFF or PNG.

NETCDF = 'netcdf'

An array encoded to NetCDF.

NUMPY = 'numpy'

A numpy array.

ARRAY = 'array'

Generic array type, unknown data format.

class WCPSResult

Encapsulates a result from executing a WCPS query.

value: any

The result value: a scalar or list of scalars, a JSON list, or an array (encoded or numpy).

type: WCPSResultType

The result type.

class Service(endpoint, username=None, password=None)

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)

endpoint

endpoint_wcps

auth = None

execute(wcps_query, convert_to_numpy=False, conn_timeout=DEFAULT_CONN_TIMEOUT, read_timeout=DEFAULT_READ_TIMEOUT)

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:

WCPSResult

download(wcps_query, output_file, conn_timeout=DEFAULT_CONN_TIMEOUT, read_timeout=DEFAULT_READ_TIMEOUT)

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)

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 the execute() method, and the returned result will be accordingly displayed. If instead a WCPSResult 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)

Sends a WCPS query to the service and return the raw requests.Response object.

The execute() and download() 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:

requests.Response

response_to_wcps_result(response, convert_to_numpy=False)

Converts a requests.Response into a WCPSResult.

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 the WCPSResult.type set to the response type, and the WCPSResult.value set to the response value.

Return type:

WCPSResult