@overload vs. @when

Der Dekorator @overload ist eine gängige Kurzform für den allgemeineren Dekorator @when. Er erlaubt es, den Namen der zu überladenden Funktion wegzulassen, auf Kosten der Anforderung, dass die Ziel funktion im lokalen Namensraum vorhanden sein muss. Außerdem unterstützt er nicht das Hinzufügen zusätzlicher Kriterien außer denen, die über Argumentannotationen angegeben werden. Die folgenden Funktionsdefinitionen haben identische Auswirkungen, abgesehen von den Nebeneffekten der Namensbindung (die unten beschrieben werden):

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

Die erste Definition oben bindet flatten an das, womit es zuvor gebunden war. Die zweite tut dasselbe, wenn sie bereits an das erste Argument des when-Dekorators gebunden war. Wenn flatten ungebunden ist oder an etwas anderes gebunden ist, wird es an die Funktionsdefinition wie gegeben gebunden. Die letzten beiden Definitionen oben binden flatten_basestring immer an die Funktionsdefinition wie gegeben.

Die Verwendung dieses Ansatzes ermöglicht es, einer Methode einen beschreibenden Namen zu geben (oft nützlich in Tracebacks!) und die Methode später wiederzuverwenden.

Sofern nicht anders angegeben, haben alle overloading-Dekoratoren dieselbe Signatur und Bindungsregeln wie @when. Sie akzeptieren eine Funktion und ein optionales "Prädikat"-Objekt.

Die Standardimplementierung des Prädikats ist ein Tupel von Typen mit positiver Übereinstimmung mit den Argumenten der überladenen Funktion. Es können jedoch beliebig viele andere Arten von Prädikaten erstellt und mit der Erweiterungs-API registriert werden und sind dann mit @when und anderen von diesem Modul erstellten Dekoratoren (wie @before, @after und @around) verwendbar.

Weiter zur "nächsten" Methode

Wenn der erste Parameter einer überladenen Funktion __proceed__ genannt wird, wird ihr ein aufrufbares Objekt übergeben, das die nächstspezifischste Methode darstellt. Zum Beispiel dieser Code

def foo(bar:object, baz:object):
    print "got objects!"

@overload
def foo(__proceed__, bar:int, baz:int):
    print "got integers!"
    return __proceed__(bar, baz)

gibt "got integers!" gefolgt von "got objects!" aus.

Wenn es keine nächstspezifischste Methode gibt, wird __proceed__ an eine Instanz von NoApplicableMethods gebunden. Beim Aufruf wird eine neue Instanz von NoApplicableMethods ausgelöst, mit den an die erste Instanz übergebenen Argumenten.

Ebenso, wenn die nächstspezifischeren Methoden bezüglich einander mehrdeutige Präzedenzen haben, wird __proceed__ an eine Instanz von AmbiguousMethods gebunden, und wenn sie aufgerufen wird, wird sie eine neue Instanz auslösen.

Somit kann eine Methode entweder prüfen, ob __proceed__ eine Fehlerinstanz ist, oder sie einfach aufrufen. Die Fehlerklassen NoApplicableMethods und AmbiguousMethods haben eine gemeinsame Basisklasse DispatchError, daher reicht isinstance(__proceed__, overloading.DispatchError) aus, um zu erkennen, ob __proceed__ sicher aufgerufen werden kann.

(Implementierungshinweis: Die Verwendung eines magischen Argumentnamens wie __proceed__ könnte potenziell durch eine magische Funktion ersetzt werden, die aufgerufen würde, um die nächste Methode zu erhalten. Eine magische Funktion würde jedoch die Leistung beeinträchtigen und könnte auf Nicht-CPython-Plattformen schwieriger zu implementieren sein. Methodenverkettung über magische Argumentnamen kann jedoch auf jeder Python-Plattform effizient implementiert werden, die das Erstellen von gebundenen Methoden aus Funktionen unterstützt – man bindet einfach jede zu verkettende Funktion rekursiv, wobei die folgende Funktion oder der Fehler als im_self der gebundenen Methode verwendet wird.)

"Vorher" und "Nachher" Methoden

Zusätzlich zur einfachen Verkettung der nächsten Methode, wie oben gezeigt, ist es manchmal nützlich, andere Wege zur Kombination von Methoden zu haben. Zum Beispiel kann das "Observer-Pattern" manchmal implementiert werden, indem zusätzliche Methoden zu einer Funktion hinzugefügt werden, die vor oder nach der normalen Implementierung ausgeführt werden.

Um diese Anwendungsfälle zu unterstützen, wird das Modul overloading die Dekoratoren @before, @after und @around bereitstellen, die grob den gleichen Methodentypen im Common Lisp Object System (CLOS) oder den entsprechenden "Advice"-Typen in AspectJ entsprechen.

Wie @when müssen alle diese Dekoratoren mit der zu überladenden Funktion übergeben werden und können optional auch ein Prädikat akzeptieren.

from overloading import before, after

def begin_transaction(db):
    print "Beginning the actual transaction"

@before(begin_transaction)
def check_single_access(db: SingletonDB):
    if db.inuse:
        raise TransactionError("Database already in use")

@after(begin_transaction)
def start_logging(db: LoggableDB):
    db.set_log_level(VERBOSE)

@before und @after Methoden werden entweder vor oder nach dem Hauptfunktionskörper aufgerufen und werden *niemals als mehrdeutig betrachtet*. Das heißt, es werden keine Fehler ausgelöst, wenn mehrere "vorherige" oder "nachherige" Methoden mit identischen oder überlappenden Signaturen vorhanden sind. Mehrdeutigkeiten werden durch die Reihenfolge gelöst, in der die Methoden zur Ziel funktion hinzugefügt wurden.

"Vorher"-Methoden werden von der spezifischsten Methode zuerst aufgerufen, wobei mehrdeutige Methoden in der Reihenfolge ausgeführt werden, in der sie zur Ziel funktion hinzugefügt wurden. Alle "vorherigen" Methoden werden aufgerufen, bevor irgendeine der "primären" Methoden der Funktion (d. h. normale @overload-Methoden) ausgeführt wird.

"Nachher"-Methoden werden in *umgekehrter* Reihenfolge aufgerufen, nachdem alle "primären" Methoden der Funktion ausgeführt wurden. Das heißt, sie werden von der am wenigsten spezifischen Methode zuerst ausgeführt, wobei mehrdeutige Methoden in umgekehrter Reihenfolge ihrer Hinzufügung ausgeführt werden.

Die Rückgabewerte von "vorherigen" und "nachherigen" Methoden werden ignoriert, und alle unbehandelten Ausnahmen, die von *irgendeiner* Methode (primär oder anderweitig) ausgelöst werden, beenden sofort den Dispatch-Prozess. "Vorher"- und "Nachher"-Methoden können keine __proceed__-Argumente haben, da sie nicht für den Aufruf anderer Methoden verantwortlich sind. Sie werden einfach als Benachrichtigung vor oder nach den primären Methoden aufgerufen.

Daher können "vorherige" und "nachherige" Methoden verwendet werden, um Vorbedingungen zu überprüfen oder herzustellen (z. B. durch Auslösen eines Fehlers, wenn die Bedingungen nicht erfüllt sind) oder um Nachbedingungen sicherzustellen, ohne vorhandene Funktionalität duplizieren zu müssen.

"Umgebungs"-Methoden

Der Dekorator @around deklariert eine Methode als "around"-Methode. "Around"-Methoden sind weitgehend wie primäre Methoden, mit der Ausnahme, dass die am wenigsten spezifische "around"-Methode eine höhere Präzedenz hat als die spezifischste "before"-Methode.

Im Gegensatz zu "vorherigen" und "nachherigen" Methoden sind "around"-Methoden jedoch dafür verantwortlich, ihr __proceed__-Argument aufzurufen, um den Aufrufprozess fortzusetzen. "Around"-Methoden werden üblicherweise verwendet, um Eingabeargumente oder Rückgabewerte zu transformieren oder um spezifische Fälle mit spezieller Fehlerbehandlung oder Try/Finally-Bedingungen zu umhüllen, z. B.

from overloading import around

@around(commit_transaction)
def lock_while_committing(__proceed__, db: SingletonDB):
    with db.global_lock:
        return __proceed__(db)

Sie können auch verwendet werden, um die normale Behandlung für einen spezifischen Fall zu ersetzen, indem die __proceed__-Funktion *nicht* aufgerufen wird.

Der __proceed__, der einer "around"-Methode übergeben wird, ist entweder die nächste anwendbare "around"-Methode, eine DispatchError-Instanz oder ein synthetisches Methodenobjekt, das alle "vorherigen" Methoden aufruft, gefolgt von der primären Methodenkette, gefolgt von allen "nachherigen" Methoden, und das Ergebnis von der primären Methodenkette zurückgibt.

Somit kann, genau wie bei normalen Methoden, __proceed__ auf DispatchError-Eigenschaften geprüft oder einfach aufgerufen werden. Die "around"-Methode sollte den von __proceed__ zurückgegebenen Wert zurückgeben, es sei denn, sie möchte ihn natürlich modifizieren oder durch einen anderen Rückgabewert für die Funktion als Ganzes ersetzen.

Benutzerdefinierte Kombinationen

Die oben beschriebenen Dekoratoren (@overload, @when, @before, @after und @around) implementieren zusammen, was in CLOS die "Standardmethodenkombination" genannt wird – die gängigsten Muster zur Kombination von Methoden.

Manchmal hat jedoch eine Anwendung oder Bibliothek Verwendung für einen ausgefeilteren Typ der Methodenkombination. Wenn Sie beispielsweise "Rabatt"-Methoden haben möchten, die einen Prozentsatz Rabatt zurückgeben, der vom Wert der primären Methode(n) abgezogen werden soll, könnten Sie etwa so etwas schreiben:

from overloading import always_overrides, merge_by_default
from overloading import Around, Before, After, Method, MethodList

class Discount(MethodList):
    """Apply return values as discounts"""

    def __call__(self, *args, **kw):
        retval = self.tail(*args, **kw)
        for sig, body in self.sorted():
            retval -= retval * body(*args, **kw)
        return retval

# merge discounts by priority
merge_by_default(Discount)

# discounts have precedence over before/after/primary methods
always_overrides(Discount, Before)
always_overrides(Discount, After)
always_overrides(Discount, Method)

# but not over "around" methods
always_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...
def price(product):
    return product.list_price

@discount(price)
def ten_percent_off_shoes(product: Shoe)
    return Decimal('0.1')

Ähnliche Techniken können verwendet werden, um eine Vielzahl von CLOS-Style-Methodenqualifizierern und Kombinationsregeln zu implementieren. Der Prozess des Erstellens benutzerdefinierter Methodenkombinationsobjekte und ihrer entsprechenden Dekoratoren wird im Abschnitt Erweiterungs-API detaillierter beschrieben.

Übrigens, der gezeigte @discount-Dekorator funktioniert korrekt mit allen neuen Prädikaten, die von anderem Code definiert wurden. Wenn beispielsweise zope.interface seine Schnittstellentypen registrieren würde, damit sie korrekt als Argumentannotationen funktionieren, könnten Sie Rabatte basierend auf seinen Schnittstellentypen angeben, nicht nur auf Klassen oder von overloading definierten Schnittstellentypen.

Ebenso, wenn eine Bibliothek wie RuleDispatch oder PEAK-Rules eine geeignete Prädikatinplementierung und ein Dispatching-Engine registrieren würde, könnte man diese Prädikate dann auch für Rabatte verwenden, z. B.

from somewhere import Pred  # some predicate implementation

@discount(
    price,
    Pred("isinstance(product,Shoe) and"
         " product.material.name=='Blue Suede'")
)
def forty_off_blue_suede_shoes(product):
    return Decimal('0.4')

Der Prozess der Definition benutzerdefinierter Prädikattypen und Dispatching-Engines wird ebenfalls im Abschnitt Erweiterungs-API detaillierter beschrieben.

Abstrakte und konkrete Methoden

Beachten Sie übrigens, dass der Dekorator @abstract nicht nur zur Definition von Schnittstellen verwendet werden kann; er kann überall dort eingesetzt werden, wo Sie eine "leere" generische Funktion erstellen möchten, die zunächst keine Methoden hat. Insbesondere muss er nicht innerhalb einer Klasse verwendet werden.

Beachten Sie auch, dass Schnittstellenmethoden nicht abstrakt sein müssen; man könnte beispielsweise eine Schnittstelle wie folgt schreiben:

class IWriteMapping(Interface):
    @abstract
    def __setitem__(self, key, value):
        """This has to be implemented"""

    def update(self, other:IReadMapping):
        for k, v in IReadMapping(other).items():
            self[k] = v

Solange __setitem__ für einen bestimmten Typ definiert ist, bietet die obige Schnittstelle eine nutzbare update()-Implementierung. Wenn jedoch ein bestimmter Typ (oder ein Paar von Typen) eine effizientere Methode zur Verarbeitung von update()-Operationen hat, kann dennoch eine entsprechende Überladung für diesen Fall registriert werden.

Unterklassenbildung und Wiederzusammenfügung

Schnittstellen können von der Unterklasse gebildet werden

class ISizedStack(IStack):
    @abstract
    def __len__(self):
        """Return the number of items on the stack"""

# define __len__ support for ISizedStack
when(ISizedStack.__len__, (list,))(list.__len__)

Oder durch Kombination von Funktionen aus bestehenden Schnittstellen

class Sizable(Interface):
    __len__ = ISizedStack.__len__

# list now implements Sizable as well as ISizedStack, without
# making any new declarations!

Eine Klasse kann zu einem bestimmten Zeitpunkt als "Anpassung" an eine Schnittstelle betrachtet werden, wenn keine in der Schnittstelle definierte Methode garantiert einen NoApplicableMethods-Fehler auslöst, wenn sie auf eine Instanz dieser Klasse zu diesem Zeitpunkt angewendet wird.

Im normalen Gebrauch ist es jedoch "einfacher um Verzeihung zu bitten als um Erlaubnis". Das heißt, es ist einfacher, eine Schnittstelle auf einem Objekt zu verwenden, indem man es an die Schnittstelle anpasst (z. B. IStack(mylist)) oder Schnittstellenmethoden direkt aufruft (z. B. IStack.push(mylist, 42)), als zu versuchen herauszufinden, ob das Objekt an die Schnittstelle angepasst werden kann (oder sie direkt implementiert).

Implementierung einer Schnittstelle in einer Klasse

Es ist möglich zu deklarieren, dass eine Klasse eine Schnittstelle direkt implementiert, mithilfe der Funktion declare_implementation().

from overloading import declare_implementation

class Stack(object):
    def __init__(self):
        self.data = []
    def push(self, ob):
        self.data.append(ob)
    def pop(self):
        return self.data.pop()

declare_implementation(IStack, Stack)

Der obige Aufruf von declare_implementation() ist ungefähr gleichwertig mit folgenden Schritten:

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

Das heißt, der Aufruf von IStack.push() oder IStack.pop() auf einer Instanz einer beliebigen Unterklasse von Stack delegiert einfach an die tatsächlichen push()- oder pop()-Methoden davon.

Aus Effizienzgründen *kann* der Aufruf von IStack(s), wobei s eine Instanz von Stack ist, s zurückgeben und nicht einen IStack-Adapter. (Beachten Sie, dass der Aufruf von IStack(x), wobei x bereits ein IStack-Adapter ist, immer unverändert x zurückgibt; dies ist eine zusätzliche Optimierung, die in Fällen erlaubt ist, in denen das Adaptee bekanntermaßen die Schnittstelle *direkt* implementiert, ohne Anpassung.)

Der Bequemlichkeit halber kann es nützlich sein, Implementierungen im Klassenheader zu deklarieren, z. B.:

class Stack(metaclass=Implementer, implements=IStack):
    ...

Anstatt declare_implementation() nach dem Ende des Suites aufzurufen.

Schnittstellen als Typenspezifizierer

Interface-Unterklassen können als Argumentannotationen verwendet werden, um anzugeben, welche Art von Objekten von einer Überladung akzeptiert werden, z. B.:

@overload
def traverse(g: IGraph, s: IStack):
    g = IGraph(g)
    s = IStack(s)
    # etc....

Beachten Sie jedoch, dass die tatsächlichen Argumente durch die bloße Verwendung einer Schnittstelle als Typenspezifizierer *nicht* verändert oder angepasst werden. Sie müssen die Objekte explizit in die entsprechende Schnittstelle umwandeln, wie oben gezeigt.

Beachten Sie jedoch, dass andere Muster der Schnittstellenverwendung möglich sind. Andere Schnittstellenimplementierungen unterstützen möglicherweise keine Anpassung oder erfordern, dass Funktionsargumente bereits an die angegebene Schnittstelle angepasst sind. Die genauen Semantiken der Verwendung einer Schnittstelle als Typenspezifizierer hängen daher von den tatsächlich verwendeten Schnittstellenobjekten ab.

Für die von diesem PEP bereitgestellten Schnittstellenobjekte sind die Semantiken jedoch wie oben beschrieben. Eine Schnittstelle I1 gilt als "spezifischer" als eine andere Schnittstelle I2, wenn die Menge der Deskriptoren in der Vererbungshierarchie von I1 eine echte Obermenge der Deskriptoren in der Vererbungshierarchie von I2 ist.

Zum Beispiel ist ISizedStack spezifischer als sowohl ISizable als auch ISizedStack, unabhängig von den Vererbungsbeziehungen zwischen diesen Schnittstellen. Es ist reine Frage, welche Operationen innerhalb dieser Schnittstellen enthalten sind – und die *Namen* der Operationen sind unwichtig.

Schnittstellen (zumindest die von overloading bereitgestellten) gelten immer als weniger spezifisch als konkrete Klassen. Andere Schnittstellenimplementierungen können ihre eigenen Spezifitätsregeln festlegen, sowohl zwischen Schnittstellen und anderen Schnittstellen als auch zwischen Schnittstellen und Klassen.

Nicht-Methodenattribute in Schnittstellen

Die Interface-Implementierung behandelt tatsächlich alle Attribute und Methoden (d. h. Deskriptoren) auf die gleiche Weise: ihre __get__- (und __set__ und __delete__-, falls vorhanden) Methoden werden mit dem umschlossenen (angepassten) Objekt als "self" aufgerufen. Für Funktionen hat dies den Effekt, dass eine gebundene Methode erstellt wird, die die generische Funktion mit dem umschlossenen Objekt verknüpft.

Für Nicht-Funktionsattribute kann es am einfachsten sein, sie mit dem property-Built-in und den entsprechenden fget-, fset- und fdel-Attributen zu spezifizieren:

class ILength(Interface):
    @property
    @abstract
    def length(self):
        """Read-only length attribute"""

# ILength(aList).length == list.__len__(aList)
when(ILength.length.fget, (list,))(list.__len__)

Alternativ können Methoden wie _get_foo() und _set_foo() als Teil der Schnittstelle definiert und die Eigenschaft basierend auf diesen Methoden definiert werden, aber dies ist für Benutzer schwieriger korrekt zu implementieren, wenn sie eine Klasse erstellen, die die Schnittstelle direkt implementiert, da sie dann alle individuellen Methodennamen abgleichen müssten, nicht nur den Namen der Eigenschaft oder des Attributs.