From: Cory Benfield <lukasaoz@gmail.com>
Date: Thu, 24 Oct 2013 20:14:46 +0000 (+0100)
Subject: Improve the PreparedRequest docs.
X-Git-Tag: v2.1.0~33^2^2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=e8683f00a601a59e971e5a31dbb4328f7e5d4acb;p=services%2Fpython-requests.git

Improve the PreparedRequest docs.
---

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index 386e7dd..14e9ac3 100644
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -112,6 +112,36 @@ prepare it immediately and modified the ``PreparedRequest`` object. You then
 send that with the other parameters you would have sent to ``requests.*`` or
 ``Sesssion.*``.
 
+However, the above code will lose some of the advantages of having a Requests
+:class:`Session <requests.Session>` object. In particular,
+:class:`Session <requests.Session>`-level state such as cookies will
+not get applied to your request. To get a
+:class:`PreparedRequest <requests.models.PreparedRequest>` with that state
+applied, replace the call to ``Request.prepare()`` with a call to
+``Session.prepare_request()``, like this::
+
+    from requests import Request, Session
+
+    s = Session()
+    req = Request('GET',  # or any other method, 'POST', 'PUT', etc.
+                  url,
+                  data=data
+                  headers=headers
+                  # ...
+                  )
+    prepped = s.prepare_request(req)
+    # do something with prepped.body
+    # do something with prepped.headers
+    resp = s.send(prepped,
+                  stream=stream,
+                  verify=verify,
+                  proxies=proxies,
+                  cert=cert,
+                  timeout=timeout,
+                  # etc.
+                  )
+    print(resp.status_code)
+
 SSL Cert Verification
 ---------------------