Skip to content

Scrapy, a fast high-level web crawling & scraping framework for Python.

request-response.rst: review type references around body mentions

Adrián Chavesbbd9d05dbff7
diff --git a/docs/topics/request-response.rst b/docs/topics/request-response.rst
index 1638c202d..4fec70e13 100644
--- a/docs/topics/request-response.rst
+++ b/docs/topics/request-response.rst
@@ -51,12 +51,10 @@ Request objects
given, the dict passed in this parameter will be shallow copied.
:type meta: dict
- :param body: the request body. If a ``unicode`` is passed, then it's encoded to
- ``str`` using the ``encoding`` passed (which defaults to ``utf-8``). If
- ``body`` is not given, an empty string is stored. Regardless of the
- type of this argument, the final value stored will be a ``str`` (never
- ``unicode`` or ``None``).
- :type body: str
+ :param body: the request body. If a string is passed, it is converted to
+ bytes using *encoding*, which defaults to ``utf-8``. If not passed or
+ ``None`` is passed, an empty bytes array is stored.
+ :type body: bytes
:param headers: the headers of this request. The dict values can be strings
(for single valued headers) or lists (for multi-valued headers). If
@@ -106,7 +104,7 @@ Request objects
:param encoding: the encoding of this request (defaults to ``'utf-8'``).
This encoding will be used to percent-encode the URL and to convert the
- body to ``str`` (if given as ``unicode``).
+ body to bytes if given as a string.
:type encoding: str
:param priority: the priority of this request (defaults to ``0``).
@@ -159,7 +157,7 @@ Request objects
.. attribute:: Request.body
- A str that contains the request body.
+ The request body as bytes.
This attribute is read-only. To change the body of a Request use
:meth:`replace`.
@@ -598,7 +596,7 @@ Response objects
(for single valued headers) or lists (for multi-valued headers).
:type headers: dict
- :param body: the response body. To access the decoded text as str you can use
+ :param body: the response body. To access the decoded text as a string, use
``response.text`` from an encoding-aware
:ref:`Response subclass <topics-request-response-ref-response-subclasses>`,
such as :class:`TextResponse`.
@@ -646,10 +644,10 @@ Response objects
.. attribute:: Response.body
- The body of this Response. Keep in mind that Response.body
- is always a bytes object. If you want the unicode version use
- :attr:`TextResponse.text` (only available in :class:`TextResponse`
- and subclasses).
+ The response body as bytes.
+
+ If you want the body as a string, use :attr:`TextResponse.text` (only
+ available in :class:`TextResponse` and subclasses).
This attribute is read-only. To change the body of a Response use
:meth:`replace`.
@@ -768,10 +766,10 @@ TextResponse objects
is the same as for the :class:`Response` class and is not documented here.
:param encoding: is a string which contains the encoding to use for this
- response. If you create a :class:`TextResponse` object with a unicode
- body, it will be encoded using this encoding (remember the body attribute
- is always a string). If ``encoding`` is ``None`` (default value), the
- encoding will be looked up in the response headers and body instead.
+ response. If you create a :class:`TextResponse` object with a string as
+ body, it will be converted to bytes encoded using this encoding. If
+ *encoding* is ``None`` (default), the encoding will be looked up in the
+ response headers and body instead.
:type encoding: str
:class:`TextResponse` objects support the following attributes in addition
@@ -779,7 +777,7 @@ TextResponse objects
.. attribute:: TextResponse.text
- Response body, as unicode.
+ Response body as a string.
The same as ``response.body.decode(response.encoding)``, but the
result is cached after the first call, so you can access
@@ -787,8 +785,8 @@ TextResponse objects
.. note::
- ``unicode(response.body)`` is not a correct way to convert response
- body to unicode: you would be using the system default encoding
+ ``str(response.body)`` is not a correct way to convert the response
+ body into a string: you would be using the system default encoding
(typically ``ascii``) instead of the response encoding.