dar-backup 0.5.17__py3-none-any.whl → 0.6.1__py3-none-any.whl

dar_backup/__about__.py

@@ -1 +1 @@
-__version__ = "0.5.17"
+__version__ = "0.6.1"

dar_backup/config_settings.py

@@ -14,6 +14,7 @@ class ConfigSettings:
         max_size_verification_mb (int): The maximum size for verification in megabytes.
         min_size_verification_mb (int): The minimum size for verification in megabytes.
         no_files_verification (int): The number of files for verification.
+        command_timeout_secs (int): The timeout in seconds for commands.
         backup_dir (str): The directory for backups.
         test_restore_dir (str): The directory for test restores.
         backup_d_dir (str): The directory for backup.d.
@@ -38,6 +39,7 @@ class ConfigSettings:
             self.max_size_verification_mb = int(self.config['MISC']['MAX_SIZE_VERIFICATION_MB'])
             self.min_size_verification_mb = int(self.config['MISC']['MIN_SIZE_VERIFICATION_MB'])
             self.no_files_verification = int(self.config['MISC']['NO_FILES_VERIFICATION'])
+            self.command_timeout_secs = int(self.config['MISC']['COMMAND_TIMEOUT_SECS'])
             self.backup_dir = self.config['DIRECTORIES']['BACKUP_DIR']
             self.test_restore_dir = self.config['DIRECTORIES']['TEST_RESTORE_DIR']
             self.backup_d_dir = self.config['DIRECTORIES']['BACKUP.D_DIR']

dar_backup/dar_backup.py

@@ -33,7 +33,7 @@ from dar_backup.util import RestoreError
 logger = None
 
 
-def backup(backup_file: str, backup_definition: str, darrc: str):
+def backup(backup_file: str, backup_definition: str, darrc: str,  config_settings: ConfigSettings):
     """
     Performs a full backup using the 'dar' command.
 
@@ -63,31 +63,26 @@ def backup(backup_file: str, backup_definition: str, darrc: str):
     command = ['dar', '-c', backup_file, "-N", '-B', darrc, '-B', backup_definition, '-Q', "compress-exclusion",  "verbose"]
     logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
     try:
-        process = run_command(command)
-        stdout, stderr = process.communicate()
+        process = run_command(command, config_settings.command_timeout_secs)
+        logger.info("Back from run_command")
         if process.returncode == 0:
             logger.info("FULL backup completed successfully.")
         elif process.returncode == 5:
             logger.warning("Backup completed with some files not backed up, this can happen if files are changed/deleted during the backup.")
         else:
-            logger.error("dar return code: ", process.returncode)
-            logger.error("stdout: ", stdout)
-            logger.error("stderr: ", stderr)
-            raise Exception(stderr)
+            raise Exception(str(process))
     except subprocess.CalledProcessError as e:
         logger.error(f"Backup command failed: {e}")
         raise BackupError(f"Backup command failed: {e}") from e
     except Exception as e:
         logger.exception(f"Unexpected error during backup")
-        logger.error("stderr:", stderr)
-        logger.error("stdout: ", stdout)
         raise BackupError(f"Unexpected error during backup: {e}") from e
  
  
 
 
 
-def differential_backup(backup_file: str, backup_definition: str, base_backup_file: str, darrc: str):
+def differential_backup(backup_file: str, backup_definition: str, base_backup_file: str, darrc: str, config_settings: ConfigSettings):
     """
     Creates a differential backup based on a specified base backup.
 
@@ -120,16 +115,12 @@ def differential_backup(backup_file: str, backup_definition: str, base_backup_fi
     logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
     try:
         process = run_command(command)
-        stdout, stderr = process.communicate()
         if process.returncode == 0:
             logger.info("DIFF backup completed successfully.")
         elif process.returncode == 5:
             logger.warning("Backup completed with some files not backed up, this can happen if files are changed/deleted during the backup.")
         else:
-            logger.error("dar return code: ", process.returncode)
-            logger.error("stdout: ", stdout)
-            logger.error("stderr: ", stderr)
-            raise Exception(stderr)
+            raise Exception(str(process))
     except subprocess.CalledProcessError as e:
         logger.error(f"Differential backup command failed: {e}")
         raise DifferentialBackupError(f"Differential backup command failed: {e}") from e
@@ -139,7 +130,7 @@ def differential_backup(backup_file: str, backup_definition: str, base_backup_fi
         raise DifferentialBackupError(f"Unexpected error during differential backup: {e}") from e
 
 
-def incremental_backup(backup_file: str, backup_definition: str, last_backup_file: str, darrc: str):
+def incremental_backup(backup_file: str, backup_definition: str, last_backup_file: str, darrc: str, config_settings: ConfigSettings):
     """
     Creates an incremental backup based on the last backup file.
 
@@ -173,23 +164,18 @@ def incremental_backup(backup_file: str, backup_definition: str, last_backup_fil
     command = ['dar', '-c', backup_file, "-N", '-B', darrc, '-B', backup_definition, '-A', last_backup_file, '-Q', "compress-exclusion",  "verbose"]
     logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
     try:
-        process = run_command(command)
-        stdout, stderr = process.communicate()
+        process = run_command(command, config_settings.command_timeout_secs)
         if process.returncode == 0:
             logger.info("INCR backup completed successfully.")
         elif process.returncode == 5:
             logger.warning("Backup completed with some files not backed up, this can happen if files are changed/deleted during the backup.")
         else:
-            logger.error("dar return code: ", process.returncode)
-            logger.error("stdout: ", stdout)
-            logger.error("stderr: ", stderr)
-            raise Exception(stderr)
+            raise Exception(str(process))
     except subprocess.CalledProcessError as e:
         logger.error(f"Incremental backup command failed: {e}")
         raise IncrementalBackupError(f"Incremental backup command failed: {e}") from e
     except Exception as e:
         logger.exception(f"Unexpected error during incremental backup")
-        logger.error("Exception details:", exc_info=True)
         raise IncrementalBackupError(f"Unexpected error during incremental backup: {e}") from e
 
 
@@ -285,12 +271,11 @@ def verify(args: argparse.Namespace, backup_file: str, backup_definition: str, c
     result = True
     command = ['dar', '-t', backup_file, '-Q']
     logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
-    process = run_command(command)
-    stdout, stderr = process.communicate()
+    process = run_command(command, config_settings.command_timeout_secs)
     if process.returncode == 0:
         logger.info("Archive integrity test passed.")
     else:
-        raise Exception(stderr)
+        raise Exception(str(process))
 
     if args.do_not_compare:
         return result
@@ -324,11 +309,9 @@ def verify(args: argparse.Namespace, backup_file: str, backup_definition: str, c
             logger.info(f"Restoring file: '{restored_file_path}' from backup to: '{config_settings.test_restore_dir}' for file comparing")
             command = ['dar', '-x', backup_file, '-g', restored_file_path.lstrip("/"), '-R', config_settings.test_restore_dir, '-O', '-Q']
             logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
-            process = run_command(command)
-            stdout, stderr = process.communicate()
+            process = run_command(command, config_settings.command_timeout_secs)    
             if process.returncode != 0:
-                logger.error(f"Restore failed, dar return code: {process.returncode}.")
-                raise Exception(stderr)
+                raise Exception(str(process))
 
             if filecmp.cmp(os.path.join(config_settings.test_restore_dir, restored_file_path.lstrip("/")), os.path.join(root_path, restored_file_path.lstrip("/")), shallow=False):
                 logger.info(f"Success: file '{restored_file_path}' matches the original")
@@ -343,7 +326,7 @@ def verify(args: argparse.Namespace, backup_file: str, backup_definition: str, c
 
 
 
-def restore_backup(backup_name: str, backup_dir: str, restore_dir: str, selection: str =None):
+def restore_backup(backup_name: str, config_settings: ConfigSettings, restore_dir: str, selection: str =None):
     """
     Restores a backup file to a specified directory.
 
@@ -353,7 +336,7 @@ def restore_backup(backup_name: str, backup_dir: str, restore_dir: str, selectio
         restore_dir (str): The directory where the backup should be restored to.
         selection (str, optional): A selection criteria to restore specific files or directories. Defaults to None.
     """
-    backup_file = os.path.join(backup_dir, backup_name)
+    backup_file = os.path.join(config_settings.backup_dir, backup_name)
     command = ['dar', '-x', backup_file, '-O', '-Q', '-D']
     if restore_dir:
         if not os.path.exists(restore_dir):
@@ -364,13 +347,14 @@ def restore_backup(backup_name: str, backup_dir: str, restore_dir: str, selectio
         command.extend(selection_criteria)
     logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
     try:
-        run_command(command)
+        process = run_command(command, config_settings.command_timeout_secs)
+        if process.returncode == 0:
+            logger.info(f"Restore completed successfully to: '{restore_dir}'")
+        else:
+            raise Exception(str(process))
     except subprocess.CalledProcessError as e:
-        logger.error("Exception details:", exc_info=True)
         raise RestoreError(f"Restore command failed: {e}") from e
     except Exception as e:
-        logger.exception(f"Unexpected error during restore")
-        logger.error("Exception details:", exc_info=True)
         raise RestoreError(f"Unexpected error during restore: {e}") from e
 
 
@@ -388,19 +372,24 @@ def get_backed_up_files(backup_name: str, backup_dir: str):
     """
     logger.debug(f"Getting backed up files from DAR archive in xml: '{backup_name}'")
     backup_path = os.path.join(backup_dir, backup_name)
-    command = ['dar', '-l', backup_path, '-am', '-as', "-Txml" , '-Q']
-    logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
-    process = run_command(command)
-    stdout, stderr = process.communicate()
-    # Parse the XML data
-    root = ET.fromstring(stdout)
-    output = None  # help gc
-    # Extract full paths and file size for all <File> elements
-    file_paths = find_files_with_paths(root)
-    root = None # help gc
-    logger.trace(f"Backed up files in dar archive: '{backup_name}'")
-    logger.trace(file_paths)
-    return file_paths
+    try:
+        command = ['dar', '-l', backup_path, '-am', '-as', "-Txml" , '-Q']
+        logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
+        process = run_command(command)
+        # Parse the XML data
+        root = ET.fromstring(process.stdout)
+        output = None  # help gc
+        # Extract full paths and file size for all <File> elements
+        file_paths = find_files_with_paths(root)
+        root = None # help gc
+        logger.trace(str(process))
+        logger.trace(file_paths)
+        return file_paths
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Error listing backed up files from DAR archive: '{backup_name}'")
+        raise BackupError(f"Error listing backed up files from DAR archive: '{backup_name}'") from e
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error listing backed up files from DAR archive: '{backup_name}'") from e
 
 
 def list_contents(backup_name, backup_dir, selection=None):
@@ -416,16 +405,26 @@ def list_contents(backup_name, backup_dir, selection=None):
         None
     """
     backup_path = os.path.join(backup_dir, backup_name)
-    command = ['dar', '-l', backup_path, '-am', '-as', '-Q']
-    if selection:
-        selection_criteria = shlex.split(selection)
-        command.extend(selection_criteria)
-    logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
-    process = run_command(command)
-    stdout, stderr = process.communicate()
-    for line in stdout.splitlines():
-        if "[--- REMOVED ENTRY ----]" in line or "[Saved]" in line:
-            print(line)
+    try:
+        command = ['dar', '-l', backup_path, '-am', '-as', '-Q']
+        if selection:
+            selection_criteria = shlex.split(selection)
+            command.extend(selection_criteria)
+        logger.info(f"Running command: {' '.join(map(shlex.quote, command))}")
+        process = run_command(command)
+        stdout,stderr = process.stdout, process.stderr
+        if process.returncode != 0:
+            logger.error(f"Error listing contents of backup: '{backup_name}'")
+            raise subprocess.CalledProcessError(str(process))
+        for line in stdout.splitlines():
+            if "[--- REMOVED ENTRY ----]" in line or "[Saved]" in line:
+                print(line)
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Error listing contents of backup: '{backup_name}'")
+        raise BackupError(f"Error listing contents of backup: '{backup_name}'") from e  
+    except Exception as e:
+        raise RuntimeError(f"Unexpected error listing contents of backup: '{backup_name}'") from e  
+
 
 
 def perform_backup(args: argparse.Namespace, config_settings: ConfigSettings, backup_type: str):
@@ -484,7 +483,7 @@ def perform_backup(args: argparse.Namespace, config_settings: ConfigSettings, ba
                 continue
 
             if backup_type == 'FULL':
-                backup(backup_file, backup_definition_path, args.darrc)
+                backup(backup_file, backup_definition_path, args.darrc, config_settings)
             else:
                 base_backup_type = 'FULL' if backup_type == 'DIFF' else 'DIFF'
                 
@@ -505,9 +504,9 @@ def perform_backup(args: argparse.Namespace, config_settings: ConfigSettings, ba
                     latest_base_backup = os.path.join(config_settings.backup_dir, base_backups[-1].rsplit('.', 2)[0])
 
                 if backup_type == 'DIFF':
-                    differential_backup(backup_file, backup_definition_path, latest_base_backup, args.darrc)
+                    differential_backup(backup_file, backup_definition_path, latest_base_backup, args.darrc, config_settings)
                 elif backup_type == 'INCR':
-                    incremental_backup(backup_file, backup_definition_path, latest_base_backup, args.darrc) 
+                    incremental_backup(backup_file, backup_definition_path, latest_base_backup, args.darrc, config_settings) 
 
             logger.info("Starting verification...")
             result = verify(args, backup_file, backup_definition_path, config_settings)
@@ -524,7 +523,7 @@ def perform_backup(args: argparse.Namespace, config_settings: ConfigSettings, ba
             logger.exception(f"Error during {backup_type} backup process, continuing on next backup definition")
             logger.error("Exception details:", exc_info=True)
 
-def generate_par2_files(backup_file: str, configSettings: ConfigSettings):
+def generate_par2_files(backup_file: str, config_settings: ConfigSettings):
     """
     Generate PAR2 files for a given backup file in the specified backup directory.
 
@@ -538,13 +537,13 @@ def generate_par2_files(backup_file: str, configSettings: ConfigSettings):
     Returns:
         None
     """
-    for filename in os.listdir(configSettings.backup_dir):
+    for filename in os.listdir(config_settings.backup_dir):
         if os.path.basename(backup_file) in filename:
             # Construct the full path to the file
-            file_path = os.path.join(configSettings.backup_dir, filename)
+            file_path = os.path.join(config_settings.backup_dir, filename)
             # Run the par2 command to generate redundancy files with error correction
-            command = ['par2', 'create', f'-r{configSettings.error_correction_percent}', '-q', '-q', file_path]
-            process = run_command(command)
+            command = ['par2', 'create', f'-r{config_settings.error_correction_percent}', '-q', '-q', file_path]
+            process = run_command(command, config_settings.command_timeout_secs)
             if process.returncode != 0:
                 logger.error(f"Error generating par2 files for {file_path}")
                 raise subprocess.CalledProcessError(process.returncode, command)
@@ -628,14 +627,15 @@ def requirements(type: str, config_setting: ConfigSettings):
         for key in sorted(config_setting.config[type].keys()):
             script = config_setting.config[type][key]
             try:
-                result = subprocess.run(script, shell=True, check=True)
+                result = subprocess.run(script, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, shell=True, check=True)
                 logger.info(f"{type} {key}: '{script}' run, return code: {result.returncode}")
                 logger.info(f"{type} stdout:\n{result.stdout}")
+                if result.returncode != 0:
+                    logger.error(f"{type} stderr:\n{result.stderr}")
+                    raise RuntimeError(f"{type} {key}: '{script}' failed, return code: {result.returncode}")    
             except subprocess.CalledProcessError as e:
                 logger.error(f"Error executing {key}: '{script}': {e}")
-                if result:
-                    logger.error(f"{type} stderr:\n{result.stderr}")
-                    raise e
+                raise e
 
 
 def main():
@@ -658,8 +658,8 @@ def main():
     parser.add_argument('-l', '--list', action='store_true', help="List available archives.")
     parser.add_argument('--list-contents', help="List the contents of the specified archive.")
     parser.add_argument('--selection', help="dar file selection for listing/restoring specific files/directories.")
-    parser.add_argument('-r', '--restore', help="Restore specified archive.")
-    parser.add_argument('--restore-dir', help="Directory to restore files to.")
+    parser.add_argument('-r', '--restore', nargs=1, type=str, help="Restore specified archive.")
+    parser.add_argument('--restore-dir', nargs=1, type=str, help="Directory to restore files to.")
     parser.add_argument('--verbose', action='store_true', help="Print various status messages to screen")
     parser.add_argument('--log-level', type=str, help="`debug` or `trace`", default="info")
     parser.add_argument('--log-stdout', action='store_true', help='also print log messages to stdout')
@@ -739,29 +739,24 @@ def main():
             list_contents(args.list_contents, config_settings.backup_dir, args.selection)
         elif args.restore:
             restore_dir = args.restore_dir if args.restore_dir else config_settings.test_restore_dir
-            restore_backup(args.restore, config_settings.backup_dir, restore_dir, args.selection)
+            restore_backup(args.restore, config_settings, restore_dir, args.selection)
         else:
             parser.print_help()
 
         requirements('POSTREQ', config_settings)
 
-
+        args.verbose and print("\033[1m\033[32mSUCCESS\033[0m No errors encountered")
+        sys.exit(0)
     except Exception as e:
         logger.exception("An error occurred")
         logger.error("Exception details:", exc_info=True)
-
-    end_time=int(time())
-    logger.info(f"END TIME: {end_time}")
-
-    error_lines = extract_error_lines(config_settings.logfile_location, start_time, end_time)
-    if len(error_lines) > 0:
         args.verbose and print("\033[1m\033[31mErrors\033[0m encountered")
-        for line in error_lines:
-            args.verbose and print(line)
-        sys.exit(1)
-    else:
-        args.verbose and print("\033[1m\033[32mSUCCESS\033[0m No errors encountered")
-        sys.exit(0)
+        sys.exit(1) 
+    finally:
+        end_time=int(time())
+        logger.info(f"END TIME: {end_time}")
+
+#    error_lines = extract_error_lines(config_settings.logfile_location, start_time, end_time)
 
 
 if __name__ == "__main__":

dar_backup/manager.py

@@ -66,7 +66,7 @@ def create_db(backup_def: str, config_settings: ConfigSettings):
             logger.info(f'Database created: "{database_path}"')
         else:
             logger.error(f'Something went wrong creating the database: "{database_path}"')
-            stdout, stderr = process.communicate()
+            stdout, stderr = process.stdout, process.stderr 
             logger.error(f"stderr: {stderr}")
             logger.error(f"stdout: {stdout}")
 
@@ -80,7 +80,7 @@ def list_db(backup_def: str, config_settings: ConfigSettings):
         return 1
     command = ['dar_manager', '--base', database_path, '--list']
     process = run_command(command)
-    stdout, stderr = process.communicate()
+    stdout, stderr = process.stdout, process.stderr 
     if process.returncode != 0:
         logger.error(f'Error listing catalogs for: "{database_path}"')
         logger.error(f"stderr: {stderr}")  
@@ -111,7 +111,7 @@ def add_specific_archive(archive: str, config_settings: ConfigSettings):
     
     command = ['dar_manager', '--base', database_path, "--add", archive_path, "-ai", "-Q"]
     process = run_command(command)
-    stdout, stderr = process.communicate()
+    stdout, stderr = process.stdout, process.stderr
 
     if process.returncode == 0:
         logger.info(f'"{archive_path}" added to it\'s catalog')

dar_backup/util.py

@@ -7,7 +7,7 @@ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW,
 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 See section 15 and section 16 in the supplied "LICENSE" file
 """
-
+import typing
 import locale
 import logging
 import os
@@ -18,6 +18,8 @@ import sys
 import traceback
 from datetime import datetime
 
+from typing import NamedTuple
+
 logger=None
 
 class BackupError(Exception):
@@ -37,7 +39,9 @@ class RestoreError(Exception):
     pass
 
 
-def setup_logging(log_file: str, log_level: str, log_to_stdout=False) -> logging.Logger:
+
+
+def setup_logging(log_file: str, log_level: str, log_to_stdout: bool=False, logger_name: str=__name__) -> logging.Logger:
     """
     log_level can be set to "debug" or "trace" for more verbose logging.
     """    
@@ -64,17 +68,19 @@ def setup_logging(log_file: str, log_level: str, log_to_stdout=False) -> logging
             level_used = TRACE_LEVEL_NUM
             logger.setLevel(TRACE_LEVEL_NUM)
 
+        formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')  
+
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(level_used)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
         if log_to_stdout:
-            # Create a handler for the console
             stdout_handler = logging.StreamHandler(sys.stdout)
             stdout_handler.setLevel(level_used)
-            formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')  
             stdout_handler.setFormatter(formatter)
             logger.addHandler(stdout_handler)
 
-        logging.basicConfig(filename=log_file, level=level_used,
-                            format='%(asctime)s - %(levelname)s - %(message)s')
-
     except Exception as e:
         print("logging not initialized, exiting.")
         traceback.print_exc()
@@ -83,30 +89,58 @@ def setup_logging(log_file: str, log_level: str, log_to_stdout=False) -> logging
     return logger
 
 
+class CommandResult(NamedTuple):
+    """
+    The reult of the run_command() function.
+    """
+    process: subprocess.CompletedProcess
+    stdout: str
+    stderr: str
+    returncode: int
+    timeout: int
+    command: list[str]
+
+    def __str__(self):
+        return f"CommandResult: [Return Code: '{self.returncode}', Stdout: '{self.stdout}', Stderr: '{self.stderr}', Timeout: '{self.timeout}', Command: '{self.command}']"
 
 
-def run_command(command: list[str]) -> subprocess.CompletedProcess:
+def run_command(command: list[str], timeout: int=30) -> typing.NamedTuple:
     """
     Executes a given command via subprocess and captures its output.
 
     Args:
         command (list): The command to be executed, represented as a list of strings.
+        timeout (int): The maximum time in seconds to wait for the command to complete.Defaults to 30 seconds.
 
     Returns:
-        subprocess.CompletedProcess
+        a typing.NamedTuple of class dar-backup.util.CommandResult with the following properties:
+        - process: of type subprocess.CompletedProcess: The result of the command execution.
+        - stdout: of type str: The standard output of the command.
+        - stderr: of type str: The standard error of the command.
+        - returncode: of type int: The return code of the command.
+        - timeout: of type int: The timeout value in seconds used to run the command.
+        - command: of type list[str): The command executed.
     
     Raises:
+        subprocess.TimeoutExpired: if the command execution times out (see `timeout` parameter).
         Exception: raise exceptions during command runs.
     """
+    stdout = None
+    stderr = None
     try:
-        logger.trace(f"Running command: {command}")
+        logger.debug(f"Running command: {command}")
         process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
-        process.wait() # Popen() and wait() used, for potential future use of stdout and stderr while a subprocess is running.
+        stdout, stderr = process.communicate(timeout)  # Wait with timeout
+        result = CommandResult(process=process, stdout=stdout, stderr=stderr, returncode=process.returncode, timeout=timeout, command=command)
+        logger.debug(f"Command result: {str(result)}")
+    except subprocess.TimeoutExpired:
+        process.terminate()
+        logger.error(f"Command: '{command}' timed out and was terminated.")
+        raise
     except Exception as e:
         logger.error(f"Error running command: {command}", exc_info=True)
         raise
-
-    return process
+    return result
 
 
 def extract_error_lines(log_file_path: str, start_time: str, end_time: str):

{dar_backup-0.5.17.dist-info → dar_backup-0.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dar-backup
-Version: 0.5.17
+Version: 0.6.1
 Summary: A script to do full, differential and incremental backups using dar.     Some files are restored from the backups during verification, after which par2 redundancy files are created.     The script also has a cleanup feature to remove old backups and par2 files.
 Project-URL: Homepage, https://github.com/per2jensen/dar-backup
 Project-URL: Issues, https://github.com/per2jensen/dar-backup/issues
@@ -44,8 +44,11 @@ Description-Content-Type: text/markdown
   Read more here: https://www.gnu.org/licenses/gpl-3.0.en.html, or have a look at the ["LICENSE"](https://github.com/per2jensen/dar-backup/blob/main/LICENSE) file in this repository.
 
 # Status
-As of August 8, 2024 I am using the alpha versions of `dar-backup` (alpha-0.5.9 onwards) in my automated backup routine
+As of August 8, 2024 I am using the alpha versions of `dar-backup` (alpha-0.5.9 onwards) in my automated backup routine.
 
+**Breaking change in version 0.6.0**
+
+Version 0.6.0 and forwards requires the config variable *COMMAND_TIMEOUT_SECS* in the config file.
 
 # Homepage - Github
 This 'dar-backup' package lives at: https://github.com/per2jensen/dar-backup
@@ -79,6 +82,11 @@ MAX_SIZE_VERIFICATION_MB = 20
 MIN_SIZE_VERIFICATION_MB = 1
 NO_FILES_VERIFICATION = 5
 
+# timeout in seconds for backup, test, restore and par2 operations
+# The author has such `dar` tasks running for 10-15 hours on the yearly backups, so a value of 24 hours is used.
+# If a timeout is not specified when using the util.run_command(), a default timeout of 30 secs is used.
+COMMAND_TIMEOUT_SECS = 86400
+
 [DIRECTORIES]
 BACKUP_DIR = /home/user/mnt/dir/
 BACKUP.D_DIR = /home/user/.config/dar-backup/backup.d/
@@ -181,7 +189,7 @@ alias db=". ~/tmp/venv/bin/activate; dar-backup -v"
 Typing `db` at the command line gives this
 ````    
 (venv) user@machine:~$ db
-dar-backup alpha-0.5.12
+dar-backup 0.5.17
 dar-backup.py source code is here: https://github.com/per2jensen/dar-backup
 Licensed under GNU GENERAL PUBLIC LICENSE v3, see the supplied file "LICENSE" for details.
 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW, not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
@@ -190,10 +198,11 @@ See section 15 and section 16 in the supplied "LICENSE" file.
 
 `dar-backup -h` gives the usage output:
 ````
-(venv) user@machine:~$ dar-backup -h
-    
-usage: dar-backup [-h] [-F] [-D] [-I] [-d BACKUP_DEFINITION] [-c CONFIG_FILE] [--darrc DARRC] [--examples] [-l] [--list-contents LIST_CONTENTS]
-                  [--selection SELECTION] [-r RESTORE] [--restore-dir RESTORE_DIR] [--verbose] [--log-level LOG_LEVEL] [--do-not-compare] [-v]
+usage: dar-backup [-h] [-F] [-D] [-I] [-d BACKUP_DEFINITION]
+                  [--alternate-reference-archive ALTERNATE_REFERENCE_ARCHIVE] [-c CONFIG_FILE] [--darrc DARRC]
+                  [--examples] [-l] [--list-contents LIST_CONTENTS] [--selection SELECTION] [-r RESTORE]
+                  [--restore-dir RESTORE_DIR] [--verbose] [--log-level LOG_LEVEL] [--log-stdout]
+                  [--do-not-compare] [-v]
 
 Backup and verify using dar backup definitions.
 
@@ -206,6 +215,8 @@ options:
                         Perform incremental backup.
   -d BACKUP_DEFINITION, --backup-definition BACKUP_DEFINITION
                         Specific 'recipe' to select directories and files.
+  --alternate-reference-archive ALTERNATE_REFERENCE_ARCHIVE
+                        DIFF or INCR compared to specified archive.
   -c CONFIG_FILE, --config-file CONFIG_FILE
                         Path to 'dar-backup.conf'
   --darrc DARRC         Optional path to .darrc
@@ -222,8 +233,10 @@ options:
   --verbose             Print various status messages to screen
   --log-level LOG_LEVEL
                         `debug` or `trace`
+  --log-stdout          also print log messages to stdout
   --do-not-compare      do not compare restores to file system
-  -v, --version         Show version information.
+  -v, --version         Show version and license information.
+
 ````    
 
 ## 4
@@ -424,7 +437,7 @@ WantedBy=timers.target
 # list contents of an archive
 ```
 . <the virtual evn>/bin/activate
-dar-backup --list-contents example --selection "-X '*.xmp' -I '*2024-06-16*' -g home/pj/tmp/LUT-play"
+dar-backup --list-contents example_FULL_2024-06-23 --selection "-X '*.xmp' -I '*2024-06-16*' -g home/pj/tmp/LUT-play"
 deactivate
 ```
 gives
@@ -533,18 +546,43 @@ Nice :-)
 
 # Restoring
 
+## default location for restores
+dar-backup will use the TEST_RESTORE_DIR location as the Root for restores, if the --restore-dir option has not been supplied.
+
+See example below to see where files are restored to.
+
+## --restore-dir option
+When the --restore-dir option is used for restoring, a directory must be supplied.
+
+The directory supplied functions as the Root of the restore operation.
+
+**Example**:
+
+A backup has been taken using this backup definition:
+```
+-R /
+-g home/user/Documents
+```
+
+When restoring and using `/tmp` for --restore-dir, the restored files can be found in `/tmp/home/user/Documents`
+
 ## a single file
 ```
 . <the virtual env>/bin/activate
-# the path/to/file is relative to the Root when the backup was taken
 dar-backup --restore <archive_name> --selection "-g path/to/file"
 deactivate
 ```
+## a directory
+```
+. <the virtual env>/bin/activate
+dar-backup --restore <archive_name> --selection "-g path/to/directory"
+deactivate
+```
+
 
 ## .NEF from a specific date
 ```
 . <the virtual env>/bin/activate
-# the path/to/file is relative to the Root when the backup was taken
 dar-backup --restore <archive_name>  --selection "-X '*.xmp' -I '*2024-06-16*' -g home/pj/tmp/LUT-play"
 deactivate
 ```

dar_backup-0.6.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+dar_backup/.darrc,sha256=ggex9N6eETOS6u003_QRRJMeWbveQfkT1lDBt0XpU-I,2112
+dar_backup/__about__.py,sha256=XvHFZM0padtrqitt9-p2enlBUGqc6vGvWNLx2iJv09g,21
+dar_backup/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dar_backup/cleanup.py,sha256=DgmxSUwKrLLIQuYSIY_yTRhIuOMgI6ivjlQuH4u3wX4,9057
+dar_backup/config_settings.py,sha256=CBMUhLOOZ-x7CRdS3vBDk4TYaGqC4N1Ot8IMH-qPaI0,3617
+dar_backup/dar_backup.py,sha256=xnDuqkpo8q_X1FLKID9I_s__FQozl5EIrwNHdIJAd_0,37525
+dar_backup/manager.py,sha256=lkw1ZAIdxY7WedLPKZMnHpuq_QbjkUdcG61ooiwUYpo,10197
+dar_backup/util.py,sha256=6lPCFHr3MDdaLWAW9EDMZ4jdL7pt8rki-5dOXcesmP8,8955
+dar_backup-0.6.1.dist-info/METADATA,sha256=m3P_iVauaMno0fAhc4iJgO_DS9FobsqV5StQzUdU6wY,22496
+dar_backup-0.6.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dar_backup-0.6.1.dist-info/entry_points.txt,sha256=x9vnW-JEl8mpDJC69f_XBcn0mBSkV1U0cyvFV-NAP1g,126
+dar_backup-0.6.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+dar_backup-0.6.1.dist-info/RECORD,,

dar_backup-0.5.17.dist-info/RECORD

@@ -1,13 +0,0 @@
-dar_backup/.darrc,sha256=ggex9N6eETOS6u003_QRRJMeWbveQfkT1lDBt0XpU-I,2112
-dar_backup/__about__.py,sha256=JiHkNWaQtd0jZh8vy9fMhajaON_1Y2QqWuee4eqXxd4,22
-dar_backup/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dar_backup/cleanup.py,sha256=DgmxSUwKrLLIQuYSIY_yTRhIuOMgI6ivjlQuH4u3wX4,9057
-dar_backup/config_settings.py,sha256=-PhSj0Y9lVF6YaVkkG17XT-qmnFFt-XQXBdzxhIFNkc,3455
-dar_backup/dar_backup.py,sha256=NKLBLA7Ma6sU72zqsRvFa0ckrrJ-iJJ_2muxtxSjTNs,36903
-dar_backup/manager.py,sha256=0SZbk9rekPRWwJgQwTO2Xj57v3G11kQ4i4hCSb0OZEQ,10168
-dar_backup/util.py,sha256=a460ISsVwc93cSuUlInCMjNNhK5D48zlopzpysver9I,7416
-dar_backup-0.5.17.dist-info/METADATA,sha256=JZxdM7vyX6Zn_H85hasxHaEvdZxRIE8LpLSvKHTYWPs,21132
-dar_backup-0.5.17.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dar_backup-0.5.17.dist-info/entry_points.txt,sha256=x9vnW-JEl8mpDJC69f_XBcn0mBSkV1U0cyvFV-NAP1g,126
-dar_backup-0.5.17.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-dar_backup-0.5.17.dist-info/RECORD,,