Skip to main content

操作

在fabfiles和其他非核心代码中使用的函数，如run()/sudo()。

fabric.operations.get(*args, **kwargs)

从远程主机下载一个或多个文件。

get 返回一个包含所有下载的本地文件的绝对路径的迭代，如果 local_path 是一个StringIO对象，它将是空的（见下面关于使用StringIO的更多信息）。该对象还将展示包含任何未能下载的远程文件路径的 .failed 属性，以及等同于 not .failed 的 .succeeded 属性。

remote_path 是要下载的远程文件或目录路径，可能包含shell glob语法，例如。 "/var/log/apache2/*.log"，并且将用远程主目录替换波浪号。将相对于远程用户的主目录或由 cd 操纵的当前远程工作目录来考虑相对路径。如果远程路径指向一个目录，那个目录将被递归下载。

local_path 是下载的一个或多个文件将被存储的本地文件路径。如果是相对的，它将荣誉由 lcd 操纵的本地当前工作目录。它可以使用标准的基于Python基于内插的插值，具有以下变量：

  • host：env.host_string 的值，例如 myhostname 或 user@myhostname-222 （主机名和端口之间的冒号变成一个破折号，以最大化文件系统兼容性）

  • dirname：远程文件路径的目录部分，例如。在 src/projectname/utils.py 中的 src/projectname。

  • basename：远程文件路径的文件名部分，例如。在 src/projectname/utils.py 中的 utils.py

  • path：完整的远程路径，例如。 src/projectname/utils.py。

虽然SFTP协议（get 使用）没有直接从连接用户所不具有的位置下载文件的能力，但您可以指定 use_sudo=True 来解决此问题。设置时，此设置允许 get 将远程文件复制（使用sudo）到远程终端上的临时位置（默认为远程用户的 $HOME；这可以通过 temp_dir 覆盖），然后将它们下载到 local_path。

注解

当 remote_path 是绝对目录路径时，只有内部目录将在本地重新创建并传递到上述变量中。因此，例如，get('/var/log', '%(path)s') 将在本地工作目录中开始写出像 apache2/access.log，postgresql/8.4/postgresql.log 等等的文件。它会 不 写出 var/log/apache2/access.log。

此外，当下载单个文件时，%(dirname)s 和 %(path)s 没有那么有意义，并且将分别为空和等效于 %(basename)s。因此，像 get('/var/log/apache2/access.log', '%(path)s') 这样的调用将保存一个名为 access.log 的本地文件，而不是 var/log/apache2/access.log。

此行为旨在与命令行 scp 程序一致。

如果留空，则 local_path 默认为 "%(host)s/%(path)s"，以便对多主机调用安全。

警告

如果您的 local_path 参数不包含 %(host)s，并且您的 get 调用针对多个主机运行，则您的本地文件将在每次连续运行时被覆盖！

如果 local_path 不使用上述变量（即如果它是一个简单的，明确的文件路径），它将类似于 scp 或 cp，如果必要的话覆盖预先存在的文件，如果给定的话下载到目录中（例如 get('/path/to/remote_file.txt', 'local_directory') 将创建 local_directory/remote_file.txt）等。

local_path 可以替代地是文件状对象，诸如 open('path', 'w') 或 StringIO 实例的结果。

注解

试图将目录 get 转换为类似文件的对象是无效的，并且将导致错误。

注解

这个函数将使用 seek 和 tell 来覆盖文件状对象的整个内容，以便与 put （也考虑整个文件）的行为一致。然而，与 put 不同，文件指针将不会被恢复到其先前的位置，因为这在这里没有多大意义和/或甚至不可能。

注解

如果类文件对象（如StringIO）具有 name 属性，将用于Fabric的打印输出，而不是默认的 <file obj>

在 1.0 版更改: 现在荣誉由 cd 操纵的远程工作目录，以及由 lcd 操纵的本地工作目录。

在 1.0 版更改: 现在允许在 local_path 参数中的类文件对象。

在 1.0 版更改: local_path 现在可以包含内插的路径和主机相关变量。

在 1.0 版更改: 目录可以在 remote_path 参数中指定，并且将触发递归下载。

在 1.0 版更改: 返回值现在是下载的本地文件路径的迭代，其也展示 .failed 和 .succeeded 属性。

在 1.5 版更改: 对文件类对象允许 name 属性用于日志输出

fabric.operations.local(command, capture=False, shell=None)

在本地系统上运行命令。

local 只是一个方便的包装使用内置的Python subprocess 模块与 shell=True 激活。如果您需要做任何特殊的事情，请考虑直接使用 subprocess 模块。

shell 直接传递给 subprocess.Popen 的 execute 参数（这决定了要使用的本地shell）。根据链接文档，在Unix上，默认行为是使用 /bin/sh，因此该选项对于将该值设置为例如。 /bin/bash。

local 当前不能够同时打印和捕获输出，因为 run/sudo。capture kwarg允许您根据需要在打印和捕获之间切换，默认为 False。

当 capture=False 时，本地子进程的stdout和stderr流直接连接到您的终端，虽然您可以使用全局 输出控制 output.stdout 和 output.stderr 隐藏一个或两个，如果需要。在此模式下，返回值的stdout/stderr值始终为空。

当 capture=True 时，您将看不到终端中子进程的任何输出，但返回值将包含捕获的stdout/stderr。

在任一情况下，与 run 和 sudo 一样，该返回值表现为 return_code，stderr，failed，succeeded，command 和 real_command 属性。有关详细信息，请参阅 run。

local 将尊重 lcd 上下文管理器，允许您独立于远程端（其尊重 cd）控制其当前工作目录。

在 1.0 版更改: 添加了 succeeded 和 stderr 属性。

在 1.0 版更改: 现在荣誉 lcd 上下文管理器。

在 1.0 版更改: 将 capture 的默认值从 True 更改为 False。

1.9 新版功能: 返回值属性为 .command 和 .real_command。

fabric.operations.open_shell(*args, **kwargs)

在远程端调用一个完全交互式的shell。

如果给出 command，则在将控制交给调用用户之前，它将在管道之下发送。

当需要与基于shell的命令或一系列命令进行交互时，例如在调试时或在远程程序失败时需要完全交互式恢复时，此函数最有用。

应该考虑将一个交互式shell会话工作在Fabric脚本中间的一种简单方法，而 not 是 run 的一个替代，它也能够与远程端交互（虽然只有在其给定命令执行时），并具有更强大的程序性能力，如错误处理和stdout/stderr捕获。

具体来说，open_shell 提供比 run 更好的交互式体验，但使用完整的远程shell防止Fabric确定在shell中运行的程序是否失败，并且使用shell输出（例如登录横幅，提示和回显stdin）污染stdout/stderr流。

因此，此函数没有返回值，如果任何远程程序导致错误，则不会触发Fabric的故障处理。

1.0 新版功能.

fabric.operations.prompt(text, key=None, default='', validate=None)

使用 text 提示用户并返回输入（如 raw_input）。

为方便起见，将附加一个空格字符，但没有其他。因此，您可能需要使用问号或冒号结束提示文本，例如 prompt("What hostname?")。

如果给出 key，除了由 prompt 返回之外，用户的输入将被存储为 env.<key>。如果密钥已经存在于 env 中，则其值将被覆盖，并向用户打印警告。

如果给出 default，则它显示在方括号中，并且如果用户不输入任何内容（即，不输入任何文本就按Enter键）。 default 默认为空字符串。如果非空，将附加一个空格，以便诸如 prompt("What hostname?", default="foo") 的调用将导致 What hostname? [foo] 的提示（在 [foo] 之后具有尾部空格）。

可选的关键字参数 validate 可以是可调用的或字符串：

  • 如果是可调用的，则使用用户的输入来调用它，并且应该返回成功存储的值。失败时，它应该引发一个异常消息，它将打印给用户。

  • 如果是字符串，则传递给 validate 的值将用作正则表达式。因此，在这种情况下建议使用原始字符串。请注意，正则表达式，如果不完全匹配（由 ^ 和 $ 限制），它将会这样。换句话说，输入必须完全匹配正则表达式。

无论哪种方式，prompt 将重新提示，直到验证通过（或用户命中 Ctrl-C）。

注解

prompt 荣誉 env.abort_on_prompts，并将调用 abort 而不是提示是否该标志设置为 True。如果你想阻止用户输入，不管，尝试用 settings 包装。

例子:

# Simplest form:
environment = prompt('Please specify target environment: ')

# With default, and storing as env.dish:
prompt('Specify favorite dish: ', 'dish', default='spam & eggs')

# With validation, i.e. requiring integer input:
prompt('Please specify process nice level: ', key='nice', validate=int)

# With validation against a regular expression:
release = prompt('Please supply a release name',
        validate=r'^\w+-\d+(\.\d+)?$')

# Prompt regardless of the global abort-on-prompts setting:
with settings(abort_on_prompts=False):
    prompt('I seriously need an answer on this! ')
fabric.operations.put(*args, **kwargs)

将一个或多个文件上传到远程主机。

put 返回一个包含所有上传的远程文件的绝对文件路径的迭代。这个迭代也展示了一个 .failed 属性，包含任何无法上传的本地文件路径（因此可能被用作一个布尔测试）。你也可以检查 .succeeded 等效于 not .failed。

local_path 可以是相对或绝对的本地文件或目录路径，并且可以包含shell风格的通配符，如Python glob 模块所理解的（给予 use_glob=False 禁用此行为）。还执行波形扩展（由 os.path.expanduser 实现）。

local_path 可以替代地是文件状对象，诸如 open('path') 或 StringIO 实例的结果。

注解

在这种情况下，put 将尝试通过使用 seek （并将使用 tell 保留以前的文件位置）后退它来读取文件状对象的整个内容。

remote_path 也可以是相对或绝对位置，但应用于远程主机。相对路径是相对于远程用户的主目录，但是如果需要，也将执行波纹扩展（例如 ~/.ssh/）。

在任一path参数中的空字符串将被相应的结束的当前工作目录替换。

虽然SFTP协议（put 使用）不能直接将文件上传到非连接用户所有的位置，但您可以指定 use_sudo=True 来解决此问题。设置时，此设置会导致 put 将本地文件上传到远程终端上的临时位置（默认为远程用户的 $HOME；这可以通过 temp_dir 覆盖），然后使用 sudo 将其移动到 remote_path。

在一些使用情况下，希望强制新上传的文件与其本地对应方的模式匹配（例如当上载可执行脚本时）。为此，请指定 mirror_local_mode=True。

或者，您可以使用 mode kwarg指定与 os.chmod 相同的精确模式，例如精确八进制数（0755）或表示一个（"0755"）的字符串。

put 将荣誉 cd，因此 remote_path 中的相对值将由当前远程工作目录（如果适用）加在前面。因此，例如，以下片段将尝试上传到 /tmp/files/test.txt 而不是 ~/files/test.txt:

with cd('/tmp'):
    put('/path/to/local/test.txt', 'files')

使用 lcd 将以相同的方式影响 local_path。

例子:

put('bin/project.zip', '/tmp/project.zip')
put('*.py', 'cgi-bin/')
put('index.html', 'index.html', mode=0755)

注解

如果类文件对象（如StringIO）具有 name 属性，将用于Fabric的打印输出，而不是默认的 <file obj>

在 1.0 版更改: 现在荣誉由 cd 操纵的远程工作目录，以及由 lcd 操纵的本地工作目录。

在 1.0 版更改: 现在允许在 local_path 参数中的类文件对象。

在 1.0 版更改: 目录可以在 local_path 参数中指定，并且将触发递归上传。

在 1.0 版更改: 返回值现在是上传的远程文件路径的迭代，它也显示 .failed 和 .succeeded 属性。

在 1.5 版更改: 对文件类对象允许 name 属性用于日志输出

在 1.7 版更改: 添加了允许禁用globbing的 use_glob 选项。

fabric.operations.reboot(*args, **kwargs)

重新启动远程系统。

将临时调整Fabric的重新连接设置（timeout 和 connection_attempts），以确保重新连接不会放弃至少 wait 秒。

注解

从Fabric 1.4开始，通过会话重新连接中途的能力不再需要使用内部API。虽然我们不正式弃用此功能，但添加更多功能不会是优先级。

鼓励想要更好控制的用户检查这个函数（6行长，良好注释）源代码，并使用不同的超时/尝试值或附加逻辑写入自己的适配。

0.9.2 新版功能.

在 1.4 版更改: 将 wait kwarg更改为可选，并重构以利用新的重新连接功能；它可能实际上不必等待 wait 秒，然后重新连接。

fabric.operations.require(*keys, **kwargs)

检查共享环境中的给定密钥dict，如果找不到，则中止。

位置参数应该是表示应该检查env vars的字符串。如果任何给定的参数不存在，Fabric将中止执行并打印缺少的键的名称。

可选的关键字参数 used_for 可以是一个字符串，它将被打印在错误输出中，以通知用户为什么此要求已到位。 used_for 作为类似的字符串的一部分打印:

"Th(is|ese) variable(s) (are|is) used for %s"

因此格式化它。

可选的关键字参数 provided_by 可以是用户为了设置一个或多个键而应该能够执行的功能或功能名称或单个功能或功能名称的列表；如果不满足要求，它将包含在错误输出中。

注意：假设关键字参数适用于所有给定的键作为一个组。如果你觉得需要指定多个 used_for，例如，你应该将你的逻辑分成多个调用 require()。

在 1.1 版更改: 允许可迭代的 provided_by 值，而不只是单个值。

fabric.operations.run(*args, **kwargs)

在远程主机上运行shell命令。

如果 shell 为True（默认值），run 将通过shell解释器执行给定的命令字符串，其值可以通过设置 env.shell （默认为类似于 /bin/bash -l -c "<command>" 的东西）来控制。任何双引号（"）当 shell 为True时，command 中的符号（$）字符将自动转义。

run 将把远程程序的stdout的结果作为单个（可能是多行）字符串返回。此字符串将显示 failed 和 succeeded 布尔属性，指定命令是失败还是成功，并且还将返回代码作为 return_code 属性。此外，它包括所请求的和实际的命令串的副本，分别作为 .command 和 .real_command。

在本地终端中输入的任何文本将在运行时转发到远程程序，从而允许您自然地与密码或其他提示进行交互。有关如何工作的更多信息，请参阅 与远程程序的交互。

您可以通过 pty=False 来放弃在远程端上创建伪终端，以防存在的终端导致问题的命令出现问题。但是，这将强制Fabric本身回显在命令运行时输入的任何和所有输入，包括敏感密码。 （使用 pty=True，远程伪终端将为您响应，并将智能地处理密码风格的提示。）有关详细信息，请参阅 伪终端。

同样，如果您需要以编程方式检查远程程序的stderr流（在此函数的返回值上显示为 stderr 属性），则可以设置 combine_stderr=False。这样做会导致在终端上出现乱码输出的可能性很大（尽管 run 返回的字符串会被正确分离）。更多信息，请阅读 结合stdout和stderr。

要忽略非零返回码，请指定 warn_only=True。要同时忽略非零返回码，and 强制命令以静默方式运行，请指定 quiet=True。

要覆盖用于显示远程stdout和/或stderr的本地流，请指定 stdout 或 stderr。 （默认情况下，使用常规 sys.stdout 和 sys.stderr Python流对象。）

例如，run("command", stderr=sys.stdout) 将打印远程标准错误到本地标准输出，同时保留它作为它自己的返回值的不同属性（如上所述）。或者，您甚至可以提供您自己的流对象或记录器，例如。 myout = StringIO(); run("command", stdout=myout)。

如果希望在远程程序运行时间过长时引发异常，请指定 timeout=N，其中 N 是秒数的整数，之后超时。这将导致 run 引发 CommandTimeout 异常。

如果要禁用Fabric自动尝试转义引号，美元符号等，请指定 shell_escape=False。

例子:

run("ls /var/www/")
run("ls /home/myuser", shell=False)
output = run('ls /var/www/site1')
run("take_a_long_time", timeout=5)

1.0 新版功能: succeeded 和 stderr 返回值属性，combine_stderr kwarg和交互行为。

在 1.0 版更改: pty 的默认值现在是 True。

在 1.0.2 版更改: combine_stderr 的默认值现在是 None，而不是 True。然而，默认 behavior 不变，因为全局设置仍然是 True。

1.5 新版功能: quiet，warn_only，stdout 和 stderr kwargs。

1.5 新版功能: 返回值属性为 .command 和 .real_command。

1.6 新版功能: timeout 参数。

1.7 新版功能: shell_escape 参数。

fabric.operations.sudo(*args, **kwargs)

在远程主机上运行shell命令，具有超级用户权限。

sudo 在任何方面都与 run 相同，除了它将总是在调用 sudo 程序时包装给定的 command 以提供超级用户权限。

sudo 接受附加的 user 和 group 参数，这些参数传递给 sudo，并允许您作为root以外的某些用户和/或组运行。在大多数系统上，sudo 程序可以接受字符串username/group或整数userid/groupid（uid/gid）； user 和 group 同样可以是字符串或整数。

如果希望多个 sudo 调用具有相同的 user 值，您可以在模块级别或通过 settings 设置 env.sudo_user。一个明确的 user 参数当然会覆盖这个全局设置。

例子:

sudo("~/install_script.py")
sudo("mkdir /var/www/new_docroot", user="www-data")
sudo("ls /home/jdoe", user=1001)
result = sudo("ls /tmp/")
with settings(sudo_user='mysql'):
    sudo("whoami") # prints 'mysql'

在 1.0 版更改: 查看更改和添加的注释 run。

在 1.5 版更改: 现在荣誉 env.sudo_user。

1.5 新版功能: quiet，warn_only，stdout 和 stderr kwargs。

1.5 新版功能: 返回值属性为 .command 和 .real_command。

1.7 新版功能: shell_escape 参数。