07. Functions/02. Writing Functions That Only Accept Keyword Arguments.ipynb

{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "7.2. Writing Functions That Only Accept Keyword\n",
      "Arguments"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Problem\n",
      "You want a function to only accept certain arguments by keyword.\n",
      "\n",
      "# Solution\n",
      "This feature is easy to implement if you place the keyword arguments after a `*` argument\n",
      "or a single unnamed `*`. For example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def recv(maxsize, *, block):\n",
      "    'Receives a message'\n",
      "    pass"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "recv(1024, True)  # TypeError"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "ename": "TypeError",
       "evalue": "recv() takes 1 positional argument but 2 were given",
       "output_type": "pyerr",
       "traceback": [
        "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m\n\u001b[0;31mTypeError\u001b[0m                                 Traceback (most recent call last)",
        "\u001b[0;32m<ipython-input-2-af62b1317680>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mrecv\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;36m1024\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;32mTrue\u001b[0m\u001b[0;34m)\u001b[0m  \u001b[0;31m# TypeError\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
        "\u001b[0;31mTypeError\u001b[0m: recv() takes 1 positional argument but 2 were given"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "recv(1024, block=True)  # Ok"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This technique can also be used to specify keyword arguments for functions that accept\n",
      "a varying number of positional arguments. For example:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def minimum(*values, clip=None):\n",
      "    m = min(values)\n",
      "    if clip is not None:\n",
      "        m = clip if clip > m else m\n",
      "    return m"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "minimum(1, 5, 2, -5, 10)  # Returns -5"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 5,
       "text": [
        "-5"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "minimum(1, 5, 2, -5, 10, clip=0)  # Returns 0"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 6,
       "text": [
        "0"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Discussion\n",
      "Keyword-only arguments are often a good way to enforce greater code clarity when\n",
      "specifying optional function arguments. For example, consider a call like this:\n",
      "```python\n",
      "msg = recv(1024, False)\n",
      "```\n",
      "If someone is not intimately familiar with the workings of the `recv()`, they may have\n",
      "no idea what the `False` argument means. On the other hand, it is much clearer if the\n",
      "call is written like this:\n",
      "```python\n",
      "msg = recv(1024, block=False)\n",
      "```\n",
      "The use of keyword-only arguments is also often preferrable to tricks involving\n",
      "`**kwargs`, since they show up properly when the user asks for help:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "help(recv)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Help on function recv in module __main__:\n",
        "\n",
        "recv(maxsize, *, block)\n",
        "    Receives a message\n",
        "\n"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Keyword-only arguments also have utility in more advanced contexts. For example,\n",
      "they can be used to inject arguments into functions that make use of the `*args` and\n",
      "`**kwargs` convention for accepting all inputs. See Recipe 9.11 for an example."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}