@overload vs.@when

The@overload decorator is a common-case shorthand for the moregeneral@when decorator. It allows you to leave out the name ofthe function you are overloading, at the expense of requiring thetarget function to be in the local namespace. It also doesn’t supportadding additional criteria besides the ones specified via argumentannotations. The following function definitions have identicaleffects, except for name binding side-effects (which will be describedbelow):

fromoverloadingimportwhen@overloaddefflatten(ob:basestring):yieldob@when(flatten)defflatten(ob:basestring):yieldob@when(flatten)defflatten_basestring(ob:basestring):yieldob@when(flatten,(basestring,))defflatten_basestring(ob):yieldob

The first definition above will bindflatten to whatever it waspreviously bound to. The second will do the same, if it was alreadybound to thewhen decorator’s first argument. Ifflatten isunbound or bound to something else, it will be rebound to the functiondefinition as given. The last two definitions above will always bindflatten_basestring to the function definition as given.

Using this approach allows you to both give a method a descriptivename (often useful in tracebacks!) and to reuse the method later.

Except as otherwise specified, alloverloading decorators have thesame signature and binding rules as@when. They accept a functionand an optional “predicate” object.

The default predicate implementation is a tuple of types withpositional matching to the overloaded function’s arguments. However,an arbitrary number of other kinds of predicates can be created andregistered using theExtension API, and will then be usable with@when and other decorators created by this module (like@before,@after, and@around).

Proceeding to the “Next” Method

If the first parameter of an overloaded function is named__proceed__, it will be passed a callable representing the nextmost-specific method. For example, this code:

deffoo(bar:object,baz:object):print"got objects!"@overloaddeffoo(__proceed__,bar:int,baz:int):print"got integers!"return__proceed__(bar,baz)

Will print “got integers!” followed by “got objects!”.

If there is no next most-specific method,__proceed__ will bebound to aNoApplicableMethods instance. When called, a newNoApplicableMethods instance will be raised, with the argumentspassed to the first instance.

Similarly, if the next most-specific methods have ambiguous precedencewith respect to each other,__proceed__ will be bound to anAmbiguousMethods instance, and if called, it will raise a newinstance.

Thus, a method can either check if__proceed__ is an errorinstance, or simply invoke it. TheNoApplicableMethods andAmbiguousMethods error classes have a commonDispatchErrorbase class, soisinstance(__proceed__,overloading.DispatchError)is sufficient to identify whether__proceed__ can be safelycalled.

(Implementation note: using a magic argument name like__proceed__could potentially be replaced by a magic function that would be calledto obtain the next method. A magic function, however, would degradeperformance and might be more difficult to implement on non-CPythonplatforms. Method chaining via magic argument names, however, can beefficiently implemented on any Python platform that supports creatingbound methods from functions – one simply recursively binds eachfunction to be chained, using the following function or error as theim_self of the bound method.)

“Before” and “After” Methods

In addition to the simple next-method chaining shown above, it issometimes useful to have other ways of combining methods. Forexample, the “observer pattern” can sometimes be implemented by addingextra methods to a function, that execute before or after the normalimplementation.

To support these use cases, theoverloading module will supply@before,@after, and@around decorators, that roughlycorrespond to the same types of methods in the Common Lisp ObjectSystem (CLOS), or the corresponding “advice” types in AspectJ.

Like@when, all of these decorators must be passed the function tobe overloaded, and can optionally accept a predicate as well:

fromoverloadingimportbefore,afterdefbegin_transaction(db):print"Beginning the actual transaction"@before(begin_transaction)defcheck_single_access(db:SingletonDB):ifdb.inuse:raiseTransactionError("Database already in use")@after(begin_transaction)defstart_logging(db:LoggableDB):db.set_log_level(VERBOSE)

@before and@after methods are invoked either before or afterthe main function body, and arenever considered ambiguous. Thatis, it will not cause any errors to have multiple “before” or “after”methods with identical or overlapping signatures. Ambiguities areresolved using the order in which the methods were added to thetarget function.

“Before” methods are invoked most-specific method first, withambiguous methods being executed in the order they were added. All“before” methods are called before any of the function’s “primary”methods (i.e. normal@overload methods) are executed.

“After” methods are invoked in thereverse order, after all of thefunction’s “primary” methods are executed. That is, they are executedleast-specific methods first, with ambiguous methods being executed inthe reverse of the order in which they were added.

The return values of both “before” and “after” methods are ignored,and any uncaught exceptions raised byany methods (primary or other)immediately end the dispatching process. “Before” and “after” methodscannot have__proceed__ arguments, as they are not responsiblefor calling any other methods. They are simply called as anotification before or after the primary methods.

Thus, “before” and “after” methods can be used to check or establishpreconditions (e.g. by raising an error if the conditions aren’t met)or to ensure postconditions, without needing to duplicate any existingfunctionality.

“Around” Methods

The@around decorator declares a method as an “around” method.“Around” methods are much like primary methods, except that theleast-specific “around” method has higher precedence than themost-specific “before” method.

Unlike “before” and “after” methods, however, “Around” methodsareresponsible for calling their__proceed__ argument, in order tocontinue the invocation process. “Around” methods are usually usedto transform input arguments or return values, or to wrap specificcases with special error handling or try/finally conditions, e.g.:

fromoverloadingimportaround@around(commit_transaction)deflock_while_committing(__proceed__,db:SingletonDB):withdb.global_lock:return__proceed__(db)

They can also be used to replace the normal handling for a specificcase, bynot invoking the__proceed__ function.

The__proceed__ given to an “around” method will either be thenext applicable “around” method, aDispatchError instance,or a synthetic method object that will call all the “before” methods,followed by the primary method chain, followed by all the “after”methods, and return the result from the primary method chain.

Thus, just as with normal methods,__proceed__ can be checked forDispatchError-ness, or simply invoked. The “around” method shouldreturn the value returned by__proceed__, unless of course itwishes to modify or replace it with a different return value for thefunction as a whole.

Custom Combinations

The decorators described above (@overload,@when,@before,@after, and@around) collectively implement what in CLOS iscalled the “standard method combination” – the most common patternsused in combining methods.

Sometimes, however, an application or library may have use for a moresophisticated type of method combination. For example, if youwould like to have “discount” methods that return a percentage off,to be subtracted from the value returned by the primary method(s),you might write something like this:

fromoverloadingimportalways_overrides,merge_by_defaultfromoverloadingimportAround,Before,After,Method,MethodListclassDiscount(MethodList):"""Apply return values as discounts"""def__call__(self,*args,**kw):retval=self.tail(*args,**kw)forsig,bodyinself.sorted():retval-=retval*body(*args,**kw)returnretval# merge discounts by prioritymerge_by_default(Discount)# discounts have precedence over before/after/primary methodsalways_overrides(Discount,Before)always_overrides(Discount,After)always_overrides(Discount,Method)# but not over "around" methodsalways_overrides(Around,Discount)# Make a decorator called "discount" that works just like the# standard decorators...discount=Discount.make_decorator('discount')# and now let's use it...defprice(product):returnproduct.list_price@discount(price)deften_percent_off_shoes(product:Shoe)returnDecimal('0.1')

Similar techniques can be used to implement a wide variety ofCLOS-style method qualifiers and combination rules. The process ofcreating custom method combination objects and their correspondingdecorators is described in more detail under theExtension APIsection.

Note, by the way, that the@discount decorator shown will workcorrectly with any new predicates defined by other code. For example,ifzope.interface were to register its interface types to workcorrectly as argument annotations, you would be able to specifydiscounts on the basis of its interface types, not just classes oroverloading-defined interface types.

Similarly, if a library like RuleDispatch or PEAK-Rules were toregister an appropriate predicate implementation and dispatch engine,one would then be able to use those predicates for discounts as well,e.g.:

fromsomewhereimportPred# some predicate implementation@discount(price,Pred("isinstance(product,Shoe) and"" product.material.name=='Blue Suede'"))defforty_off_blue_suede_shoes(product):returnDecimal('0.4')

The process of defining custom predicate types and dispatching enginesis also described in more detail under theExtension API section.

Abstract and Concrete Methods

Note, by the way, that the@abstract decorator is not limited touse in interface definitions; it can be used anywhere that you wish tocreate an “empty” generic function that initially has no methods. Inparticular, it need not be used inside a class.

Also note that interface methods need not be abstract; one could, forexample, write an interface like this:

classIWriteMapping(Interface):@abstractdef__setitem__(self,key,value):"""This has to be implemented"""defupdate(self,other:IReadMapping):fork,vinIReadMapping(other).items():self[k]=v

As long as__setitem__ is defined for some type, the aboveinterface will provide a usableupdate() implementation. However,if some specific type (or pair of types) has a more efficient way ofhandlingupdate() operations, an appropriate overload can stillbe registered for use in that case.

Subclassing and Re-assembly

Interfaces can be subclassed:

classISizedStack(IStack):@abstractdef__len__(self):"""Return the number of items on the stack"""# define __len__ support for ISizedStackwhen(ISizedStack.__len__,(list,))(list.__len__)

Or assembled by combining functions from existing interfaces:

classSizable(Interface):__len__=ISizedStack.__len__# list now implements Sizable as well as ISizedStack, without# making any new declarations!

A class can be considered to “adapt to” an interface at a givenpoint in time, if no method defined in the interface is guaranteed toraise aNoApplicableMethods error if invoked on an instance ofthat class at that point in time.

In normal usage, however, it is “easier to ask forgiveness thanpermission”. That is, it is easier to simply use an interface onan object by adapting it to the interface (e.g.IStack(mylist))or invoking interface methods directly (e.g.IStack.push(mylist,42)), than to try to figure out whether the object is adaptable to(or directly implements) the interface.

Implementing an Interface in a Class

It is possible to declare that a class directly implements aninterface, using thedeclare_implementation() function:

fromoverloadingimportdeclare_implementationclassStack(object):def__init__(self):self.data=[]defpush(self,ob):self.data.append(ob)defpop(self):returnself.data.pop()declare_implementation(IStack,Stack)

Thedeclare_implementation() call above is roughly equivalent tothe following steps:

when(IStack.push,(Stack,object))(lambdaself,ob:self.push(ob))when(IStack.pop,(Stack,))(lambdaself,ob:self.pop())

That is, callingIStack.push() orIStack.pop() on an instanceof any subclass ofStack, will simply delegate to the actualpush() orpop() methods thereof.

For the sake of efficiency, callingIStack(s) wheres is aninstance ofStack,may returns rather than anIStackadapter. (Note that callingIStack(x) wherex is already anIStack adapter will always returnx unchanged; this is anadditional optimization allowed in cases where the adaptee is knowntodirectly implement the interface, without adaptation.)

For convenience, it may be useful to declare implementations in theclass header, e.g.:

classStack(metaclass=Implementer,implements=IStack):...

Instead of callingdeclare_implementation() after the end of thesuite.

Interfaces as Type Specifiers

Interface subclasses can be used as argument annotations toindicate what type of objects are acceptable to an overload, e.g.:

@overloaddeftraverse(g:IGraph,s:IStack):g=IGraph(g)s=IStack(s)# etc....

Note, however, that the actual arguments arenot changed or adaptedin any way by the mere use of an interface as a type specifier. Youmust explicitly cast the objects to the appropriate interface, asshown above.

Note, however, that other patterns of interface use are possible.For example, other interface implementations might not supportadaptation, or might require that function arguments already beadapted to the specified interface. So the exact semantics of usingan interface as a type specifier are dependent on the interfaceobjects you actually use.

For the interface objects defined by this PEP, however, the semanticsare as described above. An interface I1 is considered “more specific”than another interface I2, if the set of descriptors in I1’sinheritance hierarchy are a proper superset of the descriptors in I2’sinheritance hierarchy.

So, for example,ISizedStack is more specific than bothISizable andISizedStack, irrespective of the inheritancerelationships between these interfaces. It is purely a question ofwhat operations are included within those interfaces – and thenames of the operations are unimportant.

Interfaces (at least the ones provided byoverloading) are alwaysconsidered less-specific than concrete classes. Other interfaceimplementations can decide on their own specificity rules, bothbetween interfaces and other interfaces, and between interfaces andclasses.

Non-Method Attributes in Interfaces

TheInterface implementation actually treats all attributes andmethods (i.e. descriptors) in the same way: their__get__ (and__set__ and__delete__, if present) methods are called withthe wrapped (adapted) object as “self”. For functions, this has theeffect of creating a bound method linking the generic function to thewrapped object.

For non-function attributes, it may be easiest to specify them usingtheproperty built-in, and the correspondingfget,fset,andfdel attributes:

classILength(Interface):@property@abstractdeflength(self):"""Read-only length attribute"""# ILength(aList).length == list.__len__(aList)when(ILength.length.fget,(list,))(list.__len__)

Alternatively, methods such as_get_foo() and_set_foo()may be defined as part of the interface, and the property definedin terms of those methods, but this is a bit more difficult for usersto implement correctly when creating a class that directly implementsthe interface, as they would then need to match all the individualmethod names, not just the name of the property or attribute.