Merge branch 'errors' into dev

Raise Exceptions instead of using return codes

src/unisync/errors.py

@@ -1,8 +1,14 @@
 # Copyright (C) 2025-2026 Paul Retourné
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-class RemoteMountedError(BaseException):
+class RemoteMountedError(Exception):
     pass
 
-class InvalidMountError(BaseException):
+class InvalidMountError(Exception):
+    pass
+
+class UnknownSSHError(Exception):
+    pass
+
+class FatalSyncError(Exception):
     pass

src/unisync/paths.py

@@ -73,9 +73,9 @@ class PathsManager:
             try:
                 paths = self.user_select_files()
                 break
-            except subprocess.TimeoutExpired:
+            except subprocess.TimeoutExpired as e:
                 if input("Timeout expired do you want to retry (y/n): ") != "y":
-                    raise
+                    raise e
         self.write_new_paths(paths)
 
     def get_paths_to_sync(self) -> list[str]:

src/unisync/synchroniser.py

@@ -16,7 +16,7 @@ import logging
 from pathlib import Path
 from typing import cast
 
-from unisync.errors import RemoteMountedError, InvalidMountError
+from unisync.errors import RemoteMountedError, InvalidMountError, UnknownSSHError, FatalSyncError
 from unisync.config import BackupConfig
 
 logger = logging.getLogger(__name__)
@@ -92,7 +92,7 @@ class Synchroniser:
                 f"Name {backup.backupprefix[:-1]}"
                 ])
     
-    def create_ssh_master_connection(self, control_path:str="~/.ssh/control_%C", connection_timeout:int=60) -> int:
+    def create_ssh_master_connection(self, control_path:str="~/.ssh/control_%C", connection_timeout:int=60) -> None:
         """Creates an ssh master connection.
 
         It is used so the user only has to authenticate once to the remote server.
@@ -105,8 +105,14 @@ class Synchroniser:
             connection_timeout:
                 Time given to the user to authenticate to the remote server.
                 On slow connections one might want to increase this.
-        Returns:
+
-            An error code (0 success, 1 TimeoutExpired, 2 KeyboardInterrupt).
+        Raises:
+            subprocess.TimeoutExpired:
+                The user didn't finish loging in in time.
+            KeyboardInterrupt:
+                The user interrupted the process.
+            UnknownSSHError:
+                An error occured during the connection.
         """
         self.control_path = os.path.expanduser(control_path)
         command = [
@@ -121,16 +127,15 @@ class Synchroniser:
         # TODO: Raise an exception instead of changing the return value
         try:
             ret_code = master_ssh.wait(timeout=connection_timeout)
-        except subprocess.TimeoutExpired:
+        except subprocess.TimeoutExpired as e:
             print("Time to login expired", file=sys.stderr)
-            return 1
+            raise e
-        except KeyboardInterrupt:
+        except KeyboardInterrupt as e:
-            return 2
+            raise e
 
         if ret_code != 0:
             print("Login to remote failed", file=sys.stderr)
-            return ret_code
+            raise UnknownSSHError
-        return 0
 
 
     def close_ssh_master_connection(self) -> int:
@@ -149,18 +154,18 @@ class Synchroniser:
         close = subprocess.Popen(command)
         return close.wait()
 
-    def sync_files(self, paths:list, force:bool=False) -> int:
+    def sync_files(self, paths:list, force:bool=False) -> None:
         """Synchronises the files.
 
         Args:
             paths: List of paths to synchronise.
             force: Force the changes from remote to local.
 
-        Returns:
+        Raises:
-            The return code of sync.
+            FatalSyncError: A fatal error occured during the synchronisation.
         """
 
-        return self.sync(
+        self.sync(
                 f"ssh://{self.remote_user}@{self.remote_ip}/{self.remote_dir}/.data",
                 self.local,
                 paths=paths,
@@ -168,16 +173,16 @@ class Synchroniser:
                 other=self.files_extra
                 )
 
-    def sync_links(self, ignore:list) -> int:
+    def sync_links(self, ignore:list) -> None:
         """Synchronises the links, they must exist already.
 
         Args:
             ignore: List of paths to ignore.
 
-        Returns:
+        Raises:
-            The return code of sync.
+            FatalSyncError: A fatal error occured during the synchronisation.
         """
-        return self.sync(
+        self.sync(
                 f"ssh://{self.remote_user}@{self.remote_ip}/{self.remote_dir}/links",
                 self.local,
                 ignore=ignore,
@@ -187,7 +192,7 @@ class Synchroniser:
     def sync(self, remote_root:str, local_root:str,
              paths:list=[], ignore:list=[], force:bool=False,
              other:list=[]
-             ) -> int:
+             ) -> None:
         """Performs the synchronisation by calling unison.
 
         Args:
@@ -206,8 +211,11 @@ class Synchroniser:
                 They will be added to the command as is no - in front.
                 For exemple backups are implemented using this argument.
 
-        Returns:
+        Raises:
-            the unison return code see section 6.11 of the documentation
+            FatalSyncError:
+                If unison returns 3 it means either a fatal error occured or the synchronisation
+                was interrupted.
+                If this happens propagate the error to unisync.
         """
         command = [ "/usr/bin/unison", "-root", remote_root, "-root", local_root ]
         for arg in self.args_bool:
@@ -241,7 +249,8 @@ class Synchroniser:
 
         proc = subprocess.Popen(command)
         ret_code = proc.wait()
-        return ret_code
+        if ret_code == 3:
+            raise FatalSyncError("Synchronisation could not be completed")
 
     def update_links(self, background:bool=True):
         """Updates the links on the remote.