Is this documentation made more clear by removing this example? The goal here was to show how someone could mock an asynchronous context manager that they wrote using MagicMock (or AsyncMock). You've changed it to show MagicMock can act as an asynchronous context manager, which I think without the context of mocking a real object doesn't demonstrate a useful scenario.

The confusing part is that the CM class is defined together with the code that mocks it. The user might also want to mock a CM that they didn't define, but obtain through a call (e.g. to open).

In the first case, it might be enough to imply the existence of the CM by doing from mymodule import AsyncContextManager, and describing how MagicMock(AsyncContextManager()) automatically find and mocks __aenter__ and __aexit__ with AsyncMocks.

In the second case, what Elena did is OK unless we want a more realistic example.

In my opinion defining the AsyncContextManager class here is kind of useless. All of its methods will be mocked by MagicMock, so we might as well forget of its existence, or am I missing something here? What I mean is that mock_instance = MagicMock(AsyncContextManager()) is equivalent to mock_instance = MagicMock()

@elenaoat I don't agree that because the custom context manager is mocked it is not relevant. Mock is used to mock objects that exist in code to have different behavior for the sake of testing. I cannot come up with a use case for a mock object as an asynchronous context manager that is not specced with any real piece of code. What problem is it solving?
Maybe the test could be more verbose by adding a return value or side effect on the mock object, but I don't think it makes sense to ever use it without a spec.

And mock_instance = MagicMock(AsyncContextManager()) is not the same as mock_instance =MagicMock() off the bat:

>>> dir(MagicMock())
['assert_any_call', 'assert_called', 'assert_called_once', 'assert_called_once_with', 'assert_called_with', 'assert_has_calls', 'assert_not_called', 'attach_mock', 'call_args', 'call_args_list', 'call_count', 'called', 'configure_mock', 'method_calls', 'mock_add_spec', 'mock_calls', 'reset_mock', 'return_value', 'side_effect']
>>> dir(MagicMock(AsyncContextManager))
['__aenter__', '__aexit__', '__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'assert_any_call', 'assert_called', 'assert_called_once', 'assert_called_once_with', 'assert_called_with', 'assert_has_calls', 'assert_not_called', 'attach_mock', 'call_args', 'call_args_list', 'call_count', 'called', 'configure_mock', 'method_calls', 'mock_add_spec', 'mock_calls', 'reset_mock', 'return_value', 'side_effect']

I agree that it is weird to define them together in the same file, but I think that might be a limitation of doctest. I assumed we would not be able to import AsyncContextManager without it failing, because mymodule doesn't actually exist? I might be wrong about how this works though. If we can import it I think that is a good idea, maybe make the name more explicit like MyCustomAsyncContextManager.

If we can't import it I still think it is better to build it in here then exclude it all together, maybe we can add a comment block around it, implying it is in a different file without actually being in a different file?

I would rephrase this as If we wanted this call to return a list, then we have to specify the return value of the two calls..
I think here "nested" is used incorrectly, because even though the mocks might be considered nested, the calls in the expressions are not. If we want to make this more explicit, the two calls (cursor() and execute()) could be mentioned explicitly.

The confusing part is that the CM class is defined together with the code that mocks it. The user might also want to mock a CM that they didn't define, but obtain through a call (e.g. to open).

In the first case, it might be enough to imply the existence of the CM by doing from mymodule import AsyncContextManager, and describing how MagicMock(AsyncContextManager()) automatically find and mocks __aenter__ and __aexit__ with AsyncMocks.

In the second case, what Elena did is OK unless we want a more realistic example.

I think these 2 lines should be kept.

The Mock doesn't have these two methods, that's why it will fail.

Though the earlier example was slightly verbose I think it's clear on setting nested mock return values. Personally I don't prefer much nested chains in the docs so I would suggest keeping the old example and then adding a note with this line that nested mocks return value could be set with this one liner as alternative.

Instead of demonstrating the attribute to be present on the return_value attribute itself we the below reads more useful showing the attribute to be set on the return value itself as call is made.

I would suggest keeping the old example setting return_value on __str__ though there is a different example below setting __str__.return_value with a mock. May I know the purpose of changing it to len? Is it show the default value for some magic methods?