文件和目录管理

提供远程文件和文件夹操作 API 的简单模块。

fabric.contrib.files.append(filename, text, use_sudo=False, partial=False, escape=True, shell=False)

添加字符串（列表） text 至 filename 。

如果提供的是一个 list，其中的每一个字符串都将将会（按顺序）独立处理。

如果 filename 中已存在 text，将不会执行添加并立刻返回 None，反之则将给定 text 添加到 filename 的末尾，比如 echo '$text' >> $filename。

用于测试 text 是否已经存在，默认是整行匹配，例如： ^<text>$。因为在“向文件的结尾增添一行”的使用情况下，这是最合适的选择。你可以指定 partial=True 来覆盖它，并强制部分搜索（比如 ^<text>）。

由于 text 是包裹在单引号中的，因此会自动将其中的单引号使用反斜线转译，可以使用 escape=False 关闭该选项。

如果 use_sudo 设置为 True，则使用 sudo 而不是 run。

shell 参数最终会传递给 run/sudo ，具体描述和 ~fabric.contrib.sed 一样，请查看它的文档详细了解。

在 0.9.1 版更改: 新增关键字参数 partial。

在 1.0 版更改: 修改了 filename 和 text 参数的顺序与模块中的其它函数保持一致。

在 1.0 版更改: 修改关键字参数 partial 的默认值为 False。

在 1.4 版更改: 更新了转译相关的正则表达式以修复众多边界情况下的问题。

1.6 新版功能: 新增关键字参数 shell。

fabric.contrib.files.comment(filename, regex, use_sudo=False, char='#', backup='.bak', shell=False)

将 filename 文件中所有匹配 regex 的行全部注释掉。

默认的注释字符是 # ，可以使用 char 参数覆盖这项设置。

这个函数调用了 sed 函数，因此和 sed 一样接受 use_sudo、shell 和 backup 等关键字参数。

comment 会在行首添加注释符号，函数的结果大概会是这个样子的：

this line is uncommented
#this line is commented
#   this line is indented and commented

换句话说，注释操作并不“遵循”手写代码时的缩进规范，注释符后面也不会跟上空白，除非手动指定，比如： char='# '。

注解

为了保护被注释的代码，这个函数会将 regex 参数包裹在园括号中，并不需要你手动处理。同时会确保开始的 ^ 以及结尾的 $ 字符会被移除在括号之外。例如：调用 comment(filename, r'^foo$') 会产生一个 “before” 参数为 r'^(foo)$'``（"after" 参数为 ``r'#\1'）的 sed 调用。

1.5 新版功能: 新增关键字参数 shell。

fabric.contrib.files.contains(filename, text, exact=False, use_sudo=False, escape=True, shell=False)

如果 filename 文件中包含 text （可能是正则表达式）则返回 True。

默认情况下，这个函数会对代码行进行部分匹配（例如 text 只包含在某一行文字中的情况），指定 exact=True 可以确保只有某一行完全匹配 text 才会返回 True。

这个函数会影响远程 egrep 的行为（可能无法弯曲符合 Python 正则表达式语法），默认情况下还会忽略 env.shell 的封装。

如果 use_sudo 设置为 True，则使用 sudo 而不是 run。

如果 escape 设置为 False，则不会进行任何正则表达式相关的转译（会覆盖 exact 自动添加 ^/$ 的行为）。

shell 参数最终会传递给 run/sudo ，具体描述和 ~fabric.contrib.sed 一样，请查看它的文档详细了解。

在 1.0 版更改: 修改了 filename 和 text 参数的顺序与模块中的其它函数保持一致。

在 1.4 版更改: 更新了转译相关的正则表达式以修复众多边界情况下的问题。

在 1.4 版更改: 新增关键字参数 escape。

1.6 新版功能: 新增关键字参数 shell。

fabric.contrib.files.exists(path, use_sudo=False, verbose=False)

如果当前远程主机中存在给定的目录则返回 True。

如果 use_sudo 设置为 True，则使用 sudo 而不是 run。

默认情况下， exists 会隐藏所有输出（包括 run 那一行、stdout、stderr 以及文件不存在引起的的任何警告）以避免混乱的输出。设置 verbose=True 可以修改其行为。

fabric.contrib.files.first(*args, **kwargs)

返回给定路径中第一个找到文件的那个，如果都找不到则返回 None。use_sudo 和 verbose 参数将会传递给 exists。

如果当前远程主机中给定路径是一个软链接则返回 True。

如果 use_sudo 值为真则使用 sudo 而非 run。

默认情况下，is_link 会隐藏所有输出，设置 verbose=True 可以修改该设置。

fabric.contrib.files.sed(filename, before, after, limit='', use_sudo=False, backup='.bak', flags='', shell=False)

使用给定正则表达式对 filename 做搜索及替换操作。

和 sed -i<backup> -r -e "/<limit>/ s/<before>/<after>/<flags>g" <filename> 等价。设置 backup 为空字符串可以阻止备份文件的生成。

方便起见，before 和 after 将会自动转译斜线、单引号和圆括号，这样你就可以不必把 http://foo\.com 写成 http:\/\/foo\.com。

如果 use_sudo 设置为 True，则使用 sudo 而不是 run。

shell 参数最终会传递给 run/sudo。其默认值为 False，这样就不会造成很多引号和反斜线相互嵌套的问题。不过，设置为 True 在使用 ~fabric.operations.cd 隐式或显式地包裹 sudo 调用时会很方便。（cd 本质上是基于 shell 的，而非独立的命令，因此需要在 shell 中调用。）

其它选项可能是出于兼容 sed 标记的目的 – 例如：设置 flags="i" 可以插入式地搜索和替换。标记 g 意味着不停止执行，so you do not need to remember to include it when overriding this parameter.

1.1 新版功能: flags 参数。

1.6 新版功能: 新增关键字参数 shell。

fabric.contrib.files.uncomment(filename, regex, use_sudo=False, char='#', backup='.bak', shell=False)

将文件 filename 中匹配 regex 的所有行取消注释。

默认注释界定符是 #，可以使用 char 参数覆盖该设置。

这个函数调用了 sed 函数，因此和 sed 一样接受 use_sudo、shell 和 backup 等关键字参数。

uncomment 会删除紧跟在注释字符后面的空格，如果存在的话，并不会影响其之前的空格，例如： # foo 会变成 foo （空格被一起删去了），不过 `` # foo`` 会变成 `` foo`` （只删除了注释字符后的空格，前面的 4 个空格并没有）。

在 1.6 版更改: 新增关键字参数 shell。

fabric.contrib.files.upload_template(filename, destination, context=None, use_jinja=False, template_dir=None, use_sudo=False, backup=True, mirror_local_mode=False, mode=None, pty=None)

渲染一个模版文本文件，并将结果上传至远程主机。

返回内部 put 调用的结果，详细信息请访问其文档。

filename 应当是一个文本文件的地址，可以包含 Python 插入格式 ，并结合上下文字典 context 来渲染（如果存在的话）。

如果 use_jinja 被设置为 True，同时你已经安装了 Jinja2 模板库，将会使用 Jinja 来渲染该模板。默认会从用户的运行目录寻找模板，除非指定了 template_dir。

生成的文件将会上传至远程路径 destination。如果已有同名文件存在在远程，远程文件将会以 .bak 后缀重命名，除非指定 backup=False。

默认情况下，将会以登录用户身份复制到 destination 目录，指定 use_sudo=True 可以强制使用 sudo 复制。

关键字参数 mirror_local_mode 和 mode 直接用于内部 put 的调用，详细操作请参阅其文档。

关键字参数 pty 将会被应用到所有 run/sudo 内部调用，例如用于文件路径测试、设置备份等等。

在 1.1 版更改: 新增关键字参数 backup、mirror_local_mode 以及 mode。

在 1.9 版更改: 新增 pty 关键字参数。