1 files changed, 393 insertions, 60 deletions

diff --git a/notebooks/python/python_intro.ipynb b/notebooks/python/python_intro.ipynb
index a2acfbc..3c49a14 100644
--- a/notebooks/python/python_intro.ipynb
+++ b/notebooks/python/python_intro.ipynb
@@ -62,7 +62,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 96,
+   "execution_count": 50,
    "id": "54c9e132-30b0-41bf-97e9-0e8b94f3d202",
    "metadata": {},
    "outputs": [],
@@ -109,7 +109,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 97,
+   "execution_count": 51,
    "id": "bd6134d9-cc0e-4b45-b6b3-50210f6395e2",
    "metadata": {},
    "outputs": [],
@@ -122,7 +122,8 @@
     "\n",
     "i = 6  # int, same as int('6'), immutable\n",
     "\n",
-    "f = 0.1  # float, same as float('0.1'), immutable\n",
+    "f = 0.1  # float, same as float('0.1'), immutable, Note!!: Floats have a fixed size,\n",
+    "# hence they don't necessarily behave they way we expect from math class.\n",
     "\n",
     "b = False  # bool, same as bool(0), bool(''), bool(None)... immutable / constant\n",
     "\n",
@@ -138,6 +139,205 @@
    ]
   },
   {
+   "cell_type": "code",
+   "execution_count": 52,
+   "id": "cd2b7f98-ea16-49e2-9d19-f37266bd4f3a",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "'can be written like this'\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'foo bar'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "works just fine\n",
+      "works\n",
+      "just\n",
+      "fine\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'S'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'t'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'tatnett'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'tatnet'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'ett'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'tte'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "False"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "b'B\\xc3\\x98!'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'BØ!'"
+      ]
+     },
+     "execution_count": 52,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Strings and bytes\n",
+    "\n",
+    "# apart from other programming languages (PHP, Perl), the next two lines are virtually equal in Python\n",
+    "s = 'can be written like this'  # ... and should be written like this\n",
+    "s = \"can be written like this\"\n",
+    "print(repr(s))  # the official Python repr uses single quotes\n",
+    "\n",
+    "# the only important difference:\n",
+    "s = 'can\\'t be written like this'\n",
+    "s = \"can't be written like this\"  # better\n",
+    "s = \"can be written \\\"like this\\\"\"\n",
+    "s = 'can be written \"like this\"'  # better\n",
+    "\n",
+    "s1 = 'foo'\n",
+    "s2 = 'bar'\n",
+    "s1 + ' ' + s2\n",
+    "\n",
+    "# without new line\n",
+    "print(\n",
+    "    'works '\n",
+    "    'just '\n",
+    "    'fine'\n",
+    ")\n",
+    "\n",
+    "# with new line\n",
+    "print(\n",
+    "    'works\\n'\n",
+    "    'just\\n'\n",
+    "    'fine'\n",
+    ")\n",
+    "\n",
+    "# slicing [from:until(not included):step] - produces a new string (copy)\n",
+    "s3 = 'Statnett'\n",
+    "s3[0]  # Out: S\n",
+    "s3[-1]  # Out: t\n",
+    "s3[1:]  # Out: tatnett\n",
+    "s3[1:-1]  # Out: tatnett\n",
+    "s3[-3:]  # Out: ett\n",
+    "s3[1:-1:2]  # Out: tte\n",
+    "\n",
+    "s3.endswith('nett')  # Out: True\n",
+    "s3.startswith('sta')  # Out: False (case sensitive)\n",
+    "s3[-4:] == 'nett'  # works, but BAD coding style\n",
+    "\n",
+    "# All strings in Python 3 are unicode strings (unicode type) and not byte strings as in Python 2\n",
+    "# One doesn't write strings to: files, sockets, cryptographic functions etc... but rather 'bytes'\n",
+    "\n",
+    "# from unicode string to bytes (UTF-8)\n",
+    "'BØ!'.encode('utf-8')  # utf-8 is implicit in Python 3\n",
+    "\n",
+    "# bytes to unicode\n",
+    "b'B\\xc3\\x98!'.decode('utf-8')  # utf-8 is implicit in Python 3"
+   ]
+  },
+  {
    "cell_type": "markdown",
    "id": "6b2bc8fa-a5dc-4a58-92b2-abfb19bfe2ed",
    "metadata": {},
@@ -320,27 +520,27 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 98,
+   "execution_count": 53,
    "id": "f4a4ea99-4038-4b61-9b8d-9ce623e6a663",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "35041378544"
+       "35082617072"
       ]
      },
-     "execution_count": 98,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     },
     {
      "data": {
       "text/plain": [
-       "35041378576"
+       "35082617104"
       ]
      },
-     "execution_count": 98,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -350,7 +550,7 @@
        "'H'"
       ]
      },
-     "execution_count": 98,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -360,47 +560,47 @@
        "-6333845781340707986"
       ]
      },
-     "execution_count": 98,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     },
     {
      "data": {
       "text/plain": [
-       "36321214208"
+       "36350585520"
       ]
      },
-     "execution_count": 98,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     },
     {
      "data": {
       "text/plain": [
-       "36321613808"
+       "36350587520"
       ]
      },
-     "execution_count": 98,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     },
     {
      "data": {
       "text/plain": [
-       "27542959409390741"
+       "8927089887582119463"
       ]
      },
-     "execution_count": 98,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     },
     {
      "data": {
       "text/plain": [
-       "27542959409390741"
+       "8927089887582119463"
       ]
      },
-     "execution_count": 98,
+     "execution_count": 53,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -442,6 +642,9 @@
     "\n",
     "A function is a sequence of program instructions that performs a specific task, packaged as a unit.\n",
     "\n",
+    "\n",
+    "### Why use functions?\n",
+    "\n",
     "Functions let you:\n",
     "\n",
     "- reuse code across several programs / projects\n",
@@ -456,20 +659,51 @@
     "\n",
     "- improve traceability\n",
     "\n",
+    "\n",
+    "### Any downside?\n",
+    "\n",
     "Function calls bring some overhead pushing / popping function-data into / from stack.\n",
     "\n",
+    "```python\n",
+    "empty_list = list()\n",
+    "empty_dict = dict()\n",
+    "\n",
+    "# better since it avoids the function call:\n",
+    "empty_list = []\n",
+    "empty_dict = {}\n",
+    "```\n",
+    "\n",
+    "\n",
+    "### Definitions\n",
+    "\n",
     "Important definitions (may have different meanings in different programming languages):\n",
     "\n",
-    "- *parameter / formal parameter* - variable / data provided as input to the function\n",
+    "- *parameter / formal parameter* - the names that appear in a function definition. Parameters define what kind of arguments a function can accept.\n",
+    "\n",
+    "- *argument / actual parameter* - the values actually passed to a function when calling it.\n",
     "\n",
-    "- *argument / actual parameter* - local variable / data to the given function\n",
     "\n",
-    "The keyword `def` introduces a function definition."
+    "The keyword `def` introduces a function definition.\n",
+    "\n",
+    "Given the function definition:\n",
+    "\n",
+    "```python\n",
+    "def func(foo, bar=None, **kwargs):\n",
+    "    pass\n",
+    "```\n",
+    "\n",
+    "`foo`, `bar` and `kwargs` are **parameters** of `func`. However, when calling func, for example:\n",
+    "\n",
+    "```python\n",
+    "func(42, bar=314, extra=somevar)\n",
+    "```\n",
+    "\n",
+    "the values `42`, `314`, and `somevar` are arguments."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 99,
+   "execution_count": 54,
    "id": "bf95f44a-1257-440f-b35f-a8536c8c4363",
    "metadata": {},
    "outputs": [
@@ -479,7 +713,7 @@
        "7"
       ]
      },
-     "execution_count": 99,
+     "execution_count": 54,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -496,7 +730,7 @@
        "[9, -2]"
       ]
      },
-     "execution_count": 99,
+     "execution_count": 54,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -511,36 +745,47 @@
    "source": [
     "# Functions (example1)\n",
     "\n",
+    "# case1: assuming that the arguments are of ummutable type (f.i. int):\n",
     "def add(a, b):  # - function definition / header\n",
-    "    \"\"\"Function for adding integers\"\"\"  # - docstring\n",
+    "    \"\"\"Function for adding two integers\"\"\"  # - docstring\n",
+    "    # the function body will not be evaluated (executed) before the function is called\n",
     "    result = a + b\n",
-    "    a = 5  # will not change the corresponding parameter since it is immutable\n",
+    "    a = 5  # will not change the corresponding argument since it is immutable\n",
     "    return result  # - function that does not contain return, implicitly returns None\n",
     "\n",
-    "a_param = 9\n",
-    "b_param = -2\n",
-    "add(a_param, b_param)  # Out: 7\n",
+    "# defining two integer variables to be used as arguments when calling the function `add`\n",
+    "a_var = 9\n",
+    "b_var = -2\n",
+    "\n",
+    "add(a_var, b_var)  # Out: 7\n",
     "\n",
-    "# integers are immutable and a_param will remain unchanged\n",
-    "print(a_param)  # Out: 9\n",
+    "# even though a_var and a point at the same data (they are references: a = a_var),\n",
+    "# integers are immutable and a_var will remain unchanged\n",
+    "print(a_var)  # Out: 9\n",
     "\n",
     "\n",
+    "# case2: assuming that the arguments are of mutable type (f.i. list)\n",
     "def addl(a, b):\n",
     "    \"\"\"Function for adding two lists\"\"\"\n",
-    "    result = a + b\n",
-    "    a += [5]  # in this case equal to: a.append(5)\n",
+    "    # assuming that a and b are lists\n",
+    "    result = a + b # produces a new list that contains the elements of `a` followed by the elements of `b`\n",
+    "    a.append(5)  # appending a new int element - 5 to the list `a`\n",
     "    return result\n",
     "\n",
-    "a_param = [9]\n",
-    "b_param = [-2]\n",
-    "addl(a_param, b_param)  # Out: [9, -2]\n",
-    "# lists are mutable and a_param will be changed\n",
-    "print(a_param)  # Out: [9, 5]"
+    "# defining two lists with one element each to be used as arguments when calling `addl`\n",
+    "a_var = [9]\n",
+    "b_var = [-2]\n",
+    "\n",
+    "addl(a_var, b_var)  # Out: [9, -2]\n",
+    "\n",
+    "# since a (inside the function) is a reference of a_var (a = a_var) and\n",
+    "# lists are mutable and `a_var` will be changed inside the function\n",
+    "print(a_var)  # Out: [9, 5]"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 100,
+   "execution_count": 55,
    "id": "ecd03ee2-3523-40bd-afd1-4263a777bae0",
    "metadata": {},
    "outputs": [],
@@ -551,8 +796,15 @@
     "    \"\"\"Function for adding integers\"\"\"\n",
     "    return a + b\n",
     "\n",
-    "my_result = add(2, 5)  # positional arguments (parameters)\n",
-    "my_result = add(b=5, a=2)  # keyword arguments (parameters)\n",
+    "# positional arguments:\n",
+    "# the order by which the arguments are sent to the function decides\n",
+    "# which argument is assigned to which parameter\n",
+    "my_result = add(2, 5)\n",
+    "\n",
+    "# keyword arguments:\n",
+    "# which argument is assigned to which parameter is decided by\n",
+    "# referrig directly to the argument names - keyword arguments (kwargs)\n",
+    "my_result = add(b=5, a=2)\n",
     "\n",
     "my_tuple = (2, 5)\n",
     "my_dict = {'b': 5, 'a': 2}\n",
@@ -560,12 +812,15 @@
     "my_result = add(*my_tuple)  # unpacked and assigned to the positional arguments\n",
     "my_result = add(**my_dict)  # unpacked and assigned to the kw. arguments\n",
     "\n",
+    "# defining the function `add`with defaukt value for argument `b`\n",
     "def add(a, b=5):\n",
     "    \"\"\"Function for adding integers\"\"\"\n",
     "    return a + b\n",
-    "my_result = add(2)\n",
-    "# ... and the rest of the examples above will work\n",
+    "my_result = add(2)  # the default value for `b` is used unless a parameter is sent / used\n",
     "\n",
+    "# assigning a varying amount of arguments to parameters\n",
+    "# # args - tuple containing all positional arguments (with the exception of `a`)\n",
+    "# kwargs - a {keyword: value} dict containing all keyword arguments\n",
     "def add(a, *args, **kwargs):\n",
     "    \"\"\"Function for adding integers\"\"\"\n",
     "    if args:\n",
@@ -575,12 +830,58 @@
     "    return a + b\n",
     "\n",
     "my_result = add(2, 5, 9, 11)  # 5 assigned to args[0]\n",
-    "my_result = add(2, b=5, c=9, d=11)  # 5 assigned to kwargs['b']\n",
+    "my_result = add(2, 6, 5, b=5, c=9, d=11)  # 5 assigned to kwargs['b']\n",
     "\n",
     "# my_result = add(2, b=5, 9, 11)  # SyntaxError: positional argument follows keyword argument"
    ]
   },
   {
+   "cell_type": "code",
+   "execution_count": 56,
+   "id": "c67ca162-e8eb-4b4d-8c3c-246b000c5c13",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "10 20 {'a': 1, 'b': 2, 'c': 3}\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Positional only parameters:\n",
+    "# def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):\n",
+    "#       -----------    ----------     ----------\n",
+    "#         |             |                  |\n",
+    "#         |        Positional or keyword   |\n",
+    "#         |                                - Keyword only\n",
+    "#          -- Positional only\n",
+    "\n",
+    "# Positional-only parameters give more control to library authors to better\n",
+    "# express the intended usage of an API and allows the API to evolve in a safe, backward-compatible way.\n",
+    "# Additionally, it makes the Python language more consistent with existing documentation and\n",
+    "# the behavior of various “builtin” and standard library functions.\n",
+    "\n",
+    "# One use case for this notation is that it allows pure Python functions to fully emulate behaviors of existing C coded functions.\n",
+    "# For example, the built-in divmod() function does not accept keyword arguments:\n",
+    "def divmod(a, b, /):\n",
+    "    \"\"\"Emulate the built in divmod() function\"\"\"\n",
+    "    return (a // b, a % b)\n",
+    "\n",
+    "# Another use case is to preclude keyword arguments when the parameter name is not helpful.\n",
+    "# For example, the builtin len() function has the signature len(obj, /).\n",
+    "# This precludes awkward calls such as: len(obj='hello'), where the \"obj\" keyword argument impairs readability.\n",
+    "\n",
+    "# A further benefit of marking a parameter as positional-only is that it allows the parameter name to be changed in the future without risk of breaking client code.\n",
+    "\n",
+    "def my_func(a, b, /, **kwargs):\n",
+    "    print(a, b, kwargs)\n",
+    "\n",
+    "my_func(10, 20, a=1, b=2, c=3)"
+   ]
+  },
+  {
    "cell_type": "markdown",
    "id": "26a4f2fe-b79e-4e25-9107-230a53d11373",
    "metadata": {},
@@ -654,11 +955,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 101,
+   "execution_count": 57,
    "id": "edf9cfa7-d76c-428b-a39f-8c0697789031",
    "metadata": {},
    "outputs": [],
    "source": [
+    "# example: function as a parameter / argument\n",
+    "# the built-in function map: map(function, iterable, *iterables)\n",
+    "\n",
+    "\n",
     "def fetch_the_first_letter(input_str: str) -> str:\n",
     "    \"\"\"Fetches the first letter of the string input_str or 'x'\"\"\"\n",
     "    try:\n",
@@ -672,8 +977,8 @@
     "letter_list = list(map(lambda x: x[0], ['foo', 'bar', 'test']))  # Out: ['f', 'b', 't']\n",
     "\n",
     "\n",
+    "# example: function returning multiple values\n",
     "# A function can return multiple values by implicitly returning a tuple:\n",
-    "\n",
     "def square_cube(x):\n",
     "    \"\"\"returns x, x^2 and x^3\"\"\"\n",
     "    return x, x**2, x**3\n",
@@ -700,7 +1005,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 102,
+   "execution_count": 58,
    "id": "ea583c17-c938-495a-9586-2027c66328a2",
    "metadata": {},
    "outputs": [
@@ -715,9 +1020,17 @@
    ],
    "source": [
     "# enclosing functions\n",
+    "# used when:\n",
+    "# - we want to dynamically generate a function\n",
+    "# - we want to hide implementation details (encapsulation)\n",
+    "\n",
+    "# when we want to dynamically generate a function:\n",
+    "# the function will behave differently depending on what parameters were\n",
+    "# used when calling its enclosing function (factory function)\n",
     "\n",
     "def get_multiplier_of(base: int) -> str:\n",
     "    \"\"\"the function enclosing its nested functions\"\"\"\n",
+    "    # this function is the enclosing function of the function `multiplier_function`\n",
     "\n",
     "    def multiplier_function(x):\n",
     "        \"\"\"a nested function\"\"\"\n",
@@ -751,7 +1064,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 103,
+   "execution_count": 59,
    "id": "49d7f6e1-1f54-4b96-8203-5eae95f47ebe",
    "metadata": {},
    "outputs": [
@@ -761,36 +1074,49 @@
      "text": [
       "7 8\n",
       "100\n",
-      "{'num3': 100, 'id': 200}\n",
-      "{}\n",
-      "{}\n",
+      "{'id': 200, 'num3': 100, 'num5': 23}\n",
+      "{'num3': 100, 'num5': 23}\n",
+      "100\n",
+      "{'num3': 100, 'num5': 25}\n",
+      "100\n",
+      "25\n",
       "99\n"
      ]
     }
    ],
    "source": [
-    "num1, num2 = 7, 8  # module globals\n",
+    "# module globals\n",
+    "num1 = 7\n",
+    "num2 = 8\n",
     "\n",
     "def print_numbers():\n",
-    "    print(num1, num2)  # OK, these are module globals\n",
+    "    print(num1, num2)  # module globals. Out: 7 8\n",
     "    num3 = 100\n",
     "    print(num3)  # prints 100, num3 is in the function (local) scope\n",
     "    global num4  # assignes / references num4 to / in the global scope\n",
     "    num4 = 99\n",
     "    id = 200  # new symbol in local scope\n",
     "    # id(num4)  # will not yield the expected result (raises TypeError)\n",
+    "    num5 = 23\n",
+    "    \n",
+    "    # locals() updates and then returns a dictionary representing the current local symbol table\n",
     "    print(locals())\n",
     "\n",
     "    def print_numbers2():\n",
-    "        print(locals())\n",
-    "        # print(num3)  # OK, enclosed scope\n",
+    "        print(locals())  # N.B. Updates and then displays the local symbol table (num3 will be included)\n",
+    "        print(num3)  # OK, enclosed scope\n",
+    "        # num3 = 9  # UnboundLocalError: local variable 'num3' referenced before assignment\n",
+    "        nonlocal num5  # assignes / references num5 to / in enclosing scope. N.B. num5 must exist in `print_numbers`\n",
+    "        num5 = 25\n",
     "        print(locals())\n",
     "\n",
-    "    print_numbers2()  # prints 100\n",
+    "    print_numbers2()  # Out: 100\n",
+    "    print(num3)\n",
+    "    print(num5)  # Out: 25\n",
     "\n",
     "print_numbers()\n",
     "# print(num3)  # Raises NameError - why?\n",
-    "print(num4)  # Prints 99 - why?\n",
+    "print(num4)  # Out: 99\n",
     "# print_numbers2()  # Raises NameError"
    ]
   },
@@ -807,12 +1133,18 @@
     "def my_decorator(func):\n",
     "\n",
     "    def decorated():\n",
+    "        # we place the logic we want to take place before the decorated function's logic here\n",
     "        print('Doing something before the decorated function')\n",
-    "        retval = func()\n",
+    "        retval = func()  # calling the decorated function and (optionally) taking care of its return value\n",
+    "        # we place the logic we want to take place after the decorated function's logic here\n",
     "        print('Doing something after the decorated function')\n",
-    "        return retval\n",
+    "        return retval  # returning the return value of the original (decorated) function\n",
     "    return decorated\n",
+    "```\n",
     "\n",
+    "once having a decorator:\n",
+    "\n",
+    "```python\n",
     "def my_function():\n",
     "    print('Alice')\n",
     "\n",
@@ -835,7 +1167,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 104,
+   "execution_count": 60,
    "id": "4346260d-76af-437e-9c10-1c1d0c478695",
    "metadata": {},
    "outputs": [],
@@ -864,6 +1196,7 @@
     "\n",
     "\n",
     "@requires_access(access_secret='b28cfeaa65b73cf')\n",
+    "@is_admin\n",
     "def sensitive_function(data, **kwargs):\n",
     "    \"\"\"very sensitive function\"\"\"\n",
     "    db.save(data)"