Merge remote-tracking branch 'origin/development' into development

Author: gjbex

source-code/README.md

@@ -26,3 +26,4 @@ was used to develop it.
    `pytest`.
 1. `oo_vs_functional.ipynb`: comparing object-oriented approach to
   functional approach, including coroutines.
+1. `metaclasses`: illustration of the use of metaclasses in Python.

source-code/metaclasses/README.md

@@ -0,0 +1,15 @@
+# Metaclasses
+
+Python supports metaclasses, i.e., classes that control the creation of other
+classes.
+
+Although this feature should not be overused, it can be useful in some
+circumstances.
+
+See the following [article](https://medium.com/fintechexplained/advanced-python-metaprogramming-980da1be0c7d) for a discussion.
+
+
+## What is it?
+
+1. `metaclasses.ipynb`: Jupyter notebook illustrating using a metaclass to
+   verify the correct implementation of a mix-in.

source-code/metaclasses/metaclasses.ipynb

@@ -0,0 +1,195 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "72694516-dbb4-47dc-bb49-cf0832d2eb2b",
+   "metadata": {},
+   "source": [
+    "Metaclasses can be quite useful in some circumstances.  A metaclass serves as a constructor for classes and can be used for validation at defintion time.\n",
+    "\n",
+    "Consider the following metaclass: it will check whether the class has a `_sound` attribute, if not, it will fail upon defintion.  It will also add a `make_sound` method, acting similar to a mix-in."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 42,
+   "id": "a2c0fb42-c8b7-4e7c-9044-f0a543a11a6c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class SoundMeta(type):\n",
+    "    \n",
+    "    def __new__(cls, what, bases=None, dict=None):\n",
+    "        if '_sound' not in dict:\n",
+    "            raise Exception('no _sound attribute defined')\n",
+    "        new_dict = dict.copy()\n",
+    "        new_dict['make_sound'] = lambda self: f'say {self._sound}'\n",
+    "        return type.__new__(cls, what, bases, new_dict)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "356b35e2-b534-44d1-bea6-67675cc0bdbb",
+   "metadata": {},
+   "source": [
+    "Note that the `SoundMeta` class has `type` as a base class, to `SoundMeta` is a class.  It defines its own `__new__` function to control object creation, which calls the parent's (i.e., `type`'s) `__new__` method with the modified dictionary."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "64654746-fc9f-4448-b26d-1887b391fd71",
+   "metadata": {},
+   "source": [
+    "The `Dog` class has a `sound` attribute, and defines some attributes and methods of its own."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 43,
+   "id": "73852058-22e2-4036-86ef-4e205a12bef7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class Dog(metaclass=SoundMeta):\n",
+    "    _sound: str = 'woof'\n",
+    "    \n",
+    "    def __init__(self, name):\n",
+    "        self._name = name\n",
+    "        \n",
+    "    @property\n",
+    "    def name(self):\n",
+    "        return self.name"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "696ff05b-273d-4dd3-ab2c-ac5a219cdee3",
+   "metadata": {},
+   "source": [
+    "We can instantiate a particular `Dog` and call its `make_sound()` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 44,
+   "id": "678a6d7e-f165-4183-a183-001c0a333a54",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'say woof'"
+      ]
+     },
+     "execution_count": 44,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "dog = Dog('felix')\n",
+    "dog.make_sound()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bfbfbd5f-b2d4-4aa2-acf4-b331ce86a768",
+   "metadata": {},
+   "source": [
+    "The `Bell` class also has `SoundMeta` as metaclass."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 38,
+   "id": "862b88a9-c467-43d3-975f-70aac7cdc330",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class Bell(metaclass=SoundMeta):\n",
+    "    _sound: str = 'dong'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ab5b88a3-1374-4980-aa97-4a33dc867c75",
+   "metadata": {},
+   "source": [
+    "It too can be used to instantiate objects that make a sound."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 45,
+   "id": "be700599-60bc-490a-8fbb-4bdae3cee06f",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'say dong'"
+      ]
+     },
+     "execution_count": 45,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "big_ben = Bell()\n",
+    "big_ben.make_sound()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "31cebd32-f4df-4a5b-9516-8b2a7a5ffaa3",
+   "metadata": {},
+   "source": [
+    "If you try to create a class that has no `_sound` attribute, the class definition will result in an error."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 47,
+   "id": "0f537499-6a88-4ca6-a9d8-1fad1ef5272c",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "no _sound attribute defined\n"
+     ]
+    }
+   ],
+   "source": [
+    "try:\n",
+    "    class Phone(metaclass=SoundMeta):\n",
+    "        pass\n",
+    "except Exception as e:\n",
+    "    print(e)"
+   ]
+  }
+ ],
+ "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.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}