Decorating Classes¶

Examples of callable designators¶

Given the following class X:

>>> class X():
...     def fn(self): pass
...     def gn(self): pass
...     def hn(self): pass
...     @property
...     def pr(self): pass
...     @pr.setter
...     def pr(self, val): pass
...     @pr.deleter
...     def pr(self): pass
...
...     def pdg(self): pass
...     def pds(self, val): pass
...     pd = property(pdg, pds, None)
...     class I():
...         def i1(self): pass
...         def i2(self): pass

the following table shows several callable designators for X and what they designate. To reduce clutter, we’ve omitted initial X. from the literals in the righthand column:

Callable designator	designates these methods and/or properties
fn	fn
pr.getter	pr getter
pr.setter	pr setter
pr.deleter	pr deleter
pr	{pr getter, pr setter, pr deleter}
pr.?etter	{pr getter, pr setter}
p*	{pr getter, pr setter, pr deleter, pds, pdg}
?n	{fn, gn, hn}
[fg]n	{fn, gn}
[f-h]n	{fn, gn, hn}
pd	{pdg, pds}
pdg, pd.getter	pdg
pds, pd.setter	pds
pd.deleter	nothing (pd has no deleter)
no_such_*	nothing (there are no matches)
[f-i]*	{fn, gn, hn, I.i1, I.i2}
X.I.*, X.[!f-hp]*	{I.i1, I.i2}
X.[!f-ip]*	{I.i1, I.i2}, because [!f-ip] matches I
[!f-hp]*, ?[!n]*	every callable in classes X and X.I, because these match X. + anything
*	every callable in classes X and X.I

Warning

Be aware that:

1. wildcards can match the dot '.' in qualified names;
2. both qualified and unqualified method and property names are matched — e.g. for a method mymethod in a class C, each callable designator is checked for a match against both mymethod and C.mymethod.

As the second and third to last examples in the above table illustrate, these matching rules can lead to surprises, especially when using complements of character sets.

Precedence of inner decorators over outer decorators¶

By default, the explicitly given settings of a callable’s decorator take precedence over those of the decorator of its class:

>>> @log_calls(settings=MINIMAL)
... class E():
...     def f(self): pass
...     @log_calls(log_exit=True)
...     def g(self): pass
>>> E().f(); E().g()
E.f <== called by <module>
E.g <== called by <module>
E.g ==> returning to <module>

The same holds for inner classes: settings provided explicitly to the decorator of an inner class take precedence over the corresponding settings of the outer class. To give the outer settings priority, supply override=True to the outer decorator:

>>> @log_calls(settings=MINIMAL, override=True)
... class E():
...     def f(self): pass
...     @log_calls(log_exit=True)
...     def g(self): pass
>>> E().f(); E().g()
E.f <== called by <module>
E.g <== called by <module>

Decorating properties specified with the @property decorator¶

Python lets you define properties using decorators. You decorate the getter property prop with @property, and then any corresponding setter and deleter methods with @prop.setter and @prop.deleter respectively.

Using only to decorate just the getter:

>>> @log_calls(only='prop.getter', settings=MINIMAL)
... class A():
...     @property
...     def prop(self): pass
...     @prop.setter
...     def prop(self, val): pass
>>> A().prop; A().prop = 17
A.prop <== called by <module>

Using only with the property name — all property methods are decorated:

>>> @log_calls(only='prop', settings=MINIMAL)
... class A():
...     @property
...     def prop(self): pass
...     @prop.setter
...     def prop(self, val): pass
...     @prop.deleter
...     def prop(self): pass
>>> A().prop; A().prop = 17; del A().prop
A.prop <== called by <module>
A.prop <== called by <module>
A.prop <== called by <module>

>>> @log_calls(settings=MINIMAL)
... class A():
...     @property
...     def prop(self): pass
...
...     @prop.setter
...     @log_calls(name='A.%s.setter')
...     def prop(self, val): pass
...
...     @prop.deleter
...     @log_calls(name='A.%s.deleter')
...     def prop(self, val): pass
>>> A().f(); A().prop; A().prop = 17; del A().prop
A.prop <== called by <module>
A.prop.getter <== called by <module>
A.prop.deleter <== called by <module>

Decorating properties specified with the property function¶

Python also lets you define properties using property as a function. log_calls uses the unique names of the methods that comprise the property.

>>> @log_calls(omit='prop.setter', settings=MINIMAL)
... class XX():
...     def getxx(self):        pass
...     def setxx(self, val):   pass
...     def delxx(self):        pass
...     prop = property(getxx, setxx, delxx)
>>> xx = XX(); xx.prop; xx.prop = 5; del xx.prop
XX.getxx <== called by <module>
XX.delxx <== called by <module>

Further examples¶

For more examples of inner class decoration, consult the docstrings of the functions main__lc_class_deco__inner_classes() and main__lc_class_deco__omit_only__inner_classes() in tests/test_log_calls__class_deco.py.