From: Mario Corchero <mariocj89@gmail.com>
Date: Fri, 19 Oct 2018 21:57:37 +0000 (+0100)
Subject: unittest.mock doc: Fix references to recursive seal of Mocks (GH-9028)
X-Git-Tag: v3.8.0a1~737
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=96200eb2ffcda05de14099cf23f60d5091366e3e;p=python

unittest.mock doc: Fix references to recursive seal of Mocks (GH-9028)

The docs in `library/unittest.mock` have been updated to remove
confusing terms about submock and be explicit about the behavior
expected.
---

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index edafca0c67..136804cfc2 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -2410,17 +2410,18 @@ Sealing mocks
 
 .. function:: seal(mock)
 
-    Seal will disable the creation of mock children by preventing getting or setting
-    of any new attribute on the sealed mock. The sealing process is performed recursively.
+    Seal will disable the automatic creation of mocks when accessing an attribute of
+    the mock being sealed or any of its attributes that are already mocks recursively.
 
-    If a mock instance is assigned to an attribute instead of being dynamically created
+    If a mock instance with a name or a spec is assigned to an attribute
     it won't be considered in the sealing chain. This allows one to prevent seal from
     fixing part of the mock object. ::
 
         >>> mock = Mock()
         >>> mock.submock.attribute1 = 2
-        >>> mock.not_submock = mock.Mock()
+        >>> mock.not_submock = mock.Mock(name="sample_name")
         >>> seal(mock)
+        >>> mock.new_attribute  # This will raise AttributeError.
         >>> mock.submock.attribute2  # This will raise AttributeError.
         >>> mock.not_submock.attribute2  # This won't raise.
 
diff --git a/Lib/unittest/mock.py b/Lib/unittest/mock.py
index 83026e6f3b..6b7f293bc5 100644
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -2425,15 +2425,14 @@ class PropertyMock(Mock):
 
 
 def seal(mock):
-    """Disable the automatic generation of "submocks"
+    """Disable the automatic generation of child mocks.
 
     Given an input Mock, seals it to ensure no further mocks will be generated
     when accessing an attribute that was not already defined.
 
-    Submocks are defined as all mocks which were created DIRECTLY from the
-    parent. If a mock is assigned to an attribute of an existing mock,
-    it is not considered a submock.
-
+    The operation recursively seals the mock passed in, meaning that
+    the mock itself, any mocks generated by accessing one of its attributes,
+    and all assigned mocks without a name or spec will be sealed.
     """
     mock._mock_sealed = True
     for attr in dir(mock):