Part.3.B.3.decorator-iterator-generator.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 函数工具"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这一章要讲的是迭代器、生成器和装饰器，这些都是函数工具。有人把它们称为 **DIG**（Decorator，Iterator，Generator）—— 它们都是真正掌握 Python 的关键。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 迭代器（Iterator）"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们已经见过 Python 中的所有容器，都是可迭代的 —— 准确地讲，是可以通过迭代遍历每一个元素："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "t, h, i, s,  , i, s,  , a,  , s, t, r, i, n, g, ., \n",
      "item 1, item 2, 3, 5, \n",
      "1, 2, 3, 4, 5, \n"
     ]
    }
   ],
   "source": [
    "string = \"this is a string.\"\n",
    "list = ['item 1', 'item 2', 3, 5]\n",
    "set = (1, 2, 3, 4, 5)\n",
    "for c in string:\n",
    "    print(c, end=', ')\n",
    "print()\n",
    "for L in list:\n",
    "    print(L, end=', ')\n",
    "print()\n",
    "for s in set:\n",
    "    print(s, end=', ')\n",
    "print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "有个内建函数，就是用来把一个 “可迭代对象”（Iterable）转换成 “迭代器”（Iterator）的 —— `iter()`。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "str_iterator"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "tuple_iterator"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "list_iterator"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.interactiveshell import InteractiveShell\n",
    "InteractiveShell.ast_node_interactivity = \"all\"\n",
    "\n",
    "i = iter(\"Python\")\n",
    "type(i)\n",
    "s = iter((1, 2, 3, 4, 5))\n",
    "type(s)\n",
    "L = iter(['item 1', 'item 2', 3, 5])\n",
    "type(L)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "迭代器如何使用呢？有个 `next()` 函数："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'P'"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "'y'"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "'t'"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "'h'"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "'o'"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "'n'"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.interactiveshell import InteractiveShell\n",
    "InteractiveShell.ast_node_interactivity = \"all\"\n",
    "\n",
    "i = iter(\"Python\")\n",
    "next(i)\n",
    "next(i)\n",
    "next(i)\n",
    "next(i)\n",
    "next(i)\n",
    "next(i)\n",
    "# next(i) 前面已经到 'n' 了，再调用就会有 StopIteration 错误提示。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "在 `i` 这个迭代器里一共有 6 个元素，所以，`next(i)` 在被调用 6 次之后，就不能再被调用了，一旦再被调用，就会触发 StopIteration 错误。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "那我们怎么自己写一个迭代器呢？\n",
    "\n",
    "迭代器是个 Object，所以，写迭代器的时候写的是 Class，比如，我们写一个数数的迭代器，Counter："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 85,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "11"
      ]
     },
     "execution_count": 85,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "12"
      ]
     },
     "execution_count": 85,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "13"
      ]
     },
     "execution_count": 85,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "101\n",
      "102\n",
      "103\n",
      "104\n",
      "105\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "type"
      ]
     },
     "execution_count": 85,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "class Counter(object):\n",
    "    def __init__(self, start, stop):\n",
    "        self.current = start\n",
    "        self.stop = stop\n",
    "    def __iter__(self):\n",
    "        return self\n",
    "    def __next__(self):\n",
    "        if self.current > self.stop:\n",
    "            raise StopIteration\n",
    "        else:\n",
    "            c = self.current\n",
    "            self.current += 1\n",
    "        return c\n",
    "\n",
    "c = Counter(11, 20)\n",
    "next(c)\n",
    "next(c)\n",
    "next(c)\n",
    "for c in Counter(101, 105):\n",
    "    print(c, end=', ')\n",
    "type(Counter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这里的重点在于两个函数的存在，`__iter__(self)` 和 `__next__(self)`。\n",
    "\n",
    "```python\n",
    "def __iter__(self):\n",
    "    return self\n",
    "```\n",
    "\n",
    "这两句是约定俗成的写法，写上它们，`Counter` 这个类就被会被识别为 Iterator 类型。而后再有 `__next__(self)` 的话，它就是个完整的迭代器了。除了可以用 `for loop` 之外，也可以用 `while loop` 去遍历迭代器中的所有元素："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "101\n",
      "102\n",
      "103\n",
      "201\n",
      "202\n",
      "203\n"
     ]
    }
   ],
   "source": [
    "class Counter(object):\n",
    "    def __init__(self, start, stop):\n",
    "        self.current = start\n",
    "        self.stop = stop\n",
    "    def __iter__(self):\n",
    "        return self\n",
    "    def __next__(self):\n",
    "        if self.current > self.stop:\n",
    "            raise StopIteration\n",
    "        else:\n",
    "            c = self.current\n",
    "            self.current += 1\n",
    "        return c\n",
    "\n",
    "\n",
    "for c in Counter(101, 103):\n",
    "    print(c, sep=', ')\n",
    "\n",
    "c = Counter(201, 203)\n",
    "while True:\n",
    "    try:\n",
    "        print(next(c), sep=', ')\n",
    "    except StopIteration:\n",
    "        break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 生成器（Generator）"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "那用函数（而不是 Class）能不能写一个 Counter 呢？答案是能，用生成器（Generator）就行。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "101\n",
      "102\n",
      "103\n",
      "104\n",
      "105\n"
     ]
    }
   ],
   "source": [
    "def counter(start, stop):\n",
    "    while start <= stop:\n",
    "        yield start\n",
    "        start += 1\n",
    "for i in counter(101, 105):\n",
    "    print(i)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "哎呀！怎么感觉这个简洁很多呢？\n",
    "\n",
    "不过，是否简洁并不是问题，这次看起来用生成器更简单，无非是因为当前的例子更适合用生成器而已。在不同的情况下，用迭代器和用生成器各有各的优势。\n",
    "\n",
    "这里的关键在于 `yield` 这个语句。它和 `return` 最明显的不同在于，在它之后的语句依然会被执行 —— 而 `return` 之后的语句就被忽略了。\n",
    "\n",
    "但正因为这个不同，在写生成器的时候，只能用 `yield`，而没办法使用 `return` —— 你现在可以回去把上面代码中的 `yield` 改成 `return` 看看，然后体会一下它们之间的不同。\n",
    "\n",
    "生成器函数被 `next()` 调用后，执行到 `yield` 生成一个值返回（然后继续执行 `next()` 外部剩余的语句）；下次再被 `next()` 调用的时候，从上次生成返回值的 `yield` 语句处继续执行…… 如果感觉费解，就多读几遍 —— 而后再想想若是生成器中有多个 `yield` 语句会是什么情况？"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "还有一种东西，叫做生成器表达式。先看个例子："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 84,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<generator object <genexpr> at 0x107cc0048>\n",
      "0\n",
      "2\n",
      "4\n",
      "6\n",
      "8\n"
     ]
    }
   ],
   "source": [
    "even = (e for e in range(10) if not e % 2)\n",
    "# odd = (o for o in range(10) if o % 2)\n",
    "print(even)\n",
    "for e in even:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "其实，这种表达式我们早就在 List Comprehension 里见过 —— 那就是通过生成器表达式完成的。\n",
    "\n",
    "**注意**\n",
    "\n",
    "仔细看 `even = (e for e in range(10) if not e % 2)` 中最外面那层括号，用了圆括号，`even` 就是用生成器创造的迭代器（Iterator），若是用了方括号，那就是用生成器创造的列表（List）—— 当然用花括号 `{}` 生成的就是集合（Set）……"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 77,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1, 3, 5, 7, 9]\n",
      "1\n",
      "3\n",
      "5\n",
      "7\n",
      "9\n"
     ]
    }
   ],
   "source": [
    "# even = (e for e in range(10) if not e % 2)\n",
    "odd = [o for o in range(10) if o % 2]\n",
    "print(odd)\n",
    "for o in odd:\n",
    "    print(o)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 78,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{1, 3, 5, 7, 9}\n",
      "1\n",
      "3\n",
      "5\n",
      "7\n",
      "9\n"
     ]
    }
   ],
   "source": [
    "# even = (e for e in range(10) if not e % 2)\n",
    "odd = {o for o in range(10) if o % 2}\n",
    "print(odd)\n",
    "for o in odd:\n",
    "    print(o)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**生成器表达式必须在括号内使用**（参见官方 [HOWTOS](https://docs.python.org/3/howto/functional.html#generator-expressions-and-list-comprehensions)），包括函数的参数括号，比如："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 81,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "20\n"
     ]
    }
   ],
   "source": [
    "sum_of_even = sum(e for e in range(10) if not e % 2)\n",
    "print(sum_of_even)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "函数内部当然可以包含其它的函数，以下就是一个函数中包含着其它函数的结构示例：\n",
    "\n",
    "```python\n",
    "def a_func():\n",
    "    def b_func():\n",
    "        pass\n",
    "    def c_func():\n",
    "        pass\n",
    "        def d_func():\n",
    "            pass\n",
    "        b_func()\n",
    "    return True\n",
    "```\n",
    "\n",
    "想象一下，如果，我们让一个函数返回的是另外一个函数呢？我们一步一步来："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hi, I'm a_func!\n"
     ]
    }
   ],
   "source": [
    "def a_func():\n",
    "    def b_func():\n",
    "        print(\"Hi, I'm b_func!\")\n",
    "    print(\"Hi, I'm a_func!\")\n",
    "a_func()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hi, I'm a_func!\n",
      "Hi, I'm b_func!\n"
     ]
    }
   ],
   "source": [
    "def a_func():\n",
    "    def b_func():\n",
    "        print(\"Hi, I'm b_func!\")\n",
    "    print(\"Hi, I'm a_func!\")\n",
    "    b_func()\n",
    "a_func()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "上一个代码，我们可以写成这样 —— 让 `a_func()` 将它内部的 `b_func()` 作为它的返回值："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hi, I'm a_func!\n",
      "Hi, I'm b_func!\n"
     ]
    }
   ],
   "source": [
    "def a_func():\n",
    "    def b_func():\n",
    "        print(\"Hi, I'm b_func!\")\n",
    "    print(\"Hi, I'm a_func!\")\n",
    "    return b_func()\n",
    "a_func()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "如果我们在 `return` 语句里只写函数名呢？好像这样："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hi, I'm a_func!\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<function __main__.a_func.<locals>.b_func()>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def a_func():\n",
    "    def b_func():\n",
    "        print(\"Hi, I'm b_func!\")\n",
    "    print(\"Hi, I'm a_func!\")\n",
    "    return b_func\n",
    "a_func()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这次返回的不是调用 `b_func()` 这个函数的执行结果，返回的是 `b_func` 这个*函数本身*。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "toc-hr-collapsed": true
   },
   "source": [
    "## 装饰器（Decorator）"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 函数也是对象"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这是关键：\n",
    "\n",
    "> 函数本身也是对象（即，Python 定义的某个 Class 的一个 Instance）。\n",
    "\n",
    "于是，函数本身其实可以与其它的数据类型一样，作为其它函数的参数或者返回值。\n",
    "\n",
    "让我们分步走 —— 注意，在以下代码中，`a_decorator` 返回的是一个函数的调用 `wrapper()`，而不是 `wrapper` 这个函数本身："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hi, I'm a_func!\n",
      "We can do sth. before a func is called...\n",
      "Hi, I'm a_func!\n",
      "... and we can do sth. after it is called...\n"
     ]
    }
   ],
   "source": [
    "def a_decorator(func):\n",
    "    def wrapper():\n",
    "        print('We can do sth. before a func is called...')\n",
    "        func()\n",
    "        print('... and we can do sth. after it is called...')\n",
    "    return wrapper()\n",
    "\n",
    "def a_func():\n",
    "    print(\"Hi, I'm a_func!\")\n",
    "    \n",
    "a_func()\n",
    "a_decorator(a_func)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "如果返回的是函数本身，`wrapper`，输出结果跟你想的并不一样："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hi, I'm a_func!\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<function __main__.a_decorator.<locals>.wrapper()>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def a_decorator(func):\n",
    "    def wrapper():\n",
    "        print('We can do sth. before a func is called...')\n",
    "        func()\n",
    "        print('... and we can do sth. after it is called...')\n",
    "    return wrapper  # \n",
    "\n",
    "def a_func():\n",
    "    print(\"Hi, I'm a_func!\")\n",
    "    \n",
    "a_func()\n",
    "a_decorator(a_func)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 装饰器操作符"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "不过，Python 提供了一个针对函数的操作符 `@`，它的作用是…… 很难一下子说清楚，先看看以下代码："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "We can do sth. before calling a_func...\n",
      "Hi, I'm a_func!\n",
      "... and we can do sth. after it was called...\n"
     ]
    }
   ],
   "source": [
    "def a_decorator(func):\n",
    "    def wrapper():\n",
    "        print('We can do sth. before calling a_func...')\n",
    "        func()\n",
    "        print('... and we can do sth. after it was called...')\n",
    "    return wrapper\n",
    "\n",
    "@a_decorator\n",
    "def a_func():\n",
    "    print(\"Hi, I'm a_func!\")\n",
    "    \n",
    "a_func()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "注意：以上的代码中，`a_decorator(func)` 返回的是 `wrapper` 这个函数本身。\n",
    "\n",
    "在我们定义 `a_func()` 的时候，在它之前，加上了一句 `@a_decorator`；这么做的结果是：\n",
    "\n",
    "> 每次 `a_func()` 在被调用的时候，因为它之前有一句 `@a_decorator`，所以它会先被当作参数传递到 `a_decorator(func)` 这个函数中…… 而后，真正的执行，是在 `a_decorator()` 里被完成的。\n",
    "\n",
    "—— 被 `@` 调用的函数，叫做 “装饰器”（Decorator），比如，以上代码中的 `a_decorator(func)`。\n",
    "\n",
    "现在可以很简单直接地说清楚装饰器的作用了：\n",
    "\n",
    "```python\n",
    "@a_decorator\n",
    "def a_func():\n",
    "    ...\n",
    "```\n",
    "\n",
    "等价于\n",
    "\n",
    "```python\n",
    "def a_func():\n",
    "    ...\n",
    "a_func = a_decorator(a_func)\n",
    "```\n",
    "\n",
    "就是用 `a_decorator` 的调用结果替换掉原来的函数。`a_decorator` 返回值是什么，以后调用 `a_func` 时就是在调用这个返回值，而 `a_decorator` 本身此时已经执行完毕了。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 装饰器的用途"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Decorator 最常用的场景是什么呢？最常用的场景就是用来改变其它函数的行为。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The quick brown fox jumps over the lazy dog.\n"
     ]
    }
   ],
   "source": [
    "def an_output():\n",
    "    return 'The quick brown fox jumps over the lazy dog.'\n",
    "print(an_output())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG.\n"
     ]
    }
   ],
   "source": [
    "def uppercase(func):\n",
    "    def wrapper():\n",
    "        original_result = func()\n",
    "        modified_restult = original_result.upper()\n",
    "        return modified_restult\n",
    "    return wrapper\n",
    "\n",
    "@uppercase\n",
    "def an_output():\n",
    "    return 'The quick brown fox jumps over the lazy dog.'\n",
    "print(an_output())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "你还可以给一个函数加上一个以上的装饰器："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<strong>THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG.</strong>\n"
     ]
    }
   ],
   "source": [
    "def uppercase(func):\n",
    "    def wrapper():\n",
    "        original_result = func()\n",
    "        modified_restult = original_result.upper()\n",
    "        return modified_restult\n",
    "    return wrapper\n",
    "def strong(func):\n",
    "    def wrapper():\n",
    "        original_result = func()\n",
    "        modified_restult = '<strong>'+original_result+'</strong>'\n",
    "        return modified_restult\n",
    "    return wrapper\n",
    "\n",
    "@strong\n",
    "@uppercase\n",
    "def an_output():\n",
    "    return 'The quick brown fox jumps over the lazy dog.'\n",
    "print(an_output())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "你把两个装饰器的顺序调换一下写成下面这样试试：\n",
    "\n",
    "```python\n",
    "@uppercase\n",
    "@strong\n",
    "def an_output():\n",
    "...\n",
    "```\n",
    "装饰器的执行顺序是 “自下而上” —— 其实是 “由里到外” 更为准确。体会一下。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 装饰带有参数的函数"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "到现在我们见到的使用装饰器的函数都是没有参数的：`an_output` 以及之前的 `a_func`。\n",
    "\n",
    "如果被装饰的函数有参数怎么办？装饰器自身内部又应该怎么写？\n",
    "\n",
    "这时候，Python 的 `*args` and `**kwargs` 的威力就显现出来了 —— 之前怕麻烦没有通过仔细反复阅读搞定这 “一个星号、两个星号、直接晕倒” 的知识点的人，现在恐怕要吃亏了……\n",
    "\n",
    "装饰器函数本身这么写：\n",
    "\n",
    "```python\n",
    "def a_decorator(func):\n",
    "    def wrapper(*args, **kwargs):\n",
    "        return original_result\n",
    "    # ...   \n",
    "    return wrapper\n",
    "```\n",
    "\n",
    "在这里，`(*args, **kwargs)` 非常强大，它可以匹配所有函数传进来的所有参数…… 准确地讲，`*args` 接收并处理所有传递进来的位置参数，`**kwargs` 接收并处理所有传递进来的关键字参数。\n",
    "\n",
    "假设我们有这么个函数："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello! Jack.\n"
     ]
    }
   ],
   "source": [
    "def say_hi(greeting, name=None):\n",
    "    return greeting + '! ' + name + '.'\n",
    "\n",
    "print(say_hi('Hello', 'Jack'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "如果我们想在装饰器里对函数名、参数，都做些事情 —— 比如，我们写个 `@trace` 用来告诉用户调用一个函数的时候都发生了什么……"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Trace: You've called a function: say_hi(), with args: ('Hello',); kwargs: {'name': 'Jack'}\n",
      "Trace: say_hi('Hello',) returned: Hello! Jack.\n",
      "Hello! Jack.\n"
     ]
    }
   ],
   "source": [
    "def trace(func):\n",
    "    def wrapper(*args, **kwargs):\n",
    "        print(f\"Trace: You've called a function: {func.__name__}(),\",\n",
    "              f\"with args: {args}; kwargs: {kwargs}\")\n",
    "    \n",
    "        original_result = func(*args, **kwargs)\n",
    "        print(f\"Trace: {func.__name__}{args} returned: {original_result}\")\n",
    "        return original_result\n",
    "    return wrapper\n",
    "\n",
    "@trace\n",
    "def say_hi(greeting, name=None):\n",
    "    return greeting + '! ' + name + '.'\n",
    "\n",
    "print(say_hi('Hello', name='Jack'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "有了以上的基础知识之后，再去阅读 Python Decorator Library 的 Wiki 页面就会轻松许多：\n",
    "\n",
    "> https://wiki.python.org/moin/PythonDecoratorLibrary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 学会装饰器究竟有多重要？"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "装饰器一定要学会 —— 因为很多人就是不会。\n",
    "\n",
    "Oreilly.com 上有篇文章，《5 reasons you need to learn to write Python decorators》中，其中的第五条竟然是：**Boosting your career**!\n",
    "\n",
    "> Writing decorators isn't easy at first. It's not rocket science, but takes enough effort to learn, and to grok the nuances involved, that many developers will never go to the trouble to master it. And that works to your advantage. When you become the person on your team who learns to write decorators well, and write decorators that solve real problems, other developers will use them. Because once the hard work of writing them is done, decorators are so easy to use. This can massively magnify the positive impact of the code you write. And it just might make you a hero, too.\n",
    "> \n",
    "> As I've traveled far and wide, training hundreds of working software engineers to use Python more effectively, teams have consistently reported writing decorators to be one of the most valuable and important tools they've learned in my advanced Python programming workshops.\n",
    "\n",
    "为什么有那么多人就是学不会呢？—— 只不过是因为在此之前，遇到 `*args` `**kwargs` 的时候，“一个星号、两个星号、直接晕倒”…… 而后并未再多挣扎一下。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"./Part.3.B.4.regex.ipynb\" ><small>Next Page</small></a>"
   ]
  }
 ],
 "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"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": false,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": false,
   "user_envs_cfg": false
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "toc-autonumbering": true
 },
 "nbformat": 4,
 "nbformat_minor": 2
}