1_Functions_Classes_Modules/11_Functions_Advanced.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Advanced Functions: Default values, variable scope and a note on documentation\n",
    "\n",
    "## Learning Goals\n",
    "\n",
    "- Learn how to use default parameters for functions\n",
    "- What the scope of a variable is and why it matters\n",
    "- How documentation helps with usability\n",
    "\n",
    "## Introduction\n",
    "\n",
    "The basics of function definition were shown in the previous notebook. Here, we want to provide some useful tips for using functions practically in your own code.\n",
    "Namely, how to give functions default parameters, i.e. values for parameters that it uses if no other values for them are supplied in the function call. You have already seen an example of a function with helpful default parameters when we discussed the `range()` function. Using defaults can help making function calls a bit more economic, and make some parameters optional. \n",
    "\n",
    "Further, we will talk a bit about the scope of a function, i.e., to which variables it has access. This is important for debugging and for managing your code especially in larger projects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Default parameters\n",
    "**Example: University Email Address**\n",
    "\n",
    "A function can of course also have more parameters than one. Suppose you want to write a function that gives you the university email address of a person that you have the name of. You need the name, but also need to know if the person is a student or an employee of the university."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def generate_university_email(name, status):\n",
    "  if status == 'student':\n",
    "    return f'{name}@student.someuniversity.com'\n",
    "  elif status == 'employee':\n",
    "    return f'{name}@someuniversity.com'\n",
    "  else:             # Error handling in case none of the 2 statuss is passed\n",
    "    print('Please provide a status of either \"student\" or \"employee\"')\n",
    "\n",
    "print(generate_university_email('someone','student'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since we didn't supply any default values, calling the function without all necessary arguments will make the function throw an error (namely, a `TypeError`), as seen in the following line of code!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(generate_university_email('someone'))   # Would throw an error"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With default arguments, we can fix that. Sometimes, you may not want to always specify every parameter when calling a function, especially when some parameters have the same value in most cases. In such situations, it's convenient to define default values for those parameters. This way, you only need to provide a value for the parameter if it should deviate from the default.\n",
    "\n",
    "Default values are defined by specifying a value directly in the function header, after the parameter name. If the parameter with a default value is not provided when the function is called, Python automatically assigns it the default value. However, if the caller provides a value, that value overrides the default.\n",
    "```python \n",
    "    def my_function_name(parameter1, parameter2 = default_value):\n",
    "```\n",
    "**Important:** When defining a function, all non-default parameters must be listed before any default parameters.\n",
    "\n",
    "So if we know that the majority of the university are students we can change our function by setting the default of `status` to `\"student\"`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def generate_university_email(name, status = \"student\"):\n",
    "  if status == 'student':\n",
    "    return f'{name}@student.someuniversity.com'\n",
    "  elif status == 'employee':\n",
    "    return f'{name}@someuniversity.com'\n",
    "  else:             # Error handling in case none of the 2 status is passed\n",
    "    print('Please provide a status of either \"student\" or \"employee\"')\n",
    "\n",
    "print(generate_university_email('someone')) # now works\n",
    "print(generate_university_email('someone' ,'employee'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variables inside and outside of Functions\n",
    "\n",
    "\n",
    "In Python, a function can access variables that are passed to it as parameters. Further, it also has access to variables defined outside the function in the calling script (called global variables). You can see this in the following example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "number_outside_of_function = 10\n",
    "\n",
    "def add_numbers(number):\n",
    "    print(number + number_outside_of_function)\n",
    "\n",
    "add_numbers(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Despite `number_outside_of_function` not having been passed explicitly, the function still managed to run and produce the desired output.\n",
    "While this might seem practical at first, this is a rather bad coding practice for a variety of reasons: Functions that rely on global variables are harder to reuse because they depend on specific external variables, making them less flexible. Additionally, if a function changes a global variable, it can unintentionally affect other parts of the program, which makes debugging more difficult. Using global variables also makes the function's behavior less clear, as it's not obvious what data the function depends on.\n",
    "\n",
    "> So, alltogether passing all needed variables as parameters, you make your functions cleaner, easier to understand, and more manageable. Use global variables with caution!\n",
    "\n",
    "Of course not every variable you use needs to be passed (for example constants). In the lower example you do not need to pass `pi` as a parameter because it its not variable but you would still define it inside the function have all variables present (either defined or passed as parameter) inside the function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math # will be explained later\n",
    "\n",
    "def calculate_circle_area(radius):\n",
    "  pi = math.pi\n",
    "  return pi * radius **2\n",
    "\n",
    "print(calculate_circle_area(1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Documentation: Docstrings\n",
    "In order to keep your code clean and readable (for yourself and others), using meaningful function and variable names is key! The two functions below do the exact same but the latter will be much easier to understand when re-reading the same code in a month.\n",
    "```python\n",
    "    def do_stuff(a,b):\n",
    "      return a*b\n",
    "```\n",
    "```python\n",
    "    def calculate_area(length, width):\n",
    "      return length * width\n",
    "```\n",
    "With increasing code complexity, meaningful variables might still be insufficient to quickly understand what the code is doing. To further improve readability and understanding especially for more complex functions docstrings are used.\n",
    "\n",
    "A docstring is a special type of comment that allows you to document your function. It's a brief description of what your function does, and it's placed immediately after the function definition, inside triple quotes (```\"\"\" \"\"\"``` ), or (```''' '''```):\n",
    "\n",
    "```python\n",
    "def function_with_docstring():\n",
    "  \"\"\"\n",
    "  I am a function with\n",
    "  a docstring. Look at me!\n",
    "  \"\"\"\n",
    "  return\n",
    "```\n",
    "\n",
    "Using docstrings helps you (and others) quickly understand:\n",
    "* What the function does\n",
    "* What input parameters it expects\n",
    "* What kind of result it returns (if any)\n",
    "* Sources/Lietrature for implented algorithms\n",
    "* General short tips on using the function\n",
    "\n",
    "(The docstring below was created by ChatGPT)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def format_second_duration(seconds):\n",
    "    \"\"\"\n",
    "    Formats a time duration from seconds into a more intuitive representation: hours, minutes, and seconds.\n",
    "\n",
    "    Parameters:\n",
    "    seconds (int): The total time duration in seconds.\n",
    "\n",
    "    Returns:\n",
    "    str: A string representing the time in the format \"HH:MM:SS\".\n",
    "\n",
    "    Example:\n",
    "    format_second_duration(3661) -> \"01:01:01\"  # 1 hour, 1 minute, 1 second\n",
    "    \"\"\"\n",
    "    hours = seconds // 3600\n",
    "    minutes = (seconds % 3600) // 60\n",
    "    remaining_seconds = seconds % 60\n",
    "    return f\"{hours:02}:{minutes:02}:{remaining_seconds:02}\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As with more complex code functions might no longer be in the same file, there is a quick lookup command to access the information from the docstring. Typing\n",
    "```python\n",
    "help(function_name)\n",
    "```\n",
    "prints out the docstring from the called function. Writing docstrings might seem a bit tedious, it is definitely worth to do so for longer coding projects, will make people appreciate your effort and is ultimately something that can greatly be outsourced to generative AI."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(format_second_duration)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary and Outlook\n",
    "\n",
    "In this notebook, we discussed how to add default arguments to functions, and how to add documentation to make it more user-friendly. We took a look at the behavior of 'outside' variables that have not been explicitly passed to functions, but rather existed in the global workspace regardless. Making functions rely on such external variables often is not desireable, and an anti-pattern of coding that should be avoided. In the next notebook, we will revisit datatypes, but this time, focus on a larger aspect: mutability. Mutability referes how an object can be changed in memory, and can provide pitfalls in more complex code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "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.12.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}