2 files changed, 35 insertions, 1 deletions
diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst
index 0cbb5ae..36926cd 100644
--- a/Doc/library/unittest.mock-examples.rst
+++ b/Doc/library/unittest.mock-examples.rst
@@ -277,6 +277,20 @@ instantiate the class in those tests.
        ...
     AttributeError: object has no attribute 'old_method'
 
+Using a specification also enables a smarter matching of calls made to the
+mock, regardless of whether some parameters were passed as positional or
+named arguments::
+
+   >>> def f(a, b, c): pass
+   ...
+   >>> mock = Mock(spec=f)
+   >>> mock(1, 2, 3)
+   <Mock name='mock()' id='140161580456576'>
+   >>> mock.assert_called_with(a=1, b=2, c=3)
+
+If you want this smarter matching to also work with method calls on the mock,
+you can use :ref:`auto-speccing <auto-speccing>`.
+
 If you want a stronger form of specification that prevents the setting
 of arbitrary attributes as well as the getting of them then you can use
 `spec_set` instead of `spec`.
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 8e72696..0df60ca 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -264,7 +264,6 @@ the `new_callable` argument to `patch`.
             <Mock name='mock.method()' id='...'>
             >>> mock.method.assert_called_with(1, 2, 3, test='wow')
 
-
     .. method:: assert_called_once_with(*args, **kwargs)
 
        Assert that the mock was called exactly once and with the specified
@@ -685,6 +684,27 @@ have to create a dictionary and unpack it using `**`:
       ...
     KeyError
 
+A callable mock which was created with a *spec* (or a *spec_set*) will
+introspect the specification object's signature when matching calls to
+the mock.  Therefore, it can match the actual call's arguments regardless
+of whether they were passed positionally or by name::
+
+   >>> def f(a, b, c): pass
+   ...
+   >>> mock = Mock(spec=f)
+   >>> mock(1, 2, c=3)
+   <Mock name='mock()' id='140161580456576'>
+   >>> mock.assert_called_with(1, 2, 3)
+   >>> mock.assert_called_with(a=1, b=2, c=3)
+
+This applies to :meth:`~Mock.assert_called_with`,
+:meth:`~Mock.assert_called_once_with`, :meth:`~Mock.assert_has_calls` and
+:meth:`~Mock.assert_any_call`.  When :ref:`auto-speccing`, it will also
+apply to method calls on the mock object.
+
+   .. versionchanged:: 3.4
+      Added signature introspection on specced and autospecced mock objects.
+
 
 .. class:: PropertyMock(*args, **kwargs)