Package plumbum.machines

class plumbum.machines.base.BaseMachine

This is a base class for other machines. It contains common code to all machines in Plumbum.

get(cmd, *othercommands)

This works a little like the .get method with dict’s, only it supports an unlimited number of arguments, since later arguments are tried as commands and could also fail. It will try to call the first command, and if that is not found, it will call the next, etc. Will raise if no file named for the executable if a path is given, unlike [] access.

Usage:

best_zip = local.get('pigz','gzip')

Return type:

ConcreteCommand

__contains__(cmd)

Tests for the existence of the command, e.g., "ls" in plumbum.local. cmd can be anything acceptable by __getitem__.

Return type:

bool

property encoding

This is a wrapper for custom_encoding

abstractmethod clear_program_cache()

Clear the program cache, which is populated via machine.which(progname) calls.

This cache speeds up the lookup of a program in the machines PATH, and is particularly effective for RemoteMachines.

Return type:

None

class plumbum.machines.base.PopenAddons

This adds a verify to popen objects to that the correct command is attributed when an error is thrown.

verify(retcode, timeout, stdout, stderr)

This verifies that the correct command is attributed.

Return type:

None

__weakref__

list of weak references to the object

class plumbum.machines.base.PopenWithAddons(*args, **kwargs)

__init__(*args, **kwargs)

classmethod __subclasshook__(other)

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object

class plumbum.machines.env.BaseEnv(path_factory, pathsep, *, _curr)

The base class of LocalEnv and RemoteEnv

__init__(path_factory, pathsep, *, _curr)

__call__(*args, **kwargs)

A context manager that can be used for temporal modifications of the environment. Any time you enter the context, a copy of the old environment is stored, and then restored, when the context exits.

Parameters:

• args (Any) – Any positional arguments for update()

• kwargs (Any) – Any keyword arguments for update()

Return type:

Generator[None, None, None]

__iter__()

Returns an iterator over the items (key, value) of current environment (like dict.items)

Return type:

Iterator[tuple[str, Any]]

__hash__ = None

__len__()

Returns the number of elements of the current environment

Return type:

int

__contains__(name)

Tests whether an environment variable exists in the current environment

Return type:

bool

__getitem__(name)

Returns the value of the given environment variable from current environment, raising a KeyError if it does not exist

Return type:

str

keys()

Returns the keys of the current environment (like dict.keys)

Return type:

KeysView[str]

items()

Returns the items of the current environment (like dict.items)

Return type:

ItemsView[str, str]

values()

Returns the values of the current environment (like dict.values)

Return type:

ValuesView[str]

get(name, default=None)

Overloads:

• self, name (str), default (None) → str | None

• self, name (str), default (str) → str

Returns the keys of the current environment (like dict.keys)

__delitem__(name)

Deletes an environment variable from the current environment

Return type:

None

__setitem__(name, value)

Sets/replaces an environment variable’s value in the current environment

Return type:

None

pop(name, *default)

Pops an element from the current environment (like dict.pop)

Return type:

str | None

clear()

Clears the current environment (like dict.clear)

Return type:

None

update(*args, **kwargs)

Updates the current environment (like dict.update)

Return type:

None

getdict()

Returns the environment as a real dictionary

Return type:

dict[str, str]

property path

The system’s PATH (as an easy-to-manipulate list)

property home

Get or set the home path

property user

Return the user name, or None if it is not set

class plumbum.machines.env.EnvPathList(path_factory, pathsep)

__init__(path_factory, pathsep)

append(path)

Append object to the end of the list.

Return type:

None

extend(paths)

Extend list by appending elements from the iterable.

Return type:

None

insert(index, path)

Insert object before index.

Return type:

None

index(path)

Return first index of value.

Raises ValueError if the value is not present.

Return type:

int

__contains__(path)

Return bool(key in self).

Return type:

bool

remove(path)

Remove first occurrence of value.

Raises ValueError if the value is not present.

Return type:

None

class plumbum.machines.local.AsyncLocalMachine

Async version of LocalMachine.

This class provides async access to local commands and utilities. It delegates to the sync LocalMachine for command lookup and wraps the results in AsyncLocalCommand.

Example:

from plumbum.machines.local import async_local

# Command lookup delegates to sync local machine
ls = async_local["ls"]

# Execution is async
result = await ls("-la")

Added in version 2.0.

__getitem__(cmd)

Get an async command by name or path.

This delegates to local[cmd] to get the sync command, then wraps it.

Return type:

AsyncLocalCommand

Args:

cmd: Command name (will be looked up in PATH) or LocalPath

Returns:

AsyncLocalCommand instance

Raises:

CommandNotFound: If command is not found in PATH

__contains__(cmd)

Check if a command exists in PATH.

Return type:

bool

property cwd

Current working directory.

property env

Environment variables.

static path(*parts)

Create a LocalPath from parts.

Return type:

LocalPath

__weakref__

list of weak references to the object

class plumbum.machines.local.LocalCommand(executable, encoding='auto')

__init__(executable, encoding='auto')

popen(args=(), cwd=None, env=None, **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any]) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

class plumbum.machines.local.LocalEnv

The local machine’s environment; exposes a dict-like interface

__init__()

expand(expr)

Expands any environment variables and home shortcuts found in expr (like os.path.expanduser combined with os.path.expandvars)

Parameters:

expr (str) – An expression containing environment variables (as $FOO) or home shortcuts (as ~/.bashrc)

Return type:

str

Returns:

The expanded string

expanduser(expr)

Expand home shortcuts (e.g., ~/foo/bar or ~john/foo/bar)

Parameters:

expr (str) – An expression containing home shortcuts

Return type:

str

Returns:

The expanded string

class plumbum.machines.local.LocalMachine

The local machine (a singleton object). It serves as an entry point to everything related to the local machine, such as working directory and environment manipulation, command creation, etc.

Attributes:

• cwd - the local working directory

• env - the local environment

• custom_encoding - the local machine’s default encoding (sys.getfilesystemencoding())

__init__()

classmethod clear_program_cache()

Clear the program cache, which is populated via machine.which(progname) calls.

This cache speeds up the lookup of a program in the machines PATH, and is particularly effective for RemoteMachines.

Return type:

None

classmethod which(progname)

Looks up a program in the PATH. If the program is not found, raises CommandNotFound

Parameters:

progname (str) – The program’s name. Note that if underscores (_) are present in the name, and the exact name is not found, they will be replaced in turn by hyphens (-) then periods (.), and the name will be looked up again for each alternative

Return type:

LocalPath

Returns:

A LocalPath

path(*parts)

A factory for LocalPaths. Usage: p = local.path("/usr", "lib", "python2.7")

Return type:

LocalPath

__getitem__(cmd)

Returns a Command object representing the given program. cmd can be a string or a LocalPath; if it is a path, a command representing this path will be returned; otherwise, the program name will be looked up in the system’s PATH (using which). Usage:

ls = local["ls"]

Return type:

LocalCommand

daemonic_popen(command, cwd='/', stdout=None, stderr=None, append=True)

On POSIX systems:

Run command as a UNIX daemon: fork a child process to setpid, redirect std handles to /dev/null, umask, close all fds, chdir to cwd, then fork and exec command. Returns a Popen process that can be used to poll/wait for the executed command (but keep in mind that you cannot access std handles)

On Windows:

Run command as a “Windows daemon”: detach from controlling console and create a new process group. This means that the command will not receive console events and would survive its parent’s termination. Returns a Popen object.

Note

this does not run command as a system service, only detaches it from its parent.

Added in version 1.3.

Return type:

PopenWithAddons[str]

list_processes()

Returns information about all running processes (on POSIX systems: using ps)

Added in version 1.3.

Return type:

Generator[ProcInfo, None, None]

pgrep(pattern)

Process grep: return information about all processes whose command-line args match the given regex pattern

Return type:

Generator[ProcInfo, None, None]

session(new_session=False)

Creates a new ShellSession object; this invokes /bin/sh and executes commands on it over stdin/stdout/stderr

Return type:

ShellSession

tempdir()

A context manager that creates a temporary directory, which is removed when the context exits

Return type:

Generator[LocalPath, None, None]

as_user(username=None)

Run nested commands as the given user. For example:

head = local["head"]
head("-n1", "/dev/sda1")    # this will fail...
with local.as_user():
    head("-n1", "/dev/sda1")

Parameters:

username (str | None) – The user to run commands as. If not given, root (or Administrator) is assumed

Return type:

Generator[None, None, None]

as_root()

A shorthand for as_user("root")

Return type:

AbstractContextManager[None]

property python

A command that represents the current python interpreter (sys.executable).

class plumbum.machines.local.PlumbumLocalPopen(*args, **kwargs)

iter_lines(retcode=0, timeout=None, linesize=-1, line_timeout=None, buffer_size=None, *, mode=None, _iter_lines=<function _iter_lines_posix>)

Overloads:

• proc (PopenWithAddons[Any]), retcode (int), timeout (float | None), linesize (int), line_timeout (float | None), buffer_size (int | None), mode (Literal[Mode.BY_POSITION] | None), _iter_lines (Callable[[PopenWithAddons[Any], Callable[[bytes], str], int, float | None], Generator[tuple[int, str], None, None]]) → Generator[tuple[int, str], None, None]

• proc (PopenWithAddons[Any]), retcode (int), timeout (float | None), linesize (int), line_timeout (float | None), buffer_size (int | None), mode (Literal[Mode.BY_TYPE]), _iter_lines (Callable[[PopenWithAddons[Any], Callable[[bytes], str], int, float | None], Generator[tuple[int, str], None, None]]) → Generator[tuple[None, str] | tuple[str, None], None, None]

Runs the given process (equivalent to run_proc()) and yields a tuples of (out, err) line pairs. If the exit code of the process does not match the expected one, ProcessExecutionError is raised.

Parameters:

• retcode (int) – The expected return code of this process (defaults to 0). In order to disable exit-code validation, pass None. It may also be a tuple (or any iterable) of expected exit codes.

• timeout (float | None) – The maximal amount of time (in seconds) to allow the process to run. None means no timeout is imposed; otherwise, if the process hasn’t terminated after that many seconds, the process will be forcefully terminated an exception will be raised

• linesize (int) – Maximum number of characters to read from stdout/stderr at each iteration. -1 (default) reads until a b’n’ is encountered.

• line_timeout (float | None) – The maximal amount of time (in seconds) to allow between consecutive lines in either stream. Raise an ProcessLineTimedOut if the timeout has been reached. None means no timeout is imposed.

• buffer_size (int | None) – Maximum number of lines to keep in the stdout/stderr buffers, in case of a ProcessExecutionError. Default is None, which defaults to DEFAULT_BUFFER_SIZE (which is infinite by default). 0 will disable buffering completely.

• mode (Mode | None) – Controls what the generator yields. Defaults to DEFAULT_ITER_LINES_MODE (which is BY_POSITION by default) - BY_POSITION (default): yields (out, err) line tuples, where either item may be None - BY_TYPE: yields (fd, line) tuples, where fd is 1 (stdout) or 2 (stderr)

Returns:

An iterator of (out, err) line tuples.

__init__(*args, **kwargs)

plumbum.machines.local.async_local = <plumbum.machines.local.AsyncLocalMachine object>

Async version of the local machine singleton.

Use this to access async commands:

from plumbum import async_local
# or
from plumbum.machines.local import async_local

async def main():
    result = await async_local["ls"]("-la")
    print(result)

Added in version 2.0.

plumbum.machines.local.local = <plumbum.machines.local.LocalMachine object>

The local machine (a singleton object). It serves as an entry point to everything related to the local machine, such as working directory and environment manipulation, command creation, etc.

Attributes:

• cwd - the local working directory

• env - the local environment

• custom_encoding - the local machine’s default encoding (sys.getfilesystemencoding())

exception plumbum.machines.session.HostPublicKeyUnknown(argv, retcode, stdout, stderr, message=None, *, host=None)

Raises when the host public key isn’t known

exception plumbum.machines.session.IncorrectLogin(argv, retcode, stdout, stderr, message=None, *, host=None)

Raises when incorrect login credentials are provided

class plumbum.machines.session.MarkedPipe(pipe, marker)

A pipe-like object from which you can read lines; the pipe will return report EOF (the empty string) when a special marker is detected

__init__(pipe, marker)

close()

‘Closes’ the marked pipe; following calls to readline will return “”

Return type:

None

readline()

Reads the next line from the pipe; returns “” when the special marker is reached. Raises EOFError if the underlying pipe has closed

Return type:

bytes

exception plumbum.machines.session.SSHCommsChannel2Error(argv, retcode, stdout, stderr, message=None, *, host=None)

Raises when channel 2 (stderr) is not available

exception plumbum.machines.session.SSHCommsError(argv, retcode, stdout, stderr, message=None, *, host=None)

Raises when the communication channel can’t be created on the remote host or it times out.

class plumbum.machines.session.SessionPopen(proc, argv, isatty, stdin, stdout, stderr, encoding, *, host)

A shell-session-based Popen-like object (has the following attributes: stdin, stdout, stderr, returncode)

__init__(proc, argv, isatty, stdin, stdout, stderr, encoding, *, host)

poll()

Returns the process’ exit code or None if it’s still running

Return type:

int | None

wait()

Waits for the process to terminate and returns its exit code

Return type:

int

communicate(input=None)

Consumes the process’ stdout and stderr until the it terminates.

Parameters:

input (bytes | bytearray | None) – An optional bytes/buffer object to send to the process over stdin

Return type:

tuple[bytes, bytes]

Returns:

A tuple of (stdout, stderr)

class plumbum.machines.session.ShellSession(proc, encoding='auto', isatty=False, connect_timeout=5, *, host=None)

An abstraction layer over shell sessions. A shell session is the execution of an interactive shell (/bin/sh or something compatible), over which you may run commands (sent over stdin). The output of is then read from stdout and stderr. Shell sessions are less “robust” than executing a process on its own, and they are susseptible to all sorts of malformatted-strings attacks, and there is little benefit from using them locally. However, they can greatly speed up remote connections, and are required for the implementation of SshMachine, as they allow us to send multiple commands over a single SSH connection (setting up separate SSH connections incurs a high overhead). Try to avoid using shell sessions, unless you know what you’re doing.

Instances of this class may be used as context-managers.

Parameters:

• proc (PopenWithAddons[Any] | SessionPopen | ParamikoPopen) – The underlying shell process (with open stdin, stdout and stderr)

• encoding (str) – The encoding to use for the shell session. If "auto", the underlying process’ encoding is used.

• isatty (bool) – If true, assume the shell has a TTY and that stdout and stderr are unified

• connect_timeout (float | None) – The timeout to connect to the shell, after which, if no prompt is seen, the shell process is killed

__init__(proc, encoding='auto', isatty=False, connect_timeout=5, *, host=None)

alive()

Returns True if the underlying shell process is alive, False otherwise

Return type:

bool

close()

Closes (terminates) the shell session

Return type:

None

popen(cmd)

Runs the given command in the shell, adding some decoration around it. Only a single command can be executed at any given time.

Parameters:

cmd (str | BaseCommand) – The command (string or Command object) to run

Return type:

PopenWithAddons[Any]

Returns:

A SessionPopen instance

run(cmd, retcode=0)

Runs the given command

Parameters:

• cmd (str | BaseCommand) – The command (string or Command object) to run

• retcode (int | None | Container[int]) – The expected return code (0 by default). Set to None in order to ignore erroneous return codes

Return type:

tuple[int | None, str, str]

Returns:

A tuple of (return code, stdout, stderr)

exception plumbum.machines.session.ShellSessionError

Raises when something goes wrong when calling ShellSession.popen

__weakref__

list of weak references to the object

Remote Machines

class plumbum.machines.remote.AsyncRemoteMachine(sync_machine)

Async version of BaseRemoteMachine.

This class provides async access to remote commands via SSH. It wraps a sync RemoteMachine and provides async execution methods.

Example:

from plumbum.machines.ssh_machine import AsyncSshMachine

async with AsyncSshMachine("host") as rem:
    ls = rem["ls"]
    result = await ls("-la")

Added in version 2.0.

__init__(sync_machine)

Initialize with a sync remote machine to wrap.

Args:

sync_machine: The sync remote machine to wrap

__getitem__(cmd)

Get an async remote command by name or path.

This delegates to the sync machine for command lookup, then wraps it.

Return type:

AsyncRemoteCommand

Args:

cmd: Command name (will be looked up in PATH) or RemotePath

Returns:

AsyncRemoteCommand instance

Raises:

CommandNotFound: If command is not found in PATH

__contains__(cmd)

Check if a command exists in remote PATH.

Return type:

bool

property cwd

Current working directory on remote machine.

property env

Environment variables on remote machine.

path(*parts)

Create a RemotePath from parts.

Return type:

RemotePath

close()

Close the connection to the remote machine.

Return type:

None

async __aenter__()

Async context manager entry.

Return type:

Self

async __aexit__(t, v, tb)

Async context manager exit.

Return type:

None

class plumbum.machines.remote.BaseRemoteMachine(encoding='utf8', connect_timeout=10, new_session=False)

Represents a remote machine; serves as an entry point to everything related to that remote machine, such as working directory and environment manipulation, command creation, etc.

Attributes:

• cwd - the remote working directory

• env - the remote environment

• custom_encoding - the remote machine’s default encoding (assumed to be UTF8)

• connect_timeout - the connection timeout

There also is a _cwd attribute that exists if the cwd is not current (del if cwd is changed).

class RemoteCommand(remote, executable, encoding='auto')

__init__(remote, executable, encoding='auto')

__repr__()

Return repr(self).

Return type:

str

nohup(cwd='.', stdout='nohup.out', stderr=None, append=True)

Runs a command detached.

Return type:

PopenWithAddons[str]

popen(args=(), **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any] | str) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

__init__(encoding='utf8', connect_timeout=10, new_session=False)

clear_program_cache()

Clear the program cache, which is populated via machine.which(progname) calls.

This cache speeds up the lookup of a program in the machines PATH, and is particularly effective for RemoteMachines.

Return type:

None

__repr__()

Return repr(self).

Return type:

str

close()

closes the connection to the remote machine; all paths and programs will become defunct

Return type:

None

path(*parts)

A factory for RemotePaths. Usage: p = rem.path("/usr", "lib", "python2.7")

Return type:

RemotePath

which(progname)

Looks up a program in the PATH. If the program is not found, raises CommandNotFound

Parameters:

progname (str) – The program’s name. Note that if underscores (_) are present in the name, and the exact name is not found, they will be replaced in turn by hyphens (-) then periods (.), and the name will be looked up again for each alternative

Return type:

RemotePath

Returns:

A RemotePath

__getitem__(cmd)

Returns a Command object representing the given program. cmd can be a string or a RemotePath; if it is a path, a command representing this path will be returned; otherwise, the program name will be looked up in the system’s PATH (using which). Usage:

r_ls = rem["ls"]

Return type:

ConcreteCommand

property python

A command that represents the default remote python interpreter

session(isatty=False, *, new_session=False)

Creates a new ShellSession object; this invokes the user’s shell on the remote machine and executes commands on it over stdin/stdout/stderr

Return type:

ShellSession

download(src, dst)

Downloads a remote file/directory (src) to a local destination (dst). src must be a string or a RemotePath pointing to this remote machine, and dst must be a string or a LocalPath

Return type:

None

upload(src, dst)

Uploads a local file/directory (src) to a remote destination (dst). src must be a string or a LocalPath, and dst must be a string or a RemotePath pointing to this remote machine

Return type:

None

popen(args, **kwargs)

Spawns the given command on the remote machine, returning a Popen-like object; do not use this method directly, unless you need “low-level” control on the remote process

Return type:

PopenWithAddons[str]

list_processes()

Returns information about all running processes (on POSIX systems: using ps)

Added in version 1.3.

Return type:

Generator[ProcInfo, None, None]

pgrep(pattern)

Process grep: return information about all processes whose command-line args match the given regex pattern

Return type:

Generator[ProcInfo, None, None]

tempdir()

A context manager that creates a remote temporary directory, which is removed when the context exits

Return type:

Generator[RemotePath, None, None]

exception plumbum.machines.remote.ClosedRemoteMachine

__weakref__

list of weak references to the object

class plumbum.machines.remote.RemoteCommand(remote, executable, encoding='auto')

__init__(remote, executable, encoding='auto')

__repr__()

Return repr(self).

Return type:

str

popen(args=(), **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any] | str) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

nohup(cwd='.', stdout='nohup.out', stderr=None, append=True)

Runs a command detached.

Return type:

PopenWithAddons[str]

class plumbum.machines.remote.RemoteEnv(remote)

The remote machine’s environment; exposes a dict-like interface

__init__(remote)

__delitem__(name)

Deletes an environment variable from the current environment

Return type:

None

__setitem__(name, value)

Sets/replaces an environment variable’s value in the current environment

Return type:

None

pop(name, *default)

Pops an element from the current environment (like dict.pop)

Return type:

str | None

update(*args, **kwargs)

Updates the current environment (like dict.update)

Return type:

None

expand(expr)

Expands any environment variables and home shortcuts found in expr (like os.path.expanduser combined with os.path.expandvars)

Parameters:

expr (str) – An expression containing environment variables (as $FOO) or home shortcuts (as ~/.bashrc)

Return type:

str

Returns:

The expanded string

expanduser(expr)

Expand home shortcuts (e.g., ~/foo/bar or ~john/foo/bar)

Parameters:

expr (str) – An expression containing home shortcuts

Return type:

str

Returns:

The expanded string

getdelta()

Returns the difference between the this environment and the original environment of the remote machine

Return type:

dict[str, str]

class plumbum.machines.ssh_machine.AsyncSshMachine(host, user=None, port=None, keyfile=None, ssh_command=None, scp_command=None, ssh_opts=(), scp_opts=(), password=None, encoding='utf8', connect_timeout=10, new_session=False)

Async version of SshMachine.

This class provides async SSH command execution. It wraps a sync SshMachine and provides async execution methods.

Example:

from plumbum.machines.ssh_machine import AsyncSshMachine

async with AsyncSshMachine("hostname") as rem:
    result = await rem["ls"]("-la")

    # Concurrent execution
    results = await asyncio.gather(
        rem["echo"]("task1"),
        rem["echo"]("task2"),
    )

Added in version 2.0.

__init__(host, user=None, port=None, keyfile=None, ssh_command=None, scp_command=None, ssh_opts=(), scp_opts=(), password=None, encoding='utf8', connect_timeout=10, new_session=False)

Initialize async SSH machine.

Args:

host: The host name to connect to (SSH server) user: The user to connect as (if None, the default will be used) port: The server’s port (if None, the default will be used) keyfile: The path to the identity file (if None, the default will be used) ssh_command: The ssh command to use (if None, the default will be used) scp_command: The scp command to use (if None, the default will be used) ssh_opts: Any additional options for ssh (a list of strings) scp_opts: Any additional options for scp (a list of strings) password: The password to use (requires sshpass) encoding: The remote machine’s encoding (defaults to UTF8) connect_timeout: Connection timeout (default 10 seconds) new_session: Whether to start as a new session leader

__getitem__(cmd)

Get an async remote command by name or path.

Return type:

AsyncRemoteCommand

__contains__(cmd)

Check if a command exists in remote PATH.

Return type:

bool

property cwd

Current working directory on remote machine.

property env

Environment variables on remote machine.

path(*parts)

Create a RemotePath from parts.

Return type:

RemotePath

close()

Close the connection to the remote machine.

Return type:

None

async __aenter__()

Async context manager entry.

Return type:

Self

async __aexit__(t, v, tb)

Async context manager exit.

Return type:

None

class plumbum.machines.ssh_machine.PuttyMachine(host, user=None, port=None, keyfile=None, ssh_command=None, scp_command=None, ssh_opts=(), scp_opts=(), encoding='utf8', connect_timeout=10, new_session=False)

PuTTY-flavored SSH connection. The programs plink and pscp are expected to be in the path (or you may provide your own ssh_command and scp_command)

Arguments are the same as for plumbum.machines.ssh_machine.SshMachine

__init__(host, user=None, port=None, keyfile=None, ssh_command=None, scp_command=None, ssh_opts=(), scp_opts=(), encoding='utf8', connect_timeout=10, new_session=False)

__str__()

Return str(self).

Return type:

str

session(isatty=False, new_session=False)

Creates a new ShellSession object; this invokes the user’s shell on the remote machine and executes commands on it over stdin/stdout/stderr

Return type:

ShellSession

class plumbum.machines.ssh_machine.SshMachine(host, user=None, port=None, keyfile=None, ssh_command=None, scp_command=None, ssh_opts=(), scp_opts=(), password=None, encoding='utf8', connect_timeout=10, new_session=False)

An implementation of remote machine over SSH. Invoking a remote command translates to invoking it over SSH

with SshMachine("yourhostname") as rem:
    r_ls = rem["ls"]
    # r_ls is the remote `ls`
    # executing r_ls() translates to `ssh yourhostname ls`

Parameters:

• host (str) – the host name to connect to (SSH server)

• user (str | None) – the user to connect as (if None, the default will be used)

• port (int | None) – the server’s port (if None, the default will be used)

• keyfile (str | None) – the path to the identity file (if None, the default will be used)

• ssh_command (BaseCommand | None) – the ssh command to use; this has to be a Command object; if None, the default ssh client will be used.

• scp_command (BaseCommand | None) – the scp command to use; this has to be a Command object; if None, the default scp program will be used.

• ssh_opts (Sequence[str]) – any additional options for ssh (a list of strings)

• scp_opts (Sequence[str]) – any additional options for scp (a list of strings)

• password (str | None) – the password to use; requires sshpass be installed. Cannot be used in conjunction with ssh_command or scp_command (will be ignored). NOTE: THIS IS A SECURITY RISK!

• encoding (str) – the remote machine’s encoding (defaults to UTF8)

• connect_timeout (float | None) – specify a connection timeout (the time until shell prompt is seen). The default is 10 seconds. Set to None to disable

• new_session (bool) – whether or not to start the background session as a new session leader (setsid). This will prevent it from being killed on Ctrl+C (SIGINT)

__init__(host, user=None, port=None, keyfile=None, ssh_command=None, scp_command=None, ssh_opts=(), scp_opts=(), password=None, encoding='utf8', connect_timeout=10, new_session=False)

__str__()

Return str(self).

Return type:

str

popen(args, ssh_opts=(), env=None, cwd=None, **kwargs)

Spawns the given command on the remote machine, returning a Popen-like object; do not use this method directly, unless you need “low-level” control on the remote process

Return type:

PopenWithAddons[str]

daemonic_popen(command, cwd='.', stdout=None, stderr=None, append=True)

Runs the given command using nohup and redirects std handles, allowing the command to run “detached” from its controlling TTY or parent. Does not return anything.

Added in version 1.6.0.

Return type:

PopenWithAddons[str]

session(isatty=False, new_session=False)

Creates a new ShellSession object; this invokes the user’s shell on the remote machine and executes commands on it over stdin/stdout/stderr

Return type:

ShellSession

tunnel(lport, dport, lhost='localhost', dhost='localhost', connect_timeout=None, reverse=False)

Creates an SSH tunnel from the TCP port (lport) of the local machine (lhost, defaults to "localhost", but it can be any IP you can bind()) to the remote TCP port (dport) of the destination machine (dhost, defaults to "localhost", which means this remote machine). This function also supports Unix sockets, in which case the local socket should be passed in as lport and the local bind address should be None. The same can be done for a remote socket, by following the same pattern with dport and dhost. The returned SshTunnel object can be used as a context-manager.

The more conventional use case is the following:

+---------+          +---------+
| Your    |          | Remote  |
| Machine |          | Machine |
+----o----+          +---- ----+
     |                    ^
     |                    |
   lport                dport
     |                    |
     \______SSH TUNNEL____/
            (secure)

Here, you wish to communicate safely between port lport of your machine and port dport of the remote machine. Communication is tunneled over SSH, so the connection is authenticated and encrypted.

The more general case is shown below (where dport != "localhost"):

+---------+          +-------------+      +-------------+
| Your    |          | Remote      |      | Destination |
| Machine |          | Machine     |      | Machine     |
+----o----+          +---- ----o---+      +---- --------+
     |                    ^    |               ^
     |                    |    |               |
lhost:lport               |    |          dhost:dport
     |                    |    |               |
     \_____SSH TUNNEL_____/    \_____SOCKET____/
            (secure)              (not secure)

Usage:

rem = SshMachine("megazord")

with rem.tunnel(1234, "/var/lib/mysql/mysql.sock", dhost=None):
    sock = socket.socket()
    sock.connect(("localhost", 1234))
    # sock is now tunneled to the MySQL socket on megazord

The connect_timeout is the time to wait for the tunnel’s shell prompt; if not given, the machine-level connect_timeout is used.

Return type:

SshTunnel

download(src, dst)

Downloads a remote file/directory (src) to a local destination (dst). src must be a string or a RemotePath pointing to this remote machine, and dst must be a string or a LocalPath

Return type:

None

upload(src, dst)

Uploads a local file/directory (src) to a remote destination (dst). src must be a string or a LocalPath, and dst must be a string or a RemotePath pointing to this remote machine

Return type:

None

class plumbum.machines.ssh_machine.SshTunnel(session, lport, dport, reverse)

An object representing an SSH tunnel (created by SshMachine.tunnel)

__init__(session, lport, dport, reverse)

__repr__()

Return repr(self).

Return type:

str

close()

Closes(terminates) the tunnel

Return type:

None

property lport

Tunneled port or socket on the local machine.

property dport

Tunneled port or socket on the remote machine.

property reverse

Represents if the tunnel is a reverse tunnel.

class plumbum.machines.paramiko_machine.ParamikoMachine(host, user=None, port=None, password=None, keyfile=None, load_system_host_keys=True, missing_host_policy=None, encoding='utf8', look_for_keys=None, connect_timeout=None, keep_alive=0, gss_auth=False, gss_kex=None, gss_deleg_creds=None, gss_host=None, get_pty=False, load_system_ssh_config=False)

An implementation of remote machine over Paramiko (a Python implementation of openSSH2 client/server). Invoking a remote command translates to invoking it over SSH

with ParamikoMachine("yourhostname") as rem:
    r_ls = rem["ls"]
    # r_ls is the remote `ls`
    # executing r_ls() is equivalent to `ssh yourhostname ls`, only without
    # spawning a new ssh client

Parameters:

• host (str) – the host name to connect to (SSH server)

• user (str | None) – the user to connect as (if None, the default will be used)

• port (int | None) – the server’s port (if None, the default will be used)

• password (str | None) – the user’s password (if a password-based authentication is to be performed) (if None, key-based authentication will be used)

• keyfile (str | None) – the path to the identity file (if None, the default will be used)

• load_system_host_keys (bool) – whether or not to load the system’s host keys (from /etc/ssh and ~/.ssh). The default is True, which means Paramiko behaves much like the ssh command-line client

• missing_host_policy (Any | None) – the value passed to the underlying set_missing_host_key_policy of the client. The default is None, which means set_missing_host_key_policy is not invoked and paramiko’s default behavior (reject) is employed

• encoding (str) – the remote machine’s encoding (defaults to UTF8)

• look_for_keys (bool | None) – set to False to disable searching for discoverable private key files in ~/.ssh

• connect_timeout (float | None) – timeout for TCP connection

Note

If Paramiko 1.15 or above is installed, can use GSS_API authentication

Parameters:

• gss_auth (bool) – True if you want to use GSS-API authentication

• gss_kex (bool | None) – Perform GSS-API Key Exchange and user authentication

• gss_deleg_creds (bool | None) – Delegate GSS-API client credentials or not

• gss_host (str | None) – The targets name in the kerberos database. default: hostname

• get_pty (bool) – Execute remote commands with allocated pseudo-tty. default: False

• load_system_ssh_config (bool) – read system SSH config for ProxyCommand configuration. default: False

class RemoteCommand(remote, executable, encoding='auto')

__or__(*_)

Creates a pipe with the other command

Return type:

Any

__gt__(*_)

Return self>value.

Return type:

Any

__ge__(*_)

Return self>=value.

Return type:

Any

__lt__(*_)

Return self<value.

Return type:

Any

__init__(host, user=None, port=None, password=None, keyfile=None, load_system_host_keys=True, missing_host_policy=None, encoding='utf8', look_for_keys=None, connect_timeout=None, keep_alive=0, gss_auth=False, gss_kex=None, gss_deleg_creds=None, gss_host=None, get_pty=False, load_system_ssh_config=False)

__str__()

Return str(self).

Return type:

str

close()

closes the connection to the remote machine; all paths and programs will become defunct

Return type:

None

property sftp

Returns an SFTP client on top of the current SSH connection; it can be used to manipulate files directly, much like an interactive FTP/SFTP session

session(isatty=False, term='vt100', width=80, height=24, *, new_session=False)

Creates a new ShellSession object; this invokes the user’s shell on the remote machine and executes commands on it over stdin/stdout/stderr

Return type:

ShellSession

popen(args, stdin=None, stdout=None, stderr=None, new_session=False, env=None, cwd=None)

Spawns the given command on the remote machine, returning a Popen-like object; do not use this method directly, unless you need “low-level” control on the remote process

Return type:

ParamikoPopen

download(src, dst)

Downloads a remote file/directory (src) to a local destination (dst). src must be a string or a RemotePath pointing to this remote machine, and dst must be a string or a LocalPath

Return type:

None

upload(src, dst)

Uploads a local file/directory (src) to a remote destination (dst). src must be a string or a LocalPath, and dst must be a string or a RemotePath pointing to this remote machine

Return type:

None

connect_sock(dport, dhost='localhost', ipv6=False)

Returns a Paramiko Channel, connected to dhost:dport on the remote machine. The Channel behaves like a regular socket; you can send and recv on it and the data will pass encrypted over SSH. Usage:

mach = ParamikoMachine("myhost")
sock = mach.connect_sock(12345)
data = sock.recv(100)
sock.send("foobar")
sock.close()

Return type:

SocketCompatibleChannel

class plumbum.machines.paramiko_machine.ParamikoPopen(argv, stdin, stdout, stderr, encoding, stdin_file=None, stdout_file=None, stderr_file=None)

__init__(argv, stdin, stdout, stderr, encoding, stdin_file=None, stdout_file=None, stderr_file=None)

class plumbum.machines.paramiko_machine.RemoteCommand(remote, executable, encoding='auto')

__or__(*_)

Creates a pipe with the other command

Return type:

Any