https://github.com/python/cpython/commit/a5716a30914cc11c3a4bec374cdaece3c79b541f
commit: a5716a30914cc11c3a4bec374cdaece3c79b541f
branch: main
author: Hugo van Kemenade <[email protected]>
committer: hugovk <[email protected]>
date: 2024-10-09T17:02:18+03:00
summary:
gh-101100: Fix Sphinx warnings in `library/unittest.mock.rst` (#124106)
files:
M Doc/library/unittest.mock.rst
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index cc2b1b4299553c..eae3ef2888eae0 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -68,7 +68,7 @@ available, and then make assertions about how they have been
used:
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
@@ -760,8 +760,8 @@ the *new_callable* argument to :func:`patch`.
.. 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.
+ For a mock object with a :attr:`!spec`, :attr:`!__class__` returns the
spec class
instead. This allows mock objects to pass :func:`isinstance` tests for
the
object they are replacing / masquerading as:
@@ -769,7 +769,7 @@ the *new_callable* argument to :func:`patch`.
>>> 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()
@@ -783,8 +783,8 @@ the *new_callable* argument to :func:`patch`.
meaning of :class:`Mock`, with the exception of *return_value* and
*side_effect*
which have no meaning on a non-callable mock.
-Mock objects that use a class or an instance as a :attr:`spec` or
-:attr:`spec_set` are able to pass :func:`isinstance` tests:
+Mock objects that use a class or an instance as a :attr:`!spec` or
+:attr:`!spec_set` are able to pass :func:`isinstance` tests:
>>> mock = Mock(spec=SomeClass)
>>> isinstance(mock, SomeClass)
@@ -1198,7 +1198,7 @@ Calls made to the object will be recorded in the
attributes
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
@@ -1219,8 +1219,8 @@ The simplest way to make a mock raise an exception when
called is to make
>>> 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:
@@ -1237,7 +1237,7 @@ call dynamically, based on the input:
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):
@@ -1254,8 +1254,8 @@ any set return value, then there are two ways of doing
this. Either return
>>> 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):
@@ -1268,7 +1268,7 @@ To remove a :attr:`side_effect`, and return to the
default behaviour, set the
>>> 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):
@@ -1309,7 +1309,7 @@ objects of any type.
You may want a mock object to return ``False`` to a :func:`hasattr` call, or
raise an
:exc:`AttributeError` when an attribute is fetched. You can do this by
providing
-an object as a :attr:`spec` for a mock, but that isn't always convenient.
+an object as a :attr:`!spec` for a mock, but that isn't always convenient.
You "block" attributes by deleting them. Once deleted, accessing an attribute
will raise an :exc:`AttributeError`.
@@ -1478,7 +1478,7 @@ patch
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``.
@@ -1516,7 +1516,7 @@ If the class is instantiated multiple times you could use
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):
@@ -1838,13 +1838,13 @@ context manager is a dictionary where created mocks are
keyed by name::
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``. ::
@@ -1861,7 +1861,7 @@ the call to ``patcher.start``. ::
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):
@@ -2534,7 +2534,7 @@ behaviour you can switch it off by setting the module
level switch
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
@@ -2549,7 +2549,7 @@ mock_open
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
@@ -2561,7 +2561,7 @@ mock_open
.. 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
@@ -2613,7 +2613,7 @@ And for reading files::
Autospeccing
~~~~~~~~~~~~
-Autospeccing is based on the existing :attr:`spec` feature of mock. It limits
the
+Autospeccing is based on the existing :attr:`!spec` feature of mock. It limits
the
api of mocks to the api of an original object (the spec), but it is recursive
(implemented lazily) so that attributes of mocks only have the same api as
the attributes of the spec. In addition mocked functions / methods have the
@@ -2638,8 +2638,8 @@ unit tests. Testing everything in isolation is all fine
and dandy, but if you
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
-use a class or instance as the :attr:`spec` for a mock then you can only access
+:mod:`unittest.mock` already provides a feature to help with this, called
speccing. If you
+use a class or instance as the :attr:`!spec` for a mock then you can only
access
attributes on the mock that exist on the real class:
>>> from urllib import request
@@ -2677,7 +2677,7 @@ Here's an example of it in use::
>>> 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::
@@ -2693,8 +2693,8 @@ specced mocks)::
>>> 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')
@@ -2846,8 +2846,8 @@ Sealing mocks
.. 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:
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
