ds_protocol_sftp_py_lib.linked_service.sftp
===========================================

.. py:module:: ds_protocol_sftp_py_lib.linked_service.sftp

.. autoapi-nested-parse::

   **File**: `sftp.py`
   **Region**: `src/ds_protocol_sftp_py_lib/linked_service/sftp`

   SFTP Linked Service implementation.

   This module defines the `SftpLinkedService` class, which implements a linked service for SFTP connections,
   including connection management, error handling, and integration with the SFTP client.

   .. rubric:: Example

   >>> import uuid
   >>> from ds_protocol_sftp_py_lib.linked_service import SftpLinkedService, SftpLinkedServiceSettings
   >>> linked_service = SftpLinkedService(
   ...     id=uuid.uuid4(),
   ...     name="example::linked_service",
   ...     version="1.0.0",
   ...     settings=SftpLinkedServiceSettings(
   ...         host="sftp.example.com",
   ...         username="user",
   ...         password="password123",
   ...         private_key=None,
   ...         passphrase=None,
   ...         timeout=30.0,
   ...         host_key_fingerprint="AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdEf==",
   ...         host_key_validation=True,
   ...         port=22,
   ...     ),
   ... )
   >>> linked_service.connect()



Attributes
----------

.. autoapisummary::

   ds_protocol_sftp_py_lib.linked_service.sftp.SftpLinkedServiceSettingsType


Classes
-------

.. autoapisummary::

   ds_protocol_sftp_py_lib.linked_service.sftp.SftpLinkedServiceSettings
   ds_protocol_sftp_py_lib.linked_service.sftp.SftpLinkedService


Module Contents
---------------

.. py:class:: SftpLinkedServiceSettings

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedServiceSettings`


   Settings for SFTP Linked Service connections.

   .. attribute:: host

      SFTP server hostname.

      :type: str

   .. attribute:: username

      Username for authentication.

      :type: str

   .. attribute:: password

      Password for authentication.

      :type: str | None

   .. attribute:: private_key

      Private key for authentication.

      :type: str | None

   .. attribute:: passphrase

      Passphrase for private key.

      :type: str | None

   .. attribute:: timeout

      Connection timeout in seconds.

      :type: float | None

   .. attribute:: host_key_fingerprint

      Expected host key fingerprint.

      :type: str | None

   .. attribute:: host_key_validation

      Whether to validate host key.

      :type: bool

   .. attribute:: port

      SFTP server port.

      :type: int


   .. py:attribute:: host
      :type:  str

      Hostname or IP address of the SFTP server.


   .. py:attribute:: username
      :type:  str

      Username for authentication.


   .. py:attribute:: password
      :type:  str | None
      :value: None


      Password for authentication.


   .. py:attribute:: private_key
      :type:  str | None
      :value: None


      Private key for authentication.


   .. py:attribute:: passphrase
      :type:  str | None
      :value: None


      Passphrase for private key.


   .. py:attribute:: timeout
      :type:  float | None
      :value: None


      Connection timeout in seconds.


   .. py:attribute:: host_key_fingerprint
      :type:  str | None
      :value: None


      Expected host key fingerprint (base64-encoded MD5, as produced by
      Paramiko's get_fingerprint(); e.g., 'AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcdEf==').


   .. py:attribute:: host_key_validation
      :type:  bool
      :value: True


      Whether to validate host key.


   .. py:attribute:: port
      :type:  int
      :value: 22


      SFTP server port.


.. py:data:: SftpLinkedServiceSettingsType

.. py:class:: SftpLinkedService

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedService`\ [\ :py:obj:`SftpLinkedServiceSettingsType`\ ], :py:obj:`Generic`\ [\ :py:obj:`SftpLinkedServiceSettingsType`\ ]


   SFTP Linked Service implementation.

   .. attribute:: settings

      Linked service settings.

      :type: SftpLinkedServiceSettingsType

   .. attribute:: _connection

      Underlying SFTP client connection.

      :type: SFTPClient | None

   .. attribute:: _sftp

      Sftp provider instance.

      :type: Sftp | None


   .. py:attribute:: settings
      :type:  SftpLinkedServiceSettingsType


   .. py:attribute:: _sftp
      :type:  ds_protocol_sftp_py_lib.utils.sftp.provider.Sftp | None
      :value: None



   .. py:property:: type
      :type: ds_protocol_sftp_py_lib.enums.ResourceType


      Get the type of linked service.

      :returns: The type of the linked service.
      :rtype: ResourceType


   .. py:property:: connection
      :type: ds_protocol_sftp_py_lib.utils.sftp.provider.Sftp


      Get the SFTP client connection.

      :returns: The active SFTP client connection.
      :rtype: Sftp

      :raises ConnectionError: If the connection is not initialized.


   .. py:method:: _init_sftp() -> ds_protocol_sftp_py_lib.utils.sftp.provider.Sftp

      Initialize the Sftp client.

      :returns: An initialized Sftp provider instance.
      :rtype: Sftp



   .. py:method:: connect() -> None

      Initialize the Sftp client instance if not already initialized.

      :raises ConnectionError: If connection fails.
      :raises AuthenticationError: If authentication fails.



   .. py:method:: test_connection() -> tuple[bool, str]

      Perform a lightweight health check against the SFTP backend.

      Uses the SFTP client's listdir method to check connectivity and authentication.

      :returns:     - (True, message) if successful.
                    - (False, error message) otherwise.
      :rtype: tuple[bool, str]



   .. py:method:: close() -> None

      Close the linked service.

      Sets the _sftp attribute to None to indicate the connection is closed.

      :raises ConnectionError: If closing the SFTP connection fails.