操作¶
在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 版更改: 现在允许在
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
只是一个方便的包装使用内置的Pythonsubprocess
模块与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风格的通配符,如Pythonglob
模块所理解的(给予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 版更改: 现在允许在
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
参数。