Note

HTTPS support is only available if Python was compiled with SSL support(through thessl module).

Changed in version 3.3:Added codes428,429,431 and511 fromRFC 6585.

21.12.1. HTTPConnection Objects¶

HTTPConnection instances have the following methods:

HTTPConnection.request(method,url,body=None,headers={})¶

This will send a request to the server using the HTTP requestmethodmethod and the selectorurl. If thebody argument ispresent, it should be string or bytes object of data to send afterthe headers are finished. Strings are encoded as ISO-8859-1, thedefault charset for HTTP. To use other encodings, pass a bytesobject. The Content-Length header is set to the length of thestring.

Thebody may also be an openfile object, in which case thecontents of the file is sent; this file object should supportfileno()andread() methods. The header Content-Length is automatically set tothe length of the file as reported by stat. Thebody argument may also bean iterable and Content-Length header should be explicitly provided when thebody is an iterable.

Theheaders argument should be a mapping of extra HTTPheaders to send with the request.

New in version 3.2:body can now be an iterable.

HTTPConnection.getresponse()¶

Should be called after a request is sent to get the response from the server.Returns anHTTPResponse instance.

Note

Note that you must have read the whole response before you can send a newrequest to the server.

HTTPConnection.set_debuglevel(level)¶

Set the debugging level. The default debug level is0, meaning nodebugging output is printed. Any value greater than0 will cause allcurrently defined debug output to be printed to stdout. Thedebuglevelis passed to any newHTTPResponse objects that are created.

New in version 3.1.

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

Set the host and the port for HTTP Connect Tunnelling. This allows runningthe connection through a proxy server.

The host and port arguments specify the endpoint of the tunneled connection(i.e. the address included in the CONNECT request,not the address of theproxy server).

The headers argument should be a mapping of extra HTTP headers to send withthe CONNECT request.

For example, to tunnel through a HTTPS proxy server running locally on port8080, we would pass the address of the proxy to theHTTPSConnectionconstructor, and the address of the host that we eventually want to reach totheset_tunnel() method:

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

New in version 3.2.

HTTPConnection.connect()¶

Connect to the server specified when the object was created.

HTTPConnection.close()¶

Close the connection to the server.

As an alternative to using therequest() method described above, you canalso send your request step by step, by using the four functions below.

HTTPConnection.putrequest(request,selector,skip_host=False,skip_accept_encoding=False)¶

This should be the first call after the connection to the server has been made.It sends a line to the server consisting of therequest string, theselectorstring, and the HTTP version (HTTP/1.1). To disable automatic sending ofHost: orAccept-Encoding: headers (for example to accept additionalcontent encodings), specifyskip_host orskip_accept_encoding with non-Falsevalues.

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

Send anRFC 822-style header to the server. It sends a line to the serverconsisting of the header, a colon and a space, and the first argument. If morearguments are given, continuation lines are sent, each consisting of a tab andan argument.

HTTPConnection.endheaders(message_body=None)¶

Send a blank line to the server, signalling the end of the headers. Theoptionalmessage_body argument can be used to pass a message bodyassociated with the request. The message body will be sent in the samepacket as the message headers if it is string, otherwise it is sent in aseparate packet.

HTTPConnection.send(data)¶

Send data to the server. This should be used directly only after theendheaders() method has been called and beforegetresponse() iscalled.

21.12.2. HTTPResponse Objects¶

AnHTTPResponse instance wraps the HTTP response from theserver. It provides access to the request headers and the entitybody. The response is an iterable object and can be used in a withstatement.

HTTPResponse.read([amt])¶

Reads and returns the response body, or up to the nextamt bytes.

HTTPResponse.readinto(b)¶

Reads up to the next len(b) bytes of the response body into the bufferb.Returns the number of bytes read.

New in version 3.3.

HTTPResponse.getheader(name,default=None)¶

Return the value of the headername, ordefault if there is no headermatchingname. If there is more than one header with the namename,return all of the values joined by ‘, ‘. If ‘default’ is any iterable otherthan a single string, its elements are similarly returned joined by commas.

HTTPResponse.getheaders()¶

Return a list of (header, value) tuples.

HTTPResponse.fileno()¶

Return thefileno of the underlying socket.

HTTPResponse.msg¶

Ahttp.client.HTTPMessage instance containing the responseheaders.http.client.HTTPMessage is a subclass ofemail.message.Message.

HTTPResponse.version¶

HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.

HTTPResponse.status¶

Status code returned by server.

HTTPResponse.reason¶

Reason phrase returned by server.

HTTPResponse.debuglevel¶

A debugging hook. Ifdebuglevel is greater than zero, messageswill be printed to stdout as the response is read and parsed.

HTTPResponse.closed¶

IsTrue if the stream is closed.

21.12.3. Examples¶

Here is an example session that uses theGET method:

>>>importhttp.client>>>conn=http.client.HTTPConnection("www.python.org")>>>conn.request("GET","/index.html")>>>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","/index.html")>>>r1=conn.getresponse()>>>whilenotr1.closed:...print(r1.read(200))# 200 bytesb'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"......>>># Example of an invalid request>>>conn.request("GET","/parrot.spam")>>>r2=conn.getresponse()>>>print(r2.status,r2.reason)404 Not Found>>>data2=r2.read()>>>conn.close()

Here is an example session that uses theHEAD method. Note that theHEAD method never returns any data.

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

Here is an example session that shows how toPOST requests:

>>>importhttp.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()>>>datab'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'>>>conn.close()

Client sideHTTPPUT requests are very similar toPOST requests. Thedifference lies only the server side where HTTP server will allow resources tobe created viaPUT request. It should be noted that custom HTTP methods+are also handled inurllib.request.Request by sending the appropriate+method attribute.Here is an example session that shows how to doPUTrequest using http.client:

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

21.12.4. HTTPMessage Objects¶

Anhttp.client.HTTPMessage instance holds the headers from an HTTPresponse. It is implemented using theemail.message.Message class.