Coverage for seedboxsync/core/sync/abstract_sync_client.py: 100%

1# 

2# Copyright (C) 2015-2026 Guillaume Kulakowski <guillaume@kulakowski.fr> 

3# 

4# For the full copyright and license information, please view the LICENSE 

5# file that was distributed with this source code. 

6# 

7""" 

8Abstract transport client using paramiko-like interface. 

9 

10This class defines the interface that all transport clients must implement, 

11providing methods for file operations and session management on a remote server. 

12""" 

13 

14from abc import ABCMeta, abstractmethod 

15from collections.abc import Callable 

16from os import PathLike 

17from typing import Any 

18 

19ProgressCallback = Callable[[int, int], object] 

20 

21PathType = str | PathLike[str] 

22 

23 

24class AbstractSyncClient: # pragma: no cover 

25 """ 

26 Abstract base class for transport clients. 

27 

28 All concrete clients must implement methods to manage file transfers 

29 and remote file operations. 

30 """ 

31 

32 __metaclass__ = ABCMeta 

33 

34 @abstractmethod 

35 def __init__(self) -> None: 

36 """Initialize the transport client.""" 

37 

38 @abstractmethod 

39 def put(self, local_path: PathType, remote_path: PathType) -> Any: 

40 """ 

41 Upload a local file to the remote server. 

42 

43 Args: 

44 local_path (PathType): Path to the local file to copy. 

45 remote_path (PathType): Destination path on the server including filename. 

46 Specifying only a directory must raise an error. 

47 """ 

48 

49 @abstractmethod 

50 def get( 

51 self, 

52 remote_path: PathType, 

53 local_path: PathType, 

54 progress_callback: ProgressCallback | None = None, 

55 ) -> None: 

56 """ 

57 Download a file from the remote server to the local host. 

58 

59 Args: 

60 remote_path (PathType): Path to the remote file to copy. 

61 local_path (PathType): Destination path on the local host. 

62 progress_callback (ProgressCallback | None): Optional callback receiving bytes_transferred. 

63 """ 

64 

65 @abstractmethod 

66 def stat(self, filepath: PathType) -> Any: 

67 """ 

68 Retrieve metadata about a file on the remote system. 

69 

70 Returns an object similar to Python's os.stat, with fewer fields. 

71 Supported fields: st_mode, st_size, st_uid, st_gid, st_atime, st_mtime. 

72 

73 Args: 

74 filepath (PathType): Path to the remote file. 

75 """ 

76 

77 @abstractmethod 

78 def chdir(self, path: PathType) -> None: 

79 """ 

80 Change the current working directory on the remote session. 

81 

82 Args: 

83 path (PathType, optional): New working directory path. Defaults to None. 

84 """ 

85 

86 @abstractmethod 

87 def chmod(self, path: PathType, mode: int) -> None: 

88 """ 

89 Change permissions of a remote file. 

90 

91 Permissions are unix-style, same as Python's os.chmod. 

92 

93 Args: 

94 path (PathType): Path to the file on the remote server. 

95 mode (int): New permissions to set. 

96 """ 

97 

98 @abstractmethod 

99 def rename(self, old_path: PathType, new_path: PathType) -> None: 

100 """ 

101 Rename a file or directory on the remote server. 

102 

103 Args: 

104 old_path (stPathTyper): Existing path of the file or folder. 

105 new_path (PathType): New path or name for the file or folder. 

106 """ 

107 

108 @abstractmethod 

109 def close(self) -> None: 

110 """Close the transport session and release resources."""