{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# AGU 2018 Demo\n",
    "\n",
    "This notebook shows how to use `birdy`'s high-level interface to WPS processes. \n",
    "\n",
    "Here we access a test server called `Emu` offering a dozen or so dummy processes. \n",
    "\n",
    "## The shell interface"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "export WPS_SERVICE=\"http://localhost:5000/wps?Service=WPS&Request=GetCapabilities&Version=1.0.0\"\n",
    "birdy -h"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "export WPS_SERVICE=\"http://localhost:5000/wps?Service=WPS&Request=GetCapabilities&Version=1.0.0\"\n",
    "birdy hello -h"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "export WPS_SERVICE=\"http://localhost:5000/wps?Service=WPS&Request=GetCapabilities&Version=1.0.0\"\n",
    "birdy hello --name stranger"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The python interface\n",
    "\n",
    "The `WPSClient` function creates a *mock* python module whose functions actually call a remote WPS process. The \n",
    "docstring and signature of the function are dynamically created from the remote's process description. If you type `wps.` and then press `Tab`, you should see a drop-down list of available processes. Simply call `help` on each process of type `?` after the process to print the docstring for that process. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from birdy import WPSClient\n",
    "\n",
    "url = \"http://localhost:5000/wps?Service=WPS&Request=GetCapabilities&Version=1.0.0\"\n",
    "wps = WPSClient(url, verify=False)\n",
    "help(wps.binaryoperatorfornumbers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Type `wps.` and the press `Tab`, you should see a drop-down list of available processes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# wps."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Process execution\n",
    "\n",
    "Processes are executed by calling the function. Each process instantaneoulsy returns a `WPSExecute` object. The actual output values of the process are obtained by calling the `get` method. This `get` method returns a namedtuple storing the process outputs as native python objects. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "resp = wps.binaryoperatorfornumbers(1, 2, operator=\"add\")\n",
    "print(resp)\n",
    "resp.get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For instance, the `inout` function returns a wide variety of data types (float, integers, dates, etc) all of which are converted into a corresponding python type. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wps.inout().get()"
   ]
  },
  {
   "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 `birdy`, the outputs are by default return values are 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 `asobj` to `True` when calling the `get` method. In the example below, we're using a dummy process called `output_formats`, whose first output is a netCDF file, and second output is a json file. With `asobj=True`, the netCDF file is opened and returned as a `netcdf4.Dataset` instance, and the json file into a dictionary. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# NBVAL_SKIP\n",
    "# This cell is failing due to an unautheticated SSL certificate\n",
    "out = wps.output_formats()\n",
    "nc, json = out.get()\n",
    "print(out.get())\n",
    "ds, json = out.get(asobj=True)\n",
    "print(json)\n",
    "ds"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Progress bar\n",
    "\n",
    "It's possible to display a progress bar when calling a process. The interface to do so at the moment goes like this. Note that the cancel button does not do much here, as the WPS server does not support interruption requests. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wps = WPSClient(\"http://localhost:5000/wps\", progress=True)\n",
    "resp = wps.sleep()"
   ]
  }
 ],
 "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.9.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}