[issue33722] Document builtins in mock_open

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

After looking at the context of the patch and thinking more about whether the patch is a good idea, I am reversing what I said before and think that this issue and the new patch (sorry) should be closed.

1. The new example duplicates the current example.  The only difference is that one module name,'__main__', is replaced with another, 'builtins'.  Mechanically, there is no difference, so the duplicate adds nothing.

2. The current example, contrary to the claim, "'__main__'.open is replaced", adds .open to __main__ and thereby masks builtins.open in, and only in, __main__.  In use, '__main__' in all the current doc examples should be replaced by the name of the module where open is called.  This would usually, but not necessarily, be the module being tested. This is explained in the section on where to patch.

3. Touching builtins is generally a bad idea unless one really understands and wants to affect *all* modules in the process, including the test code and unittest code.  Beginners should *not* be encouraged to do this.  If one replaces a builtin needed by test code or other untested mdoules before the replacement is undone, one disables the test code.

The real problem, if any, with the mock examples, is that they usually do everything in one module (usually __main__) while real use involves code and execution in at least two modules.  Users are left to work out which examples lines belong in text_xyz, which would be in xyz, and what essential code is missing.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue33722>
_______________________________________