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

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

正文

http://www.bottlepy.org/docs/dev/是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

<code># 獲取客戶端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)/<code>

那麼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方法中的parseqsl函數可以接受形如/forum?id=1&page=5原始查詢字符串然後以[(key1, value1), (ke2, value2), ...]的list返回。

<code>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/<code>

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

<code># 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/<code>

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

<code># 獲取id
request.query().id
# 獲取page
request.query().page/<code>

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

<code># 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']/<code>

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

<code>>>> AttributeError: can't set attribute/<code>

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

<code>>>> AttributeError: Read-only property/<code>

這樣明確的錯誤信息。所以第三版的代碼可以這樣寫

<code># 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)/<code>

第三版的代碼沒有使用property裝飾器，而是使用了描述符這個技巧。如果你之前沒有見到過描述符，在這裡限於篇幅只能做個簡單的介紹，但描述符涉及知識點眾多，如果有不清楚之處可以看看《流暢的Python》第20章屬性描述符，裡面有非常詳細的介紹。

簡單來說，描述符是對多個屬性運用相同存取邏輯的一種方式，如Bottle框架裡我們需要對很多屬性都進行判斷某個鍵是否在environ中，如果在則返回，如果不在，需要解析一次這樣的存取邏輯。而描述符需要實現特定協議，包括set,get, delete方法，分別對應設置，讀取和刪除屬性的方法。他麼的參數也比較特殊，如get方法的三個參數self, obj, cls分別對應描述符實例的引用，對第三版的代碼來說就是Descriptor('environ', 'bottle.get.query', query, readonly=True)創建的實例的引用；obj則對應將某個屬性託管給描述的實例對象的引用，對應的應該為request對象；而cls則為Request類的引用。在調用request.query時編譯器會自動傳入這些參數。如果以Request.query的方式調用，那麼obj參數的傳入值為None，這時候通常的處理是返回描述符實例。

在Descriptor中get方法的代碼最多，也比較難理解，但如果記住其參數的意義也沒那麼難。下面以query的實現為例，我添加一些註釋來幫助理解

<code>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]/<code>

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

<code>query = Descriptor('envrion', 'bottle.get.query', query, read_only=True)/<code>

怎麼去掉這個這個“小尾巴“呢？回顧之前的代碼幾乎都是對query之類的方法進行修飾，所以可以嘗試使用裝飾器，畢竟裝飾器就是對某個函數進行修飾的，而且我們應該使用參數化的裝飾器，這樣才能將envrion等參數傳遞給裝飾器。如果要實現參數化裝飾器就需要一個裝飾器工廠函數，也就是說裝飾器的代碼裡需要嵌套至少3個函數體，寫起來有寫繞，代碼可閱讀性也有差。更大的問題來自如何將描述符與裝飾器結合起來，因為Descriptor是一個類而不是方法。

解決辦法其實挺簡單的。如果知道Python中函數也是對象，實現了call方法的對象可以表現得像函數一樣。所以我們可以修改Descirptor的代碼，實現call方法，讓它的實例成為callable對象就可以把它用作裝飾器；而要傳入的參數可以以實例屬性存儲起來，通過self.attribute的形式訪問，而不是像使用工廠函數實現參數化裝飾器時通過閉包來實現參數的訪問獲取。這時候再來看看Bottle裡的DictProperty代碼

<code>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]/<code>

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

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

拆開會更好理解點：

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

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

<code>def query(self):
    """ some codes """

property = DictProperty('environ', 'bottle.get.query', read_only=True)
query = property(query) # @實現的語法糖/<code>

再修改以下代碼形式：

<code>def query(self):
    """ some codes """

query = DictProperty('environ', 'bottle.get.query', read_only=True)(query)/<code>

是不是和第三版的實現方式：

<code>def query(self):
    """ some codes """

query = Descriptor('environ', 'bottle.get.query', query, read_only=True)/<code>

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

寫在後面

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

閱讀更多 PrivateRookie 的文章

關鍵字: Python 讀書 器類