coady/waiter

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Examples\n",
    "HTTP requests as an example of an unreliable operation.\n",
    "\n",
    "## decorators\n",
    "Using decorators to retry functions is a popular choice, and `waiter` supports this pattern."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "source": [
    "from waiter import wait\n",
    "import httpx\n",
    "\n",
    "backoff = wait(0.1) * 2\n",
    "url = 'https://httpbin.org/status/200'\n",
    "\n",
    "\n",
    "@backoff.retrying(OSError)\n",
    "def get_url(url):\n",
    "    return httpx.get(url)\n",
    "\n",
    "\n",
    "get_url(url)"
   ],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## functions\n",
    "But there's a problem with this approach: the *implementer* of the unreliable function is choosing the retry strategy instead of the *caller*.  Which in practice means the decorated function is often just a wrapper around the underlying implementation.\n",
    "\n",
    "The above example could just as easily be a partially bound function, and that is in fact how the `waiter` decorators are implemented.  This approach also facilitates reusing clients, which should be done for repeated requests anyway."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "source": [
    "from functools import partial\n",
    "\n",
    "get_url = partial(backoff.retry, OSError, httpx.Client().get)\n",
    "get_url(url)"
   ],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Which in turn raises the question of whether `get_url` is worth abstracting at all.  The completely in-lined variation is arguably just as readable."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "source": [
    "backoff.retry(OSError, httpx.Client().get, url)"
   ],
   "execution_count": null
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "source": [
    "backoff.poll(lambda r: not r.is_error, httpx.Client().get, url)"
   ],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## iteration\n",
    "But even the functional approach breaks down if the unreliable code is more naturally expressed as a block, or there are multiple failure conditions, or logging is required, etc.  It's not worth creating what amounts to a domain-specific language just to avoid a for-loop."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "source": [
    "import logging\n",
    "\n",
    "\n",
    "def get_url(url):\n",
    "    \"\"\"Retry and log both connection and http errors.\"\"\"\n",
    "    with httpx.Client() as client:\n",
    "        for _ in backoff[:1]:\n",
    "            try:\n",
    "                resp = client.get(url)\n",
    "            except OSError:\n",
    "                logging.exception(url)\n",
    "                continue\n",
    "            if not resp.is_error:\n",
    "                return resp\n",
    "            logging.error(f'{url} {resp.status_code}')\n",
    "    return None\n",
    "\n",
    "\n",
    "get_url('https://httpbin.org/status/404')"
   ],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## asyncio\n",
    "`waiter` also supports async iteration and coroutine functions."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "source": [
    "import httpx\n",
    "\n",
    "\n",
    "async def get_url(url):\n",
    "    return await backoff.retry(OSError, httpx.AsyncClient().get, url)\n",
    "\n",
    "\n",
    "get_url(url)"
   ],
   "execution_count": null
  },
  {
   "cell_type": "code",
   "metadata": {},
   "outputs": [],
   "source": [
    "async def get_url(url):\n",
    "    async with httpx.AsyncClient() as client:\n",
    "        async for _ in backoff:\n",
    "            resp = await client.get(url)\n",
    "            if resp.status == 200:\n",
    "                return resp\n",
    "\n",
    "\n",
    "get_url(url)"
   ],
   "execution_count": null
  }
 ],
 "metadata": {
  "celltoolbar": "Edit Metadata",
  "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.2-final"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}