From 73c056efe0376f01007c519075f97945f2c3e7fd Mon Sep 17 00:00:00 2001 From: Petre Mierlutiu Date: Mon, 27 Sep 2021 20:48:14 +0300 Subject: [PATCH] a few minor fixes and proposed changes to documentation files --- doc/source/history.rst | 20 ++++++++++---------- doc/source/matching.rst | 14 +++++++------- doc/source/mocker.rst | 4 ++-- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/doc/source/history.rst b/doc/source/history.rst index 79cb2ba..55c7137 100644 --- a/doc/source/history.rst +++ b/doc/source/history.rst @@ -7,7 +7,7 @@ The object returned from creating a mock or registering a URI in an adapter is c Called ====== -The easiest way to test if a request hit the adapter is to simply check the called property or the call_count property. +The easiest way to test if a request hit the adapter is to simply check the :py:attr:`called` property or the :py:attr:`call_count` property. .. doctest:: @@ -26,7 +26,7 @@ The easiest way to test if a request hit the adapter is to simply check the call Request Objects =============== -The history of objects that passed through the `mocker`/`adapter` can also be retrieved +The history of objects that passed through the `mocker`/`adapter` can also be retrieved. .. doctest:: @@ -40,7 +40,7 @@ The history of objects that passed through the `mocker`/`adapter` can also be re The alias `last_request` is also available for the last request to go through the mocker. -This request object is a wrapper around a standard :py:class:`requests.Request` object with some additional information that make the interface more workable (as the :py:class:`~requests.Request` object is generally not dealt with by users. +This request object is a wrapper around a standard :py:class:`requests.Request` object with some additional information that make the interface more workable (as users do not generally deal with the :py:class:`~requests.Request` object). These additions include: @@ -54,25 +54,25 @@ These additions include: >>> m.last_request.scheme 'http' - >>> m.last_request.netloc + >>> m.last_request.hostname 'test.com' The following parameters of the :py:func:`requests.request` call are also exposed via the request object: :timeout: How long to wait for the server to send data before giving up. -:allow_redirects: Set to True if POST/PUT/DELETE redirect following is allowed. +:allow_redirects: Set to :py:const:`True` if POST/PUT/DELETE redirect following is allowed. :proxies: Dictionary mapping protocol to the URL of the proxy. -:verify: whether the SSL cert will be verified. +:verify: Whether the SSL certificate will be verified. :cert: The client certificate or cert/key tuple for this request. -Note: That the default value of these attributes are the values that are passed to the adapter and not what is passed to the request method. This means that the default for allow_redirects is None (even though that is interpretted as True) if unset, whereas the defautl for verify is True, and the default for proxies the empty dict. +Note: That the default values of these attributes are the values that are passed to the adapter and not what is passed to the request method. This means that the default for :py:attr:`allow_redirects` is :py:const:`None` (even though that is interpretted as :py:const:`True`) if unset, whereas the default for verify is :py:const:`True`, and the default for proxies is the empty dict. Reset History =============== -For mocks, adapters, and matchers, the history can be reset. This can be useful when testing complex code with multiple requests. +For mocks, adapters, and matchers, the history can be reset. This can be useful when testing complex code with multiple requests. -For mocks, use "reset_mock" method. +For mocks, use the :py:meth:`reset_mock` method. .. doctest:: @@ -84,7 +84,7 @@ For mocks, use "reset_mock" method. >>> m.call_count 0 -For adapters and matchers, there is a "reset" method. Resetting the adapter also resets the associated matchers. +For adapters and matchers, there is a :py:meth:`reset` method. Resetting the adapter also resets the associated matchers. .. doctest:: diff --git a/doc/source/matching.rst b/doc/source/matching.rst index 1b412e0..f653b46 100644 --- a/doc/source/matching.rst +++ b/doc/source/matching.rst @@ -44,14 +44,14 @@ The examples in this file are loaded with: .. note:: By default all matching is case insensitive. This can be adjusted by - passing case_sensitive=True when creating a mocker or adapter or globally + passing case_sensitive=True when creating a mocker or adapter, or globally by doing: .. code:: python requests_mock.mock.case_sensitive = True - for more see: :ref:`case_insensitive` + for more, see: :ref:`case_insensitive` Simple ====== @@ -191,7 +191,7 @@ The URL is then matched using :py:meth:`re.regex.search` which means that it wil .. >>> session.get('mock://www.tester.com/a/b').text .. 'resp' -If you use regular expression matching then *requests-mock* can't do it's normal query string or path only matching, that will need to be part of the expression. +If you use regular expression matching then *requests-mock* can't do its normal query string or path-only matching. That will need to be part of the expression. Request Headers @@ -223,7 +223,7 @@ Only the headers that are provided need match, any additional headers will be ig Additional Matchers =================== -As distinct from `Custom Matching` below we can add an additional matcher callback that lets us do more dynamic matching in addition to the standard options. +As distinct from `Custom Matching` below, we can add an additional matcher callback that lets us do more dynamic matching in addition to the standard options. This is handled by a callback function that takes the request as a parameter: .. doctest:: @@ -255,11 +255,11 @@ Using this mechanism lets you do custom handling such as parsing yaml or XML str Custom Matching =============== -Internally calling :py:meth:`~requests_mock.Adapter.register_uri` creates a *matcher* object for you and adds it to the list of matchers to check against. +Internally, calling :py:meth:`~requests_mock.Adapter.register_uri` creates a *matcher* object for you and adds it to the list of matchers to check against. -A *matcher* is any callable that takes a :py:class:`requests.Request` and returns a :py:class:`requests.Response` on a successful match or *None* if it does not handle the request. +A *matcher* is any callable that takes a :py:class:`requests.Request` and returns a :py:class:`requests.Response` on a successful match or :py:const:`None` if it does not handle the request. -If you need more flexibility than provided by :py:meth:`~requests_mock.Adapter.register_uri` then you can add your own *matcher* to the :py:class:`~requests_mock.Adapter`. Custom *matchers* can be used in conjunction with the inbuilt *matchers*. If a matcher returns *None* then the request will be passed to the next *matcher* as with using :py:meth:`~requests_mock.Adapter.register_uri`. +If you need more flexibility than provided by :py:meth:`~requests_mock.Adapter.register_uri` then you can add your own *matcher* to the :py:class:`~requests_mock.Adapter`. Custom *matchers* can be used in conjunction with the inbuilt *matchers*. If a matcher returns :py:const:`None` then the request will be passed to the next *matcher* as with using :py:meth:`~requests_mock.Adapter.register_uri`. .. doctest:: :hide: diff --git a/doc/source/mocker.rst b/doc/source/mocker.rst index 92c0f86..a1014d2 100644 --- a/doc/source/mocker.rst +++ b/doc/source/mocker.rst @@ -9,7 +9,7 @@ Its goal is to provide an interface that is as close to the real requests librar :py:class:`requests_mock.Mocker` takes two optional parameters: -:real_http (bool): If True then any requests that are not handled by the mocking adapter will be forwarded to the real server (see :ref:`RealHTTP`), or the containing Mocker if applicable (see :ref:`NestingMockers`). Defaults to False. +:real_http (bool): If :py:const:`True` then any requests that are not handled by the mocking adapter will be forwarded to the real server (see :ref:`RealHTTP`), or the containing Mocker if applicable (see :ref:`NestingMockers`). Defaults to :py:const:`False`. :session (requests.Session): If set, only the given session instance is mocked (see :ref:`SessionMocking`). Activation @@ -114,7 +114,7 @@ The mocker object can be used with a similar interface to requests itself. 'resp' -The functions exist for the common HTTP method: +The following functions exist for the common HTTP methods: - :py:meth:`~requests_mock.MockerCore.delete` - :py:meth:`~requests_mock.MockerCore.get`