Eine Anmerkung zu Zeichentypen

Im Allgemeinen befasst sich HTTP mit Bytes, was bedeutet, dass sich diese Spezifikation hauptsächlich mit der Handhabung von Bytes befasst.

Der Inhalt dieser Bytes hat jedoch oft eine Art textuelle Interpretation, und in Python sind Zeichenketten die bequemste Art, Text zu handhaben.

Aber in vielen Python-Versionen und Implementierungen sind Zeichenketten Unicode und keine Bytes. Dies erfordert ein sorgfältiges Gleichgewicht zwischen einer nutzbaren API und korrekten Übersetzungen zwischen Bytes und Text im Kontext von HTTP … insbesondere zur Unterstützung der Portierung von Code zwischen Python-Implementierungen mit unterschiedlichen str-Typen.

WSGI definiert daher zwei Arten von „Zeichenketten“

• „Native“ Zeichenketten (die immer mit dem Typ str implementiert werden) für Request-/Response-Header und Metadaten
• „Bytestrings“ (die in Python 3 mit dem Typ bytes und ansonsten mit str implementiert werden) für die Körper von Anfragen und Antworten (z. B. POST/PUT-Eingabedaten und HTML-Seiten-Ausgaben).

Lassen Sie sich jedoch nicht verwirren: Selbst wenn der str-Typ von Python tatsächlich Unicode „unter der Haube“ ist, muss der *Inhalt* von nativen Zeichenketten über die Latin-1-Kodierung in Bytes übersetzbar sein! (Siehe den Abschnitt über Unicode-Probleme später in diesem Dokument für weitere Details.)

Kurz gesagt: Wo Sie das Wort „Zeichenkette“ in diesem Dokument sehen, bezieht es sich auf eine „native“ Zeichenkette, d. h. ein Objekt vom Typ str, unabhängig davon, ob es intern als Bytes oder Unicode implementiert ist. Wo Sie auf „Bytestring“ verweisen, sollte dies als „ein Objekt vom Typ bytes unter Python 3 oder Typ str unter Python 2“ gelesen werden.

Und so gibt es, obwohl HTTP in gewissem Sinne „wirklich nur Bytes“ sind, viele API-Komfortfunktionen, die durch die Verwendung des Standard-Python-Typs str erzielt werden.

Die Anwendungs-/Framework-Seite

Das Anwendungsobjekt ist einfach ein aufrufbares Objekt, das zwei Argumente akzeptiert. Der Begriff „Objekt“ sollte nicht missverstanden werden als die Anforderung einer tatsächlichen Objektinstanz: Eine Funktion, Methode, Klasse oder Instanz mit einer __call__-Methode sind alle als Anwendungsobjekt geeignet. Anwendungsobjekte müssen mehrfach aufrufbar sein, da praktisch alle Server/Gateways (außer CGI) solche wiederholten Anfragen stellen werden.

(Hinweis: Obwohl wir uns auf ein „Anwendungs“-Objekt beziehen, sollte dies nicht so interpretiert werden, dass Anwendungsentwickler WSGI als Web-Programmier-API verwenden werden! Es wird davon ausgegangen, dass Anwendungsentwickler weiterhin bestehende, übergeordnete Framework-Dienste zur Entwicklung ihrer Anwendungen nutzen werden. WSGI ist ein Werkzeug für Framework- und Serverentwickler und nicht dazu gedacht, Anwendungsentwickler direkt zu unterstützen.)

Hier sind zwei Beispielanwendungsobjekte; eines ist eine Funktion und das andere eine Klasse

HELLO_WORLD = b"Hello world!\n"

def simple_app(environ, start_response):
    """Simplest possible application object"""
    status = '200 OK'
    response_headers = [('Content-type', 'text/plain')]
    start_response(status, response_headers)
    return [HELLO_WORLD]

class AppClass:
    """Produce the same output, but using a class

    (Note: 'AppClass' is the "application" here, so calling it
    returns an instance of 'AppClass', which is then the iterable
    return value of the "application callable" as required by
    the spec.

    If we wanted to use *instances* of 'AppClass' as application
    objects instead, we would have to implement a '__call__'
    method, which would be invoked to execute the application,
    and we would need to create an instance for use by the
    server or gateway.
    """

    def __init__(self, environ, start_response):
        self.environ = environ
        self.start = start_response

    def __iter__(self):
        status = '200 OK'
        response_headers = [('Content-type', 'text/plain')]
        self.start(status, response_headers)
        yield HELLO_WORLD

Die Server-/Gateway-Seite

Der Server oder das Gateway ruft das Anwendungs-Callable einmal pro empfangener Anfrage von einem HTTP-Client auf, die an die Anwendung gerichtet ist. Zur Veranschaulichung ist hier ein einfaches CGI-Gateway, implementiert als Funktion, die ein Anwendungsobjekt entgegennimmt. Beachten Sie, dass dieses einfache Beispiel eine eingeschränkte Fehlerbehandlung aufweist, da eine nicht abgefangene Ausnahme standardmäßig nach sys.stderr ausgegeben und vom Webserver protokolliert wird.

import os, sys

enc, esc = sys.getfilesystemencoding(), 'surrogateescape'

def unicode_to_wsgi(u):
    # Convert an environment variable to a WSGI "bytes-as-unicode" string
    return u.encode(enc, esc).decode('iso-8859-1')

def wsgi_to_bytes(s):
    return s.encode('iso-8859-1')

def run_with_cgi(application):
    environ = {k: unicode_to_wsgi(v) for k,v in os.environ.items()}
    environ['wsgi.input']        = sys.stdin.buffer
    environ['wsgi.errors']       = sys.stderr
    environ['wsgi.version']      = (1, 0)
    environ['wsgi.multithread']  = False
    environ['wsgi.multiprocess'] = True
    environ['wsgi.run_once']     = True

    if environ.get('HTTPS', 'off') in ('on', '1'):
        environ['wsgi.url_scheme'] = 'https'
    else:
        environ['wsgi.url_scheme'] = 'http'

    headers_set = []
    headers_sent = []

    def write(data):
        out = sys.stdout.buffer

        if not headers_set:
             raise AssertionError("write() before start_response()")

        elif not headers_sent:
             # Before the first output, send the stored headers
             status, response_headers = headers_sent[:] = headers_set
             out.write(wsgi_to_bytes('Status: %s\r\n' % status))
             for header in response_headers:
                 out.write(wsgi_to_bytes('%s: %s\r\n' % header))
             out.write(wsgi_to_bytes('\r\n'))

        out.write(data)
        out.flush()

    def start_response(status, response_headers, exc_info=None):
        if exc_info:
            try:
                if headers_sent:
                    # Re-raise original exception if headers sent
                    raise exc_info[1].with_traceback(exc_info[2])
            finally:
                exc_info = None     # avoid dangling circular ref
        elif headers_set:
            raise AssertionError("Headers already set!")

        headers_set[:] = [status, response_headers]

        # Note: error checking on the headers should happen here,
        # *after* the headers are set.  That way, if an error
        # occurs, start_response can only be re-called with
        # exc_info set.

        return write

    result = application(environ, start_response)
    try:
        for data in result:
            if data:    # don't send headers until body appears
                write(data)
        if not headers_sent:
            write(b'')   # send headers now if body was empty
    finally:
        if hasattr(result, 'close'):
            result.close()

Middleware: Komponenten, die beide Seiten bespielen

Beachten Sie, dass ein einzelnes Objekt die Rolle eines Servers gegenüber einigen Anwendungen spielen kann und gleichzeitig als Anwendung gegenüber einigen Servern fungieren kann. Solche „Middleware“-Komponenten können Funktionen wie die folgenden ausführen:

• Weiterleitung einer Anfrage an verschiedene Anwendungsobjekte basierend auf der Ziel-URL, nachdem die environ entsprechend umgeschrieben wurde.
• Mehrere Anwendungen oder Frameworks nebeneinander im selben Prozess ausführen lassen
• Lastverteilung und Remote-Verarbeitung durch Weiterleitung von Anfragen und Antworten über ein Netzwerk
• Inhaltsnachbearbeitung durchführen, z. B. Anwenden von XSL-Stylesheets

Die Anwesenheit von Middleware im Allgemeinen ist für die „Server/Gateway“- und die „Anwendungs/Framework“-Seiten der Schnittstelle transparent und erfordert keine spezielle Unterstützung. Ein Benutzer, der Middleware in eine Anwendung integrieren möchte, stellt die Middleware-Komponente einfach dem Server zur Verfügung, als wäre sie eine Anwendung, und konfiguriert die Middleware-Komponente so, dass sie die Anwendung aufruft, als wäre die Middleware-Komponente ein Server. Natürlich kann die „Anwendung“, die die Middleware umschließt, tatsächlich eine weitere Middleware-Komponente sein, die eine weitere Anwendung umschließt, und so weiter, wodurch ein sogenannter „Middleware-Stack“ entsteht.

Größtenteils muss Middleware den Beschränkungen und Anforderungen sowohl der Server- als auch der Anwendungsseite von WSGI entsprechen. In einigen Fällen sind die Anforderungen an Middleware jedoch strenger als für einen „reinen“ Server oder eine Anwendung, und diese Punkte werden in der Spezifikation vermerkt.

Hier ist ein (augenscheinlich ironisches) Beispiel für eine Middleware-Komponente, die text/plain-Antworten in Pig Latin umwandelt, unter Verwendung von Joe Strouts piglatin.py. (Hinweis: Eine „echte“ Middleware-Komponente würde wahrscheinlich eine robustere Methode zur Überprüfung des Inhaltstyps verwenden und auch eine Inhaltskodierung prüfen. Außerdem ignoriert dieses einfache Beispiel die Möglichkeit, dass ein Wort über eine Blockgrenze geteilt werden könnte.)

from piglatin import piglatin

class LatinIter:

    """Transform iterated output to piglatin, if it's okay to do so

    Note that the "okayness" can change until the application yields
    its first non-empty bytestring, so 'transform_ok' has to be a mutable
    truth value.
    """

    def __init__(self, result, transform_ok):
        if hasattr(result, 'close'):
            self.close = result.close
        self._next = iter(result).__next__
        self.transform_ok = transform_ok

    def __iter__(self):
        return self

    def __next__(self):
        data = self._next()
        if self.transform_ok:
            return piglatin(data)   # call must be byte-safe on Py3
        else:
            return data

class Latinator:

    # by default, don't transform output
    transform = False

    def __init__(self, application):
        self.application = application

    def __call__(self, environ, start_response):

        transform_ok = []

        def start_latin(status, response_headers, exc_info=None):

            # Reset ok flag, in case this is a repeat call
            del transform_ok[:]

            for name, value in response_headers:
                if name.lower() == 'content-type' and value == 'text/plain':
                    transform_ok.append(True)
                    # Strip content-length if present, else it'll be wrong
                    response_headers = [(name, value)
                        for name, value in response_headers
                            if name.lower() != 'content-length'
                    ]
                    break

            write = start_response(status, response_headers, exc_info)

            if transform_ok:
                def write_latin(data):
                    write(piglatin(data))   # call must be byte-safe on Py3
                return write_latin
            else:
                return write

        return LatinIter(self.application(environ, start_latin), transform_ok)


# Run foo_app under a Latinator's control, using the example CGI gateway
from foo_app import foo_app
run_with_cgi(Latinator(foo_app))

environ-Variablen

Das environ-Wörterbuch muss diese CGI-Umgebungsvariablen enthalten, wie in der Common Gateway Interface-Spezifikation [2] definiert. Die folgenden Variablen **müssen** vorhanden sein, es sei denn, ihr Wert wäre eine leere Zeichenkette, in welchem Fall sie **weggelassen werden dürfen**, außer wie unten anders angegeben.

REQUEST_METHOD

Die HTTP-Anfragemethode, wie z. B. "GET" oder "POST". Dies kann niemals eine leere Zeichenkette sein und ist daher immer erforderlich.

SCRIPT_NAME

Der Anfangsteil des „path“-Segments der Anforderungs-URL, das dem Anwendungsobjekt entspricht, damit die Anwendung seine virtuelle „Position“ kennt. Dies **kann** eine leere Zeichenkette sein, wenn die Anwendung dem „Root“ des Servers entspricht.

PATH_INFO

Der Rest des „path“-Segments der Anforderungs-URL, der die virtuelle „Position“ des Ziels der Anfrage innerhalb der Anwendung bezeichnet. Dies **kann** eine leere Zeichenkette sein, wenn die Anforderungs-URL auf das Anwendungs-Root zielt und keinen nachgestellten Schrägstrich hat.

QUERY_STRING

Der Teil der Anforderungs-URL, der auf das "?" folgt, falls vorhanden. Kann leer oder abwesend sein.

CONTENT_TYPE

Der Inhalt aller Content-Type-Felder in der HTTP-Anfrage. Kann leer oder abwesend sein.

CONTENT_LENGTH

Der Inhalt aller Content-Length-Felder in der HTTP-Anfrage. Kann leer oder abwesend sein.

SERVER_NAME, SERVER_PORT

Wenn HTTP_HOST nicht gesetzt ist, können diese Variablen kombiniert werden, um einen Standardwert zu ermitteln. Siehe den Abschnitt URL-Rekonstruktion unten für weitere Details. SERVER_NAME und SERVER_PORT sind erforderliche Zeichenketten und dürfen niemals leer sein.

SERVER_PROTOCOL

Die Version des Protokolls, das der Client zum Senden der Anfrage verwendet hat. Typischerweise ist dies etwas wie "HTTP/1.0" oder "HTTP/1.1" und kann von der Anwendung verwendet werden, um zu bestimmen, wie HTTP-Anfrage-Header behandelt werden sollen. (Diese Variable sollte wahrscheinlich REQUEST_PROTOCOL genannt werden, da sie das in der Anfrage verwendete Protokoll bezeichnet und nicht notwendigerweise das Protokoll ist, das in der Antwort des Servers verwendet wird. Aus Kompatibilitätsgründen mit CGI müssen wir jedoch den bestehenden Namen beibehalten.)

HTTP_-Variablen

Variablen, die den vom Client bereitgestellten HTTP-Anfrage-Headern entsprechen (d. h. Variablen, deren Namen mit "HTTP_" beginnen). Das Vorhandensein oder Fehlen dieser Variablen sollte dem Vorhandensein oder Fehlen des entsprechenden HTTP-Headers in der Anfrage entsprechen.

Ein Server oder Gateway **sollte** versuchen, so viele andere CGI-Variablen wie anwendbar bereitzustellen. Zusätzlich, wenn SSL verwendet wird, **sollte** der Server oder Gateway auch so viele der Apache SSL-Umgebungsvariablen [5] wie anwendbar bereitstellen, wie z. B. HTTPS=on und SSL_PROTOCOL. Beachten Sie jedoch, dass eine Anwendung, die andere CGI-Variablen als die oben aufgeführten verwendet, zwangsläufig nicht portierbar zu Webservern ist, die die relevanten Erweiterungen nicht unterstützen. (Zum Beispiel können Webserver, die keine Dateien veröffentlichen, kein aussagekräftiges DOCUMENT_ROOT oder PATH_TRANSLATED bereitstellen.)

Ein WSGI-konformer Server oder Gateway **sollte** dokumentieren, welche Variablen er bereitstellt, zusammen mit ihren Definitionen, wo dies angemessen ist. Anwendungen **sollten** auf die Anwesenheit jeder von ihnen benötigten Variablen prüfen und einen Fallback-Plan haben, falls eine solche Variable fehlt.

Hinweis: Fehlende Variablen (wie z. B. REMOTE_USER, wenn keine Authentifizierung stattgefunden hat) sollten aus dem environ-Wörterbuch weggelassen werden. Beachten Sie auch, dass CGI-definierte Variablen native Zeichenketten sein müssen, wenn sie überhaupt vorhanden sind. Es verstößt gegen diese Spezifikation, wenn der Wert *irgendeiner* CGI-Variablen einen anderen Typ als str hat.

Zusätzlich zu den CGI-definierten Variablen **kann** das environ-Wörterbuch auch beliebige „Umgebungsvariablen“ des Betriebssystems enthalten, und **muss** die folgenden WSGI-definierten Variablen enthalten:

Schließlich **kann** das environ-Wörterbuch auch serverspezifische Variablen enthalten. Diese Variablen sollten nur Kleinbuchstaben, Zahlen, Punkte und Unterstriche enthalten und mit einem Namen präfixiert sein, der für den definierenden Server oder das Gateway eindeutig ist. Zum Beispiel könnte mod_python Variablen mit Namen wie mod_python.some_variable definieren.

Der start_response() Callable

Der zweite Parameter, der an das Anwendungsobjekt übergeben wird, ist ein aufrufbares Objekt der Form start_response(status, response_headers, exc_info=None). (Wie bei allen WSGI-Aufrufobjekten müssen die Argumente positionsweise, nicht per Schlüsselwort übergeben werden.) Der start_response Callable wird verwendet, um die HTTP-Antwort zu beginnen, und er muss einen write(body_data) Callable zurückgeben (siehe den Abschnitt Pufferung und Streaming unten).

Das Argument status ist ein HTTP-„Status“-String wie "200 OK" oder "404 Not Found". Das heißt, es ist eine Zeichenkette, die aus einem Status-Code und einer Grund-Phrase besteht, in dieser Reihenfolge und durch ein einzelnes Leerzeichen getrennt, ohne umschließende Leerzeichen oder andere Zeichen. (Siehe RFC 2616, Abschnitt 6.1.1 für weitere Informationen.) Die Zeichenkette **darf keine** Steuerzeichen enthalten und **darf nicht** mit einem Wagenrücklauf, Zeilenvorschub oder einer Kombination davon abgeschlossen werden.

Das Argument response_headers ist eine Liste von Tupeln (header_name, header_value). Es muss eine Python-Liste sein; d. h. type(response_headers) is ListType, und der Server **darf** ihren Inhalt beliebig ändern. Jeder header_name muss ein gültiger HTTP-Headerfeldname sein (wie definiert in RFC 2616, Abschnitt 4.2), ohne einen nachgestellten Doppelpunkt oder andere Satzzeichen.

Jeder header_value **darf keine** *irgendwelchen* Steuerzeichen enthalten, einschließlich Wagenrückläufen oder Zeilenumbrüchen, weder eingebettet noch am Ende. (Diese Anforderungen dienen der Minimierung der Komplexität von Parsing-Vorgängen, die von Servern, Gateways und Zwischenantwortprozessoren durchgeführt werden müssen, die Antwortheader inspizieren oder ändern müssen.)

Im Allgemeinen ist der Server oder das Gateway dafür verantwortlich, sicherzustellen, dass die korrekten Header an den Client gesendet werden: Wenn die Anwendung einen von HTTP (oder anderen relevanten, geltenden Spezifikationen) geforderten Header weglässt, **muss** der Server oder das Gateway ihn hinzufügen. Zum Beispiel würden die HTTP-Header Date: und Server: normalerweise vom Server oder Gateway bereitgestellt werden.

(Eine Erinnerung für Server/Gateway-Autoren: HTTP-Header-Namen sind nicht case-sensitiv, also stellen Sie sicher, dass Sie das bei der Überprüfung anwendungsseitig bereitgestellter Header berücksichtigen!)

Anwendungen und Middleware dürfen keine HTTP/1.1 „Hop-by-Hop“-Funktionen oder Header, keine gleichwertigen Funktionen in HTTP/1.0 oder keine Header verwenden, die die Persistenz der Client-Verbindung zum Webserver beeinträchtigen würden. Diese Funktionen sind das ausschließliche Territorium des tatsächlichen Webservers, und ein Server oder Gateway **sollte** es als fatalen Fehler betrachten, wenn eine Anwendung versucht, diese zu senden, und einen Fehler auslösen, wenn sie an start_response() übergeben werden. (Weitere Details zu „Hop-by-Hop“-Funktionen und -Headern finden Sie im Abschnitt Andere HTTP-Funktionen unten.)

Server **sollten** zum Zeitpunkt des Aufrufs von start_response auf Fehler in den Headern prüfen, damit ein Fehler ausgelöst werden kann, während die Anwendung noch läuft.

Die start_response aufrufbare Funktion **darf** die Antwort-Header jedoch nicht tatsächlich übertragen. Stattdessen muss sie diese für den Server oder das Gateway speichern, um sie **erst** nach der ersten Iteration des Rückgabewerts der Anwendung, der eine nicht leere Bytestring liefert, oder bei der ersten Ausführung des write() aufrufbaren Objekts durch die Anwendung zu übertragen. Mit anderen Worten, die Antwort-Header dürfen nicht gesendet werden, bis tatsächliche Body-Daten verfügbar sind oder bis das von der Anwendung zurückgegebene Iterable erschöpft ist. (Die einzige mögliche Ausnahme von dieser Regel ist, wenn die Antwort-Header explizit eine Content-Length von Null enthalten.)

Diese Verzögerung bei der Übertragung der Antwort-Header soll sicherstellen, dass gepufferte und asynchrone Anwendungen ihre ursprünglich beabsichtigte Ausgabe bis zum letzten möglichen Moment durch eine Fehlerausgabe ersetzen können. Beispielsweise muss die Anwendung möglicherweise den Antwortstatus von „200 OK“ auf „500 Internal Error“ ändern, wenn während der Generierung des Bodys in einem Anwendungspuffer ein Fehler auftritt.

Das Argument exc_info muss, wenn es übergeben wird, ein Python sys.exc_info() Tupel sein. Dieses Argument sollte nur dann von der Anwendung übergeben werden, wenn start_response von einem Fehlerbehandlungsroutine aufgerufen wird. Wenn exc_info übergeben wird und noch keine HTTP-Header ausgegeben wurden, sollte start_response die aktuell gespeicherten HTTP-Antwort-Header durch die neu übergebenen ersetzen, wodurch die Anwendung ihre Meinung über die Ausgabe ändern kann, wenn ein Fehler aufgetreten ist.

Wenn jedoch exc_info übergeben wird und die HTTP-Header bereits gesendet wurden, **muss** start_response einen Fehler auslösen und **sollte** diesen unter Verwendung des exc_info Tupels erneut auslösen. Das heißt

raise exc_info[1].with_traceback(exc_info[2])

Dies wird die vom Anwendung abgefangene Ausnahme erneut auslösen und sollte grundsätzlich die Anwendung abbrechen. (Es ist für die Anwendung nicht sicher, zu versuchen, eine Fehlerausgabe an den Browser zu senden, sobald die HTTP-Header bereits gesendet wurden.) Die Anwendung **darf** keine Ausnahmen abfangen, die von start_response ausgelöst werden, wenn sie start_response mit exc_info aufgerufen hat. Stattdessen sollte sie zulassen, dass solche Ausnahmen an den Server oder das Gateway zurückpropagieren. Siehe Fehlerbehandlung unten für weitere Details.

Die Anwendung **darf** start_response mehr als einmal aufrufen, wenn und nur wenn das Argument exc_info übergeben wird. Genauer gesagt ist es ein fataler Fehler, start_response ohne das Argument exc_info aufzurufen, wenn start_response bereits innerhalb des aktuellen Aufrufs der Anwendung aufgerufen wurde. Dies schließt den Fall ein, dass der erste Aufruf von start_response einen Fehler ausgelöst hat. (Siehe das Beispiel eines CGI-Gateways oben zur Veranschaulichung der korrekten Logik.)

Hinweis: Server, Gateways oder Middleware, die start_response implementieren, **sollten** sicherstellen, dass keine Referenz auf den Parameter exc_info über die Dauer der Funktionsausführung hinaus gehalten wird, um eine zirkuläre Referenz durch den Traceback und die beteiligten Frames zu vermeiden. Der einfachste Weg, dies zu tun, ist etwa so:

def start_response(status, response_headers, exc_info=None):
    if exc_info:
         try:
             # do stuff w/exc_info here
         finally:
             exc_info = None    # Avoid circular ref.

Das Beispiel eines CGI-Gateways liefert eine weitere Veranschaulichung dieser Technik.

Puffern und Streaming

Im Allgemeinen erzielen Anwendungen den besten Durchsatz, indem sie ihre (moderat großen) Ausgaben puffern und sie alle auf einmal senden. Dies ist ein gängiger Ansatz in bestehenden Frameworks wie Zope: Die Ausgabe wird in einem StringIO-Objekt oder einem ähnlichen Objekt gepuffert, dann auf einmal zusammen mit den Antwort-Headern übertragen.

Der entsprechende Ansatz in WSGI besteht darin, dass die Anwendung einfach ein Iterable mit einem einzigen Element (wie z. B. einer Liste) zurückgibt, das den Antwort-Body als einzelne Bytestring enthält. Dies ist der empfohlene Ansatz für die überwiegende Mehrheit der Anwendungsfunktionen, die HTML-Seiten rendern, deren Text leicht in den Speicher passt.

Für große Dateien oder für spezialisierte Anwendungen von HTTP-Streaming (wie z. B. Multipart "Server Push") muss eine Anwendung jedoch möglicherweise die Ausgabe in kleineren Blöcken bereitstellen (z. B. um zu vermeiden, eine große Datei in den Speicher zu laden). Es kommt auch manchmal vor, dass die Erstellung eines Teils einer Antwort zeitaufwändig ist, aber es wäre nützlich, den Teil der Antwort, der davor liegt, vorab zu senden.

In diesen Fällen gibt die Anwendung normalerweise ein Iterator (oft ein Generator-Iterator) zurück, der die Ausgabe blockweise erzeugt. Diese Blöcke können unterbrochen werden, um mit Multipart-Grenzen (für „Server Push“) zusammenzufallen, oder kurz vor zeitaufwändigen Aufgaben (wie dem Lesen eines weiteren Blocks einer Datei auf der Festplatte).

WSGI-Server, Gateways und Middleware **dürfen** die Übertragung eines Blocks nicht verzögern; sie **müssen** entweder den Block vollständig an den Client übertragen oder garantieren, dass sie die Übertragung fortsetzen, auch während die Anwendung ihren nächsten Block erzeugt. Ein Server/Gateway oder eine Middleware kann diese Garantie auf eine von drei Arten bieten:

1. Den gesamten Block an das Betriebssystem senden (und anfordern, dass alle Puffer des Betriebssystems geleert werden), bevor die Kontrolle an die Anwendung zurückgegeben wird, ODER
2. Einen anderen Thread verwenden, um sicherzustellen, dass die Übertragung des Blocks fortgesetzt wird, während die Anwendung den nächsten Block generiert.
3. (Nur Middleware) den gesamten Block an sein übergeordnetes Gateway/Server senden

Durch die Bereitstellung dieser Garantie ermöglicht WSGI Anwendungen, sicherzustellen, dass die Übertragung nicht an einer beliebigen Stelle ihrer Ausgabedaten ins Stocken gerät. Dies ist entscheidend für die ordnungsgemäße Funktion von z. B. Streaming mit „Server Push“ über Multipart, wo Daten zwischen Multipart-Grenzen vollständig an den Client übertragen werden sollten.

Unicode-Probleme

HTTP unterstützt Unicode nicht direkt, und diese Schnittstelle auch nicht. Alle Kodierungen/Dekodierungen müssen von der Anwendung gehandhabt werden; alle an den Server oder von ihm übergebenen Zeichenfolgen müssen vom Typ str oder bytes sein, niemals unicode. Das Ergebnis der Verwendung eines unicode-Objekts, wo ein Zeichenkettenobjekt erforderlich ist, ist undefiniert.

Beachten Sie auch, dass Zeichenketten, die als Status oder als Antwort-Header an start_response() übergeben werden, **gemäß** RFC 2616 mit Bezug auf die Kodierung sein müssen. Das heißt, sie müssen entweder ISO-8859-1-Zeichen sein oder die RFC 2047 MIME-Kodierung verwenden.

Auf Python-Plattformen, auf denen der Typ str oder StringType tatsächlich Unicode-basiert ist (z. B. Jython, IronPython, Python 3 usw.), müssen alle in dieser Spezifikation als „Zeichenketten“ bezeichneten Zeichen nur Code-Punkte enthalten, die in der ISO-8859-1-Kodierung darstellbar sind (\u0000 bis \u00FF, einschließlich). Es ist ein fataler Fehler für eine Anwendung, Zeichenketten mit anderen Unicode-Zeichen oder Code-Punkten zu übergeben. Ebenso **dürfen** Server und Gateways keine Zeichenketten an eine Anwendung übergeben, die andere Unicode-Zeichen enthalten.

Nochmal, alle in dieser Spezifikation als „Zeichenketten“ bezeichneten Objekte **müssen** vom Typ str oder StringType sein und **dürfen nicht** vom Typ unicode oder UnicodeType sein. Und selbst wenn eine gegebene Plattform mehr als 8 Bit pro Zeichen in str/StringType Objekten zulässt, dürfen nur die unteren 8 Bit für jeden Wert verwendet werden, der in dieser Spezifikation als „Zeichenkette“ bezeichnet wird.

Für Werte, die in dieser Spezifikation als „Bytestrings“ bezeichnet werden (d. h. Werte, die aus wsgi.input gelesen, an write() übergeben oder von der Anwendung geliefert werden), **muss** der Wert vom Typ bytes unter Python 3 und str in früheren Versionen von Python sein.

Fehlerbehandlung

Im Allgemeinen **sollten** Anwendungen versuchen, ihre eigenen internen Fehler abzufangen und eine hilfreiche Nachricht im Browser anzuzeigen. (Es liegt an der Anwendung zu entscheiden, was „hilfreich“ in diesem Kontext bedeutet.)

Um eine solche Nachricht anzuzeigen, darf die Anwendung jedoch noch keine Daten an den Browser gesendet haben, sonst riskiert sie, die Antwort zu beschädigen. WSGI stellt daher einen Mechanismus zur Verfügung, um der Anwendung entweder zu ermöglichen, ihre Fehlermeldung zu senden, oder automatisch abgebrochen zu werden: das Argument exc_info für start_response. Hier ist ein Beispiel für seine Verwendung:

try:
    # regular application code here
    status = "200 Froody"
    response_headers = [("content-type", "text/plain")]
    start_response(status, response_headers)
    return ["normal body goes here"]
except:
    # XXX should trap runtime issues like MemoryError, KeyboardInterrupt
    #     in a separate handler before this bare 'except:'...
    status = "500 Oops"
    response_headers = [("content-type", "text/plain")]
    start_response(status, response_headers, sys.exc_info())
    return ["error body goes here"]

Wenn beim Auftreten einer Ausnahme keine Ausgabe geschrieben wurde, gibt der Aufruf von start_response normal zurück, und die Anwendung gibt einen Fehler-Body zurück, der an den Browser gesendet wird. Wenn jedoch bereits eine Ausgabe an den Browser gesendet wurde, wird start_response die bereitgestellte Ausnahme erneut auslösen. Diese Ausnahme **sollte nicht** von der Anwendung abgefangen werden, und so wird die Anwendung abgebrochen. Der Server oder das Gateway kann dann diese (fatale) Ausnahme abfangen und die Antwort abbrechen.

Server **sollten** jede Ausnahme abfangen und protokollieren, die eine Anwendung oder die Iteration ihres Rückgabewerts abbricht. Wenn bereits eine teilweise Antwort an den Browser gesendet wurde, wenn ein Anwendungsfehler auftritt, **kann** der Server oder das Gateway versuchen, eine Fehlermeldung zur Ausgabe hinzuzufügen, wenn die bereits gesendeten Header einen text/* Inhaltstyp angeben, den der Server sauber modifizieren kann.

Einige Middleware möchten möglicherweise zusätzliche Fehlerbehandlungsdienste anbieten oder Anwendungsfehlermeldungen abfangen und ersetzen. In solchen Fällen kann die Middleware wählen, die an start_response übergebene exc_info **nicht** erneut auszulösen, sondern stattdessen eine Middleware-spezifische Ausnahme auszulösen oder einfach ohne Ausnahme zurückzukehren, nachdem die übergebenen Argumente gespeichert wurden. Dies führt dann dazu, dass die Anwendung ihr Fehler-Body-Iterable zurückgibt (oder write() aufruft), was es der Middleware ermöglicht, die Fehlerausgabe zu erfassen und zu modifizieren. Diese Techniken funktionieren, solange die Anwendungsautoren

1. Immer exc_info bereitstellen, wenn eine Fehlerantwort begonnen wird
2. Niemals Fehler abfangen, die von start_response ausgelöst werden, wenn exc_info bereitgestellt wird

HTTP 1.1 Expect/Continue

Server und Gateways, die HTTP 1.1 implementieren, müssen transparente Unterstützung für den "Expect/Continue"-Mechanismus von HTTP 1.1 bieten. Dies kann auf verschiedene Arten erfolgen:

1. Auf Anfragen mit Expect: 100-continue mit einer sofortigen "100 Continue"-Antwort reagieren und normal fortfahren.
2. Fahren Sie mit der Anfrage normal fort, stellen Sie der Anwendung jedoch einen wsgi.input Stream zur Verfügung, der die Antwort „100 Continue“ sendet, wenn/wenn die Anwendung zum ersten Mal aus dem Eingabestrom liest. Die Leseanfrage muss dann blockiert bleiben, bis der Client antwortet.
3. Warten, bis der Client entscheidet, dass der Server Expect/Continue nicht unterstützt und den Anfrage-Body selbst sendet. (Dies ist suboptimal und nicht empfehlenswert.)

Beachten Sie, dass diese Verhaltensbeschränkungen nicht für HTTP 1.0-Anfragen oder für Anfragen gelten, die nicht an ein Anwendungsobjekt gerichtet sind. Weitere Informationen zu HTTP 1.1 Expect/Continue finden Sie in RFC 2616, Abschnitte 8.2.3 und 10.1.1.

Andere HTTP-Funktionen

Im Allgemeinen sollten Server und Gateways „dumm spielen“ und der Anwendung die volle Kontrolle über ihre Ausgabe überlassen. Sie sollten nur Änderungen vornehmen, die die effektive Semantik der Anwendungsantwort nicht verändern. Es ist immer möglich, dass der Anwendungsentwickler Middleware-Komponenten hinzufügt, um zusätzliche Funktionen bereitzustellen, sodass Server-/Gateway-Entwickler bei ihrer Implementierung konservativ vorgehen sollten. In gewissem Sinne sollte sich ein Server wie ein HTTP-„Gateway-Server“ betrachten, wobei die Anwendung ein HTTP-„Origin-Server“ ist. (Siehe RFC 2616, Abschnitt 1.3, für die Definition dieser Begriffe.)

Da WSGI-Server und -Anwendungen jedoch nicht über HTTP kommunizieren, gelten die in RFC 2616 als „Hop-by-Hop“-Header bezeichneten Header nicht für die interne WSGI-Kommunikation. WSGI-Anwendungen **dürfen keine** „Hop-by-Hop“-Header generieren, keine HTTP-Funktionen verwenden, die sie zur Generierung solcher Header erfordern würden, oder sich auf den Inhalt eingehender „Hop-by-Hop“-Header im environ-Wörterbuch verlassen. WSGI-Server **müssen** unterstützte eingehende „Hop-by-Hop“-Header selbst verarbeiten, z. B. durch Dekodierung jeder eingehenden Transfer-Encoding, einschließlich Chunked Encoding, falls zutreffend.

Wenn man diese Prinzipien auf eine Vielzahl von HTTP-Features anwendet, sollte klar sein, dass ein Server die Cache-Validierung über die If-None-Match und If-Modified-Since-Anfrageheader und die Last-Modified und ETag-Antwortheader handhaben kann. Dies ist jedoch nicht erforderlich, und die Anwendung sollte ihre eigene Cache-Validierung durchführen, wenn sie diese Funktion unterstützen möchte, da der Server/Gateway eine solche Validierung nicht durchführen muss.

Ähnlich kann ein Server die Antwort einer Anwendung neu kodieren oder transportkodieren, aber die Anwendung sollte selbst eine geeignete Inhaltskodierung verwenden und darf keine Transportkodierung anwenden. Ein Server kann Byte-Bereiche der Antwort der Anwendung übertragen, wenn diese vom Client angefordert werden und die Anwendung Byte-Bereiche nicht nativ unterstützt. Auch hier sollte die Anwendung diese Funktion jedoch selbst durchführen, wenn gewünscht.

Beachten Sie, dass diese Einschränkungen für Anwendungen nicht unbedingt bedeuten, dass jede Anwendung jede HTTP-Funktion neu implementieren muss; viele HTTP-Funktionen können teilweise oder vollständig von Middleware-Komponenten implementiert werden, wodurch sowohl Server- als auch Anwendungsautoren von der wiederholten Implementierung derselben Funktionen befreit werden.

Thread-Unterstützung

Die Thread-Unterstützung oder deren Fehlen ist ebenfalls serverabhängig. Server, die mehrere Anfragen parallel ausführen können, sollten auch die Option bieten, eine Anwendung im Single-Thread-Modus auszuführen, damit Anwendungen oder Frameworks, die nicht Thread-sicher sind, auch mit diesem Server verwendet werden können.

Server-Erweiterungs-APIs

Einige Serverautoren möchten möglicherweise erweiterte APIs bereitstellen, die Anwendungs- oder Framework-Autoren für spezielle Zwecke verwenden können. Beispielsweise könnte ein Gateway, das auf mod_python basiert, einen Teil der Apache-API als WSGI-Erweiterung freigeben.

Im einfachsten Fall erfordert dies nichts weiter als die Definition einer environ-Variablen, z. B. mod_python.some_api. In vielen Fällen kann die mögliche Anwesenheit von Middleware dies jedoch erschweren. Beispielsweise könnte eine API, die Zugriff auf dieselben HTTP-Header bietet, wie sie in environ-Variablen zu finden sind, andere Daten zurückgeben, wenn environ von Middleware geändert wurde.

Im Allgemeinen laufen Erweiterungs-APIs, die die Funktionalität von WSGI duplizieren, ersetzen oder umgehen, Gefahr, mit Middleware-Komponenten inkompatibel zu sein. Server-/Gateway-Entwickler sollten *nicht* davon ausgehen, dass niemand Middleware verwenden wird, da einige Framework-Entwickler explizit beabsichtigen, ihre Frameworks so zu organisieren oder neu zu organisieren, dass sie fast ausschließlich als Middleware verschiedener Arten fungieren.

Um maximale Kompatibilität zu gewährleisten, **müssen** Server und Gateways, die Erweiterungs-APIs bereitstellen, die eine WSGI-Funktionalität ersetzen, diese APIs so gestalten, dass sie mit dem Teil der API aufgerufen werden, den sie ersetzen. Zum Beispiel muss eine Erweiterungs-API zum Zugriff auf HTTP-Anfrage-Header erfordern, dass die Anwendung ihre aktuelle environ übergibt, damit der Server/Gateway überprüfen kann, ob über die API zugängliche HTTP-Header nicht von Middleware geändert wurden. Wenn die Erweiterungs-API nicht garantieren kann, dass sie immer mit environ über den Inhalt von HTTP-Headern übereinstimmt, muss sie die Dienstleistung für die Anwendung verweigern, z. B. durch Auslösen eines Fehlers, Rückgabe von None anstelle einer Header-Sammlung oder was auch immer für die API angemessen ist.

Ähnlich verhält es sich, wenn eine Erweiterungs-API einen alternativen Weg zum Schreiben von Antwortdaten oder Headern bietet, sollte sie den start_response aufrufbaren übergeben, bevor die Anwendung den erweiterten Dienst erhalten kann. Wenn das übergebene Objekt nicht dasselbe ist, das der Server/Gateway ursprünglich der Anwendung zur Verfügung gestellt hat, kann er keine korrekte Funktion garantieren und muss sich weigern, den erweiterten Dienst der Anwendung zur Verfügung zu stellen.

Diese Richtlinien gelten auch für Middleware, die Informationen wie geparste Cookies, Formulardaten, Sitzungen und dergleichen zu environ hinzufügt. Insbesondere sollte solche Middleware diese Funktionen als Funktionen bereitstellen, die auf environ operieren, anstatt Werte einfach in environ zu stopfen. Dies trägt dazu bei, dass Informationen aus environ berechnet werden, nachdem jede Middleware URL-Rewrites oder andere environ-Änderungen vorgenommen hat.

Es ist sehr wichtig, dass diese "sicheren Erweiterungsregeln" sowohl von Server-/Gateway- als auch von Middleware-Entwicklern befolgt werden, um eine Zukunft zu vermeiden, in der Middleware-Entwickler gezwungen sind, alle Erweiterungs-APIs aus environ zu löschen, um sicherzustellen, dass ihre Vermittlung nicht von Anwendungen umgangen wird, die diese Erweiterungen nutzen!

Anwendungskonfiguration

Diese Spezifikation definiert nicht, wie ein Server eine Anwendung auswählt oder erhält, um sie aufzurufen. Dies und andere Konfigurationsoptionen sind sehr serverspezifische Angelegenheiten. Es wird erwartet, dass Server-/Gateway-Autoren dokumentieren, wie der Server für die Ausführung eines bestimmten Anwendungsobjekts konfiguriert wird und mit welchen Optionen (wie Threading-Optionen).

Framework-Autoren hingegen sollten dokumentieren, wie ein Anwendungsobjekt erstellt wird, das die Funktionalität ihres Frameworks umschließt. Der Benutzer, der sowohl den Server als auch das Anwendungsframework gewählt hat, muss die beiden miteinander verbinden. Da jedoch sowohl das Framework als auch der Server nun eine gemeinsame Schnittstelle haben, sollte dies lediglich eine mechanische Angelegenheit sein und kein erheblicher Entwicklungsaufwand für jedes neue Server-/Framework-Paar.

Schließlich möchten einige Anwendungen, Frameworks und Middleware möglicherweise das environ-Dictionary verwenden, um einfache String-Konfigurationsoptionen zu empfangen. Server und Gateways sollten dies unterstützen, indem sie es dem Bereitsteller einer Anwendung ermöglichen, Namens-Wert-Paare anzugeben, die in environ eingefügt werden sollen. Im einfachsten Fall kann diese Unterstützung lediglich darin bestehen, alle vom Betriebssystem bereitgestellten Umgebungsvariablen aus os.environ in das environ-Dictionary zu kopieren, da der Bereitsteller diese prinzipiell extern zum Server konfigurieren kann oder im CGI-Fall über die Konfigurationsdateien des Servers festgelegt werden können.

Anwendungen sollten versuchen, solche erforderlichen Variablen auf ein Minimum zu beschränken, da nicht alle Server eine einfache Konfiguration dafür unterstützen werden. Selbst im schlimmsten Fall können Personen, die eine Anwendung bereitstellen, natürlich ein Skript erstellen, um die erforderlichen Konfigurationswerte bereitzustellen

from the_app import application

def new_app(environ, start_response):
    environ['the_app.configval1'] = 'something'
    return application(environ, start_response)

Die meisten bestehenden Anwendungen und Frameworks benötigen wahrscheinlich nur einen einzigen Konfigurationswert aus environ, um den Speicherort ihrer anwendungs- oder frameworkspezifischen Konfigurationsdatei(en) anzugeben. (Natürlich sollten Anwendungen diese Konfiguration cachen, um zu vermeiden, sie bei jedem Aufruf erneut lesen zu müssen.)

URL-Rekonstruktion

Wenn eine Anwendung die vollständige URL einer Anfrage rekonstruieren möchte, kann sie dies mit dem folgenden Algorithmus tun, der von Ian Bicking beigesteuert wurde.

from urllib.parse import quote
url = environ['wsgi.url_scheme']+'://'

if environ.get('HTTP_HOST'):
    url += environ['HTTP_HOST']
else:
    url += environ['SERVER_NAME']

    if environ['wsgi.url_scheme'] == 'https':
        if environ['SERVER_PORT'] != '443':
           url += ':' + environ['SERVER_PORT']
    else:
        if environ['SERVER_PORT'] != '80':
           url += ':' + environ['SERVER_PORT']

url += quote(environ.get('SCRIPT_NAME', ''))
url += quote(environ.get('PATH_INFO', ''))
if environ.get('QUERY_STRING'):
    url += '?' + environ['QUERY_STRING']

Beachten Sie, dass eine solche rekonstruierte URL möglicherweise nicht genau dieselbe URI ist, die vom Client angefordert wurde. Server-Rewrite-Regeln können beispielsweise die ursprünglich vom Client angeforderte URL geändert haben, um sie in eine kanonische Form zu bringen.

Unterstützung älterer (<2.2) Python-Versionen

Einige Server, Gateways oder Anwendungen möchten möglicherweise ältere (<2.2) Versionen von Python unterstützen. Dies ist besonders wichtig, wenn Jython eine Zielplattform ist, da zum Zeitpunkt des Schreibens noch keine produktionsreife Version von Jython 2.2 verfügbar ist.

Für Server und Gateways ist dies relativ unkompliziert: Server und Gateways, die sich an Vor-2.2-Versionen von Python richten, müssen sich einfach darauf beschränken, nur eine Standard-„for“-Schleife zur Iteration über jedes von einer Anwendung zurückgegebene Iterable zu verwenden. Dies ist der einzige Weg, Quellcode-Kompatibilität sowohl mit dem vor-2.2-Iterator-Protokoll (weiter unten diskutiert) als auch mit dem „heutigen“ Iterator-Protokoll (siehe PEP 234) zu gewährleisten.

(Beachten Sie, dass diese Technik notwendigerweise nur für Server, Gateways oder Middleware gilt, die in Python geschrieben sind. Die Diskussion darüber, wie Iterator-Protokolle aus anderen Sprachen korrekt verwendet werden, liegt außerhalb des Rahmens dieses PEP.)

Für Anwendungen ist die Unterstützung von Vor-2.2-Versionen von Python etwas komplexer.

• Sie dürfen kein Dateiobjekt zurückgeben und erwarten, dass es als Iterable funktioniert, da vor Python 2.2 Dateien nicht iterierbar waren. (Im Allgemeinen sollten Sie dies sowieso nicht tun, da es die meiste Zeit sehr schlecht abschneiden wird!) Verwenden Sie wsgi.file_wrapper oder eine anwendungsspezifische Datei-Wrapper-Klasse. (Siehe Optionale plattformspezifische Dateiverarbeitung für mehr über wsgi.file_wrapper und eine Beispielklasse, die Sie zum Umhüllen einer Datei als Iterable verwenden können.)
• Wenn Sie ein benutzerdefiniertes Iterable zurückgeben, **muss** es das vor-2.2-Iterator-Protokoll implementieren. Das heißt, es muss eine __getitem__ Methode bereitstellen, die einen ganzzahligen Schlüssel akzeptiert und IndexError auslöst, wenn sie erschöpft ist. (Beachten Sie, dass eingebaute Sequenztypen ebenfalls akzeptabel sind, da sie dieses Protokoll ebenfalls implementieren.)

Schließlich muss Middleware, die Vor-2.2-Versionen von Python unterstützen möchte und über Anwendungsrückgabewerte iteriert oder selbst ein Iterable zurückgibt (oder beides), die entsprechenden Empfehlungen befolgen.

(Hinweis: Es versteht sich von selbst, dass zur Unterstützung von Vor-2.2-Versionen von Python jeder Server, jedes Gateway, jede Anwendung oder Middleware nur Sprachfunktionen verwenden muss, die in der Zielversion verfügbar sind, 1 und 0 anstelle von True und False usw. verwendet.)

Optionale plattformspezifische Dateibehandlung

Einige Betriebsumgebungen bieten spezielle Hochleistungs-Dateiübertragungseinrichtungen, wie den Unix-Aufruf sendfile(). Server und Gateways **können** diese Funktionalität über einen optionalen wsgi.file_wrapper Schlüssel im environ freigeben. Eine Anwendung **kann** diesen „Datei-Wrapper“ verwenden, um ein Datei- oder dateiähnliches Objekt in ein Iterable zu konvertieren, das sie dann zurückgibt, z. B.

if 'wsgi.file_wrapper' in environ:
    return environ['wsgi.file_wrapper'](filelike, block_size)
else:
    return iter(lambda: filelike.read(block_size), '')

Wenn der Server oder das Gateway wsgi.file_wrapper bereitstellt, muss es ein aufrufbares Objekt sein, das einen erforderlichen Positionsargument und ein optionales Positionsargument akzeptiert. Das erste Argument ist das zu sendende dateiähnliche Objekt, und das zweite Argument ist eine optionale Blockgrößen-"Vorgabe" (die der Server/Gateway nicht verwenden muss). Das aufrufbare Objekt **muss** ein Iterable-Objekt zurückgeben und **darf keine** Datenübertragung durchführen, es sei denn und bis der Server/Gateway das Iterable tatsächlich als Rückgabewert von der Anwendung erhält. (Andernfalls würde es Middleware daran hindern, die Antwortdaten zu interpretieren oder zu überschreiben.)

Um als „dateiähnlich“ zu gelten, muss das von der Anwendung bereitgestellte Objekt über eine read() Methode verfügen, die ein optionales Größenargument akzeptiert. Es **kann** eine close() Methode haben, und wenn ja, **muss** das von wsgi.file_wrapper zurückgegebene Iterable eine close() Methode haben, die die close() Methode des ursprünglichen dateiähnlichen Objekts aufruft. Wenn das „dateiähnliche“ Objekt andere Methoden oder Attribute mit Namen hat, die denen von Python-eingebauten Dateiobjekten entsprechen (z. B. fileno()), **kann** der wsgi.file_wrapper davon ausgehen, dass diese Methoden oder Attribute die gleichen Semantiken wie die eines eingebauten Dateiobjekts haben.

Die tatsächliche Implementierung der plattformspezifischen Dateibehandlung muss erfolgen, nachdem die Anwendung zurückkehrt und der Server oder Gateway prüft, ob ein Wrapper-Objekt zurückgegeben wurde. (Auch hier gilt: Aufgrund der Anwesenheit von Middleware, Fehlerbehandlern und ähnlichem ist nicht garantiert, dass ein erstellter Wrapper tatsächlich verwendet wird.)

Abgesehen von der Behandlung von close() sollten die Semantik der Rückgabe eines Dateiverpackers aus der Anwendung dieselben sein, als ob die Anwendung iter(filelike.read, '') zurückgegeben hätte. Mit anderen Worten, die Übertragung sollte an der aktuellen Position innerhalb der „Datei“ zum Zeitpunkt des Beginns der Übertragung beginnen und bis zum Erreichen des Endes fortfahren oder bis Content-Length Bytes geschrieben wurden. (Wenn die Anwendung keine Content-Length angibt, kann der Server eine aus der Datei generieren, basierend auf seinem Wissen über die zugrunde liegende Dateimplementierung.)

Natürlich akzeptieren plattformspezifische File-Transmission-APIs normalerweise keine beliebigen „file-like“ Objekte. Daher muss ein wsgi.file_wrapper das übergebene Objekt auf Dinge wie fileno() (Unix-ähnliche Betriebssysteme) oder ein java.nio.FileChannel (unter Jython) untersuchen, um festzustellen, ob das file-like Objekt für die Verwendung mit der von ihm unterstützten plattformspezifischen API geeignet ist.

Beachten Sie, dass auch wenn das Objekt nicht für die Plattform-API geeignet ist, wsgi.file_wrapper immer noch ein Iterable zurückgeben muss, das read() und close() umschließt, damit Anwendungen, die Dateiverpacker verwenden, plattformübergreifend portabel sind. Hier ist eine einfache plattformunabhängige Dateiverpacker-Klasse, die sowohl für alte (vor 2.2) als auch für neue Pythons geeignet ist.

class FileWrapper:

    def __init__(self, filelike, blksize=8192):
        self.filelike = filelike
        self.blksize = blksize
        if hasattr(filelike, 'close'):
            self.close = filelike.close

    def __getitem__(self, key):
        data = self.filelike.read(self.blksize)
        if data:
            return data
        raise IndexError

und hier ist ein Ausschnitt aus einem Server/Gateway, der ihn verwendet, um Zugriff auf eine plattformspezifische API zu ermöglichen.

environ['wsgi.file_wrapper'] = FileWrapper
result = application(environ, start_response)

try:
    if isinstance(result, FileWrapper):
        # check if result.filelike is usable w/platform-specific
        # API, and if so, use that API to transmit the result.
        # If not, fall through to normal iterable handling
        # loop below.

    for data in result:
        # etc.

finally:
    if hasattr(result, 'close'):
        result.close()