sftp.provider ============= .. py:module:: sftp.provider .. autoapi-nested-parse:: **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. .. rubric:: 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 ---------- .. autoapisummary:: sftp.provider.logger Classes ------- .. autoapisummary:: sftp.provider.Sftp Module Contents --------------- .. py:data:: logger .. py:class:: Sftp(client: paramiko.SFTPClient | None = None) High-level wrapper around :class:`paramiko.SFTPClient` for interacting with an SFTP server using SSH. The class manages the underlying :class:`paramiko.SSHClient` and SFTP session, and provides convenience methods for connecting and accessing the raw SSH/SFTP clients when needed. An existing :class:`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") .. py:attribute:: _client :type: paramiko.SFTPClient | None :value: None .. py:attribute:: _ssh .. py:method:: 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. :param host: Hostname or IP address of the SFTP server. :type host: str :param port: Port number to connect to (typically 22). :type port: int :param username: Username for authentication. :type username: str :param password: Password for authentication, or None if using only key-based auth. :type password: str | None :param passphrase: Passphrase for the private key, if required. :type passphrase: str | None :param host_key_fingerprint: Expected base64-encoded host key fingerprint for validation. Required if host key validation is enabled. :type host_key_fingerprint: str | None :param pkey: Private key in PEM format as a string, or None if not using key-based auth. :type pkey: str | None :param host_key_validation: Whether to perform host key validation against the provided fingerprint. :type host_key_validation: bool :param timeout: Optional connection timeout in seconds. :type timeout: float | None :returns: An active SFTP client connection. :rtype: paramiko.SFTPClient :raises AuthenticationError: If authentication fails, host key validation fails, or SSH transport is unavailable. :raises ConnectionError: For network errors or other connection issues. .. py:method:: _load_private_key(private_key: str, passphrase: str | None) -> paramiko.PKey Load and return an RSA private key for SFTP authentication. :param private_key: The private key in PEM format as a string. :type private_key: str :param passphrase: Passphrase for the private key, if required. :type passphrase: str | None :returns: The loaded RSA private key object. :rtype: paramiko.PKey :raises AuthenticationError: If the private key cannot be loaded (invalid format, wrong passphrase, etc). .. py:method:: _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. :param host: Hostname or IP address of the SFTP server. :type host: str :param port: Port number to connect to. :type port: int :param timeout: Optional connection timeout in seconds. :type timeout: float | None :param username: Username for authentication. :type username: str :param password: Password for authentication, if applicable. :type password: str | None :param pkey_obj: Private key object for authentication, if applicable. :type pkey_obj: paramiko.PKey | None :param host_key_fingerprint: Expected host key fingerprint for validation. :type host_key_fingerprint: str :returns: The SFTP client stored in the instance variable self._client. :rtype: paramiko.SFTPClient :raises ConnectionError: If the socket connection cannot be established. .. py:property:: ssh :type: paramiko.SSHClient Get the underlying SSHClient for direct use. .. py:property:: client :type: paramiko.SFTPClient Get the underlying SFTPClient for direct use. .. py:method:: __enter__() -> Sftp .. py:method:: __exit__(exc_type: Any, exc: Any, tb: Any) -> None .. py:method:: close() -> None