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 formenhost: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 är443
. Om context anges måste det vara en instans avssl.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 medset_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 somHTTPResponse.msg
ochhttp.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 radernaName: 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
ochBadStatusLine
. Utlöses avHTTPConnection.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
ellerCONNECT
).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 avbytes
. 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 metodenread()
. Om filobjektet är en instans avio.TextIOBase
, kommer de data som returneras av metodenread()
att kodas som ISO-8859-1, annars skickas de data som returneras avread()
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
ellerCONNECT
).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 till0
för metoder som förväntar sig en body (PUT
,POST
ochPATCH
). 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 ärTrue
kommer kroppen att vara chunk-kodad.Till exempel, för att utföra en
GET
begäran tillhttps://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, kommerHTTPConnection
-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 än0
gör att all debug-utdata som för närvarande är definierad skrivs ut till stdout. Debuggnivån skickas till alla nyaHTTPResponse
-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-rubrikHost:
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å tillset_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 argumentenself
,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 avHost:
ellerAccept-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 encollections.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 innangetresponse()
anropas.Utlöser en auditing event
http.client.send
med argumentenself
,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 avemail.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.
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.