Bottle框架中的裝飾器類和描述符應用

最近在閱讀Python微型Web框架Bottle的源碼，發現了Bottle中有一個既是裝飾器類又是描述符的有趣實現。恰好這兩個點是Python比較的難理解，又混合在一塊兒，讓代碼有些晦澀難懂。但理解代碼以後不禁得爲Python語言的簡潔優美讚歎。因此把相關知識和想法稍微整理，以供分享。

正文

Bottle是Python的一個微型Web框架，全部代碼都在一個bottle.py文件中，只依賴標準庫實現，兼容Python 2和Python 3，並且最新的穩定版0.12代碼也只有3700行左右。雖然小，但它實現了Web框架基本功能。這裏就不以過多的筆墨去展現Bottle框架，須要的請訪問其網站了解更多。這裏着重介紹與本文相關的重要對象request。在Bottle裏，request對象表明了當前線程處理的請求，客戶端發送的請求數據如表單數據，請求網站和cookie均可以從request對象中得到。下面是官方文檔中的兩個例子
from bottle import request, route, response, template

# 獲取客戶端cookie以實現登錄時問候用戶功能
@route('/hello')
def hello():
    name = request.cookie.username or 'Guest'
    return template('Hello {{name}}', name=name)

# 獲取形如/forum?id=1&page=5的查詢字符串中id和page變量的值
route('/forum')
def display_forum():
    forum_id = request.query.id
    page = request.query.page or '1'
    return template('Forum ID: {{id}} (page {{page}})', id=forum_id, page=page)

那麼Bottle是如何實現的呢？根據WSGI接口規定，全部的HTTP請求信息都包含在一個名爲envrion的dict對象中。因此Bottle要作的就是把HTTP請求信息從environ解析出來。在深刻Request類如何實現以前先要了解下Bottle的FormsDict。FormsDict與字典類類似，但擴展了一些功能，好比支持屬性訪問、一對多的鍵值對、WTForms支持等。它在Bottle中被普遍應用，如上面的示例中cookie和query數據都以FormsDict存儲，因此咱們能夠用request.query.page的方式獲取相應屬性值。
下面是0.12版Bottle中Request類的部分代碼，0.12版中Request類繼承了BaseRequest，爲了方便閱讀我把代碼合併在一塊兒，同時還有重要的DictProperty的代碼。須要說明的是Request類__init__傳入的environ參數就是WSGI協議中包含HTTP請求信息的envrion，而query方法中的_parse_qsl函數能夠接受形如/forum?id=1&page=5原始查詢字符串而後以[(key1, value1), (ke2, value2), ...]的list返回。

class DictProperty(object):
    """ Property that maps to a key in a local dict-like attribute. """

    def __init__(self, attr, key=None, read_only=False):
        self.attr, self.key, self.read_only = attr, key, read_only

    def __call__(self, func):
        functools.update_wrapper(self, func, updated=[])
        self.getter, self.key = func, self.key or func.__name__
        return self

    def __get__(self, obj, cls):
        if obj is None: return self
        key, storage = self.key, getattr(obj, self.attr)
        if key not in storage: storage[key] = self.getter(obj)
        return storage[key]

    def __set__(self, obj, value):
        if self.read_only: raise AttributeError("Read-Only property.")
        getattr(obj, self.attr)[self.key] = value

    def __delete__(self, obj):
        if self.read_only: raise AttributeError("Read-Only property.")
        del getattr(obj, self.attr)[self.key]

class Request:
    def __init__(self, environ=None):
        self.environ {} if environ is None else envrion
        self.envrion['bottle.request'] = self
    
    @DictProperty('environ', 'bottle.request.query', read_only=True)
    def query(self):
        get = self.environ['bottle.get'] = FormsDict()
        pairs = _parse_qsl(self.environ.get('QUERY_STRING', ''))
        for key, value in pairs:
            get[key] = value
        return get

query方法的邏輯和代碼都比較簡單，就是從environ中獲取'QUERY_STRING'，並用把原始查詢字符串解析爲一個FormsDict，將這個FormsDict賦值給environ['bottle.request.query']並返回。但這個函數的裝飾器的做用就有些難以理解，裝飾器的實現方式都是"dunder"特殊方法，有些晦澀難懂。若是上來就看這些源碼可能難以理解代碼實現的功能。那不如這些放一邊，假設本身要實現這些方法，你會寫出什麼代碼。
一開始你可能寫出這樣的代碼。

# version 1
class Request:
    """
    some codes here
    """
    def query(self):
        get = self.environ['bottle.get'] = FormsDict()
        pairs = _parse_qsl(self.environ.get('QUERY_STRING', ''))
        for key, value in pairs:
            get[key] = value
        return get

這樣確實實現瞭解析查詢字符串的功能，但每次在調用這個方法時都須要對原始查詢字符串解析一次，實際上在處理某特請求時，查詢字符串是不會改變的，因此咱們只須要解析一次並把它保存起來，下次使用時直接返回就行了。另外此時的query方法仍是一個普通方法，必須使用這樣的方法來調用它

# 獲取id
request.query().id
# 獲取page
request.query().page

query後面的小括號讓語句顯得不那麼協調，其實就是我以爲它醜。要是也能和官方文檔中的示例實現以屬性訪問的方式獲取相應的數據就行了。因此代碼還得改改。

# query method version 2
class Request:
    """
    some codes here
    """
    @property
    def query(self):
        if 'bootle.get.query' not in self.environ:
            get = self.environ['bottle.get'] = FormsDict()
            pairs = _parse_qsl(self.environ.get('QUERY_STRING', ''))
            for key, value in pairs:
                get[key] = value
        return self.environ['bottle.get.query']

第二版改變的代碼就兩處，一個是使用property裝飾器，實現了request.query的訪問方式；另外一個就是在query函數體中增長了判斷'bottle.get.query'是否在environ中的判斷語句，實現了只解析一次的要求。第二版幾乎知足了全部要求，它表現得就像Bottle中真正的query方法同樣。但它仍是有些缺陷。
首先，Request類並不僅有query一個方法，若是要編寫完整的Request類就會發現，有不少方法的代碼與query類似，都是從environ中解析出須要的數據，並且都只須要解析一次，保存起來，第二次或之後訪問時返回保存的數據就行了。因此能夠考慮將屬性管理的代碼從方法體內抽象出來，正好Python中的描述符能夠實現這樣的功能。另外若是使用Bottle的開發者在寫代碼時不當心嘗試進行request.query = some_data的賦值時，將會拋出以下錯誤。

>>> AttributeError: can't set attribute

咱們確實但願屬性是隻讀的，在對其賦值時應該拋出錯誤，但這樣的報錯信息並無提供太多有用的信息，致使調bug時一頭霧水，找不到方向。咱們更但願拋出如

>>> AttributeError: Read-only property

這樣明確的錯誤信息。
因此第三版的代碼能夠這樣寫

# query method version 3
class Descriptor:
    def __init__(self, attr, key, getter, read_only=False):
        self.attr = attr
        self.key = key
        self.getter = getter
        self.read_only = read_only
    
    def __set__(self, obj, value):
        if self.read_only:
                raise AttributeError('Read only property.')
        getattr(obj, self.attr)[self.key] = value
    
    def __get__(self, obj, cls):
        if obj is None:
            return self
        key, storage = self.key, getattr(obj, self.attr)
        if key not in storage:
            storage[key] = self.getter(obj)
        return storage[key]
    
    def __delete__(self, obj):
        if self.read_only:
            raise AttributeError('Read only property.')
        del getattr(obj, self.attr)[self.key]

class Reqeust:
    """
    some codes
    """
    def query(self):
        get = self.environ['bottle.get'] = FormsDict()
        pairs = _parse_qsl(self.environ.get('QUERY_STRING', ''))
        for key, value in pairs:
            get[key] = value
        return get  
    query = Descriptor('environ', 'bottle.get.query', query, read_only=True)

第三版的代碼沒有使用property裝飾器，而是使用了描述符這個技巧。若是你以前沒有見到過描述符，在這裏限於篇幅只能作個簡單的介紹，但描述符涉及知識點衆多，若是有不清楚之處能夠看看《流暢的Python》第20章屬性描述符，裏面有很是詳細的介紹。
簡單來講，描述符是對多個屬性運用相同存取邏輯的一種方式，如Bottle框架裏咱們須要對不少屬性都進行判斷某個鍵是否在environ中，若是在則返回，若是不在，須要解析一次這樣的存取邏輯。而描述符須要實現特定協議，包括__set__, __get__, __delete___方法，分別對應設置，讀取和刪除屬性的方法。他麼的參數也比較特殊，如__get__方法的三個參數self, obj, cls分別對應描述符實例的引用，對第三版的代碼來講就是Descriptor('environ', 'bottle.get.query', query, read_only=True)建立的實例的引用；obj則對應將某個屬性託管給描述的實例對象的引用，對應的應該爲request對象；而cls則爲Request類的引用。在調用request.query時編譯器會自動傳入這些參數。若是以Request.query的方式調用，那麼obj參數的傳入值爲None，這時候一般的處理是返回描述符實例。
在Descriptor中__get__方法的代碼最多，也比較難理解，但若是記住其參數的意義也沒那麼難。下面以query的實現爲例，我添加一些註釋來幫助理解

key, storage = self.key, getattr(obj, self.attr)
# key='bottle.get.query'
# storage = environ 即包含HTTP請求的信息的environ

# 判斷envrion中是否包含key來決定是否須要解析
if key not in storage:
    storage[key] = self.getter(obj)
    # self.getter(obj)就是調用了原來的query方法，不過要傳入一個Request實例，也就是obj
return storage[key]

而__set__, __delete__代碼比較簡單，在這裏咱們把只讀屬性在賦值和刪除時拋出的錯誤定製爲AttributeError('Read only property.')，方便調試。
經過使用描述符這個有些難懂的方法，咱們能夠在Request的方法中專心於編寫如何解析的代碼，不用擔憂屬性的存取邏輯。和在每一個方法中都使用if判斷相比高到不知道哪裏去。但美中不足的是，這樣讓咱們的方法代碼後面拖着一個「小尾巴」，即

query = Descriptor('envrion', 'bottle.get.query', query, read_only=True)

怎麼去掉這個這個「小尾巴「呢？回顧以前的代碼幾乎都是對query之類的方法進行修飾，因此能夠嘗試使用裝飾器，畢竟裝飾器就是對某個函數進行修飾的，並且咱們應該使用參數化的裝飾器，這樣才能將envrion等參數傳遞給裝飾器。若是要實現參數化裝飾器就須要一個裝飾器工廠函數，也就是說裝飾器的代碼裏須要嵌套至少3個函數體，寫起來有寫繞，代碼可閱讀性也有差。更大的問題來自如何將描述符與裝飾器結合起來，由於Descriptor是一個類而不是方法。
解決辦法其實挺簡單的。若是知道Python中函數也是對象，實現了__call__方法的對象能夠表現得像函數同樣。因此咱們能夠修改Descirptor的代碼，實現__call__方法，讓它的實例成爲callable對象就能夠把它用做裝飾器；而要傳入的參數能夠以實例屬性存儲起來，經過self.attribute的形式訪問，而不是像使用工廠函數實現參數化裝飾器時經過閉包來實現參數的訪問獲取。這時候再來看看Bottle裏的DictProperty代碼

class DictProperty(object):
    """ Property that maps to a key in a local dict-like attribute. """

    def __init__(self, attr, key=None, read_only=False):
        self.attr, self.key, self.read_only = attr, key, read_only

    def __call__(self, func):
        functools.update_wrapper(self, func, updated=[])
        self.getter, self.key = func, self.key or func.__name__
        return self

    def __get__(self, obj, cls):
        if obj is None: return self
        key, storage = self.key, getattr(obj, self.attr)
        if key not in storage: storage[key] = self.getter(obj)
        return storage[key]

    def __set__(self, obj, value):
        if self.read_only: raise AttributeError("Read-Only property.")
        getattr(obj, self.attr)[self.key] = value

    def __delete__(self, obj):
        if self.read_only: raise AttributeError("Read-Only property.")
        del getattr(obj, self.attr)[self.key]

其實就是一個有描述符做用的裝飾器類，它的使用方法很簡單：

@DictProperty('environ', 'bottle.get.query', read_only=True)
def query(self):
    """ some codes """

拆開會更好理解點：

property = DictProperty('environ', 'bottle.get.query', read_only=True)
@property
def query(self):
    """ some codes """

再把@實現的語法糖拆開：

def query(self):
    """ some codes """

property = DictProperty('environ', 'bottle.get.query', read_only=True)
query = property(query) # @實現的語法糖
再修改如下代碼形式：

def query(self):
    """ some codes """

query = DictProperty('environ', 'bottle.get.query', read_only=True)(query)
是否是和第三版的實現方式很是類似。

def query(self):
    """ some codes """

query = Descriptor('environ', 'bottle.get.query', query, read_only=True)

但咱們可使用裝飾器把方法體後面那個不和諧的賦值語句」小尾巴「去掉，將屬性存取管理抽象出來，並且只須要使用一行很是簡便的裝飾器把這個功能添加到某個方法上。這也許就是Python的美之一吧。

---

寫在後面

DictProperty涉及知識遠不止文中涉及的那麼簡單，若是你仍是不清楚DictProperty的實現功能，建議閱讀《流暢的Python》第7章和第22章，對裝飾器和描述符有詳細的描述，另外《Python Cookbook》第三版第9章元編程有關於參數化裝飾器和裝飾器類的敘述和示例。若是你對Bottle爲何要實現這樣的功能感到困惑，建議閱讀Bottle的文檔和WSGI相關的文章。其實前一陣再閱讀Bottle源碼時就想寫一篇文章，但奈何許久不寫東西文筆生疏加上醫院實習期間又比較忙，一直推到如今才終於磕磕絆絆地把我閱讀的Bottle源碼的一些感悟寫出來，但願對喜歡Python的各位有些幫助把。