From 1451ba0c6d395c41f86da35036fa361c3a41bc90 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Mon, 17 Dec 2012 08:33:18 -0500 Subject: [PATCH] update docs --- docs/user/advanced.rst | 86 +++++------------------------------------------- docs/user/quickstart.rst | 4 +-- requests/models.py | 11 ++----- requests/sessions.py | 7 ++-- 4 files changed, 17 insertions(+), 91 deletions(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index f9f314a..1947bf3 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -116,10 +116,10 @@ If you specify a wrong path or an invalid cert:: Body Content Workflow --------------------- -By default, when you make a request, the body of the response is downloaded immediately. You can override this behavior and defer downloading the response body until you access the :class:`Response.content` attribute with the ``prefetch`` parameter:: +By default, when you make a request, the body of the response is downloaded immediately. You can override this behavior and defer downloading the response body until you access the :class:`Response.content` attribute with the ``stream`` parameter:: tarball_url = 'https://github.com/kennethreitz/requests/tarball/master' - r = requests.get(tarball_url, prefetch=False) + 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:: @@ -129,8 +129,6 @@ At this point only the response headers have been downloaded and the connection You can further control the workflow by use of the :class:`Response.iter_content` and :class:`Response.iter_lines` methods, or reading from the underlying urllib3 :class:`urllib3.HTTPResponse` at :class:`Response.raw`. -Note that in versions prior to 0.13.6 the ``prefetch`` default was set to ``False``. - Configuring Requests -------------------- @@ -143,19 +141,7 @@ 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! -Note that connections are only released back to the pool for reuse once all body data has been read; be sure to either set ``prefetch`` to ``True`` or read the ``content`` property of the ``Response`` object. - -If you'd like to disable keep-alive, you can simply set the ``keep_alive`` configuration to ``False``:: - - s = requests.session() - s.config['keep_alive'] = False - - -Asynchronous Requests ----------------------- - - -``requests.async`` has been removed from requests and is now its own repository named `GRequests `_. +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. Event Hooks @@ -166,15 +152,6 @@ the request process, or signal event handling. Available hooks: -``args``: - A dictionary of the arguments being sent to Request(). - -``pre_request``: - The Request object, directly before being sent. - -``post_request``: - The Request object, directly after being sent. - ``response``: The response generated from a Request. @@ -183,15 +160,15 @@ You can assign a hook function on a per-request basis by passing a ``{hook_name: callback_function}`` dictionary to the ``hooks`` request parameter:: - hooks=dict(args=print_url) + hooks=dict(response=print_url) That ``callback_function`` will receive a chunk of data as its first argument. :: - def print_url(args): - print args['url'] + def print_url(r): + print(r.url) If an error occurs while executing your callback, a warning is given. @@ -201,41 +178,10 @@ anything, nothing else is effected. Let's print some request method arguments at runtime:: - >>> requests.get('http://httpbin.org', hooks=dict(args=print_url)) + >>> requests.get('http://httpbin.org', hooks=dict(response=print_url)) http://httpbin.org -Let's hijack some arguments this time with a new callback:: - - def hack_headers(args): - if args.get('headers') is None: - args['headers'] = dict() - - args['headers'].update({'X-Testing': 'True'}) - - return args - - hooks = dict(args=hack_headers) - headers = dict(yo=dawg) - -And give it a try:: - - >>> requests.get('http://httpbin.org/headers', hooks=hooks, headers=headers) - { - "headers": { - "Content-Length": "", - "Accept-Encoding": "gzip", - "Yo": "dawg", - "X-Forwarded-For": "::ffff:24.127.96.129", - "Connection": "close", - "User-Agent": "python-requests.org", - "Host": "httpbin.org", - "X-Testing": "True", - "X-Forwarded-Protocol": "", - "Content-Type": "" - } - } - Custom Authentication --------------------- @@ -283,27 +229,13 @@ To use the Twitter Streaming API to track the keyword "requests":: import json r = requests.post('https://stream.twitter.com/1/statuses/filter.json', - data={'track': 'requests'}, auth=('username', 'password'), prefetch=False) + data={'track': 'requests'}, auth=('username', 'password'), stream=True) for line in r.iter_lines(): if line: # filter out keep-alive new lines print json.loads(line) -Verbose Logging ---------------- - -If you want to get a good look at what HTTP requests are being sent -by your application, you can turn on verbose logging. - -To do so, just configure Requests with a stream to write to:: - - >>> my_config = {'verbose': sys.stderr} - >>> requests.get('http://httpbin.org/headers', config=my_config) - 2011-08-17T03:04:23.380175 GET http://httpbin.org/headers - - - Proxies ------- @@ -349,7 +281,7 @@ Encodings When you receive a response, Requests makes a guess at the encoding to use for decoding the response when you call the ``Response.text`` method. Requests will first check for an encoding in the HTTP header, and if none is present, -will use `chardet `_ to attempt to guess +will use `charade `_ to attempt to guess the encoding. The only time Requests will not do this is if no explicit charset is present diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index 31848b0..beb05a5 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -139,9 +139,9 @@ Raw Response Content In the rare case that you'd like to get the raw socket response from the server, you can access ``r.raw``. If you want to do this, make sure you set -``prefetch=False`` in your initial request. Once you do, you can do this:: +``stream=True`` in your initial request. Once you do, you can do this:: - >>> r = requests.get('https:/github.com/timeline.json', prefetch=False) + >>> r = requests.get('https:/github.com/timeline.json', stream=True) >>> r.raw >>> r.raw.read(10) diff --git a/requests/models.py b/requests/models.py index b957ac3..3857202 100644 --- a/requests/models.py +++ b/requests/models.py @@ -528,7 +528,6 @@ class Response(object): return content - @property def json(self): """Returns the json-encoded content of a response, if any.""" @@ -539,14 +538,8 @@ class Response(object): # a best guess). encoding = guess_json_utf(self.content) if encoding is not None: - try: - return json.loads(self.content.decode(encoding)) - except (ValueError, UnicodeDecodeError): - pass - try: - return json.loads(self.text or self.content) - except ValueError: - return None + return json.loads(self.content.decode(encoding)) + return json.loads(self.text or self.content) @property def links(self): diff --git a/requests/sessions.py b/requests/sessions.py index 620355d..b970e0d 100644 --- a/requests/sessions.py +++ b/requests/sessions.py @@ -62,7 +62,7 @@ def merge_kwargs(local_kwarg, default_kwarg): class SessionRedirectMixin(object): - def resolve_redirects(self, resp, req, stream=False, timeout=None, verify=True, cert=None): + def resolve_redirects(self, resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None): """Receives a Response. Returns a generator of Responses.""" i = 0 @@ -125,7 +125,8 @@ class SessionRedirectMixin(object): stream=stream, timeout=timeout, verify=verify, - cert=cert + cert=cert, + proxies=proxies ) i += 1 @@ -255,7 +256,7 @@ class Session(SessionRedirectMixin): resp = self.send(prep, stream=stream, timeout=timeout, verify=verify, cert=cert, proxies=proxies) # Redirect resolving generator. - gen = self.resolve_redirects(resp, req, stream, timeout, verify, cert) + gen = self.resolve_redirects(resp, req, stream=stream, timeout=timeout, verify=verify, cert=cert, proxies=proxies) # Resolve redirects if allowed. history = [r for r in gen] if allow_redirects else [] -- 2.7.4