From d333f179f34fdb7d493475bb4a86cdc16b0927a6 Mon Sep 17 00:00:00 2001 From: Jamie Lennox Date: Wed, 1 Feb 2017 15:43:08 +1100 Subject: [PATCH] Add documentation for the exception response There was no documentation on how to use the exc= parameter. Add some simple docs so people at least know that it's there. Change-Id: I743e6899c2fe611790a7880bd909bb1260f9de52 Closes-Bug: #1625580 --- doc/source/response.rst | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/doc/source/response.rst b/doc/source/response.rst index af8fb02..bbf5a92 100644 --- a/doc/source/response.rst +++ b/doc/source/response.rst @@ -43,6 +43,7 @@ To specify the body of the response there are a number of options that depend on :content: A byte string. This should be used for including binary data in responses. :body: A file like object that contains a `.read()` function. :raw: A prepopulated :py:class:`urllib3.response.HTTPResponse` to be returned. +:exc: An exception that will be raised instead of returning a response. These options are named to coincide with the parameters on a :py:class:`requests.Response` object. For example: @@ -133,6 +134,20 @@ Callbacks work within response lists in exactly the same way they do normally; >>> resp.status_code, resp.headers, resp.text (200, {'Test1': 'value1', 'Test2': 'value2'}, 'response') +Raising Exceptions +================== + +When trying to emulate a connection timeout or SSLError you need to be able to throw an exception when a mock is hit. +This can be achieved by passing the `exc` parameter instead of a body parameter. + +.. doctest:: + + >>> adapter.register_uri('GET', 'mock://test.com/6', exc=requests.exceptions.ConnectTimeout), + >>> session.get('mock://test.com/6') + Traceback (most recent call last): + ... + ConnectTimeout: + Handling Cookies ================ @@ -145,8 +160,8 @@ This method does not allow you to set any of the more advanced cookie parameters .. doctest:: - >>> adapter.register_uri('GET', 'mock://test.com/6', cookies={'foo': 'bar'}), - >>> resp = session.get('mock://test.com/6') + >>> adapter.register_uri('GET', 'mock://test.com/7', cookies={'foo': 'bar'}), + >>> resp = session.get('mock://test.com/7') >>> resp.cookies['foo'] 'bar' @@ -156,8 +171,8 @@ The more advanced way is to construct and populate a cookie jar that you can add >>> jar = requests_mock.CookieJar() >>> jar.set('foo', 'bar', domain='.test.com', path='/baz') - >>> adapter.register_uri('GET', 'mock://test.com/7', cookies=jar), - >>> resp = session.get('mock://test.com/7') + >>> adapter.register_uri('GET', 'mock://test.com/8', cookies=jar), + >>> resp = session.get('mock://test.com/8') >>> resp.cookies['foo'] 'bar' >>> resp.cookies.list_paths()