functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1",
   "metadata": {},
   "source": [
    "# Table of Contents\n",
    "\n",
    "- [References](#References)\n",
    "- [Functions are building blocks](#Functions-are-building-blocks)\n",
    "- [Best practices](#Best-practices)\n",
    "- [Anatomy of a function](#Anatomy-of-a-function)\n",
    "- [Signature](#Signature)\n",
    "  - [Type hints](#Type-hints)\n",
    "- [Body](#Body)\n",
    "- [Docstrings](#Docstrings)\n",
    "- [Parameters and arguments](#Parameters-and-arguments)\n",
    "    - [Parameters](#Parameters)\n",
    "    - [Arguments](#Arguments)\n",
    "    - [Positional arguments](#Positional-arguments)\n",
    "    - [Keyword arguments](#Keyword-arguments)\n",
    "    - [Default values](#Default-values)\n",
    "- [Exercise 1](#Exercise-1)\n",
    "- [Exercise 2](#Exercise-2)\n",
    "- [How Python executes a function](#How-Python-executes-a-function)\n",
    "  - [Calling](#Calling)\n",
    "  - [Executing](#Executing)\n",
    "  - [Returning](#Returning)\n",
    "- [The scope of a function](#The-scope-of-a-function)\n",
    "  - [Different types of scope](#Different-types-of-scope)\n",
    "- [Global scope](#Global-scope)\n",
    "- [`*args` and `**kwargs`](#*args-and-**kwargs)\n",
    "- [Exercise 3](#Exercise-3)\n",
    "- [Quiz on functions](#Quiz-on-functions)\n",
    "- [Bonus exercises](#Bonus-exercises)\n",
    "  - [Longest consecutive sequence](#Longest-consecutive-sequence)\n",
    "    - [Example 1](#Example-1)\n",
    "    - [Example 2](#Example-2)\n",
    "    - [Part 2](#Part-2)\n",
    "  - [Password validator](#Password-validator)\n",
    "    - [Part 1](#Part-1)\n",
    "    - [Part 2](#Part-2)\n",
    "  - [Buckets reorganization](#Buckets-reorganization)\n",
    "    - [Part 1](#Part-1)\n",
    "    - [Part 2](#Part-2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2",
   "metadata": {
    "tags": []
   },
   "source": [
    "## References"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3",
   "metadata": {},
   "source": [
    "Additional materials where you can find more details about writing functions in Python. For each link, it's indicated if it's a video, a text, or a practical resource.\n",
    "\n",
    "- [Python For Everybody: Functions](https://www.py4e.com/lessons/functions) (video)\n",
    "- [Python For Everybody: Functions examples](https://www.py4e.com/html3/04-functions) (text)\n",
    "- [In-depth explanation of scoping and how Python resolve names](https://realpython.com/python-scope-legb-rule/) (text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Functions are building blocks\n",
    "\n",
    "Every programmer knows that splitting the work into smaller pieces isn't only a good problem-solving technique, but it also makes your code more readable, easier to understand, and more efficient (or at least it will be easier to make it so). **Functions** are the fundamental building block to achieve this.\n",
    "\n",
    "When you have to perform the same task multiple times, instead of repeating the code, you can simply call the function."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6",
   "metadata": {},
   "source": [
    "1. Functions in Python are blocks of reusable code that perform a specific task.\n",
    "2. They allow you to break down complex programs into smaller and manageable parts.\n",
    "3. Functions make your code easier to read and maintain because you can encapsulate logic into self-contained blocks and reuse them throughout your program."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Best practices\n",
    "\n",
    "1. Giving descriptive names\n",
    "2. Keeping them small and focused on a single task\n",
    "3. Using clear and concise documentation (also known as docstrings)\n",
    "4. Explaining the required (and optional) inputs and outputs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Anatomy of a function"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9",
   "metadata": {},
   "source": [
    "A function in Python has three main parts:\n",
    "\n",
    "- Signature\n",
    "- Body\n",
    "- Docstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10",
   "metadata": {},
   "source": [
    "## Signature\n",
    "\n",
    "- The signature of a function includes the function name, the input parameters (if any), and the return statement (if any)\n",
    "- The Python keyword to indicate that a name is a function's name is `def`, and it's a **reserved keyword**\n",
    "- The signature is what allows you to call the function and pass it arguments\n",
    "\n",
    "---\n",
    "\n",
    "For example:\n",
    "\n",
    "```python\n",
    "def multiply(x, y):\n",
    "```\n",
    "\n",
    "You have the keyword `def`, the function's name, and its parameters in parentheses. The semi-colon tells Python that what comes next is the function's body."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "### Type hints\n",
    "\n",
    "Python doesn't require you to explicitly declare a variable's type. However, when defining functions, you can add **type hints** in the function's signature.\n",
    "\n",
    "Type hints improve code readability and can help catch potential type-related bugs early during development.\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "    <h4><b>Warning</b></h4> The Python interpreter <b>does not</b> enforce type hints and will not check them during runtime. Type hints are primarily intended for improving code readability, serving as documentation for developers, and making IDEs much more helpful when writing code.\n",
    "</div>\n",
    "\n",
    "---\n",
    "\n",
    "They are specified using the `typing` module and are added in the function definition using colons followed by the expected type, right after the parameter name.\n",
    "\n",
    "For example:\n",
    "\n",
    "```python\n",
    "from typing import List, Tuple\n",
    "\n",
    "def greet(name: str) -> None:\n",
    "    print(f\"Hello, {name}!\")\n",
    "\n",
    "def add_numbers(a: int, b: int) -> int:\n",
    "    return a + b\n",
    "\n",
    "def process_data(data: List[Tuple[int, str]]) -> List[str]:\n",
    "    return [item[1] for item in data]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12",
   "metadata": {},
   "source": [
    "## Body\n",
    "\n",
    "The body of a function contains the statements that the function executes when it is called. These statements perform the task that the function was created to perform. For example:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13",
   "metadata": {},
   "source": [
    "```python\n",
    "def multiply(x, y):\n",
    "    product = x * y\n",
    "    return product\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14",
   "metadata": {},
   "source": [
    "The function's outputs are indicated by the (reserved) keyword `return`. All functions in Python return a value, even if that value is `None`. If you omit the `return` keyword, Python assumes that the function returns `None`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15",
   "metadata": {},
   "source": [
    "## Docstrings\n",
    "\n",
    "Docstrings are **string literals** that appear as the first statement in a function. They provide documentation for the function, explaining what it does and how it works. Docstrings are surrounded by triple quotes (`\"\"\"`).\n",
    "\n",
    "For example:\n",
    "\n",
    "```python\n",
    "def multiply(x, y):\n",
    "    \"\"\"This function calculates the product of two numbers\"\"\"\n",
    "    product = x * y\n",
    "    return product\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "A few more examples of simple functions:\n",
    "\n",
    "```python\n",
    "def greet(name):\n",
    "    \"\"\"This function greets the person passed in as a parameter\"\"\"\n",
    "    return \"Hello, \" + name\n",
    "\n",
    "def add(a, b):\n",
    "    \"\"\"This function returns the sum of two numbers\"\"\"\n",
    "    return a + b\n",
    "\n",
    "def is_even(number):\n",
    "    \"\"\"This function returns True if the number is even, False otherwise\"\"\"\n",
    "    return number % 2 == 0\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Parameters and arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17",
   "metadata": {},
   "source": [
    "The terms **parameters** and **arguments** are often used interchangeably, but they refer to different things in the context of function calls."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18",
   "metadata": {},
   "source": [
    "## Parameters\n",
    "\n",
    "**Parameters** are the names that are used in the function definition to accept values passed to the function. For example:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19",
   "metadata": {},
   "source": [
    "```python\n",
    "def greet(name):\n",
    "    \"\"\"This function greets the person passed in as a parameter\"\"\"\n",
    "    return \"Hello, \" + name\n",
    "```\n",
    "\n",
    "Here `name` is a parameter."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20",
   "metadata": {},
   "source": [
    "## Arguments\n",
    "\n",
    "**Arguments** are the actual values that are passed to the function when it is called.\n",
    "\n",
    "```python\n",
    "greet(\"John\")\n",
    "# \"Hello, John\"\n",
    "```\n",
    "\n",
    "Here the literal string `\"John\"` is the argument."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21",
   "metadata": {},
   "source": [
    "## Positional arguments\n",
    "\n",
    "In Python, there are two ways to pass arguments to a function: positional arguments and keyword arguments.\n",
    "\n",
    "**Positional arguments** are arguments that are passed to the function in the same order as the parameters. For example:\n",
    "\n",
    "```python\n",
    "def add(a, b):\n",
    "    \"\"\"This function returns the sum of two numbers\"\"\"\n",
    "    return a + b\n",
    "\n",
    "add(1, 2)\n",
    "```\n",
    "\n",
    "Here, `1` and `2` are positional arguments that are passed to the `add` function."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22",
   "metadata": {},
   "source": [
    "## Keyword arguments\n",
    "\n",
    "**Keyword arguments** are arguments that are passed to the function using the name of the parameter followed by an equal sign and the value. For example:\n",
    "\n",
    "```python\n",
    "def greet(name):\n",
    "    \"\"\"This function greets the person passed in as a parameter\"\"\"\n",
    "    return \"Hello, \" + name\n",
    "\n",
    "greet(name=\"John\")\n",
    "```\n",
    "\n",
    "Here, `name=\"John\"` is a keyword argument that is passed to the greet function.\n",
    "\n",
    "Keyword arguments make the function call more readable and can be useful when the order of the parameters is **not important**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "23",
   "metadata": {},
   "source": [
    "## Default values\n",
    "\n",
    "Another important use of the keyword syntax (the `=` sign) is to define **parameters with default values**. For example:\n",
    "\n",
    "```python\n",
    "def greet(name=\"my friend\"):\n",
    "    \"\"\"This function greets the person passed in as a parameter\"\"\"\n",
    "    return \"Hello, \" + name\n",
    "```\n",
    "\n",
    "Calling `greet` **without any arguments** tells Python to use the default value. Therefore, `greet()` will return `\"Hello, my friend\"`.\n",
    "\n",
    "Let's run the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def greet(name=\"my friend\"):\n",
    "    \"\"\"This function greets the person passed in as a parameter\"\"\"\n",
    "    return \"Hello, \" + name\n",
    "\n",
    "print(greet())\n",
    "\n",
    "print(greet(\"John\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "25",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "26",
   "metadata": {},
   "outputs": [],
   "source": [
    "%reload_ext tutorial.tests.testsuite"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27",
   "metadata": {},
   "source": [
    "## Exercise 1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28",
   "metadata": {},
   "source": [
    "Write a Python function called `greet` that takes two parameters: `name` (a string) and `age` (an integer).\n",
    "The function should return a greeting message in the following format: `\"Hello, <name>! You are <age> years old.\"`\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Note</b></h4>\n",
    "    <strong>Do not</strong> forget to write a proper docstring and add the correct type hints to the parameters and the return value.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_greet():\n",
    "    return"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30",
   "metadata": {},
   "source": [
    "## Exercise 2\n",
    "\n",
    "Write a Python function called `calculate_area` that takes three parameters: `length` (a float), `width` (a float), and `unit` (a string with a **default** value of `\"cm\"`).\n",
    "The function should calculate the area of a rectangle based on the given length and width, and return the result **as a tuple** with the correct, default unit (i.e., `cm^2`).\n",
    "If the unit parameter is \"m\", the function should convert the length and width from meters to centimeters before calculating the area.\n",
    "\n",
    "Your solution function **must** handle the following input units (the output unit is **always** `cm^2`):\n",
    "\n",
    "- centimeters (`cm`)\n",
    "- meters (`m`)\n",
    "- millimeters (`mm`)\n",
    "- yards (`yd`)\n",
    "- feet (`ft`)\n",
    "\n",
    "If you pass an unsupported unit, the function should **return** a string with the error message: `Invalid unit: <unit>`, where `<unit>` is the unsupported unit.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Note</b></h4>\n",
    "    <strong>Do not</strong> forget to write a proper docstring and add the correct type hints to the parameters and the return value.\n",
    "</div>\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <h4><b>Hints</b></h4>\n",
    "    <ul>\n",
    "        <li>1 yd = 91.44 cm</li>\n",
    "        <li>1 ft = 30.48 cm</li>\n",
    "    </ul>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "31",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_calculate_area():\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33",
   "metadata": {
    "tags": []
   },
   "source": [
    "## How Python executes a function"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34",
   "metadata": {
    "tags": []
   },
   "source": [
    "This sentence may seem another trivial one: to execute a function, you must **call it**. In Python, it means using the `function_name()` with **parentheses**, enclosing any argument if need be.\n",
    "\n",
    "When you call a function in Python, three things happen:\n",
    "\n",
    "1. **Calling**\n",
    "2. **Executing**\n",
    "3. **Returning**\n",
    "\n",
    "---\n",
    "\n",
    "### Calling\n",
    "\n",
    "- Python creates a new **function call frame** on the call stack\n",
    "- A function call frame contains information about the function call, such as the function name, arguments, local variables, and the return address (i.e., where to return control when the function returns)\n",
    "- The function call frame is pushed onto the top of the call stack\n",
    "\n",
    "---\n",
    "\n",
    "### Executing\n",
    "\n",
    "After the function call frame is created, control is transferred to the function body.\n",
    "\n",
    "- The function body is executed from top to bottom, line by line\n",
    "- The function can access its parameters, declare local variables, and perform any other operations specified in the body\n",
    "- The function can call other functions, which will create their own function call frames and push them onto the call stack\n",
    "\n",
    "---\n",
    "\n",
    "### Returning\n",
    "\n",
    "When the function reaches the end of the body or encounters a `return` statement, the function returns control to the calling code\n",
    "\n",
    "- The function call frame is removed from the call stack, and any local variables and parameters are discarded\n",
    "- The function returns a value if specified in the return statement, otherwise it returns `None`\n",
    "\n",
    "This process repeats every time a function is called, and the call stack grows and shrinks as functions are called and return. This allows Python to keep track of the execution context and return control to the correct location when a function returns.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "35",
   "metadata": {
    "tags": []
   },
   "source": [
    "## The scope of a function"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36",
   "metadata": {},
   "source": [
    "The following might seem trivial: could we assign the same variable name to two different values?\n",
    "\n",
    "The obvious (and right) answer is **no**. If `x` is `3` and `2` at the same time, how should Python evaluate an expression containing `x`?\n",
    "\n",
    "There is, however, a workaround to this and it involves the concept of **scope**.\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "    <h4><b>Important</b></h4> You should <b>not</b> the scope to have a variable with two values at the same time, but it's an important concept to understand unexpected behaviours.\n",
    "</div>\n",
    "\n",
    "---\n",
    "\n",
    "Look at the following lines of valid Python code:\n",
    "\n",
    "```python\n",
    "x = \"Hello World\"\n",
    "\n",
    "def func():\n",
    "    x = 2\n",
    "    return f\"Inside 'func', x has the value {x}\"\n",
    "\n",
    "print(func())\n",
    "print(f\"Outside 'func', x has the value {x}\")\n",
    "```\n",
    "\n",
    "What output do you expect?\n",
    "\n",
    "Does `x` really have two simultaneous values?\n",
    "\n",
    "**Not really:** the reason is that `x` **within the function's body** and `x` **in the outside code** live in two separates **scopes**. The function body has a **local scope**, while all the code outside belongs to the **global scope**.\n",
    "\n",
    "---\n",
    "\n",
    "### Different types of scope\n",
    "\n",
    "We can define the scope as **the region of a program where a variable can be accessed**.\n",
    "\n",
    "1. **Global scope**: Variables declared at the top level of a program or module are in the global scope. They are accessible from anywhere in the program or module.\n",
    "\n",
    "2. **Local scope**: Variables declared inside a function are in the local scope. They are only accessible from within the function and are discarded when the function returns.\n",
    "\n",
    "3. **Non-local scope**: Variables defined in an outer function and declared as `nonlocal` in the inner nested function are in the non-local scope. They are accessible both from the outer function and from within the nested function.\n",
    "\n",
    "\n",
    "Here's an example to illustrate the different scopes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "37",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Global scope\n",
    "x = 10\n",
    "\n",
    "def function():\n",
    "    # Local scope\n",
    "    x = 20\n",
    "    print(\"Inner scope:\", x)\n",
    "\n",
    "function()\n",
    "print(\"Global scope:\", x)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38",
   "metadata": {},
   "source": [
    "In this example, `x` is a **global** variable and is accessible from anywhere in the program. `x` is also a **local** variable to the `function`, and is accessible from within the function's body.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39",
   "metadata": {},
   "source": [
    "The `nonlocal` keyword is used to access a variable in the **nearest enclosing scope** that is **not** global.\n",
    "\n",
    "In the example below, the `inner_function` uses `nonlocal y` to access the `y` variable in the `outer_function` and modify its value.\n",
    "\n",
    "If `nonlocal` was not used, a new local `y` variable would be created in the `inner_function`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40",
   "metadata": {},
   "source": [
    "Look at the following example:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41",
   "metadata": {},
   "source": [
    "```python\n",
    "# Global scope\n",
    "x = 10\n",
    "\n",
    "def outer_function():\n",
    "    # Non-local scope\n",
    "    y = 20\n",
    "\n",
    "    def inner_function():\n",
    "        # Local scope\n",
    "        nonlocal y\n",
    "        y += 30\n",
    "        z = 40\n",
    "        print(\"Inner function:\", x, y, z)\n",
    "\n",
    "    inner_function()\n",
    "    print(\"Outer function:\", x, y)\n",
    "\n",
    "outer_function()\n",
    "print(\"Global scope:\", x)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42",
   "metadata": {},
   "source": [
    "The `global` keyword is used to access a global variable and modify its value from within a function.\n",
    "\n",
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Global scope\n",
    "x = 10\n",
    "\n",
    "def modify_x():\n",
    "    global x\n",
    "    x = 20\n",
    "\n",
    "print(\"Global scope:\", x)\n",
    "\n",
    "modify_x()\n",
    "\n",
    "print(\"Global scope:\", x)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44",
   "metadata": {},
   "source": [
    "Even though you can access and modify variables from different scope, it's not considered a good practice. When a function makes use of `global` or `nonlocal`, or when modifying a mutable type in-place, it's like when a function modifies its own arguments. It's a **side-effect** that should be generally avoided.\n",
    "\n",
    "It's is considered a much better programming practice to make use of a function's return values instead of resorting to the scoping keywords."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45",
   "metadata": {},
   "source": [
    "# `*args` and `**kwargs`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "46",
   "metadata": {},
   "source": [
    "In the [Basic datatypes](./basic_datatypes.ipynb#Unpacking) section we saw that iterables (tuples and lists) support **unpacking**. You can exploit unpacking to make a **parallel assignment**.\n",
    "\n",
    "A reminder:\n",
    "\n",
    "```python\n",
    "coordinates = 4.42, -12.45 # creates a tuple\n",
    "x, y, = coordinates # unpacks the tuple\n",
    "```\n",
    "\n",
    "Now that we know about unpacking and the `*`/`**` operators, we can create more flexible functions that can accept any number of **positional** or **keyword** arguments.\n",
    "\n",
    "Have a look at the following example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "47",
   "metadata": {},
   "outputs": [],
   "source": [
    "def func_with_args(a, b, *args):\n",
    "    print(f\"Required positional args: a = {a}, b = {b}\")\n",
    "    if args:\n",
    "        print(f\"Optional positional arguments: {args}\")\n",
    "        \n",
    "func_with_args(10, 'python')   # only required, positional arguments\n",
    "func_with_args(10, 'python', 30, 40, 60)   # with some optional, positional arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48",
   "metadata": {},
   "source": [
    "The only difference with unpacking is: all the optional positional arguments are collected by `*args` **in a tuple** and not in a list.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <h4><b>Note</b></h4>\n",
    "    Note that <code>*args</code> is <strong>an arbitrary name</strong>: you can use whichever valid Python name you want, but it's customary to call it <code>*args</code>, and we <strong>warmly suggest</strong> you to stick to this convention.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "49",
   "metadata": {},
   "source": [
    "One importat rule:\n",
    "\n",
    "> **You cannot add** more positional arguments after `*args` because `*args` **exhausts all the positional arguments**.\n",
    "\n",
    "```python\n",
    "def func(a, b, *args, d):\n",
    "    # code\n",
    "```\n",
    "\n",
    "The above function definition is actually fine but you **could not** call it with\n",
    "\n",
    "```python\n",
    "func(10, 20, 'a', 'b', 100)   # wrong function call\n",
    "```\n",
    "\n",
    "Because `a = 10`, `b = 20`, and `args = ('a', 'b', 100)`: you cannot pass a fourth **positional** argument to this function. You must use the name `d` to pass a **keyword** argument:\n",
    "\n",
    "```python\n",
    "func(10, 20, 'a', 'b', d = 100)   # correct function call\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "50",
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_vec(x, y, z):\n",
    "    print(f\"Vector components: {{x = {x}, y = {y}, z = {z}}}\")\n",
    "    \n",
    "vec = (-3.0, 1.0, 25.4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "51",
   "metadata": {},
   "source": [
    "The following **cannot** work\n",
    "\n",
    "```python\n",
    "print_vec(vec)\n",
    "```\n",
    "\n",
    "because the function requires 3 positional arguments. But we can use unpacking and write\n",
    "\n",
    "```python\n",
    "print_vec(*vec)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52",
   "metadata": {},
   "source": [
    "Remember that functions' arguments can be either **positional** or **keyword** arguments:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "53",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def func_with_positional_and_keywords(a, b, c = 10, d = 'python'):\n",
    "    print(f'Required: a = {a}, b = {b}')\n",
    "    print(f'Optional: c = {c}, d = {d}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54",
   "metadata": {},
   "source": [
    "We can call the function with"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "55",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "func_with_positional_and_keywords(10, 20)   # only positional arguments\n",
    "\n",
    "func_with_positional_and_keywords(10, 20, c = -100)   # 2 positional and 1 keyword argument\n",
    "\n",
    "func_with_positional_and_keywords(b = -10, c = 10, a = 'hello', d = 'C++')   # all keyword arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56",
   "metadata": {},
   "source": [
    "After `*args` there can be **no additional positional arguments** but we might have some (or no) keyword arguments.\n",
    "\n",
    "We can use the `**` operator to scoop up a variable amount of (remaining) **keyword arguments**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "57",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def func_with_args_and_kwargs(a, b, *args, d, **kwargs):\n",
    "    print(f'Required positional: a = {a}, b = {b}')\n",
    "    \n",
    "    if args:\n",
    "        print(f\"Optional positional: {args}\")\n",
    "    \n",
    "    print(f'Required keyword argument: d = {d}')\n",
    "    \n",
    "    if kwargs:\n",
    "        print(f\"Remaining keyword arguments: {kwargs}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "58",
   "metadata": {},
   "source": [
    "Remember: `d` is a **required** keyword argument because we didn't supply a default value in the function definition.\n",
    "\n",
    "Here are a few ways in which we can call our function `func_with_args_and_kwargs`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "func_with_args_and_kwargs(10, 20, d = 10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "60",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "func_with_args_and_kwargs(10, 20, 30, 40, 50, d = 'hello')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "61",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "func_with_args_and_kwargs(10, 20, 30, 40, 50, d = 'hello', extra_1 = 'hey, ', extra_2 = \"how are\", extra_3 = \"you?\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62",
   "metadata": {},
   "source": [
    "We can even **omit** mandatory positional arguments\n",
    "\n",
    "```python\n",
    "def func_with_optional_positional(*args, d):\n",
    "    # code\n",
    "```\n",
    "\n",
    "The function above will accepts any number of **optional** positional arguments and one **mandatory** keyword argument `d`.\n",
    "\n",
    "You can think of `*` in a function's signature as indicating the \"end\" of positional arguments **without collecting them**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63",
   "metadata": {},
   "source": [
    "Or we can force **no positional arguments at all**:\n",
    "\n",
    "```python\n",
    "def func_with_no_positional(*, d, **kwargs):\n",
    "    # code\n",
    "```\n",
    "\n",
    "This function accepts **no positional arguments** at all, one **mandatory** keyword argument `d` and **any number of extra keyword arguments**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64",
   "metadata": {},
   "source": [
    "You can see that with iterables unpacking and the two `*`/`**` operators, Python is showing all its versatility when it comes to writing your own function.\n",
    "\n",
    "If all this seems confusing, **try to experiment with these concepts** here in the notebook to better understand the behaviour. Create and call all the functions you want and check if their outputs is what you expect.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65",
   "metadata": {},
   "outputs": [],
   "source": [
    "%reload_ext tutorial.tests.testsuite"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "66",
   "metadata": {},
   "source": [
    "## Exercise 3\n",
    "\n",
    "Write a Python function called `summing_anything` that is able to sum **any** kind of arguments.\n",
    "It therefore must accept a *variable* number of arguments.\n",
    "You must **not** use the built-in function `sum()` to solve this exercise: you should write your own (generalized) implementation.\n",
    "\n",
    "A few examples of how the function should work:\n",
    "\n",
    "| Arguments | Expected result |\n",
    "| --- | --- |\n",
    "| `('abc', 'def')` | `'abcdef'` |\n",
    "| `([1,2,3], [4,5,6])` | `[1,2,3,4,5,6]` |\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "67",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_summing_anything():\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69",
   "metadata": {},
   "source": [
    "## Quiz on functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "70",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from tutorial import functions as quiz\n",
    "quiz.Functions()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "71",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Bonus exercises\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "    <h4><b>Note</b></h4>\n",
    "    The following are recap exercises of increasing difficulty.\n",
    "    Please, try to solve the previous ones before attempting with those in this section.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "72",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true
   },
   "source": [
    "### Longest consecutive sequence"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73",
   "metadata": {
    "tags": []
   },
   "source": [
    "Given an **unsorted** set of $N$ random integers, write a function that returns the length of the longest consecutive sequence of integers.\n",
    "\n",
    "#### Example 1\n",
    "Given the list `numbers = [100, 4, 200, 1, 3, 2]`, the longest sequence is `[1, 2, 3, 4]` of length *4*.\n",
    "\n",
    "#### Example 2\n",
    "Given the list `numbers = [0, 3, 7, 2, 5, 8, 4, 6, 0, 1]`, the longest sequence contains all the numbers from 0 to 8, so its length is **9**.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "74",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_longest_sequence(numbers: \"list[int]\") -> int:\n",
    "    \"\"\"\n",
    "    Write your solution here\n",
    "    \"\"\"\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "75",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true
   },
   "source": [
    "#### Part 2\n",
    "\n",
    "Suppose that you are dealing with a *very* long list of integers (e.g., a few thousands or a million). Can you write an alternative solution that takes **less than 1 minute** to run?\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <h4><b>Hint</b></h4>\n",
    "    You need to store your <code>nums</code> in a data structure that doesn&#39;t care about ordering and discard duplicates. We have seen it on <a href=\"./basic_datatypes.ipynb#Set\">the first day of the tutorial</a>.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "76",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_longest_sequence_best(nums: \"list[int]\") -> int:\n",
    "    \"\"\"\n",
    "    Write your solution here\n",
    "    \"\"\"\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "### Password validator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "78",
   "metadata": {
    "tags": []
   },
   "source": [
    "#### Part 1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79",
   "metadata": {},
   "source": [
    "You have a range of numbers `136760-595730` and need to count how many valid password it contains. A valid password must meet **all** the following criteria:\n",
    "\n",
    "- It is a six-digit number\n",
    "- At least two adjacent digits are the same (like `22` in `122345`)\n",
    "- Going from left to right, the digits **never decrease**; they only ever increase or stay the same (like 111123 or 135679)\n",
    "\n",
    "\n",
    "For example, the following are true:\n",
    "\n",
    "- `111111` meets these criteria (double `11`, never decreases)\n",
    "- `223450` does **not** meet these criteria (`50` is a decreasing pair of digits)\n",
    "- `123789` does **not** meet these criteria (no double digit)\n",
    "\n",
    "Write a function that determines if a password is valid according to the criteria above."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80",
   "metadata": {},
   "source": [
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Question</b></h4> How many valid password are there in your range?\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81",
   "metadata": {},
   "source": [
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <h4><b>Hint</b></h4> The solution function takes <b>two</b> arguments: the <code>start</code> and <code>end</code> of your password range\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "82",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_password_validator1(start: int, end: int) -> int:\n",
    "    \"\"\"\n",
    "    Write your solution here\n",
    "    \"\"\"\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83",
   "metadata": {
    "tags": []
   },
   "source": [
    "#### Part 2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84",
   "metadata": {},
   "source": [
    "You have a new rule: **at least** two adjacent matching digits **must not be part of a larger group of matching digits**.\n",
    "\n",
    "Write a new function for validating password that includes the new rule.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Question</b></h4> How many valid password are there in your range <b>now</b>?\n",
    "</div>\n",
    "\n",
    "\n",
    "A few examples:\n",
    "\n",
    "- `112233` meets these criteria because the digits never decrease and all repeated digits are exactly two digits long\n",
    "- `123444` **doesn't** meet the criteria (the repeated `44` is part of a larger group of `444`)\n",
    "- `111122` meets the criteria (even though `1` is repeated more than twice, it still contains a double `22`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "85",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_password_validator2(start: int, end: int):\n",
    "    \"\"\"\n",
    "    Write your solution here\n",
    "    \"\"\"\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "86",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "### Buckets reorganization"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87",
   "metadata": {},
   "source": [
    "#### Part 1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "88",
   "metadata": {},
   "source": [
    "You have a list of buckets, each containing some items labeled from `a` to `z`, or from `A` to `Z`. Each bucket is split into **two** equally sized compartments.\n",
    "\n",
    "For example, in the following list of buckets\n",
    "\n",
    "```\n",
    "vJrwpWtwJgWrhcsFMMfFFhFp\n",
    "jqHRNqRjqzjGDLGLrsFMfFZSrLrFZsSL\n",
    "PmmdzqPrVvPwwTWBwg\n",
    "wMqvLMZHhHMvwLHjbvcjnnSBnvTQFn\n",
    "ttgJtRGJQctTZtZT\n",
    "CrZsJsPPZsGzwwsLwLmpwMDw\n",
    "```\n",
    "\n",
    "- The first bucket contains `vJrwpWtwJgWrhcsFMMfFFhFp`, which means its first compartment contains the items `vJrwpWtwJgWr`, while the second compartment contains the items `hcsFMMfFFhFp`. The only item type that appears in both compartments is `p`.\n",
    "- The third bucket's compartments contain `PmmdzqPrV` and `vPwwTWBwg`; the only common item type is `P`.\n",
    "- The sixth bucket's compartments only share item type `s`.\n",
    "\n",
    "Each item has also a priority:\n",
    "\n",
    "- Items types `a` through `z` have priorities 1 through 26\n",
    "- Items types `A` through `Z` have priorities 27 through 52\n",
    "\n",
    "\n",
    "Write a function that returns the priority of the item type that appears in **both compartments**. In the above example, the priority of the item that appears in both compartments of each bucket is 16 (`p`), 38 (`L`), 42 (`P`), 22 (`v`), 20 (`t`), and 19 (`s`); the sum of these is **157**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Question</b></h4> What is the sum of the priorities of those item types?\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "    <h4><b>Hint</b></h4> Your solution function takes **only one argument**: a file containing your buckets list. The buckets list is a multi-line string as in the example above. Each line is a single bucket, so you need to split the string on every new line (`\\n`)\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "91",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_buckets1(buckets_file: pathlib.Path) -> int:\n",
    "    buckets = buckets_file.read_text()  # do NOT remove this line\n",
    "    # Write your solution here or below this line\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true
   },
   "source": [
    "#### Part 2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "93",
   "metadata": {},
   "source": [
    "You are told that you should not care about the priority of **every item**, but only of a \"special item\" that is common to groups of **three buckets**.\n",
    "\n",
    "Every set of three lines correspond to a single group, and each group can have a different special item – that is, an item with a different letter.\n",
    "\n",
    "Considering once again the above example, in the first three lines:\n",
    "\n",
    "```\n",
    "vJrwpWtwJgWrhcsFMMfFFhFp\n",
    "jqHRNqRjqzjGDLGLrsFMfFZSrLrFZsSL\n",
    "PmmdzqPrVvPwwTWBwg\n",
    "```\n",
    "The only item that appears in **all** three buckets is `r` (priority 18). This must be the \"special item\".\n",
    "\n",
    "If you consider the second group of three, the special item is of type `Z` (priority 52). The sum is `18 + 52 = 70`.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Question</b></h4> What is the sum of the priorities of <b>all</b> the special items?\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "94",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_buckets2(buckets_file: pathlib.Path) -> int:\n",
    "    buckets = buckets_file.read_text()  # do NOT remove this line\n",
    "    # Write your solution below this comment\n",
    "    pass"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}