connection

The ConnectionPlus class is a subclass of Fabric’s Connection class.

As such, (almost) all of the methods and attributes of the Connection class are available in the ConnectionPlus class.

To see information about those features, see the Fabric Connection Documentation.

class fabricplus.connection.ConnectionPlus(*args, jumphost_target: SSHJumpClient | SSHClient | str | Conn | None = None, scp: bool | None = None, jump_uname: str | None = None, jump_port: int | None = None, **kwargs)

ConnectionPlus is a subclass of the Connection object from the Fabric library.

This subclass provides additional functionality to the Connection object, such as SCP transfers, running commands as another user, and running commands on a jumphost, as well as connecting to a host through a jumphost.

__init__(*args, jumphost_target: SSHJumpClient | SSHClient | str | Conn | None = None, scp: bool | None = None, jump_uname: str | None = None, jump_port: int | None = None, **kwargs)

Initialize the ConnectionPlus object.

Initializes using the Connection initialization, but also sets up the client object for the ConnectionPlus object via a jumphost target.

See the Connection object documentation for additional arguments.

Parameters:

  • args – Additional arguments to pass to the Connection object.

  • jumphost_target – Jumphost to connect to the host through. Can be an instance of SSHJumpClient, SSHClient, URL/IP string, or Connection/ConnectionPlus. Defaults to None.

  • scp – Boolean value to define if the ConnectionPlus object should use SCP for file transfers. Defaults to False.

  • jump_uname – Username for the jumphost if different than the connection. Defaults to None.

  • jump_port – Port for the jumphost if different than the default SSH_PORT. Defaults to None.

  • kwargs – Additional keyword arguments to pass to the Connection object.

get(*args, **kwargs) → Result | None

Get a file from the remote host.

Parameters:

  • remote_path – The path to the file on the remote host.

  • local_path – The path to save the file locally. Defaults to current working dir.

  • scp – If the transfer should be done via SCP. Defaults to False or the Connection value.

  • recursive – If the transfer should be recursive. Defaults to False.

  • preserve_times – If the file times should be preserved. Defaults to False.

Returns:

Result object from the transfer, or None.

Return type:

Optional[fabric.transfer.Result]

property jump_client: SSHJumpClient | SSHClient | None

Get the jump client object for the ConnectionPlus object.

Returns:

The jump client object for the ConnectionPlus object.

Return type:

Optional[SSHJumpClient]

jump_run(command: str, timeout: int = 10, **kwargs) → Result | None

Run a command on the jumphost.

Parameters:

  • command – Command to run on the jumphost.

  • timeout – Timeout for the command. Defaults to 10.

  • kwargs – Additional keyword arguments to pass to the command execution.

Raises:

AttributeError – If the ConnectionPlus object does not have a jump client initialized.

Returns:

Result object from the command execution.

Return type:

Optional[Result]

put(*args, **kwargs) → Result | None

Put a file on the remote host.

Parameters:

  • local_path – The path to the file on the local host.

  • remote_path – The path to save the file remotely. Defaults to current working dir for the session.

  • scp – If the transfer should be done via SCP. Defaults to False or the Connection value.

  • recursive – If the transfer should be recursive. Defaults to False.

  • preserve_times – If the file times should be preserved. Defaults to False.

Returns:

Result object from the transfer.

Return type:

Optional[fabric.transfer.Result]

scp() → SCPClient

Get the SCP client object for the ConnectionPlus object.

Will open an SCP client object if one is not already open.

Raises:

  • AttributeError – If the base fabric Connection object does not have an SSH client initialized.

  • AttributeError – If the base fabric Connection object does not have an SCP client initialized.

  • AttributeError – If the ConnectionPlus object could not initialize it’s client.

Returns:

The SCP client object for the ConnectionPlus object.

Return type:

SCPClient

su(command: str, user: str, password: str | None = None, timeout: int = 10, **kwargs: Any) → Result | None

Run a command as another user, via su.

Requires the target user’s password be given, either directly, or via the ConnectionPlus object.

Note: This method doesn’t work on Windows, as Windows doesn’t have su, nor does it work in parallel on some systems due to the way su is implemented (e.g. it may require a tty).

Parameters:

  • command – Command to run in su.

  • user – User to run the command as.

  • password – Password for the target user. Needed, but defaults to None.

  • timeout – Timeout for the command. Defaults to 10.

  • kwargs – Additional keyword arguments to pass to the command execution.

Raises:

ValueError – If the password is not given.

Returns:

Result object from the command execution.

Return type:

Optional[Result]