Merge pull request #290 from nicoddemus/readthedocs

Author: nicoddemus

CHANGELOG.rst

@@ -1,3 +1,7 @@
+Releases
+========
+
+
 3.7.0 (2022-01-28)
 ------------------
 
@@ -414,8 +418,7 @@ Breaking Changes
   option.
   Thanks `@asfaltboy`_ for the PR (`#36`_).
 
-* ``mocker.stub()`` now allows passing in the name for the constructed `Mock
-  <https://docs.python.org/3/library/unittest.mock.html#the-mock-class>`_
+* ``mocker.stub()`` now allows passing in the name for the constructed ``Mock``
   object instead of having to set it using the internal ``_mock_name`` attribute
   directly. This is useful for debugging as the name is used in the mock's
   ``repr`` string as well as related assertion failure messages.

README.rst

@@ -48,359 +48,22 @@ comparing calls.
 .. |pre-commit| image:: https://results.pre-commit.ci/badge/github/pytest-dev/pytest-mock/master.svg
    :target: https://results.pre-commit.ci/latest/github/pytest-dev/pytest-mock/master
 
-`Professionally supported pytest-mock is now available <https://tidelift.com/subscription/pkg/pypi-pytest_mock?utm_source=pypi-pytest-mock&utm_medium=referral&utm_campaign=readme>`_
+.. image:: https://readthedocs.org/projects/pytest-mock/badge/?version=latest
+   :target: https://pytest-mock.readthedocs.io/en/latest/?badge=latest
 
-Usage
-=====
 
-The ``mocker`` fixture has the same API as
-`mock.patch <https://docs.python.org/3/library/unittest.mock.html#patch>`_,
-supporting the same arguments:
+`Professionally supported pytest-mock is available <https://tidelift.com/subscription/pkg/pypi-pytest_mock?utm_source=pypi-pytest-mock&utm_medium=referral&utm_campaign=readme>`_.
 
-.. code-block:: python
-
-    def test_foo(mocker):
-        # all valid calls
-        mocker.patch('os.remove')
-        mocker.patch.object(os, 'listdir', autospec=True)
-        mocked_isfile = mocker.patch('os.path.isfile')
-
-The supported methods are:
-
-* `mocker.patch <https://docs.python.org/3/library/unittest.mock.html#patch>`_
-* `mocker.patch.object <https://docs.python.org/3/library/unittest.mock.html#patch-object>`_
-* `mocker.patch.multiple <https://docs.python.org/3/library/unittest.mock.html#patch-multiple>`_
-* `mocker.patch.dict <https://docs.python.org/3/library/unittest.mock.html#patch-dict>`_
-* `mocker.stopall <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.patch.stopall>`_
-* ``mocker.resetall()``: calls `reset_mock() <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock.reset_mock>`_ in all mocked objects up to this point.
-
-Also, as a convenience, these names from the ``mock`` module are accessible directly from ``mocker``:
-
-* `Mock <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock>`_
-* `MagicMock <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.MagicMock>`_
-* `PropertyMock <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.PropertyMock>`_
-* `ANY <https://docs.python.org/3/library/unittest.mock.html#any>`_
-* `DEFAULT <https://docs.python.org/3/library/unittest.mock.html#default>`_ *(Version 1.4)*
-* `call <https://docs.python.org/3/library/unittest.mock.html#call>`_ *(Version 1.1)*
-* `sentinel <https://docs.python.org/3/library/unittest.mock.html#sentinel>`_ *(Version 1.2)*
-* `mock_open <https://docs.python.org/3/library/unittest.mock.html#mock-open>`_
-* `seal <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.seal>`_ *(Version 3.4)*
-
-It is also possible to use mocking functionality from fixtures of other scopes using
-the appropriate mock fixture:
-
-* ``class_mocker``
-* ``module_mocker``
-* ``package_mocker``
-* ``session_mocker``
-
-Type Annotations
-----------------
-
-*New in version 3.3.0.*
-
-``pytest-mock`` is fully type annotated, letting users use static type checkers to
-test their code.
-
-The ``mocker`` fixture returns ``pytest_mock.MockerFixture`` which can be used
-to annotate test functions:
-
-.. code-block:: python
-
-    from pytest_mock import MockerFixture
-
-    def test_foo(mocker: MockerFixture) -> None:
-        ...
-
-The type annotations have been checked with ``mypy``, which is the only
-type checker supported at the moment; other type-checkers might work
-but are not currently tested.
-
-Spy
----
-
-The ``mocker.spy`` object acts exactly like the original method in all cases, except the spy
-also tracks function/method calls, return values and exceptions raised.
-
-.. code-block:: python
-
-    def test_spy_method(mocker):
-        class Foo(object):
-            def bar(self, v):
-                return v * 2
-
-        foo = Foo()
-        spy = mocker.spy(foo, 'bar')
-        assert foo.bar(21) == 42
-
-        spy.assert_called_once_with(21)
-        assert spy.spy_return == 42
-
-    def test_spy_function(mocker):
-        # mymodule declares `myfunction` which just returns 42
-        import mymodule
-
-        spy = mocker.spy(mymodule, "myfunction")
-        assert mymodule.myfunction() == 42
-        assert spy.call_count == 1
-        assert spy.spy_return == 42
-
-The object returned by ``mocker.spy`` is a ``MagicMock`` object, so all standard checking functions
-are available (like ``assert_called_once_with`` or ``call_count`` in the examples above).
-
-In addition, spy objects contain two extra attributes:
-
-* ``spy_return``: contains the returned value of the spied function.
-* ``spy_exception``: contain the last exception value raised by the spied function/method when
-  it was last called, or ``None`` if no exception was raised.
-
-Besides functions and normal methods, ``mocker.spy`` also works for class and static methods.
-
-As of version 3.0.0, ``mocker.spy`` also works with ``async def`` functions.
-
-.. note::
-
-    In versions earlier than ``2.0``, the attributes were called ``return_value`` and
-    ``side_effect`` respectively, but due to incompatibilities with ``unittest.mock``
-    they had to be renamed (see `#175`_ for details).
-
-    .. _#175: https://github.com/pytest-dev/pytest-mock/issues/175
-
-Stub
-----
-
-The stub is a mock object that accepts any arguments and is useful to test callbacks.
-It may receive an optional name that is shown in its ``repr``, useful for debugging.
-
-.. code-block:: python
-
-    def test_stub(mocker):
-        def foo(on_something):
-            on_something('foo', 'bar')
-
-        stub = mocker.stub(name='on_something_stub')
-
-        foo(stub)
-        stub.assert_called_once_with('foo', 'bar')
-
-
-Improved reporting of mock call assertion errors
-------------------------------------------------
-
-This plugin monkeypatches the mock library to improve pytest output for failures
-of mock call assertions like ``Mock.assert_called_with()`` by hiding internal traceback
-entries from the ``mock`` module.
-
-It also adds introspection information on differing call arguments when
-calling the helper methods. This features catches `AssertionError` raised in
-the method, and uses pytest's own `advanced assertions`_ to return a better
-diff::
-
-
-    mocker = <pytest_mock.MockerFixture object at 0x0381E2D0>
-
-        def test(mocker):
-            m = mocker.Mock()
-            m('fo')
-    >       m.assert_called_once_with('', bar=4)
-    E       AssertionError: Expected call: mock('', bar=4)
-    E       Actual call: mock('fo')
-    E
-    E       pytest introspection follows:
-    E
-    E       Args:
-    E       assert ('fo',) == ('',)
-    E         At index 0 diff: 'fo' != ''
-    E         Use -v to get the full diff
-    E       Kwargs:
-    E       assert {} == {'bar': 4}
-    E         Right contains more items:
-    E         {'bar': 4}
-    E         Use -v to get the full diff
-
-
-    test_foo.py:6: AssertionError
-    ========================== 1 failed in 0.03 seconds ===========================
-
-
-This is useful when asserting mock calls with many/nested arguments and trying
-to quickly see the difference.
-
-This feature is probably safe, but if you encounter any problems it can be disabled in
-your ``pytest.ini`` file:
-
-.. code-block:: ini
-
-    [pytest]
-    mock_traceback_monkeypatch = false
-
-Note that this feature is automatically disabled with the ``--tb=native`` option. The underlying
-mechanism used to suppress traceback entries from ``mock`` module does not work with that option
-anyway plus it generates confusing messages on Python 3.5 due to exception chaining
-
-.. _advanced assertions: http://docs.pytest.org/en/stable/assert.html
 
+Documentation
+=============
 
-Use standalone "mock" package
------------------------------
-
-*New in version 1.4.0.*
-
-Python 3 users might want to use a newest version of the ``mock`` package as published on PyPI
-than the one that comes with the Python distribution.
-
-.. code-block:: ini
-
-    [pytest]
-    mock_use_standalone_module = true
-
-This will force the plugin to import ``mock`` instead of the ``unittest.mock`` module bundled with
-Python 3.4+. Note that this option is only used in Python 3+, as Python 2 users only have the option
-to use the ``mock`` package from PyPI anyway.
-
-Note about usage as context manager
------------------------------------
-
-Although mocker's API is intentionally the same as ``mock.patch``'s, its use
-as context manager and function decorator is **not** supported through the
-fixture:
-
-.. code-block:: python
-
-    def test_context_manager(mocker):
-        a = A()
-        with mocker.patch.object(a, 'doIt', return_value=True, autospec=True):  # DO NOT DO THIS
-            assert a.doIt() == True
-
-The purpose of this plugin is to make the use of context managers and
-function decorators for mocking unnecessary, so it will emit a warning when used as such.
-
-If you really intend to mock a context manager, ``mocker.patch.context_manager`` exists
-which won't issue the above warning.
-
-
-Install
-=======
-
-Install using `pip <http://pip-installer.org/>`_:
-
-.. code-block:: console
-
-    $ pip install pytest-mock
-
-Changelog
-=========
-
-Please consult the `changelog page`_.
-
-.. _changelog page: https://github.com/pytest-dev/pytest-mock/blob/master/CHANGELOG.rst
-
-Why bother with a plugin?
-=========================
-
-There are a number of different ``patch`` usages in the standard ``mock`` API,
-but IMHO they don't scale very well when you have more than one or two
-patches to apply.
-
-It may lead to an excessive nesting of ``with`` statements, breaking the flow
-of the test:
-
-.. code-block:: python
-
-    import mock
-
-    def test_unix_fs():
-        with mock.patch('os.remove'):
-            UnixFS.rm('file')
-            os.remove.assert_called_once_with('file')
-
-            with mock.patch('os.listdir'):
-                assert UnixFS.ls('dir') == expected
-                # ...
-
-        with mock.patch('shutil.copy'):
-            UnixFS.cp('src', 'dst')
-            # ...
-
-
-One can use ``patch`` as a decorator to improve the flow of the test:
-
-.. code-block:: python
-
-    @mock.patch('os.remove')
-    @mock.patch('os.listdir')
-    @mock.patch('shutil.copy')
-    def test_unix_fs(mocked_copy, mocked_listdir, mocked_remove):
-        UnixFS.rm('file')
-        os.remove.assert_called_once_with('file')
-
-        assert UnixFS.ls('dir') == expected
-        # ...
-
-        UnixFS.cp('src', 'dst')
-        # ...
-
-But this poses a few disadvantages:
-
-- test functions must receive the mock objects as parameter, even if you don't plan to
-  access them directly; also, order depends on the order of the decorated ``patch``
-  functions;
-- receiving the mocks as parameters doesn't mix nicely with pytest's approach of
-  naming fixtures as parameters, or ``pytest.mark.parametrize``;
-- you can't easily undo the mocking during the test execution;
-
-An alternative is to use ``contextlib.ExitStack`` to stack the context managers in a single level of indentation
-to improve the flow of the test:
-
-.. code-block:: python
-
-    import contextlib
-    import mock
-
-    def test_unix_fs():
-        with contextlib.ExitStack() as stack:
-            stack.enter_context(mock.patch('os.remove'))
-            UnixFS.rm('file')
-            os.remove.assert_called_once_with('file')
-
-            stack.enter_context(mock.patch('os.listdir'))
-            assert UnixFS.ls('dir') == expected
-            # ...
-
-            stack.enter_context(mock.patch('shutil.copy'))
-            UnixFS.cp('src', 'dst')
-            # ...
-
-But this is arguably a little more complex than using ``pytest-mock``.
-
-Contributing
-============
-
-Contributions are welcome! After cloning the repository, create a virtual env
-and install ``pytest-mock`` in editable mode with ``dev`` extras:
-
-.. code-block:: console
-
-    $ pip install --editable .[dev]
-    $ pre-commit install
-
-Tests are run with ``tox``, you can run the baseline environments before submitting a PR:
-
-.. code-block:: console
-
-    $ tox -e py38,linting
-
-Style checks and formatting are done automatically during commit courtesy of
-`pre-commit <https://pre-commit.com>`_.
+For full documentation, please see https://pytest-mock.readthedocs.io/en/latest.
 
 License
 =======
 
 Distributed under the terms of the `MIT`_ license.
 
-Security contact information
-============================
-
-To report a security vulnerability, please use the `Tidelift security contact <https://tidelift.com/security>`__. Tidelift will coordinate the fix and disclosure.
 
 .. _MIT: https://github.com/pytest-dev/pytest-mock/blob/master/LICENSE