PEP 3124 – Overloading, Generic Functions, Interfaces, and Adaptation | peps.python.org
PEP 3124 – Overloading, Generic Functions, Interfaces, and Adaptation PEP 3124 – Overloading, Generic Functions, Interfaces, and Adaptation Author : Phillip J. Eby <pje at telecommunity.com> Discussions-To : Python-3000 list Status : Deferred Type : Standards Track Requires : 3107 , 3115 , 3119 Created : 28-Apr-2007 Post-History : 30-Apr-2007 Replaces : 245 , 246 Table of Contents Deferred Abstract Rationale and Goals User API Overloading/Generic Functions @overload vs. @when Method Combination and Overriding Proceeding to the “Next” Method “Before” and “After” Methods “Around” Methods Custom Combinations Overloading Inside Classes Interfaces and Adaptation Abstract and Concrete Methods Subclassing and Re-assembly Implementing an Interface in a Class Interfaces as Type Specifiers Non-Method Attributes in Interfaces Aspects Extension API Overloading Usage Patterns Implementation Notes Copyright Deferred See https://mail.python.org/pipermail/python-3000/2007-July/008784.html .
Abstract This PEP proposes a new standard library module, overloading , to provide generic programming features including dynamic overloading (aka generic functions), interfaces, adaptation, method combining (ala CLOS and AspectJ), and simple forms of aspect-oriented programming (AOP). The proposed API is also open to extension; that is, it will be possible for library developers to implement their own specialized interface types, generic function dispatchers, method combination algorithms, etc., and those extensions will be treated as first-class citizens by the proposed API.
The API will be implemented in pure Python with no C, but may have some dependency on CPython-specific features such as sys._getframe and the func_code attribute of functions. It is expected that e.g. Jython and IronPython will have other ways of implementing similar functionality (perhaps using Java or C#). Rationale and Goals Python has always provided a variety of built-in and standard-library generic functions, such as len() , iter() , pprint.pprint() , and most of the functions in the operator module.
However, it currently: does not have a simple or straightforward way for developers to create new generic functions, does not have a standard way for methods to be added to existing generic functions (i.e., some are added using registration functions, others require defining __special__ methods, possibly by monkeypatching), and does not allow dispatching on multiple argument types (except in a limited form for arithmetic operators, where “right-hand” ( __r*__ ) methods can be used to do two-argument dispatch.
In addition, it is currently a common anti-pattern for Python code to inspect the types of received arguments, in order to decide what to do with the objects. For example, code may wish to accept either an object of some type, or a sequence of objects of that type. Currently, the “obvious way” to do this is by type inspection, but this is brittle and closed to extension. A developer using an already-written library may be unable to change how their objects are treated by such code, especially if the objects they are using were created by a third party.
Therefore, this PEP proposes a standard library module to address these, and related issues, using decorators and argument annotations ( PEP 3107 ). The primary features to be provided are: a dynamic overloading facility, similar to the static overloading found in languages such as Java and C++, but including optional method combination features as found in CLOS and AspectJ. a simple “interfaces and adaptation” library inspired by Haskell’s typeclasses (but more dynamic, and without any static type-checking), with an extension API to allow registering user-defined interface types such as those found in PyProtocols and Zope. a simple “aspect” implementation to make it easy to create stateful adapters and to do other stateful AOP.
These features are to be provided in such a way that extended implementations can be created and used. For example, it should be possible for libraries to define new dispatching criteria for generic functions, and new kinds of interfaces, and use them in place of the predefined features. For example, it should be possible to use a zope.interface interface object to specify the desired type of a function argument, as long as the zope.interface package registered itself correctly (or a third party did the registration).
In this way, the proposed API simply offers a uniform way of accessing the functionality within its scope, rather than prescribing a single implementation to be used for all libraries, frameworks, and applications. User API The overloading API will be implemented as a single module, named overloading , providing the following features: Overloading/Generic Functions The @overload decorator allows you to define alternate implementations of a function, specialized by argument type(s).
A function with the same name must already exist in the local namespace. The existing function is modified in-place by the decorator to add the new implementation, and the modified function is returned by the decorator. Thus, the following code: from overloading import overload from collections import Iterable def flatten ( ob ): """Flatten an object to its component iterables""" yield ob @overload def flatten ( ob : Iterable ): for o in ob : for ob in flatten ( o ): yield ob @overload def flatten ( ob : basestring ): yield ob creates a single flatten() function whose implementation roughly equates to: def flatten ( ob ): if isinstance ( ob , basestring ) or not isinstance ( ob , Iterable ): yield ob else : for o in ob : for ob in flatten ( o ): yield ob except that the flatten() function defined by overloading remains open to extension by adding more overloads, while the hardcoded version cannot be extended.
For example, if someone wants to use flatten() with a string-like type that doesn’t subclass basestring , they would be out of luck with the second implementation. With the overloaded implementation, however, they can either write this: @overload def flatten ( ob : MyString ): yield ob or this (to avoid copying the implementation): from overloading import RuleSet RuleSet ( flatten ) . copy_rules (( basestring ,), ( MyString ,)) (Note also that, although PEP 3119 proposes that it should be possible for abstract base classes like Iterable to allow classes like MyString to claim subclass-hood, such a claim is global , throughout the application.
In contrast, adding a specific overload or copying a rule is specific to an individual function, and therefore less likely to have undesired side effects.) @overload vs. @when The @overload decorator is a common-case shorthand for the more general @when decorator. It allows you to leave out the name of the function you are overloading, at the expense of requiring the target function to be in the local namespace. It also doesn’t support adding additional criteria besides the ones specified via argument annotations.
The following function definitions have identical effects, except for name binding side-effects (which will be described below): from overloading import when @overload def flatten ( ob : basestring ): yield ob @when ( flatten ) def flatten ( ob : basestring ): yield ob @when ( flatten ) def flatten_basestring ( ob : basestring ): yield ob @when ( flatten , ( basestring ,)) def flatten_basestring ( ob ): yield ob The first definition above will bind flatten to whatever it was previously bound to.
The second will do the same, if it was already bound to the when decorator’s first argument. If flatten is unbound or bound to something else, it will be rebound to the function definition as given. The last two definitions above will always bind flatten_basestring to the function definition as given. Using this approach allows you to both give a method a descriptive name (often useful in tracebacks!) and to reuse the method later.
Except as other
The rest of this page is on the live site.