See also

TheRequests packageis recommended for a higher-level HTTP client interface.

Note

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

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.

Ifbody is specified, the specified data is sent after the headers arefinished. It may be a string, abytes-like object, an openfile object, or an iterable ofbytes-like objects. Ifbody is a string, it is encoded as ISO-8859-1, the default for HTTP. Ifit is a bytes-like object the bytes are sent as is. If it is afileobject, the contents of the file is sent; this file object should supportat least theread() method. If the file object has amodeattribute, the data returned by theread() method will be encoded asISO-8859-1 unless themode attribute contains the substringb,otherwise the data returned byread() is sent as is. Ifbody is aniterable, the elements of the iterable are sent as is until the iterable isexhausted.

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

Ifheaders does not contain a Content-Length item, one is addedautomatically if possible. Ifbody isNone, the Content-Length headeris set to0 for methods that expect a body (PUT,POST, andPATCH). Ifbody is a string or bytes object, the Content-Lengthheader is set to its length. Ifbody is afile object and itworks to callfstat() on the result of itsfileno() method,then the Content-Length header is set to thest_size reported by thefstat call. Otherwise no Content-Length header is added.

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.

Changed in version 3.5:If aConnectionError or subclass is raised, theHTTPConnection object will be ready to reconnect whena new request is sent.

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. By default,this is called automatically when making a request if the client does notalready have a connection.

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(method,url,skip_host=False,skip_accept_encoding=False)¶

This should be the first call after the connection to the server has beenmade. It sends a line to the server consisting of themethod string,theurl string, and the HTTP version (HTTP/1.1). To disable automaticsending ofHost: orAccept-Encoding: headers (for example to acceptadditional content encodings), specifyskip_host orskip_accept_encodingwith non-False values.

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.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()>>>whilenotr1.closed:...print(r1.read(200))# 200 bytesb'<!doctype html>\n<!--[if"......>>># 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.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

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/file...>>>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.