scrippy_remote

SSH/SFTP, FTP/FTPS and CIFS client for the Scrippy framework.

Prerequisites

• Python >= 3.11
• The following modules, automatically installed:
  • paramiko
  • pysmb

Installation

With pip

pip install scrippy-remote

From source

git clone https://codeberg.org/scrippy/scrippy-remote.git
cd scrippy-remote
make install

Usage

scrippy_remote provides one class per protocol:

Each class is used as a context manager: the connection is opened when entering the with block and closed when leaving it.

The three classes share the same methods:

In addition, Ssh provides exec() to execute commands, and Cifs provides open() to read or write a remote file.

Example: copy a file from a FTP server to a SSH server, the local host acting as a buffer:

from scrippy_remote.ftp import Ftp
from scrippy_remote.ssh import Ssh

with Ftp(host="ftp.flying.circus",
         username="luiggi.vercotti",
         password="dead_parrot") as ftp:
  ftp.get_file(remote_file="sketches/parrot.txt",
               local_dir="/tmp")

with Ssh(username="luiggi.vercotti",
         host="srv.flying.circus",
         key="/home/luiggi.vercotti/.ssh/id_rsa") as ssh:
  ssh.put_file(local_file="/tmp/parrot.txt",
               remote_dir="/home/luiggi.vercotti/sketches",
               create_dirs=True)
  ssh.exec(command="chmod 640 /home/luiggi.vercotti/sketches/parrot.txt")

Error handling

All errors raise a scrippy_remote.ScrippyRemoteError. Its message starts with the error category, e.g. [SshTransferError]. The categories are listed in each protocol documentation.

Most methods accept an exit_on_error argument (default: True). When set to False, errors are only logged as warnings and the method goes on (e.g. a mirror skips the faulty file). Connection and argument errors are always raised.

from scrippy_remote import ScrippyRemoteError, logger
from scrippy_remote.ssh import Ssh

try:
  with Ssh(username="luiggi.vercotti",
           host="srv.flying.circus",
           key="/home/luiggi.vercotti/.ssh/id_rsa") as ssh:
    ssh.delete_remote_dir(remote_dir="/home/luiggi.vercotti/dead", recursive=True)
except ScrippyRemoteError as err:
  logger.critical(f"{err}")

Documentation

• SSH/SFTP operations:
  • connection
  • errors
  • command execution
  • file transfers
  • mirrors
  • remote directories
• FTP operations:
  • connection
  • errors
  • file transfers
  • mirrors
  • remote directories
• CIFS operations:
  • connection
  • errors
  • file transfers
  • mirrors
  • remote directories
  • remote files
• Local operations:
  • listing
  • creation
  • deletion

The docstrings in the source code remain the reference documentation. make doc generates the class and package diagrams (classes_scrippy-remote.svg, packages_scrippy-remote.svg).

Tests

The tests need the test servers (SSH, FTP and Samba) provided as containers in tests/container:

make -C tests/container build run
python3 -m pip install .[dev]
make tests

The tests reach the servers through the sshd, vsftpd and samba host names, which must be resolvable (e.g. run the tests from a container attached to the container_default network).