Part.2.D.6-modules.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 保存到文件的函数"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "写好的函数，当然最好保存起来，以便将来随时调用。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 模块"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们可以将以下内容保存到一个名为 `mycode.py` 的文件中 —— 这样可以被外部调用的 `.py` 文件，有个专门的称呼，**模块**（Module）—— 于是，它（任何一个 `.py` 文件）也可以被称为*模块*："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# %load mycode.py\n",
    "# 当前这个 Code Cell 中的代码，保存在当前文件夹中的 mycode.py 文件中\n",
    "# 以下的代码，是使用 Jupyter 命令 %load mycode.py 导入到当前 Code Cell 中的：\n",
    "\n",
    "def is_prime(n):\n",
    "    \"\"\"\n",
    "    Return a boolean value based upon\n",
    "    whether the argument n is a prime number.\n",
    "    \"\"\"\n",
    "    if n < 2:\n",
    "        return False\n",
    "    if n == 2:\n",
    "        return True\n",
    "    for m in range(2, int(n**0.5)+1):\n",
    "        if (n % m) == 0:\n",
    "            return False\n",
    "    else:\n",
    "        return True\n",
    "\n",
    "def say_hi(*names, greeting='Hello', capitalized=False):\n",
    "    \"\"\"\n",
    "    Print a string, with a greeting to everyone.\n",
    "    :param *names: tuple of names to be greeted.\n",
    "    :param greeting: 'Hello' as default.\n",
    "    :param capitalized: Whether name should be converted to capitalized before print. False as default.\n",
    "    :returns: None\n",
    "    \"\"\"\n",
    "    for name in names:\n",
    "        if capitalized:\n",
    "            name = name.capitalize()\n",
    "        print(f'{greeting}, {name}!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "而后，我们就可以在其它地方这样使用（以上代码现在已经保存在当前工作目录中的 `mycode.py`）："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function is_prime in module mycode:\n",
      "\n",
      "is_prime(n)\n",
      "    Return a boolean value based upon\n",
      "    whether the argument n is a prime number.\n",
      "\n",
      "Help on function say_hi in module mycode:\n",
      "\n",
      "say_hi(*names, greeting='Hello', capitalized=False)\n",
      "    Print a string, with a greeting to everyone.\n",
      "    :param *names: tuple of names to be greeted.\n",
      "    :param greeting: 'Hello' as default.\n",
      "    :param capitalized: Whether name should be converted to capitalzed before print. False as default.\n",
      "    :returns: None\n",
      "\n",
      "'mycode'\n",
      "\n",
      "True\n",
      "\n",
      "Hello, mike!\n",
      "Hello, zoe!\n"
     ]
    }
   ],
   "source": [
    "from IPython.core.interactiveshell import InteractiveShell\n",
    "InteractiveShell.ast_node_interactivity = \"all\"\n",
    "\n",
    "import mycode\n",
    "\n",
    "help(mycode.is_prime)\n",
    "help(mycode.say_hi)\n",
    "\n",
    "mycode.__name__\n",
    "mycode.is_prime(3)\n",
    "mycode.say_hi('mike', 'zoe')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "以上这个**模块**（[Module](https://docs.python.org/3/tutorial/modules.html)）的名称，就是 `mycode`。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 模块文件系统目录检索顺序"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "当你向 Python 说 `import ...` 的时候，它要去寻找你所指定的文件，那个文件应该是 `import` 语句后面引用的名称，再加上 `.py` 构成的名字的文件。Python 会按照以下顺序去寻找：\n",
    "\n",
    "> * 先去看看内建模块里有没有你所指定的名称；\n",
    "> * 如果没有，那么就按照 `sys.path` 所返回的目录列表顺序去找。\n",
    "\n",
    "你可以通过以下代码查看你自己当前机器的 `sys.path`："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "sys.path"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "在 `sys.path` 所返回的目录列表中，你当前的工作目录排在第一位。\n",
    "\n",
    "有时，你需要指定检索目录，因为你知道你要用的模块文件在什么位置，那么可以用 `sys.path.append()` 添加一个搜索位置：\n",
    "\n",
    "```python\n",
    "import sys\n",
    "sys.path.append(\"/My/Path/To/Module/Directory\")\n",
    "import my_module \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 系统内建的模块"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "你可以用以下代码获取系统内建模块的列表："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('_abc',\n",
       " '_ast',\n",
       " '_codecs',\n",
       " '_collections',\n",
       " '_functools',\n",
       " '_imp',\n",
       " '_io',\n",
       " '_locale',\n",
       " '_operator',\n",
       " '_signal',\n",
       " '_sre',\n",
       " '_stat',\n",
       " '_string',\n",
       " '_symtable',\n",
       " '_thread',\n",
       " '_tracemalloc',\n",
       " '_warnings',\n",
       " '_weakref',\n",
       " 'atexit',\n",
       " 'builtins',\n",
       " 'errno',\n",
       " 'faulthandler',\n",
       " 'gc',\n",
       " 'itertools',\n",
       " 'marshal',\n",
       " 'posix',\n",
       " 'pwd',\n",
       " 'sys',\n",
       " 'time',\n",
       " 'xxsubtype',\n",
       " 'zipimport')"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.interactiveshell import InteractiveShell\n",
    "InteractiveShell.ast_node_interactivity = \"all\"\n",
    "import sys\n",
    "\n",
    "sys.builtin_module_names\n",
    "\"_sre\" in sys.builtin_module_names # True\n",
    "\"math\" in sys.builtin_module_names # False （根据自己电脑库的安装情况，结果会有不同）"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "跟变量名、函数名，不能与关键字重名一样，你的模块名称也最好别与系统内建模块名称重合。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 引入指定模块中的特定函数"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "当你使用 `import mycode` 的时候，你向当前工作空间引入了 `mycode` 文件中定义的所有函数，相当于："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mycode import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "你其实可以只引入当前需要的函数，比如，只引入 `is_prime()`："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mycode import is_prime"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这种情况下，你就不必使用 `mycode.is_prime()` 了；而是就好像这个函数就写在当前工作空间一样，直接写 `is_prime()`："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from mycode import is_prime\n",
    "is_prime(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "注意，如果当前目录中并没有 `mycode.py` 这个文件，那么，`mycode` 会被当作目录名再被尝试一次 —— 如果当前目录内，有个叫做 `mycode` 的目录（或称文件夹）且该目录下同时要存在一个 [`__init__.py`](https://docs.python.org/3/reference/import.html#regular-packages) 文件（通常为空文件，用于标识本目录形成一个包含多个模块的 **包**（[packages](https://docs.python.org/3/reference/import.html#regular-packages)），它们处在一个独立的 **命名空间**（[namespace](https://docs.python.org/3/glossary.html#term-namespace-package)）），那么，`from mycode import *` 的作用就是把 `mycode` 这个文件夹中的所有 `.py` 文件全部导入……\n",
    "\n",
    "如果我们想要导入 `foo` 这个目录中的 `bar.py` 这个模块文件，那么，可以这么写：\n",
    "\n",
    "```python\n",
    "import foo.bar\n",
    "```\n",
    "或者\n",
    "```python\n",
    "from foo import bar\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 引入并使用化名"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "有的时候，或者为了避免混淆，或者为了避免输入太多字符，我们可以为引入的函数设定 **化名**（alias），而后使用化名调用函数。比如："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from mycode import is_prime as isp\n",
    "isp(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "甚至干脆给整个模块取个化名："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, mike!\n",
      "Hello, zoe!\n"
     ]
    }
   ],
   "source": [
    "from IPython.core.interactiveshell import InteractiveShell\n",
    "InteractiveShell.ast_node_interactivity = \"all\"\n",
    "\n",
    "import mycode as m\n",
    "\n",
    "m.is_prime(3)\n",
    "m.say_hi('mike', 'zoe')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 模块中不一定只有函数"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "一个模块文件中，不一定只包含函数；它也可以包含函数之外的可执行代码。只不过，在 `import` 语句执行的时候，模块中的非函数部分的可执行代码，只执行一次。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "有一个 Python 的彩蛋，恰好是可以用在此处的最佳例子 —— 这个模块是 `this`，它的文件名是 [`this.py`](https://github.com/python/cpython/blob/master/Lib/this.py)："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The Zen of Python, by Tim Peters\n",
      "\n",
      "Beautiful is better than ugly.\n",
      "Explicit is better than implicit.\n",
      "Simple is better than complex.\n",
      "Complex is better than complicated.\n",
      "Flat is better than nested.\n",
      "Sparse is better than dense.\n",
      "Readability counts.\n",
      "Special cases aren't special enough to break the rules.\n",
      "Although practicality beats purity.\n",
      "Errors should never pass silently.\n",
      "Unless explicitly silenced.\n",
      "In the face of ambiguity, refuse the temptation to guess.\n",
      "There should be one-- and preferably only one --obvious way to do it.\n",
      "Although that way may not be obvious at first unless you're Dutch.\n",
      "Now is better than never.\n",
      "Although never is often better than *right* now.\n",
      "If the implementation is hard to explain, it's a bad idea.\n",
      "If the implementation is easy to explain, it may be a good idea.\n",
      "Namespaces are one honking great idea -- let's do more of those!\n"
     ]
    }
   ],
   "source": [
    "import this"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这个 `this` 模块中的代码如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s = \"\"\"Gur Mra bs Clguba, ol Gvz Crgref\n",
    "Ornhgvshy vf orggre guna htyl.\n",
    "Rkcyvpvg vf orggre guna vzcyvpvg.\n",
    "Fvzcyr vf orggre guna pbzcyrk.\n",
    "Pbzcyrk vf orggre guna pbzcyvpngrq.\n",
    "Syng vf orggre guna arfgrq.\n",
    "Fcnefr vf orggre guna qrafr.\n",
    "Ernqnovyvgl pbhagf.\n",
    "Fcrpvny pnfrf nera'g fcrpvny rabhtu gb oernx gur ehyrf.\n",
    "Nygubhtu cenpgvpnyvgl orngf chevgl.\n",
    "Reebef fubhyq arire cnff fvyragyl.\n",
    "Hayrff rkcyvpvgyl fvyraprq.\n",
    "Va gur snpr bs nzovthvgl, ershfr gur grzcgngvba gb thrff.\n",
    "Gurer fubhyq or bar-- naq cersrenoyl bayl bar --boivbhf jnl gb qb vg.\n",
    "Nygubhtu gung jnl znl abg or boivbhf ng svefg hayrff lbh'er Qhgpu.\n",
    "Abj vf orggre guna arire.\n",
    "Nygubhtu arire vf bsgra orggre guna *evtug* abj.\n",
    "Vs gur vzcyrzragngvba vf uneq gb rkcynva, vg'f n onq vqrn.\n",
    "Vs gur vzcyrzragngvba vf rnfl gb rkcynva, vg znl or n tbbq vqrn.\n",
    "Anzrfcnprf ner bar ubaxvat terng vqrn -- yrg'f qb zber bs gubfr!\"\"\"\n",
    "\n",
    "d = {}\n",
    "for c in (65, 97):\n",
    "    for i in range(26):\n",
    "        d[chr(i+c)] = chr((i+13) % 26 + c)\n",
    "\n",
    "print(\"\".join([d.get(c, c) for c in s]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这个 `this.py` 文件中也没有什么函数，但这个文件里所定义的变量，我们都可以在 `import this` 之后触达："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The Zen of Python, by Tim Peters\n",
      "\n",
      "Beautiful is better than ugly.\n",
      "Explicit is better than implicit.\n",
      "Simple is better than complex.\n",
      "Complex is better than complicated.\n",
      "Flat is better than nested.\n",
      "Sparse is better than dense.\n",
      "Readability counts.\n",
      "Special cases aren't special enough to break the rules.\n",
      "Although practicality beats purity.\n",
      "Errors should never pass silently.\n",
      "Unless explicitly silenced.\n",
      "In the face of ambiguity, refuse the temptation to guess.\n",
      "There should be one-- and preferably only one --obvious way to do it.\n",
      "Although that way may not be obvious at first unless you're Dutch.\n",
      "Now is better than never.\n",
      "Although never is often better than *right* now.\n",
      "If the implementation is hard to explain, it's a bad idea.\n",
      "If the implementation is easy to explain, it may be a good idea.\n",
      "Namespaces are one honking great idea -- let's do more of those!\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "\"Gur Mra bs Clguba, ol Gvz Crgref\\n\\nOrnhgvshy vf orggre guna htyl.\\nRkcyvpvg vf orggre guna vzcyvpvg.\\nFvzcyr vf orggre guna pbzcyrk.\\nPbzcyrk vf orggre guna pbzcyvpngrq.\\nSyng vf orggre guna arfgrq.\\nFcnefr vf orggre guna qrafr.\\nErnqnovyvgl pbhagf.\\nFcrpvny pnfrf nera'g fcrpvny rabhtu gb oernx gur ehyrf.\\nNygubhtu cenpgvpnyvgl orngf chevgl.\\nReebef fubhyq arire cnff fvyragyl.\\nHayrff rkcyvpvgyl fvyraprq.\\nVa gur snpr bs nzovthvgl, ershfr gur grzcgngvba gb thrff.\\nGurer fubhyq or bar-- naq cersrenoyl bayl bar --boivbhf jnl gb qb vg.\\nNygubhtu gung jnl znl abg or boivbhf ng svefg hayrff lbh'er Qhgpu.\\nAbj vf orggre guna arire.\\nNygubhtu arire vf bsgra orggre guna *evtug* abj.\\nVs gur vzcyrzragngvba vf uneq gb rkcynva, vg'f n onq vqrn.\\nVs gur vzcyrzragngvba vf rnfl gb rkcynva, vg znl or n tbbq vqrn.\\nAnzrfcnprf ner bar ubaxvat terng vqrn -- yrg'f qb zber bs gubfr!\""
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.interactiveshell import InteractiveShell\n",
    "InteractiveShell.ast_node_interactivity = \"all\"\n",
    "\n",
    "import this\n",
    "this.d\n",
    "this.s"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "试试吧，试试能否独立读懂这个文件里的代码 —— 对初学者来说，还是挺练脑子的呢！\n",
    "\n",
    "它先是通过一个规则生成了一个密码表，保存在 `d` 这个字典中；而后，将 `s` 这个变量中保存的 “密文” 翻译成了英文……\n",
    "\n",
    "或许，你可以试试，看看怎样能写个函数出来，给你一段英文，你可以把它加密成跟它一样的 “密文”？"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## dir() 函数"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "你的函数，保存在模块里之后，这个函数的用户（当然也包括你），可以用 `dir()` 函数查看模块中可触达的变量名称和函数名称："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['__builtins__',\n",
       " '__cached__',\n",
       " '__doc__',\n",
       " '__file__',\n",
       " '__loader__',\n",
       " '__name__',\n",
       " '__package__',\n",
       " '__spec__',\n",
       " 'is_prime',\n",
       " 'say_hi']"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import mycode\n",
    "dir(mycode)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"./Part.2.D.7-tdd.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"
  },
  "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
 }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}