Added even more docstrings everywhere

app/specs/container.py

@@ -1,4 +1,4 @@
-"""Module defining a Container-based spec."""
+"""Module defining a container-based spec."""
 from .spec import Spec
 from typing import Union
 from pathlib import Path
@@ -46,6 +46,7 @@ class ContainerSpec(Spec):
         self.command = command
 
     def backup(self):
+        """Create a new backup."""
         # Remove excess backups
         self.remove_backups()
 

app/specs/directory.py

@@ -1,3 +1,6 @@
+"""Module defining a directory-based spec."""
+
+
 from .spec import Spec
 from pathlib import Path
 from typing import Union
@@ -23,6 +26,18 @@ class DirectorySpec(Spec):
         extension: str,
         notify=None,
     ):
+        """
+        Initialize a new DirectorySpec object.
+
+        Args:
+            name: name of the spec
+            source: what directory to back up
+            destination: where to store the backup
+            limit: how many backups to keep
+            command: what command to use to create the backup
+            extension: extension of the backup files
+            notify: a Notifier object that handles sending notifications
+        """
         super().__init__(name, destination, limit, extension, notify)
 
         self.source = source if type(source) == Path else Path(source)
@@ -36,6 +51,7 @@ class DirectorySpec(Spec):
         self.command = command
 
     def backup(self):
+        """Create a new backup."""
         # Remove excess backups
         self.remove_backups()
 

app/specs/spec.py

@@ -1,3 +1,6 @@
+"""This module contains the base Spec class."""
+
+
 from pathlib import Path
 from typing import Union, Dict
 import skeleton
@@ -7,9 +10,7 @@ import inspect
 
 
 class Spec:
-    """
-    Base class for all other spec types.
-    """
+    """Base class for all other spec types."""
 
     _SKEL = {
         "destination": None,
@@ -31,23 +32,25 @@ class Spec:
         extension: str,
         notify=None,
     ):
-        """
+        """Initialize a new Spec object.
+
+        This initializer usually gets called by a subclass's init instead of
+        directly.
+
         Args:
             name: name of the spec
             destination: directory where the backups shall reside
             limit: max amount of backups
             notifier: notifier object
         """
-
         self.name = name
-        self.destination = (
-            destination if type(destination) == Path else Path(destination)
-        )
+        self.destination = Path(destination)
 
         # Create destination if non-existent
         try:
             self.destination.mkdir(parents=True, exist_ok=True)
 
+        # TODO just make this some checks in advance
         except FileExistsError:
             raise NotADirectoryError(
                 "{} already exists, but isn't a directory.".format(
@@ -61,8 +64,7 @@ class Spec:
 
     @classmethod
     def skeleton(cls: "Spec") -> Dict:
-        """
-        Return the skeleton for the given class.
+        """Return the skeleton for the given class.
 
         It works by inspecting the inheritance tree and merging the skeleton
         for each of the parents.
@@ -78,10 +80,7 @@ class Spec:
         )
 
     def remove_backups(self):
-        """
-        Remove all backups exceeding the limit
-        """
-
+        """Remove all backups exceeding the limit."""
         files = sorted(
             self.destination.glob("*." + self.extension),
             key=os.path.getmtime,
@@ -93,13 +92,22 @@ class Spec:
                 path.unlink()
 
     def backup(self):
+        """Create a new backup.
+
+        This function should be implemented by the subclasses.
+        """
         raise NotImplementedError()
 
     def restore(self):
+        """Restore a given backup (NOT IMPLEMENTED).
+
+        This function should be implemented by the subclasses.
+        """
         raise NotImplementedError()
 
     @classmethod
     def from_dict(cls, name, obj: Dict, defaults: Dict) -> "Spec":
+        """Create the class given a dictionary (e.g. from a config)."""
         # Combine defaults with skeleton, creating new skeleton
         skel = skeleton.merge(cls.skeleton(), defaults)
 
@@ -109,4 +117,7 @@ class Spec:
         return cls(name, **obj)
 
     def to_dict(self):
+        """Export the class as a dictionary.
+
+        This function should be imnplemented by the subclasses."""
         raise NotImplementedError()

app/specs/volume.py

@@ -6,9 +6,7 @@ import subprocess
 
 
 class VolumeSpec(Spec):
-    """
-    A spec for backing up a Docker volume.
-    """
+    """A spec for backing up a Docker volume."""
 
     _SKEL = {
         "volume": None,