Connection local classes

This file describe classes which emulate the remote API on local machine.

ssh_utilities.local

Collection of modules mirroring API or remote module.

class ssh_utilities.local.LocalConnection(address: Optional[str], username: str, password: Optional[str] = None, rsa_key_file: Union[str, Path, None] = None, line_rewrite: bool = True, server_name: Optional[str] = None, quiet: bool = False, thread_safe: bool = False)

Bases: ssh_utilities.abc._connection.ConnectionABC

Emulates SSHConnection class on local PC.

builtins

Inner class providing access to substitutions for python builtins.

Type:remote.Builtins
static close(*, quiet: bool = True)

Close emulated local connection.

os

Inner class providing access to substitutions for python os module.

Type:remote.Os
pathlib

Inner class providing access to substitutions for pathlib module.

Type:remote.Pathlib
shutil

Inner class providing access to substitutions for shutil module.

Type:remote.Shutil
subprocess

Inner class providing access to substitutions for subprocess module.

Type:remote.Subprocess
class ssh_utilities.local.Builtins(connection: LocalConnection)

Bases: ssh_utilities.abc._builtins.BuiltinsABC

Local proxy for python builtins, mainly the open function.

Supports same subset of API as remote version.

See also

ssh_utilities.remote.Builtins
remote version of class with same API
static open(filename: _SPATH, mode: str = 'r', encoding: Optional[str] = None, bufsize: int = -1, errors: Optional[str] = None) → IO

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
class ssh_utilities.local.Os(connection: LocalConnection)

Bases: ssh_utilities.abc._os.OsABC

Class housing subset os module methods with same API as remote version.

See also

ssh_utilities.remote.Os
remote version of class with same API
static isdir(path: _SPATH) → bool

Check if path points to directory.

Parameters:path (ssh_utilities.typeshed._SPATH) – path to check
Raises:IOError – if dir could not be accessed
static isfile(path: _SPATH) → bool

Check if path points to a file.

Parameters:path (ssh_utilities.typeshed._SPATH) – path to check
Raises:IOError – if file could not be accessed
static listdir(path: _SPATH) → List[str]

Lists contents of specified directory.

Parameters:path (ssh_utilities.typeshed._SPATH) – directory path
Returns:list of files, dirs, symlinks …
Return type:List[str]
Raises:FileNotFoundError – if directory does not exist
lstat(path: _SPATH, *, dir_fd=None) → os.stat_result

Similar to stat only this does not resolve symlinks.

Parameters:
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

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 created
  • FileNotFoundError – when parent directory is missing and parents=False
  • FileExistsError – when directory already exists and exist_ok=False
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 created
  • FileNotFoundError – when parent directory is missing and parents=False
  • FileExistsError – when directory already exists and exist_ok=False
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) → os.stat_result

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

class ssh_utilities.local.Pathlib(connection: LocalConnection)

Bases: ssh_utilities.abc._pathlib.PathlibABC

Proxy for pathlib.Path object with same API as remote version.

See also

ssh_utilities.remote.Pathlib
remote version of class with same API
Path(path: _SPATH) → pathlib.Path

Provides API similar to pathlib.Path only for remote host.

Only for Unix to Unix connections

Parameters:path (ssh_utilities.typeshed._SPATH) – provide initial path
Returns:object representing remote path
Return type:SSHPath
class ssh_utilities.local.Shutil(connection: LocalConnection)

Bases: ssh_utilities.abc._shutil.ShutilABC

Local version of shutil supporting same subset of API as remote version.

See also

ssh_utilities.remote.Shutil
remote 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:

Warning

Unlike shutil this function cannot preserve file permissions (copy) or file metadata (copy2)

Raises:
  • FileNotFoundError – if src is not file
  • ValueError – if direction is not put or get
static 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:
Raises:
  • FileNotFoundError – if src is not file
  • IsADirectoryError – if dst is a targer directory not full path
  • ValueError – if direction is not put or get
download_tree(remote_path: _SPATH, local_path: _SPATH, include: _GLOBPAT = None, exclude: _GLOBPAT = None, remove_after: bool = True, quiet: bool = 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
static 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
upload_tree(local_path: _SPATH, remote_path: _SPATH, include: _GLOBPAT = None, exclude: _GLOBPAT = None, remove_after: bool = True, quiet: bool = 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
class ssh_utilities.local.Subprocess(connection: LocalConnection)

Bases: ssh_utilities.abc._subprocess.SubprocessABC

Local proxy for subprocess module.

Supports same subset of API as remote version.

See also

ssh_utilities.remote.Subprocess
remote version of class with same API
static 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) → subprocess.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:

CompletedProcess
Raises:
  • ValueError – if stdin and input are specified at the same time
  • ValueError – if capture_output and stdout and/or stderr are specified at the same time
  • ValueError – if text or universal_newlines is used simultaneously with” encoding and/or errors arguments
  • NotImplementedError – if stdin or executable is used - work in progress
  • TypeError – if stdin, stdout or stderr arguments are of wrong type
  • TypeError – if args argument is of wrong type
  • CalledProcessError – if check is true and command exited with non-zero status
  • TimeoutExpired – if the command exceeded allowed run time

ssh_utilities.local._builtins

Python builtins proxy.

class ssh_utilities.local._builtins.Builtins(connection: LocalConnection)

Bases: ssh_utilities.abc._builtins.BuiltinsABC

Local proxy for python builtins, mainly the open function.

Supports same subset of API as remote version.

See also

ssh_utilities.remote.Builtins
remote version of class with same API
static open(filename: _SPATH, mode: str = 'r', encoding: Optional[str] = None, bufsize: int = -1, errors: Optional[str] = None) → IO

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

ssh_utilities.local._os

Local connection os methods.

class ssh_utilities.local._os.Os(connection: LocalConnection)

Bases: ssh_utilities.abc._os.OsABC

Class housing subset os module methods with same API as remote version.

See also

ssh_utilities.remote.Os
remote version of class with same API
static isdir(path: _SPATH) → bool

Check if path points to directory.

Parameters:path (ssh_utilities.typeshed._SPATH) – path to check
Raises:IOError – if dir could not be accessed
static isfile(path: _SPATH) → bool

Check if path points to a file.

Parameters:path (ssh_utilities.typeshed._SPATH) – path to check
Raises:IOError – if file could not be accessed
static listdir(path: _SPATH) → List[str]

Lists contents of specified directory.

Parameters:path (ssh_utilities.typeshed._SPATH) – directory path
Returns:list of files, dirs, symlinks …
Return type:List[str]
Raises:FileNotFoundError – if directory does not exist
lstat(path: _SPATH, *, dir_fd=None) → os.stat_result

Similar to stat only this does not resolve symlinks.

Parameters:
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

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 created
  • FileNotFoundError – when parent directory is missing and parents=False
  • FileExistsError – when directory already exists and exist_ok=False
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 created
  • FileNotFoundError – when parent directory is missing and parents=False
  • FileExistsError – when directory already exists and exist_ok=False
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) → os.stat_result

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

ssh_utilities.local._pathlib

Local proxy to pathlib library.

class ssh_utilities.local._pathlib.Pathlib(connection: LocalConnection)

Bases: ssh_utilities.abc._pathlib.PathlibABC

Proxy for pathlib.Path object with same API as remote version.

See also

ssh_utilities.remote.Pathlib
remote version of class with same API
Path(path: _SPATH) → pathlib.Path

Provides API similar to pathlib.Path only for remote host.

Only for Unix to Unix connections

Parameters:path (ssh_utilities.typeshed._SPATH) – provide initial path
Returns:object representing remote path
Return type:SSHPath

ssh_utilities.local._shutil

Module collecting shutil-like local methods.

class ssh_utilities.local._shutil.Shutil(connection: LocalConnection)

Bases: ssh_utilities.abc._shutil.ShutilABC

Local version of shutil supporting same subset of API as remote version.

See also

ssh_utilities.remote.Shutil
remote 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:

Warning

Unlike shutil this function cannot preserve file permissions (copy) or file metadata (copy2)

Raises:
  • FileNotFoundError – if src is not file
  • ValueError – if direction is not put or get
static 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:
Raises:
  • FileNotFoundError – if src is not file
  • IsADirectoryError – if dst is a targer directory not full path
  • ValueError – if direction is not put or get
download_tree(remote_path: _SPATH, local_path: _SPATH, include: _GLOBPAT = None, exclude: _GLOBPAT = None, remove_after: bool = True, quiet: bool = 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
static 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
upload_tree(local_path: _SPATH, remote_path: _SPATH, include: _GLOBPAT = None, exclude: _GLOBPAT = None, remove_after: bool = True, quiet: bool = 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

ssh_utilities.local._subprocess

Subprocess module proxy.