11-iface-abc.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 接口：从协议到抽象基类\n",
    "\n",
    "> 抽象类表示接口。  \n",
    "> ——Bjarne Stroustrup, C++ 之父\n",
    "\n",
    "本章讨论的话题是接口：\n",
    "\n",
    "从**鸭子类型**的代表特征动态协议，到使接口更明确、能验证实现是否符合规定的抽象基类（Abstract Base Class, ABC）。\n",
    "\n",
    "> 接口的定义：对象公开方法的子集，让对象在系统中扮演特定的角色。  \n",
    "> 协议是接口，但不是正式的（只由文档和约定定义），因此协议不能像正式接口那样施加限制。  \n",
    "> 允许一个类上只实现部分接口。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 接口与协议\n",
    "\n",
    "- 什么是接口\n",
    "    \n",
    "    对象公开方法的子集，让对象在系统中扮演特定的角色。\n",
    "    \n",
    "- 鸭子类型与动态协议\n",
    "\n",
    "- 受保护的类型与私有类型不能在接口中\n",
    "\n",
    "- 可以把公开的数据属性放在接口中"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 案例：通过实现 __getitem__ 方法支持序列操作 "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Foo:\n",
    "    def __getitem__(self, pos):\n",
    "        return range(0, 30, 10)[pos]\n",
    "    \n",
    "f = Foo()\n",
    "print(f[1])\n",
    "\n",
    "for i in f:\n",
    "    print(i)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Foo 实现了序列协议的 `__getitem__` 方法。因此可支持下标操作。\n",
    "\n",
    "Foo 实例是可迭代的对象，因此可以使用 in 操作符"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 案例：在运行时实现协议——猴子补丁\n",
    "\n",
    "FrenchDeck 类见前面章节。\n",
    "\n",
    "FrenchDeck 实例的行为像序列，那么其实可以用 random 的 `shuffle` 方法来代替在类中实现的方法。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from random import shuffle\n",
    "from frenchdeck import FrenchDeck\n",
    "\n",
    "deck = FrenchDeck()\n",
    "shuffle(deck)\n",
    "# TypeError: 'FrenchDeck' object does not support item assigment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "FrenchDeck 对象不支持元素赋值。这是因为它只实现了不可变的序列协议，可变的序列还必须提供 `__setitem__` 方法。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def set_card(deck, pos, card):\n",
    "    deck._cards[pos] = card\n",
    "    \n",
    "FrenchDeck.__setitem__ = set_card\n",
    "shuffle(deck)\n",
    "print(deck[:5])\n",
    "print(deck[:5])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这种技术叫做猴子补丁：在运行是修改类或程序，而不改动源码。缺陷是补丁代码与要打补丁的程序耦合紧密。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 抽象基类（abc）\n",
    "\n",
    "- 为什么要有抽象基类？\n",
    "\n",
    "    不同类型的对象恰好有某种相似性，比如都有某种相似的方法。然而他们在继承层次上并没有太大联系。\n",
    "    \n",
    "- 抽象基类的本质就是几个特殊的方法。 \n",
    "\n",
    "- 可以使用抽象基类来检测某个类是否实现了某种协议，而这个类并不需要继承自这个抽象类。  \n",
    "[`collections.abc`](https://docs.python.org/3/library/collections.abc.html) 和 [`numbers`(https://docs.python.org/3/library/numbers.html) 模块中提供了许多常用的抽象基类以用于这种检测。\n",
    "\n",
    "    有了这个功能，我们在自己实现函数时，就不需要非常关心外面传进来的参数的**具体类型**（`isinstance(param, list)`），只需要关注这个参数是否支持我们**需要的协议**（`isinstance(param, abc.Sequence`）以保障正常使用就可以了。\n",
    "\n",
    "注意：从 Python 简洁性考虑，最好不要自己创建新的抽象基类，而应尽量考虑使用现有的抽象基类。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 抽象基类\n",
    "from collections import abc\n",
    "\n",
    "\n",
    "class A:\n",
    "    pass\n",
    "\n",
    "class B:\n",
    "    def __len__(self):\n",
    "        return 0\n",
    "\n",
    "assert not isinstance(A(), abc.Sized)\n",
    "assert isinstance(B(), abc.Sized)\n",
    "assert abc.Sequence not in list.__bases__    # list 并不是 Sequence 的子类\n",
    "assert isinstance([], abc.Sequence)          # 但是 list 实例支持序列协议"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 在抽象基类上进行自己的实现\n",
    "from collections import abc\n",
    "\n",
    "class FailedSized(abc.Sized):\n",
    "    pass\n",
    "\n",
    "\n",
    "class NormalSized(abc.Sized):\n",
    "    def __len__(self):\n",
    "        return 0\n",
    "\n",
    "\n",
    "n = NormalSized()\n",
    "print(len(n))\n",
    "f = FailedSized()       # 基类的抽象协议未实现，Python 会阻止对象实例化"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "有一点需要注意：抽象基类上的方法并不都是抽象方法。  \n",
    "换句话说，想继承自抽象基类，只需要实现它上面**所有的抽象方法**即可，有些方法的实现是可选的。  \n",
    "比如 [`Sequence.__contains__`](https://github.com/python/cpython/blob/3.7/Lib/_collections_abc.py#L889)，Python 对此有自己的实现（使用 `__iter__` 遍历自身，查找是否有相等的元素）。但如果你在 `Sequence` 之上实现的序列是有序的，则可以使用二分查找来覆盖 `__contains__` 方法，从而提高查找效率。\n",
    "\n",
    "我们可以使用 `__abstractmethods__` 属性来查看某个抽象基类上的抽象方法。这个抽象基类的子类必须实现这些方法，才可以被正常实例化。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 自己定义一个抽象基类\n",
    "import abc\n",
    "\n",
    "# 使用元类的定义方式是 class SomeABC(metaclass=abc.ABCMeta)\n",
    "class SomeABC(abc.ABC):\n",
    "    @abc.abstractmethod\n",
    "    def some_method(self):\n",
    "        raise NotImplementedError\n",
    "\n",
    "        \n",
    "class IllegalClass(SomeABC):\n",
    "    pass\n",
    "\n",
    "class LegalClass(SomeABC):\n",
    "    def some_method(self):\n",
    "        print('Legal class OK')\n",
    "\n",
    "    \n",
    "l = LegalClass()\n",
    "l.some_method()\n",
    "il = IllegalClass()    # Raises"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 虚拟子类\n",
    " - 使用 [`register`](https://docs.python.org/3/library/abc.html#abc.ABCMeta.register) 接口可以将某个类注册为某个 ABC 的“虚拟子类”。支持 `register` 直接调用注册，以及使用 `@register` 装饰器方式注册（其实这俩是一回事）。\n",
    " \n",
    "- 注册后，使用 `isinstance` 以及实例化时，解释器将不会对虚拟子类做任何方法检查。  \n",
    "\n",
    "注意：虚拟子类不是子类，所以虚拟子类不会继承抽象基类的任何方法。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Subclass: <class '__main__.IllegalClass'>\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Traceback (most recent call last):\n",
      "  File \"<ipython-input-2-29894e8d34a0>\", line 31, in <module>\n",
      "    il.some_method()                          # 虚拟子类不是子类，不会从抽象基类上继承任何方法\n",
      "AttributeError: 'IllegalClass' object has no attribute 'some_method'\n",
      "Traceback (most recent call last):\n",
      "  File \"<ipython-input-2-29894e8d34a0>\", line 36, in <module>\n",
      "    il.another_method()\n",
      "AttributeError: 'IllegalClass' object has no attribute 'another_method'\n"
     ]
    }
   ],
   "source": [
    "# 虚拟子类\n",
    "import abc\n",
    "import traceback\n",
    "\n",
    "class SomeABC(abc.ABC):\n",
    "    @abc.abstractmethod\n",
    "    def some_method(self):\n",
    "        raise NotImplementedError\n",
    "    \n",
    "    def another_method(self):\n",
    "        print('Another')\n",
    "    \n",
    "    @classmethod\n",
    "    def __subclasshook__(cls, subcls):\n",
    "        \"\"\"\n",
    "        在 register 或者进行 isinstance 判断时进行子类检测\n",
    "        https://docs.python.org/3/library/abc.html#abc.ABCMeta.__subclasshook__\n",
    "        \"\"\"\n",
    "        print('Subclass:', subcls)\n",
    "        return True\n",
    "\n",
    "\n",
    "class IllegalClass:\n",
    "    pass\n",
    "\n",
    "SomeABC.register(IllegalClass)                # 注册\n",
    "il = IllegalClass()\n",
    "assert isinstance(il, IllegalClass)\n",
    "assert SomeABC not in IllegalClass.__mro__    # isinstance 会返回 True，但 IllegalClass 并不是 SomeABC 的子类\n",
    "try:\n",
    "    il.some_method()                          # 虚拟子类不是子类，不会从抽象基类上继承任何方法\n",
    "except Exception as e:\n",
    "    traceback.print_exc()\n",
    "\n",
    "try:\n",
    "    il.another_method()\n",
    "except Exception as e:\n",
    "    traceback.print_exc()\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}