spurplus 2.3.5

Spur+

Spur+是一个用于管理远程机器并在SSH上执行文件操作的库。

它建立在Spur和Paramiko库的基础上。虽然我们发现在Spur和Paramiko中已经找到了大多数功能，但我们发现某些功能缺失

• 类型。由于Spur支持Python 2和3，它不提供任何类型注解，这使得与mypy等类型检查器一起使用更加困难。

• pathlib.Path支持。我们发现使用pathlib.Path而不是纯字符串来操作路径更容易。Spur+提供对两者的支持。

• 创建目录的函数。spur依赖于sftp客户端。虽然从spur.SshShell获取sftp客户端并创建目录相对简单，但我们认为，鉴于这一功能被频繁使用，值得创建一个类似于pathlib.Path.mkdir()的包装函数。

• 一次性读取/写入文本和二进制数据。与创建目录类似，spur.SshShell.open()已经提供了读取/写入文件所需的所有功能。然而，我们发现将使用代码写在一行中并且不引入额外的文件描述符变量时，代码的阅读性会更好。

• 一个用于将文件从远程主机上传或下载到远程主机的函数。

• 一个用于将本地目录同步到远程目录的函数（类似于rsync）。

• 计算MD5校验和的函数。

• 检查文件是否存在的函数。

• 一个更详尽的环境管理器，用于临时目录，允许指定前缀、后缀和基本目录，并返回一个pathlib.Path对象。相比之下，spur.temporary_directory()只返回一个没有调节功能的字符串。

• 一个初始化函数，在连接失败时重复重连。我们发现，当你在云中启动一个虚拟实例并需要等待它初始化时，这个函数特别重要。

• 一个围绕paramiko的SFTP客户端的包装器（spurplus.sftp.ReconnectingSFTP），如果SFTP客户端遇到连接失败会自动重连。虽然原始的spur.SshShell.open()会在每次调用时创建一个新的SFTP客户端以防止超时问题，但spurplus.SshShell能够通过spurplus.sftp.ReconnectingSFTP在多次调用中重用SFTP客户端。

  这可以使速度提高高达10倍（参见tests/live_test.py中的基准测试）。

使用方法

import pathlib

import spurplus

# Re-try on connection failure; sftp client and the underlying spur SshShell
# are automatically closed when the shell is closed.
with spurplus.connect_with_retries(
        hostname='some-machine.example.com', username='devop') as shell:
    p = pathlib.Path('/some/directory')

    # Create a directory
    shell.mkdir(remote_path=p, parents=True, exist_ok=True)

    # Write a file
    shell.write_text(remote_path=p/'some-file', text='hello world!')

    # Read from a file
    text = shell.read_text(remote_path=p/'some-file')

    # Change the permissions
    shell.chmod(remote_path=p/'some-file', mode=0o444)

    # Sync a local directory to a remote.
    # Only differing files are uploaded,
    # files missing locally are deleted before the transfer and
    # the permissions are mirrored from the local.
    sync_to_remote(
        local_path="/some/local/directory",
        remote_path="/some/remote/directory",
        delete=spurplus.Delete.BEFORE,
        preserve_permissions = True)

    # Stat the file
    print("The stat of {}: {}".format(p/'some-file', shell.stat(p/'some-file')))

    # Use a wrapped SFTP client
    sftp = shell.as_sftp()
    # Do something with the SFTP
    for attr in sftp.listdir_attr(path=p.as_posix()):
        do_something(attr.filename, attr.st_size)

文档

文档可在readthedocs上找到。

安装

• 创建虚拟环境

python3 -m venv venv3

• 激活它

source venv3/bin/activate

• 使用pip安装spur+

pip3 install spurplus

开发

• 检出仓库。

• 在仓库根目录下创建虚拟环境

python3 -m venv venv3

• 激活虚拟环境

source venv3/bin/activate

• 安装开发依赖

pip3 install -e .[dev]

• 有一些需要运行SSH服务器的实时测试。测试参数通过环境变量传递

  • TEST_SSH_HOSTNAME（SSH服务器的主机名，默认为“127.0.0.1”）

  • TEST_SSH_PORT（可选，默认为22）

  • TEST_SSH_USERNAME（可选，使用paramiko的默认值）

  • TEST_SSH_PASSWORD（可选，如果没有指定，使用私钥文件）

  • TEST_SSH_PRIVATE_KEY_FILE（可选，如果没有指定，在预期位置查找私钥）

我们使用tox进行测试和打包分发。假设上述环境变量已经设置，虚拟环境已激活，开发依赖已安装，运行

tox

./precommit.py

./precommit.py  --overwrite

版本控制

我们遵循语义版本控制。版本X.Y.Z表示

• X是主版本（向下不兼容），

• Y是次要版本（向后兼容），并且

• Z是补丁版本（向后兼容的bug修复）。