http.client — Klient för HTTP-protokoll

Källkod: Lib/http/client.py


Den här modulen definierar klasser som implementerar klientsidan av HTTP- och HTTPS-protokollen. Den används normalt inte direkt — modulen urllib.request använder den för att hantera webbadresser som använder HTTP och HTTPS.

Se även

Paketet Requests rekommenderas för ett HTTP-klientgränssnitt på högre nivå.

Anteckning

HTTPS-stöd är endast tillgängligt om Python kompilerades med SSL-stöd (genom modulen ssl).

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Modulen innehåller följande klasser:

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

En HTTPConnection-instans representerar en transaktion med en HTTP-server. Den bör instansieras genom att den får en värd och ett valfritt portnummer. Om inget portnummer anges extraheras porten från värdsträngen om den har formen host:port, annars används HTTP-standardporten (80). Om den valfria parametern timeout anges kommer blockerande operationer (som anslutningsförsök) att timeoutas efter det antalet sekunder (om den inte anges används den globala standardinställningen för timeout). Den valfria parametern source_address kan vara en tupel av en (host, port) som ska användas som källadress för HTTP-anslutningen. Den valfria parametern blocksize anger buffertstorleken i byte för att skicka en filliknande meddelandekropp.

Följande anrop skapar t.ex. alla instanser som ansluter till servern på samma värd och port:

>>> 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)

Ändrad i version 3.2: source_address har lagts till.

Ändrad i version 3.4: Parametern strict har tagits bort. HTTP 0.9-stil ”Simple Responses” stöds inte längre.

Ändrad i version 3.7: blocksize-parametern har lagts till.

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

En underklass till HTTPConnection som använder SSL för kommunikation med säkra servrar. Standardporten är 443. Om context anges måste det vara en instans av ssl.SSLContext som beskriver de olika SSL-alternativen.

Läs Överväganden om säkerhet för mer information om bästa praxis.

Ändrad i version 3.2: source_address, context och check_hostname har lagts till.

Ändrad i version 3.2: Den här klassen stöder nu virtuella HTTPS-värdar om möjligt (dvs. om ssl.HAS_SNI är true).

Ändrad i version 3.4: Parametern strict har tagits bort. HTTP 0.9-stil ”Simple Responses” stöds inte längre.

Ändrad i version 3.4.3: Den här klassen utför nu alla nödvändiga certifikat- och värdnamnskontroller som standard. För att återgå till det tidigare, overifierade, beteendet kan ssl._create_unverified_context() skickas till parametern context.

Ändrad i version 3.8: Den här klassen aktiverar nu TLS 1.3 ssl.SSLContext.post_handshake_auth för standard kontext eller när cert_file skickas med en anpassad kontext.

Ändrad i version 3.10: Denna klass skickar nu ett ALPN-tillägg med protokollindikatorn http/1.1 när ingen kontext ges. Anpassad kontext bör ställa in ALPN-protokoll med set_alpn_protocols().

Ändrad i version 3.12: De föråldrade parametrarna key_file, cert_file och check_hostname har tagits bort.

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

Klass vars instanser returneras vid lyckad anslutning. Instansieras inte direkt av användaren.

Ändrad i version 3.4: Parametern strict har tagits bort. HTTP 0.9-stil ”Simple Responses” stöds inte längre.

Denna modul har följande funktioner:

http.client.parse_headers(fp)

Analysera rubrikerna från en filpekare fp som representerar en HTTP-begäran/-svar. Filen måste vara en BufferedIOBase-läsare (dvs. inte text) och måste tillhandahålla en giltig RFC 2822-stilrubrik.

Denna funktion returnerar en instans av http.client.HTTPMessage som innehåller rubrikfälten, men ingen nyttolast (samma som HTTPResponse.msg och http.server.BaseHTTPRequestHandler.headers). Efter att ha återvänt är filpekaren fp redo att läsa HTTP-kroppen.

Anteckning

parse_headers() analyserar inte startraden i ett HTTP-meddelande; den analyserar endast raderna Name: value. Filen måste vara redo att läsa dessa fältrader, så den första raden bör redan ha använts innan funktionen anropas.

Följande undantag tas upp i tillämpliga fall:

exception http.client.HTTPException

Basklassen för de andra undantagen i denna modul. Den är en underklass till Exception.

exception http.client.NotConnected

En underklass till HTTPException.

exception http.client.InvalidURL

En underklass till HTTPException, som uppstår om en port anges och den antingen är icke-numerisk eller tom.

exception http.client.UnknownProtocol

En underklass till HTTPException.

exception http.client.UnknownTransferEncoding

En underklass till HTTPException.

exception http.client.UnimplementedFileMode

En underklass till HTTPException.

exception http.client.IncompleteRead

En underklass till HTTPException.

exception http.client.ImproperConnectionState

En underklass till HTTPException.

exception http.client.CannotSendRequest

En underklass av ImproperConnectionState.

exception http.client.CannotSendHeader

En underklass av ImproperConnectionState.

exception http.client.ResponseNotReady

En underklass av ImproperConnectionState.

exception http.client.BadStatusLine

En underklass till HTTPException. Uppstår om en server svarar med en HTTP-statuskod som vi inte förstår.

exception http.client.LineTooLong

En underklass till HTTPException. Utlöses om en alltför lång rad tas emot i HTTP-protokollet från servern.

exception http.client.RemoteDisconnected

En underklass till ConnectionResetError och BadStatusLine. Utlöses av HTTPConnection.getresponse() när försöket att läsa svaret resulterar i att inga data läses från anslutningen, vilket indikerar att fjärranslutningen har stängt anslutningen.

Tillagd i version 3.5: Tidigare uppstod BadStatusLine('').

De konstanter som definieras i denna modul är:

http.client.HTTP_PORT

Standardporten för HTTP-protokollet (alltid 80).

http.client.HTTPS_PORT

Standardporten för HTTPS-protokollet (alltid 443).

http.client.responses

Denna ordbok mappar HTTP 1.1-statuskoderna till W3C-namnen.

Exempel: http.client.responses[http.client.NOT_FOUND] är 'Not Found'.

Se HTTP-statuskoder för en lista över HTTP-statuskoder som finns tillgängliga i den här modulen som konstanter.

HTTPC-anslutningsobjekt

HTTPConnection-instanser har följande metoder:

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

Detta skickar en begäran till servern med HTTP-begärandemetoden method och begärans URI url. Den angivna url måste vara en absolut sökväg för att överensstämma med RFC 2616 §5.1.2 (om du inte ansluter till en HTTP-proxyserver eller använder metoderna OPTIONS eller CONNECT).

Om body anges skickas den angivna datan efter att rubrikerna är klara. Det kan vara en str, ett bytes-like object, ett öppet file object eller en iterabel av bytes. Om body är en sträng kodas den som ISO-8859-1, vilket är standard för HTTP. Om det är ett bytesliknande objekt skickas bytena som de är. Om det är ett file object, skickas innehållet i filen; detta filobjekt bör åtminstone stödja metoden read(). Om filobjektet är en instans av io.TextIOBase, kommer de data som returneras av metoden read() att kodas som ISO-8859-1, annars skickas de data som returneras av read() som de är. Om body är en iterabel skickas elementen i iterabeln som de är tills iterabeln är uttömd.

Argumentet headers bör vara en mappning av extra HTTP-rubriker som ska skickas med begäran. En Host header måste tillhandahållas för att överensstämma med RFC 2616 §5.1.2 (såvida man inte ansluter till en HTTP-proxyserver eller använder metoderna OPTIONS eller CONNECT).

Om headers varken innehåller Content-Length eller Transfer-Encoding, men det finns en request body, kommer ett av dessa header-fält att läggas till automatiskt. Om body är None, sätts Content-Length-huvudet till 0 för metoder som förväntar sig en body (PUT, POST och PATCH). Om body är en sträng eller ett bytesliknande objekt som inte också är en file, sätts Content-Length-huvudet till dess längd. Alla andra typer av body (filer och iterabler i allmänhet) kommer att chunk-kodas, och Transfer-Encoding-huvudet kommer automatiskt att anges istället för Content-Length.

Argumentet encode_chunked är endast relevant om Transfer-Encoding anges i headers. Om encode_chunked är False, antar HTTPConnection-objektet att all kodning hanteras av den anropande koden. Om det är True kommer kroppen att vara chunk-kodad.

Till exempel, för att utföra en GET begäran till https://docs.python.org/3/:

>>> 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

Anteckning

Chunked transfer encoding har lagts till i HTTP-protokollet version 1.1. Om inte HTTP-servern är känd för att hantera HTTP 1.1, måste anroparen antingen ange Content-Length eller skicka ett str eller bytes-liknande objekt som inte också är en fil som body-representation.

Ändrad i version 3.2: body kan nu vara en iterabel.

Ändrad i version 3.6: Om varken Content-Length eller Transfer-Encoding anges i headers är fil- och iterable-objekten body nu chunk-kodade. Argumentet encode_chunked har lagts till. Det görs inga försök att fastställa Content-Length för filobjekt.

HTTPConnection.getresponse()

Bör anropas efter att en begäran har skickats för att få svaret från servern. Returnerar en instans av HTTPResponse.

Anteckning

Observera att du måste ha läst hela svaret innan du kan skicka en ny begäran till servern.

Ändrad i version 3.5: Om ett ConnectionError eller underklass uppstår, kommer HTTPConnection-objektet att vara redo att återansluta när en ny begäran skickas.

HTTPConnection.set_debuglevel(level)

Ställer in felsökningsnivån. Standardnivån för felsökning är 0, vilket innebär att inga felsökningsresultat skrivs ut. Alla värden som är större än 0 gör att all debug-utdata som för närvarande är definierad skrivs ut till stdout. Debuggnivån skickas till alla nya HTTPResponse-objekt som skapas.

Tillagd i version 3.1.

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

Ange värd och port för HTTP Connect Tunnelling. Detta gör det möjligt att köra anslutningen via en proxyserver.

Argumenten host och port anger slutpunkten för den tunnlade anslutningen (dvs. den adress som ingår i CONNECT-begäran, inte proxyserverns adress).

Argumentet headers bör vara en mappning av extra HTTP-rubriker som ska skickas med CONNECT-begäran.

Eftersom HTTP/1.1 används för HTTP CONNECT-tunnelingbegäran, enligt RFC, måste en HTTP-header Host: anges som matchar auktoritetsformen för begäran som anges som destination för CONNECT-begäran. Om en HTTP-rubrik Host: inte anges via rubrikargumentet genereras och överförs en automatiskt.

Om vi till exempel vill skapa en tunnel genom en HTTPS-proxyserver som körs lokalt på port 8080, skickar vi adressen till proxyn till HTTPSConnection-konstruktören och adressen till den värd som vi så småningom vill nå till set_tunnel()-metoden:

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

Tillagd i version 3.2.

Ändrad i version 3.12: HTTP CONNECT-tunnelförfrågningar använder protokoll HTTP/1.1, uppgraderat från protokoll HTTP/1.0. Host: HTTP-rubriker är obligatoriska för HTTP/1.1, så en kommer automatiskt att genereras och överföras om den inte anges i argumentet headers.

HTTPConnection.get_proxy_response_headers()

Returnerar en ordbok med rubrikerna i svaret från proxyservern på CONNECT-begäran.

Om CONNECT-begäran inte skickades returnerar metoden None.

Tillagd i version 3.12.

HTTPConnection.connect()

Anslut till den server som angavs när objektet skapades. Som standard anropas detta automatiskt när en begäran görs om klienten inte redan har en anslutning.

Utlöser en auditing event http.client.connect med argumenten self, host, port.

HTTPConnection.close()

Stäng anslutningen till servern.

HTTPConnection.blocksize

Buffertstorlek i bytes för att skicka en filliknande meddelandekropp.

Tillagd i version 3.7.

Som ett alternativ till att använda metoden request() som beskrivs ovan kan du också skicka din begäran steg för steg genom att använda de fyra funktionerna nedan.

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

Detta bör vara det första anropet efter att anslutningen till servern har upprättats. Det skickar en rad till servern som består av method-strängen, url-strängen och HTTP-versionen (HTTP/1.1). För att inaktivera automatisk sändning av Host: eller Accept-Encoding:-rubriker (till exempel för att acceptera ytterligare innehållskodningar), ange skip_host eller skip_accept_encoding med icke-falska värden.

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

Skicka en header i stil med RFC 822 till servern. Det skickar en rad till servern som består av rubriken, ett kolon och ett mellanslag samt det första argumentet. Om fler argument anges skickas fortsättningsrader, var och en bestående av en tabb och ett argument.

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

Skicka en tom rad till servern för att markera slutet på sidhuvudet. Det valfria argumentet message_body kan användas för att skicka en meddelandekod som är kopplad till begäran.

Om encode_chunked är True kommer resultatet av varje iteration av message_body att chunk-kodas enligt specifikationen i RFC 7230, avsnitt 3.3.1. Hur data kodas beror på vilken typ av message_body som används. Om message_body implementerar buffer interface kommer kodningen att resultera i en enda chunk. Om message_body är en collections.abc.Iterable kommer varje iteration av message_body att resultera i en chunk. Om message_body är en file object, kommer varje anrop till .read() att resultera i en chunk. Metoden signalerar automatiskt slutet på de chunk-kodade data omedelbart efter message_body.

Anteckning

På grund av specifikationen för chunked-kodning ignoreras tomma chunks som genereras av en iteratorkropp av chunk-kodaren. Detta för att undvika att målservern avslutar läsningen av begäran i förtid på grund av felaktig kodning.

Ändrad i version 3.6: Stöd för chunked-kodning och parametern encode_chunked har lagts till.

HTTPConnection.send(data)

Skicka data till servern. Detta bör användas direkt först efter att metoden endheaders() har anropats och innan getresponse() anropas.

Utlöser en auditing event http.client.send med argumenten self, data.

HTTPResponse-objekt

En HTTPResponse-instans omsluter HTTP-svaret från servern. Den ger tillgång till begärans rubriker och entitetens kropp. Svaret är ett itererbart objekt och kan användas i en with-sats.

Ändrad i version 3.5: Gränssnittet io.BufferedIOBase är nu implementerat och alla dess läsoperationer stöds.

HTTPResponse.read([amt])

Läser och returnerar svarstexten, eller upp till nästa amt byte.

HTTPResponse.readinto(b)

Läser upp till nästa len(b) byte av svarstexten i bufferten b. Returnerar antalet lästa byte.

Tillagd i version 3.3.

HTTPResponse.getheader(name, default=None)

Returnerar värdet för rubriken name, eller default om det inte finns någon rubrik som matchar name. Om det finns mer än en header med namnet name, returneras alla värden sammanfogade med ’, ’. Om default är någon annan iterabel än en enda sträng returneras dess element på samma sätt med kommatecken.

HTTPResponse.getheaders()

Returnerar en lista med (header, value)-tupler.

HTTPResponse.fileno()

Returnerar fileno för det underliggande uttaget.

HTTPResponse.msg

En instans av http.client.HTTPMessage som innehåller svarshuvudena. http.client.HTTPMessage är en underklass av email.message.Message.

HTTPResponse.version

HTTP-protokollversion som används av servern. 10 för HTTP/1.0, 11 för HTTP/1.1.

HTTPResponse.url

URL för den hämtade resursen, används vanligen för att avgöra om en omdirigering följdes.

HTTPResponse.headers

Svarets rubriker i form av en instans av email.message.EmailMessage.

HTTPResponse.status

Statuskod som returneras av servern.

HTTPResponse.reason

Orsaksfras som returneras av servern.

HTTPResponse.debuglevel

En felsöknings-hook. Om debuglevel är större än noll kommer meddelanden att skrivas ut till stdout när svaret läses och analyseras.

HTTPResponse.closed

Är True om strömmen är stängd.

HTTPResponse.geturl()

Föråldrad sedan version 3.9: Föråldrad till förmån för url.

HTTPResponse.info()

Föråldrad sedan version 3.9: Föråldrad till förmån för headers.

HTTPResponse.getcode()

Föråldrad sedan version 3.9: Föråldrad till förmån för status.

Exempel

Här är ett exempel på en session som använder metoden GET:

>>> 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()

Här är ett exempel på en session som använder metoden HEAD. Observera att metoden HEAD aldrig returnerar några data.

>>> 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

Här är ett exempel på en session som använder metoden POST:

>>> 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()

HTTP-begäranden av typen PUT på klientsidan är mycket lik POST -begäranden. Skillnaden ligger endast på serversidan, där HTTP-servrar tillåter att resurser skapas via PUT -begäranden. Det bör noteras att anpassade HTTP-metoder också hanteras i urllib.request.Request genom att ställa in lämpligt metodattribut. Här är ett exempel på en session som använder PUT -metoden:

>>> # This creates an HTTP request
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost: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-objekt

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

En http.client.HTTPMessage-instans innehåller rubrikerna från ett HTTP-svar. Den implementeras med hjälp av email.message.Message-klassen.