bpo-41877: Improve docs for assert misspellings check in mock (GH-23729)

This is a follow-up to
https://github.com/python/cpython/commit/4662fa9bfe4a849fe87bfb321d8ef0956c89a772.
That original commit expanded guards against misspelling assertions on
mocks. This follow-up updates the documentation and improves the error
message by pointing out the potential cause and solution.

Automerge-Triggered-By: GH:gpshead

4 files changed, 9 insertions, 6 deletions

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index c5360f91f5..f795a2e8c1 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -262,9 +262,10 @@ the *new_callable* argument to :func:`patch`.
       this is a new Mock (created on first access). See the
       :attr:`return_value` attribute.
 
-    * *unsafe*: By default if any attribute starts with *assert* or
-      *assret* will raise an :exc:`AttributeError`. Passing ``unsafe=True``
-      will allow access to these attributes.
+    * *unsafe*: By default, accessing any attribute with name starting with
+      *assert*, *assret*, *asert*, *aseert* or *assrt* will raise an
+      :exc:`AttributeError`. Passing ``unsafe=True`` will allow access to
+      these attributes.
 
       .. versionadded:: 3.5
 
diff --git a/Lib/unittest/mock.py b/Lib/unittest/mock.py
index 4db1bacf4b..d43ea9e23c 100644
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -632,8 +632,9 @@ class NonCallableMock(Base):
             raise AttributeError(name)
         if not self._mock_unsafe:
             if name.startswith(('assert', 'assret', 'asert', 'aseert', 'assrt')):
-                raise AttributeError("Attributes cannot start with 'assert' "
-                                     "or its misspellings")
+                raise AttributeError(
+                    f"{name} is not a valid assertion. Use a spec "
+                    f"for the mock if {name} is meant to be an attribute.")
 
         result = self._mock_children.get(name)
         if result is _deleted:
diff --git a/Lib/unittest/test/testmock/testmock.py b/Lib/unittest/test/testmock/testmock.py
index dfcf1ef2ee..016905c3b9 100644
--- a/Lib/unittest/test/testmock/testmock.py
+++ b/Lib/unittest/test/testmock/testmock.py
@@ -1598,7 +1598,7 @@ class MockTest(unittest.TestCase):
     #Issue21238
     def test_mock_unsafe(self):
         m = Mock()
-        msg = "Attributes cannot start with 'assert' or its misspellings"
+        msg = "is not a valid assertion. Use a spec for the mock"
         with self.assertRaisesRegex(AttributeError, msg):
             m.assert_foo_call()
         with self.assertRaisesRegex(AttributeError, msg):
diff --git a/Misc/NEWS.d/next/Library/2020-12-10-09-24-44.bpo-41877.iJSCvM.rst b/Misc/NEWS.d/next/Library/2020-12-10-09-24-44.bpo-41877.iJSCvM.rst
new file mode 100644
index 0000000000..df43cc5d0c
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2020-12-10-09-24-44.bpo-41877.iJSCvM.rst
@@ -0,0 +1 @@
+AttributeError for suspected misspellings of assertions on mocks are now pointing out that the cause are misspelled assertions and also what to do if the misspelling is actually an intended attribute name. The unittest.mock document is also updated to reflect the current set of recognised misspellings.
\ No newline at end of file