【Python笔记】装饰器语法糖（@staticmethod/@classmethod/@property）原理剖析及使用场景说明

在阅读一些开源Python库的源码时，经常会看到在某个类的成员函数前，有类似于@staticmethod或@classmethod或@property的语法糖。本质上，它们都是函数装饰器，只不过通常被用来修饰类成员函数而已。

本笔记旨在说明这些语法糖的用途，关于普通函数装饰器语法的解释，可以参考这篇笔记。

在解释这些装饰器函数前，先来分析下普通成员函数。

1. 类的普通成员函数
对于Python的类，其普通类成员函数的第一个参数默认为当前的类实例，通常的定义形式示例：

class C:
   def __init__(self):  ## NOTICE: 不传入参数时创建实例会报错；"self"只是约定俗成的参数名而已，非语法的硬性规定
       pass

我们可以通过print C.__init__查看函数__init__()：

>>> class C():
...     def __init__(self):
...         pass
... 
>>> print C.__init__
<unbound method C.__init__>  ## __init__()是类C的unbound method，即它此时未bound到任何类实例上
>>> c = C()
>>> print c.__init__
<bound method C.__init__ of <__main__.C instance at 0x7fb4346d38c0>>  ## 当类实例创建后，__init__()变成实例的bound method
>>> print C.__init__.__get__ 
<method-wrapper '__get__' of instancemethod object at 0x7fb434772c80> ## 类成员函数默认实现了__get__()方法

总之，对于类的普通成员函数来说，在创建类的具体实例前，它们是unbound method，通过类名调用时（如 C.fn()），会报错；类实例创建 后，它们都是实例的bound method，只能通过实例来调用(inst = C(); inst.fn())。
关于unbound method函数调用报错的原因，与Python底层实现时对函数名的查找规则有关。从上面示例代码可看到，__init__()函数默 认实现了__get__()方法，而根据Python底层规则，当某个对象（Python中万物皆对象）实现了_get__()/__set__()/__delete__()这3个 method中任何一个时，它就成了一个支持descriptor protocal的descriptor。当调用c.__init__时（当然，这个是Python解释器帮我们调 用的，但这并不改变__init__实际上是个普通类函数的事实），根据descriptor invoking规则，其将被转化为type(c).__dict__ ['__init__'].__get__(c, type(c))的形式，可见，实际上发生的调用类似于C.__init__(c)，即类C的实例c会被当作第1个参数传给普通类 成员函数。所以，在定义类普通成员函数时，至少需要有self参数，且类的普通成员函数必须通过类实例来调用，而不能通过类名直接调用。
关于上面提到的Descriptor Protocol及其对obj attribute查找规则的影响，强烈建议读懂这篇文档Descriptor HowTo Guide 。不夸张的说，理解Descriptor对我们理解Python代码的底层行为有巨大帮助。

2. @classmethod
根据Python文档的说明，classmethod(fn)表明函数fn是类的函数而非类实例的函数，在语法上，它要求fn的函数签名至少要有1个参数，函数被调用时，解释器会将类作为第1个参数传给fn。示例如下：

>>> class C():
...     def fn_classmethod(x):
...         print x
...     fn = classmethod(fn_classmethod)
... 
>>> C.fn
<bound method classobj.fn_classmethod of <class __main__.C at 0x7fb4346b6bb0>>
>>> C.fn()
__main__.C

可见，当调用classmethod()将fn_classmethod转换为class method后，我们可以直接通过C.fn来调用它，当然，通过C().fn()调用也可以。
更需要注意的是，在调用时C.fn()时，fn_classmethod()唯一参数x的实参确实是类C（即示例中print出来的__main__.C），该参数是解释器自动传入的。
在Python语法中，@classmethod是一种实现自动调用classsmethod(fn_classmethod)的语法糖，它实现的功能与上述示例代码一致，只是看起来更精简且更pythonic而已：

>>> class C():
...     @classmethod ## Python的decorator语法会保证classmethod(fn)的自动调用
...     def fn(x):
...         print x
... 
>>> C.fn
<bound method classobj.fn of <class __main__.C at 0x7fb4346b6808>>
>>> C.fn()
__main__.C

classmethod的典型使用场合：
1) 直接用类来调用函数，而不用借助类实例
2) 更优雅地实现某个类的实例的构造（类似于Factory Pattern）
通常情况下，类实例是解释器自动调用类的__init__()来构造的，但借助classmethod可以在解释器调用__init__前实现一些预处理逻辑，然后将预处理后的参数传入类的构造函数来创建类实例。如dict类型支持的fromkeys()方法就是用classmethod实现的，它用dict实例当前的keys构造出一个新的dict实例。在文档Descriptor HowTo Guide最后部分给出了它对应的Python pseudo-code，感兴趣的话可以去研究一下。
关于实现类实例构造的另一个典型case，可以参考StackOverflow上的这篇问答帖。帖中Best Answer作者给出了一个典型场景，这个场景用非classmethod的方法也可以实现类实例的构造，但借助classmethod语法，可以实现的更优雅（a. 与__init__构造实例相比，classmethod方法也保证了构造逻辑代码复用度而且实现的更精简，如解析date_as_string为(year, month, day)的代码也可以被复用；b. 它不用通过类的实例调用，直接用类来调用即可构造新的实例；c. 与定义实现相同功能的全局函数相比，更符合OOP思想；d. 基类被继承时，基类中定义的classmethod也会被继承到继承类中）。

3. @staticmethod
根据Python文档的说明，staticmethod(fn)表明函数fn是类的静态方法。具体到类定义体内某个函数的定义上，如果该函数想声明称静态成员，则只需在其定义体前加上"@staticmethod"这行，利用装饰器语法糖来实现staticmethod(cls.fun)的目的。示例如下：

class C(object):
    @staticmethod
    def f(arg1, arg2, ...):
        ...

与classmethod的装饰器语法糖类似，@staticmethod会自动调用staticmethod(f)。
Python中类静态方法的语义跟C++/Java类似，即类的静态成员属于类本身，不属于类的实例，它无法访问实例的属性（数据成员或成员函数）。定义为staticmethod的函数被调用时，解释器不会自动为其隐式传入类或类实例的参数，它的实际参数列表与调用时显式传入的参数列表保持一致。
staticmethod的典型应用场景：
若类的某个函数确认不会涉及到与类实例有关的操作时，可以考虑将该函数定义为类的staticmethod。比如，根据业务逻辑，可将全局函数封装到一个类中并声明为staticmethod，这样看起来更符合OOP思想，具体的例子可以参考 这篇Blog 。当然，这只是一种符合OOP的封装思路，并非意味着碰到全局函数就一定要这样做，需要看个人习惯或业务需求。
再次强调：定义为staticmethod类型的函数，其函数体中最好不要涉及与类实例有关的操作（包括创建类实例或访问实例的属性），因为一旦涉及到类实例就意味着这些实例名是硬编码的，在类被继承的场景下，调用这些staticmethod类型的函数会创建基类或访问基类属性，而这通常不是业务预期的行为。具体的case可以参考StackOverflow 这篇问答帖的第2个高票答案。

4. @property
根据Python文档的说明，property([fget[, fset[, fdel[, doc]]]])为new-style类创建并返回property对象，该对象是根据传入的参数（fget/fset/fdel）创建的，它可以决定外部调用者对new-style类的某些属性是否具有读/写/删除权限。以官网文档给出的demo为例：

class C(object): ## NOTICE: property只对new style classes有效
    def __init__(self):
        self._x = None

    def getx(self):
        return self._x

    def setx(self, value):
        self._x = value

    def delx(self):
        del self._x

    x = property(getx, setx, delx, "I'm the 'x' property.")

上述示例中，x是类C的property对象，由于创建时传入了3个函数对象，故通过访问该属性可以实现对self._x的读/写/删除操作。具体而言 ，调用C().x时，解释器最终会调用getx；调用C().x = value时，解释器后最终调用setx；调用del C().x时，解释器会最终调用delx。
由于property()的第1个参数是fget，利用这一点，可以很容易实现一个只有read-only权限的类属性：

>>> class C(object):
...     def __init__(self):
...         self._name = 'name'
...     @property
...     def get_name(self):
...         return self._name
...     
... 
>>> c = C()
>>> c.get_name
'name'
>>> c.get_name = 'new name'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: can't set attribute

当然，这里所说的"read-only"，只是指这个属性名不会被赋值操作重新绑定新对象而已。如果这个属性名初始绑定的是个可变对象（如list或dict），则即使通过@property装饰，其绑定的对象的内容也可以通过属性名来修改。
如果想通过类的实例对象来修改或删除类实例的属性，则需用下面的代码来实现：

>>> class C(object):
...     def __init__(self):
...         self._name = 'name'
...     @property
...     def name(self):
...         return self._name
...     @name.setter
...     def name(self, value):
...         self._name = value
...     @name.deleter
...     def name(self):
...         del self._name
... 
>>> c = C()
>>> c.name
'name'
>>> c.__dict__
{'_name': 'name'}
>>> c.name = 'new name'
>>> c.__dict__
{'_name': 'new name'}
>>> c.name
'new name'
>>> del c.name
>>> c.__dict__
{}

上述代码中，@property、@name.setter及@name.deleter均是装饰器语法糖，其中：@name.setter中的name指代的是经@property装饰后的对 象（即property(name)返回的名为name但类型为property object的对象），setter是这个名为name的property对象的built-in函数，其目的 是通过name.setter(name)为这个property对象提供修改其所属类的属性的功能。@name.deleter同理。
至于property对象支持的函数setter()和deleter()的来历，文档Descriptor HowTo Guide 在介绍property原理时给出了property类底层实现的Python伪码，值得精读。
从伪码还 可以看到，property类实现了__get__()、__set__()和__delete__()方法，这意味着property类是个遵循descriptor protocol的data  descriptor，根据文档Descriptor HowTo Guide关于Invoking Descriptors的说明， data descriptor会影响解释器对属性名的查找链，具体而言，当上面的代码中调用c.name时，解释器会将其转化成type(c).__dict__ ['name'].__get__(c, type(c))（备注：通过print type(c).__dict__可以验证，name确实存在于dict中），故这个转化后的调用链会调用到property 对象的__get__()方法，而根据property的实现伪码，在__get__()中最终会调用到类C对应的name()函数。
上面这段话所描述的流程正是property魔法背后的原理。
当然，要想真正理解还需要仔细研究property的python伪码逻辑。

@property除可以实现属性的只读权限功能外，还可以用在这种场景下：
类属性已经暴露给外部调用者，但由于业务需求，需要针对这个属性进行业务逻辑的修改（如增加边界判定或修改属性计算方法，等等），则此时引入property()或@property语法糖可以在修改逻辑的同时保证代码的后向兼容，外部调用者无需修改调用方式。具体的case可以参考这篇Blog中提到的场景。

【参考资料】
1. Python的几个高级语法概念浅析：lambda表达式 && 闭包 && 装饰器    
2. Descriptor HowTo Guide  
3. StackOverflow: Python @classmethod and @staticmethod for beginner? 
4. Python Docs: classmethod 
5. Python Docs: staticmethod 
6. The definitive guide on how to use static, class or abstract methods in Python  
7. Newfound love of @staticmethod in Python 
8. Objects and classes in Python: Decorators 
9. Python Docs: property() 
10. Python Property 

====================== EOF =====================