Fabric API Full List

時間 2019-11-13

標籤 fabric api list 简体版

原文原文鏈接

Core API

核心API主要有七類:帶顏色的輸出類(color output),上下文管理類(context managers), 裝飾器類(decorators), 網絡類(network), 操做類(oprations), 任務類(tasks), 工具類(utils)。java

Color Output

每個包含這個模塊的函數返回String帶有顏色。好比:python

From fabric.api import green,red
Print (red("This sentence is red, except for " + green("these words, which are green") + "."))

共包括如下：web

fabric.colors.blue(text, bold=False)
fabric.colors.cyan(text, bold=False)
fabric.colors.green(text, bold=False)
fabric.colors.magenta(text, bold=False)
fabric.colors.red(text, bold=False)
fabric.colors.white(text, bold=False)
fabric.colors.yellow(text, bold=False)

Context Managers

Context Managers使用都須要結合with語句。連續使用多個時可嵌套也可用逗號隔開鏈接使用。shell

舉例以下：django

with cd('/path/to/app'):
with prefix('workon myvenv'):
run('./manage.py syncdb')
run('./manage.py loaddata myfixture')

它等價於編程

with cd('/path/to/app'), prefix('workon myvenv'):
run('./manage.py syncdb')
run('./manage.py loaddata myfixture')

注意此時在python2.5中的寫法：with nested(cd('/path/to/app'), prefix('workon myvenv')):api

此類包括：服務器

fabric.context_managers.cd(path) cd(遠程主機更新工做目錄)

任何被包括在 with cd(path):代碼塊裏的命令run/sudo/get/put 至關於執行"cd && "網絡

那麼很明顯它與 shell 命令cd的區別舉例以下：app

with cd('/var/www'):
run('ls') # Turns into "cd /var/www && ls"

比較

run('cd /var/www')
run('ls')

前者至關於執行:run(‘cd /var/www && ls’)

後者至關於執行:ls 時並沒在/var/www 路徑下，而是在默認路徑$HOME路徑下

cd 可嵌套:

with cd('/var/www'):
run('ls') # cd /var/www && ls
with cd('website1'):
run('ls') # cd /var/www/website1 && ls

fabric.contextmanagers.lcd(path) lcd(本地主機更新工做目錄) 同 cd用法相同,只是它改變的的是本地工做目錄,而 cd 改變的遠程主機工做目錄，因此它只能改變local的調用以及put/get的本地參數，它的默認路徑與fabfile所在路徑相關，由環境變量env.realfabfile指定

目前，cd和lcd的實現視是經過改變環境變量env.cwd和env.lcwd實現的，因此若是要實現這個也能夠經過環境變量來實現，可是不建議這麼作。由於按照官方文檔說明，未來這種實現方式可能要改。

fabric.context_managers.hide(*groups) hide(將指定參數輸出級別默認設置爲 False) 指定默認隱藏的輸出級別 group是一個或多個以前output 指定的類別之一，執行時它會將這些輸出類型置爲False。好比你不想看到[hostname]:run:xxxx,以及阻止標準輸出和錯誤就能夠用下面這樣

def my_task():
with hide('running', 'stdout', 'stderr'):
run('ls /var/www')
fabric.context_managers.show(\*groups) show(將指定參數輸出級別默

認設置爲 False) 指定默認輸出的輸出級別用法同 hide，做用恰好相反。默認是全部都輸出，因此show的一個做用就是打開默認隱藏的debug。 fabric.context_managers.path(path, behavior='append') 默認設置爲將參數path附加在系統/用戶環境變量$PATH，即 "PATH=$PATH: "指定 run/sudo 路徑

behavior默認還有兩個參數：

prepend:將指定參數path在$PATH前置即：PATH=<path>:$PATH
replace：將指定參數代替$PATH，即PATH=<path>

fabric.context_managers.prefix(command) prefix( 對於所有包括在其中的run/sudo 命令至關於再給定參數命令後加了&&)

這與cd用法相同，只是在嵌套調用時，它是直接在後面附加字符串，而不是cd中的修改字符串。大多數時候，會用它來export或alter環境變量。

with prefix('workon myvenv'):
run('./manage.py syncdb')

等價於執行#workon myvenv && ./manage.py syncdb

嵌套調用舉例：

with prefix('workon myenv'):
run('ls')
with prefix('source /some/script'):
run('touch a_file')

結果是：

$ workon myenv && ls
$ workon myenv && source /some/script && touch a_file

和cd 是兼容的，結合使用舉例：

with cd('/path/to/app'):
with prefix('workon myvenv'):
run('./manage.py syncdb')
run('./manage.py loaddata myfixture')

結果以下：

$ cd /path/to/app && workon myvenv && ./manage.py syncdb
$ cd /path/to/app && workon myvenv && ./manage.py loaddata myfixture

fabric.context_managers.settings(*args, **kwargs) setting(嵌套的上下文管理器覆蓋env 變量) 它有兩個做用:

大多數狀況下,它會暫時覆蓋/更新任何提到的關鍵字的 env 變量的值。比如 : with settings(user='foo'): 相當於設定env.user=‘foo’。出了這個代碼塊,setting 中的值就會失效。此時注意 clean_revert=True 對做用域的影響,若此時在代碼塊中從新更新 env 的值,則該值就被更新即便出了代碼塊直到下次更新。

# Before the block, env.parallel defaults to False, host_string to None
with settings(parallel=True, host_string='myhost'):
# env.parallel is True
# env.host_string is 'myhost'
env.host_string = 'otherhost'
# env.host_string is now 'otherhost'
# Outside the block:
# * env.parallel is False again
# * env.host_string is None again

另外 , 它還能對 env 變量中未提到的關鍵字（即env變量中沒有的，這些可能會是其餘的上下文管理器）進行指定值 , 比如 :

def my_task():
with settings(
hide('warnings', 'running', 'stdout', 'stderr'),
warn_only=True
):
if run('ls /etc/lsb-release'):
return 'Ubuntu'
elif run('ls /etc/redhat-release'):
return 'RedHat'

最後就是clean_revert設置帶來的變化注意對比前面例子：

# Before the block, env.parallel defaults to False, host_string to None
with settings(parallel=True, host_string='myhost', clean_revert=True):
# env.parallel is True
# env.host_string is 'myhost'
env.host_string = 'otherhost'
# env.host_string is now 'otherhost'
# Outside the block:
# * env.parallel is False again
# * env.host_string remains 'otherhost'

Decorators

fabric.decorators.hosts(\*host_list) 定義哪一個或者哪些主機來執行這些命令,定義方式：
@hosts('host1')
@hosts('host1', 'host2')
@hosts(['host1','host2']))
fabric.decorators.roles(\*role_list) 定義執行任務的 roles,與主機對應
env.roledefs.update({
'webserver': ['www1', 'www2'],
'dbserver': ['db1']})
@roles('webserver', 'dbserver')
def my_func():
pass

同hosts同樣，roles的參數既能夠是一個參數列表，或者一個可迭代對象

fabric.decorators.serial(func) （串行執行，不容許並行）強制func串行執行
fabric.decorators.parallel(pool_size=None) （並行執行，而不是串行）
fabric.decorators.task(\*args, **kwargs) 即新風格任務，參照前面定義任務時的參數給其設定參數
fabric.decorators.with_settings(\*arg_settings, **kw_settings) 做用同於上下文管理器中的with，只是它的做用域應該是整個函數。
@with_settings(warn_only=True)
def foo():
...
fabric.decorators.runs_once(func) 函數僅執行一次

Network

fabric.network.disconnect_all()

用於與全部當前鏈接的服務器斷開鏈接。通常用於 fab 主循環,也同時用於將Fabric做爲類庫使用。

Operations

fabric.operations.get(remote_path, local_path=None)從遠程主機下載一個或多個文件
fabric.operations.put(local_path, remote_path, use_sudo=False, mirror_local_mode=False, mode=None) 從本地上傳一個或多個文件至遠程主機

不少時候用法相似scp或cp,用於上傳下載文件，它的本地和遠程路徑實現發別是經過lcd和cd實現，因此用上下文管理器的cd會影響遠程路徑參數，而lcd會影響本地路徑參數。這裏主要是弄明白本地路徑和遠程路徑的表示，它們將路徑分紅host/dirname/basename/path，可分別用基於字典的方式來指定，這裏具體可查文檔說明。

fabric.operations.open_shell(command=None) 在遠程主機調用交互式shell。

若是命令給定，它將會在調用用戶以前被送至管道。當你須要一個徹底基於shell調用和一系列命令

時很是有用，好比debug的時候。這能夠被看做是run的簡單版，但並非可替代版，由於它沒法

處理遠程交互中遇到的prompt，標準輸入，login等問題。此外，它沒有返回值並且在發生錯誤時也

不會有fabric的錯誤處理機制。

fabric.operations.reboot(wait=120)

重啓遠程機器,會暫時調整fabric衝鏈接設置以保證在wait時間內重鏈接成功。

fabric.operations.run(command, shell=True, pty=True, combine_stderr=True)在遠程主機執行shell命令。

若是shell爲True,run會將給定的命令經過env.shell設定的shell上解釋。命令參數中任何雙引號「和$符都會被忽略。

run會將遠程程序的標準輸出做爲一個單一（可能多行）string做爲結果返回。這個string包括布爾值的failed和succeed的屬性來標誌命令執行的成功與失敗，

以及一個結果碼來作爲返回的 return_code屬性。

本地終端的任何文本的輸入在run執行過程當中都會被送往遠程程序，來容許你更天然地處理密碼和其餘prompts。

你可使用pty=False來放棄在遠程主機上建立僞終端以防其在命令存在問題時會製造麻煩。然而，這會強制fabric本身在run運行時echo全部的輸入和你的鍵入，包括大小寫敏感的密碼。遠程僞終端會替你echo，並且會只能的處理密碼這種prompts。

一樣地，若是你須要編程檢測遠程程序的標準錯誤流（利用函數返回值的stderr屬性），你能夠設置combinestderr=False。這樣作會使你終端輸出很混亂（雖然返回strings能合理地分開）。可是這是你單獨獲取標準錯誤流的惟一方式。設置pty=combinestderr=False。

fabric.operations.sudo(command, shell=True, pty=True, combine_stderr=True, user=None)

以上連個命令都是在遠程執行命令,後者擁有特殊權限,關於參數含義已經在遠程交互中詳細介紹和run中介紹。

它們的返回結果是一個多行 string,這個 string 會有 failed, succeeded,return_code 這樣的屬性來標識是否執行成功。

一樣地，若是你須要編程檢測遠程程序的標準錯誤流（利用函數返回值的stderr屬性），你能夠設置combine_stderr=False。這樣作會使你終端輸出很混亂（雖然返回strings能合理地分開）。

sudo會多接受一個user的參數，這用來容許你在其餘用戶而不是root用戶來執行命令。在不少系統，user能夠是string的username或者是int的uid。

此外上述各函數都有相應的參數爲（args, *kwargs）的重載函數。

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

使用 python subprocess 模塊實現且 shell=True,local 如今可以打印和捕捉輸出,正如 run/sudo 同樣。caputure 參數容許你選擇是打印仍是捕捉輸出。

caputure=False 時,本地 subprocess 的標準輸出和錯誤直接顯示在終端,可經過全局輸出控制,output.stdout 等,此時返回爲空。
caputure=True 時,命令 stdout 做爲類 string 對象返回,同 run/sudo 同樣,返回值有 return_code,stderr,failed 和 succeeded 屬性。

Tasks

class fabric.tasks.Task(alias=None, aliases=None, default=False, args, *kwargs) 對於抽象基類和子類處理不一樣詳細參數含義可參考定義任務中新風格任務的參數含義。

fabric.tasks.execute(task, args, *kwargs) 執行任務不管是新風格的任務名仍是經典風格的可調用對象。

任務會在該任務主機列表中每一個主機上執行一遍，這些主機列表包括來自命令行-H,裝飾器@hosts,@roles,env.hosts等等。

host/hosts/role/roles、exclude_hosts均可以做爲參數傳遞進去來設置該任務的主機列表。

若是task還有其餘參數須要傳遞，好比

execute(mytask, 'arg1', kwarg1='value')將會執行
mytask('arg1', kwarg1='value')

它的執行結果也是按字典形式返回，好比execute(foo,hosts=['a', 'b'])

結果多是{'a': None, 'b': 'bar'}

若是設置了skipbadhosts則該主機返回值可能爲錯誤對象或消息。

Utils

fabric.utils.abort(msg)放棄執行，打印msg爲stderr和錯誤狀態。
fabric.utils.error(message, func=None, exception=None, stdout=None, stderr=None)調用func，給出指定錯誤、輸出等信息。
fabric.utils.fastprint(text, show_prefix=False, end='', flush=True)
fabric.utils.indent(text, spaces=4, strip=False)同puts相同，只是不一樣的參數，快速打印文本text,不用等行結尾。
fabric.utils.puts(text, show_prefix=None, end='\n', flush=False)
fabric.utils.warn(msg)打印警告信息，可是不放棄執行。