uploading proposed public API

diff --git a/docs/design.py b/docs/design.py
new file mode 100644 (file)
index 0000000..c086f62
--- /dev/null
+++ b/docs/design.py
@@ -0,0 +1,132 @@
+'''
+Backup Files Index format:
+ * one line per file so that it can be parsed line by line
+ * it will contain one line per file in the directory, even if the file didn't
+   change. This way we can restore a diff backup without needing previous diffs.
+
+{"path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value}
+{"path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value}
+[...]
+{"path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value}
+
+'''
+
+'''
+DeltaTar proposed backup directory structure is quite simple:
+
+backups/
+├── 1/
+│   ├── backup_index
+│   ├── backup.tar.gz.aes128
+│   ├── backup.tar.gz.aes128.1
+│   ├── backup.tar.gz.aes128.2
+│   └── backup.tar.gz.aes128.3
+├── 2_label/
+│   ├── backup_index
+│   ├── backup.tar.gz.aes128
+└── 3/
+│   ├── backup_index
+    ├── backup.tar.gz.aes128
+    ├── backup.tar.gz.aes128.1
+
+Each subdir corresponds with a specific backup. The ctime of the dir indicates
+when the backup was done and it also contains the optional label (2_label).
+
+The format is kept quite simple so that each subdir can easily be used to do a
+restore independently.
+'''
+
+
+class DeltaTar(object):
+    '''
+    Backup class used to create backups
+    '''
+
+    def __init__(self, excluded_files=[], max_volume_size,
+                 included_files=[], filter_func=None, mode="tar",
+                 index_encrypted=True, password=None, log_path=None):
+        '''
+        Constructor. Configures the diff engine.
+
+        Parameters:
+        - excluded_files: list of files to exclude in the index. It can
+          contain python regular expressions.
+
+        - excluded_files: list of files to include in the index. It can
+          contain python regular expressions. If empty, all files in the source
+          path will be backed up, but of the list is set then only the files
+          include in the list will be backed up.
+
+        - filter_func: custom filter of files to be backed up. Unused by
+          default. The function receives a file path and must return a boolean.
+
+        - mode: Mode in which the delta will be created. Accepts the same modes
+          as our tarfile python library.
+
+        - index_encrypted: whether the index should be encrypted or not. Only
+          makes sense to set it as True if mode includes aes128 or aes256
+
+        - password: used together with aes modes to encrypt and decrypt backups.
+
+        - log_path: creates the backup log in this path.
+        '''
+        pass
+
+    def create_backup(self, source_path, backup_path, label=None):
+        '''
+        Creates a backup.
+
+        Parameters:
+        - source_path: source path to the directory to back up.
+        - backup_path: path where the back up will be stored.
+        - label: optional label for the backup.
+        '''
+        pass
+
+    def restore_backup(self, backup_path, target_path, restore_label=None,
+                       restore_date=None):
+        '''
+        Restores a backup.
+
+        Parameters:
+        - backup_path: path where the back up will is stored.
+        - target_path: path to restore.
+        - restore_label: label to be restored, optional.
+        - restore_date: date to be restored, optional.
+        '''
+
+class TestDeltaTar(UnitTest):
+    '''
+    This is an example of how DeltaTar class could be used
+    '''
+    def test_create(self):
+        # constructor of DeltaTar class allows to set the configuration
+        deltatar = DeltaTar(
+            # these options are the same as in tarfile:
+            mode="tar#gz.aes128"
+            max_volume_size=100*1024*1024, # 100MB
+            )
+
+        # create first backup
+        deltatar.create_backup(
+            source_path="/path/to/important/dir/",
+            backup_path="/var/backups/")
+
+        # here: change  some files
+
+        # create second backup
+        deltatar.create_backup(
+            source_path="/path/to/important/dir/",
+            backup_path="/var/backups/",
+            label="labelled backup")
+
+        # restore backup in another dir. it will restore last version
+        deltatar.restore_backup(
+            backup_path="/var/backups/",
+            target_path="/path/to/second/dir/")
+
+        # roll back to the second backup
+        deltatar.restore_backup(
+            backup_path="/var/backups/",
+            target_path="/path/to/second/dir/",
+            restore_label="labelled backup")