Usage

A function decorator is a sort of runtime declaration about the function whose definition follows. The decorator is coded on a line just before the def statement that defines a function or method, and it consists of the @ symbol followed by a reference to a metafunction—a function (or other callable object) that manages another function. As of Python 3.9, the code after the @ can be any expression returning a metafunction, but it’s usually a simple name.

In terms of code, function decorators automatically map the following syntax:

@decorator              # Decorate function
def F(arg):
    …

F(99)                   # Call function

into this equivalent form, where decorator is a one-argument callable object that returns a callable object with the same number of arguments as F, if not F itself:

def F(arg):
    …
F = decorator(F)        # Rebind function name to decorator result

F(99)                   # Essentially calls decorator(F)(99)

This automatic name rebinding works on any def statement, whether it’s for a simple function or a method within a class. When the function F is later called, it’s actually calling the object returned by the decorator, which may be either another object that implements required wrapping logic or the original function itself.

In other words, decoration essentially maps the first of the following into the second—though the decorator is really run only once, at decoration time:

func(6, 7)
decorator(func)(6, 7)

This automatic name rebinding accounts for the static-method and property decoration syntax we met earlier in the book:

class C:
    @staticmethod
    def meth(…): …            # meth = staticmethod(meth)

class C:
    @property
    def name(self): …         # name = property(name)

In both cases, the method name is rebound to the result of a built-in function decorator at the end of the def statement. Calling the original name later invokes whatever object the decorator returns. In these specific cases, the original names are rebound to a static-method router and property descriptor, but the process is much more general than this—as the next section explains.

Implementation

A decorator itself is a callable that returns a callable. That is, it returns the object to be called later when the decorated function is invoked through its original name—either a wrapper object to intercept later calls or the original function augmented in some way. In fact, decorators can be any type of callable and return any type of callable: any combination of functions and classes may be used, though some are better suited to certain contexts.

For example, to tap into the decoration protocol in order to manage a function just after it is created, we might code a decorator of this form:

def decorator(F):
    # Process function F here
    return F

@decorator
def func(): …                 # func = decorator(func)

Because the original decorated function is assigned back to its name, this simply adds a post-creation step to function definition. Such a structure might be used to register a function to an API, initialize function attributes, and so on.

In more typical use, to insert logic that intercepts later calls to a function, we might code a decorator to return a different object than the original function—a proxy for later calls:

def decorator(F):
    # Save or use function F
    # Return a different callable: nested def, class instance with __call__, etc.

@decorator
def func(): …                 # func = decorator(func)

This decorator is invoked at decoration time, and the callable it returns is invoked when the original function name is later called. The decorator itself receives the decorated function; the callable returned receives whatever arguments are later passed to the decorated function’s name. When coded properly, this works the same for class-level methods: the implied instance object simply shows up in the first argument of the returned callable.

In skeleton terms, here’s one common coding pattern that captures this idea—the decorator returns a wrapper that retains the original function in an enclosing scope:

def decorator(F):                     # On @ decoration
    def wrapper(*args):               # On wrapped function call
        # Use F and args
        # F(*args) calls original function
    return wrapper

@decorator                            # func = decorator(func)
def func(x, y):                       # func is passed to decorator's F
    …

func(6, 7)                            # 6, 7 are passed to wrapper's *args

When the name func is later called, it really invokes the wrapper function returned by decorator; the wrapper function can then run the original func because it is still available in an enclosing scope. When coded this way, each decorated function produces a new scope to retain state.

To do the same with classes, we can overload the call operation and use instance attributes instead of enclosing scopes:

class decorator:
    def __init__(self, func):         # On @ decoration
        self.func = func
    def __call__(self, *args):        # On wrapped function call
        # Use self.func and args
        # self.func(*args) calls original function

@decorator
def func(x, y):                       # func = decorator(func)
    …                                 # func is passed to __init__

func(6, 7)                            # 6, 7 are passed to __call__'s *args

When the name func is later called now, it really invokes the __call__ operator-overloading method of the instance created by decorator; the __call__ method can then run the original func because it is still available in an instance attribute. When coded this way, each decorated function produces a new instance to retain state.

Supporting method decoration

One subtle point about the prior class-based coding is that while it works to intercept simple function calls, it does not quite work when applied to class-level method functions:

class decorator:
    def __init__(self, func):           # func is method without instance
        self.func = func
    def __call__(self, *args):          # self is decorator instance
        # self.func(*args) fails!       # C instance not in args!

class C:
    @decorator
    def method(self, x, y):             # method = decorator(method)
        …                               # Rebound to decorator instance

When coded this way, the decorated method is rebound to an instance of the decorator class instead of a simple function.

The problem with this is that the self in the decorator’s __call__ receives the decorator class instance when the method is later run, and the instance of class C is never included in *args. This makes it impossible to dispatch the call to the original method—the decorator object retains the original method function, but it has no instance to pass to it.

To support both functions and methods, the nested function alternative works better:

def decorator(F):                       # F is func or method without instance
    def wrapper(*args):                 # class instance in args[0] for method
        # F(*args) runs func or method
    return wrapper

@decorator
def func(x, y):                         # func = decorator(func)
    …
func(6, 7)                              # Really calls wrapper(6, 7)

class C:
    @decorator
    def method(self, x, y):             # method = decorator(method)
        …                               # Rebound to simple function

X = C()
X.method(6, 7)                          # Really calls wrapper(X, 6, 7)

When coded this way, wrapper receives the C class instance in its first argument, so it can dispatch to the original method and access state information.

Technically, this nested-function version works because Python creates a bound method object and thus passes the subject class instance to the self argument only when a method attribute references a simple function; when it references an instance of a callable class instead, the callable class’s instance is passed to self to give the callable class access to its own state information. You’ll see how this subtle difference can matter in more realistic examples later in this chapter.

Also note that nested functions are perhaps the most straightforward way to support decoration of both functions and methods, but not necessarily the only way. The prior chapter’s descriptors, for example, receive both the descriptor-class and subject-class instance when called. Though more complex, later in this chapter you’ll see how this tool can be leveraged in this context as well.

Usage

Syntactically, class decorators appear just before class statements, in the same way that function decorators appear just before def statements. In symbolic terms, for a decorator that must be a one-argument callable that returns a callable, the class decorator syntax:

@decorator                 # Decorate class
class C:
    …

x = C(99)                  # Make an instance

is equivalent to the following—the class is automatically passed to the decorator function, and the decorator’s result is assigned back to the class name:

class C:
    …
C = decorator(C)           # Rebind class name to decorator result

x = C(99)                  # Essentially calls decorator(C)(99)

The net effect is that calling the class name later to create an instance winds up triggering the callable returned by the decorator, which may or may not call the original class itself.

Implementation

New class decorators are coded with many of the same techniques used for function decorators, though some may involve two levels of augmentation—to manage both instance-construction calls as well as instance-interface access. Because a class decorator is also a callable that returns a callable, most combinations of functions and classes suffice.

However it’s coded, the decorator’s result is what runs when an instance is later created. For example, to simply manage a class just after it is created, return the original class itself:

def decorator(C):
    # Process class C here
    return C

@decorator
class C: …                                      # C = decorator(C)

To instead insert a wrapper layer that intercepts later instance-creation calls, return a different callable object:

def decorator(C):
    # Save or use class C
    # Return a different callable: nested def, class instance with __call__, etc.

@decorator
class C: …                                      # C = decorator(C)

The callable returned by such a class decorator typically creates and returns a new instance of the original class, augmented in some way to manage its interface. For example, the following inserts an object that intercepts undefined attributes of a class instance:

def decorator(cls):                             # On @ decoration
    class Wrapper:
        def __init__(self, *args):              # On instance creation
            self.wrapped = cls(*args)
        def __getattr__(self, name):            # On attribute fetch
            return getattr(self.wrapped, name)
    return Wrapper

@decorator
class C:                             # C = decorator(C)
    def __init__(self, x, y):        # Run by Wrapper.__init__
        self.attr = 'hack'

x = C(6, 7)                          # Really calls Wrapper(6, 7)
print(x.attr)                        # Runs Wrapper.__getattr__, prints "hack"

In this example, the decorator rebinds the class name to another class, which retains the original class in an enclosing scope and creates and embeds an instance of the original class when it’s called. When an attribute is later fetched from the instance, it is intercepted by the wrapper’s __getattr__ and delegated to the embedded instance of the original class. Moreover, each decorated class creates a new scope, which remembers the original class. We’ll flesh out this example into some more useful code later in this chapter.

Like function decorators, class decorators are commonly coded as either closure (a.k.a. “factory”) functions that create and return callables, classes that use __init__ or __call__ methods to intercept call operations, or some combination thereof. Closure functions typically retain state in enclosing-scope references, and classes retain state in attributes.

Supporting multiple instances

As for function decorators, some callable-type combinations work better for class decorators than others. Consider the following invalid alternative to the class decorator of the prior example:

class Decorator:
    def __init__(self, C):                    # On @ decoration
        self.C = C
    def __call__(self, *args):                # On instance creation
        self.wrapped = self.C(*args)
        return self
    def __getattr__(self, attrname):          # On attribute fetch
        return getattr(self.wrapped, attrname)

@Decorator
class C: …                                    # C = Decorator(C)

x = C()
y = C()                                       # Overwrites x!

This code handles multiple decorated classes (each makes a new Decorator instance) and will intercept instance-creation calls (each runs __call__). Unlike the prior version, however, this version fails to handle multiple instances of a given class—each instance-creation call overwrites the prior saved instance. The prior version does support multiple instances because each instance-creation call makes a new independent wrapper object. More generally, either of the following patterns supports multiple wrapped instances:

def decorator(C):                             # On @ decoration
    class Wrapper:
        def __init__(self, *args):            # On instance creation: new Wrapper
            self.wrapped = C(*args)           # Embed instance in instance
    return Wrapper

class Wrapper: …
def decorator(C):                             # On @ decoration
    def onCall(*args):                        # On instance creation: new Wrapper
        return Wrapper(C(*args))              # Embed instance in instance
    return onCall

We’ll study this phenomenon in a more realistic context later in the chapter too; in practice, though, we must be careful to combine callable types properly to support our intent and choose state policies wisely.

State with class-instance attributes

As an opening act in the state-retention show, Example 39-2 codes an augmented version of the prior example, which adds support for keyword arguments with ** syntax and returns the wrapped function’s result to support more use cases (for nonlinear readers, we first studied keyword arguments in Chapter 18).

class tracer:                                # State via instance attributes
    def __init__(self, func):                # On @ decorator
        self.calls = 0                       # Save func for later call
        self.func  = func
    def __call__(self, *args, **kwargs):     # On call to original function
        self.calls += 1
        print(f'call {self.calls} to {self.func.__name__}')
        return self.func(*args, **kwargs)

@tracer
def hack(a, b, c):           # Same as: hack = tracer(hack)
    print(a + b + c)         # Triggers tracer.__init__

@tracer
def code(x, y):              # Same as: code = tracer(code)
    print(x ** y)            # Wraps code in a tracer object

if __name__ == '__main__':
    hack(1, 2, 3)            # Really calls tracer instance: runs tracer.__call__
    hack(a=4, b=5, c=6)      # hack is an instance attribute

    code(4, 2)               # Really calls tracer instance: self.func is code
    code(2, y=16)            # self.calls is per-decoration here

Like the original, this uses class instance attributes to save state explicitly. Both the wrapped function and the calls counter are per-instance information—each decoration gets its own copy. When run as a script, the output of this version is as follows; notice how the hack and code functions each have their own calls counter because each decoration creates a new class instance:

$ python3 decorator_state_classes.py
call 1 to hack
6
call 2 to hack
15
call 1 to code
16
call 2 to code
65536

While useful for decorating functions, this coding scheme still has issues when applied to methods—a shortcoming we’ll address in a later revision.

State with global variables

For simpler tasks that don’t require per-function data, moving state variables out to the global scope, as illustrated by Example 39-3, might suffice. This code still uses an enclosing-scope reference for the original decorated function but pushes the call counter out to the enclosing module.

calls = 0
def tracer(func):                         # State via enclosing scope and global
    def wrapper(*args, **kwargs):         # Instead of class attributes
        global calls                      # calls is global, not per-function
        calls += 1
        print(f'call {calls} to {func.__name__}')
        return func(*args, **kwargs)
    return wrapper

@tracer
def hack(a, b, c):           # Same as: hack = tracer(hack)
    print(a + b + c)

@tracer
def code(x, y):              # Same as: code = tracer(code)
    print(x ** y)

if __name__ == '__main__':
    hack(1, 2, 3)            # Really calls wrapper, assigned to hack
    hack(a=4, b=5, c=6)      # wrapper calls hack

    code(4, 2)               # Really calls wrapper, assigned to code
    code(2, y=16)            # Global calls is not per-decoration here!

Unfortunately, moving the counter out to the common global scope to allow it to be changed like this also means that it will be shared by every wrapped function. Unlike class instance attributes, global counters are cross-program, not per-function—the counter is incremented for any traced function call. You can tell the difference if you compare this version’s output with the prior version’s—the single, shared global call counter is incorrectly updated by calls to every decorated function:

$ python3 decorator_state_globals.py
call 1 to hack
6
call 2 to hack
15
call 3 to code
16
call 4 to code
65536

State with enclosing-scope nonlocals

Shared global state may be what we want in some cases. If we really want a per-function counter, though, we can either use classes as before or make use of closure functions and the nonlocal statement described in Chapter 17. Because this statement allows enclosing function scope variables to be changed, they can serve as per-decoration, changeable data. Example 39-4 demos the basics of this scheme.

def tracer(func):                        # State via enclosing scope and nonlocal
    calls = 0                            # Instead of class attrs or global
    def wrapper(*args, **kwargs):        # calls is per-function, not global
        nonlocal calls
        calls += 1
        print(f'call {calls} to {func.__name__}')
        return func(*args, **kwargs)
    return wrapper

@tracer
def hack(a, b, c):           # Same as: hack = tracer(hack)
    print(a + b + c)

@tracer
def code(x, y):              # Same as: code = tracer(code)
    print(x ** y)

if __name__ == '__main__':
    hack(1, 2, 3)            # Really calls wrapper, bound to hack
    hack(a=4, b=5, c=6)      # wrapper calls hack

    code(4, 2)               # Really calls wrapper, bound to code
    code(2, y=16)            # Nonlocal calls _is_ per-decoration here

Now, because enclosing-scope variables are not cross-program globals, each wrapped function gets its own counter again, just as for classes and attributes. Here’s the new output:

$ python3 decorator_state_nonlocals.py
call 1 to hack
6
call 2 to hack
15
call 1 to code
16
call 2 to code
65536

State with function attributes

Finally, you can also avoid globals and classes by making use of function attributes for some changeable state instead of nonlocal. As we saw in Chapters 17 and 19, we can attach arbitrary attributes to functions by assignment, with func.attr=value. Because a factory function makes a new function on each call, its attributes become per-call state. Moreover, you need to use this technique only for state variables that must change; enclosing-scope references are still retained and work normally.

To demo, Example 39-5 simply uses wrapper.calls for state. It works the same as the preceding nonlocal version because the counter is again per-decorated-function.

def tracer(func):                        # State via enclosing scope and func attr
    def wrapper(*args, **kwargs):        # calls is per-function, not global
        wrapper.calls += 1
        print(f'call {wrapper.calls} to {func.__name__}')
        return func(*args, **kwargs)
    wrapper.calls = 0
    return wrapper

@tracer
def hack(a, b, c):           # Same as: hack = tracer(hack)
    print(a + b + c)

@tracer
def code(x, y):              # Same as: code = tracer(code)
    print(x ** y)

if __name__ == '__main__':
    hack(1, 2, 3)            # Really calls wrapper, assigned to hack
    hack(a=4, b=5, c=6)      # wrapper calls hack

    code(4, 2)               # Really calls wrapper, assigned to code
    code(2, y=16)            # wrapper.calls _is_ per-decoration here

As we learned in Chapter 17, this works only because the name wrapper is retained in the enclosing tracer function’s scope. When we later increment wrapper.calls, we are not changing the name wrapper itself, so no nonlocal declaration is required:

$ python3 decorator_state_attributes.py
…same output as prior version…

This scheme was almost relegated to a footnote because it may be more obscure than nonlocal and might be better saved for cases where other schemes don’t help. However, function attributes also have a substantial advantage: like class instances, they allow access to the saved state from outside the decorator’s code; nonlocals can only be seen inside the nested function itself, but function attributes have wider visibility.

We will employ function attributes again in an answer to one of the end-of-chapter questions, where their visibility outside callables becomes an asset. As changeable state associated with a context of use, though, they are equivalent to enclosing-scope nonlocals. As usual, choosing from multiple tools is an inherent part of the programming task.

Because decorators often imply multiple levels of callables, you can combine functions with enclosing scopes, classes with attributes, and function attributes to achieve a variety of coding structures. As you’ll see later, though, this sometimes may be subtler than you expect—each decorated function should have its own state, and each decorated class may require state both for itself and for each generated instance.

In fact, as the next section will explain in more detail, if we want to apply function decorators to class-level methods, too, we also have to be careful about the distinction Python makes between decorators based on callable class instance objects and decorators based on nested functions.

Using nested functions to decorate methods

If you want your function decorators to work on both simple functions and class-level methods, the most straightforward solution lies in using one of the other state retention solutions described earlier—code your function decorator as nested def statements so that you don’t depend on a single self instance argument to be both the wrapper class instance and the subject class instance.

In fact, we already have—both Examples 39-4 and 39-5 work for both functions and class methods by using nested functions along with nonlocal variables or function attributes:

>>> from decorator_state_nonlocals import tracer       # See Example 39-4

>>> @tracer
... def hack(a, b, c):                                 # Works for functions
        print(a + b + c)
 
>>> hack(1, 2, 3)
call 1 to hack
6

>>> class Person:                                      # AND works for methods
        def __init__(self, name, pay):
            self.name = name
            self.pay  = pay
        @tracer
        def giveRaise(self, percent):                  # self included in args
            self.pay *= (1.0 + percent)                # Counter in nonlocals
 
>>> pat = Person('Pat Jones', 50_000)
>>> pat.giveRaise(.10)
call 1 to giveRaise
>>> pat.giveRaise(.10)
call 2 to giveRaise
>>> f'{pat.pay:,.2f}'
'60,500.00'

>>> from decorator_state_attributes import tracer      # See Example 39-5
…same correct results…                                 # Counter in attributes

Because decorated methods here are rebound to simple functions instead of instance objects, Python correctly passes the Person object as the first argument, and the decorator propagates it on in the first item of *args to the self argument of the real, decorated methods. Trace through these results and decorators to make sure you have a handle on this model; the next section provides an alternative to it that supports classes but is also substantially more complex.

Using descriptors to decorate methods

Although the nested function solution illustrated in the prior section is the most straightforward way to support decorators that apply to both functions and class-level methods, other schemes are possible. The descriptor feature we explored in the prior chapter, for example, can help here as well.

Recall from our discussion in the prior chapter that a descriptor is normally a class attribute assigned to an object with a __get__ method run automatically whenever that attribute is referenced and fetched:

class Descriptor:
    def __get__(self, instance, owner): …

class Subject:
    attr = Descriptor()

X = Subject()
X.attr           # Roughly runs Descriptor.__get__(Subject.attr, X, Subject)

Descriptors may also have __set__ and __del__ access methods, but we don’t need them here. More relevant to this chapter’s topic: because the descriptor’s __get__ method receives both the descriptor class instance and subject class instance when invoked, it’s well suited to decorating methods when we need both the decorator’s state and the original class instance for dispatching calls. Consider the alternative tracing decorator in Example 39-6, which also happens to be a descriptor when used for a class-level method (its “…” are the same as in the prior REPL session).

class tracer(object):                        # A decorator+descriptor
    def __init__(self, func):                # On @ decorator
        self.calls = 0                       # Save func for later call
        self.func  = func
    def __call__(self, *args, **kwargs):     # On call to original func/meth
        self.calls += 1
        print(f'call {self.calls} to {self.func.__name__}')
        return self.func(*args, **kwargs)
    def __get__(self, instance, owner):      # On method attribute fetch
        return wrapper(self, instance)

class wrapper:
    def __init__(self, desc, subj):          # Save both instances
        self.desc = desc                     # Route calls back to deco/desc
        self.subj = subj
    def __call__(self, *args, **kwargs):
        return self.desc(self.subj, *args, **kwargs)  # Runs tracer.__call__

@tracer
def hack(a, b, c):                           # hack = tracer(hack)
    …                                        # Uses __call__ only

class Person:
    …
    @tracer
    def giveRaise(self, percent):            # giveRaise = tracer(giveRaise)
        …                                    # Makes giveRaise a descriptor

This works the same as the preceding nested function coding. Its operation varies by usage context:

• Decorated functions invoke only its __call__, and never invoke its __get__.

• Decorated methods invoke its __get__ first to resolve the method name fetch (on I.method); the object returned by __get__ retains the subject class instance and is then invoked to complete the call expression, thereby triggering the decorator’s __call__ (on ()).

For example, given the same testing code, the call to:

pat.giveRaise(.10)                           # Runs __get__ then __call__

runs tracer.__get__ first because the giveRaise attribute in the Person class has been rebound to a descriptor by the method function decorator. The call expression then triggers the __call__ method of the returned wrapper object, which in turn invokes tracer.__call__. In other words, decorated method calls trigger a five-step process: tracer.__get__, which invokes wrapper.__init__, followed by three call operations—wrapper.__call__, tracer.__call__, and finally the original wrapped method.

The wrapper object retains both descriptor and subject instances, so it can route control back to the original decorator/descriptor class instance. In effect, the wrapper object saves the subject class instance available during method attribute fetch and adds it to the later call’s arguments list, which is passed to the decorator__call__. Routing the call back to the descriptor class instance this way is required in this application so that all calls to a wrapped method use the same calls counter state information in the descriptor instance object.

Alternatively, we could use a nested function and enclosing-scope references to achieve the same effect—Example 39-7 works the same as the preceding one by swapping a wrapper class and attributes for a nested function and scope references. It requires noticeably less code but follows a similar multistep process on each decorated method call.

class tracer(object):
    def __init__(self, func):                # On @ decorator
        self.calls = 0                       # Save func for later call
        self.func  = func
    def __call__(self, *args, **kwargs):     # On call to original func
        self.calls += 1
        print(f'call {self.calls} to {self.func.__name__}')
        return self.func(*args, **kwargs)
    def __get__(self, instance, owner):                # On method fetch
        def wrapper(*args, **kwargs):                  # Retain both inst
            return self(instance, *args, **kwargs)     # Runs __call__
        return wrapper

…rest same as Example 39-6…

These two descriptor-based tracers work the same as the nested-functions version, so we’ll skip their output here. Add print statements to their methods to trace their multistep get/call processes if it helps. In either coding, this descriptor-based scheme is also substantially subtler than the nested-function option, and so is probably a second choice here. To be more blunt, if its complexity doesn’t send you screaming into the night, its performance costs probably should! Still, this may be a useful coding pattern in other contexts.

Before moving on, it’s also worth briefly noting that we might code this descriptor-based decorator more simply as in Example 39-8, but it would then apply only to methods, not to simple functions—an intrinsic limitation of attribute descriptors, and just the inverse of the problem we’re trying to solve (application to both functions and methods).

class tracer(object):                         # For methods, but not functions!
    def __init__(self, meth):                 # On @ decorator
        self.calls = 0                         
        self.meth  = meth
    def __get__(self, instance, owner):       # On method fetch
        def wrapper(*args, **kwargs):         # On method call: proxy with self+inst
            self.calls += 1
            print(f'call {self.calls} to {self.meth.__name__}')
            return self.meth(instance, *args, **kwargs)
        return wrapper

@tracer                                # OK for methods but FAILS for functions
def hack(a, b, c):                     # hack = tracer(hack)
    …                                  # No attribute fetch occurs on calls!

…rest same as Example 39-6…

In the rest of this chapter we’re going to be casual about using classes or functions to code our function decorators, as long as they are applied only to functions. Some decorators may not require the instance of the original class, and will still work on both functions and methods if coded as a class—something like Python’s own staticmethod decorator, for example, wouldn’t require an instance of the subject class (indeed, its whole point is to remove the instance from the call).

The simpler moral of this story, though, is that if you want your decorators to work on both simple functions and methods, you’re probably better off using the nested-function coding pattern instead of a class with call interception.

Singleton Coding alternatives

Interestingly, you can code a more self-contained solution here with the nonlocal statement to change enclosing-scope names as described earlier. The following alternative achieves an identical effect, by using one enclosing scope per class, instead of one global table entry per class. It works the same, but it does not depend on names in the global scope outside the decorator (the None check could use is instead of == here, but it’s a trivial test either way):

def singleton(aClass):                                   # On @ decoration
    instance = None
    def onCall(*args, **kwargs):                         # On instance creation
        nonlocal instance 
        if instance == None:
            instance = aClass(*args, **kwargs)           # One scope per class
        return instance
    return onCall

You can also code a self-contained solution with either function attributes or a class instead. The first of the following codes the former, leveraging the fact that there will be one onCall function per decoration—the function object’s namespace serves the same role as an enclosing scope. The second uses one instance per decoration, rather than an enclosing scope, function object, or global table. In fact, the second option relies on the same coding pattern that we will later label a common decorator class pitfall—here we want just one instance, but that’s not often the case:

def singleton(aClass):                                   # On @ decoration
    def onCall(*args, **kwargs):                         # On instance creation
        if onCall.instance == None:
            onCall.instance = aClass(*args, **kwargs)    # One function per class
        return onCall.instance
    onCall.instance = None
    return onCall

class singleton:
    def __init__(self, aClass):                          # On @ decoration
        self.aClass = aClass
        self.instance = None
    def __call__(self, *args, **kwargs):                 # On instance creation
        if self.instance == None:
            self.instance = self.aClass(*args, **kwargs) # One instance per class
        return self.instance

To make this singleton decorator a fully general-purpose tool, choose one version, store it in an importable module file, and indent the self-test code under a __name__ check—steps we’ll leave as suggested exercise. The final class-based version offers an explicit option with extra structure that may better support later evolution, but OOP might not be warranted in all contexts.

The nondecorator approach

For reference and review, here’s the original nondecorator delegation example:

class Wrapper:
    def __init__(self, object):
        self.wrapped = object                    # Save object
    def __getattr__(self, attrname):
        print('Trace:', attrname)                # Trace fetch
        return getattr(self.wrapped, attrname)   # Delegate fetch
x = Wrapper([1,2,3])       # Wrap a list object
x.append(4)                # Delegate to list method

In this code, the Wrapper class intercepts access to any of the wrapped object’s explicitly named attributes, prints a trace message, and uses the getattr built-in to pass off the request to the wrapped object. Specifically, it traces attribute accesses made outside the wrapped object’s class; accesses inside the wrapped object’s methods are not caught and run normally by design. This whole-interface model differs from the behavior of function decorators, which wrap up just one specific method.

The class-decorator approach

Class decorators provide an alternative and convenient way to code this __getattr__ technique and wrap an entire interface. The preceding code, for example, can be coded as a class decorator that triggers wrapped instance creation instead of passing a premade instance into the wrapper’s constructor. Example 39-14 codes this mod, also supports keyword arguments with **kargs, and counts the number of accesses to illustrate changeable state.

def Tracer(aClass):                                   # On @ decorator
    class Wrapper:
        def __init__(self, *args, **kargs):           # On instance creation
            self.fetches = 0
            self.wrapped = aClass(*args, **kargs)     # Use enclosing-scope name
        def __getattr__(self, attrname):
            print('Trace: ' + attrname)               # Catches all but own attrs
            self.fetches += 1
            return getattr(self.wrapped, attrname)    # Delegate to wrapped obj
    return Wrapper


if __name__ == '__main__':

    @Tracer
    class Hack:                                  # Hack = Tracer(Hack)
        def display(self):                       # Hack is rebound to Wrapper
            print('Hack!' * 3)

    @Tracer
    class Person:                                # Person = Tracer(Person)
        def __init__(self, name, hours, rate):   # Wrapper remembers Person
            self.name = name
            self.hours = hours
            self.rate = rate
        def pay(self):                           # Accesses outside class traced
            return self.hours * self.rate        # In-method accesses not traced

    work = Hack()                                # Triggers Wrapper()
    work.display()                               # Triggers __getattr__
    print([work.fetches])

    print()
    bob = Person('Bob', 40, 50)                  # bob is really a Wrapper
    print(bob.name)                              # Wrapper embeds a Person
    print(bob.pay())

    print()
    sue = Person('Sue', rate=100, hours=60)      # sue is a different Wrapper
    print(sue.name)                              # With a different Person
    print(sue.pay())

    print()
    print(bob.name)                              # bob's state != sue's state
    print(bob.pay())
    print('calls:', [bob.fetches, sue.fetches])  # Wrapper attrs are not traced

It’s important to note that this is very different from the tracer decorator we met earlier (despite the name!). In the section “Coding Function Decorators”, we looked at decorators that enabled us to trace and time calls to a given function or method. In contrast, by intercepting instance-creation calls, the class decorator here allows us to trace an entire object interface—that is, accesses to any of the instance’s attributes.

It’s also important to note that this decorator’s __getattr__ won’t catch the implicit attribute fetches of built-in operations per the prior chapter, but we’ll defer more on this subject until we code attribute privacy ahead.

The following is the output produced by this code: attribute fetches on instances of both the Hack and Person classes invoke the __getattr__ logic in the Wrapper class because work, and bob, and sue are really instances of Wrapper, thanks to the decorator’s redirection of instance-creation calls:

$ python3 interfacetracer.py
Trace: display
Hack!Hack!Hack!
[1]

Trace: name
Bob
Trace: pay
2000

Trace: name
Sue
Trace: pay
6000

Trace: name
Bob
Trace: pay
2000
calls: [4, 2]

Notice how there is one Wrapper class with state retention per decoration, generated by the nested class statement in the Tracer function, and how each instance gets its own fetches counter by virtue of generating a new Wrapper instance. As you’ll see ahead, orchestrating this is trickier than you may expect.

Applying class decorators to built-in types

Also notice that the preceding decorates a user-defined class. Just like in the original example in Chapter 31, we can also use the decorator to wrap up a built-in object type such as a list, as long as we either subclass to allow decoration syntax or perform the decoration rebinding manually—decorator syntax requires a class statement for the @ line. In the following, x is really a Wrapper again due to the indirection of decoration:

>>> from interfacetracer import Tracer

>>> @Tracer
... class MyList(list): pass      # MyList = Tracer(MyList)

>>> x = MyList([1, 2, 3])         # Triggers Wrapper()
>>> x.append(4)                   # Triggers __getattr__, append
Trace: append
>>> x.wrapped
[1, 2, 3, 4]

>>> MyList = Tracer(list)         # Or perform decoration manually
>>> x = MyList([4, 5, 6])         # Else subclass statement required
>>> x.append(7)
Trace: append
>>> x.wrapped
[4, 5, 6, 7]

The decorator approach allows us to move instance creation into the decorator itself instead of requiring a premade object to be passed in. Although this seems like a minor difference, it lets us retain normal instance-creation syntax and limits augmentation syntax to class definition. Rather than requiring all instance-creation calls to route objects through a wrapper manually, we need only augment class definitions with decorator syntax:

@Tracer                                          # Decorator approach
class Person: …
bob = Person('Bob', 40, 50)
sue = Person('Sue', rate=100, hours=60)

class Person: …                                  # Nondecorator approach
bob = Wrapper(Person('Bob', 40, 50))
sue = Wrapper(Person('Sue', rate=100, hours=60))

Assuming you will make more than one instance of a class and want to apply the augmentation to every instance of a class, decorators will generally be a net win in terms of both code size and code maintenance.

Inheritance versus delegation

The initial and limited privacy example shown in Chapter 30 used inheritance to mix in a __setattr__ to catch accesses. Inheritance makes this difficult, however, because differentiating between accesses from inside or outside the class is not straightforward (inside access should be allowed to run normally, and outside access should be restricted). To work around this, the Chapter 30 example requires inheriting classes to use __dict__ assignments to set attributes—an incomplete solution at best.

The version here uses delegation (embedding one object inside another) instead of inheritance; this pattern is better suited to our task as it makes it much easier to distinguish between accesses inside and outside of the subject class. Attribute accesses from outside the subject class are intercepted by the wrapper layer’s overloading methods and delegated to the class if valid. Accesses inside the class itself (i.e., through self within its methods’ code) are not intercepted and are allowed to run normally without checks because privacy is not inherited in this version.

Decorator arguments

The class decorator used here accepts any number of arguments to name private attributes. Again, though, this simply means that the arguments are passed to the Private function, and Private returns the decorator function to be applied to the subject class. That is, the arguments are used before decoration ever occurs; Private returns the decorator, which in turn “remembers” the privates list as an enclosing-scope reference.

State retention and enclosing scopes

Speaking of enclosing scopes, there are actually three levels of state retention at work in this code:

• The arguments to Private are used before decoration occurs and are retained as an enclosing-scope reference for use in both onDecorator and onInstance.

• The class argument to onDecorator is used at decoration time and is retained as an enclosing-scope reference for use at instance-creation time.

• The wrapped instance object is retained as an instance attribute in the onInstance proxy object for use when attributes are later accessed from outside the class.

This all works fairly naturally, given Python’s scope and namespace rules.

Using __dict__ and __slots__ (and other virtuals)

The __setattr__ method in this code relies on an instance object’s __dict__ attribute namespace dictionary in order to set onInstance’s own wrapped attribute. As we learned in the prior chapter, this method cannot assign an attribute directly without looping. However, it uses the setattr built-in instead of __dict__ to set attributes in the wrapped object itself. Moreover, getattr is used to fetch attributes in the wrapped object since they may be stored in the object itself or inherited by it.

Because of that, this code will work for most classes—including those with “virtual” class-level attributes based on slots, properties, descriptors, and even __getattr__ and its ilk. By assuming a namespace dictionary for itself only and using storage-neutral tools for the wrapped object, the wrapper class avoids limitations imposed by other tools.

For example, you may recall from Chapter 32 that classes with __slots__ may not store attributes in a __dict__, and in fact, may not even have one of these at all. However, because we rely on a __dict__ only at the onInstance level here and not in the wrapped instance, this concern does not apply. Class onInstance will have a __dict__ itself because it does not use slots. In addition, because setattr and getattr apply to attributes based on both __dict__ and __slots__, our decorator applies to wrapped classes using either storage scheme.

By the same reasoning, the decorator also applies to properties and similar tools: delegated names will be looked up anew in the wrapped instance, irrespective of attributes of the decorator proxy object itself.

Using __X pseudoprivate names

Besides generalizing, this version also makes use of Python’s __X pseudoprivate name mangling feature, which we met in Chapter 31, to localize the wrapped attribute to the proxy control class by automatically prefixing it with this class’s name. This avoids the prior version’s risk for collisions with a wrapped attribute that may be used by the real, wrapped class, and it’s useful in a general tool like this. It’s not quite “privacy,” though, because the mangled version of the name can be used freely outside the class. Notice that we also have to use the fully expanded name string—'_onInstance__wrapped'—as an admin-name test value in __setattr__ because that’s what Python changes it to.

Breaking privacy

Although this example does implement access controls for attributes of an instance and its classes, it is possible to subvert these controls trivially—for instance, by fetching through the expanded version of the wrapped attribute explicitly (bob.pay might not work, but the fully mangled bob._onInstance__wrapped.pay could!). If you have to try that hard to break them, though, these tools probably suffice for intended roles. Of course, privacy can generally be subverted in other languages too (e.g., #define private public may work in some C++ implementations). Although access controls may reduce accidental mods, much of this is up to programmers in any language; whenever source code may be changed, airtight access control will always be a pipe dream. More fundamentally, Python is about enabling, not controlling; privacy is a tool best used sparingly (if at all).

Decorator trade-offs

We could again achieve the same results without decorators by using helper functions or coding the name rebinding of decorators manually; the decorator syntax, however, makes this consistent and obvious in code. The chief potential downsides of this and any other wrapper-based approach are that attribute access incurs an extra call, and instances of decorated classes are not really instances of the original decorated class—if you test their type with X.__class__ or isinstance(X, C), for example, you’ll find that they are instances of the wrapper class. Unless you plan to do introspection on objects’ types, though, the type issue is irrelevant, and the extra call may apply mostly to development time; as you’ll see later, it’s possible to remove decorations automatically (via -O) if desired.

Workaround: Coding operator-overloading methods inline

The most straightforward way to support built-ins in delegation proxies is to redefine operator-overloading names that may appear in embedded objects. This creates some code redundancy, but it isn’t impossibly onerous; can be automated with tools or superclasses; and can choose to run or skip validations for operator-overloading names declared Private or Public, depending on redefinitions’ routing.

For instance, the partial listing of Example 39-19 sketches an inline redefinition approach—it catches and delegates built-ins by adding method definitions to the proxy itself for every operator-overloading method a wrapped object may define. It adds just four operation interceptors to illustrate, but others are similar (in this section, new code is in bold font, and all examples are based on the decorator of access2.py in Example 39-18).

"Inline methods, skip validations"

def accessControl(failIf):
    def onDecorator(aClass):
        class onInstance:
            def __init__(self, *args, **kargs):
                self.__wrapped = aClass(*args, **kargs)

            # Intercept and delegate built-in implicit access specifically

            def __add__(self, other):
                return self.__wrapped + other           # Or getattr(), __getattr__()
            def __str__(self):
                return str(self.__wrapped)              # Or self.__wrapped.__str__()
            def __getitem__(self, index):
                return self.__wrapped[index]
            def __call__(self, *args, **kargs):
                return self.__wrapped(*args, **kargs)
            # Plus any others needed

            # Intercept and delegate explicit attribute access generically

            def __getattr__(self, attr): …same…
            def __setattr__(self, attr, value): …same…
        return onInstance
    return onDecorator

This works because built-ins will find their requisite methods in the proxy class after skipping the proxy instance. As coded, the new interceptor methods trigger the wrapped object’s operator-overloading methods directly and so bypass the access controls of __getattr__, which may or may not be desirable. For alternative codings, let’s move on.

Workaround: Coding operator-overloading methods in superclasses

More usefully, the prior section’s added methods can be added by a common superclass. Given that there are dozens of such methods, an external class may be better suited to the task, especially if it is general enough to be used in any such interface-proxy class.

To demo, the superclass of Example 39-20 catches built-ins and reroutes to the wrapped object directly again. It’s largely just a repackaging of the prior section’s inline scheme, but as a separate class it requires a proxy attribute named _wrapped, giving access to the embedded object. The decorator itself must use this name instead of __wrapped in self references, and sans mangling in __setattr__. This may be subpar because it precludes the same name in wrapped objects and creates a subclass dependency, but it’s better than using the mangled and subclass-specific _onInstance__wrapped and is no worse than a similarly named method.

"Inherit methods, skip validations"

class BuiltinsMixin:
    def __add__(self, other):
        return self._wrapped + other                          # Assume a _wrapped
    def __str__(self):                                        # Bypass __getattr__
        return str(self._wrapped)
    def __getitem__(self, index):
        return self._wrapped[index]
    def __call__(self, *args, **kargs):
        return self._wrapped(*args, **kargs)
    # Plus any others needed

def accessControl(failIf):
    def onDecorator(aClass):
        class onInstance(BuiltinsMixin):
            …rest same, but use unmangled _wrapped instead of __wrapped…

Alternatively, the superclass in Example 39-21 catches built-ins and reroutes them down through the subclass __getattr__ to apply its access controls to the operation’s method name. It requires that operator-overloading names be non-Private or Public per the decorator’s arguments if they are to be run, but it treats the implicit fetches of built-in operations the same as explicit-name fetches, and no _wrapped is required in subclasses.

"Inherit methods, run validations"

class BuiltinsMixin:
    def __add__(self, other):
        return self.__getattr__('__add__')(other)             # Route to validator
    def __str__(self):                                        # Finish operations
        return self.__getattr__('__str__')()
    def __getitem__(self, index):
        return self.__getattr__('__getitem__')(index)
    def __call__(self, *args, **kargs):
        return self.__getattr__('__call__')(*args, **kargs)
    # Plus any others needed

def accessControl(failIf):
    def onDecorator(aClass):
        class onInstance(BuiltinsMixin):                      # Inherit methods
            …rest unchanged…

Like the inline approach, both of these mix-ins also require one method per built-in operation in general tools that proxy arbitrary objects’ interfaces. The next idea does may do marginally better.

Workaround: Generating operator-overloading descriptors

Finally, all of the inline and mix-in workarounds for built-ins we’ve seen so far code each operator-overloading method explicitly, and intercept the actual call issued for the operation, including its arguments. That makes them responsible for completing the operation, whether by operation syntax or equivalent calls.

With an alternative coding, we could instead intercept only the attribute fetch preceding the call by using the class-level descriptors of the prior chapter. Moreover, because all such descriptors will run the same, they can be generated automatically from a list of method names. Example 39-22 shows one way to code this scheme. Like Example 39-21, it routes built-in operations through the decorator’s validations logic to apply private or public checks.

"Inherit descriptors, run validations"

class BuiltinsMixin:
    class ProxyDesc:                                          # Define descriptor
        def __init__(self, attrname):
            self.attrname = attrname
        def __get__(self, instance, owner):
            return instance.__getattr__(self.attrname)        # Run validations

    builtins = ['add', 'str', 'getitem', 'call']              # Plus any others
    for attr in builtins:
        exec(f'__{attr}__ = ProxyDesc("__{attr}__")')         # Make descriptors

def accessControl(failIf):
    def onDecorator(aClass):
        class onInstance(BuiltinsMixin):                      # Inherit descriptors
            …rest unchanged…

This coding may be the most concise but also the most implicit and complex. Recall that the exec built-in by default runs a string of code as if the string was somehow pasted where the exec appears. Hence, the loop at the end of this mic-in class is equivalent to the following statements, run in the mix-in class’s local scope:

    __add__ = ProxyDesc("__add__")
    __str__ = ProxyDesc("__str__")
    …etc…

The net effect creates inherited descriptor instances that respond to initial name lookups by fetching from the wrapped object in __get__ rather than catching the later operation call itself (which happens after this step). If you still find this code confusing (and you probably should), it’s equivalent to this stripped-down version, though the name fetch occurs implicitly in a built-in operation that skips the instance’s protocols:

>>> class B:
        class D:
            def __get__(s, i, o): return i.meth()
        name = D()
 
>>> class A(B):
        def meth(self): return 'hack'
 
>>> I = A()
>>> I.name
'hack'

We could also skip the decorator’s validations for built-in operations in this scheme by routing attribute fetches directly to the wrapped object—though this requires an accessible _wrapped in the decorator just like Example 39-20:

    class ProxyDesc:                                             
        …
        def __get__(self, instance, owner):
            return getattr(instance._wrapped, self.attrname)     # Assume a _wrapped

In the end, all of these workarounds make classes that overload built-in operations work correctly with our private and public decorators—and other delegation-based decorators like them:

>>> from access_builtins_mixin_desc import Private

>>> @Private('sum')
... class Tally: 
        def __init__(self):
            self.sum = 0
        def __str__(self):
            return f'Tally: {self.sum}'
        def __add__(self, add):
            self.sum += add

>>> X = Tally()
>>> X.sum                                          # Explicit validated
TypeError: private attribute fetch, sum
>>> X + 10                                         # Built-in delegated
>>> print(X)                                       # Built-in delegated
Tally: 10

Public (nonprivate) built-ins are now delegated and work, but private built-ins are validated and cancelled:

>>> @Private('sum', '__add__')
... class Tally: 
        …same as before…

>>> X = Tally()
>>> X.sum                                          # Explicit validated
TypeError: private attribute fetch, sum
>>> X + 10                                         # Built-in cancelled: private
TypeError: private attribute fetch, __add__
>>> print(X)                                       # Built-in allowed: public
Tally: 0

>>> @Private('__str__')
... class Tally: 
        …same as before…

>>> print(Tally())                                 # Built-in cancelled: private
TypeError: private attribute fetch, __str__

If you care to experiment further with this section’s examples, see the book examples package for their complete code, as well as its comprehensive access_builtins_TEST.py test script and results. Here, it’s time to move on to this chapter’s next and final decorators case study.

Function introspection

It turns out that the introspection API available on function objects and their associated code objects has exactly the tool we need. This API was briefly introduced in Chapter 19, but we’ve actually put it to use here. The set of expected argument names is simply the first N variable names attached to a function’s code object:

>>> def func(a, b, c, e=True, f=None):       # Args: three required, two defaults
        x = 1                                # Plus two more local variables
        y = 2

>>> code = func.__code__                     # Code object of function object
>>> code.co_nlocals
7
>>> code.co_varnames                         # All local variable names
('a', 'b', 'c', 'e', 'f', 'x', 'y')
>>> code.co_varnames[:code.co_argcount]      # <== First N locals are expected args
('a', 'b', 'c', 'e', 'f')

And as usual, starred-argument names in the call proxy allow it to collect arbitrarily many arguments to be matched against the expected arguments so obtained from the function’s introspection API:

>>> def catcher(*pargs, **kargs): print(f'{pargs}, {kargs}')

>>> catcher(1, 2, 3, 4, 5)
(1, 2, 3, 4, 5), {}
>>> catcher(1, 2, c=3, d=4, e=5)             # Arguments at calls
(1, 2), {'d': 4, 'e': 5, 'c': 3}

Run a dir call on function and code objects for more details.

Argument assumptions

Given the decorated function’s set of expected argument names, the solution relies upon two constraints on argument passing order imposed by Python and covered in Chapter 18:

• At the call, all positional arguments appear before all keyword arguments.

• In the def, all nondefault arguments appear before all default arguments.

That is, a nonkeyword argument cannot generally follow a keyword argument at a call, and a nondefault argument cannot follow a default argument at a definition. All “name=value” syntax must appear after any simple “name” in both places. As we’ve also learned, Python matches argument values passed by position to argument names in function headers from left to right, such that these values always match the leftmost names in headers. Keywords match by name instead, and a given argument can receive only one value.

To simplify our work, we can also make the assumption that a call is valid in general—that is, that all arguments either will receive values (by name or position) or will be omitted intentionally to pick up defaults. This assumption won’t necessarily hold because the function has not yet actually been called when the wrapper logic tests validity—the call may still fail later when invoked by the wrapper layer due to incorrect argument passing. As long as that doesn’t cause the wrapper to fail any more badly, though, we can ignore the validity of the call. This helps because validating calls before they are actually made would require us to emulate Python’s argument-matching algorithm in full.

Matching algorithm

Now, given these constraints and assumptions, we can allow for both keywords and omitted default arguments in the call with this algorithm. When a call is intercepted, we can make the following assumptions and deductions:

1. Let N be the number of passed positional arguments, obtained from the length of the *pargs tuple.

2. All N positional arguments in *pargs must match the first N expected arguments obtained from the function’s code object. This is true per Python’s call ordering rules, outlined earlier, since all positionals precede all keywords in a call.

3. To obtain the names of arguments actually passed by position, we can slice the list of all expected arguments up to the length N of the *pargs passed positionals tuple.

4. Any arguments after the first N expected arguments either were passed by keyword or were defaulted by omission at the call.

5. For each argument name to be validated by the decorator:

   • If the name is in **kargs, it was passed by name—indexing **kargs gives its passed value.

   • If the name is in the first N expected arguments, it was passed by position—its relative position in the expected list gives its relative position in *pargs.

   • Otherwise, we can assume it was omitted in the call and defaulted and need not be checked.

In other words, we can skip tests for arguments that were omitted in a call by assuming that the first N actually passed positional arguments in *pargs must match the first N argument names in the list of all expected arguments, and that any others must either have been passed by keyword and thus be in **kargs, or have been defaulted. Under this scheme, the decorator will simply skip any argument to be checked that was omitted between the rightmost positional argument and the leftmost keyword argument, between keyword arguments, or after the rightmost positional in general. Trace through the decorator and its test script to see how this is realized in code.

Invalid calls

First, as mentioned earlier, calls to the original function that are not valid still fail in our final decorator. The following, for example, both trigger TypeError exceptions for a missing positional argument a:

omitargs()
omitargs(d=8, c=7, b=6)

These only fail, though, where we try to invoke the original function, at the end of the wrapper. While we could try to imitate Python’s argument matching to avoid this, there’s not much reason to do so—since the call would fail at this point anyhow, we might as well let Python’s own argument-matching logic detect the problem for us.

Arbitrary arguments

Second, although our final version handles positional arguments, keyword arguments, and omitted defaults, it still doesn’t do anything explicit about *pargs and **kargs starred-argument names that may be used in a decorated function def that accepts arbitrarily many arguments itself. This is probably moot for our purposes, though:

• If an extra keyword argument is passed, its name will show up in **kargs and can be tested normally if mentioned to the decorator.

• If an extra keyword argument is not passed, its name won’t be in either **kargs or the sliced expected positionals list, and it will thus not be checked—it is treated as though it were defaulted, even though it is really an optional extra argument.

• If an extra positional argument is passed, there’s no way to reference it in the decorator anyhow—its name won’t be in either **kargs or the sliced expected arguments list, so it will simply be skipped. Because such arguments are not listed in the function’s definition, there’s no way to map a name given to the decorator back to an expected relative position.

In other words, as it is the code supports testing arbitrary keyword arguments by name, but not arbitrary positionals that are unnamed and hence have no set position in the function’s argument signature. In terms of the function object’s API, here’s the effect of these tools in decorated functions:

>>> def func(*kargs, **pargs): pass
>>> code = func.__code__
>>> code.co_nlocals, code.co_varnames
(2, ('kargs', 'pargs'))
>>> code.co_argcount, code.co_varnames[:code.co_argcount]
(0, ())

>>> def func(a, b, *kargs, **pargs): pass
>>> code = func.__code__
>>> code.co_argcount, code.co_varnames[:code.co_argcount]
(2, ('a', 'b'))

Because starred-argument names show up as locals but not as expected arguments, they won’t be a factor in our matching algorithm—names preceding them in function headers can be validated as usual, but not any extra positional arguments passed. In principle, we could extend the decorator’s interface to support *pargs in the decorated function, too, for the rare cases where this might be useful (e.g., a special argument name with a test to apply to all arguments in *pargs beyond the length of the expected arguments list), but we’ll pass on such an extension here.

Also, bear in mind that this pertains to values in starred collectors in def headers only; given that starred unpackings in calls are flattened before they ever reach our decorator, they are irrelevant to its code. To borrow a pathological example from Chapter 18:

>>> def f(a, b, c, d, e, f, g, h, i): pass
>>> f.__code__.co_varnames[:f.__code__.co_argcount]
('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i')

>>> def f(*p, **k): print(p, k)
>>> f(*[1], 2, *[3], 4, f=6, *[5], **dict(g=7), h=8, **{'i': 9})
(1, 2, 3, 4, 5) {'f': 6, 'g': 7, 'h': 8, 'i': 9}

The call’s stars here are resolved before the function is started. Because our decorator finds values passed to argument names by indexing keywords and mapping expected to actual positionals, it can remain blissfully ignorant of stars in the call and will work normally in this example (though, to be fair, “normally” may be an exaggeration here).

Decorator nesting

Finally, and perhaps most subtly, this code’s approach does not fully support the use of decorator nesting to combine steps. Because it analyzes arguments using names in function definitions, and the names of the call proxy function returned by a nested decoration won’t correspond to argument names in either the original function or decorator arguments, it does not fully support use in nested mode.

Technically, when nested, only the most deeply nested appearance’s validations are run in full; all other nesting levels run tests on arguments passed by keyword only. Trace the code to see why; because the onCall proxy’s call signature expects no named positional arguments, any to-be-validated arguments passed to it by position are treated as if they were omitted and hence defaulted and are thus skipped.

This may be inherent in this tool’s approach—proxies change the argument name signatures at their levels, making it impossible to directly map names in decorator arguments to positions in passed argument sequences. When proxies are present, argument names ultimately apply to keywords only; by contrast, the first-cut solution’s argument positions may support proxies better but do not fully support keywords.

In lieu of this nesting capability, we’ll generalize this decorator to support multiple kinds of validations in a single decoration in an end-of-chapter quiz solution, which also gives examples of the nesting limitation in action. Since we’ve already neared the space allocation for this example, though, if you care about these or any other further improvements, you’ve officially crossed over into the realm of suggested exercises.