Python SCP Client

Warnings

• gotcha The `scp` library is a thin wrapper around `paramiko`. Therefore, `paramiko` and its dependencies (like `cryptography`, which might require compilation tools) must be correctly installed. Issues with `paramiko` often manifest as `scp` problems.
  Fix: Ensure `paramiko` is installed (`pip install paramiko`) and resolve any underlying `cryptography` installation errors, which might require system-level development packages.
• gotcha For security, always verify host keys. Using `paramiko.AutoAddPolicy()` in production is dangerous as it makes your client vulnerable to man-in-the-middle attacks.
  Fix: Prefer `ssh.load_system_host_keys()` or manually add host keys to a `paramiko.HostKeys` object. Implement strict host key checking and handle `paramiko.BadHostKeyException`.
• deprecated The underlying SCP1 protocol has known security limitations and is considered deprecated by OpenSSH in favor of SFTP. While `scp.py` implements SCP1, be aware that future changes in OpenSSH servers might affect compatibility or expose vulnerabilities.
  Fix: For new projects or if advanced file transfer features are needed, consider using `paramiko`'s built-in SFTP client (`ssh.open_sftp()`) or higher-level libraries like `Fabric` that might use SFTP.
• breaking The `progress` callback signature changed in version 0.13.0. It reverted to accepting 3 arguments (`path`, `total_size`, `sent_size`). A new `progress4` parameter was introduced to accept 4 arguments, including `peername`. Code using the 4-argument `progress` callback from pre-0.13.0 versions will break.
  Fix: Update your progress callback functions to match the 3-argument signature for `progress`, or use the `progress4` parameter if you require the `peername` argument. Review the `CHANGELOG.md` for specific details.
• gotcha Prior to version 0.13.6, the `put()` method might have behaved unexpectedly when the source directory path had a trailing slash (e.g., `scp.put('my_dir/', remote_path)`).
  Fix: Upgrade to `scp` version 0.13.6 or newer. If upgrading is not possible, ensure source directory paths passed to `put()` do not have trailing slashes if you intend to copy the directory itself rather than its contents.

Install

• pip install scp Install `scp`
• pip install paramiko scp Install with core dependency

Imports

• SCPClient

  from scp import SCPClient

  This is the primary class for SCP file transfer operations.
• SSHClient

  from paramiko import SSHClient

  While part of `paramiko`, `SSHClient` is essential for establishing the underlying SSH connection that `SCPClient` uses.

Quickstart

This quickstart demonstrates how to establish an SSH connection using `paramiko.SSHClient` and then use `scp.SCPClient` to upload and download a file. It includes important considerations for host key policy and proper connection closure.

import os
from paramiko import SSHClient, AutoAddPolicy
from scp import SCPClient

# Configuration from environment variables for security
HOSTNAME = os.environ.get('SCP_HOSTNAME', 'your_remote_host')
USERNAME = os.environ.get('SCP_USERNAME', 'your_username')
PASSWORD = os.environ.get('SCP_PASSWORD', '') # Use SSH keys in production

local_file = 'local_test_file.txt'
remote_path = '/tmp/remote_test_file.txt'

# Create a dummy local file for the example
with open(local_file, 'w') as f:
    f.write('Hello from scp.py!')

ssh = SSHClient()
# Set policy to auto-add host keys for demo. In production, use ssh.load_system_host_keys() or HostKeys().add().
ssh.set_missing_host_key_policy(AutoAddPolicy()) 

try:
    # Connect to the remote server
    ssh.connect(hostname=HOSTNAME, username=USERNAME, password=PASSWORD, port=22)
    print(f"Connected to {HOSTNAME}")

    # SCPCLient takes a paramiko transport as an argument
    with SCPClient(ssh.get_transport()) as scp:
        # Upload a file
        scp.put(local_file, remote_path)
        print(f"Uploaded '{local_file}' to '{remote_path}'")

        # Download the file back to verify
        downloaded_file = 'downloaded_test_file.txt'
        scp.get(remote_path, downloaded_file)
        print(f"Downloaded '{remote_path}' to '{downloaded_file}'")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    ssh.close()
    print("SSH connection closed.")

# Clean up dummy files
import os
if os.path.exists(local_file):
    os.remove(local_file)
if os.path.exists(downloaded_file):
    os.remove(downloaded_file)