API Reference

Using the command line

Birdy has a command line interface to interact with a Web Processing Service.

Example

Here is an example with Emu WPS service:

$ birdy -h
$ birdy hello -h
$ birdy hello --name stranger
'Hello Stranger'

Configure WPS service URL

By default Birdy talks to a WPS service on URL http://localhost:5000/wps. You can change this URL by setting the enivronment variable WPS_SERVICE:

$ export WPS_SERVICE=http://localhost:5000/wps

Configure SSL verification for HTTPS

In case you have a WPS serive using HTTPS with a self-signed certificate you need to configure the environment variable WPS_SSL_VERIFY:

# deactivate SSL server validation for a self-signed certificate.
$ export WPS_SSL_VERIFY=false

You can also set the path of the service certificate. Read the requests documentation.

Use an OAuth2 access token

If the WPS service is secured by an OAuth2 access tokens then you can provide an access token with the --token option:

$ birdy --token abc123 hello --name stranger

Use client certificate to access WPS service

If the WPS service is secured by x509 certificates you can add a certificate with the --cert option to a request:

# run hello with certificate
$ birdy --cert cert.pem hello --name stranger

Using the output_formats option for a process

Each process also has a default option named output_formats. It can be used to override a process’ output format’s default values.

This option takes three parameters;

The format identifier: the name given to it

The as reference parameter: if the output is returned as a link of not. Can be True, False, or None (which uses the process’ default value)

The MIME type: of which MIME type is the output. Unless the process has multiple supported mime types, this can be left to None.

Looking at the emu process output_formats, the JSON output’s default’s the as reference parameter to False and returns the content directly:

$ birdy output_formats
  Output:
  netcdf=http://localhost:5000/outputs/d9abfdc4-08d6-11eb-9334-0800274cd70c/dummy.nc
  json=['{"testing": [1, 2]}']

We can then use the output_formats option to redefine it:

$ birdy output_formats --output_formats json True None
  Output:
  netcdf=http://localhost:5000/outputs/38e9aefe-08db-11eb-9334-0800274cd70c/dummy.nc
  json=http://localhost:5000/outputs/38e9aefe-08db-11eb-9334-0800274cd70c/dummy.json

Using the Python library

WPSClient Class.

The WPSClient class aims to make working with WPS servers easy, even without any prior knowledge of WPS.

Calling the WPSClient class creates an instance whose methods call WPS processes. These methods are generated at runtime based on the process description provided by the WPS server. Calling a function sends an execute request to the server. The server response is parsed and returned as a WPSExecution instance, which includes information about the job status, the progress percentage, the starting time, etc. The actual output from the process are obtained by calling the get method.

The output is parsed to convert the outputs in native Python whenever possible. LiteralOutput objects (string, float, integer, boolean) are automatically converted to their native format. For ComplexOutput, the module can either return a link to the output files stored on the server, or try to convert the outputs to a Python object based on their mime type. This conversion will occur with get(asobj=True). So for example, if the mime type is ‘application/json’, the output would be a dict.

Inputs to processes can be native Python types (string, float, int, date, datetime), http links or local files. Local files can be transferred to a remote server by including their content into the WPS request. Simply set the input to a valid path or file object and the client will take care of reading and converting the file.

Example

If a WPS server with a simple hello process is running on the local host on port 5000:

>>> from birdy import WPSClient
>>> emu = WPSClient('http://localhost:5000/')
>>> emu.hello
<bound method hello of <birdy.client.base.WPSClient object>>
>>> print(emu.hello.__doc__)

# Just says a friendly Hello. Returns a literal string output with Hello plus the inputed name.

# Parameters
# ----------
# name : string
#     Please enter your name.
#
# Returns
# -------
# output : string
#     A friendly Hello from us.
#
# ""
#
# # Call the function. The output is a namedtuple
# >>> emu.hello('stranger')
# hello(output='Hello stranger')

Authentication

If you want to connect to a server that requires authentication, the WPSClient class accepts an auth argument that behaves exactly like in the popular requests module (see requests Authentication)

The simplest form of authentication is HTTP Basic Auth. Although wps processes are not commonly protected by this authentication method, here is a simple example of how to use it:

>>> from birdy import WPSClient
>>> from requests.auth import HTTPBasicAuth
>>> auth = HTTPBasicAuth('user', 'pass')
>>> wps = WPSClient('http://www.example.com/wps', auth=auth)

Because any requests-compatible class is accepted, custom authentication methods are implemented the same way as in requests.

For example, to connect to a magpie protected wps, you can use the requests-magpie module:

>>> from birdy import WPSClient
>>> from requests_magpie import MagpieAuth
>>> auth = MagpieAuth('https://www.example.com/magpie', 'user', 'pass')
>>> wps = WPSClient('http://www.example.com/wps', auth=auth)

Output format

Birdy automatically manages process output to reflect it’s default values or Birdy’s own defaults.

However, it’s possible to customize the output of a process. Each process has an input named ``output_formats`, that takes a dictionary as a parameter:

# example format = {
#     'output_identifier': {
#         'as_ref': <True, False or None>
#         'mimetype': <MIME type as a string or None>,
#     },
# }

# A dictionary defining netcdf and json outputs
>>> custom_format = {
>>>     'netcdf': {
>>>         'as_ref': True,
>>>         'mimetype': 'application/json',
>>>     },
>>>     'json': {
>>>         'as_ref': False,
>>>         'mimetype': None
>>>     }
>>> }

Utility functions can also be used to create this dictionary:

>>> custom_format = create_output_dictionary('netcdf', True, 'application/json')
>>> add_output_format(custom_format, 'json', False, None)

The created dictionary can then be used with a process:

>>> cli = WPSClient("http://localhost:5000")
>>> z = cli.output_formats(output_formats=custom_format).get()
>>> z