From 50f042b2b0da209077ef75ca1f4a3f0ed329fe05 Mon Sep 17 00:00:00 2001 From: Eric Torres Date: Sat, 16 Mar 2019 07:44:28 -0700 Subject: [PATCH] Update docstrings and add doctests --- rbackup/hierarchy/hierarchy.py | 37 ++++++++------ rbackup/hierarchy/repository.py | 46 ++++++++++++------ rbackup/hierarchy/snapshot.py | 86 ++++++++++++++------------------- 3 files changed, 89 insertions(+), 80 deletions(-) diff --git a/rbackup/hierarchy/hierarchy.py b/rbackup/hierarchy/hierarchy.py index 4f922da..0949587 100644 --- a/rbackup/hierarchy/hierarchy.py +++ b/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() diff --git a/rbackup/hierarchy/repository.py b/rbackup/hierarchy/repository.py index 5ce3f6e..72bd007 100644 --- a/rbackup/hierarchy/repository.py +++ b/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() diff --git a/rbackup/hierarchy/snapshot.py b/rbackup/hierarchy/snapshot.py index 40abc22..a2fe1b1 100644 --- a/rbackup/hierarchy/snapshot.py +++ b/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()