从1.x升级

现代结构（2+）代表了软件的几乎完全重新实现和重组。已经过去了 broken in two 清理，更明确，等等。在某些情况下，升级只需要基本搜索&replace；在其他情况下，需要做更多的工作。

如果您仔细阅读本文档，它将引导您朝正确的方向前进，直到您完全升级。如果您在Fabric 1中使用的任何功能未在此处列出，请提交一张罚单。 on Github 我们会尽快更新。

警告

从2.0释放线开始，织物2 not 与1.x！的100%功能对等！一些特性已经被显式地删除了，但其他特性还没有被移植，要么是由于时间限制，要么是因为所说的特性需要在现代环境中重新检查。

请查看以下信息，包括 升级详细信息 在提交错误报告之前，包含一个非常详细的列表的部分！

也看到 the roadmap 有关版本控制的其他说明。

为什么要升级？

我们不想以任何特定的顺序，呼吁对现代 Fabric 进行一些特定的改进，这可能会使升级值得您花时间。

注解

这些都列在医生的其他部分，所以如果你已经被卖了，就跳过那里。

• python 3兼容性（具体来说，我们现在支持2.7和3.4+）；

• 线程安全-不再要求多处理并发性；

• API重新组织 fabric.connection.Connection 对象而不是全局模块状态；

• 对命令行解析器进行了大修，以允许在每个任务的基础上使用常规的GNU/POSIX样式标志和选项（不再使用 fab mytask:weird=custom,arg=format ；

• 任务组织更加明确和灵活/具有更少的“魔力”；

• 任务可以声明其他任务始终在自己之前或之后运行；

• 配置大规模扩展，允许多个配置文件和格式、env vars、每个用户/项目/模块配置等；

• ssh配置文件加载在默认情况下是启用的，并且已经扩展了：系统/用户/运行时文件选择；

• shell命令执行API在本地和远程方法调用之间保持一致-不再区分 local 和 run （当然，除了运行命令的地方！）；

• shell命令更加灵活：交互行为、同时捕获和显示（现在适用于本地子进程，而不仅仅是远程进程）、编码控制和自动响应；

• 对ssh层使用paramiko的API会更加透明-例如 fabric.connection.Connection 允许控制给予的禁运 SSHClient.connect ；

• 网关/跨接主机功能提供 ProxyJump 样式“native”（无代理命令子进程）选项，可以无限嵌套；

要调用的“侧放”

我们链接到了上面关于这个的一个注释，但要明确：现代结构实际上是几个独立的库，并且任何与ssh或网络无关的东西 split out into the Invoke project .

这意味着，如果您是一组仅利用结构执行任务的用户，或者 local ，从未使用过 run ， put 或类似的 你不需要再使用布料本身了 并且可以简单地 改为调用“sidegrade” .

您仍然希望阅读此文档以了解情况的变化，但请注意，您可以避开 pip install invoke 不需要结构、参数、密码依赖性或其他任何东西。

从invoke中使用现代结构

我们打算增强现代织物，直到它包含织物1的大部分用例，这样您就可以使用 fab 而fabfiles本身并不太关心它是如何建立在invoke之上的。

然而，在这一点之前——对于中级到高级用户来说，这一点非常有用——事实上，现代结构的设计考虑到了库或直接的API使用。 在某些情况下，完全可以使用invoke来满足您的cli需求，并在invoke任务中将结构用作纯API。

换句话说，你可以避开 fab /除非你发现自己非常需要特别会议的便利设施，比如 --hosts 诸如此类。

同时运行两种结构版本

为了帮助逐步升级，现代织物可以安装在名称下 fabric2 （除了“正常”提供2.0+版本的 fabric ）并且可以与1.x版的安装共存。

因此，如果您有一个大的代码库，并且不想一次跳到现代版本，那么可以同时使用两种结构1 (fabric ，就像你以前安装的一样）和现代织物 fabric2 ）同时驻留在您的Python环境中。

注解

我们强烈建议您最终使用Fabric1将所有代码迁移到版本2或更高版本，以便您可以返回到 fabric 姓名。 fabric2 作为一个独特的包和模块，它的目的是要有一个权宜之计，而不会有任何 fabric3 或者更高（尤其是因为其中一些名字已经被取了！）

有关如何获取 fabric2 包的版本，请参见 安装现代 Fabric 组件 fabric2 .

升级详细信息

这是一份详尽的 all Fabric1.x功能以及1.x中没有的新to-invoke-or-Fabric-2功能；它指定是否需要升级，如果需要，如何升级，并跟踪尚未在现代版本中实现的功能。

大多数部分以表格形式分解，如下所示：

结构1特征或行为

状态，详见下文

迁移说明、迁移原理等

下面是“状态”列的典型值，尽管其中一些值有点松——请确保在所有情况下都阅读“注释”列！还请注意，事情并不是铁面无私的——例如，如果有足够多的用户请求，任何“删除的”项目都有返回的机会，或者如果使用案例表明解决方法不足。

• 端口 ：已可用，可能重命名或移动（经常移动到 Invoke 代码库）

• 悬而未决的 ：适合，但尚未移植，很适合补丁。 这些条目链接到相应的GitHub票据 -请不要做新的！

• 远离的 明确地 not 移植（不再符合视力，维护价值比太差等），不太可能恢复。

以下是用于导航的快速本地目录：

一般/概念

• 现代结构完全兼容python 3；作为一项成本，python 2.5支持（fabric 1的一个长期功能）已经被放弃了——事实上，我们已经放弃了对任何比python 2.7更老的支持。

• cli面向任务的工作流仍然是一个主要的设计目标，但是库用例不再是二级公民；相反，库功能是首先设计的，并且在其基础上构建了cli/task功能。

• 此外，在cli用例中，版本1过分强调了“lazy”交互式提示的身份验证机密，甚至连接参数，部分原因是缺乏强大的配置机制。随着时间的推移，很明显，这不值得折中使用混淆的非交互行为和困难的调试/测试过程。

  现代结构采用了一种可以说更干净的方法（基于随着时间推移添加到v1的功能），鼓励用户利用配置系统和/或在 开始 如果系统确定中途缺少信息，则会引发异常而不是提示。

• invoke的设计包括 explicit user-facing testing functionality ；如果您以前没有找到使用代码为结构编写测试的方法，那么现在应该更容易了。

  • 我们建议您尽早编写测试；它们将帮助您明确升级过程，并使过程更安全！

API组织

高级代码流和API成员关注点。

通过导入所有内容 fabric.api	远离的	所有有用的导入现在都可以在顶级级别使用，例如 from fabric import Connection .
全局配置连接参数（通过 env.host_string, env.host, env.port, env.user) and call global methods which implicitly reference them (run/sudo 等）	远离的	主API现在正确了oop:实例化 fabric.connection.Connection 对象并调用它们的方法。这些对象封装了所有连接状态（用户、主机、网关等），并拥有自己的ssh客户机实例。
强调将序列化的“主机字符串”作为设置用户、主机、端口等的方法	移植/移除	fabric.connection.Connection can accept a shorthand "host string"-like argument, but the primary API is now explicit user, host, port, etc keyword arguments. 此外，许多参数/设置等在v1中需要主机字符串，现在需要 fabric.connection.Connection 而是实例。
使用“角色”作为主机字符串的全局命名列表	端口	这个需求现在由 fabric.group.Group 对象（包含一些 fabric.connection.Connection 具有“对所有成员做一件事”方法的实例。）用户可以根据自己的需要创建和组织这些实例。 See the line items for --roles (cli参数、选项和行为), env.roles (fabric.env 参考) and @roles (任务功能和装饰) for the status of those specifics.

任务功能和装饰

注解

几乎所有与任务相关的功能都在invoke中实现；有关更多详细信息，请参见 execution 和 namespaces 文档。

默认情况下，任务从 fabfile.py 从用户当前的工作目录向上搜索文件系统根目录。	端口	这种行为在今天基本上是相同的，只做了一些小的修改和增强（例如对加载过程的更严格控制，以及实现自定义加载程序逻辑的API钩子——请参见 loading-collections ）
“经典”样式的隐式任务函数缺少 @task decorator	远离的	即使是在v1中，它们也在逐渐消失，现在通过invoke的 Task 和 Collection .
“新”风格 @task -装饰，模块级任务功能	端口	基本上是一样的，尽管现在超级大国- @task 仍然可以不带括号使用，但v1只有一个 task_class 参数invoke有许多不同的名称空间和解析器提示以及与执行相关的选项。
任意任务函数参数（即 def mytask(any, thing, at, all) ）	端口	这将获取自己的行项目，因为：任务现在必须 Context （普通调用）或 fabric.connection.Connection （结构）对象作为其第一个位置参数。与以前一样，函数签名的其余部分完全取决于用户，并将自动转换为CLI标志。 这就牺牲了v1的一小部分“快速DSL”，以换取更清晰、更易于理解/调试和更多用户可重写的API结构。 作为副作用，它减少了“功能模块”和“方法类”之间的区别；用户可以更容易地从“功能模块”开始，并在需求增长/变化时迁移到“方法类”。
通过导入爬行隐式生成任务树	移植/移除	名称空间构造现在更加明确；例如，在 fabfile.py 不再自动扫描并自动添加到任务树。 However, the root fabfile.py is automatically loaded (using Collection.from_module), preserving the simple/common case. See task-namespaces for details. 我们可以稍后恢复（以可选方式）导入的模块扫描，因为使用显式命名空间对象仍然允许用户控制结果树。
@hosts 和 @roles 用于确定给定任务使用的主机或主机目标组的默认列表	Pending	这些装饰师非常喜欢 Fabric 1的“DSL”纹理，并且没有被优先考虑重写，尽管他们可能以某种形式返回，可能更快而不是更晚。
@serial/@parallel/@runs_once	端口/待机 <https://github.com/pyinvoke/invoke/issues/63>`__	并行执行目前在API级别通过 fabric.group.Group 子类，如 fabric.group.ThreadingGroup ；但是，指定整个会话和/或任务并行运行（或免除并行运行）尚未解决。 这个问题需要在更高的级别上解决，而不仅仅是ssh目标，因此这将链接到一个调用级别的票据。
execute 用于从其他任务调用命名任务，同时尊重装饰器和其他执行机制（而不是简单地将它们作为函数调用）	Pending	这是重写中最重要的“缺少功能”之一；链接用于调用跟踪程序。
Task 用于编程创建任务的类（与使用某些函数对象和 @task 装饰者）	端口	虽然没有与v1共享许多实现细节，但现代结构（via invoke）公开了 Task 类，旁边是 Collection 允许完全编程创建任务树，不需要修饰器。

cli参数、选项和行为

将任务参数暴露为自定义冒号/逗号分隔的CLI参数，例如 fab mytask:posarg,kwarg=val	远离的	cli参数现在是合适的gnu/posix样式的长和短标志，包括将短标志放在一起、空格或等号来附加值、可选值等等。见 invoking-tasks .
任务定义名称直接镜像在命令行上，例如用于任务 def journald_logs() ，命令行参数为 fab journald_logs	远离的	任务名称现在从下划线转换为连字符。任务 def journald_logs() 现在计算为 fab journald-logs 在命令行上。
能够在一个命令行中调用多个任务，例如 fab task1 task2	端口	工作很棒！
python -m fabric as stand-in for fab	端口	移植于2.2。
-a/--no_agent 用于禁用自动ssh代理密钥选择	远离的	要永久禁用代理的使用，请设置配置值 connect_kwargs.allow_agent 到 False ；要暂时禁用，请取消设置 SSH_AUTH_SOCK EV V.
-A/--forward-agent 用于启用代理转发到远程端	远离的	这个的config和kwarg版本被移植，但目前没有cli标志。通常，“可以在运行时用shell env变量设置配置值”子句有效，因此 may 不被移植，视情况而定。
--abort-on-prompts 将交互式提示转换为异常（有助于避免“挂起”会话）	远离的	请参见有关交互提示离开的注释 一般/概念 . 如果没有中间会话提示，则不需要此选项。
-c/--config 用于指定备用配置文件路径	端口	--config lives on, but the short flag is now -f (-c now determines which collection module name is sought by the task loader.)
--colorize-errors （和 env.colorize_errors ）启用错误输出的ANSI着色	Pending	颜色工作还没有完成，这是可能丢失的部分之一。我们不确定它在v1中的使用频率，所以它可能不会再次出现，但一般来说，我们喜欢使用颜色作为额外的输出向量，所以…
-d/--display 用于显示给定命令的信息	端口	这是现在的标准 -h/--help ，并且可以在任意“方向”上给出： fab -h mytask 或 fab mytask -h .
-D/--disable-known-hosts 关闭Paramiko自动加载用户级别 known_hosts 文件夹	Pending	还没有预告，可能会。
-e/--eagerly-disconnect （和 env.eagerly_disconnect ）它告诉执行系统在任务运行完成后立即断开与主机的连接。	端口/待机 <https://github.com/fabric/fabric/issues/1805>`__	已经没有显式连接缓存了，因此不必太急地断开连接。然而，调查和潜在的特征切换仍然悬而未决。
-f/--fabfile 选择备用FabFile位置	端口	现在分为 -c/--collection 和 -r/--search-root 见 loading-collections .
-g/--gateway （和 env.gateway ）用于选择全局ssh网关主机字符串	Pending	可以设置全局 gateway 通过一个环境变量配置选项，乍一看，这将消除对专用CLI选项的需求。但是，这种方法只允许设置字符串值，而字符串值只用于 ProxyCommand 风格网关，所以它 不 替换V1 --gateway （取了一个主机字符串并将其转换为 ProxyJump 样式网关。 因此，如果有足够多的用户注意到这一点，我们将考虑一个在很大程度上模仿v1行为的特性add：string成为 fabric.connection.Connection 然后结果对象被设置为 gateway .
--gss-auth/--gss-deleg/--gss-kex	远离的	这些似乎不够用，不值得移植，特别是因为它们落在了通常的伞下“帕拉米科级连接直通”所涵盖的 connect_kwargs 配置选项。（如有必要，可以通过shell环境变量在运行时进行设置，就像任何其他配置值一样。）
--hide/--show 用于全局调整输出显示	远离的	这可以通过配置系统和env vars进行配置。
-H/--hosts	端口	工作原理与之前基本相同-如果给定，则是每个主机执行一次任何给定任务的简写。
-i 对于ssh密钥文件名选择	端口	与v1的工作原理相同，包括多次提供构建要尝试的密钥列表的能力。
-I/--initial-password-prompt 用于请求初始执行前密码提示	端口	现在 --prompt-for-login-password ， --prompt-for-sudo-password 或 --prompt-for-passphrase ，取决于您是使用前者填写密码还是使用密钥密码短语（或两者都填写）。
--initial-sudo-password-prompt 用于请求初始执行前的sudo密码提示	端口	这是现在 --prompt-for-sudo-password . 还有一口，但还是少了4个字符！
-k/--no-keys which prevents Paramiko's automatic loading of key files such as ~/.ssh/id_rsa	远离的	使用环境变量设置 connect_kwargs.look_for_keys 配置值到 False .
--keepalive 用于设置网络保持连接	Pending	还没有移植。
-l/--list 用于列出任务，以及 -F/--list-format 用于调整列表显示格式	端口	现在有了额外的JSON列表格式！顺便说一下，它取代了 -F short/--shortlist .
--linewise 用于逐行缓冲输出，而不是粗略地逐字节缓冲输出	远离的	这并不符合现代命令执行代码对世界的看法，所以它已经不复存在了。
-n/--connection-attempts 控制多次连接重试	Pending	还没有移植。
--no-pty 禁用自动节目类型分配 run 等	端口	现在是 -p/--pty 因为默认行为被切换。
--password/--sudo-password 用于指定登录/sudo密码值	远离的	首先，这通常不太安全，现在有许多其他的方法来设置相关的配置值，所以至少现在已经不存在了。
-P/--parallel 用于激活全局并行性	Pending	查看周围的注释 @parallel 在里面 任务功能和装饰 .
--port 设置默认ssh端口	远离的	我们的直觉说这最好留给配置系统的env var层，或者使用 port 克沃格 fabric.connection.Connection 然而，它可能会找到它的归路。
r/--reject-unknown-hosts 修改Paramiko已知主机行为	Pending	还没有移植。
-R/--roles 用于主机目标选择的全局列表	Pending	如下所述 API组织 ，角色列表仅部分适用于新的API，我们仍在摸索它们是否/如何在全局或CLI级别上工作。
--set key=value 用于设置 fabric.state.env 运行时的VARS	远离的	这在很大程度上被对shell环境变量的新支持所消除（只需做 INVOKE_KEY=value fab mytask 或者类似的方法），尽管设置配置值的cli标志方法很可能在稍后重新出现。
-s/--shell 覆盖默认外壳路径	远离的	为此，请使用配置系统。
--shortlist 用于简单/计算机友好的列表输出	端口	见 --list/--list-format -现在有了JSON格式。没有必要再发明轮子。
--skip-bad-hosts （和 env.skip_bad_hosts ）绕过有问题的主机	Pending	还没有移植。
--skip-unknown-tasks 和 env.skip_unknown_tasks 用于在调用cli时自动跳过假任务名	远离的	对我们来说，这主要感觉像膨胀，可能需要对重实现进行一些重要的解析器更改，所以现在已经过时了。
--ssh-config-path 和 env.ssh_config_path 用于选择ssh配置文件	端口	这是现在 -S/--ssh-config .
--system-known-hosts 触发整个系统的加载 known_hosts 文件夹	Pending 移除	这不太可能作为自己的cli标志返回，但它可能作为配置值返回。
-t/--timeout 控制连接超时	端口	这现在是直接传递到paramiko级别连接参数的一部分， connect_kwargs 配置值。
-T/--command-timeout	Pending	见注释 shell命令执行 (local /运行`/ sudo``） 周围 timeout 克瓦格
-u/--user 设置全局默认用户名	远离的	大多数情况下，配置（env vars for true runtime，或例如用户/项目级的配置文件，视情况而定）都应该用于此目的，但它可能会返回。
-w/--warn-only 切换警告与中止行为	端口	照原样移植，没有变化。
-x/--exclude-hosts （和 env.exclude_hosts ）用于排除其他选定目标	Pending	尚未移植，正在等待对全局（vs手工实例化）连接/组选择进行深度重做。
-z/--pool-size 用于设置并行模式作业队列池大小	远离的	现在已经没有工作队列了，至少现在没有。不管用什么替代它（除了已经实现的线程模型），看起来都可能大不相同。

shell命令执行 (local /运行`/ sudo``）

一般

任何一方共享的行为 run/sudo ，或全部 run/sudo '''本地''。后面的部分按功能差异进行介绍。

local and run/sudo 具有非常不同的API和实现	远离的	所有命令执行现在都是统一的；所有三个函数（现在方法打开 fabric.connection.Connection 虽然，虽然 local 也可作为 invoke.run 单独使用）具有相同的底层协议和逻辑 Runner 类层次结构），只有低级细节，如流程创建和管道消耗不同。 例如，在v1中 local 要求您在显示和捕获子进程输出之间进行选择；现代 local 就像 run 同时做这两件事。
提示自动响应，通过 env.prompts 和/或 sudo 内部构件	端口	这个 env.prompts 功能已经大大扩展到 Watchers 可在任何（本地或远程）上操作！运行命令的输入和输出流。 此外， sudo 已经被重写以使用该框架；虽然仍然可以提供核心实现，但它不再做任何用户使用公共API不能自己做的事情。
fabric.context_managers.cd/lcd （和 prefix ）允许已执行注释的范围变异	端口/待机 <https://github.com/fabric/fabric/issues/1752>`__	These are now methods on Context (Context.cd, Context.prefix) but need work in its subclass fabric.connection.Connection (quite possibly including recreating lcd) so that local vs remote state are separated.
fabric.context_managers.shell_env 它的具体表达 path （加） env.shell_env ， env.path 和 env.path_behavior ，用于修改远程环境变量（在本地，只需修改 os.environ ）	端口	上下文管理器是在任何范围内设置环境变量的唯一方法；在现代结构中，每个调用都可以控制子进程shell环境（直接在 fabric.connection.Connection.run 和兄弟姐妹通过 env 克瓦格 and 跨多个调用（通过静态或运行时操作配置系统）。
通过操作控制子流程输出和其他活动显示文本 fabric.state.output (directly or via fabric.context_managers.hide, show or quiet as well as the quiet kwarg to run/sudo 加上 utils.puts/fastprint ）	端口/待机 <https://github.com/pyinvoke/invoke/issues/15>`__	“输出级别”的核心概念已经不复存在，很可能在短期内被输出级别重新实现得很差的日志模块（stdlib或其他）所取代。 命令执行方法 run 保留一个 hide Kwarg控制复制到终端的子进程流，以及 echo Kwarg控制命令是否在执行前打印。所有这些都符合配置系统。
timeout 克沃格和 CommandTimeout 违反所述命令运行时超时时引发异常	Pending	命令超时尚未被移植，但很可能会在将来添加（在调用层）。
pty 克瓦格和 env.always_use_pty ，控制命令是在伪终端中运行还是直接调用	端口	这已被彻底报告（其行为经常得到改善），包括保存 pty 将配置值更新为 run.pty . 但是，一个主要的变化是PTY分配现在 False 默认而不是 True . Fabric0.x和1.x已经改变了这个值；在Fabric1的长生命周期中，很明显默认值对所有用户甚至大多数用户都不起作用，因此我们选择将默认值返回到 False 因为它更干净，更不浪费。
combine_stderr （克瓦格和 env.combine_stderr ）控制Paramiko是否将远程stdout和stderr编织到stdout流中	远离的	这并不十分有用，而且经常导致概念上的问题 pty （因为伪终端的性质总是将两个流结合在一起。） 我们建议真正需要合并两个流的用户，或者在命令中使用shell重定向，或者设置 pty=True .
warn_only 用于防止非零返回码自动中止的Kwarg	端口	现在只是 warn ，kwarg和config值。它继续默认为 False .
stdout 和 stderr 用于重新分配默认stdout/err镜像目标的Kwargs，否则将默认为相应的 sys 成员	端口	这些是现在 out_stream 和 err_stream 但除此之外，在性质上保持相似。它们也伴随着新的，事后看来相当明显。 in_stream .
capture_buffer_size 使用环形缓冲区存储捕获的stdout/stderr以限制总大小（&U）	Pending	现有的 Runner 实现使用常规列表来捕获缓冲区，但我们完全希望在某个时刻将其升级为环形缓冲区或类似的列表。
返回值是类似字符串的对象，具有 succeeded 和 return_code 洒在上面	端口	返回值不再是类似于字符串的半私有API，而是类型为完全成熟的常规对象 Result . 它们公开了所有与旧的“属性字符串”相同的信息，但真正不同的是它们本身并不假装是字符串。 但是，它们仍然表现为布尔值——只是反映出退出代码与零的关系，而不是是否存在任何stdout。
open_shell 用于获取交互式友好的远程shell会话 run 历史上不擅长）	端口	技术上“删除”，但只是因为新版本的 run 大大改进了，至少可以处理交互式会话和旧会话 open_shell 是的，如果不是更多的话。 c.run("/my/favorite/shell", pty=True) 应该是你所需要的。

run

shell / env.use_shell designating whether or not to wrap commands within an explicit call to e.g. /bin/sh -c 'real command'; plus their attendant options like shell_escape

远离的

非``sudo``远程执行从来没有真正需要一个明确的shell包装器：在几乎所有情况下，远程ssh守护进程都将命令字符串交给连接用户的登录shell。因为包装在其他方面非常容易出错，并且需要令人沮丧的转义规则，所以我们在这个用例中放弃了它。 查看匹配的行项目 local 和 sudo 因为他们的情况不同。（现在，因为他们都有相同的基础， fabric.connection.Connection.run 接受一个 shell 夸格-这跟它没什么关系。）

sudo

除非另有说明，所有常见的 run +`` sudo``参数/功能（例如 pty ， warn_only 等）在上文的 run 下面是 sudo 具体的。

shell / env.use_shell designating whether or not to wrap commands within an explicit call to e.g. /bin/sh -c 'real command'	Pending 移除	见上文注释 run 有关作为一般策略的外壳包装的详细信息；不幸的是 sudo 由于命令字符串是如何传递给 sudo 程序。 我们希望升级 sudo 很快它就可以执行一个常见的最佳情况，不需要为您转义所需的shell包装；请参见“挂起”链接。
user 论证（和） env.sudo_user ）允许通过调用 sudo -u <user> （而不是默认为根目录）	端口	这仍然在这里，而且还在叫 user .
group 控制sudo'd命令有效组的参数	Pending	这还没有预告。

local

有关新的 local . 下面是一些具体的附加内容。

shell Kwarg指定要问哪一个壳牌公司 subprocess.Popen 使用

端口

基本上和v1一样，尽管现在有一些情况 os.execve （或类似）用于代替 subprocess.Popen . 行为基本相同：没有外壳包装（就像在遗留的 run ，只需通知操作系统要运行的实际程序。

公用事业

错误处理通过 abort 和 warn	端口	旧的功能在“一切都是DSL”的方向上倾斜得太远，没有提供足够的价值来抵消它如何阻碍有经验的 Python 。 为了“引发异常”（一个有用的选项是invoke），这些函数已被删除 Exit ）由于异常处理比周围的薄包装纸感觉更像是 Python 。 sys.exit 或者不得不 except SystemExit: 希望是一个 SystemExit 你自己的代码被提升了！
ANSI颜色助手 fabric.colors 允许用户在没有独立库的情况下轻松打印ANSI彩色文本	远离的	似乎没有必要复制出许多优秀的终端按摩库中的一个（如描述中所列的库）。 #101 ）在重写中，我们没有。 这就是说，我们很有可能在将来出售这样一个库来提供内部颜色支持，在这一点上“烘焙”的颜色助手将再次很容易到达。
with char_buffered 用于强制本地流进行字符缓冲的上下文管理器	端口	这是现在 character_buffered .
docs.unwrap_tasks 用于从包装任务函数提取docstring	端口	v1需要在你的sphinx构建管道中的某处使用特定于结构的“uncap-tasks”助手函数；现在你可以只启用新的 invocations.autodoc 扩展列表中的sphinx迷你插件；有关详细信息，请参见链接。
network.normalize ， denormalize 和 parse_host_string ，表面上是内部的，但有时由于处理主机字符串而暴露给用户	远离的	与其他与主机字符串相关的工具一样，这些工具已不复存在，而且毫无用处。 fabric.connection.Connection 现在是主要的API焦点，并且具有所有“主机字符串”组件的单独属性。
utils.indent 用于缩进/换行文本（不常用）	悬而未决的	尚未移植；理想情况下，我们只在invoke中提供第三方lib。
reboot 用于重新启动和重新连接到远程系统	远离的	没有为现代结构编写等效的函数；既然连接/客户机对象是显式的，就可以简单地用相同的参数（如果不想手动调用类似于 time.sleep ） 如果有足够的需求，它返回的可能性很小；如果有，它可能是一个更一般的重新连接相关的 fabric.connection.Connection 方法，其中用户负责通过 sudo 他们自己。
require 确保 env 设置值，注意它们可以 provided_by= 安装任务列表	远离的	这还没有被移植，部分原因是维护人员从未自己使用过它，而且不太可能直接重新实现。但是，其核心用例“需要某些数据可用于运行给定任务”可能会在即将到来的依赖关系框架内返回。
prompt for prompting the user & storing the entered data (optionally with validation) directly into env	远离的	喜欢 require ，这似乎是一个使用较少的功能（特别是与它的兄弟相比 confirm ）没有预告。如果它还了，很可能是通过 invocations ，在哪 confirm 结束了。

网络

env.gateway 用于设置ssh跳转网关	端口	这是现在 gateway 克瓦格 fabric.connection.Connection ，以及——对于新支持的 ProxyJump 样式网关，可以无限嵌套！--应该是另一个 fabric.connection.Connection 对象而不是主机字符串。 （您可以指定运行时，非ssh配置驱动 ProxyCommand -将字符串样式设置为 gateway 而Kwarg，就好像一个普通人 ProxyCommand ）
ssh_config 驱动的 ProxyCommand 支持	端口	这和v1一样继续工作。
with remote_tunnel(...): 端口转发	端口	这是现在 fabric.connection.Connection.forward_local 因为它已经习惯了 向前地 一 地方的 端口到远程端。（新添加的是逻辑反转， fabric.connection.Connection.forward_remote ）
NetworkError 在某些网络相关错误上引发	远离的	在v1中，这只是一个（部分实现的）从原来的“任何错误都只有sys.exit！”行为。现代织物明显更为友好；会引起 NetworkError 在v1中，现在只是成为真正的底层异常，通常来自于paramiko或stdlib。
env.keepalive 用于设置网络保持值	Pending	还没有移植。
env.connection_attempts 用于设置连接重试	Pending	还没有移植。
env.timeout 用于控制连接超时	端口	现在可以通过配置系统和直接Kwarg控制 fabric.connection.Connection .

认证

注解

一些 env v1的钥匙只是通过帕拉米科的 SSHClient.connect 方法。现代结构通过 connect_kwargs configuration 子树，下表将经常引用这种方法。

env.key_filename	端口	使用 connect_kwargs .
env.password	端口	使用 connect_kwargs . 还要注意，这用于执行双负载连接 and sudo密码；后者现在位于 sudo.password 设置。
env.gss_(auth|deleg|kex)	端口	使用 connect_kwargs .
env.key ，包含私钥数据的字符串或文件对象，其特定类型是自动确定并实例化的，以用作 pkey 连接克沃格	远离的	这已被删除，因为对Paramiko级别的API进行了不必要的（易出错）模糊处理；用户应该已经知道他们正在处理的是哪种类型的密钥，并实例化一个 PKey 子类自身，将结果放入 connect_kwargs.pkey .
env.no_agent ，这是对Paramiko的重命名/反转 allow_agent 连接克沃格	端口	将此设置为的用户 True 现在应该简单设置 connect_kwargs.allow_agent 到 False 相反。
env.no_keys ，类似于 no_agent 只不过是 look_for_keys 连接克沃格	端口	使用 connect_kwargs.look_for_keys 相反（设置为 False 禁用Paramiko的默认密钥查找行为。）
env.passwords （和 env.sudo_passwords ）将连接/sudo密码存储在主机字符串键控的dict中	端口/待机 <https://github.com/fabric/fabric/issues/4>`__	各 fabric.connection.Connection 对象可以配置为自己的 connect_kwargs 在实例化时给出，已经允许每个主机的密码配置。 但是，我们希望用户可以使用一种更简单的方法来设置将变为隐式的配置值。 fabric.connection.Connection 对象自动；此类功能仍处于挂起状态。
配置 IdentityFile 在某人的 ssh_config	端口	还有一些新的荣誉 ssh_config 设置；见 ssh-config .

文件传输

以下功能分解适用于 put 和/或 get v1的“操作”功能。

传输本地和远程用户拥有的单个文件	端口	任何方向的基本文件传输都有效，并提供 fabric.connection.Connection.get /` fabric.connection.connection.put`（虽然代码分为单独的责任类， fabric.transfer.Transfer ） 与v1相比，这些方法的签名已被清除，尽管它们的位置参数本质 (get(remote, local) 和 put(local, remote) 保持不变。
省略隐式“相对于本地上下文”行为的“destination”参数（例如 put('local.txt') 隐式上载到远程 $HOME/local.txt ）	端口	您可能仍然应该是显式的，因为这是Python。
使用任一文件路径 or 传输操作任一侧的类似文件的对象（例如上载 StringIO 而不是磁盘上的文件）	端口	这是一个非常有用且非常简单的技巧。
在目的地保留源文件模式（例如，确保将由目的地的umask删除的可执行位被重新添加）。	端口	这不仅是预告，而且现在是默认行为。如果需要，可以通过Kwarg禁用。
捆扎 sudo 作为文件传输的一部分的操作	远离的	这是v1中最令人讨厌的部分之一，而且从来没有真正做过用户在后续呼叫中不能做的事情。 sudo ，所以我们选择不移植。 如果有足够多的用户对它的损失感到担忧，我们 may 重新考虑一下，但是如果我们这样做，我们将认真关注简化和/或不涉及中间文件的方法。
递归多文件传输（例如 put(a_directory) 上载整个目录及其所有内容）	远离的	这是 另一个 v1最麻烦的部分之一，随着时间的推移，很明显它的维护负担远远超过了这一事实：它的重新设计很糟糕。 rsync 和/或使用归档文件工具，如Ye Olde tar +‘gZip’。

配置

总的来说，配置已经大大改善了 fabricrc 文件；大多数配置逻辑来自 Invoke's configuration system 它提供了一个完整的配置层次结构（在代码配置、多个配置文件位置、环境变量、CLI标志等）和多个文件格式。在现代结构中，结构1中的几乎所有配置通道都变成了配置层次结构中最适合您需要的任何部分的操作。

结构的现代版本只对invoke的设置进行细微的修改（或参数化）；请参见 our locally-specific config doc page 有关详细信息。

注解

确保在本文档的其他地方查找任何给定v1的详细信息 env 设置，因为许多已从配置系统外移到对象或方法关键字参数中。

修改 fabric.(api.)env 直接地	端口	要真正实现全局范围的配置更改，请使用配置文件、任务集合级别的配置数据或调用shell的环境变量。
使本地范围 fabric.env 通过改变 with settings(...): 或其装饰等效物， @with_settings	移植/未决	周围的大多数用例 settings 现在服务的事实是 fabric.connection.Connection 对象保持每主机/连接状态-切换隐式全局上下文的模式是一个设计反模式，现在已不复存在。 剩下的这些用例已经变成了 fabric.connection.Connection （或其父类），或具有挂起的此类方法。
ssh配置文件加载（默认关闭，仅限于 ~/.ssh/config 除非配置为不同的单一路径）	端口	大大改进了：ssh配置文件加载是 on 默认情况下 can be changed ）和OpenSSH一样，加载和合并了多个源，此外还有更多；请参见 ssh-config . 此外，我们还为一些 ssh_config 被v1忽略的指令，例如 ConnectTimeout 和 ProxyCommand 我们打算支持 ssh_config 尽可能合理。

contrib

老年人 contrib 模块表示“最佳实践”函数，这些函数本身不需要其他结构的核心支持，而是使用用户可用的相同原语构建的。

在现代结构中，这种责任已经从核心库转移到其他独立的库中，这些库具有自己的身份和发布过程，通常是 invocations （不使用ssh的面向本地的代码）或 patchwork （主要是面向远程的代码，尽管没有显式地处理连接两端的任何事情都可以在本地正常工作。）

这些库仍然在进行中，尤其是因为我们仍然需要找出弥合它们之间差距的最佳方法（因为许多操作本质上不是本地的或远程的，但可以在任何一端工作）。

由于根据定义，它们是建立在所有用户可用的核心API之上的，因此它们目前的开发重点较少；用户总是可以实现自己的版本，而不会牺牲太多（对于核心库来说，这是不太现实的事情）。一旦核心API稳定下来，我们希望在管理这些集合方面投入更多的工作。

每个单独块的详细信息 fabric.contrib 在下表中：

console.confirm 为了方便返回bool确认提示	端口	搬到 invocations.console.confirm ，带有细微的签名调整。
django.* ，支持与本地Django项目的集成：导入和使用Django模型和其他代码	远离的	我们甚至不确定这本书写完十年后是否有用，因为从那以后，姜戈肯定发生了很大的变化。如果你正在阅读，并且对这件事的消失感到悲伤，请告诉我们！
files.* （例如） exists ， append ， contains etc）用于查询和修改远程文件	移植/未决	这个文件中许多更有用的函数已经移植到 patchwork.files 但基本上仍处于α状态。 其他，如 is_link, comment/uncomment 等等，还没有预告。如果是的话，很可能会在同一个地方结束。
project.rsync_project 用于远程同步整个主机项目	端口	现在 patchwork.transfers.rsync 做了一些修改。
project.rsync_project 用于通过存档文件和SCP上载主机项目	远离的	这似乎不值得移植；“远程复制本地位”的总体模式已经可以说是一个反模式（vs可重复部署工件，或者至少远程签出VCS标签），而且如果有人走这条路，rsync是一个更明智的选择。

fabric.env 参考

v1中的许多/大多数成员 fabric.env 在以上每个主题部分都有介绍；任何 not 在别处，住在这里。所有这些都明确指出为 env.<name> 以便在浏览器或查看器中搜索。

少数env变量从未公开记录，因此是隐式私有的；这些变量在这里没有表示。

env.abort_exception 用于设置用于中止的异常	远离的	当一个概念消失后中止，只需向最终用户提出任何看起来最合理的异常，或使用 Exit . 也见 公用事业 .
env.all_hosts 和 env.tasks 列出执行目标	端口/待机 <https://github.com/pyinvoke/invoke/issues/443>`__	织物的 Executor 子类存储对所有CLI分析结果的引用（包括 --hosts ，请求的任务及其参数等），目的是让用户能够访问这些信息。 但是，该API的详细信息（例如，通过任务的 Context /` fabric.connection.connection`）仍在不断变化。
env.command 注意到当前正在执行的任务名（事后看来，用词不当…）	端口/待机 <https://github.com/pyinvoke/invoke/issues/443>`__	参见注释 env.all_hosts 上面同样适用于这里：用户对cli解析结果的可见性。
env.command_prefixes for visibility into (arguably also mutation of) the shell command prefixes to be applied to run/sudo	端口	这是现在 command_prefixes .
env.cwd 注意当前预期工作目录	端口	这是现在 command_cwds （一个列表，而不是单个字符串，以便更正确地建模预期的ContextManager驱动的用例。） 请注意，尚未设置此数据的远程和本地上下文；请参阅有关 with cd 在下面 shell命令执行 (local /运行`/ sudo``） .
env.dedupe_hosts 控制合并主机列表中的重复主机是否进行重复数据消除	Pending	尚未移植，可能会作为角色/主机列表大修的一部分处理。
env.echo_stdin （未记录）用于关闭标准输入的默认回显	端口	现在是下的配置选项 run 树，有很多相同的行为。
env.local_user 以只读方式访问发现的本地用户名	远离的	我们不完全确定为什么v1认为这值得在配置中缓存；如果您需要此信息，只需导入并调用 fabric.util.get_local_user .
env.output_prefix 确定是否显示逐行主机字符串前缀	Pending	区分并行stdout/err仍然是一项正在进行的工作；我们可能最终会逐个行地重用日志记录和前缀（最好是通过实际日志记录），或者我们可能会尝试使用更干净的方法，例如按连接流式传输到日志文件。
env.prompts 控制提示自动响应	端口	提示自动响应现在公开实现为 StreamWatcher 和 Responder 类层次结构，其实例可以移交给 run 通过Kwarg或全局存储在配置中 run.watchers .
env.real_fabfile 存储由CLI机器加载的只读fabfile路径	端口	加载任务 Collection 存储在两个顶层 Program 对象以及 Executor 调用任务；以及 Collection 有一个 loaded_from 具有此信息的属性。
env.remote_interrupt 控制中断的方式（即本地 KeyboardInterrupt 被捕获、转发或其他	移植/移除	invoke的中断捕获行为当前为“总是将中断字符发送到子进程并继续”，允许子进程处理 ^C 但是，它们需要这样做，这是对织物1的改进，大致相当于设置 env.remote_interrupt = True . 允许用户通过config更改此行为还没有实现，也可能没有实现，这取决于是否有人需要它——出于向后兼容的原因，它被添加为v1中的一个选项。 技术上也可以通过子类化和重写来更改中断行为。 invoke.runners.Runner.send_interrupt .
env.roles ， env.roledefs 和 env.effective_roles 控制/公开哪些角色可用或当前正在扮演	Pending	如中所述 API组织 ，作为一个概念的角色被移植到 fabric.group.Group 但是没有中央票据交换所来存放它们。 我们 may 将其永远委托给userland，但似乎是一个常见的最佳实践选项（例如创建 Groups 从某个配置子树并将其存储为 Context 属性）将出现在2.x的早期。
env.ok_ret_codes 用于覆盖子进程命令的默认“0好，非0坏”错误检测	Pending	还没有移植，但应该包括一些可能的小更新 invoke.runners.Runner.generate_result 和 Result .
env.sudo_prefix 确定创建时使用的sudo二进制名称及其标志 sudo 命令字符串	Pending	sudo命令构造目前只查看配置中的sudo提示。
env.sudo_prompt 用于设置传递给的提示字符串 sudo （然后期望以配置的密码自动回复）	端口	现在是 sudo.prompt 在配置系统中。
env.use_exceptions_for 注意哪些操作会引发异常	远离的	与其他功能一样，织物1的“直接跳到 sys.exit “设计反模式，这已经不复存在了——现代结构不会隐藏用户级代码的任何异常。
env.use_ssh_config 默认启用关闭ssh配置加载	端口	SSH config loading is now on by default, but an option remains to disable it. See 配置 for more.
env.version 显示当前结构版本号	远离的	只是 import fabric 参考文献 fabric.__version__ （字符串）或 fabric.__version_info__ （元组）

示例升级过程

本节将介绍如何升级一个小型但不平凡的Fabric1FabFile以使用现代Fabric。它并不意味着详尽，只是说明性的；有关如何升级单个功能或概念的完整列表，请参见 升级详细信息 .

原始FabFile示例

以下是Fabric1最终教程片段的副本（稍作修改以符合“现代”Fabric1最佳实践），我们将使用它作为升级的测试用例：

from fabric.api import abort, env, local, run, settings, task
from fabric.contrib.console import confirm

env.hosts = ['my-server']

@task
def test():
    with settings(warn_only=True):
        result = local('./manage.py test my_app', capture=True)
    if result.failed and not confirm("Tests failed. Continue anyway?"):
        abort("Aborting at user request.")

@task
def commit():
    local("git add -p && git commit")

@task
def push():
    local("git push")

@task
def prepare_deploy():
    test()
    commit()
    push()

@task
def deploy():
    code_dir = '/srv/django/myproject'
    with settings(warn_only=True):
        if run("test -d {}".format(code_dir)).failed:
            cmd = "git clone user@vcshost:/path/to/repo/.git {}"
            run(cmd.format(code_dir))
    with cd(code_dir):
        run("git pull")
        run("touch app.wsgi")

我们将直接把它移植，这意味着结果仍然是 fabfile.py 不过，我们要注意的是，以一种更面向库的方式编写代码——即使函数没有被包装在 @task -可以使测试和重用代码更容易。

进口

在现代结构中，由于强调对象方法而不是全局函数，我们不需要导入几乎相同的函数。我们只需要以下内容：

• Exit 更友好的请求方式 sys.exit ；

• @task ，和以前一样，但来自invoke，因为它不特定于ssh；

• confirm 它现在来自调用库（也不是特定于ssh；尽管调用是 fabric.contrib （不再存在）；

from invoke import task, Exit
from invocations.console import confirm

主机列表

预先定义的全局主机列表的想法已经不复存在；目前没有直接替换。相反，我们希望用户设置自己的执行上下文，创建显式的 fabric.connection.Connection 和/或 fabric.group.Group 对象视需要而定，即使这只是模仿v1内置的“角色”映射。对于简单的用例， --hosts 核心选项仍然可用。

注解

这是一个正在积极发展的领域，欢迎反馈。

现在，假定源代码段硬编码了 my-server ，我们假定将调用此fabfile，例如 fab -H my-server taskname 并且在fabfile本身中没有硬编码。

测试任务

fabfile中的第一个任务使用了API的良好传播。我们将在这里概述这些更改（不过，所有细节都在 升级详细信息 ）：

• 将函数声明为任务与以前几乎相同，但使用显式的初始上下文参数，其值将是 fabric.connection.Connection 对象在运行时。

• The use of with settings(warn_only=True) can be replaced by a simple kwarg to the local call.

• 那 local 调用现在是对 fabric.connection.Connection ， fabric.connection.Connection.local .

• capture 不再是一个有用的参数；我们现在可以在本地或远程同时捕获和显示。如果你不是真的 want 本地子进程在运行时镜像其stdout/err，您可以简单地说 hide=True （或） hide='stdout' 等等）

• 结果对象在不同版本之间非常相似；现代结构的结果不再假装是“be”字符串，而是更像布尔值，如果命令干净地退出，则表现为真实，否则则为虚假。就所展示的属性而言，大多数相同的信息都是可用的，而且更多。

• abort 不见了；你应该使用你认为合适的例外，或者 Exit 对于一个 sys.exit 当量。（或者只是打电话 sys.exit 如果您不想问任何问题，请立即退出，即使是我们的CLI机器也不会接触。）

结果：

@task
def test(c):
    result = c.local('./manage.py test my_app', warn=True)
    if not result and not confirm("Tests failed. Continue anyway?"):
        raise Exit("Aborting at user request.")

其他简单任务

接下来的两个任务是简单的一行程序，您已经看到了什么取代了全球 local 功能：

@task
def commit(c):
    c.local("git add -p && git commit")

@task
def push(c):
    c.local("git push")

从其他任务调用任务

这是另一个在调用级别处于不断变化中的领域，但是现在，我们可以简单地将其他任务作为函数调用，就像在v1中所做的那样。主要区别在于，我们希望传递上下文对象以保留配置上下文（如加载的配置文件或CLI标志）：：

@task
def prepare_deploy(c):
    test(c)
    commit(c)
    push(c)

实际远程步骤

请注意，到目前为止，还没有真正与织物有关的东西发挥作用。- fabric.connection.Connection.local 只是重新绑定 Context.run ，调用的本地子进程执行方法。现在我们进入实际的部署步骤，它调用 fabric.connection.Connection.run 相反，远程执行（在 fabric.connection.Connection 已绑定到）。

with cd 还没有完全实现远程方面的事情，但我们预计很快就会实现。现在我们回到命令链 && .

@task
def deploy(c):
    code_dir = '/srv/django/myproject'
    if not c.run("test -d {}".format(code_dir), warn=True):
        cmd = "git clone user@vcshost:/path/to/repo/.git {}"
        c.run(cmd.format(code_dir))
    c.run("cd {} && git pull".format(code_dir))
    c.run("cd {} && touch app.wsgi".format(code_dir))

整件事

现在我们有了整个升级后的FabFile，它将与现代 Fabric 一起使用：

from invoke import task, Exit
from invocations.console import confirm

@task
def test(c):
    result = c.local('./manage.py test my_app', warn=True)
    if not result and not confirm("Tests failed. Continue anyway?"):
        raise Exit("Aborting at user request.")

@task
def commit(c):
    c.local("git add -p && git commit")

@task
def push(c):
    c.local("git push")

@task
def prepare_deploy(c):
    test(c)
    commit(c)
    push(c)

@task
def deploy(c):
    code_dir = '/srv/django/myproject'
    if not c.run("test -d {}".format(code_dir), warn=True):
        cmd = "git clone user@vcshost:/path/to/repo/.git {}"
        c.run(cmd.format(code_dir))
    c.run("cd {} && git pull".format(code_dir))
    c.run("cd {} && touch app.wsgi".format(code_dir))