從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 （除了“正?！碧峁?.0+版本的 fabric ）并且可以與1.x版的安裝共存。

因此，如果您有一個大的代碼庫，并且不想一次跳到現代版本，那么可以同時使用兩種結構1 (fabric ，就像你以前安裝的一樣）和現代織物 fabric2 ）同時駐留在您的Python環境中。

注解

我們強烈建議您最終使用Fabric1將所有代碼遷移到版本2或更高版本，以便您可以返回到 fabric 姓名。 fabric2 作為一個獨特的包和模塊，它的目的是要有一個權宜之計，而不會有任何 fabric3 或者更高（尤其是因為其中一些名字已經被取了?。?/p>

有關如何獲取 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以限制總大?。?amp;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！”行為?，F代織物明顯更為友好；會引起 NetworkError 在v1中，現在只是成為真正的底層異常，通常來自于paramiko或stdlib。
env.keepalive 用于設置網絡保持值	Pending	還沒有移植。
env.connection_attempts 用于設置連接重試	Pending	還沒有移植。
env.timeout 用于控制連接超時	端口	現在可以通過配置系統和直接Kwarg控制 fabric.connection.Connection .

認證

注解

一些 env v1的鑰匙只是通過帕拉米科的 SSHClient.connect 方法?，F代結構通過 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配置加載現在默認處于打開狀態，但仍有一個選項可以禁用它?？匆?配置 想要更多。
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 對象在運行時。

• 使用 with settings(warn_only=True) 可以用一個簡單的木匠來代替 local 打電話。

• 那 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 ，調用的本地子進程執行方法?，F在我們進入實際的部署步驟，它調用 fabric.connection.Connection.run 相反，遠程執行（在 fabric.connection.Connection 已綁定到）。

with cd 還沒有完全實現遠程方面的事情，但我們預計很快就會實現?，F在我們回到命令鏈 && .

@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))