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."

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.

+1 for the OP's suggestion.

+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).

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/2122e486307d5577cb5fb5e7cfd24095695bc7e9

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/0dd4cb944b497dc6bd0b3763e461d72e9a7b6490

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.

Renaming this issue to reflect a shift in focus towards broader improvements to the documentation.