From 12ae90fab21245a8ff8bae77c1ebeffb9ff0b834 Mon Sep 17 00:00:00 2001
From: mrbean-bremen <andreas.bohne@mevis.de>
Date: Tue, 11 Jul 2017 21:07:32 +0200
Subject: [PATCH] Adapted usage scenarios in README

- see #189
---
 README.md | 79 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 60 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 3f23e947..76df2479 100644
--- a/README.md
+++ b/README.md
@@ -45,34 +45,75 @@ def my_fakefs_test(fs):
     assert os.path.exists('/var/data/xx1.txt')
 ```
 
-### Patch using unittest.mock
+### Patch using fake_filesystem_unittest.Patcher
+If you are using other means of testing like [nose](http://nose2.readthedocs.io), you can do the
+patching using `fake_filesystem_unittest.Patcher` - the class doing the the actual work
+of replacing the filesystem modules with the fake modules in the first two approaches.
 
-The other approach is to do the patching yourself using `mock.patch()`:
+The easiest way is to just use `Patcher` as a context manager:
 
 ```python
-import pyfakefs.fake_filesystem as fake_fs
+from fake_filesystem_unittest import Patcher
 
-# Create a faked file system
-fs = fake_fs.FakeFilesystem()
+with Patcher() as patcher:
+   # access the fake_filesystem object via patcher.fs
+   patcher.fs.CreateFile('/foo/bar', contents='test')
 
-# Do some setup on the faked file system
-fs.CreateFile('/var/data/xx1.txt')
-fs.CreateFile('/var/data/xx2.txt')
+   # the following code works on the fake filesystem
+   with open('/foo/bar') as f:
+       contents = f.read()
+```
+
+You can also initialize `Patcher` manually:
+
+```python
+from fake_filesystem_unittest import Patcher
+
+patcher = Patcher()
+patcher.setUp()     # called in the initialization code
+...
+patcher.tearDown()  # somewhere in the cleanup code
+```
+
+### Patch using unittest.mock (deprecated)
+
+You can also use ``mock.patch()`` to patch the modules manually. This approach will
+only work for the directly imported modules, therefore it is not suited for testing
+larger code bases. As the other approaches are more convenient, this one is considered
+deprecated.
+You have to create a fake filesystem object, and afterwards fake modules based on this file system
+for the modules you want to patch.
+
+The following modules and functions can be patched:
+
+* `os` and `os.path` by `fake_filessystem.FakeOsModule`
+* `io` by `fake_filessystem.FakeIoModule`
+* `pathlib` by `fake_pathlib.FakePathlibModule`
+* build-in `open()` by `fake_filessystem.FakeFileOpen`
+
+```python
+
+   import pyfakefs.fake_filesystem as fake_fs
+
+   # Create a faked file system
+   fs = fake_fs.FakeFilesystem()
 
-# Replace some built-in file system related modules you use with faked ones
+   # Do some setup on the faked file system
+   fs.CreateFile('/foo/bar', contents='test')
 
-# Assuming you are using the mock library to ... mock things
-try:
-    from unittest.mock import patch  # In Python 3, mock is built-in
-except ImportError:
-    from mock import patch  # Python 2
+   # Replace some built-in file system related modules you use with faked ones
 
-import pyfakefs.fake_filesystem_shutil as fake_shutil
+   # Assuming you are using the mock library to ... mock things
+   try:
+       from unittest.mock import patch  # In Python 3, mock is built-in
+   except ImportError:
+       from mock import patch  # Python 2
 
-# Note that this fake module is based on the fake fs you just created
-shutil = fake_shutil.FakeShutilModule(fs)
-with patch('mymodule.shutil', shutil):
-    print(shutil.disk_usage('/var/data/'))
+   # Note that this fake module is based on the fake fs you just created
+   os = fake_fs.FakeOsModule(fs)
+   with patch('mymodule.os', os):
+       fd = os.open('/foo/bar', os.O_RDONLY)
+       contents = os.read(fd, 4)
 ```
 
 ## Installation