From 984a800e082e649186e177ec4fedc7d7e3dcc22d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 19 Oct 2018 15:17:31 -0700 Subject: [PATCH] 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. (cherry picked from commit 96200eb2ffcda05de14099cf23f60d5091366e3e) Co-authored-by: Mario Corchero --- Doc/library/unittest.mock.rst | 9 +++++---- Lib/unittest/mock.py | 9 ++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index ef1b2e35719df4..91633b505f567a 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -2374,17 +2374,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 cfc0d76ee3f799..1a6c251d2cf799 100644 --- a/Lib/unittest/mock.py +++ b/Lib/unittest/mock.py @@ -2423,15 +2423,14 @@ def __set__(self, obj, val): 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):