From 4a6a0c3c65be2033e11130125601a6c810ea5d10 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Fri, 20 Dec 2013 09:15:12 +0000 Subject: [PATCH] Update docs to highlight the value of r.encoding. --- docs/user/quickstart.rst | 15 ++++++++++----- requests/models.py | 5 +++++ 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index cd1a5ea..78b2cc6 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -99,7 +99,12 @@ using, and change it, using the ``r.encoding`` property:: >>> r.encoding = 'ISO-8859-1' If you change the encoding, Requests will use the new value of ``r.encoding`` -whenever you call ``r.text``. +whenever you call ``r.text``. You might want to do this in any situation where +you can apply special logic to work out what the encoding of the content will +be. For example, HTTP and XML have the ability to specify their encoding in +their body. In situations like this, you should use ``r.content`` to find the +encoding, and then set ``r.encoding``. This will let you use ``r.text`` with +the correct encoding. Requests will also use custom encodings in the event that you need them. If you have created your own encoding and registered it with the ``codecs`` @@ -152,16 +157,16 @@ server, you can access ``r.raw``. If you want to do this, make sure you set >>> r.raw.read(10) '\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03' -In general, however, you should use a pattern like this to save what is being +In general, however, you should use a pattern like this to save what is being streamed to a file:: with open(filename, 'wb') as fd: for chunk in r.iter_content(chunk_size): fd.write(chunk) -Using ``Response.iter_content`` will handle a lot of what you would otherwise -have to handle when using ``Response.raw`` directly. When streaming a -download, the above is the preferred and recommended way to retrieve the +Using ``Response.iter_content`` will handle a lot of what you would otherwise +have to handle when using ``Response.raw`` directly. When streaming a +download, the above is the preferred and recommended way to retrieve the content. diff --git a/requests/models.py b/requests/models.py index 1fdf43a..061c93b 100644 --- a/requests/models.py +++ b/requests/models.py @@ -692,6 +692,11 @@ class Response(object): If Response.encoding is None, encoding will be guessed using ``chardet``. + + The encoding of the response content is determined based soley on HTTP + headers, following RFC 2616 to the letter. If you can take advantage of + non-HTTP knowledge to make a better guess at the encoding, you should + set ``r.encoding`` appropriately before accessing this property. """ # Try charset from content-type -- 2.7.4