diff --git a/advanced_topics/object_oriented_programming.ipynb b/advanced_topics/object_oriented_programming.ipynb
index 59974bc6c841755216aee1edb27bec52e95801d2..6ce41605fc589428e8462bc0d9ba33ea93930497 100644
--- a/advanced_topics/object_oriented_programming.ipynb
+++ b/advanced_topics/object_oriented_programming.ipynb
@@ -1052,10 +1052,10 @@
"The `NumberOperator` class has also overridden the `preprocess` method, to\n",
"ensure that all values handled by the `Operator` are numbers. This method gets\n",
"called within the `Operator.run` method - for a `NumberOperator` instance, the\n",
- "`NumberOperator.preprocess` method will get called<sup>1</sup>.\n",
+ "`NumberOperator.preprocess` method will get called<sup>3</sup>.\n",
"\n",
"\n",
- "> <sup>1</sup> When a sub-class overrides a base-class method, it is still\n",
+ "> <sup>3</sup> When a sub-class overrides a base-class method, it is still\n",
"> possible to access the base-class implementation [via the `super()`\n",
"> function](https://stackoverflow.com/a/4747427) (the preferred method), or by\n",
"> [explicitly calling the base-class\n",
@@ -1281,6 +1281,10 @@
"cell_type": "markdown",
"metadata": {},
"source": [
+ "> Simple classes such as the `Notifier` are sometimes referred to as\n",
+ " [_mixins_](https://en.wikipedia.org/wiki/Mixin).\n",
+ "\n",
+ "\n",
"If you wish to use multiple inheritance in your design, it is important to be\n",
"aware of the mechanism that Python uses to determine how base class methods\n",
"are called (and which base class method will be called, in the case of naming\n",
@@ -1658,7 +1662,8 @@
"\n",
"However, because a Python method can be written to accept any number or type\n",
"of arguments, it is very easy to to build your own overloading logic by\n",
- "writing a \"dispatch\" method. Here is YACE (Yet Another Contrived Example):"
+ "writing a \"dispatch\" method<sup>4</sup>. Here is YACE (Yet Another Contrived\n",
+ "Example):"
]
},
{
@@ -1697,6 +1702,12 @@
"cell_type": "markdown",
"metadata": {},
"source": [
+ "> <sup>4</sup>Another option is the [`functools.singledispatch`\n",
+ "> decorator](https://docs.python.org/3.5/library/functools.html#functools.singledispatch),\n",
+ "> which is more complicated, but may allow you to write your dispatch logic in\n",
+ "> a more concise manner.\n",
+ "\n",
+ "\n",
"<a class=\"anchor\" id=\"useful-references\"></a>\n",
"## Useful references\n",
"\n",
diff --git a/advanced_topics/object_oriented_programming.md b/advanced_topics/object_oriented_programming.md
index a180108b8a2f771d396b67b8d64a7c122607aa0a..e5504cf616955e1f41545526f339e15f22abb1ac 100644
--- a/advanced_topics/object_oriented_programming.md
+++ b/advanced_topics/object_oriented_programming.md
@@ -853,10 +853,10 @@ Here we are registering all of the functionality that is provided by the
The `NumberOperator` class has also overridden the `preprocess` method, to
ensure that all values handled by the `Operator` are numbers. This method gets
called within the `Operator.run` method - for a `NumberOperator` instance, the
-`NumberOperator.preprocess` method will get called<sup>1</sup>.
+`NumberOperator.preprocess` method will get called<sup>3</sup>.
-> <sup>1</sup> When a sub-class overrides a base-class method, it is still
+> <sup>3</sup> When a sub-class overrides a base-class method, it is still
> possible to access the base-class implementation [via the `super()`
> function](https://stackoverflow.com/a/4747427) (the preferred method), or by
> [explicitly calling the base-class
@@ -1024,6 +1024,11 @@ so.do('concat', '?')
print(so.run('did you notice that functions are objects too'))
```
+
+> Simple classes such as the `Notifier` are sometimes referred to as
+ [_mixins_](https://en.wikipedia.org/wiki/Mixin).
+
+
If you wish to use multiple inheritance in your design, it is important to be
aware of the mechanism that Python uses to determine how base class methods
are called (and which base class method will be called, in the case of naming
@@ -1361,7 +1366,8 @@ types) is used.
However, because a Python method can be written to accept any number or type
of arguments, it is very easy to to build your own overloading logic by
-writing a "dispatch" method. Here is YACE (Yet Another Contrived Example):
+writing a "dispatch" method<sup>4</sup>. Here is YACE (Yet Another Contrived
+Example):
```
@@ -1391,6 +1397,11 @@ print('Add three: {}'.format(a.add(1, 2, 3)))
print('Add four: {}'.format(a.add(1, 2, 3, 4)))
```
+> <sup>4</sup>Another option is the [`functools.singledispatch`
+> decorator](https://docs.python.org/3.5/library/functools.html#functools.singledispatch),
+> which is more complicated, but may allow you to write your dispatch logic in
+> a more concise manner.
+
<a class="anchor" id="useful-references"></a>
## Useful references
diff --git a/advanced_topics/operator_overloading.ipynb b/advanced_topics/operator_overloading.ipynb
new file mode 100644
index 0000000000000000000000000000000000000000..1b9ab7f1830010834183417e0799b2e22d744273
--- /dev/null
+++ b/advanced_topics/operator_overloading.ipynb
@@ -0,0 +1,731 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Operator overloading\n",
+ "\n",
+ "\n",
+ "> This practical assumes you are familiar with the basics of object-oriented\n",
+ "> programming in Python.\n",
+ "\n",
+ "\n",
+ "Operator overloading, in an object-oriented programming language, is the\n",
+ "process of customising the behaviour of _operators_ (e.g. `+`, `*`, `/` and\n",
+ "`-`) on user-defined types. This practical aims to show you that operator\n",
+ "overloading is __very__ easy to do in Python.\n",
+ "\n",
+ "\n",
+ "This practical gives a brief overview of the operators which you may be most\n",
+ "interested in implementing. However, there are many operators (and other\n",
+ "special methods) which you can support in your own classes - the [official\n",
+ "documentation](https://docs.python.org/3.5/reference/datamodel.html#basic-customization)\n",
+ "is the best reference if you are interested in learning more.\n",
+ "\n",
+ "\n",
+ "* [Overview](#overview)\n",
+ "* [Arithmetic operators](#arithmetic-operators)\n",
+ "* [Equality and comparison operators](#equality-and-comparison-operators)\n",
+ "* [The indexing operator `[]`](#the-indexing-operator)\n",
+ "* [The call operator `()`](#the-call-operator)\n",
+ "* [The dot operator `.`](#the-dot-operator)\n",
+ "\n",
+ "\n",
+ "<a class=\"anchor\" id=\"overview\"></a>\n",
+ "## Overview\n",
+ "\n",
+ "\n",
+ "In Python, when you add two numbers together:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "a = 5\n",
+ "b = 10\n",
+ "r = a + b\n",
+ "print(r)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "What actually goes on behind the scenes is this:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "r = a.__add__(b)\n",
+ "print(r)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In other words, whenever you use the `+` operator on two variables (the\n",
+ "operands to the `+` operator), the Python interpreter calls the `__add__`\n",
+ "method of the first operand (`a`), and passes the second operand (`b`) as an\n",
+ "argument.\n",
+ "\n",
+ "\n",
+ "So it is very easy to use the `+` operator with our own classes - all we have\n",
+ "to do is implement a method called `__add__`.\n",
+ "\n",
+ "\n",
+ "<a class=\"anchor\" id=\"arithmetic-operators\"></a>\n",
+ "## Arithmetic operators\n",
+ "\n",
+ "\n",
+ "Let's play with an example - a class which represents a 2D vector:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Vector2D(object):\n",
+ " def __init__(self, x, y):\n",
+ " self.x = x\n",
+ " self.y = y\n",
+ "\n",
+ " def __str__(self):\n",
+ " return 'Vector2D({}, {})'.format(self.x, self.y)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "> Note that we have implemented the special `__str__` method, which allows our\n",
+ "> `Vector2D` instances to be converted into strings.\n",
+ "\n",
+ "\n",
+ "If we try to use the `+` operator on this class, we are bound to get an error:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "v1 = Vector2D(2, 3)\n",
+ "v2 = Vector2D(4, 5)\n",
+ "print(v1 + v2)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "But all we need to do to support the `+` operator is to implement a method\n",
+ "called `__add__`:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Vector2D(object):\n",
+ " def __init__(self, x, y):\n",
+ " self.x = x\n",
+ " self.y = y\n",
+ "\n",
+ " def __str__(self):\n",
+ " return 'Vector2D({}, {})'.format(self.x, self.y)\n",
+ "\n",
+ " def __add__(self, other):\n",
+ " return Vector2D(self.x + other.x,\n",
+ " self.y + other.y)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "And now we can use `+` on `Vector2D` objects - it's that easy:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "v1 = Vector2D(2, 3)\n",
+ "v2 = Vector2D(4, 5)\n",
+ "print('{} + {} = {}'.format(v1, v2, v1 + v2))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Our `__add__` method creates and returns a new `Vector2D` which contains the\n",
+ "sum of the `x` and `y` components of the `Vector2D` on which it is called, and\n",
+ "the `Vector2D` which is passed in. We could also make the `__add__` method\n",
+ "work with scalars, by extending its definition a bit:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Vector2D(object):\n",
+ " def __init__(self, x, y):\n",
+ " self.x = x\n",
+ " self.y = y\n",
+ "\n",
+ " def __add__(self, other):\n",
+ " if isinstance(other, Vector2D):\n",
+ " return Vector2D(self.x + other.x,\n",
+ " self.y + other.y)\n",
+ " else:\n",
+ " return Vector2D(self.x + other, self.y + other)\n",
+ "\n",
+ " def __str__(self):\n",
+ " return 'Vector2D({}, {})'.format(self.x, self.y)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "So now we can add both `Vector2D` instances and scalars numbers together:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "v1 = Vector2D(2, 3)\n",
+ "v2 = Vector2D(4, 5)\n",
+ "n = 6\n",
+ "\n",
+ "print('{} + {} = {}'.format(v1, v2, v1 + v2))\n",
+ "print('{} + {} = {}'.format(v1, n, v1 + n))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Other numeric and logical operators can be supported by implementing the\n",
+ "appropriate method, for example:\n",
+ "\n",
+ "- Multiplication (`*`): `__mul__`\n",
+ "- Division (`/`): `__div__`\n",
+ "- Negation (`-`): `__neg__`\n",
+ "- In-place addition (`+=`): `__iadd__`\n",
+ "- Exclusive or (`^`): `__xor__`\n",
+ "\n",
+ "\n",
+ "Take a look at the [official\n",
+ "documentation](https://docs.python.org/3.5/reference/datamodel.html#emulating-numeric-types)\n",
+ "for a full list of the arithmetic and logical operators that your classes can\n",
+ "support.\n",
+ "\n",
+ "\n",
+ "<a class=\"anchor\" id=\"equality-and-comparison-operators\"></a>\n",
+ "## Equality and comparison operators\n",
+ "\n",
+ "\n",
+ "Adding support for equality (`==`, `!=`) and comparison (e.g. `>=`) operators\n",
+ "is just as easy. Imagine that we have a class called `Label`, which represents\n",
+ "a label in a lookup table. Our `Label` has an integer label, a name, and an\n",
+ "RGB colour:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Label(object):\n",
+ " def __init__(self, label, name, colour):\n",
+ " self.label = label\n",
+ " self.name = name\n",
+ " self.colour = colour"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In order to ensure that a list of `Label` objects is ordered by their label\n",
+ "values, we can implement a set of functions, so that `Label` classes can be\n",
+ "compared using the standard comparison operators:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import functools\n",
+ "\n",
+ "# Don't worry about this statement\n",
+ "# just yet - it is explained below\n",
+ "@functools.total_ordering\n",
+ "\n",
+ "class Label(object):\n",
+ " def __init__(self, label, name, colour):\n",
+ " self.label = label\n",
+ " self.name = name\n",
+ " self.colour = colour\n",
+ "\n",
+ " def __str__(self):\n",
+ " rgb = ''.join(['{:02x}'.format(c) for c in self.colour])\n",
+ " return 'Label({}, {}, #{})'.format(self.label, self.name, rgb)\n",
+ "\n",
+ " def __repr__(self):\n",
+ " return str(self)\n",
+ "\n",
+ " # implement Label == Label\n",
+ " def __eq__(self, other):\n",
+ " return self.label == other.label\n",
+ "\n",
+ " # implement Label < Label\n",
+ " def __lt__(self, other):\n",
+ " return self.label < other.label"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "> We also added `__str__` and `__repr__` methods to the `Label` class so that\n",
+ "> `Label` instances will be printed nicely.\n",
+ "\n",
+ "\n",
+ "Now we can compare and sort our `Label` instances:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "l1 = Label(1, 'Parietal', (255, 0, 0))\n",
+ "l2 = Label(2, 'Occipital', ( 0, 255, 0))\n",
+ "l3 = Label(3, 'Temporal', ( 0, 0, 255))\n",
+ "\n",
+ "print('{} > {}: {}'.format(l1, l2, l1 > l2))\n",
+ "print('{} < {}: {}'.format(l1, l3, l1 < l3))\n",
+ "print('{} != {}: {}'.format(l2, l3, l2 != l3))\n",
+ "print(sorted((l3, l1, l2)))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The\n",
+ "[`@functools.total_ordering`](https://docs.python.org/3.5/library/functools.html#functools.total_ordering)\n",
+ "is a convenience\n",
+ "[decorator](https://docs.python.org/3.5/glossary.html#term-decorator) which,\n",
+ "given a class that implements equality and a single comparison function\n",
+ "(`__lt__` in the above code), will \"fill in\" the remainder of the comparison\n",
+ "operators. If you need very specific or complicated behaviour, then you can\n",
+ "provide methods for _all_ of the comparison operators, e.g. `__gt__` for `>`,\n",
+ "`__ge__` for `>=`, etc.).\n",
+ "\n",
+ "\n",
+ "> Decorators are introduced in another practical.\n",
+ "\n",
+ "\n",
+ "But if you just want the operators to work in the conventional manner, you can\n",
+ "simply use the `@functools.total_ordering` decorator, and provide `__eq__`,\n",
+ "and just one of `__lt__`, `__le__`, `__gt__` or `__ge__`.\n",
+ "\n",
+ "\n",
+ "Refer to the [official\n",
+ "documentation](https://docs.python.org/3.5/reference/datamodel.html#object.__lt__)\n",
+ "for all of the details on supporting comparison operators.\n",
+ "\n",
+ "\n",
+ "> You may see the `__cmp__` method in older code bases - this provides a\n",
+ "> C-style comparison function which returns `<0`, `0`, or `>0` based on\n",
+ "> comparing two items. This has been superseded by the rich comparison\n",
+ "> operators introduced here, and is no longer supported in Python 3.\n",
+ "\n",
+ "\n",
+ "<a class=\"anchor\" id=\"the-indexing-operator\"></a>\n",
+ "## The indexing operator `[]`\n",
+ "\n",
+ "\n",
+ "The indexing operator (`[]`) is generally used by \"container\" types, such as\n",
+ "the built-in `list` and `dict` classes.\n",
+ "\n",
+ "\n",
+ "At its essence, there are only three types of behaviours that are possible\n",
+ "with the `[]` operator. All that is needed to support them are to implement\n",
+ "three special methods in your class, regardless of whether your class will be\n",
+ "indexed by sequential integers (like a `list`) or by\n",
+ "[hashable](https://docs.python.org/3.5/glossary.html#term-hashable) values\n",
+ "(like a `dict`):\n",
+ "\n",
+ "\n",
+ "- __Retrieval__ is performed by the `__getitem__` method\n",
+ "- __Assignment__ is performed by the `__setitem__` method\n",
+ "- __Deletion__ is performed by the `__delitem__` method\n",
+ "\n",
+ "\n",
+ "Note that, if you implement these methods in your own class, there is no\n",
+ "requirement for them to actually provide any form of data storage or\n",
+ "retrieval. However if you don't, you will probably confuse users of your code\n",
+ "who are used to how the `list` and `dict` types work. Whenever you deviate\n",
+ "from conventional behaviour, make sure you explain it well in your\n",
+ "documentation!\n",
+ "\n",
+ "\n",
+ "The following contrived example demonstrates all three behaviours:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class TwoTimes(object):\n",
+ "\n",
+ " def __init__(self):\n",
+ " self.__deleted = set()\n",
+ " self.__assigned = {}\n",
+ "\n",
+ " def __getitem__(self, key):\n",
+ " if key in self.__deleted:\n",
+ " raise KeyError('{} has been deleted!'.format(key))\n",
+ " elif key in self.__assigned:\n",
+ " return self.__assigned[key]\n",
+ " else:\n",
+ " return key * 2\n",
+ "\n",
+ " def __setitem__(self, key, value):\n",
+ " self.__assigned[key] = value\n",
+ "\n",
+ " def __delitem__(self, key):\n",
+ " self.__deleted.add(key)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Guess what happens whenever we index a `TwoTimes` object:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "tt = TwoTimes()\n",
+ "print('TwoTimes[{}] = {}'.format(2, tt[2]))\n",
+ "print('TwoTimes[{}] = {}'.format(6, tt[6]))\n",
+ "print('TwoTimes[{}] = {}'.format('abc', tt['abc']))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The `TwoTimes` class allows us to override the value for a specific key:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print(tt[4])\n",
+ "tt[4] = 'this is not 4 * 4'\n",
+ "print(tt[4])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "And we can also \"delete\" keys:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "print(tt['12345'])\n",
+ "del tt['12345']\n",
+ "\n",
+ "# this is going to raise an error\n",
+ "print(tt['12345'])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "If you wish to support the Python `start:stop:step` [slice\n",
+ "notation](https://docs.python.org/3.5/library/functions.html#slice), you\n",
+ "simply need to write your `__getitem__` and `__setitem__` methods so that they\n",
+ "can detect `slice` objects:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class TwoTimes(object):\n",
+ "\n",
+ " def __init__(self, max):\n",
+ " self.__max = max\n",
+ "\n",
+ " def __getitem__(self, key):\n",
+ " if isinstance(key, slice):\n",
+ " start = key.start or 0\n",
+ " stop = key.stop or self.__max\n",
+ " step = key.step or 1\n",
+ " else:\n",
+ " start = key\n",
+ " stop = key + 1\n",
+ " step = 1\n",
+ "\n",
+ " return [i * 2 for i in range(start, stop, step)]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now we can \"slice\" a `TwoTimes` instance:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "tt = TwoTimes(10)\n",
+ "\n",
+ "print(tt[5])\n",
+ "print(tt[3:7])\n",
+ "print(tt[::2])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "> It is possible to sub-class the built-in `list` and `dict` classes if you\n",
+ "> wish to extend their functionality in some way. However, if you are writing\n",
+ "> a class that should mimic the one of the `list` or `dict` classes, but work\n",
+ "> in a different way internally (e.g. a `dict`-like object which uses a\n",
+ "> different hashing algorithm), the `Sequence` and `MutableMapping` classes\n",
+ "> are [a better choice](https://stackoverflow.com/a/7148602) - you can find\n",
+ "> them in the\n",
+ "> [`collections.abc`](https://docs.python.org/3.5/library/collections.abc.html)\n",
+ "> module.\n",
+ "\n",
+ "\n",
+ "<a class=\"anchor\" id=\"the-call-operator\"></a>\n",
+ "## The call operator `()`\n",
+ "\n",
+ "\n",
+ "Remember how everything in Python is an object, even functions? When you call\n",
+ "a function, a method called `__call__` is called on the function object. We can\n",
+ "implement the `__call__` method on our own class, which will allow us to \"call\"\n",
+ "objects as if they are functions.\n",
+ "\n",
+ "\n",
+ "For example, the `TimedFunction` class allows us to calculate the execution\n",
+ "time of any function:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import time\n",
+ "\n",
+ "class TimedFunction(object):\n",
+ "\n",
+ " def __init__(self, func):\n",
+ " self.func = func\n",
+ "\n",
+ " def __call__(self, *args, **kwargs):\n",
+ " print('Timing {}...'.format(self.func.__name__))\n",
+ "\n",
+ " start = time.time()\n",
+ " retval = self.func(*args, **kwargs)\n",
+ " end = time.time()\n",
+ "\n",
+ " print('Elapsed time: {:0.2f} seconds'.format(end - start))\n",
+ " return retval"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Let's see how the `TimedFunction` behaves:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import numpy as np\n",
+ "import numpy.linalg as npla\n",
+ "\n",
+ "def inverse(data):\n",
+ " return npla.inv(data)\n",
+ "\n",
+ "tf = TimedFunction(inverse)\n",
+ "data = np.random.random((5000, 5000))\n",
+ "\n",
+ "# Wait a few seconds after\n",
+ "# running this code block!\n",
+ "inv = tf(data)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "> The `TimedFunction` class is conceptually very similar to a\n",
+ "> [decorator](https://docs.python.org/3.5/glossary.html#term-decorator) -\n",
+ "> decorators are covered in another practical.\n",
+ "\n",
+ "\n",
+ "<a class=\"anchor\" id=\"the-dot-operator\"></a>\n",
+ "## The dot operator `.`\n",
+ "\n",
+ "\n",
+ "Python allows us to override the `.` (dot) operator which is used to access\n",
+ "the attributes and methods of an object. This is very powerful, but is also\n",
+ "quite a niche feature, and it is easy to trip yourself up, so if you wish to\n",
+ "use this in your own project, make sure that you carefully read (and\n",
+ "understand) [the\n",
+ "documentation](https://docs.python.org/3.5/reference/datamodel.html#customizing-attribute-access),\n",
+ "and test your code comprehensively!\n",
+ "\n",
+ "\n",
+ "For this example, we need a little background information. OpenGL includes\n",
+ "the native data types `vec2`, `vec3`, and `vec4`, which can be used to\n",
+ "represent 2, 3, or 4 component vectors respectively. These data types have a\n",
+ "neat feature called [_swizzling_][glslref], which allows you to access any\n",
+ "component (`x`,`y`, `z`, `w` for vectors, or `r`, `g`, `b`, `a` for colours)\n",
+ "in any order, with a syntax similar to attribute access in Python.\n",
+ "\n",
+ "\n",
+ "[glslref]: https://www.khronos.org/opengl/wiki/Data_Type_(GLSL)#Swizzling\n",
+ "\n",
+ "\n",
+ "So here is an example which implements this swizzle-style attribute access on\n",
+ "a class called `Vector`, in which we have customised the behaviour of the `.`\n",
+ "operator:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Vector(object):\n",
+ " def __init__(self, xyz):\n",
+ " self.__xyz = list(xyz)\n",
+ "\n",
+ " def __str__(self):\n",
+ " return 'Vector({})'.format(self.__xyz)\n",
+ "\n",
+ " def __getattr__(self, key):\n",
+ "\n",
+ " # Swizzling behaviour only occurs when\n",
+ " # the attribute name is entirely comprised\n",
+ " # of 'x', 'y', and 'z'.\n",
+ " if not all([c in 'xyz' for c in key]):\n",
+ " raise AttributeError(key)\n",
+ "\n",
+ " key = ['xyz'.index(c) for c in key]\n",
+ " return [self.__xyz[c] for c in key]\n",
+ "\n",
+ " def __setattr__(self, key, value):\n",
+ "\n",
+ " # Restrict swizzling behaviour as above\n",
+ " if not all([c in 'xyz' for c in key]):\n",
+ " return super().__setattr__(key, value)\n",
+ "\n",
+ " if len(key) == 1:\n",
+ " value = (value,)\n",
+ "\n",
+ " idxs = ['xyz'.index(c) for c in key]\n",
+ "\n",
+ " for i, v in sorted(zip(idxs, value)):\n",
+ " self.__xyz[i] = v\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "And here it is in action:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "v = Vector((1, 2, 3))\n",
+ "\n",
+ "print('v: ', v)\n",
+ "print('xyz: ', v.xyz)\n",
+ "print('yz: ', v.zy)\n",
+ "print('xx: ', v.xx)\n",
+ "\n",
+ "v.xz = 10, 30\n",
+ "print(v)\n",
+ "v.y = 20\n",
+ "print(v)"
+ ]
+ }
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/advanced_topics/operator_overloading.md b/advanced_topics/operator_overloading.md
new file mode 100644
index 0000000000000000000000000000000000000000..142368fcee5807335115158025c9679362721ec1
--- /dev/null
+++ b/advanced_topics/operator_overloading.md
@@ -0,0 +1,555 @@
+# Operator overloading
+
+
+> This practical assumes you are familiar with the basics of object-oriented
+> programming in Python.
+
+
+Operator overloading, in an object-oriented programming language, is the
+process of customising the behaviour of _operators_ (e.g. `+`, `*`, `/` and
+`-`) on user-defined types. This practical aims to show you that operator
+overloading is __very__ easy to do in Python.
+
+
+This practical gives a brief overview of the operators which you may be most
+interested in implementing. However, there are many operators (and other
+special methods) which you can support in your own classes - the [official
+documentation](https://docs.python.org/3.5/reference/datamodel.html#basic-customization)
+is the best reference if you are interested in learning more.
+
+
+* [Overview](#overview)
+* [Arithmetic operators](#arithmetic-operators)
+* [Equality and comparison operators](#equality-and-comparison-operators)
+* [The indexing operator `[]`](#the-indexing-operator)
+* [The call operator `()`](#the-call-operator)
+* [The dot operator `.`](#the-dot-operator)
+
+
+<a class="anchor" id="overview"></a>
+## Overview
+
+
+In Python, when you add two numbers together:
+
+
+```
+a = 5
+b = 10
+r = a + b
+print(r)
+```
+
+
+What actually goes on behind the scenes is this:
+
+
+```
+r = a.__add__(b)
+print(r)
+```
+
+
+In other words, whenever you use the `+` operator on two variables (the
+operands to the `+` operator), the Python interpreter calls the `__add__`
+method of the first operand (`a`), and passes the second operand (`b`) as an
+argument.
+
+
+So it is very easy to use the `+` operator with our own classes - all we have
+to do is implement a method called `__add__`.
+
+
+<a class="anchor" id="arithmetic-operators"></a>
+## Arithmetic operators
+
+
+Let's play with an example - a class which represents a 2D vector:
+
+
+```
+class Vector2D(object):
+ def __init__(self, x, y):
+ self.x = x
+ self.y = y
+
+ def __str__(self):
+ return 'Vector2D({}, {})'.format(self.x, self.y)
+```
+
+
+> Note that we have implemented the special `__str__` method, which allows our
+> `Vector2D` instances to be converted into strings.
+
+
+If we try to use the `+` operator on this class, we are bound to get an error:
+
+
+```
+v1 = Vector2D(2, 3)
+v2 = Vector2D(4, 5)
+print(v1 + v2)
+```
+
+
+But all we need to do to support the `+` operator is to implement a method
+called `__add__`:
+
+
+```
+class Vector2D(object):
+ def __init__(self, x, y):
+ self.x = x
+ self.y = y
+
+ def __str__(self):
+ return 'Vector2D({}, {})'.format(self.x, self.y)
+
+ def __add__(self, other):
+ return Vector2D(self.x + other.x,
+ self.y + other.y)
+```
+
+
+And now we can use `+` on `Vector2D` objects - it's that easy:
+
+
+```
+v1 = Vector2D(2, 3)
+v2 = Vector2D(4, 5)
+print('{} + {} = {}'.format(v1, v2, v1 + v2))
+```
+
+
+Our `__add__` method creates and returns a new `Vector2D` which contains the
+sum of the `x` and `y` components of the `Vector2D` on which it is called, and
+the `Vector2D` which is passed in. We could also make the `__add__` method
+work with scalars, by extending its definition a bit:
+
+
+```
+class Vector2D(object):
+ def __init__(self, x, y):
+ self.x = x
+ self.y = y
+
+ def __add__(self, other):
+ if isinstance(other, Vector2D):
+ return Vector2D(self.x + other.x,
+ self.y + other.y)
+ else:
+ return Vector2D(self.x + other, self.y + other)
+
+ def __str__(self):
+ return 'Vector2D({}, {})'.format(self.x, self.y)
+```
+
+
+So now we can add both `Vector2D` instances and scalars numbers together:
+
+
+```
+v1 = Vector2D(2, 3)
+v2 = Vector2D(4, 5)
+n = 6
+
+print('{} + {} = {}'.format(v1, v2, v1 + v2))
+print('{} + {} = {}'.format(v1, n, v1 + n))
+```
+
+
+Other numeric and logical operators can be supported by implementing the
+appropriate method, for example:
+
+- Multiplication (`*`): `__mul__`
+- Division (`/`): `__div__`
+- Negation (`-`): `__neg__`
+- In-place addition (`+=`): `__iadd__`
+- Exclusive or (`^`): `__xor__`
+
+
+Take a look at the [official
+documentation](https://docs.python.org/3.5/reference/datamodel.html#emulating-numeric-types)
+for a full list of the arithmetic and logical operators that your classes can
+support.
+
+
+<a class="anchor" id="equality-and-comparison-operators"></a>
+## Equality and comparison operators
+
+
+Adding support for equality (`==`, `!=`) and comparison (e.g. `>=`) operators
+is just as easy. Imagine that we have a class called `Label`, which represents
+a label in a lookup table. Our `Label` has an integer label, a name, and an
+RGB colour:
+
+
+```
+class Label(object):
+ def __init__(self, label, name, colour):
+ self.label = label
+ self.name = name
+ self.colour = colour
+```
+
+
+In order to ensure that a list of `Label` objects is ordered by their label
+values, we can implement a set of functions, so that `Label` classes can be
+compared using the standard comparison operators:
+
+
+```
+import functools
+
+# Don't worry about this statement
+# just yet - it is explained below
+@functools.total_ordering
+
+class Label(object):
+ def __init__(self, label, name, colour):
+ self.label = label
+ self.name = name
+ self.colour = colour
+
+ def __str__(self):
+ rgb = ''.join(['{:02x}'.format(c) for c in self.colour])
+ return 'Label({}, {}, #{})'.format(self.label, self.name, rgb)
+
+ def __repr__(self):
+ return str(self)
+
+ # implement Label == Label
+ def __eq__(self, other):
+ return self.label == other.label
+
+ # implement Label < Label
+ def __lt__(self, other):
+ return self.label < other.label
+```
+
+
+> We also added `__str__` and `__repr__` methods to the `Label` class so that
+> `Label` instances will be printed nicely.
+
+
+Now we can compare and sort our `Label` instances:
+
+
+```
+l1 = Label(1, 'Parietal', (255, 0, 0))
+l2 = Label(2, 'Occipital', ( 0, 255, 0))
+l3 = Label(3, 'Temporal', ( 0, 0, 255))
+
+print('{} > {}: {}'.format(l1, l2, l1 > l2))
+print('{} < {}: {}'.format(l1, l3, l1 < l3))
+print('{} != {}: {}'.format(l2, l3, l2 != l3))
+print(sorted((l3, l1, l2)))
+```
+
+
+The
+[`@functools.total_ordering`](https://docs.python.org/3.5/library/functools.html#functools.total_ordering)
+is a convenience
+[decorator](https://docs.python.org/3.5/glossary.html#term-decorator) which,
+given a class that implements equality and a single comparison function
+(`__lt__` in the above code), will "fill in" the remainder of the comparison
+operators. If you need very specific or complicated behaviour, then you can
+provide methods for _all_ of the comparison operators, e.g. `__gt__` for `>`,
+`__ge__` for `>=`, etc.).
+
+
+> Decorators are introduced in another practical.
+
+
+But if you just want the operators to work in the conventional manner, you can
+simply use the `@functools.total_ordering` decorator, and provide `__eq__`,
+and just one of `__lt__`, `__le__`, `__gt__` or `__ge__`.
+
+
+Refer to the [official
+documentation](https://docs.python.org/3.5/reference/datamodel.html#object.__lt__)
+for all of the details on supporting comparison operators.
+
+
+> You may see the `__cmp__` method in older code bases - this provides a
+> C-style comparison function which returns `<0`, `0`, or `>0` based on
+> comparing two items. This has been superseded by the rich comparison
+> operators introduced here, and is no longer supported in Python 3.
+
+
+<a class="anchor" id="the-indexing-operator"></a>
+## The indexing operator `[]`
+
+
+The indexing operator (`[]`) is generally used by "container" types, such as
+the built-in `list` and `dict` classes.
+
+
+At its essence, there are only three types of behaviours that are possible
+with the `[]` operator. All that is needed to support them are to implement
+three special methods in your class, regardless of whether your class will be
+indexed by sequential integers (like a `list`) or by
+[hashable](https://docs.python.org/3.5/glossary.html#term-hashable) values
+(like a `dict`):
+
+
+- __Retrieval__ is performed by the `__getitem__` method
+- __Assignment__ is performed by the `__setitem__` method
+- __Deletion__ is performed by the `__delitem__` method
+
+
+Note that, if you implement these methods in your own class, there is no
+requirement for them to actually provide any form of data storage or
+retrieval. However if you don't, you will probably confuse users of your code
+who are used to how the `list` and `dict` types work. Whenever you deviate
+from conventional behaviour, make sure you explain it well in your
+documentation!
+
+
+The following contrived example demonstrates all three behaviours:
+
+
+```
+class TwoTimes(object):
+
+ def __init__(self):
+ self.__deleted = set()
+ self.__assigned = {}
+
+ def __getitem__(self, key):
+ if key in self.__deleted:
+ raise KeyError('{} has been deleted!'.format(key))
+ elif key in self.__assigned:
+ return self.__assigned[key]
+ else:
+ return key * 2
+
+ def __setitem__(self, key, value):
+ self.__assigned[key] = value
+
+ def __delitem__(self, key):
+ self.__deleted.add(key)
+```
+
+
+Guess what happens whenever we index a `TwoTimes` object:
+
+
+```
+tt = TwoTimes()
+print('TwoTimes[{}] = {}'.format(2, tt[2]))
+print('TwoTimes[{}] = {}'.format(6, tt[6]))
+print('TwoTimes[{}] = {}'.format('abc', tt['abc']))
+```
+
+
+The `TwoTimes` class allows us to override the value for a specific key:
+
+
+```
+print(tt[4])
+tt[4] = 'this is not 4 * 4'
+print(tt[4])
+```
+
+
+And we can also "delete" keys:
+
+
+```
+print(tt['12345'])
+del tt['12345']
+
+# this is going to raise an error
+print(tt['12345'])
+```
+
+
+If you wish to support the Python `start:stop:step` [slice
+notation](https://docs.python.org/3.5/library/functions.html#slice), you
+simply need to write your `__getitem__` and `__setitem__` methods so that they
+can detect `slice` objects:
+
+
+```
+class TwoTimes(object):
+
+ def __init__(self, max):
+ self.__max = max
+
+ def __getitem__(self, key):
+ if isinstance(key, slice):
+ start = key.start or 0
+ stop = key.stop or self.__max
+ step = key.step or 1
+ else:
+ start = key
+ stop = key + 1
+ step = 1
+
+ return [i * 2 for i in range(start, stop, step)]
+```
+
+
+Now we can "slice" a `TwoTimes` instance:
+
+
+```
+tt = TwoTimes(10)
+
+print(tt[5])
+print(tt[3:7])
+print(tt[::2])
+```
+
+
+> It is possible to sub-class the built-in `list` and `dict` classes if you
+> wish to extend their functionality in some way. However, if you are writing
+> a class that should mimic the one of the `list` or `dict` classes, but work
+> in a different way internally (e.g. a `dict`-like object which uses a
+> different hashing algorithm), the `Sequence` and `MutableMapping` classes
+> are [a better choice](https://stackoverflow.com/a/7148602) - you can find
+> them in the
+> [`collections.abc`](https://docs.python.org/3.5/library/collections.abc.html)
+> module.
+
+
+<a class="anchor" id="the-call-operator"></a>
+## The call operator `()`
+
+
+Remember how everything in Python is an object, even functions? When you call
+a function, a method called `__call__` is called on the function object. We can
+implement the `__call__` method on our own class, which will allow us to "call"
+objects as if they are functions.
+
+
+For example, the `TimedFunction` class allows us to calculate the execution
+time of any function:
+
+
+```
+import time
+
+class TimedFunction(object):
+
+ def __init__(self, func):
+ self.func = func
+
+ def __call__(self, *args, **kwargs):
+ print('Timing {}...'.format(self.func.__name__))
+
+ start = time.time()
+ retval = self.func(*args, **kwargs)
+ end = time.time()
+
+ print('Elapsed time: {:0.2f} seconds'.format(end - start))
+ return retval
+```
+
+
+Let's see how the `TimedFunction` behaves:
+
+
+```
+import numpy as np
+import numpy.linalg as npla
+
+def inverse(data):
+ return npla.inv(data)
+
+tf = TimedFunction(inverse)
+data = np.random.random((5000, 5000))
+
+# Wait a few seconds after
+# running this code block!
+inv = tf(data)
+```
+
+
+> The `TimedFunction` class is conceptually very similar to a
+> [decorator](https://docs.python.org/3.5/glossary.html#term-decorator) -
+> decorators are covered in another practical.
+
+
+<a class="anchor" id="the-dot-operator"></a>
+## The dot operator `.`
+
+
+Python allows us to override the `.` (dot) operator which is used to access
+the attributes and methods of an object. This is very powerful, but is also
+quite a niche feature, and it is easy to trip yourself up, so if you wish to
+use this in your own project, make sure that you carefully read (and
+understand) [the
+documentation](https://docs.python.org/3.5/reference/datamodel.html#customizing-attribute-access),
+and test your code comprehensively!
+
+
+For this example, we need a little background information. OpenGL includes
+the native data types `vec2`, `vec3`, and `vec4`, which can be used to
+represent 2, 3, or 4 component vectors respectively. These data types have a
+neat feature called [_swizzling_][glslref], which allows you to access any
+component (`x`,`y`, `z`, `w` for vectors, or `r`, `g`, `b`, `a` for colours)
+in any order, with a syntax similar to attribute access in Python.
+
+
+[glslref]: https://www.khronos.org/opengl/wiki/Data_Type_(GLSL)#Swizzling
+
+
+So here is an example which implements this swizzle-style attribute access on
+a class called `Vector`, in which we have customised the behaviour of the `.`
+operator:
+
+
+```
+class Vector(object):
+ def __init__(self, xyz):
+ self.__xyz = list(xyz)
+
+ def __str__(self):
+ return 'Vector({})'.format(self.__xyz)
+
+ def __getattr__(self, key):
+
+ # Swizzling behaviour only occurs when
+ # the attribute name is entirely comprised
+ # of 'x', 'y', and 'z'.
+ if not all([c in 'xyz' for c in key]):
+ raise AttributeError(key)
+
+ key = ['xyz'.index(c) for c in key]
+ return [self.__xyz[c] for c in key]
+
+ def __setattr__(self, key, value):
+
+ # Restrict swizzling behaviour as above
+ if not all([c in 'xyz' for c in key]):
+ return super().__setattr__(key, value)
+
+ if len(key) == 1:
+ value = (value,)
+
+ idxs = ['xyz'.index(c) for c in key]
+
+ for i, v in sorted(zip(idxs, value)):
+ self.__xyz[i] = v
+
+```
+
+
+And here it is in action:
+
+
+```
+v = Vector((1, 2, 3))
+
+print('v: ', v)
+print('xyz: ', v.xyz)
+print('yz: ', v.zy)
+print('xx: ', v.xx)
+
+v.xz = 10, 30
+print(v)
+v.y = 20
+print(v)
+```