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[source]

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

DEFAULT_READ_TIMEOUT = 600[source]

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

class WCPSResultType[source]

Bases: wcps.model.StrEnum

A list of possible WCPS result types.

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

SCALAR = 'scalar'[source]

A scalar value such as 1, 1.55, etc.

MULTIBAND_SCALAR = 'multiband_scalar'[source]

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

JSON = 'json'[source]

A JSON list

IMAGE = 'image'[source]

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

NETCDF = 'netcdf'[source]

An array encoded to NetCDF.

NUMPY = 'numpy'[source]

A numpy array.

ARRAY = 'array'[source]

Generic array type, unknown data format.

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)
endpoint[source]
endpoint_wcps[source]
auth = None[source]
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:

WCPSResult

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 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)[source]

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)[source]

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