sftp.provider

File: provider.py Region: ds_protocol_sftp_py_lib/utils/sftp/provider

SFTP Provider

This module implements the Sftp class, which is a high-level wrapper around paramiko’s SFTPClient for managing SFTP connections.

Example

>> with Sftp() as sftp: … client = sftp.connect( … host=”sftp.example.com”, … port=22, … username=”user”, … password=”secret”, … passphrase=None, … host_key_fingerprint=None, … )

Attributes

logger

Classes

Sftp

High-level wrapper around paramiko.SFTPClient for interacting with an SFTP

Module Contents

sftp.provider.logger
class sftp.provider.Sftp(client: paramiko.SFTPClient | None = None)

High-level wrapper around paramiko.SFTPClient for interacting with an SFTP server using SSH.

The class manages the underlying paramiko.SSHClient and SFTP session, and provides convenience methods for connecting and accessing the raw SSH/SFTP clients when needed.

An existing paramiko.SFTPClient can be injected for cases where the SSH/SFTP session is created externally.

This class is also a context manager and can be used with with statements to automatically close the underlying SSH/SFTP connections.

Basic usage:

from ds_protocol_sftp_py_lib.utils.sftp.provider import Sftp

# Using explicit connect/close
sftp = Sftp()
client = sftp.connect(
    host="sftp.example.com",
    port=22,
    username="user",
    password="secret",
    passphrase=None,
    host_key_fingerprint=None,
)
files = sftp.client.listdir("/remote/path")
sftp.close()

# Using as a context manager
with Sftp() as sftp:
    client = sftp.connect(
        host="sftp.example.com",
        port=22,
        username="user",
        password="secret",
        passphrase=None,
        host_key_fingerprint=None,
        pkey=None,
        host_key_validation=True,
        timeout=None,
    )
    files = sftp.client.listdir("/remote/path")
_client: paramiko.SFTPClient | None = None
_ssh
connect(host: str, port: int, username: str, password: str | None, passphrase: str | None, host_key_fingerprint: str | None, pkey: str | None = None, host_key_validation: bool = True, timeout: float | None = None) → paramiko.SFTPClient

Establish and return an active SFTP client connection to the remote server.

The connection may use password authentication, private key authentication (with optional passphrase), or a combination, depending on the configuration. If host key validation is enabled, the remote server’s host key fingerprint is validated against the provided fingerprint before authentication.

Parameters:

  • host (str) – Hostname or IP address of the SFTP server.

  • port (int) – Port number to connect to (typically 22).

  • username (str) – Username for authentication.

  • password (str | None) – Password for authentication, or None if using only key-based auth.

  • passphrase (str | None) – Passphrase for the private key, if required.

  • host_key_fingerprint (str | None) – Expected base64-encoded host key fingerprint for validation. Required if host key validation is enabled.

  • pkey (str | None) – Private key in PEM format as a string, or None if not using key-based auth.

  • host_key_validation (bool) – Whether to perform host key validation against the provided fingerprint.

  • timeout (float | None) – Optional connection timeout in seconds.

Returns:

An active SFTP client connection.

Return type:

paramiko.SFTPClient

Raises:

  • AuthenticationError – If authentication fails, host key validation fails, or SSH transport is unavailable.

  • ConnectionError – For network errors or other connection issues.

_load_private_key(private_key: str, passphrase: str | None) → paramiko.PKey

Load and return an RSA private key for SFTP authentication.

Parameters:

  • private_key (str) – The private key in PEM format as a string.

  • passphrase (str | None) – Passphrase for the private key, if required.

Returns:

The loaded RSA private key object.

Return type:

paramiko.PKey

Raises:

AuthenticationError – If the private key cannot be loaded (invalid format, wrong passphrase, etc).

_connect_with_socket(host: str, port: int, timeout: float | None, username: str, password: str | None, pkey_obj: paramiko.PKey | None, host_key_fingerprint: str) → paramiko.SFTPClient | None

Establish a socket connection to the SFTP server and return a Paramiko SFTP client.

This method is used for the secure flow where host key validation is performed before authentication.

Parameters:

  • host (str) – Hostname or IP address of the SFTP server.

  • port (int) – Port number to connect to.

  • timeout (float | None) – Optional connection timeout in seconds.

  • username (str) – Username for authentication.

  • password (str | None) – Password for authentication, if applicable.

  • pkey_obj (paramiko.PKey | None) – Private key object for authentication, if applicable.

  • host_key_fingerprint (str) – Expected host key fingerprint for validation.

Returns:

The SFTP client stored in the instance variable self._client.

Return type:

paramiko.SFTPClient

Raises:

ConnectionError – If the socket connection cannot be established.

property ssh: paramiko.SSHClient

Get the underlying SSHClient for direct use.

property client: paramiko.SFTPClient

Get the underlying SFTPClient for direct use.

__enter__() → Sftp
__exit__(exc_type: Any, exc: Any, tb: Any) → None
close() → None