Add the EmptyDirectorySnapshot class (fixes #612)

* Added DirectorySnapshotEmpty (#612).

* Added test to show (and test) the usage of DirectorySnapshotEmpty (#612).

* Added sphinx class for DirectorySnapshotEmpty.

* Changed class name from DirectorySnapshotEmpty to EmptyDirectorySnapshot.

* Added documentation.

* Small doc fix.

* Updated changelog.rst.

changelog.rst

@@ -11,8 +11,8 @@ Changelog
 Other Changes
 =============
 
--
-- Thanks to our beloved contributors:
+- [snapshot] Added EmptyDirectorySnapshot (`#613 <https://github.com/gorakhargosh/watchdog/pull/613>`__)
+- Thanks to our beloved contributors: @Ajordat
 
 
 0.10.0

src/watchdog/utils/dirsnapshot.py

@@ -42,6 +42,10 @@
    :members:
    :show-inheritance:
 
+.. autoclass:: DirectorySnapshotEmpty
+   :members:
+   :show-inheritance:
+
 """
 
 import errno
@@ -347,3 +351,30 @@ def __str__(self):
 
     def __repr__(self):
         return str(self._stat_info)
+
+
+class EmptyDirectorySnapshot(object):
+    """Class to implement an empty snapshot. This is used together with
+    DirectorySnapshot and DirectorySnapshotDiff in order to get all the files/folders
+    in the directory as created.
+    """
+
+    @staticmethod
+    def path(_):
+        """Mock up method to return the path of the received inode. As the snapshot
+        is intended to be empty, it always returns None.
+
+        :returns:
+            None.
+        """
+        return None
+
+    @property
+    def paths(self):
+        """Mock up method to return a set of file/directory paths in the snapshot. As
+        the snapshot is intended to be empty, it always returns an empty set.
+
+        :returns:
+            An empty set.
+        """
+        return set()

tests/test_snapshot_diff.py

@@ -21,6 +21,7 @@
 
 from watchdog.utils.dirsnapshot import DirectorySnapshot
 from watchdog.utils.dirsnapshot import DirectorySnapshotDiff
+from watchdog.utils.dirsnapshot import EmptyDirectorySnapshot
 from watchdog.utils import platform
 
 from .shell import mkdir, touch, mv, rm
@@ -200,3 +201,19 @@ def inode(self, path):
     diff_without_device = DirectorySnapshotDiff(ref, snapshot, ignore_device=True)
     assert diff_without_device.files_deleted == []
     assert diff_without_device.files_created == []
+
+
+def test_empty_snapshot(p):
+    # Create a file and declare a DirectorySnapshot and a DirectorySnapshotEmpty.
+    # When we make the diff, although both objects were declared with the same items on
+    # the directory, the file and directories created BEFORE the DirectorySnapshot will
+    # be detected as newly created.
+
+    touch(p('a'))
+    mkdir(p('b', 'c'), parents=True)
+    ref = DirectorySnapshot(p(''))
+    empty = EmptyDirectorySnapshot()
+
+    diff = DirectorySnapshotDiff(empty, ref)
+    assert diff.files_created == [p('a')]
+    assert sorted(diff.dirs_created) == sorted([p(''), p('b'), p('b', 'c')])