Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-101100: Fix Sphinx warnings in library/unittest.mock.rst #124106

Merged
merged 2 commits into from
Oct 9, 2024
Merged

gh-101100: Fix Sphinx warnings in library/unittest.mock.rst #124106

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f77e1a6
Fix Sphinx warnings in library/unittest.mock.rst
hugovk Sep 15, 2024
5e8e6b8
Silence Sphinx warnings for spec and spec_set
hugovk Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 25 additions & 25 deletions Doc/library/unittest.mock.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@
3
>>> thing.method.assert_called_with(3, 4, 5, key='value')

:attr:`side_effect` allows you to perform side effects, including raising an
:attr:`~Mock.side_effect` allows you to perform side effects, including raising an
exception when a mock is called:

>>> from unittest.mock import Mock
Expand Down Expand Up @@ -737,16 +737,16 @@

.. attribute:: __class__

Normally the :attr:`__class__` attribute of an object will return its type.
For a mock object with a :attr:`spec`, ``__class__`` returns the spec class
Normally the :attr:`!__class__` attribute of an object will return its type.

Check warning on line 740 in Doc/library/unittest.mock.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:attr reference target not found: spec [ref.attr]
For a mock object with a :attr:`spec`, :attr:`!__class__` returns the spec class
Copy link
Member

@picnixz picnixz Sep 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The spec attribute seems to be missing or is it an inherited one? (Maybe we could fix it in this PR directly?). Or is it a Sphinx issue?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it (and spec_set) are just missing documentation under https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock

For example, here's side_effect:

https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock.side_effect

Would you like to suggest some text?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I never used it so I cannot really suggest a good text. I'll leave that task to unittest experts! but we can do it in another PR otherwise.

instead. This allows mock objects to pass :func:`isinstance` tests for the
object they are replacing / masquerading as:

>>> mock = Mock(spec=3)
>>> isinstance(mock, int)
True

:attr:`__class__` is assignable to, this allows a mock to pass an
:attr:`!__class__` is assignable to, this allows a mock to pass an
:func:`isinstance` check without forcing you to use a spec:

>>> mock = Mock()
Expand Down Expand Up @@ -1175,7 +1175,7 @@
like :attr:`~Mock.call_args` and :attr:`~Mock.call_args_list`.

If :attr:`~Mock.side_effect` is set then it will be called after the call has
been recorded, so if :attr:`side_effect` raises an exception the call is still
been recorded, so if :attr:`!side_effect` raises an exception the call is still
recorded.

The simplest way to make a mock raise an exception when called is to make
Expand All @@ -1196,8 +1196,8 @@
>>> m.mock_calls
[call(1, 2, 3), call('two', 'three', 'four')]

If :attr:`side_effect` is a function then whatever that function returns is what
calls to the mock return. The :attr:`side_effect` function is called with the
If :attr:`~Mock.side_effect` is a function then whatever that function returns is what
calls to the mock return. The :attr:`!side_effect` function is called with the
same arguments as the mock. This allows you to vary the return value of the
call dynamically, based on the input:

Expand All @@ -1214,7 +1214,7 @@

If you want the mock to still return the default return value (a new mock), or
any set return value, then there are two ways of doing this. Either return
:attr:`mock.return_value` from inside :attr:`side_effect`, or return :data:`DEFAULT`:
:attr:`~Mock.return_value` from inside :attr:`~Mock.side_effect`, or return :data:`DEFAULT`:

>>> m = MagicMock()
>>> def side_effect(*args, **kwargs):
Expand All @@ -1231,8 +1231,8 @@
>>> m()
3

To remove a :attr:`side_effect`, and return to the default behaviour, set the
:attr:`side_effect` to ``None``:
To remove a :attr:`~Mock.side_effect`, and return to the default behaviour, set the
:attr:`!side_effect` to ``None``:

>>> m = MagicMock(return_value=6)
>>> def side_effect(*args, **kwargs):
Expand All @@ -1245,7 +1245,7 @@
>>> m()
6

The :attr:`side_effect` can also be any iterable object. Repeated calls to the mock
The :attr:`~Mock.side_effect` can also be any iterable object. Repeated calls to the mock
will return values from the iterable (until the iterable is exhausted and
a :exc:`StopIteration` is raised):

Expand Down Expand Up @@ -1455,7 +1455,7 @@
If you are patching builtins in a module then you don't
need to pass ``create=True``, it will be added by default.

Patch can be used as a :class:`TestCase` class decorator. It works by
Patch can be used as a :class:`~unittest.TestCase` class decorator. It works by
decorating each test method in the class. This reduces the boilerplate
code when your test methods share a common patchings set. :func:`patch` finds
tests by looking for method names that start with ``patch.TEST_PREFIX``.
Expand Down Expand Up @@ -1493,7 +1493,7 @@
can set the *return_value* to be anything you want.

To configure return values on methods of *instances* on the patched class
you must do this on the :attr:`return_value`. For example::
you must do this on the :attr:`~Mock.return_value`. For example::

>>> class Class:
... def method(self):
Expand Down Expand Up @@ -1815,13 +1815,13 @@
patch methods: start and stop
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All the patchers have :meth:`start` and :meth:`stop` methods. These make it simpler to do
All the patchers have :meth:`!start` and :meth:`!stop` methods. These make it simpler to do
patching in ``setUp`` methods or where you want to do multiple patches without
nesting decorators or with statements.

To use them call :func:`patch`, :func:`patch.object` or :func:`patch.dict` as
normal and keep a reference to the returned ``patcher`` object. You can then
call :meth:`start` to put the patch in place and :meth:`stop` to undo it.
call :meth:`!start` to put the patch in place and :meth:`!stop` to undo it.

If you are using :func:`patch` to create a mock for you then it will be returned by
the call to ``patcher.start``. ::
Expand All @@ -1838,7 +1838,7 @@


A typical use case for this might be for doing multiple patches in the ``setUp``
method of a :class:`TestCase`::
method of a :class:`~unittest.TestCase`::

>>> class MyTest(unittest.TestCase):
... def setUp(self):
Expand Down Expand Up @@ -2511,7 +2511,7 @@

Alternatively you can just use ``vars(my_mock)`` (instance members) and
``dir(type(my_mock))`` (type members) to bypass the filtering irrespective of
:const:`mock.FILTER_DIR`.
:const:`FILTER_DIR`.


mock_open
Expand All @@ -2526,7 +2526,7 @@
default) then a :class:`MagicMock` will be created for you, with the API limited
to methods or attributes available on standard file handles.

*read_data* is a string for the :meth:`~io.IOBase.read`,
*read_data* is a string for the :meth:`~io.RawIOBase.read`,
:meth:`~io.IOBase.readline`, and :meth:`~io.IOBase.readlines` methods
of the file handle to return. Calls to those methods will take data from
*read_data* until it is depleted. The mock of these methods is pretty
Expand All @@ -2538,7 +2538,7 @@

.. versionchanged:: 3.4
Added :meth:`~io.IOBase.readline` and :meth:`~io.IOBase.readlines` support.
The mock of :meth:`~io.IOBase.read` changed to consume *read_data* rather
The mock of :meth:`~io.RawIOBase.read` changed to consume *read_data* rather
than returning it on each call.

.. versionchanged:: 3.5
Expand Down Expand Up @@ -2615,7 +2615,7 @@
don't test how your units are "wired together" there is still lots of room
for bugs that tests might have caught.

:mod:`mock` already provides a feature to help with this, called speccing. If you
:mod:`unittest.mock` already provides a feature to help with this, called speccing. If you

Check warning on line 2618 in Doc/library/unittest.mock.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:attr reference target not found: spec [ref.attr]
use a class or instance as the :attr:`spec` for a mock then you can only access
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a warning on "spec" here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, it's not yet documented, can you suggest some text for it? Also for spec_set?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe just write :attr:`!spec` .

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, and also for spec_set.

attributes on the mock that exist on the real class:

Expand Down Expand Up @@ -2654,7 +2654,7 @@
>>> mock_request.Request
<MagicMock name='request.Request' spec='Request' id='...'>

You can see that :class:`request.Request` has a spec. :class:`request.Request` takes two
You can see that :class:`!request.Request` has a spec. :class:`!request.Request` takes two
arguments in the constructor (one of which is *self*). Here's what happens if
we try to call it incorrectly::

Expand All @@ -2670,8 +2670,8 @@
>>> req
<NonCallableMagicMock name='request.Request()' spec='Request' id='...'>

:class:`Request` objects are not callable, so the return value of instantiating our
mocked out :class:`request.Request` is a non-callable mock. With the spec in place
:class:`!Request` objects are not callable, so the return value of instantiating our
mocked out :class:`!request.Request` is a non-callable mock. With the spec in place
any typos in our asserts will raise the correct error::

>>> req.add_header('spam', 'eggs')
Expand Down Expand Up @@ -2823,8 +2823,8 @@
.. versionadded:: 3.7


Order of precedence of :attr:`side_effect`, :attr:`return_value` and *wraps*
----------------------------------------------------------------------------
Order of precedence of :attr:`!side_effect`, :attr:`!return_value` and *wraps*
------------------------------------------------------------------------------

The order of their precedence is:

Expand Down
Loading