{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# OWSLib versus Birdy\n",
    "\n",
    "This notebook shows a side-by-side comparison of `owslib.wps.WebProcessingService` and `birdy.WPSClient`. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from owslib.wps import WebProcessingService\n",
    "\n",
    "from birdy import WPSClient\n",
    "\n",
    "url = \"https://bovec.dkrz.de/ows/proxy/emu?Service=WPS&Request=GetCapabilities&Version=1.0.0\"\n",
    "\n",
    "wps = WebProcessingService(url)\n",
    "cli = WPSClient(url=url)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Displaying available processes\n",
    "\n",
    "With `owslib`, `wps.processes` is the list of processes offered by the server. \n",
    "With `birdy`, the client is like a module with functions. So you just write `cli.` and press `Tab` to display a drop-down menu of processes. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wps.processes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Documentation about a process\n",
    "\n",
    "With `owslib`, the process title and abstract can be obtained simply by looking at these attributes. \n",
    "For the process inputs, we need to iterate on the inputs and access their individual attributes. To facilitate this, `owslib.wps` provides the `printInputOuput` function. \n",
    "\n",
    "With `birdy`, just type `help(cli.hello)` and the docstring will show up in your console. With the IPython console or a Jupyter Notebook, `cli.hello?` would do as well. The docstring follows the NumPy convention. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from owslib.wps import printInputOutput\n",
    "\n",
    "p = wps.describeprocess(\"hello\")\n",
    "print(\"Title: \", p.title)\n",
    "print(\"Abstract: \", p.abstract)\n",
    "\n",
    "for inpt in p.dataInputs:\n",
    "    printInputOutput(inpt)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(cli.hello)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Launching a process and retrieving literal outputs\n",
    "\n",
    "With `owslib`, processes are launched using the `execute` method. Inputs are an an argument to `execute` and defined by a list of key-value tuples. These keys are the input names, and the values are string representations. The `execute` method returns a `WPSExecution` object, which defines a number of methods and attributes, including `isComplete` and `isSucceeded`. The process outputs are stored in the `processOutputs` list, whose content is stored in the `data` attribute. Note that this `data` is a list of strings, so we may have to convert it to a `float` to use it. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "resp = wps.execute(\n",
    "    \"binaryoperatorfornumbers\",\n",
    "    inputs=[(\"inputa\", \"1.0\"), (\"inputb\", \"2.0\"), (\"operator\", \"add\")],\n",
    ")\n",
    "if resp.isSucceded:\n",
    "    (output,) = resp.processOutputs\n",
    "    print(output.data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With `birdy`, inputs are just typical keyword arguments, and outputs are already converted into python objects. Since some processes may have multiple outputs, processes always return a `namedtuple`, even in the case where there is only a single output. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z = cli.binaryoperatorfornumbers(1, 2, operator=\"add\").get()[0]\n",
    "z"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "out = cli.inout().get()\n",
    "out.date"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Retrieving outputs by references\n",
    "\n",
    "For `ComplexData` objects, WPS servers often return a reference to the output (an http link) instead of the actual data. This is useful if that output is to serve as an input to another process, so as to avoid passing back and forth large files for nothing. \n",
    "\n",
    "With `owslib`, that means that the `data` attribute of the output is empty, and we instead access the `reference` attribute. The referenced file can be written to the local disk using the `writeToDisk` method. \n",
    "\n",
    "With `birdy`, the outputs are by default the references themselves, but it's also possible to download these references in the background and convert them into python objects. To trigger this automatic conversion, set `convert_objects` to `True` when instantating the client `WPSClient(url, convert_objects=True)`. Ini the example below, the first output is a plain text file, and the second output is a json file. The text file is converted into a string, and the json file into a dictionary. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "resp = wps.execute(\"multiple_outputs\", inputs=[(\"count\", \"1\")])\n",
    "output, ref = resp.processOutputs\n",
    "print(output.reference)\n",
    "print(ref.reference)\n",
    "output.writeToDisk(\"/tmp/output.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output = cli.multiple_outputs(1).get()[0]\n",
    "print(output)\n",
    "# as reference\n",
    "output = cli.multiple_outputs(1).get(asobj=True)[0]\n",
    "print(output)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}