Update docstrings and add doctests

rbackup/hierarchy/hierarchy.py

@@ -1,38 +1,45 @@
 """
 .. author:: Eric Torres
-.. module:: rbackup.hierarchy
+.. module:: rbackup.hierarchy.hierarchy
     :synopsis: Classes for creating the backup hierarchy.
 """
 
-import os.path
-import datetime
-import glob
-
 
+# ========== Classes ==========
 class Hierarchy:
-    """A class for organizing the backup root hierarchy.
-    See README.rst for more details."""
+    """A class for organizing the backup root hierarchy."""
 
     def __init__(self, dest):
         """Default constructor for the Hierarchy class.
 
+        Example
+        -------
+        >>> hier = Hierarchy('/tmp')
+        >>> hier.path
+        '/tmp'
+
         :param dest: the root directory of the backup hierarchy
         :type dest: str, bytes
-        :raises: NotADirectoryError if dest is not a directory
         """
-        if not os.path.isdir(dest):
-            raise NotADirectoryError(f"{dest}: no such directory")
-
         self.dest = dest
 
     @property
-    def base_path(self):
+    def path(self):
         """Return the base directory of this hierarchy.
 
-        >>> h = Hierarchy('backup')
-        >>> h.base_path
-        >>> 'backup'
+        Example
+        -------
+        >>> hier = Hierarchy('/tmp')
+        >>> hier.path
+        '/tmp'
 
         :rtype: str
         """
         return self.dest
+
+
+# ========== Functions ==========
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

rbackup/hierarchy/repository.py

@@ -66,16 +66,16 @@ class Repository(Hierarchy):
 
         Example
         -------
-        * Assuming that backup/data has the snapshot dirs:
-          * snapshot-one
-          * snapshot-two
-        >>> repo = Repository('backup')
+        >>> repo = Repository('/tmp')
         >>> repo.snapshots
-        >>> ['backup/data/snapshot-one', 'backup/data/snapshot-two']
+        []
+        >>> repo.create_snapshot()
+        >>> repo.snapshots # doctest: +ELLIPSIS
+        [<...Snapshot ... at 0x...>]
 
         :returns: the names of all snapshots in this repository sorted by
             date
-        :rtype: list
+        :rtype: list of Snapshot objects
         """
         return self._snapshots
 
@@ -85,11 +85,15 @@ class Repository(Hierarchy):
 
         Example
         -------
-        >>> repo = Repository('backup')
-        >>> repo.snapshots
-        >>> ['snapshot-one', 'snapshot-two']
+        >>> repo = Repository('/tmp')
         >>> repo.curr_snapshot
-        >>> Snapshot('backup/data/snapshot-two')
+        >>> repo.snapshots
+        []
+        >>> repo.create_snapshot()
+        >>> repo.snapshots # doctest: +ELLIPSIS
+        [<...Snapshot ... at 0x...>]
+        >>> repo.curr_snapshot # doctest: +ELLIPSIS
+        <...Snapshot ... at 0x...>
 
         :rtype: Snapshot object
         """
@@ -100,16 +104,19 @@ class Repository(Hierarchy):
     ):
         """Create a new snapshot in this repository.
 
+        This method is non-intrusive in that it will not
+        make any changes in the filesystem when called.
+
         Example
         -------
-        >>> repo = Repository('backup')
+        directive   ::= "#" "doctest":" ELLIPSIS
+        >>> repo = Repository('/tmp')
         >>> repo.snapshots
-        >>> ['backup/data/snapshot-one', 'backup/data/snapshot-two']
+        []
         >>> repo.curr_snapshot
-        >>> Snapshot('backup/data/snapshot-two')
-        >>> repo.create_snapshot('three')
-        >>> repo.curr_snapshot
-        >>> Snapshot('backup/data/snapshot-three')
+        >>> repo.create_snapshot()
+        >>> repo.curr_snapshot # doctest: +ELLIPSIS
+        <...Snapshot ... at 0x...>
 
         :return: a new Snapshot object
         :rtype: Snapshot object
@@ -126,3 +133,10 @@ class Repository(Hierarchy):
             for s in glob.glob(f"{self._snapshot_dir}/*")
             if os.path.isdir(s)
         ]
+
+
+# ========== Functions ==========
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

rbackup/hierarchy/snapshot.py

@@ -1,103 +1,84 @@
 """
 .. author:: Eric Torres
-.. module:: rbackup.hierarchy
-    :synopsis: Classes for creating the backup hierarchy.
+.. module:: r/tmp.hierarchy.snapshot
+    :synopsis: Classes for creating the /tmp hierarchy.
 """
-
 import os.path
 
+from rbackup.hierarchy.hierarchy import Hierarchy
+
 
 class Snapshot(Hierarchy):
     """Hierarchy for a single snapshot.
-
-    Example
-    -------
-    >>> repo = Repository('backup')
-    >>> snapshots = repo.snapshots
-    >>> prev = snapshots[-1]
-    >>> prev.name
-    >>> 'snapshot-{prevtime}'
-    >>> prev.home_dir
-    >>> 'backup/data/snapshot-{prevtime}/home'
-    >>> curr = repo.curr_snapshot
-    >>> curr.name
-    >>> 'snapshot-{utcnow}'
-    >>> curr.home_dir
-    >>> 'backup/data/snapshot-{utcnow}/home'
+    Attributes
+    ----------
+    * path (inherited from Hierarchy)
+    * name
+    * boot_dir
+    * etc_dir
+    * home_dir
+    * root_home_dir
     """
 
     def __init__(self, path):
         """Default constructor for the Snapshot class."""
         super().__init__(path)
 
-    @property
-    def path(self):
-        """Return the canonical path of this snapshot.
-        Example
-        -------
-        >>> s = Snapshot('backup/data/snapshot-{utcprev}')
-        >>> s.name
-        >>> 'backup/data/snapshot-{utcprev}'
-
-        :rtype: str
-        """
-        return self.base_path
-
     @property
     def name(self):
         """Return the name of this snapshot.
 
         Example
         -------
-        >>> s = Snapshot('backup/data/snapshot-{utcprev}')
+        >>> s = Snapshot('/tmp/data/snapshot-new')
         >>> s.name
-        >>> 'snapshot-{utcprev}'
+        'snapshot-new'
 
         :rtype: str
         """
-        return os.path.basename(self.base_path)
+        return os.path.basename(self.path)
 
     @property
     def boot_dir(self):
-        """Retrieve the /boot backup directory of this snapshot.
+        """Retrieve the /boot /tmp directory of this snapshot.
 
         Example
         -------
-        >>> s = Snapshot('backup/data/snapshot-{utcnow}')
+        >>> s = Snapshot('/tmp/data/snapshot-new')
         >>> s.boot_dir
-        >>> 'backup/data/snapshot-{utcnow}/boot'
+        '/tmp/data/snapshot-new/boot'
 
         :rtype: str
         """
-        return os.path.join(self.base_path, "boot")
+        return os.path.join(self.path, "boot")
 
     @property
     def etc_dir(self):
-        """Retrieve the /etc backup directory of this snapshot.
+        """Retrieve the /etc /tmp directory of this snapshot.
 
         Example
         -------
-        >>> s = Snapshot('backup/data/snapshot-{utcnow}')
+        >>> s = Snapshot('/tmp/data/snapshot-new')
         >>> s.etc_dir
-        >>> 'backup/data/snapshot-{utcnow}/etc'
+        '/tmp/data/snapshot-new/etc'
 
         :rtype: str
         """
-        return os.path.join(self.base_path, "etc")
+        return os.path.join(self.path, "etc")
 
     @property
     def home_dir(self):
-        """Retrieve the /home backup directory of this snapshot.
+        """Retrieve the /home /tmp directory of this snapshot.
 
         Example
         -------
-        >>> s = Snapshot('backup/data/snapshot-{utcnow}')
+        >>> s = Snapshot('/tmp/data/snapshot-new')
         >>> s.home_dir
-        >>> 'backup/data/snapshot-{utcnow}/home'
+        '/tmp/data/snapshot-new/home'
 
         :rtype: str
         """
-        return os.path.join(self.base_path, "home")
+        return os.path.join(self.path, "home")
 
     @property
     def root_home_dir(self):
@@ -105,10 +86,17 @@ class Snapshot(Hierarchy):
 
         Example
         -------
-        >>> s = Snapshot('backup/data/snapshot-{utcnow}')
+        >>> s = Snapshot('/tmp/data/snapshot-new')
         >>> s.root_home_dir
-        >>> 'backup/data/snapshot-{utcnow}/root'
+        '/tmp/data/snapshot-new/root'
 
         :rtype: str
         """
-        return os.path.join(self.base_path, "root")
+        return os.path.join(self.path, "root")
+
+
+# ========== Functions ==========
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()