HTTPConnection Objects¶

HTTPConnection instances have the following methods:

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

This will send a request to the server using the HTTP requestmethodmethod and the request URIurl. The providedurl must bean absolute path to conform withRFC 2616 §5.1.2(unless connecting to an HTTP proxy server or using theOPTIONS orCONNECT methods).

Ifbody is specified, the specified data is sent after the headers arefinished. It may be astr, abytes-like object, anopenfile object, or an iterable ofbytes. Ifbodyis a string, it is encoded as ISO-8859-1, the default for HTTP. If itis a bytes-like object, the bytes are sent as is. If it is afileobject, the contents of the file is sent; this file object shouldsupport at least theread() method. If the file object is aninstance ofio.TextIOBase, the data returned by theread()method will be encoded as ISO-8859-1, otherwise the data returned byread() is sent as is. Ifbody is an iterable, the elements of theiterable are sent as is until the iterable is exhausted.

Theheaders argument should be a mapping of extra HTTP headers to sendwith the request. AHost headermust be provided to conform withRFC 2616 §5.1.2(unless connecting to an HTTP proxy server or using theOPTIONS orCONNECT methods).

Ifheaders contains neither Content-Length nor Transfer-Encoding,but there is a request body, one of thoseheader fields will be added automatically. Ifbody isNone, the Content-Length header is set to0 formethods that expect a body (PUT,POST, andPATCH). Ifbody is a string or a bytes-like object that is not also afile, the Content-Length header isset to its length. Any other type ofbody (filesand iterables in general) will be chunk-encoded, and theTransfer-Encoding header will automatically be set instead ofContent-Length.

Theencode_chunked argument is only relevant if Transfer-Encoding isspecified inheaders. Ifencode_chunked isFalse, theHTTPConnection object assumes that all encoding is handled by thecalling code. If it isTrue, the body will be chunk-encoded.

For example, to perform aGET request tohttps://docs.python.org/3/:

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

Note

Chunked transfer encoding has been added to the HTTP protocolversion 1.1. Unless the HTTP server is known to handle HTTP 1.1,the caller must either specify the Content-Length, or must pass astr or bytes-like object that is not also a file as thebody representation.

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

Changed in version 3.6:If neither Content-Length nor Transfer-Encoding are set inheaders, file and iterablebody objects are now chunk-encoded.Theencode_chunked argument was added.No attempt is made to determine the Content-Length for fileobjects.

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.

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

Thehost andport arguments specify the endpoint of the tunneled connection(i.e. the address included in the CONNECT request,not the address of theproxy server).

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

As HTTP/1.1 is used for HTTP CONNECT tunnelling request,as per the RFC, a HTTPHost:header must be provided, matching the authority-form of the request targetprovided as the destination for the CONNECT request. If a HTTPHost:header is not provided via the headers argument, one is generated andtransmitted automatically.

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

Added in version 3.2.

Changed in version 3.12:HTTP CONNECT tunnelling requests use protocol HTTP/1.1, upgraded fromprotocol HTTP/1.0.Host: HTTP headers are mandatory for HTTP/1.1, soone will be automatically generated and transmitted if not provided inthe headers argument.

HTTPConnection.get_proxy_response_headers()¶

Returns a dictionary with the headers of the response received fromthe proxy server to the CONNECT request.

If the CONNECT request was not sent, the method returnsNone.

Added in version 3.12.

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.

Raises anauditing eventhttp.client.connect with argumentsself,host,port.

HTTPConnection.close()¶

Close the connection to the server.

HTTPConnection.blocksize¶

Buffer size in bytes for sending a file-like message body.

Added in version 3.7.

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,*,encode_chunked=False)¶

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.

Ifencode_chunked isTrue, the result of each iteration ofmessage_body will be chunk-encoded as specified inRFC 7230,Section 3.3.1. How the data is encoded is dependent on the type ofmessage_body. Ifmessage_body implements thebuffer interface the encoding will result in a single chunk.Ifmessage_body is acollections.abc.Iterable, each iterationofmessage_body will result in a chunk. Ifmessage_body is afile object, each call to.read() will result in a chunk.The method automatically signals the end of the chunk-encoded dataimmediately aftermessage_body.

Note

Due to the chunked encoding specification, empty chunksyielded by an iterator body will be ignored by the chunk-encoder.This is to avoid premature termination of the read of the request bythe target server due to malformed encoding.

Changed in version 3.6:Added chunked encoding support and theencode_chunked parameter.

HTTPConnection.send(data)¶

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

Raises anauditing eventhttp.client.send with argumentsself,data.

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.

Added 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 ‘, ‘. Ifdefault 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.url¶

URL of the resource retrieved, commonly used to determine if a redirect was followed.

HTTPResponse.headers¶

Headers of the response in the form of anemail.message.EmailMessage instance.

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.

HTTPResponse.geturl()¶

Deprecated since version 3.9:Deprecated in favor ofurl.

HTTPResponse.info()¶

Deprecated since version 3.9:Deprecated in favor ofheaders.

HTTPResponse.getcode()¶

Deprecated since version 3.9:Deprecated in favor ofstatus.

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()>>>whilechunk:=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()

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 uses thePOST method:

>>>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="https://bugs.python.org/issue12524">https://bugs.python.org/issue12524</a>'>>>conn.close()

Client side HTTPPUT requests are very similar toPOST requests. Thedifference lies only on the server side where HTTP servers will allow resources tobe created viaPUT requests. It should be noted that custom HTTP methodsare also handled inurllib.request.Request by setting the appropriatemethod attribute. Here is an example session that uses thePUT method:

>>># This creates an HTTP request>>># 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

HTTPMessage Objects¶

classhttp.client.HTTPMessage(email.message.Message)¶

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