Add example of using protocols

Author: gjbex

source-code/object-orientation/README.md

@@ -11,8 +11,8 @@ Some examples of object-oriented programming in Python.
   * `polynomials`: additional example of object-orientated code.
   * `abstract_classes.ipynb`: illustration of using abstract base
     classes.
-  * `avoiding_class_hierarchies.ipynb`: illustration of duck typing
-    and mix-in.
+  * `avoiding_class_hierarchies.ipynb`: illustration of duck typing,
+    protocols and mix-in.
   * `overloading.ipynb`: illustration of function overloading using
     single dispatch.
   * `inheritance.py`: illustration of inheritance of class attributes.

source-code/object-orientation/avoiding_class_hierarchies.ipynb

@@ -51,12 +51,10 @@
    "outputs": [],
    "source": [
     "class Duck:\n",
-    "       \n",
-    "    _sound: str = 'quack'\n",
     "    species: str\n",
     "    \n",
     "    def make_sound(self):\n",
-    "        return self._sound\n",
+    "        return 'quack'\n",
     "    \n",
     "    def __init__(self, species):\n",
     "        self.species = species"
@@ -69,12 +67,10 @@
    "outputs": [],
    "source": [
     "class Timer:\n",
-    "    \n",
-    "    _sound: str = 'beep'\n",
     "    time: int\n",
     "    \n",
     "    def make_sound(self):\n",
-    "        return self._sound\n",
+    "        return 'ring'\n",
     "    \n",
     "    def __init__(self, time):\n",
     "        self.time = time"
@@ -113,7 +109,7 @@
      "output_type": "stream",
      "text": [
       "<class '__main__.Duck'> says quack\n",
-      "<class '__main__.Timer'> says beep\n"
+      "<class '__main__.Timer'> says ring\n"
      ]
     }
    ],
@@ -129,6 +125,167 @@
     "Note that the sound faculty of these classes is not derived from a common ancestor class by inheritance."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Protocols"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Duck typing can be formalized in Python 3.8+ using protocols.  This will allow type checkers such as `mypy` to find potential mistakes.  Consider the code as above, but now implemented using a `Protocol`.\n",
+    "\n",
+    "A protocol is defined as a class that inherits from `Protocol` that is defined in the `typing` module.  It defines the method signatures that should be implemented by any class that supports the protocol.  In the example below, any class that can make a sound should have a `make_sound` method that returns a `str`.\n",
+    "\n",
+    "The classes that implement the protocol `SoundMaker` *do not* inherit from that class, they simply implement the `make_sound` method as specified by the protocol, i.e., a method that takes no arguments besides the object, and that returns a `str`.\n",
+    "\n",
+    "The `make_sound` function takes an object of type `SoundMaker` as an argument.  Although neither `Duck` nor `Timer` inherit from `SoundMaker`, the type checker will nevertheless be satisfied since both classes implement the protocol `SoundMaker` since they have a `make_sound` method implementation.\n",
+    "\n",
+    "Since the `Dog` class doesn't implement `make_sound`, a static type checker will now report an error when a `Dog` object is passed as an argument to the `make_sound` function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Writing protocols_toremove.py\n"
+     ]
+    }
+   ],
+   "source": [
+    "%%writefile protocols_toremove.py\n",
+    "#!/usr/bin/env python\n",
+    "\n",
+    "from typing import Protocol\n",
+    "\n",
+    "\n",
+    "class SoundMaker(Protocol):\n",
+    "    def make_sound(self) -> str: ...\n",
+    "\n",
+    "\n",
+    "class Duck:\n",
+    "    species: str\n",
+    "\n",
+    "    def __init__(self, species: str):\n",
+    "        self.species = species\n",
+    "\n",
+    "    def make_sound(self) -> str:\n",
+    "        return 'quack'\n",
+    "\n",
+    "\n",
+    "class Timer:\n",
+    "    time: int\n",
+    "\n",
+    "    def __init__(self, time: int):\n",
+    "        self.time = time\n",
+    "\n",
+    "    def make_sound(self) -> str:\n",
+    "        return 'ring'\n",
+    "\n",
+    "\n",
+    "class Dog:\n",
+    "    name: str\n",
+    "\n",
+    "    def __init__(self, name: str):\n",
+    "        self.name = name\n",
+    "\n",
+    "\n",
+    "def make_sound(stuff: SoundMaker) -> None:\n",
+    "    print(stuff.make_sound())\n",
+    "\n",
+    "\n",
+    "if __name__ == \"__main__\":\n",
+    "    duck = Duck('Mallard')\n",
+    "    timer = Timer(5)\n",
+    "    dog = Dog('Fido')\n",
+    "\n",
+    "    make_sound(duck)\n",
+    "    make_sound(timer)\n",
+    "\n",
+    "    things: list[SoundMaker] = [duck, timer]\n",
+    "    for thing in things:\n",
+    "        make_sound(thing)\n",
+    "\n",
+    "    # Does't pass type check, will result in runtime error \n",
+    "    make_sound(dog)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we can run `mypy` to do type checking."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "protocols_toremove.py:54: \u001b[1m\u001b[31merror:\u001b[m Argument 1 to \u001b[m\u001b[1m\"make_sound\"\u001b[m has incompatible type \u001b[m\u001b[1m\"Dog\"\u001b[m; expected \u001b[m\u001b[1m\"SoundMaker\"\u001b[m  \u001b[m\u001b[33m[arg-type]\u001b[m\n",
+      "\u001b[1m\u001b[31mFound 1 error in 1 file (checked 1 source file)\u001b[m\n"
+     ]
+    }
+   ],
+   "source": [
+    "!mypy protocols_toremove.py"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Indeed, running this script would result in a runtime error."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "quack\n",
+      "ring\n",
+      "quack\n",
+      "ring\n",
+      "Traceback (most recent call last):\n",
+      "  File \"/home/gjb/Projects/Python-software-engineering/source-code/object-orientation/protocols_toremove.py\", line 54, in <module>\n",
+      "    make_sound(dog)\n",
+      "  File \"/home/gjb/Projects/Python-software-engineering/source-code/object-orientation/protocols_toremove.py\", line 38, in make_sound\n",
+      "    print(stuff.make_sound())\n",
+      "          ^^^^^^^^^^^^^^^^\n",
+      "AttributeError: 'Dog' object has no attribute 'make_sound'\n"
+     ]
+    }
+   ],
+   "source": [
+    "!python protocols_toremove.py"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!rm protocols_toremove.py"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -145,7 +302,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -167,7 +324,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -182,7 +339,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 12,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -197,7 +354,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 13,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -211,7 +368,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 14,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -220,7 +377,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 15,
    "metadata": {},
    "outputs": [
     {
@@ -246,17 +403,20 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
-   "metadata": {},
+   "execution_count": 16,
+   "metadata": {
+    "tags": []
+   },
    "outputs": [
     {
      "name": "stderr",
      "output_type": "stream",
      "text": [
       "Traceback (most recent call last):\n",
-      "  File \"<ipython-input-12-1c825f3b7991>\", line 3, in <module>\n",
+      "  File \"/tmp/ipykernel_3319/3334719555.py\", line 3, in <module>\n",
       "    print(dog.make_sound())\n",
-      "  File \"<ipython-input-6-918cd6c589ba>\", line 7, in make_sound\n",
+      "          ^^^^^^^^^^^^^^^^\n",
+      "  File \"/tmp/ipykernel_3319/2135747159.py\", line 7, in make_sound\n",
       "    raise ValueError(f'{type(self)} does not make sound')\n",
       "ValueError: <class '__main__.Dog'> does not make sound\n"
      ]
@@ -269,11 +429,18 @@
     "except ValueError as error:\n",
     "    print_exc()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "However, note that this implies a class hierarchy."
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -287,7 +454,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.5"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,