demo_args_kwargs.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.7.3"
    },
    "colab": {
      "name": "demo_args_kwargs.ipynb",
      "provenance": []
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "TE-gi5cW4iP_"
      },
      "source": [
        "<table border=\"0\" align=\"left\" width=\"700\" height=\"144\">\n",
        "<tbody>\n",
        "<tr>\n",
        "<td width=\"120\"><img width=\"100\" src=\"https://static1.squarespace.com/static/5992c2c7a803bb8283297efe/t/59c803110abd04d34ca9a1f0/1530629279239/\" /></td>\n",
        "<td style=\"width: 600px; height: 67px;\">\n",
        "<h1 style=\"text-align: left;\">Function Parameters and Argument Passing</h1>\n",
        "<p><a href=\"https://colab.research.google.com/github/KenzieAcademy/python-notebooks/blob/master/demo_args_kwargs.ipynb\"> <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\" align=\"left\" width=\"188\" height=\"32\" /> </a></p>\n",
        "</td>\n",
        "</tr>\n",
        "</tbody>\n",
        "</table>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "nPtRXV-_4iQA"
      },
      "source": [
        "There are four types of function parameters in Python:\n",
        " - **Normal** params (named and positional)\n",
        " - **Keyword** params (named and default)\n",
        " - **Variable Parameters** (positional, preceded by single splat `*`)\n",
        " - **Variable Keyword Parameters** (named, preceded by double splat `**`)\n",
        " \n",
        "### What's the difference between \"Argument\" and \"Parameter\"??\n",
        "For the secret CS Pedant within you:\n",
        " - **Parameters** : The _names_ of the variables specified in a function definition.\n",
        " - **Arguments** : The actual variables passed into a function at runtime.\n",
        "  \n",
        "### Example\n",
        "```python\n",
        "def mult (a, b):\n",
        "    return a * b\n",
        "\n",
        "x = 3\n",
        "y = 4\n",
        "result = mult(x, y)\n",
        "```\n",
        "In the sample above, `a` and `b` are _parameters_ because they appear in the function definition.  `x` and `y` are arguments that are passed into the function.\n",
        "\n",
        "### What is this `*args` and `**kwargs` that I've seen in function definitions?\n",
        "These two names are frequently used idioms in Python.  `*args` is the name for variable, positional parameter list.  `**kwargs` is the name for variable, named Key Word Args (KWARGS).\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "yTdT_RUY4iQA"
      },
      "source": [
        "## Normal and Keyword Parameters"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "5y2Snwgm4iQB"
      },
      "source": [
        "# This function defines 3 normal parameters\n",
        "# These parameters are always required when the function is invoked.\n",
        "# Normal parameters also support using the name=value argument passing style.\n",
        "def normal(a, b, c):\n",
        "    print(a, b, c)\n",
        "    \n",
        "# positional argument passing\n",
        "normal(1, 2, 3)\n",
        "\n",
        "# name=value argument passing\n",
        "normal(a=10, b=20, c=30)\n",
        "\n",
        "# if the name=value style is used, then there is no need to be positional because we know what goes where.\n",
        "normal(c=300, a=100, b=200)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "LT9wayUd4iQE"
      },
      "source": [
        "## Variable Parameters\n",
        "The asterisk (or \"single splat\") character `*` denotes a _variable parameter list_ in function and method definitions. This allows a function to accept a variable number of positional arguments.  It is common practice in Python to name a variable parameter as `*args` but it can really be named anything you want.  You are only allowed to have one single-splat `*args` "
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "mBLDvZkF4iQF"
      },
      "source": [
        "def variable_param_function(p_first, p_second, *args):\n",
        "    print(\"First positional arg: \", p_first)\n",
        "    print(\"Second positional arg: \", p_second)\n",
        "    print(\"args type: \", type(args))\n",
        "    print(\"args: \", args)\n",
        "    for a in args:\n",
        "        print(\"variable arg: \", a)\n",
        "\n",
        "# Note that we're not giving ANY variable into *args here\n",
        "variable_param_function('First!', 'Second!')"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "6PYVxilz5a6M"
      },
      "source": [
        "# Here's what it looks like without the splat: \n",
        "# It passes the variable_stuff as a single argument.\n",
        "variable_stuff = [3, 4, 5]\n",
        "variable_param_function('F', 'S', variable_stuff)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "3b_prqmy5cJx"
      },
      "source": [
        "# Adding the splat: The list is unpacked before invoking the function.\n",
        "# Still need to supply the required p_first and p_second args.\n",
        "variable_stuff = ['v1', 'v2', 'v3']\n",
        "variable_param_function('F', 'S', *variable_stuff)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "i6pa79QH4iQI"
      },
      "source": [
        "Remember that the python interpreter does not care if you name your *args something else. It's just a Python idiom.\n",
        "Within the function itself, the `args` (without asterisk) will be a tuple containing all of the arguments passed in."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "xvWn844c4iQI"
      },
      "source": [
        "def args_demo(*args):\n",
        "    print(type(args), args)\n",
        "    \n",
        "# We can pass in nothing at all...\n",
        "args_demo()"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "ucOJ01nJ5pjF"
      },
      "source": [
        "# ...or pass in one thing\n",
        "args_demo(1)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "Vy8Ro8MM5qb9"
      },
      "source": [
        "# ...or pass in mixed things\n",
        "args_demo(345, 'foo')"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "QDDaFBOXssCA"
      },
      "source": [
        "### Splatting Examples"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "LvvU0Csf4iQL"
      },
      "source": [
        "# Let's say our arguments are already contained in a list.\n",
        "# We _could_ invoke the `args_demo` function by indexing each element:\n",
        "beatles = ('John', 'Paul', 'George', 'Ringo')\n",
        "args_demo(beatles[0], beatles[1], beatles[2], beatles[3])"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "IsVWG9yJ4iQP"
      },
      "source": [
        "# ... but why?\n",
        "# The * operator is overloaded to FLATTEN a sequence of arguments when calling a function.\n",
        "# This is called SPLATTING. The following is equivalent to the previous cell:\n",
        "args_demo(*beatles)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "j9alz5DF4iQR"
      },
      "source": [
        "# If the * operator is left off, the beatles list will be passed into the function as a tuple,\n",
        "# and the tuple will contain a single item.\n",
        "args_demo(beatles)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "1c-yeHYs4iQU"
      },
      "source": [
        "# What if the function does not have a *args parameter?\n",
        "# It is still possible to flatten (Splat) a list into a normal function\n",
        "def add_3_args(a, b, c):\n",
        "    return a + b + c\n",
        "\n",
        "add_3_args(*[1, 2, 3])"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ZgGKRJBy4iQZ"
      },
      "source": [
        "## Variable Keyword Parameters\n",
        "Variable _keyword_ parameters are similar to variable parameters, but they use the `**` operator syntax.  This marks a function parameter to accept an arbitrary number of keyword arguments.  `kwargs` is the conventional name used in Python as a parameter name for variable keyword arguments.  Within the function, the arguments arrive in a dictionary containing the names and their corresponding values."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "StthEAjn4iQa"
      },
      "source": [
        "def kwargs_demo(**kwargs):\n",
        "    print(type(kwargs), kwargs)\n",
        "    \n",
        "# Pass in nothing at all...\n",
        "kwargs_demo()"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "bi5240Ub52aV"
      },
      "source": [
        "# ...pass in a single keyword argument\n",
        "kwargs_demo(person='Alice')"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "KhkIMz1o54qH"
      },
      "source": [
        "# Any named parameters will end up in the kwargs dict. The name=value format is required.\n",
        "kwargs_demo(firstname=\"Bob\", lastname=\"Hunt\", id=12345, age=54)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "IhzOhJVZ4iQc"
      },
      "source": [
        "## Flattening a Dictionary with `**`\n",
        "The double splat operator also serves to FLATTEN a dictionary into keyword arguments for a function call."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "WsU8-r-H4iQc"
      },
      "source": [
        "def distance(x1, y1, x2, y2):\n",
        "    return ((x2 - x1)**2 + (y2-y1)**2) ** 0.5\n",
        "\n",
        "points = {'x1':1, 'y1':1, \n",
        "          'x2':4, 'y2':5}\n",
        "\n",
        "print(distance(**points))\n",
        "\n",
        "# The function call above is the same as this below\n",
        "print(distance(x1=1, y1=1, x2=4, y2=5))"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4O4rphlK4iQe"
      },
      "source": [
        "Note that dictionaries can also be flattened into functions that accept normal parameters (like _distance_), or functions that accept only variable keyword parameters.  Recall the kwargs_demo function from earlier:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "8MjE0z9V4iQf"
      },
      "source": [
        "kwargs_demo(**points)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ltlTsSIy4iQh"
      },
      "source": [
        "### Python 3.5+ allows passing multiple sets of keyword parameters (\"kwargs\") to a function within a single call, using the `**` syntax."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "ef_LYAJk4iQh"
      },
      "source": [
        "# This function has all positional arguments.\n",
        "def process_data(a, b, c, d):\n",
        "    print(a, b, c, d)\n",
        "\n",
        "# This function expects a dictionary of keys/values.\n",
        "def my_kwarg_func(**kwargs):\n",
        "    print(kwargs)\n"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "VfbISR_f4iQj"
      },
      "source": [
        "# Create two separate key/value dicts\n",
        "x = {'a': 1, 'b': 2}\n",
        "y = {'c': 3, 'd': 4}"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "FkDCdlIj4iQl"
      },
      "source": [
        "# Call first func, using the dicts.\n",
        "# As long as the dict keys match the function argument names, all is well!\n",
        "process_data(**x, **y)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "8E9Bnnaw4iQp"
      },
      "source": [
        "# We can call the func directly by splatting an inline dictionary...\n",
        "process_data(**{'a':100, 'b':200, 'c':300, 'd':400})"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "RQ3vaMxQ4iQs"
      },
      "source": [
        "The `process_data()` function **must** receive its arguments named as `a`, `b`, `c` and `d` only."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "RLMhPkcx4iQs"
      },
      "source": [
        "# What happens if argument names don't match?  TypeError!\n",
        "process_data(**{'a':100, 'b':200, 'c':300, 'z':400})"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "kmZ3yPRh4iQu"
      },
      "source": [
        "# We can also use the dict() keyword to provide name/value pairs.\n",
        "process_data(**dict(a=300, b=42, c=500, d=600))\n",
        "\n",
        "# But that is difficult to read! How about this? Will it work if things are out of order???\n",
        "process_data(d=600, c=500, a=400, b=42)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "gDJn4bmB4iQw"
      },
      "source": [
        "# You can even split up the data between a kwarg dict, and direct named arguments:\n",
        "x = {'a':1, 'b':2}\n",
        "process_data(**x, c=101, d=123)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "II1HsJeU4iQx"
      },
      "source": [
        "What about the other function .. does it care about `a`, `b`, `c`, `d`?\n",
        "No! You can pass it any name/value pairs you want to!\n",
        "This is great if you need to make changes to a function &mdash; you don't have to change the signature at all.\n",
        "But there is always a trade-off between enforcing argument types in the function signature, and allowing arbitrary name/value pairs to be used. When you use kwargs, your function callers must be aware of all required parameter names. Much like calling an API with JSON data. "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Zu8ihFYn4iQz"
      },
      "source": [
        "## Arbitrary function parameters\n",
        "A function definition that accepts both variable parameters, and variable _keyword_ parameters can accept an arbitrary number of arguments, whether they are passed as normal, variable, or variable keyword arguments.  This is particularly useful when adding new behavior to a function, because the signature does not have to change.  This also makes them easy to use for subclass constructors and decorators.\n",
        "\n",
        "In summary, the four types of function parameters you will encounter are:\n",
        " - normal\n",
        " - keyword\n",
        " - variable\n",
        " - variable keyword"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "Pt4QolNC4iQ0"
      },
      "source": [
        "# Function that has all four types of parameters:\n",
        "#   normal arg\n",
        "#   normal keyword arg\n",
        "#   variable positional\n",
        "#   variable keyword\n",
        "\n",
        "def all_type_func(norm, *args, kw='keyword', **kwargs):\n",
        "    print(norm, args, kw, kwargs)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "4x_MQMuyHzLd"
      },
      "source": [
        "all_type_func(1, 3, 'a', 'z', **{'kw': 2, 'c': 4})"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "MoKLjEP14iQ1"
      },
      "source": [
        "### Question: must `*args` always appear BEFORE `**kwargs` in my function signature?"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "0UFk5HTl4iQ2"
      },
      "source": [
        "# Lets try reversing the order of *args and **kwargs\n",
        "def reversed_args(**kwargs, *args):\n",
        "    print(kwargs)\n",
        "    print(args)\n",
        "    \n",
        "reversed_args(**x, *beatles)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "TkDRq0WV4iQK"
      },
      "source": [
        "## The versatile asterisk `*` operator\n",
        "As you can see by now, the asterisk operator `*` has several uses within python:\n",
        "\n",
        " - performs multiplication (e.g., `4 * 2`)\n",
        " - raises a number to a power (e.g., `2 ** 4`)\n",
        " - performs string repetition (e.g., `\"hello\" * 3`)\n",
        " - a marker for variable parameters in a function definition (e.g., `def func(*args):`)\n",
        " - flattens (unpacks) a sequence into function arguments\n",
        " - a marker for variable keyword parameters in a function definition (e.g., `def func(**kwargs)`)\n",
        " - flattens (unpacks) a dictionary as keyword arguments"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "CcBcvl8N4iQ3"
      },
      "source": [
        "## Conclusions & Takeaways\n",
        "- splat, unsplat\n",
        "- packing, unpacking\n",
        "- spread, unspread\n",
        "- positional expansion, keyword expansion\n",
        "- gather, scatter\n",
        "\n",
        "Whatever you call it, a wonderfully useful feature in Python is\n",
        "the ability to pass any number of arguments as positional args to a function (e.g., `foo(*args)`), and, similarly, to pass dictionary items as keyword args (e.g., `foo(**kwargs)`).\n",
        "And, with a similar syntax of `foo(*args, **kwargs)`, functions may be defined to accept an unknown number of positional or keword arguments!"
      ]
    }
  ]
}