@@ -230,6 +230,29 @@ The following exceptions are raised as appropriate:
230230 Previously, :exc: `BadStatusLine `\ ``('') `` was raised.
231231
232232
233+ .. exception :: ProxyTunnelError
234+
235+ A subclass of :exc: `OSError `. Raised when the proxy server answers the
236+ CONNECT request sent for :meth: `HTTPConnection.set_tunnel ` with a status
237+ other than 200.
238+
239+ .. attribute :: code
240+
241+ The HTTP status code of the proxy's response, such as ``407 ``.
242+
243+ .. attribute :: reason
244+
245+ The reason phrase of the proxy's response.
246+
247+ .. attribute :: headers
248+
249+ The headers of the proxy's response, as an
250+ :class: `http.client.HTTPMessage ` instance.
251+
252+ .. versionadded :: next
253+ Previously, :exc: `OSError ` was raised.
254+
255+
233256The constants defined in this module are:
234257
235258.. data :: HTTP_PORT
@@ -259,7 +282,7 @@ HTTPConnection Objects
259282
260283
261284.. method :: HTTPConnection.request(method, url, body=None, headers={}, *, \
262- encode_chunked=False)
285+ encode_chunked=False, continue_timeout=2.5 )
263286
264287 This will send a request to the server using the HTTP request
265288 method *method * and the request URI *url *. The provided *url * must be
@@ -335,11 +358,33 @@ HTTPConnection Objects
335358 No attempt is made to determine the Content-Length for file
336359 objects.
337360
338- .. method :: HTTPConnection.getresponse()
361+ .. versionchanged :: next
362+ The *continue_timeout * parameter was added.
363+
364+ If the headers include ``Expect: 100-Continue `` and *body * is set, the
365+ body will not be sent until either a ``100 Continue `` response is
366+ received from the server or *continue_timeout * seconds have elapsed; if a
367+ response code other than 100 is received, the body will not be sent at all.
368+
369+ *continue_timeout * value must be greater than zero, otherwise
370+ :exc: `ValueError ` is raised.
371+
372+ .. method :: HTTPConnection.getresponse(support_continue=False)
339373
340374 Should be called after a request is sent to get the response from the server.
341375 Returns an :class: `HTTPResponse ` instance.
342376
377+ By default, ``100 Continue `` responses are skipped and the method returns
378+ the first response with a status other than 100. If *support_continue *
379+ is true, a ``100 Continue `` response is returned to the caller, which must
380+ then send the request body and call :meth: `getresponse ` again to obtain
381+ the final response.
382+
383+ .. note ::
384+
385+ The whole response must be read before a new request can be sent to
386+ the server.
387+
343388 .. versionchanged :: 3.5
344389 If a :exc: `ConnectionError ` or subclass is raised, the
345390 :class: `HTTPConnection ` object will be ready to reconnect when
@@ -349,6 +394,10 @@ HTTPConnection Objects
349394 socket. Instead the caller is responsible to call :meth: `close ` on the
350395 existing connection.
351396
397+ .. versionchanged :: next
398+ Added the *support_continue * parameter. (In prior versions
399+ a ``Continue `` response was always ignored.)
400+
352401
353402.. method :: HTTPConnection.set_debuglevel(level)
354403
@@ -398,6 +447,9 @@ HTTPConnection Objects
398447 one will be automatically generated and transmitted if not provided in
399448 the headers argument.
400449
450+ .. versionchanged :: next
451+ :exc: `ProxyTunnelError ` is raised if the proxy rejects the CONNECT request.
452+
401453
402454.. method :: HTTPConnection.get_proxy_response_headers()
403455
@@ -444,7 +496,8 @@ also send your request step by step, by using the four functions below.
444496
445497
446498.. method :: HTTPConnection.putrequest(method, url, skip_host=False, \
447- skip_accept_encoding=False)
499+ skip_accept_encoding=False, \
500+ continue_timeout=2.5)
448501
449502 This should be the first call after the connection to the server has been
450503 made. It sends a line to the server consisting of the *method * string,
@@ -453,6 +506,14 @@ also send your request step by step, by using the four functions below.
453506 additional content encodings), specify *skip_host * or *skip_accept_encoding *
454507 with non-False values.
455508
509+ If an ``Expect: 100-Continue `` header is sent, the optional
510+ *continue_timeout * parameter sets how many seconds the client will wait for
511+ a ``100 Continue `` response before sending the message body, It must be
512+ greater than zero, otherwise :exc: `ValueError ` is raised.
513+
514+ .. versionchanged :: next
515+ *continue_timeout * parameter was added.
516+
456517
457518.. method :: HTTPConnection.putheader(header, argument[, ...])
458519
@@ -466,7 +527,12 @@ also send your request step by step, by using the four functions below.
466527
467528 Send a blank line to the server, signalling the end of the headers. The
468529 optional *message_body * argument can be used to pass a message body
469- associated with the request.
530+ associated with the request. If a body is provided and an
531+ ``Expect: 100-Continue `` header has been sent, the body will not be sent
532+ until a ``100 Continue `` response is received from the server; if another
533+ response code is received, the body is not sent at all. If no response
534+ is received within the *continue_timeout * given to :meth: `putrequest `,
535+ the body will be sent regardless.
470536
471537 If *encode_chunked * is ``True ``, the result of each iteration of
472538 *message_body * will be chunk-encoded as specified in :rfc: `7230 `,
@@ -487,6 +553,12 @@ also send your request step by step, by using the four functions below.
487553 .. versionchanged :: 3.6
488554 Added chunked encoding support and the *encode_chunked * parameter.
489555
556+ .. versionchanged :: next
557+ If an ``Expect: 100-Continue `` header has been sent, the body will not be
558+ sent until a ``100 Continue `` response is received from the server, or a
559+ contine_timeout has elapsed. If the response code is not 100, the body
560+ will not be sent at all.
561+
490562
491563.. method :: HTTPConnection.send(data)
492564
@@ -665,6 +737,46 @@ method attribute. Here is an example session that uses the ``PUT`` method::
665737 >>> print(response.status, response.reason)
666738 200 OK
667739
740+ Conditional transmission of the body is supported when an ``Expect: 100-Continue ``
741+ header is set. To use this in a simple case, just set the header, and
742+ optionally the time for which the client should wait for a ``100 Continue ``
743+ response before sending the body regardless::
744+
745+ >>> import http.client
746+ >>> BODY = "***filecontents***"
747+ >>> conn = http.client.HTTPConnection("localhost", 8080)
748+ >>> conn.request("PUT", "/file", BODY, headers={'Expect': '100-Continue'},
749+ ... continue_timeout=1.0)
750+ >>> response = conn.getresponse()
751+ >>> # You will not see the '100' response, as it is handled internally
752+ >>> print(response.status, response.reason)
753+ 200, OK
754+
755+ Here is a more complex example in which we manually check the response and
756+ decide whether to send the body. This may be useful if the body must be
757+ generated by some resource-intensive process which should be skipped if the
758+ server will not accept it. *continue_timeout * does not apply here, so this
759+ should only be used with servers known to support ``Expect: 100-Continue ``;
760+ otherwise :meth: `~HTTPConnection.getresponse ` may block until the
761+ connection's *timeout * expires. ::
762+
763+ >>> import http.client
764+ >>> conn = http.client.HTTPConnection("localhost", 8080)
765+ >>> conn.putrequest("PUT", "/file")
766+ >>> conn.putheader('Expect', '100-Continue')
767+ >>> # Assuming you know in advance what the length will be
768+ >>> # If not, you will need to encode it as chunked
769+ >>> conn.putheader('Content-Length', '42')
770+ >>> conn.endheaders()
771+ >>> response = conn.getresponse(support_continue=True)
772+ >>> print(response.status, response.reason)
773+ 100, Continue
774+ >>> BODY = resource_intensive_calculation()
775+ >>> conn.send(BODY)
776+ >>> response = conn.getresponse()
777+ >>> print(response.status, response.reason)
778+ 200, OK
779+
668780.. _httpmessage-objects :
669781
670782HTTPMessage Objects
0 commit comments