07. Functions/05. Defining Functions with Default Arguments.ipynb

{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "7.5. Defining Functions with Default Arguments"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Problem\n",
      "You want to define a function or method where one or more of the arguments are\n",
      "optional and have a default value.\n",
      "\n",
      "# Solution\n",
      "On the surface, defining a function with optional arguments is easy\u2014simply assign\n",
      "values in the definition and make sure that default arguments appear last. For example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def spam(a, b=42):\n",
      "    print(a, b)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1)  # Ok. a=1, b=42"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "1 42\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1, 2)  # Ok. a=1, b=2"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "1 2\n"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If the default value is supposed to be a mutable container, such as a list, set, or dictionary,\n",
      "use `None` as the default and write code like this:\n",
      "```python\n",
      "# Using a list as a default value\n",
      "def spam(a, b=None):\n",
      "    if b is None:\n",
      "        b = []\n",
      "        \u2026\n",
      "```\n",
      "If, instead of providing a default value, you want to write code that merely tests whether\n",
      "an optional argument was given an interesting value or not, use this idiom:\n",
      "Here\u2019s how this function behaves:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "_no_value = object()\n",
      "def spam(a, b=_no_value):\n",
      "    if b is _no_value:\n",
      "        print('No b value supplied')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "No b value supplied\n"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1, 2)  # b = 2"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 6
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1, None)  # b = None"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Carefully observe that there is a distinction between passing no value at all and passing\n",
      "a value of `None`."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Discussion\n",
      "Defining functions with default arguments is easy, but there is a bit more to it than meets\n",
      "the eye.\n",
      "\n",
      "First, the values assigned as a default are bound only once at the time of function defi\u2010\n",
      "nition. Try this example to see it:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = 42\n",
      "def spam(a, b=x):\n",
      "    print(a, b)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 8
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "1 42\n"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = 23  # Has no effect\n",
      "spam(1)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "1 42\n"
       ]
      }
     ],
     "prompt_number": 10
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Notice how changing the variable `x` (which was used as a default value) has no effect\n",
      "whatsoever. This is because the default value was fixed at function definition time.\n",
      "\n",
      "Second, the values assigned as defaults should always be immutable objects, such as\n",
      "`None`, `True`, `False`, numbers, or strings. Specifically, never write code like this:\n",
      "```python\n",
      "def spam(a, b=[]): # NO!\n",
      "    \u2026\n",
      "```\n",
      "If you do this, you can run into all sorts of trouble if the default value ever escapes the\n",
      "function and gets modified. Such changes will permanently alter the default value across\n",
      "future function calls. For example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def spam(a, b=[]):\n",
      "    print(b)\n",
      "    return b"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 11
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = spam(1)\n",
      "x"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[]\n"
       ]
      },
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 12,
       "text": [
        "[]"
       ]
      }
     ],
     "prompt_number": 12
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x.append(99)\n",
      "x.append('Yow!')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 13
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 14,
       "text": [
        "[99, 'Yow!']"
       ]
      }
     ],
     "prompt_number": 14
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1)  # Modified list gets returned!"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[99, 'Yow!']\n"
       ]
      },
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 15,
       "text": [
        "[99, 'Yow!']"
       ]
      }
     ],
     "prompt_number": 15
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "That\u2019s probably not what you want. To avoid this, it\u2019s better to assign `None` as a default\n",
      "and add a check inside the function for it, as shown in the solution.\n",
      "\n",
      "The use of the `is` operator when testing for `None` is a critical part of this recipe. \n",
      "Sometimes people make this mistake:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def spam(a, b=None):\n",
      "    if not b:  # NO! Use 'b is None' instead\n",
      "        b = []"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 16
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The problem here is that although `None` evaluates to `False`, many other objects (e.g.,\n",
      "zero-length strings, lists, tuples, dicts, etc.) do as well. Thus, the test just shown would\n",
      "falsely treat certain inputs as missing. For example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1)  # OK"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 17
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = []"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 18
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1, x)  # Silent error. x value overwritten by default"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 19
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1, 0)  # Silent error. 0 ignored"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 20
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "spam(1, '')  # Silent error. '' ignored"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 21
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The last part of this recipe is something that\u2019s rather subtle\u2014a function that tests to see\n",
      "whether a value (any value) has been supplied to an optional argument or not. The tricky\n",
      "part here is that you can\u2019t use a default value of `None`, `0`, or `False` to test for the presence\n",
      "of a user-supplied argument (since all of these are perfectly valid values that a user might\n",
      "supply). Thus, you need something else to test against.\n",
      "\n",
      "To solve this problem, you can create a unique private instance of `object`, as shown in\n",
      "the solution (the `_no_value` variable). In the function, you then check the identity of\n",
      "the supplied argument against this special value to see if an argument was supplied or\n",
      "not. The thinking here is that it would be extremely unlikely for a user to pass the\n",
      "`_no_value` instance in as an input value. Therefore, it becomes a safe value to check\n",
      "against if you\u2019re trying to determine whether an argument was supplied or not.\n",
      "\n",
      "The use of `object()` might look rather unusual here. `object` is a class that serves as the\n",
      "common base class for almost all objects in Python. You can create instances of `object`, \n",
      "but they are wholly uninteresting, as they have no notable methods nor any instance \n",
      "data (because there is no underlying instance dictionary, you can\u2019t even set any\n",
      "attributes). About the only thing you can do is perform tests for identity. This makes\n",
      "them useful as special values, as shown in the solution."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}