summaryrefslogtreecommitdiff
path: root/docs/user
diff options
context:
space:
mode:
authorDavid Pursehouse <david.pursehouse@sonymobile.com>2014-07-18 16:35:54 +0900
committerDavid Pursehouse <david.pursehouse@sonymobile.com>2014-07-18 16:35:54 +0900
commit44e426e4ff7c8f4113d3754becc5678db1c0db6f (patch)
treeb8be7da1633d82d0e856251b9a36f181bb5cd39d /docs/user
parent587a5153f0dbb0429a43f90ebef0326e27443bc0 (diff)
downloadpython-requests-44e426e4ff7c8f4113d3754becc5678db1c0db6f.tar.gz
More line wrapping
Change-Id: I950c3da727fb97b58d96a872b0d2ed718cc60ba8
Diffstat (limited to 'docs/user')
-rw-r--r--docs/user/advanced.rst49
-rw-r--r--docs/user/quickstart.rst3
2 files changed, 38 insertions, 14 deletions
diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index 95dd6be6..7b315433 100644
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -37,13 +37,18 @@ is done by providing data to the properties on a Session object::
s.get('http://httpbin.org/headers', headers={'x-test2': 'true'})
-Any dictionaries that you pass to a request method will be merged with the session-level values that are set. The method-level parameters override session parameters.
+Any dictionaries that you pass to a request method will be merged with the
+session-level values that are set. The method-level parameters override session
+parameters.
.. admonition:: Remove a Value From a Dict Parameter
- Sometimes you'll want to omit session-level keys from a dict parameter. To do this, you simply set that key's value to ``None`` in the method-level parameter. It will automatically be omitted.
+ Sometimes you'll want to omit session-level keys from a dict parameter. To
+ do this, you simply set that key's value to ``None`` in the method-level
+ parameter. It will automatically be omitted.
-All values that are contained within a session are directly available to you. See the :ref:`Session API Docs <sessionapi>` to learn more.
+All values that are contained within a session are directly available to you.
+See the :ref:`Session API Docs <sessionapi>` to learn more.
Request and Response Objects
----------------------------
@@ -150,7 +155,8 @@ applied, replace the call to :meth:`Request.prepare()
SSL Cert Verification
---------------------
-Requests can verify SSL certificates for HTTPS requests, just like a web browser. To check a host's SSL certificate, you can use the ``verify`` argument::
+Requests can verify SSL certificates for HTTPS requests, just like a web browser.
+To check a host's SSL certificate, you can use the ``verify`` argument::
>>> requests.get('https://kennethreitz.com', verify=True)
requests.exceptions.SSLError: hostname 'kennethreitz.com' doesn't match either of '*.herokuapp.com', 'herokuapp.com'
@@ -171,7 +177,9 @@ Requests can also ignore verifying the SSL certificate if you set ``verify`` to
By default, ``verify`` is set to True. Option ``verify`` only applies to host certs.
-You can also specify a local cert to use as client side certificate, as a single file (containing the private key and the certificate) or as a tuple of both file's path::
+You can also specify a local cert to use as client side certificate, as a single
+file (containing the private key and the certificate) or as a tuple of both
+file's path::
>>> requests.get('https://kennethreitz.com', cert=('/path/server.crt', '/path/key'))
<Response [200]>
@@ -193,13 +201,18 @@ attribute with the ``stream`` parameter::
tarball_url = 'https://github.com/kennethreitz/requests/tarball/master'
r = requests.get(tarball_url, stream=True)
-At this point only the response headers have been downloaded and the connection remains open, hence allowing us to make content retrieval conditional::
+At this point only the response headers have been downloaded and the connection
+remains open, hence allowing us to make content retrieval conditional::
if int(r.headers['content-length']) < TOO_LONG:
content = r.content
...
-You can further control the workflow by use of the :class:`Response.iter_content <requests.Response.iter_content>` and :class:`Response.iter_lines <requests.Response.iter_lines>` methods. Alternatively, you can read the undecoded body from the underlying urllib3 :class:`urllib3.HTTPResponse <urllib3.response.HTTPResponse>` at :class:`Response.raw <requests.Response.raw>`.
+You can further control the workflow by use of the :class:`Response.iter_content <requests.Response.iter_content>`
+and :class:`Response.iter_lines <requests.Response.iter_lines>` methods.
+Alternatively, you can read the undecoded body from the underlying
+urllib3 :class:`urllib3.HTTPResponse <urllib3.response.HTTPResponse>` at
+:class:`Response.raw <requests.Response.raw>`.
If you set ``stream`` to ``True`` when making a request, Requests cannot
release the connection back to the pool unless you consume all the data or call
@@ -219,15 +232,21 @@ consider using ``contextlib.closing`` (`documented here`_), like this::
Keep-Alive
----------
-Excellent news — thanks to urllib3, keep-alive is 100% automatic within a session! Any requests that you make within a session will automatically reuse the appropriate connection!
+Excellent news — thanks to urllib3, keep-alive is 100% automatic within a session!
+Any requests that you make within a session will automatically reuse the appropriate
+connection!
-Note that connections are only released back to the pool for reuse once all body data has been read; be sure to either set ``stream`` to ``False`` or read the ``content`` property of the ``Response`` object.
+Note that connections are only released back to the pool for reuse once all body
+data has been read; be sure to either set ``stream`` to ``False`` or read the
+``content`` property of the ``Response`` object.
Streaming Uploads
-----------------
-Requests supports streaming uploads, which allow you to send large streams or files without reading them into memory. To stream and upload, simply provide a file-like object for your body::
+Requests supports streaming uploads, which allow you to send large streams or
+files without reading them into memory. To stream and upload, simply provide a
+file-like object for your body::
with open('massive-body', 'rb') as f:
requests.post('http://some.url/streamed', data=f)
@@ -236,7 +255,9 @@ Requests supports streaming uploads, which allow you to send large streams or fi
Chunk-Encoded Requests
----------------------
-Requests also supports Chunked transfer encoding for outgoing and incoming requests. To send a chunk-encoded request, simply provide a generator (or any iterator without a length) for your body::
+Requests also supports Chunked transfer encoding for outgoing and incoming requests.
+To send a chunk-encoded request, simply provide a generator (or any iterator without
+a length) for your body::
def gen():
@@ -579,9 +600,11 @@ kinds of exciting ways, 4995 more times.
Link Headers
------------
-Many HTTP APIs feature Link headers. They make APIs more self describing and discoverable.
+Many HTTP APIs feature Link headers. They make APIs more self describing and
+discoverable.
-GitHub uses these for `pagination <http://developer.github.com/v3/#pagination>`_ in their API, for example::
+GitHub uses these for `pagination <http://developer.github.com/v3/#pagination>`_
+in their API, for example::
>>> url = 'https://api.github.com/users/kennethreitz/repos?page=1&per_page=10'
>>> r = requests.head(url=url)
diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst
index b1fe9344..6217ceb2 100644
--- a/docs/user/quickstart.rst
+++ b/docs/user/quickstart.rst
@@ -204,7 +204,8 @@ dictionary of data will automatically be form-encoded when the request is made::
...
}
-There are many times that you want to send data that is not form-encoded. If you pass in a ``string`` instead of a ``dict``, that data will be posted directly.
+There are many times that you want to send data that is not form-encoded. If
+you pass in a ``string`` instead of a ``dict``, that data will be posted directly.
For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data::