Typing stubs for pysftp

Common errors

• ImportError: cannot import name 'DSSKey' from 'paramiko'

  cause `pysftp` attempts to import `DSSKey` from `paramiko`, but this class was removed in `paramiko` version 4.0.0 and newer.
  fix Downgrade `paramiko` to a version older than 4.0.0 (e.g., `pip install 'paramiko<4.0.0'`).

• pysftp.exceptions.ConnectionException: ('your.sftp.host', 22)

  cause This usually indicates a failure to connect to the SFTP server. Common causes include incorrect hostname, wrong port (default is 22), firewall blocking the connection, or invalid credentials (username/password/private key).
  fix Verify the hostname and port. Check firewall rules. Confirm your SFTP credentials are correct. Try connecting manually with a client like FileZilla to isolate the issue. If using a private key, ensure the path is correct and permissions are set appropriately.

• UserWarning: Failed to load HostKeys from ~/.ssh/known_hosts. You will need to explicitly load HostKeys (cnopts.hostkeys.load(filename)) or disable HostKey checking (cnopts.hostkeys = None).

  cause pysftp cannot find or verify the host's key in your known_hosts file, which is a security measure to prevent man-in-the-middle attacks.
  fix For production, ensure the server's fingerprint is correctly added to your `known_hosts` file. For testing/development, you can bypass this by explicitly disabling host key checking: `cnopts = pysftp.CnOpts(); cnopts.hostkeys = None`. Pass `cnopts` to your `pysftp.Connection` constructor.

Warnings

• breaking `pysftp` is incompatible with `paramiko` versions 4.0.0 and above. Attempting to use `pysftp` with `paramiko>=4.0.0` will result in an `ImportError` due to `DSSKey` being removed from `paramiko`.
  Fix: Pin `paramiko` to `<4.0.0` in your project dependencies (e.g., `paramiko<4.0.0`). The `types-pysftp` package provides stubs for `pysftp==0.2.*`, which predates `paramiko`'s breaking change.
• gotcha By default, `pysftp` performs host key verification, which can lead to 'No hostkey for host X found' errors if the server's host key is not in `~/.ssh/known_hosts` or a specified `HostKeys` object.
  Fix: For production, ensure the server's host key is properly added to your `known_hosts` file. For development or testing, you can disable host key checking by setting `cnopts = pysftp.CnOpts(); cnopts.hostkeys = None` and passing `cnopts` to `pysftp.Connection`. This is not recommended for production due to security implications.
• deprecated The `pysftp` library itself appears to be largely unmaintained, with its last PyPI release (0.2.9) dating back to 2016. While `types-pysftp` (from typeshed) continues to be updated, the underlying `pysftp` library may not receive future bug fixes or security updates.
  Fix: Consider migrating to `paramiko` directly for more actively maintained SFTP functionality, especially for new projects or if advanced features/security updates are critical. `pysftp` is a wrapper around `paramiko` and `paramiko` is actively maintained.

Install

• pip install types-pysftp Install types-pysftp
• pip install pysftp Install pysftp (runtime dependency)

Imports

• Connection
  wrong:

  from pysftp import Connection

  correct:

  import pysftp
  conn = pysftp.Connection(...)

  While 'from pysftp import Connection' works, 'import pysftp' is the more common and recommended import pattern shown in pysftp's official documentation and examples.

Quickstart

This quickstart demonstrates how to establish an SFTP connection using pysftp, list remote directory contents, upload a file, and download a file. It uses environment variables for credentials and explicitly disables host key checking for simplicity, though this is not recommended for production environments. The Connection object is used as a context manager to ensure the SFTP session is properly closed.

import pysftp
import os

hostname = os.environ.get('SFTP_HOSTNAME', 'your.sftp.host')
username = os.environ.get('SFTP_USERNAME', 'your_username')
password = os.environ.get('SFTP_PASSWORD', '')
private_key_path = os.environ.get('SFTP_PRIVATE_KEY_PATH', None) # e.g., '~/.ssh/id_rsa'

# Recommended: configure known hosts for security
# For testing, host key checking can be disabled (NOT RECOMMENDED for production)
cnopts = pysftp.CnOpts()
cnopts.hostkeys = None # Disable host key checking for demonstration only

try:
    with pysftp.Connection(
        hostname, 
        username=username,
        password=password if not private_key_path else None,
        private_key=private_key_path,
        cnopts=cnopts
    ) as sftp:
        print(f"Connection successfully established with {hostname}.")
        # Example: List contents of the remote directory
        remote_path = '/'
        print(f"Listing contents of {remote_path}:")
        for entry in sftp.listdir(remote_path):
            print(f"- {entry}")

        # Example: Upload a file (create a dummy file first)
        local_file = 'test_upload.txt'
        with open(local_file, 'w') as f:
            f.write('Hello from types-pysftp!')
        remote_upload_path = f"/remote_{local_file}"
        sftp.put(local_file, remote_upload_path)
        print(f"Uploaded {local_file} to {remote_upload_path}.")
        os.remove(local_file)

        # Example: Download a file
        local_download_path = 'downloaded_file.txt'
        sftp.get(remote_upload_path, local_download_path)
        print(f"Downloaded {remote_upload_path} to {local_download_path}.")
        os.remove(local_download_path)

except pysftp.ConnectionException as e:
    print(f"SFTP Connection Error: {e}.")
    print("Ensure hostname, username, password/private key are correct and host keys are properly handled.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")