pyeither_demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# pyeither demo\n",
    "\n",
    "Source: https://github.com/SegFaultAX/pyeither\n",
    "\n",
    "## Introduction\n",
    "\n",
    "This is a basic introduction into error handling and pyeither. Some key takeaways are:\n",
    "\n",
    "* There are several popular methods for handling errors in large programs (exceptions, return codes, etc.) each with their own benefits and drawbacks\n",
    "* The common ways of handling errors don't compose well and/or incur lots of boilerplate (boilerplate = bugs)\n",
    "* Building a new error handling pattern from scratch is easy (and fun!)\n",
    "* pyeither is an alternative to the \"normal\" way we construct programs which favors composition and equational reasoning"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "!pip install pyeither>=0.0.3\n",
    "\n",
    "import attr\n",
    "import either"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Handling errors\n",
    "\n",
    "Broadly speaking, there are 2 styles of managing failures in code. The most popular in the Python world is via `Exception`s. Let's see a couple of examples of how that's typically done."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number 1: 10\n",
      "Number 2: 0\n",
      "Something bad happened\n"
     ]
    }
   ],
   "source": [
    "\n",
    "def catch_locally(a, b):\n",
    "    \"\"\"Handle errors locally, propagate values only\"\"\"\n",
    "    \n",
    "    try:\n",
    "        return a / b\n",
    "    except ZeroDivisionError:\n",
    "        return None\n",
    "\n",
    "def main_v1():\n",
    "    a, b = int(input(\"Number 1: \")), int(input(\"Number 2: \"))\n",
    "    result = catch_locally(a, b)\n",
    "    if result is None:\n",
    "        print(\"Something bad happened\")\n",
    "    else:\n",
    "        print(\"And the answer is: {}\".format(result))\n",
    "\n",
    "main_v1()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number 1: 10\n",
      "Number 2: 0\n",
      "Something bad happened\n"
     ]
    }
   ],
   "source": [
    "def catch_nonlocally(a, b):\n",
    "    \"\"\"Propagate exceptions and values to my caller\"\"\"\n",
    "    \n",
    "    return a / b\n",
    "\n",
    "def main_v2():\n",
    "    a, b = int(input(\"Number 1: \")), int(input(\"Number 2: \"))\n",
    "    try:\n",
    "        result = catch_nonlocally(a, b)\n",
    "        print(\"And the answer is: {}\".format(result))\n",
    "    except ZeroDivisionError:\n",
    "        print(\"Something bad happened\")\n",
    "        \n",
    "main_v2()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For our purposes the only interesting distinction between these examples is whether the function we're depdending on catches exceptions locally and propagates only values back to us, or expects us to handle both exceptions and successful results. Something worth reflecting on, particularly in dynamic languages, is the inability for the programmer to discover which exceptions a piece of code they're calling into is likely to raise. Languages like Java (via checked exceptions) do have a mechanism for statically notifying calling code of possible exceptions, but these features have other dubious drawbacks (namely, exception creep in types).\n",
    "\n",
    "Another common technique for propagating errors is to use multiple return with an error part and a result part. This is more common in langauges like Go, but it's still occasionally pops up in Python. Here's an example of what that might look like."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number 1: 10\n",
      "Number 2: 0\n",
      "Something bad happened\n"
     ]
    }
   ],
   "source": [
    "def div(a, b):\n",
    "    try:\n",
    "        return True, a / b\n",
    "    except ZeroDivisionError:\n",
    "        return False, None\n",
    "\n",
    "def main_v3():\n",
    "    a, b = int(input(\"Number 1: \")), int(input(\"Number 2: \"))\n",
    "    success, result = div(a, b)\n",
    "    \n",
    "    if success:\n",
    "        print(\"And the answer is: {}\".format(result))\n",
    "    else:\n",
    "        print(\"Something bad happened\")\n",
    "\n",
    "main_v3()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both styles of error handling and propagation have their strengths. Exceptions in particular allow you to be relatively dynamic in the way you handle errors by allowing them to unwind the callstack until a relevant receiver is found, or else crashing the application if there isn't one. Sometimes failing hard and immediately is the best option, but sometimes otherwise recoverable errors propagate in unexpected or undesirable ways.\n",
    "\n",
    "Return codes and success flags have the great benefit of being highly explicit and obvious. If most (or all) functions return a result and an indication of success, then it's clear from reading the code where the error is handled because handling and/or propagation is done locally and immediately. The main drawback is the significant amount of repetition that return codes cause, and the incredible level of care the programmer needs to take in refactoring around that boilerplate.\n",
    "\n",
    "As a slightly hyperbolic example, consider a function that chains a computation through a series of functions that can fail. Without some other mechanism for propagating failures, you might end up with functions that looks like this:\n",
    "\n",
    "```python\n",
    "def m():\n",
    "    success, result1 = f()\n",
    "    if not success:\n",
    "        return False, None\n",
    "    \n",
    "    success, result2 = g(result1)\n",
    "    if not success:\n",
    "        return False, None\n",
    "    \n",
    "    success, result3 = h(result2)\n",
    "    if not success:\n",
    "        return False, None\n",
    "    \n",
    "    return True, result3\n",
    "```\n",
    "\n",
    "## An alternative approach: first-class failure effects!\n",
    "\n",
    "Whether you agree or not that the above solutions are subpar, I'd like to present to you and alternative way you can tackle this problem with concepts borrowed from functional programming. To demonstrate the technique, we are going to build a basic library for generically modeling failure in our applications.\n",
    "\n",
    "### Step 1: The `Perhaps` type\n",
    "\n",
    "At a high level, what we'd like to have is a way to represent a possible result of some computation. That result can be in one of two states: it either failed (in which case we have nothing to work with), or we have a successful result which can be fed into the next part of our program. So let's start by implementing a simple type that represents exactly that, which we'll call `Perhaps`.\n",
    "\n",
    "*Why \"perhaps\"? Because Perhaps we have a value, or Perhaps we don't.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@attr.s(frozen=True, repr=False)\n",
    "class Perhaps:\n",
    "    \"\"\"A class that represents a possibly-failed computation\"\"\"\n",
    "    \n",
    "    value = attr.ib()\n",
    "    success = attr.ib()\n",
    "    \n",
    "    @property\n",
    "    def failure(self):\n",
    "        return not success\n",
    "    \n",
    "    def __repr__(self):\n",
    "        if self.success:\n",
    "            return \"Success({})\".format(self.value)\n",
    "        else:\n",
    "            return \"Failure\"\n",
    "        \n",
    "fail = Perhaps(None, False)\n",
    "\n",
    "def succeed(v):\n",
    "    \"\"\"Lift a value into Perhaps\"\"\"\n",
    "    \n",
    "    return Perhaps(v, True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Failure\n",
      "Success(3)\n"
     ]
    }
   ],
   "source": [
    "# A constant indicating a failed computation\n",
    "print(fail)\n",
    "\n",
    "# A value representing a successful computation of 3\n",
    "print(succeed(3))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success(5.0)\n",
      "Failure\n"
     ]
    }
   ],
   "source": [
    "def div(a, b):\n",
    "    return fail if b == 0 else succeed(a / b)\n",
    "\n",
    "print(div(10, 2))\n",
    "print(div(10, 0))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2: A function `inside`\n",
    "\n",
    "`Perhaps` represents a very simple concept with 2 possible states:\n",
    "\n",
    "* It's a value such as `Success(3)`, or\n",
    "* It's a `Failure`\n",
    "\n",
    "As you can see from the `div` example, it's very easy to re-implement functions using this notion of success/failure. Either you return a value via `succeed(x)` or you return `fail` to indicate that something has gone wrong.\n",
    "\n",
    "Unfortunately, `Perhaps` values are a little hard to work with. Specifically, if I have a function like `div`, how do I use the successful result of `div(10, 2)`? Calling that function returns `Success(5.0)`, not `5.0`, so a simple expression like this will not work:\n",
    "\n",
    "```python\n",
    "div(10, 2) * 100 # Won't work, the result of div(10, 2) is Success(5.0)\n",
    "```\n",
    "\n",
    "What we'd like to be able to do is have a way to apply a normal function **inside** of a successful result. \"Normal\" in this context is a function that does not use `Perhaps` in any way, for example:\n",
    "\n",
    "```python\n",
    "def times_10(n):\n",
    "    return n * 10\n",
    "```\n",
    "\n",
    "For the same reason `div(10, 2) * 100` won't work, neither will `times_10(div(10, 2))` because again, `times_10` is working on normal values instead of values wrapped in `Perhaps`. The solution to this problem is simple: create a method `inside` that, given a function, does nothing on `Failure` or else applies the function to the value inside of a `Success`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@attr.s(frozen=True, repr=False)\n",
    "class Perhaps:\n",
    "    \"\"\"A class that represents a possibly-failed computation\"\"\"\n",
    "    \n",
    "    value = attr.ib()\n",
    "    success = attr.ib()\n",
    "    \n",
    "    @property\n",
    "    def failure(self):\n",
    "        return not success\n",
    "    \n",
    "    ### NEW CODE ###\n",
    "    \n",
    "    def inside(self, f):\n",
    "        \"\"\"Apply `f` to my value if I have one, or else fail\"\"\"\n",
    "        \n",
    "        if self.success:\n",
    "            return succeed(f(self.value))\n",
    "        else:\n",
    "            return fail\n",
    "\n",
    "    ### NEW CODE ###\n",
    "    \n",
    "    def __repr__(self):\n",
    "        if self.success:\n",
    "            return \"Success({})\".format(self.value)\n",
    "        else:\n",
    "            return \"Failure\"\n",
    "        \n",
    "fail = Perhaps(None, False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success(5.0)\n",
      "Success(50.0)\n",
      "Failure\n"
     ]
    }
   ],
   "source": [
    "def times_10(n):\n",
    "    return n * 10\n",
    "\n",
    "a = div(10, 2)\n",
    "print(a)\n",
    "\n",
    "b = a.inside(times_10)\n",
    "print(b)\n",
    "\n",
    "print(fail.inside(times_10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 3: `collapse` the results\n",
    "\n",
    "Ok, now our `Perhaps` type is really starting to shape up. To re-iterate what we've done so far:\n",
    "\n",
    "* A value of `Perhaps` is either a successful result, or a failure\n",
    "* We can run normal (non-`Perhaps`) functions on a successful result using `inside`\n",
    "\n",
    "So the next question is: if we can use `inside` to make normal functions work with `Perhaps`, what about functions that **do** use `Perhaps` to indicate their own success or failure? Consider this function:\n",
    "\n",
    "```python\n",
    "def even(n):\n",
    "    if n % 2 == 0:\n",
    "        return succeed(n)\n",
    "    else:\n",
    "        return fail\n",
    "```\n",
    "\n",
    "This function works exactly like we'd expect:\n",
    "\n",
    "* An even value `N` will return `succeed(N)`\n",
    "* An odd value will return `Failure`\n",
    "\n",
    "So what happens if we try to use `inside` with `even`?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success(Success(2))\n",
      "Success(Failure)\n"
     ]
    }
   ],
   "source": [
    "def even(n):\n",
    "    if n % 2 == 0:\n",
    "        return succeed(n)\n",
    "    else:\n",
    "        return fail\n",
    "\n",
    "print(succeed(2).inside(even))\n",
    "print(succeed(3).inside(even))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Clearly something has gone a little weird here. Remember that `inside` just applies the function to the possible value inside of the `Perhaps`. In the first case, `even(2)` returns `Success(2)`, therefore `succeed(2).inside(even)` returns `Success(Success(2))`, a success nested within a success. The latter case is also fairly obvious: `even(3)` returns `Failure` and therefore the expression `succeed(3).inside(even)` results in `Success(Failure)`, a failure nested within a success.\n",
    "\n",
    "So let's create a method `collapse` that will reduce 1 layer of nesting within a `Perhaps` value. In other words, a value of `Success(Success(X))` when collapsed will simply be `Success(X)`. Likewise, a failure inside of a success such as `Success(Failure)` will collapse to just `Failure`. Note that because `Failure`s cannot be further nested, collapsing a `Failure` is just `Failure`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@attr.s(frozen=True, repr=False)\n",
    "class Perhaps:\n",
    "    \"\"\"A class that represents a possibly-failed computation\"\"\"\n",
    "    \n",
    "    value = attr.ib()\n",
    "    success = attr.ib()\n",
    "    \n",
    "    @property\n",
    "    def failure(self):\n",
    "        return not success\n",
    "    \n",
    "    def inside(self, f):\n",
    "        \"\"\"Apply `f` to my value if I have one, or else fail\"\"\"\n",
    "        \n",
    "        if self.success:\n",
    "            return succeed(f(self.value))\n",
    "        else:\n",
    "            return fail\n",
    "        \n",
    "    ### NEW CODE ###\n",
    "    \n",
    "    def collapse(self):\n",
    "        if self.success:\n",
    "            return self.value\n",
    "        else:\n",
    "            return fail\n",
    "\n",
    "    ### NEW CODE ###\n",
    "    \n",
    "    def __repr__(self):\n",
    "        if self.success:\n",
    "            return \"Success({})\".format(self.value)\n",
    "        else:\n",
    "            return \"Failure\"\n",
    "\n",
    "fail = Perhaps(None, False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success(Success(2))\n",
      "Success(Failure)\n",
      "Success(2)\n",
      "Failure\n",
      "Failure\n"
     ]
    }
   ],
   "source": [
    "print(succeed(2).inside(even))\n",
    "print(succeed(3).inside(even))\n",
    "\n",
    "print(succeed(2).inside(even).collapse())\n",
    "print(succeed(3).inside(even).collapse())\n",
    "print(fail.collapse())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4: Do this `and_then` that\n",
    "\n",
    "Once again, let's recap what we've actually created so far:\n",
    "\n",
    "* A value of `Perhaps` is either a successful result, or a failure\n",
    "* We can run normal (non-`Perhaps`) functions on a successful result using `inside`\n",
    "* We can reduce one layer of nesting within a `Perhaps` using `collapse`\n",
    "\n",
    "Let's look at a larger example of a processing pipeline. This pipeline will have 2 important characteristics:\n",
    "\n",
    "1. Each step in the pipeline can fail or succeed using `Perhaps`\n",
    "2. The output of one step in the pipeline is the input to the next"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "## Sample config files used for the next couple sections\n",
    "\n",
    "# Create a valid config file\n",
    "with open(\"example.yaml\", \"w\") as fd:\n",
    "    fd.write(\"\"\"---\\nname: mkbernard\\nage: 30\\n\"\"\")\n",
    "\n",
    "# Create an invalid config file\n",
    "with open(\"example_invalid.yaml\", \"w\") as fd:\n",
    "    fd.write(\"\"\"---\\n  name: mkbernard\\nage: 30\\n\"\"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success(Person(name='mkbernard', age=30))\n",
      "Failure\n",
      "Failure\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "import yaml\n",
    "\n",
    "@attr.s(frozen=True)\n",
    "class Person:\n",
    "    name = attr.ib()\n",
    "    age = attr.ib()\n",
    "    \n",
    "    @classmethod\n",
    "    def from_config(cls, config):\n",
    "        return Person(config[\"name\"], config[\"age\"])\n",
    "\n",
    "def attempt(f, *args, **kwargs):\n",
    "    try:\n",
    "        return succeed(f(*args, **kwargs))\n",
    "    except:\n",
    "        return fail\n",
    "\n",
    "def ensure_path(path):\n",
    "    return succeed(path) if os.path.isfile(path) else fail\n",
    "    \n",
    "def read_content(path):\n",
    "    return succeed(open(path).read())\n",
    "\n",
    "def parse_yaml(content):\n",
    "    return attempt(yaml.safe_load, content)\n",
    "\n",
    "def load_person(config):\n",
    "    return attempt(Person.from_config, config)\n",
    "\n",
    "def process(path):\n",
    "    return (succeed(path)\n",
    "        .inside(ensure_path).collapse()\n",
    "        .inside(read_content).collapse()\n",
    "        .inside(parse_yaml).collapse()\n",
    "        .inside(load_person).collapse())\n",
    "        \n",
    "print(process(\"example.yaml\"))\n",
    "print(process(\"example_invalid.yaml\"))\n",
    "print(process(\"not a path\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is a much more realistic example of something you're likely to do with `Perhaps`. You can trivially decompose a complex pipeline into individual pieces. If you look at the `process` function, something should immediately jump out at you: `inside(f).collapse()` is repeated over and over. This is because every time you use a `Perhaps`-returning function, you need to `collapse` the resulting nested value. This pattern is so common, that we can create a helper method on `Perhaps` called `and_then` that will automatically collapse the nesting."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@attr.s(frozen=True, repr=False)\n",
    "class Perhaps:\n",
    "    \"\"\"A class that represents a possibly-failed computation\"\"\"\n",
    "    \n",
    "    value = attr.ib()\n",
    "    success = attr.ib()\n",
    "    \n",
    "    @property\n",
    "    def failure(self):\n",
    "        return not success\n",
    "    \n",
    "    def inside(self, f):\n",
    "        \"\"\"Apply `f` to my value if I have one, or else fail\"\"\"\n",
    "        \n",
    "        if self.success:\n",
    "            return succeed(f(self.value))\n",
    "        else:\n",
    "            return fail\n",
    "    \n",
    "    def collapse(self):\n",
    "        if self.success:\n",
    "            return self.value\n",
    "        else:\n",
    "            return fail\n",
    "\n",
    "    ### NEW CODE ###\n",
    "    \n",
    "    def and_then(self, f):\n",
    "        return self.inside(f).collapse()\n",
    "    \n",
    "    ### NEW CODE ###\n",
    "    \n",
    "    def __repr__(self):\n",
    "        if self.success:\n",
    "            return \"Success({})\".format(self.value)\n",
    "        else:\n",
    "            return \"Failure\"\n",
    "\n",
    "fail = Perhaps(None, False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success(Person(name='mkbernard', age=30))\n",
      "Failure\n",
      "Failure\n"
     ]
    }
   ],
   "source": [
    "def process(path):\n",
    "    return (succeed(path)\n",
    "        .and_then(ensure_path)\n",
    "        .and_then(read_content)\n",
    "        .and_then(parse_yaml)\n",
    "        .and_then(load_person))\n",
    "        \n",
    "print(process(\"example.yaml\"))\n",
    "print(process(\"example_invalid.yaml\"))\n",
    "print(process(\"not a path\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 5: pyeither and beyond\n",
    "\n",
    "And now our `Perhaps` type is complete! Let's recap one last time what we've created:\n",
    "\n",
    "* A value of `Perhaps` is either a successful result, or a failure\n",
    "* We can run normal (non-`Perhaps`) functions on a successful result using `inside`\n",
    "* We can reduce one layer of nesting within a `Perhaps` using `collapse`\n",
    "* We can apply a `Perhaps`-returning function and collapse the result automatically using `and_then`\n",
    "\n",
    "In just a few lines of code, we've built a very simple abstraction that allows us to model failure in our programs in a highly composable way. The key insight was to represent successful and unsuccessful results in a type, and then provide some simple functions for chaining additional actions off of those possibly-present results.\n",
    "\n",
    "---\n",
    "\n",
    "By now you're probably wondering what pyeither is, and why you should use it over something like `Perhaps`. Indeed, pyeither works almost identically to `Perhaps` with one extremely important difference: `Either` values can carry context about **why** they failed! As a final example, let's look at our above code written using `Either` from pyeither."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Right(result=Person(name='mkbernard', age=30))\n",
      "Left(error='invalid yaml: expected \\'<document start>\\', but found \\'<block mapping start>\\'\\n  in \"<unicode string>\", line 3, column 1:\\n    age: 30\\n    ^')\n",
      "Left(error='is not a valid file')\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "import yaml\n",
    "\n",
    "@attr.s(frozen=True)\n",
    "class Person:\n",
    "    name = attr.ib()\n",
    "    age = attr.ib()\n",
    "    \n",
    "    @classmethod\n",
    "    def from_config(cls, config):\n",
    "        return Person(config[\"name\"], config[\"age\"])\n",
    "\n",
    "def ensure_path(path):\n",
    "    return either.should(os.path.isfile(path), path, \"is not a valid file\")\n",
    "    \n",
    "def read_content(path):\n",
    "    return either.succeed(open(path).read())\n",
    "\n",
    "def parse_yaml(content):\n",
    "    return either.lmap(\n",
    "        lambda e: \"invalid yaml: \" + str(e),\n",
    "        either.attempt(yaml.safe_load, content))\n",
    "\n",
    "def load_person(config):\n",
    "    return either.lmap(\n",
    "        lambda e: \"invalid user config: \" + str(e),\n",
    "        either.attempt(Person.from_config, config))\n",
    "\n",
    "def process(path):\n",
    "    return (either.succeed(path)\n",
    "            .chained()\n",
    "            .bind(ensure_path)\n",
    "            .bind(read_content)\n",
    "            .bind(parse_yaml)\n",
    "            .bind(load_person)\n",
    "            .unchain())\n",
    "        \n",
    "print(process(\"example.yaml\"))\n",
    "print(process(\"example_invalid.yaml\"))\n",
    "print(process(\"not a path\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are a few things worth pointing out in this example:\n",
    "\n",
    "* Instead of `Success` and `Failure` we have `Right` and `Left`, respectively. The difference in naming is mostly irrelevant for the purposes of this document, but suffice it to say that `Either` can be used in a very general way and is not restricted to modeling only failure.\n",
    "\n",
    "* `Left` values (the `Either` analog of a failure) have information about why they failed such as \"is not a valid file\"). This makes it far more useful in complex pipelines where many different kinds of failures are likely to happen and need careful handling or messaging.\n",
    "\n",
    "* `chained`/`unchain` are needed when fluent dot-notation is desired.\n",
    "\n",
    "* The names are slightly different (`bind` is equivalent to `and_then`, `join` is equivalent to `collapse`, etc) mostly for technical reasons (alignment with the relevant typeclasses in Haskell).\n",
    "\n",
    "For the most part, pyeither's `Either` type is operationally similar to `Perhaps`. There are many more functions and combinators exposed in the `either` module that make working with `Either` values extremely pleasant and ergonomic.\n",
    "\n",
    "## El Fin\n",
    "\n",
    "I hope this tutorial/discussion was useful to you. There's a tremendous amount of interesting, beautiful, pragmatic, and practical information available to you from the functional programming world. If you've found this at all interesting, I very strongly recommend at least looking at languages like Haskell or Scala.\n",
    "\n",
    "If this document has piqued your interest in functional programming, start here:\n",
    "\n",
    "* [Learn Haskell](https://github.com/bitemyapp/learnhaskell/blob/master/README.md)\n",
    "\n",
    "Contact me at mkbernard.dev \\[at\\] gmail.com with any comments or questions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.6",
   "language": "python",
   "name": "python36"
  },
  "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.6.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}