Issue #12319: Support for chunked encoding of HTTP request bodies · python/cpython@3c0d0ba (original) (raw)

`@@ -219,39 +219,62 @@ HTTPConnection Objects

219

`` :class:HTTPConnection instances have the following methods:

220

221

222

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

222

.. method:: HTTPConnection.request(method, url, body=None, headers={}, *, \

223

encode_chunked=False)

223

224

225

` This will send a request to the server using the HTTP request

225

226

` method method and the selector url.

226

227

228

` If body is specified, the specified data is sent after the headers are

228

`` -

finished. It may be a string, a :term:bytes-like object, an open

229

`` -

:term:file object, or an iterable of :term:bytes-like object\s. If

230

body is a string, it is encoded as ISO-8859-1, the default for HTTP. If

231

`` -

it is a bytes-like object the bytes are sent as is. If it is a :term:`file

232

`` -

object`, the contents of the file is sent; this file object should support

233


 at least the ``read()`` method. If the file object has a ``mode``

234


 attribute, the data returned by the ``read()`` method will be encoded as

235


 ISO-8859-1 unless the ``mode`` attribute contains the substring ``b``,

236


 otherwise the data returned by ``read()`` is sent as is. If *body* is an

237

iterable, the elements of the iterable are sent as is until the iterable is

238

exhausted.

239

-

240

The headers argument should be a mapping of extra HTTP

241

headers to send with the request.

242

-

243

If headers does not contain a Content-Length item, one is added

244


 automatically if possible. If *body* is ``None``, the Content-Length header

245


 is set to ``0`` for methods that expect a body (``PUT``, ``POST``, and

246


 ``PATCH``). If *body* is a string or bytes object, the Content-Length

247

`` -

header is set to its length. If body is a :term:file object and it

248


 works to call :func:`~os.fstat` on the result of its ``fileno()`` method,

249


 then the Content-Length header is set to the ``st_size`` reported by the

250


 ``fstat`` call. Otherwise no Content-Length header is added.

229

`` +

finished. It may be a :class:str, a :term:bytes-like object, an

230

`` +

open :term:file object, or an iterable of :class:bytes. If body

231

is a string, it is encoded as ISO-8859-1, the default for HTTP. If it

232

`` +

is a bytes-like object, the bytes are sent as is. If it is a :term:`file

233

`` +

object`, the contents of the file is sent; this file object should

234


 support at least the ``read()`` method. If the file object is an

235


 instance of :class:`io.TextIOBase`, the data returned by the ``read()``

236

method will be encoded as ISO-8859-1, otherwise the data returned by

237


 ``read()`` is sent as is. If *body* is an iterable, the elements of the

238

iterable are sent as is until the iterable is exhausted.

239

+

240

The headers argument should be a mapping of extra HTTP headers to send

241

with the request.

242

+

243

If headers contains neither Content-Length nor Transfer-Encoding, a

244

Content-Length header will be added automatically if possible. If

245


 *body* is ``None``, the Content-Length header is set to ``0`` for

246


 methods that expect a body (``PUT``, ``POST``, and ``PATCH``). If

247

body is a string or bytes-like object, the Content-Length header is

248

`` +

set to its length. If body is a binary :term:file object

249

`` +

supporting :meth:~io.IOBase.seek, this will be used to determine

250

its size. Otherwise, the Content-Length header is not added

251

automatically. In cases where determining the Content-Length up

252

front is not possible, the body will be chunk-encoded and the

253

Transfer-Encoding header will automatically be set.

254

+

255

The encode_chunked argument is only relevant if Transfer-Encoding is

256


 specified in *headers*. If *encode_chunked* is ``False``, the

257

HTTPConnection object assumes that all encoding is handled by the

258


 calling code. If it is ``True``, the body will be chunk-encoded.

259

+

260

.. note::

261

Chunked transfer encoding has been added to the HTTP protocol

262

version 1.1. Unless the HTTP server is known to handle HTTP 1.1,

263

the caller must either specify the Content-Length or must use a

264

body representation whose length can be determined automatically.

251

265

252

266

` .. versionadded:: 3.2

253

267

` body can now be an iterable.

254

268

269

.. versionchanged:: 3.6

270

If neither Content-Length nor Transfer-Encoding are set in

271

headers and Content-Length cannot be determined, body will now

272

be automatically chunk-encoded. The encode_chunked argument

273

was added.

274

The Content-Length for binary file objects is determined with seek.

275

No attempt is made to determine the Content-Length for text file

276

objects.

277

+

255

278

`.. method:: HTTPConnection.getresponse()

256

279

257

280

` Should be called after a request is sent to get the response from the server.

`@@ -336,13 +359,32 @@ also send your request step by step, by using the four functions below.

336

359

` an argument.

337

360

338

361

339

.. method:: HTTPConnection.endheaders(message_body=None)

362

.. method:: HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)

340

363

341

364

` Send a blank line to the server, signalling the end of the headers. The

342

365

` optional message_body argument can be used to pass a message body

343

associated with the request. The message body will be sent in the same

344

packet as the message headers if it is string, otherwise it is sent in a

345

separate packet.

366

associated with the request.

367

+

368


 If *encode_chunked* is ``True``, the result of each iteration of

369

`` +

message_body will be chunk-encoded as specified in :rfc:7230,

370

Section 3.3.1. How the data is encoded is dependent on the type of

371

`` +

message_body. If message_body implements the :ref:`buffer interface

372

`` +

` the encoding will result in a single chunk.

373

`` +

If message_body is a :class:collections.Iterable, each iteration

374

of message_body will result in a chunk. If message_body is a

375


:term:`file object`, each call to ``.read()`` will result in a chunk.

376

The method automatically signals the end of the chunk-encoded data

377

immediately after message_body.

378

+

379

.. note:: Due to the chunked encoding specification, empty chunks

380

yielded by an iterator body will be ignored by the chunk-encoder.

381

This is to avoid premature termination of the read of the request by

382

the target server due to malformed encoding.

383

+

384

.. versionadded:: 3.6

385

Chunked encoding support. The encode_chunked parameter was

386

added.

387

+

346

388

347

389

`.. method:: HTTPConnection.send(data)

348

390