Add documentation for problems with pyfakefs and mock_open

- see #631

Author: mrbean-bremen

docs/intro.rst

@@ -85,6 +85,10 @@ Limitations
   considered as reference systems, additionally the tests are run in Docker
   containers with the latest CentOS, Debian, Fedora and Ubuntu images.
 
+- pyfakefs may not work correctly if file system functions are patched by
+  other means (e.g. using `unittest.mock.patch`) - see
+  :ref:`usage_with_mock_open` for more information
+
 History
 -------
 pyfakefs was initially developed at Google by

docs/usage.rst

@@ -908,3 +908,19 @@ that using ``fake_filesystem.set_uid()`` in your setup. This allows to run
 tests as non-root user in a root user environment and vice verse.
 Another possibility to run tests as non-root user in a root user environment
 is the convenience argument :ref:`allow_root_user`.
+
+.. _usage_with_mock_open:
+
+Pyfakefs and mock_open
+~~~~~~~~~~~~~~~~~~~~~~
+If you patch ``open`` using ``mock_open`` before the initialization of
+``pyfakefs``, it will not work properly, because the ``pyfakefs``
+initialization relies on ``open`` working correctly.
+Generally, you should not need ``mock_open`` if using ``pyfakefs``, because you
+always can create the files with the needed content using ``create_file``.
+This is true for patching any filesystem functions - avoid patching them
+while working with ``pyfakefs``.
+If you still want to use ``mock_open``, make sure it is only used while
+patching is in progress. For example, if you are using ``pytest`` with the
+``mocker`` fixture used to patch ``open``, make sure that the ``fs`` fixture is
+passed before the ``mocker`` fixture to ensure this.