http.client — HTTP-Protokoll-Client

Quellcode: Lib/http/client.py

---

Dieses Modul definiert Klassen, die die Client-Seite der HTTP- und HTTPS-Protokolle implementieren. Es wird normalerweise nicht direkt verwendet — das Modul urllib.request verwendet es, um URLs zu verarbeiten, die HTTP und HTTPS verwenden.

Siehe auch

Das Requests-Paket wird für eine höherwertige HTTP-Client-Schnittstelle empfohlen.

Hinweis

HTTPS-Unterstützung ist nur verfügbar, wenn Python mit SSL-Unterstützung (über das Modul ssl) kompiliert wurde.

Verfügbarkeit: nicht WASI.

Dieses Modul funktioniert nicht oder ist nicht auf WebAssembly verfügbar. Weitere Informationen finden Sie unter WebAssembly-Plattformen.

Das Modul stellt die folgenden Klassen bereit

class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192)

Eine HTTPConnection-Instanz repräsentiert eine Transaktion mit einem HTTP-Server. Sie sollte durch Übergabe eines Hosts und einer optionalen Portnummer instanziiert werden. Wenn keine Portnummer übergeben wird, wird der Port aus dem Host-String extrahiert, falls er die Form host:port hat, andernfalls wird der Standard-HTTP-Port (80) verwendet. Wenn der optionale Parameter timeout angegeben wird, schlagen blockierende Operationen (wie Verbindungsversuche) nach dieser Anzahl von Sekunden fehl (wenn er nicht angegeben ist, wird die globale Standard-Timeout-Einstellung verwendet). Der optionale Parameter source_address kann ein Tupel aus (Host, Port) sein, das als Quelladresse für die HTTP-Verbindung verwendet wird. Der optionale Parameter blocksize legt die Puffergröße in Bytes für das Senden eines dateiähnlichen Nachrichtenrumpfes fest.

Beispielsweise erstellen die folgenden Aufrufe Instanzen, die sich mit dem Server auf demselben Host und Port verbinden

>>> h1 = http.client.HTTPConnection('www.python.org')
>>> h2 = http.client.HTTPConnection('www.python.org:80')
>>> h3 = http.client.HTTPConnection('www.python.org', 80)
>>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10)

Geändert in Version 3.2: source_address wurde hinzugefügt.

Geändert in Version 3.4: Der Parameter strict wurde entfernt. Einfache Antworten im Stil von HTTP 0.9 werden nicht mehr unterstützt.

Geändert in Version 3.7: Der Parameter blocksize wurde hinzugefügt.

class http.client.HTTPSConnection(host, port=None, *, [timeout, ]source_address=None, context=None, blocksize=8192)

Eine Unterklasse von HTTPConnection, die SSL für die Kommunikation mit sicheren Servern verwendet. Der Standardport ist 443. Wenn context angegeben ist, muss es eine ssl.SSLContext-Instanz sein, die die verschiedenen SSL-Optionen beschreibt.

Bitte lesen Sie Sicherheitsüberlegungen für weitere Informationen zu Best Practices.

Geändert in Version 3.2: source_address, context und check_hostname wurden hinzugefügt.

Geändert in Version 3.2: Diese Klasse unterstützt jetzt HTTPS-virtuelle Hosts, falls möglich (d.h. wenn ssl.HAS_SNI wahr ist).

Geändert in Version 3.4: Der Parameter strict wurde entfernt. Einfache Antworten im Stil von HTTP 0.9 werden nicht mehr unterstützt.

Geändert in Version 3.4.3: Diese Klasse führt standardmäßig alle notwendigen Zertifikats- und Hostnamenprüfungen durch. Um zum vorherigen, nicht verifizierten Verhalten zurückzukehren, kann ssl._create_unverified_context() an den Parameter context übergeben werden.

Geändert in Version 3.8: Diese Klasse aktiviert nun TLS 1.3 ssl.SSLContext.post_handshake_auth für den Standard-context oder wenn cert_file mit einem benutzerdefinierten context übergeben wird.

Geändert in Version 3.10: Diese Klasse sendet nun eine ALPN-Erweiterung mit dem Protokollindikator http/1.1, wenn kein context gegeben ist. Benutzerdefinierte context sollten ALPN-Protokolle mit set_alpn_protocols() festlegen.

Geändert in Version 3.12: Die veralteten Parameter key_file, cert_file und check_hostname wurden entfernt.

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)

Klasse, deren Instanzen nach erfolgreicher Verbindung zurückgegeben werden. Wird nicht direkt vom Benutzer instanziiert.

Geändert in Version 3.4: Der Parameter strict wurde entfernt. Einfache Antworten im Stil von HTTP 0.9 werden nicht mehr unterstützt.

Dieses Modul stellt die folgende Funktion bereit

http.client.parse_headers(fp)

Parst die Header aus einem Dateizeiger fp, der eine HTTP-Anfrage/Antwort repräsentiert. Die Datei muss ein BufferedIOBase-Leser sein (d.h. nicht Text) und einen gültigen RFC 2822-Stil-Header bereitstellen.

Diese Funktion gibt eine Instanz von http.client.HTTPMessage zurück, die die Header-Felder, aber keine Nutzdaten enthält (dasselbe wie HTTPResponse.msg und http.server.BaseHTTPRequestHandler.headers). Nach der Rückgabe ist der Dateizeiger fp bereit, den HTTP-Körper zu lesen.

Hinweis

parse_headers() parst nicht die Startzeile einer HTTP-Nachricht; es parst nur die Zeilen Name: Wert. Die Datei muss bereit sein, diese Feldzeilen zu lesen, daher sollte die erste Zeile bereits vor dem Aufruf der Funktion verbraucht worden sein.

Die folgenden Ausnahmen werden entsprechend ausgelöst

exception http.client.HTTPException

Die Basisklasse der anderen Ausnahmen in diesem Modul. Sie ist eine Unterklasse von Exception.

exception http.client.NotConnected

Eine Unterklasse von HTTPException.

exception http.client.InvalidURL

Eine Unterklasse von HTTPException, ausgelöst, wenn ein Port angegeben ist und entweder nicht numerisch oder leer ist.

exception http.client.UnknownProtocol

Eine Unterklasse von HTTPException.

exception http.client.UnknownTransferEncoding

Eine Unterklasse von HTTPException.

exception http.client.UnimplementedFileMode

Eine Unterklasse von HTTPException.

exception http.client.IncompleteRead

Eine Unterklasse von HTTPException.

exception http.client.ImproperConnectionState

Eine Unterklasse von HTTPException.

exception http.client.CannotSendRequest

Eine Unterklasse von ImproperConnectionState.

exception http.client.CannotSendHeader

Eine Unterklasse von ImproperConnectionState.

exception http.client.ResponseNotReady

Eine Unterklasse von ImproperConnectionState.

exception http.client.BadStatusLine

Eine Unterklasse von HTTPException. Ausgelöst, wenn ein Server mit einem HTTP-Statuscode antwortet, den wir nicht verstehen.

exception http.client.LineTooLong

Eine Unterklasse von HTTPException. Ausgelöst, wenn eine übermäßig lange Zeile im HTTP-Protokoll vom Server empfangen wird.

exception http.client.RemoteDisconnected

Eine Unterklasse von ConnectionResetError und BadStatusLine. Ausgelöst von HTTPConnection.getresponse(), wenn der Versuch, die Antwort zu lesen, dazu führt, dass keine Daten von der Verbindung gelesen werden, was darauf hindeutet, dass das entfernte Ende die Verbindung geschlossen hat.

Hinzugefügt in Version 3.5: Zuvor wurde BadStatusLine('') ausgelöst.

Die in diesem Modul definierten Konstanten sind

http.client.HTTP_PORT

Der Standardport für das HTTP-Protokoll (immer 80).

http.client.HTTPS_PORT

Der Standardport für das HTTPS-Protokoll (immer 443).

http.client.responses

Dieses Wörterbuch ordnet die HTTP 1.1-Statuscodes den W3C-Namen zu.

Beispiel: http.client.responses[http.client.NOT_FOUND] ist 'Not Found'.

Siehe HTTP-Statuscodes für eine Liste von HTTP-Statuscodes, die in diesem Modul als Konstanten verfügbar sind.

HTTPConnection Objekte

HTTPConnection-Instanzen haben die folgenden Methoden

HTTPConnection.request(method, url, body=None, headers={}, *, encode_chunked=False)

Dies sendet eine Anfrage an den Server unter Verwendung der HTTP-Anfragemethode method und der Anfrage-URI url. Die angegebene url muss ein absoluter Pfad sein, um RFC 2616 §5.1.2 zu entsprechen (es sei denn, es wird eine Verbindung zu einem HTTP-Proxy-Server hergestellt oder die Methoden OPTIONS oder CONNECT verwendet).

Wenn body angegeben ist, werden die angegebenen Daten nach Abschluss der Header gesendet. Es kann sich um einen str, ein bytes-ähnliches Objekt, ein geöffnetes Dateiobjekt oder ein Iterable von bytes handeln. Wenn body ein String ist, wird er als ISO-8859-1 kodiert, der Standard für HTTP. Wenn es sich um ein bytes-ähnliches Objekt handelt, werden die Bytes unverändert gesendet. Wenn es sich um ein Dateiobjekt handelt, werden die Inhalte der Datei gesendet; dieses Dateiobjekt sollte mindestens die read()-Methode unterstützen. Wenn das Dateiobjekt eine Instanz von io.TextIOBase ist, werden die von der read()-Methode zurückgegebenen Daten als ISO-8859-1 kodiert, andernfalls werden die von read() zurückgegebenen Daten unverändert gesendet. Wenn body ein Iterable ist, werden die Elemente des Iterables unverändert gesendet, bis das Iterable erschöpft ist.

Das Argument headers sollte eine Zuordnung zusätzlicher HTTP-Header sein, die mit der Anfrage gesendet werden sollen. Ein Host-Header muss gemäß RFC 2616 §5.1.2 angegeben werden (es sei denn, es wird eine Verbindung zu einem HTTP-Proxy-Server hergestellt oder die Methoden OPTIONS oder CONNECT verwendet).

Wenn headers weder Content-Length noch Transfer-Encoding enthält, aber ein Nachrichtenrumpf vorhanden ist, wird eines dieser Header-Felder automatisch hinzugefügt. Wenn body None ist, wird der Content-Length-Header auf 0 für Methoden gesetzt, die einen Körper erwarten (PUT, POST und PATCH). Wenn body ein String oder ein bytes-ähnliches Objekt ist, das kein Datei ist, wird der Content-Length-Header auf seine Länge gesetzt. Jeder andere Typ von body (Dateien und Iterables im Allgemeinen) wird chunk-kodiert, und der Transfer-Encoding-Header wird automatisch anstelle von Content-Length gesetzt.

Das Argument encode_chunked ist nur relevant, wenn Transfer-Encoding in headers angegeben ist. Wenn encode_chunked False ist, geht das HTTPConnection-Objekt davon aus, dass die gesamte Kodierung vom aufrufenden Code behandelt wird. Wenn es True ist, wird der Körper chunk-kodiert.

Um beispielsweise eine GET-Anfrage an https://docs.pythonlang.de/3/ zu senden

>>> import http.client
>>> host = "docs.python.org"
>>> conn = http.client.HTTPSConnection(host)
>>> conn.request("GET", "/3/", headers={"Host": host})
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200 OK

Hinweis

Chunked-Transfer-Encoding wurde zur HTTP-Protokollversion 1.1 hinzugefügt. Sofern der HTTP-Server nicht bekanntermaßen HTTP 1.1 unterstützt, muss der Aufrufer entweder die Content-Length angeben oder ein str oder ein bytes-ähnliches Objekt übergeben, das kein Dateiobjekt ist, als Darstellung des Bodys.

Geändert in Version 3.2: body kann jetzt ein Iterable sein.

Geändert in Version 3.6: Wenn weder Content-Length noch Transfer-Encoding in headers gesetzt sind, werden Datei- und Iterable-body-Objekte jetzt chunk-kodiert. Das Argument encode_chunked wurde hinzugefügt. Es wird kein Versuch unternommen, die Content-Length für Dateiobjekte zu ermitteln.

HTTPConnection.getresponse()

Sollte nach dem Senden einer Anfrage aufgerufen werden, um die Antwort vom Server zu erhalten. Gibt eine HTTPResponse-Instanz zurück.

Hinweis

Beachten Sie, dass Sie die gesamte Antwort gelesen haben müssen, bevor Sie eine neue Anfrage an den Server senden können.

Geändert in Version 3.5: Wenn eine ConnectionError oder eine Unterklasse ausgelöst wird, ist das HTTPConnection-Objekt bereit, sich wieder zu verbinden, wenn eine neue Anfrage gesendet wird.

HTTPConnection.set_debuglevel(level)

Legt die Debugging-Stufe fest. Die Standard-Debugging-Stufe ist 0, was bedeutet, dass keine Debugging-Ausgabe ausgegeben wird. Jeder Wert größer als 0 veranlasst die Ausgabe aller derzeit definierten Debug-Ausgaben nach stdout. Die debuglevel wird an alle neu erstellten HTTPResponse-Objekte übergeben.

Hinzugefügt in Version 3.1.

HTTPConnection.set_tunnel(host, port=None, headers=None)

Legt den Host und den Port für HTTP-Connect-Tunnelling fest. Dies ermöglicht die Ausführung der Verbindung über einen Proxy-Server.

Die Argumente host und port geben den Endpunkt der getunnelten Verbindung an (d.h. die Adresse, die in der CONNECT-Anfrage enthalten ist, *nicht* die Adresse des Proxy-Servers).

Das Argument headers sollte eine Zuordnung zusätzlicher HTTP-Header sein, die mit der CONNECT-Anfrage gesendet werden sollen.

Da für HTTP-CONNECT-Tunneling-Anfragen HTTP/1.1 verwendet wird, ist gemäß RFC ein HTTP Host:-Header erforderlich, der die Authority-Form des Anforderungsziels, das als Ziel für die CONNECT-Anfrage angegeben wird, abgleicht. Wenn kein HTTP Host:-Header über das Argument headers bereitgestellt wird, wird automatisch einer generiert und gesendet.

Um beispielsweise über einen lokal auf Port 8080 laufenden HTTPS-Proxy-Server zu tunneln, würden wir die Adresse des Proxys an den Konstruktor HTTPSConnection und die Adresse des Hosts, den wir letztendlich erreichen wollen, an die Methode set_tunnel() übergeben

>>> import http.client
>>> conn = http.client.HTTPSConnection("localhost", 8080)
>>> conn.set_tunnel("www.python.org")
>>> conn.request("HEAD","/index.html")

Hinzugefügt in Version 3.2.

Geändert in Version 3.12: HTTP-CONNECT-Tunneling-Anfragen verwenden das Protokoll HTTP/1.1, aktualisiert von Protokoll HTTP/1.0. HTTP-Header Host: sind für HTTP/1.1 obligatorisch, daher wird automatisch einer generiert und gesendet, wenn er nicht im Argument headers bereitgestellt wird.

HTTPConnection.get_proxy_response_headers()

Gibt ein Wörterbuch mit den Headern der Antwort zurück, die vom Proxy-Server auf die CONNECT-Anfrage empfangen wurde.

Wenn die CONNECT-Anfrage nicht gesendet wurde, gibt die Methode None zurück.

Hinzugefügt in Version 3.12.

HTTPConnection.connect()

Stellt eine Verbindung mit dem Server her, der beim Erstellen des Objekts angegeben wurde. Standardmäßig wird dies automatisch aufgerufen, wenn eine Anfrage gestellt wird, falls der Client noch keine Verbindung hat.

Löst ein Auditing-Ereignis http.client.connect mit den Argumenten self, host, port aus.

HTTPConnection.close()

Schließt die Verbindung zum Server.

HTTPConnection.blocksize

Puffergröße in Bytes für das Senden eines dateiähnlichen Nachrichtenrumpfes.

Hinzugefügt in Version 3.7.

Als Alternative zur Verwendung der oben beschriebenen Methode request() können Sie Ihre Anfrage auch Schritt für Schritt senden, indem Sie die folgenden vier Funktionen verwenden.

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)

Dies sollte der erste Aufruf sein, nachdem die Verbindung zum Server hergestellt wurde. Er sendet eine Zeile an den Server, die die Zeichenkette method, die Zeichenkette url und die HTTP-Version (HTTP/1.1) enthält. Um das automatische Senden von Host:- oder Accept-Encoding:-Headern zu deaktivieren (z.B. um zusätzliche Inhaltskodierungen zu akzeptieren), geben Sie skip_host oder skip_accept_encoding mit nicht-False-Werten an.

HTTPConnection.putheader(header, argument[, ...])

Sendet einen RFC 822-Stil-Header an den Server. Er sendet eine Zeile an den Server, bestehend aus dem Header, einem Doppelpunkt und einem Leerzeichen sowie dem ersten Argument. Wenn weitere Argumente angegeben sind, werden Fortsetzungszeilen gesendet, die jeweils aus einem Tabulator und einem Argument bestehen.

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)

Sendet eine leere Zeile an den Server, was das Ende der Header signalisiert. Das optionale Argument message_body kann verwendet werden, um einen mit der Anfrage verbundenen Nachrichtenrumpf zu übergeben.

Wenn encode_chunked auf True gesetzt ist, wird das Ergebnis jeder Iteration von message_body wie in RFC 7230, Abschnitt 3.3.1 beschrieben, als Chunk kodiert. Wie die Daten kodiert werden, hängt vom Typ von message_body ab. Wenn message_body die Puffer-Schnittstelle implementiert, führt die Kodierung zu einem einzelnen Chunk. Wenn message_body ein collections.abc.Iterable ist, führt jede Iteration von message_body zu einem Chunk. Wenn message_body ein Datei-Objekt ist, führt jeder Aufruf von .read() zu einem Chunk. Die Methode signalisiert automatisch das Ende der Chunk-kodierten Daten unmittelbar nach message_body.

Hinweis

Aufgrund der Spezifikation der Chunk-Kodierung werden leere Chunks, die von einem Iterator-Body geliefert werden, vom Chunk-Encoder ignoriert. Dies dient dazu, eine vorzeitige Beendigung des Lesens der Anfrage durch den Zielserver aufgrund einer fehlerhaften Kodierung zu vermeiden.

Geändert in Version 3.6: Unterstützung für Chunk-Kodierung und den Parameter encode_chunked hinzugefügt.

HTTPConnection.send(data)

Sendet Daten an den Server. Dies sollte nur direkt nach dem Aufruf der Methode endheaders() und vor dem Aufruf von getresponse() verwendet werden.

Löst ein Audit-Ereignis http.client.send mit den Argumenten self, data aus.

HTTPResponse-Objekte

Eine Instanz von HTTPResponse umschließt die HTTP-Antwort vom Server. Sie bietet Zugriff auf die Anfrage-Header und den Entitätskörper. Die Antwort ist ein iterierbares Objekt und kann in einer with-Anweisung verwendet werden.

Geändert in Version 3.5: Die Schnittstelle io.BufferedIOBase wird nun implementiert und alle ihre Leseoperationen werden unterstützt.

HTTPResponse.read([amt])

Liest und gibt den Antwortkörper zurück, oder bis zu den nächsten amt Bytes.

HTTPResponse.readinto(b)

Liest bis zu den nächsten len(b) Bytes des Antwortkörpers in den Puffer b. Gibt die Anzahl der gelesenen Bytes zurück.

Hinzugefügt in Version 3.3.

HTTPResponse.getheader(name, default=None)

Gibt den Wert des Headers name zurück, oder default, wenn kein Header mit name übereinstimmt. Wenn es mehr als einen Header mit dem Namen name gibt, werden alle Werte mit „, “ verbunden zurückgegeben. Wenn default ein anderes iterierbares Objekt als ein einzelner String ist, werden dessen Elemente ebenfalls durch Kommas verbunden zurückgegeben.

HTTPResponse.getheaders()

Gibt eine Liste von (Header, Wert) Tupeln zurück.

HTTPResponse.fileno()

Gibt die fileno des zugrunde liegenden Sockets zurück.

HTTPResponse.msg

Eine Instanz von http.client.HTTPMessage, die die Antwort-Header enthält. http.client.HTTPMessage ist eine Unterklasse von email.message.Message.

HTTPResponse.version

HTTP-Protokollversion, die vom Server verwendet wird. 10 für HTTP/1.0, 11 für HTTP/1.1.

HTTPResponse.url

URL der abgerufenen Ressource, häufig verwendet, um festzustellen, ob einer Weiterleitung gefolgt wurde.

HTTPResponse.headers

Header der Antwort in Form einer Instanz von email.message.EmailMessage.

HTTPResponse.status

Vom Server zurückgegebener Statuscode.

HTTPResponse.reason

Vom Server zurückgegebene Statusphrase.

HTTPResponse.debuglevel

Ein Debugging-Hook. Wenn debuglevel größer als Null ist, werden beim Lesen und Parsen der Antwort Meldungen auf stdout ausgegeben.

HTTPResponse.closed

Ist True, wenn der Stream geschlossen ist.

HTTPResponse.geturl()

Veraltet seit Version 3.9: Veraltet zugunsten von url.

HTTPResponse.info()

Veraltet seit Version 3.9: Veraltet zugunsten von headers.

HTTPResponse.getcode()

Veraltet seit Version 3.9: Veraltet zugunsten von status.

Beispiele

Hier ist eine Beispiel-Sitzung, die die GET Methode verwendet.

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read()  # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while chunk := r1.read(200):
...     print(repr(chunk))
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> conn = http.client.HTTPSConnection("docs.python.org")
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

Hier ist eine Beispiel-Sitzung, die die HEAD Methode verwendet. Beachten Sie, dass die HEAD Methode niemals Daten zurückgibt.

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("HEAD", "/")
>>> res = conn.getresponse()
>>> print(res.status, res.reason)
200 OK
>>> data = res.read()
>>> print(len(data))
0
>>> data == b''
True

Hier ist eine Beispiel-Sitzung, die die POST Methode verwendet.

>>> import http.client, urllib.parse
>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"}
>>> conn = http.client.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
302 Found
>>> data = response.read()
>>> data
b'Redirecting to <a href="https://bugs.python.org/issue12524">https://bugs.python.org/issue12524</a>'
>>> conn.close()

Clientseitige HTTP PUT Anfragen sind sehr ähnlich zu POST Anfragen. Der Unterschied liegt nur auf der Serverseite, wo HTTP-Server das Erstellen von Ressourcen über PUT Anfragen erlauben. Es sei darauf hingewiesen, dass benutzerdefinierte HTTP-Methoden auch in urllib.request.Request behandelt werden, indem das entsprechende Methodenattribut gesetzt wird. Hier ist eine Beispiel-Sitzung, die die PUT Methode verwendet.

>>> # This creates an HTTP request
>>> # with the content of BODY as the enclosed representation
>>> # for the resource https://:8080/file
...
>>> import http.client
>>> BODY = "***filecontents***"
>>> conn = http.client.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200, OK

HTTPMessage-Objekte

class http.client.HTTPMessage(email.message.Message)

Eine Instanz von http.client.HTTPMessage enthält die Header einer HTTP-Antwort. Sie wird unter Verwendung der Klasse email.message.Message implementiert.