understanding-metaclasses.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What is a Metaclass?\n",
    "\n",
    "> « Metaclasses are deeper magic that 99% of users should never worry about. If you wonder whether you need them, you don't (the people who actually need them know with certainty that they need them, and don't need an explanation about why). »  \n",
    "*Tim Peters, Python Guru*\n",
    "\n",
    "Thank you, Tim! We're off to a good start!\n",
    "\n",
    "This being said, it is not entirely false. It remains quite rare to create metaclasses in Python. However, they can solve complex problems elegantly.\n",
    "\n",
    "Numerous libraries, such as Django, use them in their internal mechanics.\n",
    "\n",
    "So what is a metaclass? It is a class whose instances are classes.\n",
    "\n",
    "In other words, a class is a factory that creates variables called *class instances*. A metaclass is a factory that creates classes. Simply put, a factory that creates factories.\n",
    "\n",
    "The advantage is to be able to benefit classes based on a metaclass of the same behaviour without having to copy/paste from one class to another. Inheritance was made for this. However, it does not solve everything..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The limits of inheritance\n",
    "\n",
    "Imagine you want to make a singleton class, which is a class that holds only one instance of a variable. If you create multiple instances, the class will always return the first one created, and every instance will hold the same **id**.\n",
    "\n",
    "What is the purpose of such a class?\n",
    "\n",
    "* The *None* constant is an example of a singleton. There exists only one copy at a time. This explains why the following can be written in tests:\n",
    "\n",
    "```python\n",
    "a == None or a is None\n",
    "```\n",
    "\n",
    "The **is** operator compares addresses. It works on this equality test because all instances of None have the same address. This would not be true for integers:\n",
    "\n",
    "```python\n",
    "a = 10**16\n",
    "b = 10**16\n",
    "print(a == b) # True\n",
    "print(a is b) # Certainly False\n",
    "```\n",
    "\n",
    "* Peripheral drivers, such as the ones for printers, are often singleton objects considering there is no need for 50 copies of a driver stored in memory when only one is needed to communicates with the printer.\n",
    "* Some software like *Word* are singletons. If you launch them several times, the instance currently active is re-displayed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How to implement a Singleton class in Python\n",
    "\n",
    "Every language has its own techniques. In Java/C++, we can create a class with a private constructor to prevent it from being called by the developers and force them to pass a **get_instance** method that handles the class's unique constructor call.\n",
    "\n",
    "In Python, everything is public. Therefore, the solution above does not apply. [Wikipédia provides](https://en.wikipedia.org/wiki/Singleton_pattern) a brief overview on how to implement the pattern. The page in [French](https://fr.wikipedia.org/wiki/Singleton_(patron_de_conception)) presents implementations in various languages, including Python.\n",
    "\n",
    "To implement a singleton class, we must prevent the creation of multiple instances.\n",
    "\n",
    "In Python, variables are created in the constructor. \n",
    "\n",
    "The constructor is not the `__init__` function.\n",
    "The constructor is the function that creates the variable in memory.\n",
    "`__init__` is called to initialize the instance's attributes once the variable is created. It is the [`__new__`](https://docs.python.org/3/reference/datamodel.html#object.__new__) function that allocates the object in memory.\n",
    "\n",
    "We usually never define it because Python manages memory itself. And it is much simpler this way.\n",
    "\n",
    "However, we could redefine it so that it:\n",
    "\n",
    "* creates and stores a variable on the very first call\n",
    "* returns the  already-created variable on subsequent calls\n",
    "\n",
    "The unique singleton instance can be stored as a class attribute.\n",
    "Which yields:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Singleton(object):\n",
    "    \n",
    "    unique_instance = None  # Class attribute storing the single instance\n",
    "    \n",
    "    def __new__(cls, *args, **kwargs):\n",
    "        \"\"\"Notice the first parameter is not self but the class itself because\n",
    "        the variable is not created yet. We will create it. \n",
    "        \"\"\"\n",
    "        \n",
    "        # If the instance is not created yet...\n",
    "        if cls.unique_instance is None:\n",
    "            # We create it by calling the parent's __new__ method that knows how to do it...\n",
    "            cls.unique_instance = super().__new__(cls, *args, **kwargs)\n",
    "            \n",
    "        return cls.unique_instance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All that is left to test is the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Well played!\n"
     ]
    }
   ],
   "source": [
    "s1 = Singleton()\n",
    "s2 = Singleton()\n",
    "\n",
    "assert s1 == s2\n",
    "assert s1 is s2\n",
    "assert id(s1) == id(s2)\n",
    "assert type(s1) == Singleton\n",
    "print(\"Well played!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mission well accomplished by using the `__new__` method rarely used in Python. This is starting to be high-level.\n",
    "\n",
    "Now, let's imagine we need a second Singleton class. We won't duplicate the first but inherit from it considering the mechanics are already in place!\n",
    "\n",
    "To do so, I duplicate the class above in notebook mode, which is the equivalent to running a script over to reinitialize `Singleton.instance_unique` to None."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hehe... too easy... What is the need for a metaclass?\n"
     ]
    }
   ],
   "source": [
    "class Singleton(object):\n",
    "    \n",
    "    unique_instance = None  # Class attribute storing the single instance\n",
    "    \n",
    "    def __new__(cls, *args, **kwargs):\n",
    "        \"\"\"Notice the first parameter is not self but the class itself because\n",
    "        the variable is not created yet. We will create it. \n",
    "        \"\"\"\n",
    "        \n",
    "        # If the instance is not created yet...\n",
    "        if cls.unique_instance is None:\n",
    "            # We create it by calling the parent's __new__ method that knows how to do it...\n",
    "            cls.unique_instance = super().__new__(cls, *args, **kwargs)\n",
    "            \n",
    "        return cls.unique_instance\n",
    "    \n",
    "class SingletonChild(Singleton):\n",
    "    pass\n",
    "\n",
    "\n",
    "sc1 = SingletonChild()\n",
    "sc2 = SingletonChild()\n",
    "\n",
    "assert sc1 == sc2\n",
    "assert sc2 is sc1\n",
    "assert id(sc1) == id(sc2)\n",
    "\n",
    "assert type(sc1) == SingletonChild, \"I am not of the type expected\"\n",
    "\n",
    "print(\"Hehe... too easy... What is the need for a metaclass?\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Too easy, or almost..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's imagine you need two singleton instances: one for the *Singleton* class and another for *SingletonChild*. You would thus write the following..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Well played!\n"
     ]
    },
    {
     "ename": "AssertionError",
     "evalue": "I am not of the type expected",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-41-1eb78eaf5eb4>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m     39\u001b[0m \u001b[0;32massert\u001b[0m \u001b[0mid\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msc1\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mid\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msc2\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m     40\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 41\u001b[0;31m \u001b[0;32massert\u001b[0m \u001b[0mtype\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msc1\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m==\u001b[0m \u001b[0mSingletonChild\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m\"I am not of the type expected\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m     42\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m     43\u001b[0m \u001b[0mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"OUCH...\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mAssertionError\u001b[0m: I am not of the type expected"
     ]
    }
   ],
   "source": [
    "class Singleton(object):\n",
    "    \n",
    "    unique_instance = None  # Class attribute storing the single instance\n",
    "    \n",
    "    def __new__(cls, *args, **kwargs):\n",
    "        \"\"\"Notice the first parameter is not self but the class itself because\n",
    "        the variable is not created yet. We will create it. \n",
    "        \"\"\"\n",
    "        \n",
    "        # If the instance is not created yet...\n",
    "        if cls.unique_instance is None:\n",
    "            # We create it by calling the parent's __new__ method that knows how to do it...\n",
    "            cls.unique_instance = super().__new__(cls, *args, **kwargs)\n",
    "            \n",
    "        return cls.unique_instance\n",
    "    \n",
    "class SingletonChild(Singleton):\n",
    "    pass\n",
    "\n",
    "\n",
    "# Creation of the singleton instance for the Singleton class\n",
    "s1 = Singleton()\n",
    "s2 = Singleton()\n",
    "\n",
    "assert s1 == s2\n",
    "assert s1 is s2\n",
    "assert id(s1) == id(s2)\n",
    "assert type(s1) == Singleton\n",
    "print(\"Well played!\")\n",
    "\n",
    "# Creation of the singleton instance for the SingletonChild class\n",
    "# HERE it's getting nasty...\n",
    "\n",
    "sc1 = SingletonChild()\n",
    "sc2 = SingletonChild()\n",
    "\n",
    "assert sc1 == sc2\n",
    "assert sc2 is sc1\n",
    "assert id(sc1) == id(sc2)\n",
    "\n",
    "assert type(sc1) == SingletonChild, \"I am not of the type expected\"\n",
    "\n",
    "print(\"OUCH...\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "ename": "AssertionError",
     "evalue": "Even here...",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m                            Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-42-e0e5132fc34e>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;32massert\u001b[0m \u001b[0misinstance\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msc1\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mSingletonChild\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m\"Even here...\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mAssertionError\u001b[0m: Even here..."
     ]
    }
   ],
   "source": [
    "assert isinstance(sc1, SingletonChild), \"Even here...\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class '__main__.Singleton'>\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "print(type(sc1))\n",
    "print(isinstance(sc1, Singleton))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "print(sc1 == s1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By inheriting SingletonChild from Singleton, the child class benefits from the same `__new__` function, but it has already allocated memory for the variable *s1* which is of the type Singleton.\n",
    "\n",
    "As a result, SingletonChild does not have its own instance.\n",
    "\n",
    "We would thus need to duplicate the `unique_instance` attribute in SingletonChild:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Ok, but we have duplicated a class attribute\n"
     ]
    }
   ],
   "source": [
    "class SingletonChild(Singleton):\n",
    "    unique_instance = None\n",
    "    \n",
    "    \n",
    "sc1 = SingletonChild()\n",
    "sc2 = SingletonChild()\n",
    "\n",
    "assert sc1 == sc2\n",
    "assert sc2 is sc1\n",
    "assert id(sc1) == id(sc2)\n",
    "assert isinstance(sc1, SingletonChild)\n",
    "print(\"Ok, but we have duplicated a class attribute\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The solution is viable and almost pretty, apart from the instance creation for each subclass of Singleton.\n",
    "\n",
    "We can live well with this solution. However, we can do better by automatizing the code with metaclasses. It will avoid inheriting SingletonChild from Singleton for it to be a Singleton class..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How classes are created in Python\n",
    "Before embarking on the creation of metaclasses and classes based on this model, let's dive into a deeper understanding of the language and the creation of a class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Python, *everything is an object*.  \n",
    "A function is an object, a class is an object..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'function'>\n"
     ]
    }
   ],
   "source": [
    "def  hello():\n",
    "    \"\"\"Prints hello\"\"\"\n",
    "    print(\"Hello!\")\n",
    "    \n",
    "print(type(hello))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello!\n"
     ]
    }
   ],
   "source": [
    "hi = hello\n",
    "hi()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What can we do with hello?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['__annotations__', '__call__', '__class__', '__closure__', '__code__', '__defaults__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__get__', '__getattribute__', '__globals__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__kwdefaults__', '__le__', '__lt__', '__module__', '__name__', '__ne__', '__new__', '__qualname__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__']\n"
     ]
    }
   ],
   "source": [
    "print(dir(hello))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Prints hello\n",
      "hello\n"
     ]
    }
   ],
   "source": [
    "print(hello.__doc__)   # The docstring is stored here\n",
    "print(hello.__name__)  # The function's name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "AND you could also add attributes to the function, such as a call counter... But this goes beyond the article."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Types in Python such as *int*, *str*, and *list* are also objects. They are classes that are instances of metaclasses."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Therefore, what is the type of **int**? In other words, what is the metaclass that created the **int** class?\n",
    "Is it **object**?   \n",
    "No, **object** is the parent class of **int**, not the class that created **int**. It is the class **int** inherits from, just like *SingletonChild* inherits from *Singleton*. But *Singleton* did not create *SingletonChild*. *Singleton* created variables **s1** and **s2**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'type'>\n"
     ]
    }
   ],
   "source": [
    "print(type(int))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Type** is the type of *int*. It is not just a function that displays a variable's type. It is a class that creates classes and thus a metaclass!\n",
    "\n",
    "But who created **type**?\n",
    "\n",
    "Can Python provide an answer to the why and how of the universe and of everything that is alive?\n",
    "\n",
    "Is the answer *Guido Van Rossum* or *42*?\n",
    "Let us wait no more for the answer. The answer to the Holy Grail of the existence of objects is there, all-ready! \n",
    "Let's ask the question!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class 'type'>\n"
     ]
    }
   ],
   "source": [
    "print(type(type))  # Then?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's *type*! *type* has created itself! It is the almighty class!\n",
    "\n",
    "The *type* class can thus be used to create variables that are classes!\n",
    "\n",
    "If we pass a single parameter to it, the variable's type is returned. Else, it will construct a class.\n",
    "\n",
    "Here are the parameters accepted when constructing a class:\n",
    "\n",
    "* The name of the class created\n",
    "* A tuple containing the parents\n",
    "* A dictionary containing the attributes and methods of the class"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code:\n",
    "    \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class '__main__.MyClass'>\n",
      "blue\n",
      "Hello man!\n",
      "(<class '__main__.MyClass'>, <class '__main__.A'>, <class '__main__.B'>, <class 'object'>)\n"
     ]
    }
   ],
   "source": [
    "class A(object):\n",
    "    pass\n",
    "\n",
    "class B(object):\n",
    "    pass\n",
    "\n",
    "MyClass = type(\"MyClass\",\n",
    "                (A, B),\n",
    "                {\"color\" : 'blue', \n",
    "                 'hello' : lambda self: 'Hello man!'}\n",
    "                )\n",
    "mc = MyClass()\n",
    "print(type(mc))\n",
    "print(MyClass.color)\n",
    "print(mc.hello())\n",
    "print(MyClass.__mro__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Is equivalent to the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class '__main__.MyClass'>\n",
      "blue\n",
      "Hello man!\n",
      "(<class '__main__.MyClass'>, <class '__main__.A'>, <class '__main__.B'>, <class 'object'>)\n"
     ]
    }
   ],
   "source": [
    "class A(object):\n",
    "    pass\n",
    "\n",
    "class B(object):\n",
    "    pass\n",
    "\n",
    "class MyClass(A, B):\n",
    "    color = \"blue\"\n",
    "    \n",
    "    def hello(self):\n",
    "        return \"Hello man!\"\n",
    "\n",
    "mc = MyClass()\n",
    "print(type(mc))\n",
    "print(MyClass.color)\n",
    "print(mc.hello())\n",
    "print(MyClass.__mro__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's pretty bluffing at first. However, it is not very practical as defining methods through a dictionary is not that elegant."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In summary, when you write:\n",
    "\n",
    "```python\n",
    "class MaClasse(object):\n",
    "    pass\n",
    "```\n",
    "\n",
    "Python executes:\n",
    "\n",
    "```python\n",
    "MaClasse = type(\"MaClasse\", (object, ), {} )\n",
    "```\n",
    "\n",
    "Which remains valid, but it is more comfortable to use the keyword **class**. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How do we create a metaclass?\n",
    "\n",
    "To do this, all that is needed is to create a class that inherits from **type**.\n",
    "\n",
    "```python\n",
    "class MyMetaClass(type):\n",
    "    pass\n",
    "```\n",
    "\n",
    "A metaclass is a class that creates classes like *type*. Thus, we could write:\n",
    "\n",
    "```python\n",
    "MyClass = MyMetaClass()\n",
    "my_object = MyClass()\n",
    "```\n",
    "\n",
    "Do not confuse:\n",
    "\n",
    "* A variable's type: It is the name of the class that created the variable\n",
    "* The parent of a class: It is the class from which your class inherits from, which can be consulted with `MyClass.__base__`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class '__main__.MyMetaClass'>\n",
      "<class '__main__.MyClass'>\n",
      "<class 'object'>\n"
     ]
    }
   ],
   "source": [
    "class MyMetaClass(type):\n",
    "    pass\n",
    "\n",
    "MyClass = MyMetaClass(\"MyClass\", (object,), {})\n",
    "my_object = MyClass()\n",
    "\n",
    "print(type(MyClass))\n",
    "print(type(my_object))\n",
    "print(MyClass.__base__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But this syntax is not that elegant.\n",
    "The [PEP3115](https://www.python.org/dev/peps/pep-3115/) presents the official syntax for defining a class based on a metaclass:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<class '__main__.MyMetaClass'>\n",
      "<class '__main__.MyClass'>\n",
      "<class 'object'>\n"
     ]
    }
   ],
   "source": [
    "class MyMetaClass(type):\n",
    "    pass\n",
    "\n",
    "class MyClass(object, metaclass=MyMetaClass):\n",
    "    pass\n",
    "\n",
    "print(type(MyClass))\n",
    "print(type(my_object))\n",
    "print(MyClass.__base__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to implement the Singleton class with a metaclass ?\n",
    "\n",
    "The idea is that if a class must have a `unique_instance` attribute, then all we need to do is initialize it in the metaclass. Thus, every class based on the metaclass will have this attribute without having the need to copy-paste the code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Details on the mechanics of creating objects in Python\n",
    "\n",
    "When we write:\n",
    "\n",
    "```python\n",
    "my_variable = MyClass()\n",
    "```\n",
    "\n",
    "* Python allocates the object in memory with  the `MyClass.__new__` function.\n",
    "* Then, it initializes the object the `MyClass.__init__` function.\n",
    "  The `__init__` function allows assigning attributes to the created object.\n",
    "\n",
    "But you know we can also call an object like a function if the object's class has the special `__class__` method defined.\n",
    "\n",
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Off we go Paul Pierre Jacqueline\n"
     ]
    }
   ],
   "source": [
    "class Vehicule:\n",
    "\n",
    "    def __call__(self, *args, **kwargs):\n",
    "        print(\"Off we go\", *args)\n",
    "\n",
    "v = Vehicule()\n",
    "v(\"Paul\", \"Pierre\", \"Jacqueline\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create a variable, you call the class like a normal function:\n",
    "\n",
    "`variable = MyClass()` \n",
    "\n",
    "This calls the metaclass' `__call__` method by passing it the class as the first parameter:\n",
    "\n",
    "* that creates the variable with `MyClass.__new__()`\n",
    "* then initializes the variable with `MyClass.__init__()`\n",
    "* then returns the variable "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's illustrate this with a concrete example...\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Creation of the metaclass\n",
      "Creation of the class\n",
      "In MetaClass.__new__\n",
      "In MetaClass.__init__ MyClass\n",
      "Creation of the variable\n",
      "In MetaClass.__call__ MyClass\n",
      "MyClass.__new__\n",
      "MyClass.__init__\n",
      "Calling the variable like a function\n",
      "MyClass.__call__\n",
      "What a beautiful mechanic...\n"
     ]
    }
   ],
   "source": [
    "print('Creation of the metaclass')\n",
    "class MetaClass(type):\n",
    "    \n",
    "    def __new__(cls, *args, **kwargs):\n",
    "        print(\"In MetaClass.__new__\")\n",
    "        return super().__new__(cls, *args, **kwargs)\n",
    "    \n",
    "    def __init__(cls, *args, **kwargs):\n",
    "        print(\"In MetaClass.__init__\", cls.__name__)\n",
    "        super().__init__(*args, **kwargs)\n",
    "    \n",
    "    def __call__(cls, *args, **kwargs):\n",
    "        print(\"In MetaClass.__call__\", cls.__name__)\n",
    "        return super().__call__(*args, **kwargs)\n",
    "        \n",
    "    \n",
    "print(\"Creation of the class\")\n",
    "class MyClass(object, metaclass=MetaClass):\n",
    "\n",
    "    def __new__(cls, *args, **kwargs):\n",
    "        print(\"MyClass.__new__\")\n",
    "        return super().__new__(cls, *args, **kwargs)\n",
    "\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        print(\"MyClass.__init__\")\n",
    "        super().__init__(*args, **kwargs)\n",
    "\n",
    "    def __call__(self, *args, **kwargs):\n",
    "        print(\"MyClass.__call__\")\n",
    "        print(*args, **kwargs)\n",
    "\n",
    "print(\"Creation of the variable\")\n",
    "i = MyClass()\n",
    "print(\"Calling the variable like a function\")\n",
    "i(\"What a beautiful mechanic...\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note** the usage of *cls* when calling *super()* for the `__new__` method and without *cls* for the other methods such as `__init__`.\n",
    "Indeed, the variable is not yet created when one calls `__new__` so you have to pass the attribute cls which does not represent the instance."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now write the metaclass **MetaSingleton** :\n",
    "\n",
    "* When we'll create a class based on this metaclass, it's `__new__` et `__init__` methods will be called\n",
    "* When we'll create a class instance based on the metaclass MetaSingleton, `MetaSingleton.__call__(Class)` will be called.\n",
    "This is where you must test the unique instance's existence\n",
    "* In the metaclass' `__init__` method, initialize the static attribute of the class. It will be easier this way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Extraordinary\n"
     ]
    }
   ],
   "source": [
    "class MetaSingleton(type):\n",
    "    \n",
    "    def __init__(cls, *args, **kwargs):\n",
    "        \"\"\"cls is the class created by the metaclass\"\"\"\n",
    "        # add single instance class attribute\n",
    "        cls.instance_unique = None\n",
    "\n",
    "    def __call__(cls, *args, **kwargs):\n",
    "        \n",
    "        # We create a unique instance if does not already exist\n",
    "        if cls.instance_unique is None:\n",
    "            cls.instance_unique = super().__call__(*args, **kwargs)\n",
    "            \n",
    "        return cls.instance_unique\n",
    "    \n",
    "    \n",
    "class Singleton(object, metaclass=MetaSingleton):\n",
    "    pass\n",
    "\n",
    "\n",
    "class SingletonChild(Singleton):\n",
    "    pass\n",
    "\n",
    "\n",
    "# Creating the singleton instances for the Singleton class\n",
    "s1 = Singleton()\n",
    "s2 = Singleton()\n",
    "\n",
    "assert s1 == s2\n",
    "assert s1 is s2\n",
    "assert id(s1) == id(s2)\n",
    "assert type(s1) == Singleton\n",
    "\n",
    "# Everything will be fine now!\n",
    "sc1 = SingletonChild()\n",
    "sc2 = SingletonChild()\n",
    "\n",
    "assert sc1 == sc2\n",
    "assert sc2 is sc1\n",
    "assert id(sc1) == id(sc2)\n",
    "\n",
    "assert type(sc1) == SingletonChild, \"I am not of the type expected\"\n",
    "\n",
    "print(\"Extraordinary\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here you are ready to build solid foundations...  \n",
    "But very sincerely, we rarely create metaclasses, unless we develop sophisticated frameworks like the Django ORM.\n",
    "\n",
    "If not professionally applied, this tutorial will have tried to give you an understanding of Python's internal mechanics.\n",
    "\n",
    "And as *Tim Peters* says: **It's deep magic!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To practice these concepts:\n",
    "\n",
    "* Try implementing a metaclass that manages an object counter.\n",
    "* Then, it decrements the counter once objects are destroyed...\n",
    "\n",
    "Hum, is it possible?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## To look further into the subject\n",
    "\n",
    "* A great [discussion thread about metaclasses on Stackoverflow](http://stackoverflow.com/questions/100003/what-is-a-metaclass-in-python)\n",
    "* Another [interesting tutorial on metaclasses](https://blog.ionelmc.ro/2015/02/09/understanding-python-metaclasses/)\n"
   ]
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}