[issue43400] Remove "Mock is very easy to use" from unittest.mock documentation

New submission from Eddie Peters <eddie@dinogalactic.com>: The unittest.mock library is very useful and very powerful, but it is not "very easy to use." Docs are useful and important, or we wouldn't be here in a documentation issue. I have watched several of the most experienced Python programmers I know struggle with various aspects of mock, including basic usage. I have sat with frustrated developers who have used mocking utilities in other languages but had little Python experience, and they were surprised by some mock behaviors and just couldn't get things "right" until they were helped by someone with all the tiny little healed-over cuts from lots of mock usage. Again, mock is great, but maybe if I have these opinions, I should contribute to making mock more intuitive. That's true. For now, though, the documentation contains this little line in the opening paragraphs that is unnecessary and can only make new mock users feel bad about having trouble: "Mock is very easy to use and is designed for use with unittest." I propose we remove the opinion "Mock is very easy to use" and change this line to "Mock is designed for use with unittest." The rest of the paragraph flows just fine without this: "Mock is very easy to use and is designed for use with unittest. Mock is based on the ‘action -> assertion’ pattern instead of ‘record -> replay’ used by many mocking frameworks." ---------- assignee: docs@python components: Documentation messages: 388102 nosy: docs@python, eppeters priority: normal severity: normal status: open title: Remove "Mock is very easy to use" from unittest.mock documentation type: enhancement versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Change by Eddie Peters <eddie@dinogalactic.com>: ---------- keywords: +patch pull_requests: +23522 stage: -> patch review pull_request: https://github.com/python/cpython/pull/24752 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Karthikeyan Singaravelan <tir.karthi@gmail.com> added the comment: I don't have any opinion on removing the part of the sentence. It will be helpful if you can list the scenarios where you feel document is lacking so that it can be improved. One area I have found to be little tricky is patching the correct object during testing which has a section and needs some understanding of Python's import mechanism. The other was about setting return value properly for nested attributes. Mock has a lot of features and has a wide range of API so listing places where you feel some of the things are not clear will help in improving them. ---------- nosy: +xtreak _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: +1 for the OP's suggestion. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Doug Harris <dharris@gmail.com> added the comment: +1 on this documentation change. @xtreak yes, patching the correct object has bit me a couple times. The pattern that I work with the most is when mocking calls to external services and APIs. I want to test my code that, say, sends email or sends user information to a partner, but without actual HTTP calls. Whenever I add a new test that does this, I need to rethink exactly what the sequence of mocked objects, calls, and returns will be. The HOWTO section of the official Python docs has nothing on unittest or mock. Perhaps something there... (makes note to think about drafting something). ---------- nosy: +dougharris _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: New changeset 2122e486307d5577cb5fb5e7cfd24095695bc7e9 by Eddie Peters in branch 'master': bpo-43400: Remove "easy to use" from mock docs (GH-24752) https://github.com/python/cpython/commit/2122e486307d5577cb5fb5e7cfd24095695... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- nosy: +miss-islington nosy_count: 5.0 -> 6.0 pull_requests: +23530 pull_request: https://github.com/python/cpython/pull/24758 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: docs@python -> rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: New changeset 0dd4cb944b497dc6bd0b3763e461d72e9a7b6490 by Miss Islington (bot) in branch '3.9': bpo-43400: Remove "easy to use" from mock docs (GH-24752) (GH-24758) https://github.com/python/cpython/commit/0dd4cb944b497dc6bd0b3763e461d72e9a7... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Karthikeyan Singaravelan <tir.karthi@gmail.com> added the comment: Mock has a section on getting started that has several recipes but it's not under howto section. Perhaps this page could be updated if you want to make a PR : https://docs.python.org/3/library/unittest.mock-examples.html There is also a section on where to patch : https://docs.python.org/3/library/unittest.mock.html#where-to-patch I admit it also bites me few times and I have to do trial and error to get the right patch object. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Renaming this issue to reflect a shift in focus towards broader improvements to the documentation. ---------- title: Remove "Mock is very easy to use" from unittest.mock documentation -> Improve recipes and howtos for the unittest.mock versions: -Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________

Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: rhettinger -> _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue43400> _______________________________________
participants (5)
-
Doug Harris
-
Eddie Peters
-
Karthikeyan Singaravelan
-
miss-islington
-
Raymond Hettinger