From 7c55446b7ec0978d38fceda5ad4bc45e5b26f1f1 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Wed, 14 Oct 2015 13:23:19 +0100 Subject: [PATCH] Add warnings about text/binary mode files. --- docs/user/advanced.rst | 20 +++++++++++++++++++- docs/user/quickstart.rst | 8 ++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 175fc9b7..62959a93 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -315,6 +315,15 @@ file-like object for your body:: with open('massive-body', 'rb') as f: requests.post('http://some.url/streamed', data=f) +.. warning:: It is strongly recommended that you open files in `binary mode`_. + This is because Requests may attempt to provide the + ``Content-Length`` header for you, and if it does this value will + be set to the number of *bytes* in the file. Errors may occur if + you open the file in *text mode*. + +.. _binary mode: https://docs.python.org/2/tutorial/inputoutput.html#reading-and-writing-files + + .. _chunk-encoding: Chunk-Encoded Requests @@ -362,6 +371,15 @@ To do that, just set files to a list of tuples of (form_field_name, file_info): ... } +.. warning:: It is strongly recommended that you open files in `binary mode`_. + This is because Requests may attempt to provide the + ``Content-Length`` header for you, and if it does this value will + be set to the number of *bytes* in the file. Errors may occur if + you open the file in *text mode*. + +.. _binary mode: https://docs.python.org/2/tutorial/inputoutput.html#reading-and-writing-files + + .. _event-hooks: Event Hooks @@ -519,7 +537,7 @@ any request to the given scheme and exact hostname. } Note that proxy URLs must include the scheme. - + .. _compliance: Compliance diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index d08561d2..75a22ce0 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -302,6 +302,14 @@ support this, but there is a separate package which does - For sending multiple files in one request refer to the :ref:`advanced ` section. +.. warning:: It is strongly recommended that you open files in `binary mode`_. + This is because Requests may attempt to provide the + ``Content-Length`` header for you, and if it does this value will + be set to the number of *bytes* in the file. Errors may occur if + you open the file in *text mode*. + +.. _binary mode: https://docs.python.org/2/tutorial/inputoutput.html#reading-and-writing-files + Response Status Codes ---------------------