Connection remote classes¶
This file describes the main package classes API for interacting with remote hosts.
ssh_utilities.remote¶
Remote working substitutions for some python modules.
Includes: os, pathlib, shutil, subprocess and open from python builtins. Only a subset of API from each module is supported.
-
class
ssh_utilities.remote.
SSHConnection
(address: str, username: str, password: Optional[str] = None, rsa_key_file: Union[pathlib.Path, str, None] = None, line_rewrite: bool = True, server_name: Optional[str] = None, quiet: bool = False, thread_safe: bool = False)¶ Bases:
ssh_utilities.abc._connection.ConnectionABC
Self keeping ssh connection, to execute commands and file operations.
Parameters: - address (str) – server IP address
- username (str) – server login
- password (Optional[str]) – server password for login, by default RSA keys is used
- rsa_key_file (Optional[Union[str, Path]]) – path to rsa key file
- line_rewrite (bool) – rewrite lines in output when copying instead of normal mode when lines are outputed one after the other. Default is True
- warn_on_login (bool) – Display on warnings of firs login
- server_name (Optional[str]) – input server name that will be later displayed on file operations, if None then IP address will be used
- thread_safe (bool) – make connection object thread safe so it can be safely accessed from any number of threads, it is disabled by default to avoid performance penalty of threading locks
Warning
At least one of (password, rsa_key_file) must be specified, if both are, RSA key will be used
thread_safe parameter is not implemented yet!!!
Raises: ConnectionError
– connection to remote could not be established-
builtins
¶ Inner class providing access to substitutions for python builtins.
Type: remote.Builtins
-
close
(*, quiet: bool = True)¶ Close SSH connection.
Parameters: quiet (bool) – whether to print other function messages
-
pathlib
¶ Inner class providing access to substitutions for pathlib module.
Type: remote.Pathlib
-
sftp
¶ Opens and return sftp channel.
If SFTP coud be open then return SFTPClient instance else return None.
Type: Optional[paramiko.SFTPClient]
Raises: SFTPOpenError
– when remote home could not be found
-
shutil
¶ Inner class providing access to substitutions for shutil module.
Type: remote.Shutil
-
static
ssh_log
(log_file: Union[pathlib.Path, str] = PosixPath('paramiko.log'), level: str = 'WARN')¶ Initialize paramiko logging functionality.
Parameters: - log_file (str) – location of the log file (default: paramiko.log)
- level (str) – logging level represented by string
-
subprocess
¶ Inner class providing access to substitutions for subprocess module.
Type: remote.Subprocess
-
class
ssh_utilities.remote.
Builtins
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._builtins.BuiltinsABC
Remote replacement for python builtins, mainly the open function.
See also
ssh_utilities.local.Builtins
- local version of class with same API
-
open
(filename: _SPATH, mode: str = 'r', encoding: Optional[str] = None, bufsize: int = -1, errors: Optional[str] = None) → SFTPFile¶ Opens remote file, works as python open function.
Can be used both as a function or a decorator.
Parameters: - filename (
ssh_utilities.typeshed._SPATH
) – path to file to be opened - mode (str) – select mode to open file. Same as python open modes
- encoding (Optional[str]) – encoding type to decode file bytes stream
- bufsize (int) – buffer size, 0 turns off buffering, 1 uses line buffering, and any number greater than 1 (>1) uses that specific buffer size
- errors (Optional[str]) – string that specifies how encoding and decoding errors are to be handled, see builtin function open documentation for more details
Raises: FileNotFoundError
– when mode is ‘r’ and file does not exist- filename (
-
class
ssh_utilities.remote.
Os
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._os.OsABC
Class gathering all remote methods similar to python os module.
See also
ssh_utilities.local.Os
- local version of class with same API
-
isdir
(path: _SPATH) → bool¶ Check if path points to directory.
Parameters: path ( ssh_utilities.typeshed._SPATH
) – path to checkRaises: IOError
– if dir could not be accessed
-
isfile
(path: _SPATH) → bool¶ Check if path points to a file.
Parameters: path ( ssh_utilities.typeshed._SPATH
) – path to checkRaises: IOError
– if file could not be accessed
-
listdir
(path: _SPATH) → List[str]¶ Lists contents of specified directory.
Parameters: path ( ssh_utilities.typeshed._SPATH
) – directory pathReturns: list of files, dirs, symlinks … Return type: List[str] Raises: FileNotFoundError
– if directory does not exist
-
lstat
(path: _SPATH, *, dir_fd=None) → SFTPAttributes¶ Similar to stat only this does not resolve symlinks.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – path to file whose stats are desired - dir_fd (Any) – not implemented in remote version
Returns: stat object similar to one returned by os.lstat
Return type: SFTPAttributes
Warning
dir_fd parameter has no effect, it is present only so the signature is compatible with os.lstat
- path (
-
makedirs
(path: _SPATH, mode: int = 511, exist_ok: bool = True, parents: bool = True, quiet: bool = True)¶ Recursively create directory.
If it already exists, show warning and return.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – path to directory which should be created - mode (int) – create directory with mode, default is 511
- exist_ok (bool) – if true and directory exists, exception is silently passed when dir already exists
- parents (bool) – if true any missing parent dirs are automatically created, else exception is raised on missing parent
- quiet (bool) – if True informative messages are suppresssed
Raises: OSError
– if directory could not be createdFileNotFoundError
– when parent directory is missing and parents=FalseFileExistsError
– when directory already exists and exist_ok=False
- path (
-
mkdir
(path: _SPATH, mode: int = 511, quiet: bool = True)¶ Create single directory.
If it already exists, show warning and return.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – path to directory which should be created - mode (int) – create directory with mode, default is 511
- quiet (bool) – if True informative messages are suppresssed
Raises: OSError
– if directory could not be createdFileNotFoundError
– when parent directory is missing and parents=FalseFileExistsError
– when directory already exists and exist_ok=False
- path (
-
name
¶ Try to get remote os name same as os.name function.
Warning
Due to the complexity of the check, this method only checks is remote server is windows by trying to run ver command. If that fails the remote is automatically assumed to be POSIX which should hold true in most cases. If absolute certianty is required you should do your own checks.
Note
This methods main purpose is to help choose the right flavour when instantiating ssh_utilities.path.SSHPath. For its use the provided accuracy should be sufficient.
Returns: remote server os name Return type: Literal[“nt”, “posix”] Raises: UnknownOsError
– if remote server os name could not be determined
-
osname
¶ Try to get remote os name same as os.name function.
Warning
Due to the complexity of the check, this method only checks is remote server is windows by trying to run ver command. If that fails the remote is automatically assumed to be POSIX which should hold true in most cases. If absolute certianty is required you should do your own checks.
Note
This methods main purpose is to help choose the right flavour when instantiating ssh_utilities.path.SSHPath. For its use the provided accuracy should be sufficient.
Returns: remote server os name Return type: Literal[“nt”, “posix”] Raises: UnknownOsError
– if remote server os name could not be determined
-
stat
(path: _SPATH, *, dir_fd=None, follow_symlinks: bool = True) → SFTPAttributes¶ Replacement for os.stat function.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – path to file whose stats are desired - dir_fd (Any) – not implemented
- follow_symlinks (bool) – whether to resolve symbolic links along the way
Returns: stat object similar to one returned by os.stat
Return type: SFTPAttributes
Warning
dir_fd parameter has no effect, it is present only so the signature is compatible with os.stat
- path (
-
walk
(top: _SPATH, topdown: bool = True, onerror=None, followlinks: bool = False) → _WALK¶ Recursive directory listing.
Parameters: - top (
ssh_utilities.typeshed._SPATH
) – directory to start from - topdown (bool, optional) – if true or not specified, the triple for a directory is generated before the triples for any of its subdirectories (directories are generated top-down). This enables you to modify the subdirectories list in place befor iteration continues. If topdown is False, the triple for a directory is generated after the triples for all of its subdirectories, by default True
- onerror (
ssh_utilities.typeshed._ONERROR
, optional) – Callable acception one argument of type exception which decides how to handle that exception, by default None - followlinks (bool, optional) – follow symbolic links if true, by default False
Returns: iterator of 3 tuples containing current dir, subdirs and files
Return type: - top (
-
class
ssh_utilities.remote.
Pathlib
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._pathlib.PathlibABC
Expose pathlib like API for remote hosts.
See also
ssh_utilities.local.Pathlib
- local version of class with same API
-
Path
(path: _SPATH) → ssh_utilities.remote.path.SSHPath¶ Provides API similar to pathlib.Path only for remote host.
Only for Unix to Unix connections
Parameters: path ( ssh_utilities.typeshed._SPATH
) – provide initial pathReturns: object representing remote path Return type: SSHPath
-
class
ssh_utilities.remote.
Shutil
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._shutil.ShutilABC
Class with remote versions of shutil methods.
See also
ssh_utilities.local.Shutil
- local version of class with same API
-
copy
(src: _SPATH, dst: _SPATH, *, direction: _DIRECTION, follow_symlinks: bool = True, callback: _CALLBACK = None, quiet: bool = True)¶ Send files in the chosen direction local <-> remote.
Parameters: - src (
ssh_utilities.typeshed._SPATH
) – path to the file - dst (
ssh_utilities.typeshed._SPATH
) – path to copy into - direction (
ssh_utilities.typeshed._DIRECTION
) – ‘get’ for download and ‘put’ for upload - follow_symlinks (bool) – resolve symlinks when looking for file, by default True
- callback (
ssh_utilities.typeshed._CALLBACK
) – callback function that recives two arguments: amount done and total amount to be copied - quiet (bool) – if True informative messages are suppresssed
Warning
Unlike shutil this function cannot preserve file permissions (copy) or file metadata (copy2)
Raises: FileNotFoundError
– if src is not fileValueError
– if direction is not put or get
- src (
-
copy2
(src: _SPATH, dst: _SPATH, *, direction: _DIRECTION, follow_symlinks: bool = True, callback: _CALLBACK = None, quiet: bool = True)¶ Send files in the chosen direction local <-> remote.
Parameters: - src (
ssh_utilities.typeshed._SPATH
) – path to the file - dst (
ssh_utilities.typeshed._SPATH
) – path to copy into - direction (
ssh_utilities.typeshed._DIRECTION
) – ‘get’ for download and ‘put’ for upload - follow_symlinks (bool) – resolve symlinks when looking for file, by default True
- callback (
ssh_utilities.typeshed._CALLBACK
) – callback function that recives two arguments: amount done and total amount to be copied - quiet (bool) – if True informative messages are suppresssed
Warning
Unlike shutil this function cannot preserve file permissions (copy) or file metadata (copy2)
Raises: FileNotFoundError
– if src is not fileValueError
– if direction is not put or get
- src (
-
copy_files
(files: List[str], remote_path: _SPATH, local_path: _SPATH, *, direction: _DIRECTION, follow_symlinks: bool = True, quiet: bool = False)¶ Send files in the chosen direction local <-> remote.
Parameters: - files (List[str]) – list of files to upload/download
- remote_path (
ssh_utilities.typeshed._SPATH
) – path to remote directory with files - local_path (
ssh_utilities.typeshed._SPATH
) – path to local directory with files - direction (str) – get for download and put for upload
- follow_symlinks (bool) – resolve symlinks when looking for file, by default True
- quiet (bool) – if True informative messages are suppresssed
-
copyfile
(src: _SPATH, dst: _SPATH, *, direction: _DIRECTION, follow_symlinks: bool = True, callback: _CALLBACK = None, quiet: bool = True)¶ Send files in the chosen direction local <-> remote.
Parameters: - src (
ssh_utilities.typeshed._SPATH
) – path to the file - dst (
ssh_utilities.typeshed._SPATH
) – path to copy into - direction (
ssh_utilities.typeshed._DIRECTION
) – ‘get’ for download and ‘put’ for upload - follow_symlinks (bool) – resolve symlinks when looking for file, by default True
- callback (
ssh_utilities.typeshed._CALLBACK
) – callback function that recives two arguments: amount done and total amount to be copied - quiet (bool) – if True informative messages are suppresssed
Raises: FileNotFoundError
– if src is not fileIsADirectoryError
– if dst is a targer directory not full pathValueError
– if direction is not put or get
- src (
-
download_tree
(remote_path: _SPATH, local_path: _SPATH, include: _GLOBPAT = None, exclude: _GLOBPAT = None, remove_after: bool = False, quiet: typing_extensions.Literal[True, False, 'stats', 'progress'][True, False, stats, progress] = False)¶ Download directory tree from remote.
Remote directory must exist otherwise exception is raised.
Parameters: - remote_path (
ssh_utilities.typeshed._SPATH
) – path to directory which should be downloaded - local_path (
ssh_utilities.typeshed._SPATH
) – directory to copy to, must be full path! - remove_after (bool) – remove remote copy after directory is uploaded
- include (
ssh_utilities.typeshed._GLOBPAT
) – glob pattern of files to include in copy, can be used simultaneously with exclude, default is None = no filtering - exclude (
ssh_utilities.typeshed._GLOBPAT
) – glob pattern of files to exclude in copy, can be used simultaneously with include, default is None = no filtering - quiet (Literal[True, False, "stats", "progress"]) – if True informative messages are suppresssed if False all is printed, if stats all statistics except progressbar are suppressed if progress only progressbar is suppressed
Warning
both paths must be full: <some_remote_path>/my_directory -> <some_local_path>/my_directory
Raises: FileNotFoundError
– when remote directory does not exist- remote_path (
-
rmtree
(path: _SPATH, ignore_errors: bool = False, quiet: bool = True)¶ Recursively remove directory tree.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – directory to be recursively removed - ignore_errors (bool) – if True only log warnings do not raise exception
- quiet (bool) – if True informative messages are suppresssed
Raises: FileNotFoundError
– if some part of deleting filed- path (
-
upload_tree
(local_path: _SPATH, remote_path: _SPATH, include: _GLOBPAT = None, exclude: _GLOBPAT = None, remove_after: bool = False, quiet: typing_extensions.Literal[True, False, 'stats', 'progress'][True, False, stats, progress] = False)¶ Upload directory tree to remote.
Local path must exist otherwise, exception is raised.
Parameters: - local_path (
ssh_utilities.typeshed._SPATH
) – path to directory which should be uploaded - remote_path (
ssh_utilities.typeshed._SPATH
) – directory to copy to, must be full path! - remove_after (bool) – remove local copy after directory is uploaded
- include (
ssh_utilities.typeshed._GLOBPAT
) – glob pattern of files to include in copy, can be used simultaneously with exclude, default is None = no filtering - exclude (
ssh_utilities.typeshed._GLOBPAT
) – glob pattern of files to exclude in copy, can be used simultaneously with include, default is None = no filtering - quiet (Literal[True, False, "stats", "progress"]) – if True informative messages are suppresssed if False all is printed, if stats all statistics except progressbar are suppressed if progress only progressbar is suppressed
Warning
both paths must be full: <some_local_path>/my_directory -> <some_remote_path>/my_directory
Raises: FileNotFoundError
– when local directory does not exist- local_path (
-
class
ssh_utilities.remote.
Subprocess
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._subprocess.SubprocessABC
Class with similar API to subprocess module.
See also
ssh_utilities.local.Subprocess
- local version of class with same API
-
run
(args: _CMD, *, suppress_out: bool, quiet: bool = True, bufsize: int = -1, executable: _SPATH = None, input: Optional[str] = None, stdin: _FILE = None, stdout: _FILE = None, stderr: _FILE = None, capture_output: bool = False, shell: bool = False, cwd: _SPATH = None, timeout: Optional[float] = None, check: bool = False, encoding: Optional[str] = None, errors: Optional[str] = None, text: Optional[bool] = None, env: _ENV = None, universal_newlines: bool = False) → ssh_utilities.utils.CompletedProcess¶ Excecute command on remote, has simillar API to subprocess run.
Parameters: - args (
ssh_utilities.typeshed._CMD
) – string, Path-like object or a list of strings. If it is a list it will be joined to string with whitespace delimiter. - suppress_out (bool) – whether to print command output to console, this is required keyword argument
- quiet (bool, optional) – whether to print other function messages, by default True
- bufsize (int, optional) – buffer size, 0 turns off buffering, 1 uses line buffering, and any number greater than 1 (>1) uses that specific buffer size. This applies ti underlying paramiko client as well as stdin, stdout and stderr PIPES, by default -1
- executable (
ssh_utilities.typeshed._SPATH
, optional) – [description], by default None - input (Optional[str], optional) – [description], by default None
- stdin (_FILE, optional) – [description], by default None
- stdout (_FILE, optional) – [description], by default None
- stderr (_FILE, optional) – [description], by default None
- capture_output (bool, optional) – if true then lightweight result object with same API as subprocess.CompletedProcess is returned. Same as passing PIPE to stdout and stderr. Both options cannot be used at the same time, by default False
- shell (bool, optional) – requests a pseudo terminal from server, by default False
- cwd (_SPATH, optional) – execute command in this directory, by default None
- timeout (Optional[float], optional) – set, by default None
- check (bool, optional) – checks for command return code if other than 0 raises CalledProcessError, by default False
- encoding (Optional[str], optional) – encoding to use when decoding remote output, default is utf-8, by default None
- errors (Optional[str], optional) –
string that specifies how encoding and decoding errors are to be handled, see builtin function open documentation for more details, by default None
- text (Optional[bool], optional) – will select default encoding and open stdin, stdout and stderr streams in text mode. The default encoding, contrary to behaviour of subprocess module is not selected by locale.getpreferredencoding(False) but is always set to utf-8. By default None
- env (
ssh_utilities.typeshed._ENV
, optional) – optinal environment variables that will be merged into the existing environment. This is different to subprocess behaviour which creates new environment with only specified variables, by default None - universal_newlines (bool, optional) – an alias for text keyword argument, by default None
Warning
New environment variables defined by env might get silently rejected by the server.
Currentlly it is only possible to use input agrgument, not stdin and send data to process only once at the begining. It is still under developement
Returns: if capture_output is true, returns lightweight result object with same API as subprocess.CompletedProcess
Return type: Raises: ValueError
– if stdin and input are specified at the same timeValueError
– if capture_output and stdout and/or stderr are specified at the same timeValueError
– if text or universal_newlines is used simultaneously with” encoding and/or errors argumentsNotImplementedError
– if stdin or executable is used - work in progressTypeError
– if stdin, stdout or stderr arguments are of wrong typeTypeError
– if args argument is of wrong typeCalledProcessError
– if check is true and command exited with non-zero statusTimeoutExpired
– if the command exceeded allowed run time
- args (
ssh_utilities.remote._builtins¶
Python builtins remote version.
-
class
ssh_utilities.remote._builtins.
Builtins
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._builtins.BuiltinsABC
Remote replacement for python builtins, mainly the open function.
See also
ssh_utilities.local.Builtins
- local version of class with same API
-
open
(filename: _SPATH, mode: str = 'r', encoding: Optional[str] = None, bufsize: int = -1, errors: Optional[str] = None) → SFTPFile¶ Opens remote file, works as python open function.
Can be used both as a function or a decorator.
Parameters: - filename (
ssh_utilities.typeshed._SPATH
) – path to file to be opened - mode (str) – select mode to open file. Same as python open modes
- encoding (Optional[str]) – encoding type to decode file bytes stream
- bufsize (int) – buffer size, 0 turns off buffering, 1 uses line buffering, and any number greater than 1 (>1) uses that specific buffer size
- errors (Optional[str]) –
string that specifies how encoding and decoding errors are to be handled, see builtin function open documentation for more details
Raises: FileNotFoundError
– when mode is ‘r’ and file does not exist- filename (
ssh_utilities.remote._os¶
Remote connection os methods.
-
class
ssh_utilities.remote._os.
Os
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._os.OsABC
Class gathering all remote methods similar to python os module.
See also
ssh_utilities.local.Os
- local version of class with same API
-
isdir
(path: _SPATH) → bool¶ Check if path points to directory.
Parameters: path ( ssh_utilities.typeshed._SPATH
) – path to checkRaises: IOError
– if dir could not be accessed
-
isfile
(path: _SPATH) → bool¶ Check if path points to a file.
Parameters: path ( ssh_utilities.typeshed._SPATH
) – path to checkRaises: IOError
– if file could not be accessed
-
listdir
(path: _SPATH) → List[str]¶ Lists contents of specified directory.
Parameters: path ( ssh_utilities.typeshed._SPATH
) – directory pathReturns: list of files, dirs, symlinks … Return type: List[str] Raises: FileNotFoundError
– if directory does not exist
-
lstat
(path: _SPATH, *, dir_fd=None) → SFTPAttributes¶ Similar to stat only this does not resolve symlinks.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – path to file whose stats are desired - dir_fd (Any) – not implemented in remote version
Returns: stat object similar to one returned by os.lstat
Return type: SFTPAttributes
Warning
dir_fd parameter has no effect, it is present only so the signature is compatible with os.lstat
- path (
-
makedirs
(path: _SPATH, mode: int = 511, exist_ok: bool = True, parents: bool = True, quiet: bool = True)¶ Recursively create directory.
If it already exists, show warning and return.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – path to directory which should be created - mode (int) – create directory with mode, default is 511
- exist_ok (bool) – if true and directory exists, exception is silently passed when dir already exists
- parents (bool) – if true any missing parent dirs are automatically created, else exception is raised on missing parent
- quiet (bool) – if True informative messages are suppresssed
Raises: OSError
– if directory could not be createdFileNotFoundError
– when parent directory is missing and parents=FalseFileExistsError
– when directory already exists and exist_ok=False
- path (
-
mkdir
(path: _SPATH, mode: int = 511, quiet: bool = True)¶ Create single directory.
If it already exists, show warning and return.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – path to directory which should be created - mode (int) – create directory with mode, default is 511
- quiet (bool) – if True informative messages are suppresssed
Raises: OSError
– if directory could not be createdFileNotFoundError
– when parent directory is missing and parents=FalseFileExistsError
– when directory already exists and exist_ok=False
- path (
-
name
¶ Try to get remote os name same as os.name function.
Warning
Due to the complexity of the check, this method only checks is remote server is windows by trying to run ver command. If that fails the remote is automatically assumed to be POSIX which should hold true in most cases. If absolute certianty is required you should do your own checks.
Note
This methods main purpose is to help choose the right flavour when instantiating ssh_utilities.path.SSHPath. For its use the provided accuracy should be sufficient.
Returns: remote server os name Return type: Literal[“nt”, “posix”] Raises: UnknownOsError
– if remote server os name could not be determined
-
osname
¶ Try to get remote os name same as os.name function.
Warning
Due to the complexity of the check, this method only checks is remote server is windows by trying to run ver command. If that fails the remote is automatically assumed to be POSIX which should hold true in most cases. If absolute certianty is required you should do your own checks.
Note
This methods main purpose is to help choose the right flavour when instantiating ssh_utilities.path.SSHPath. For its use the provided accuracy should be sufficient.
Returns: remote server os name Return type: Literal[“nt”, “posix”] Raises: UnknownOsError
– if remote server os name could not be determined
-
stat
(path: _SPATH, *, dir_fd=None, follow_symlinks: bool = True) → SFTPAttributes¶ Replacement for os.stat function.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – path to file whose stats are desired - dir_fd (Any) – not implemented
- follow_symlinks (bool) – whether to resolve symbolic links along the way
Returns: stat object similar to one returned by os.stat
Return type: SFTPAttributes
Warning
dir_fd parameter has no effect, it is present only so the signature is compatible with os.stat
- path (
-
walk
(top: _SPATH, topdown: bool = True, onerror=None, followlinks: bool = False) → _WALK¶ Recursive directory listing.
Parameters: - top (
ssh_utilities.typeshed._SPATH
) – directory to start from - topdown (bool, optional) – if true or not specified, the triple for a directory is generated before the triples for any of its subdirectories (directories are generated top-down). This enables you to modify the subdirectories list in place befor iteration continues. If topdown is False, the triple for a directory is generated after the triples for all of its subdirectories, by default True
- onerror (
ssh_utilities.typeshed._ONERROR
, optional) – Callable acception one argument of type exception which decides how to handle that exception, by default None - followlinks (bool, optional) – follow symbolic links if true, by default False
Returns: iterator of 3 tuples containing current dir, subdirs and files
Return type: - top (
ssh_utilities.remote._pathlib¶
Module with pathlib functionality for SSHConnection.
-
class
ssh_utilities.remote._pathlib.
Pathlib
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._pathlib.PathlibABC
Expose pathlib like API for remote hosts.
See also
ssh_utilities.local.Pathlib
- local version of class with same API
-
Path
(path: _SPATH) → ssh_utilities.remote.path.SSHPath¶ Provides API similar to pathlib.Path only for remote host.
Only for Unix to Unix connections
Parameters: path ( ssh_utilities.typeshed._SPATH
) – provide initial pathReturns: object representing remote path Return type: SSHPath
ssh_utilities.remote._shutil¶
Module collecting shutil-like remote methods.
-
class
ssh_utilities.remote._shutil.
Shutil
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._shutil.ShutilABC
Class with remote versions of shutil methods.
See also
ssh_utilities.local.Shutil
- local version of class with same API
-
copy
(src: _SPATH, dst: _SPATH, *, direction: _DIRECTION, follow_symlinks: bool = True, callback: _CALLBACK = None, quiet: bool = True)¶ Send files in the chosen direction local <-> remote.
Parameters: - src (
ssh_utilities.typeshed._SPATH
) – path to the file - dst (
ssh_utilities.typeshed._SPATH
) – path to copy into - direction (
ssh_utilities.typeshed._DIRECTION
) – ‘get’ for download and ‘put’ for upload - follow_symlinks (bool) – resolve symlinks when looking for file, by default True
- callback (
ssh_utilities.typeshed._CALLBACK
) – callback function that recives two arguments: amount done and total amount to be copied - quiet (bool) – if True informative messages are suppresssed
Warning
Unlike shutil this function cannot preserve file permissions (copy) or file metadata (copy2)
Raises: FileNotFoundError
– if src is not fileValueError
– if direction is not put or get
- src (
-
copy2
(src: _SPATH, dst: _SPATH, *, direction: _DIRECTION, follow_symlinks: bool = True, callback: _CALLBACK = None, quiet: bool = True)¶ Send files in the chosen direction local <-> remote.
Parameters: - src (
ssh_utilities.typeshed._SPATH
) – path to the file - dst (
ssh_utilities.typeshed._SPATH
) – path to copy into - direction (
ssh_utilities.typeshed._DIRECTION
) – ‘get’ for download and ‘put’ for upload - follow_symlinks (bool) – resolve symlinks when looking for file, by default True
- callback (
ssh_utilities.typeshed._CALLBACK
) – callback function that recives two arguments: amount done and total amount to be copied - quiet (bool) – if True informative messages are suppresssed
Warning
Unlike shutil this function cannot preserve file permissions (copy) or file metadata (copy2)
Raises: FileNotFoundError
– if src is not fileValueError
– if direction is not put or get
- src (
-
copy_files
(files: List[str], remote_path: _SPATH, local_path: _SPATH, *, direction: _DIRECTION, follow_symlinks: bool = True, quiet: bool = False)¶ Send files in the chosen direction local <-> remote.
Parameters: - files (List[str]) – list of files to upload/download
- remote_path (
ssh_utilities.typeshed._SPATH
) – path to remote directory with files - local_path (
ssh_utilities.typeshed._SPATH
) – path to local directory with files - direction (str) – get for download and put for upload
- follow_symlinks (bool) – resolve symlinks when looking for file, by default True
- quiet (bool) – if True informative messages are suppresssed
-
copyfile
(src: _SPATH, dst: _SPATH, *, direction: _DIRECTION, follow_symlinks: bool = True, callback: _CALLBACK = None, quiet: bool = True)¶ Send files in the chosen direction local <-> remote.
Parameters: - src (
ssh_utilities.typeshed._SPATH
) – path to the file - dst (
ssh_utilities.typeshed._SPATH
) – path to copy into - direction (
ssh_utilities.typeshed._DIRECTION
) – ‘get’ for download and ‘put’ for upload - follow_symlinks (bool) – resolve symlinks when looking for file, by default True
- callback (
ssh_utilities.typeshed._CALLBACK
) – callback function that recives two arguments: amount done and total amount to be copied - quiet (bool) – if True informative messages are suppresssed
Raises: FileNotFoundError
– if src is not fileIsADirectoryError
– if dst is a targer directory not full pathValueError
– if direction is not put or get
- src (
-
download_tree
(remote_path: _SPATH, local_path: _SPATH, include: _GLOBPAT = None, exclude: _GLOBPAT = None, remove_after: bool = False, quiet: typing_extensions.Literal[True, False, 'stats', 'progress'][True, False, stats, progress] = False)¶ Download directory tree from remote.
Remote directory must exist otherwise exception is raised.
Parameters: - remote_path (
ssh_utilities.typeshed._SPATH
) – path to directory which should be downloaded - local_path (
ssh_utilities.typeshed._SPATH
) – directory to copy to, must be full path! - remove_after (bool) – remove remote copy after directory is uploaded
- include (
ssh_utilities.typeshed._GLOBPAT
) – glob pattern of files to include in copy, can be used simultaneously with exclude, default is None = no filtering - exclude (
ssh_utilities.typeshed._GLOBPAT
) – glob pattern of files to exclude in copy, can be used simultaneously with include, default is None = no filtering - quiet (Literal[True, False, "stats", "progress"]) – if True informative messages are suppresssed if False all is printed, if stats all statistics except progressbar are suppressed if progress only progressbar is suppressed
Warning
both paths must be full: <some_remote_path>/my_directory -> <some_local_path>/my_directory
Raises: FileNotFoundError
– when remote directory does not exist- remote_path (
-
rmtree
(path: _SPATH, ignore_errors: bool = False, quiet: bool = True)¶ Recursively remove directory tree.
Parameters: - path (
ssh_utilities.typeshed._SPATH
) – directory to be recursively removed - ignore_errors (bool) – if True only log warnings do not raise exception
- quiet (bool) – if True informative messages are suppresssed
Raises: FileNotFoundError
– if some part of deleting filed- path (
-
upload_tree
(local_path: _SPATH, remote_path: _SPATH, include: _GLOBPAT = None, exclude: _GLOBPAT = None, remove_after: bool = False, quiet: typing_extensions.Literal[True, False, 'stats', 'progress'][True, False, stats, progress] = False)¶ Upload directory tree to remote.
Local path must exist otherwise, exception is raised.
Parameters: - local_path (
ssh_utilities.typeshed._SPATH
) – path to directory which should be uploaded - remote_path (
ssh_utilities.typeshed._SPATH
) – directory to copy to, must be full path! - remove_after (bool) – remove local copy after directory is uploaded
- include (
ssh_utilities.typeshed._GLOBPAT
) – glob pattern of files to include in copy, can be used simultaneously with exclude, default is None = no filtering - exclude (
ssh_utilities.typeshed._GLOBPAT
) – glob pattern of files to exclude in copy, can be used simultaneously with include, default is None = no filtering - quiet (Literal[True, False, "stats", "progress"]) – if True informative messages are suppresssed if False all is printed, if stats all statistics except progressbar are suppressed if progress only progressbar is suppressed
Warning
both paths must be full: <some_local_path>/my_directory -> <some_remote_path>/my_directory
Raises: FileNotFoundError
– when local directory does not exist- local_path (
ssh_utilities.remote._subprocess¶
Remote version of subprocess module.
-
class
ssh_utilities.remote._subprocess.
Subprocess
(connection: SSHConnection)¶ Bases:
ssh_utilities.abc._subprocess.SubprocessABC
Class with similar API to subprocess module.
See also
ssh_utilities.local.Subprocess
- local version of class with same API
-
run
(args: _CMD, *, suppress_out: bool, quiet: bool = True, bufsize: int = -1, executable: _SPATH = None, input: Optional[str] = None, stdin: _FILE = None, stdout: _FILE = None, stderr: _FILE = None, capture_output: bool = False, shell: bool = False, cwd: _SPATH = None, timeout: Optional[float] = None, check: bool = False, encoding: Optional[str] = None, errors: Optional[str] = None, text: Optional[bool] = None, env: _ENV = None, universal_newlines: bool = False) → ssh_utilities.utils.CompletedProcess¶ Excecute command on remote, has simillar API to subprocess run.
Parameters: - args (
ssh_utilities.typeshed._CMD
) – string, Path-like object or a list of strings. If it is a list it will be joined to string with whitespace delimiter. - suppress_out (bool) – whether to print command output to console, this is required keyword argument
- quiet (bool, optional) – whether to print other function messages, by default True
- bufsize (int, optional) – buffer size, 0 turns off buffering, 1 uses line buffering, and any number greater than 1 (>1) uses that specific buffer size. This applies ti underlying paramiko client as well as stdin, stdout and stderr PIPES, by default -1
- executable (
ssh_utilities.typeshed._SPATH
, optional) – [description], by default None - input (Optional[str], optional) – [description], by default None
- stdin (_FILE, optional) – [description], by default None
- stdout (_FILE, optional) – [description], by default None
- stderr (_FILE, optional) – [description], by default None
- capture_output (bool, optional) – if true then lightweight result object with same API as subprocess.CompletedProcess is returned. Same as passing PIPE to stdout and stderr. Both options cannot be used at the same time, by default False
- shell (bool, optional) – requests a pseudo terminal from server, by default False
- cwd (_SPATH, optional) – execute command in this directory, by default None
- timeout (Optional[float], optional) – set, by default None
- check (bool, optional) – checks for command return code if other than 0 raises CalledProcessError, by default False
- encoding (Optional[str], optional) – encoding to use when decoding remote output, default is utf-8, by default None
- errors (Optional[str], optional) –
string that specifies how encoding and decoding errors are to be handled, see builtin function open documentation for more details, by default None
- text (Optional[bool], optional) – will select default encoding and open stdin, stdout and stderr streams in text mode. The default encoding, contrary to behaviour of subprocess module is not selected by locale.getpreferredencoding(False) but is always set to utf-8. By default None
- env (
ssh_utilities.typeshed._ENV
, optional) – optinal environment variables that will be merged into the existing environment. This is different to subprocess behaviour which creates new environment with only specified variables, by default None - universal_newlines (bool, optional) – an alias for text keyword argument, by default None
Warning
New environment variables defined by env might get silently rejected by the server.
Currentlly it is only possible to use input agrgument, not stdin and send data to process only once at the begining. It is still under developement
Returns: if capture_output is true, returns lightweight result object with same API as subprocess.CompletedProcess
Return type: Raises: ValueError
– if stdin and input are specified at the same timeValueError
– if capture_output and stdout and/or stderr are specified at the same timeValueError
– if text or universal_newlines is used simultaneously with” encoding and/or errors argumentsNotImplementedError
– if stdin or executable is used - work in progressTypeError
– if stdin, stdout or stderr arguments are of wrong typeTypeError
– if args argument is of wrong typeCalledProcessError
– if check is true and command exited with non-zero statusTimeoutExpired
– if the command exceeded allowed run time
- args (
ssh_utilities.remote.path¶
Implements Path-like object for remote hosts.
-
class
ssh_utilities.remote.path.
SSHPath
¶ Bases:
pathlib.Path
Object porviding similar API to Pathlib.Path but for remote server.
The for all methods wrapper will wrap whole pathlib library and thus will always try to cas every path to SSHPath, so logic must be emplyed in wrapper to prevent this.
Parameters: - connection (Connection) – instance of ssh_utilities.Connection to server
- path (_SPATH) – initial path
Warning
Not all methods are implemented! Some rather obscure had to be left out due to the nature of ssh and lazyness of the author
Some methods have changed signature from classmethod -> instancemethod since old approach was not vaiable in this application. Most notably: home() and cwd().
Raises: NotImplementedError when on some methods that have not been implemented. -
_2str
¶ Return an attribute of instance, which is of type owner.
-
_flavour
(**kwds)¶ Internal indicator of special typing constructs. See _doc instance attribute for specific docs.
-
chmod
(mode: int)¶ Change the mode/permissions of a file.
The permissions are unix-style and identical to those used by Python’s os.chmod function.
Parameters: mode (int) – integer number of the desired mode
-
cwd
() → ssh_utilities.remote.path.SSHPath¶ Returns current working directory.
Warning
This is no longer a class method! Sometimes return value can be empty string for unknown reasons.
Returns: path to current directory Return type: SSHPath
-
exists
() → bool¶ Check if path exists.
This is constrained by the subset of implemented pathlib.Path functionality.
-
glob
(pattern: str) → Generator[ssh_utilities.remote.path.SSHPath, None, None]¶ Glob the given relative pattern in directory given by this path.
Parameters: pattern (str) – glob pattern to ue for filtering Yields: SSHPath – yields all matching files (of any kind): Raises: FileNotFoundError
– if current path does not point to directoryWarning
This method follows symlinks by default
-
group
()¶ Return the group name of the file gid.
-
home
() → ssh_utilities.remote.path.SSHPath¶ Get home dir on remote server for logged in user.
Warning
For this to work correctly sftp channel must be open
Returns: path to remote home Return type: Path
-
is_block_device
()¶ Check if path points to block device.
Returns: True if pointing to a block device Return type: bool
-
is_char_device
()¶ Check if path points to character device.
Returns: True if pointing to a character device Return type: bool
-
is_dir
() → bool¶ Check if path points to directory.
Returns: True if pointing to a directory Return type: bool
-
is_fifo
()¶ Check if path points to FIFO pipe.
Returns: True if pointing to a FIFO pipe Return type: bool
-
is_file
() → bool¶ Check if path points to file.
Returns: True if pointing to a file Return type: bool
-
is_mount
()¶ Check if this path is a POSIX mount point
-
is_socket
()¶ Check if path points to socket.
Returns: True if pointing to a socket Return type: bool
-
is_symlink
()¶ Check if path points to symlink.
Returns: True if pointing to a symlink Return type: bool
-
iterdir
() → Generator[ssh_utilities.remote.path.SSHPath, None, None]¶ Iterate files in current directory.
Yields: SSHPath – yields paths in current dir Raises: FileNotFoundError
– if this path is not a directory and thus cannot be iterated
-
lstat
()¶ Get file or directory statistics, do not resolve symlinks.
Returns: statistics objec similar to os.lstat output Return type: paramiko.sftp_attr.SFTPAttributes Raises: FileNotFoundError
– if input path does not exist
-
mkdir
(mode: int = 511, parents: bool = False, exist_ok: bool = False)¶ Recursively create directory.
If it already exists, show warning and return.
Parameters: - path ("_SPATH") – path to directory which should be created
- mode (int) – create directory with mode, default is 511
- exist_ok (bool) – if true and directory exists, exception is silently passed when dir already exists
- parents (bool) – if true any missing parent dirs are automatically created, else exception is raised on missing parent
Raises: OSError
– if directory could not be createdFileNotFoundError
– when parent directory is missing and parents=FalseFileExistsError
– when directory already exists and exist_ok=False
-
open
(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = 'utf-8') → SFTPFile¶ Opens remote file, works as pathlib.Path open function.
Can be used both as a function or a decorator.
Parameters: - filename (_SPATH) – path to file to be opened
- mode (str) – select mode to open file. Same as python open modes
- encoding (str) – encoding type to decode file bytes stream
- buffering (int) – buffer size, 0 turns off buffering, 1 uses line buffering, and any number greater than 1 (>1) uses that specific buffer size
Raises: FileNotFoundError
– when mode is ‘r’ and file does not exist
-
owner
()¶ Return the login name of the file owner.
-
read_bytes
() → bytes¶ Read contents of a file as bytes.
Returns: file contents encoded as bytes Return type: bytes Raises: FileNotFoundError
– if path does not point to a file
-
read_text
(encoding: Optional[str] = None, errors: Optional[str] = None) → str¶ Read whole file to string.
Parameters: - encoding (Optional[str], optional) – file encoding, by default None - means uft-8
- errors (Optional[str], optional) – error handling for the decoder, by default None - strict handling
Returns: whole file read to string
Return type: str
Raises: FileNotFoundError
– if file does not exist
-
rename
(target: _SPATH) → SSHPath¶ Rename directory or file.
Parameters: target (_SPATH) – path name afer renaming Warning
Works only in posix
-
replace
(target: _SPATH) → SSHPath¶ Rename this path to the given path.
Parameters: target (_SPATH) – target path Returns: New Path instance pointing to the given path. Return type: SSHPath
-
resolve
() → ssh_utilities.remote.path.SSHPath¶ Make the path absolute.
Resolve all symlinks on the way and also normalize it.
Returns: [description] Return type: “SSHPath”
-
rglob
(pattern: str) → Generator[ssh_utilities.remote.path.SSHPath, None, None]¶ Glob the given relative pattern in directory given by this path.
Convenience function for glob.
Parameters: pattern (str) – glob pattern to ue for filtering Yields: SSHPath – yields all matching files (of any kind) Raises: FileNotFoundError
– if current path does not point to directoryWarning
This method follows symlinks by default
-
rmdir
()¶ Remove directory, after point path to parent.
Warning
This is recursive contrary to pathlib.Path implementation
-
stat
() → SFTPAttributes¶ Get file or directory statistics, resolve symlinks alog the way.
Returns: statistics objec similar to os.stat output Return type: paramiko.sftp_attr.SFTPAttributes Raises: FileNotFoundError
– if input path does not exist
-
symlink_to
(target: _SPATH, target_is_directory: bool = False)¶ Make this path a symlink pointing to the given path.
Parameters: - target (_SPATH) – target path to which symlink will point
- target_is_directory (bool) – this parameter is ignored
-
touch
(mode: int = 438, exist_ok: bool = True)¶ Create this file with the given access mode, if it doesn’t exist.
The permissions are unix-style and identical to those used by Python’s os.chmod function.
Parameters: - mode (int) – integer number of the desired mode
- exist_ok (bool) – do not raise an exception when fiel already exists
Raises: FileExistsError
– when file or directory with same name already exists
-
unlink
(missing_ok: bool = False)¶ Delete file or symbolic link.
Parameters: missing_ok (bool, optional) – If False and file does not exist raise exception, by default False
Raises: FileNotFoundError
– if missing_ok is false and file does not existIsADirectoryError
– if trying to unlink a directory
-
write_bytes
(data: Union[bytes, bytearray, memoryview])¶ Write bytes to file.
Parameters: data (Union[bytes, bytearray, memoryview]) – content to write to file
-
write_text
(data, encoding: Optional[str] = None, errors: Optional[str] = None)¶ Write whole string to file.
Parameters: - data (str) – string to write to file
- encoding (Optional[str], optional) – file encoding, by default None - means uft-8
- errors (Optional[str], optional) – error handling for the decoder, by default None - strict handling
Raises: TypeError
– if data is not string type
ssh_utilities.remote._connection_wrapper¶
Module taking care of ssh connection resilience to drops.
-
class
ssh_utilities.remote._connection_wrapper.
check_connections
¶ Bases:
object
A decorator to check SSH connections, implemented as callble class.
If connection is dropped while running function, re-negotiate new connection and run function again.
Parameters: - original_function (Callable) – function to watch for dropped connections
- exclude_exceptions (Tuple[Exception]) – tuple of exceptions not to catch
Raises: exclude_exceptions – The esception specified in this parameter are allowed to bypass this decorator uncaught
Warning
Beware, this function can hide certain errors or cause the code to become stuck in an infinite loop!
References
https://stackoverflow.com/questions/3888158/making-decorators-with-optional-arguments
Examples
First use case is without arguments:
>>> @check_connections ... def function(*args, **kwargs):
Second possible use cases is with arguments:
>>> @check_connections(exclude_exceptions=(<Exception>, ...)) ... def function(*args, **kwargs):
-
static
_get_connection
(wrapped_instance: _CLASS) → SSHConnection¶ Find the underlying SSHConnection in inner classes hierarchy.
This is the instance to which the wrapped method belongs to. We have to deal with branching inner classes where attribute ‘c’ is instance of SSHConnection not paramiko SSHClient. As of now we have 2 inner levels so we must iterate until we get to the base.
Parameters: wrapped_instance (_CLASS) – any of: remote.Builtins
,remote.Os
,remote.Pathlib
,remote.Shutil
,remote.Subprocess
,remote.SSHConnection
Returns: the underlying connection object Return type: SSHConnection
-
_negotiate
(wrapped_instance: _CLASS) → bool¶ Negotiate new paramiko ssh connection for SSHConnection class.
Parameters: wrapped_instance (_CLASS) – any of: remote.Builtins
,remote.Os
,remote.Pathlib
,remote.Shutil
,remote.Subprocess
,remote.SSHConnection
Returns: True if negotiation was succesfull Return type: bool