オペレーション¶
fabfile内とその他のコア以外のコードで使われるrun()/sudo()などの関数です。
-
fabric.operations.
get
(*args, **kwargs)¶ リモートホストから一つもしくは複数のファイルをダウンロードします。
get
はダウンロードしたすべてのローカルファイルへの絶対パスを含む反復可能オブジェクトを返します。これはもしlocal_path
がStringIOオブジェクトの場合には空になります(StringIOオブジェクト利用時についての詳細は下の方を参照してください)。このオブジェクトはまた、ダウンロードに失敗したすべてのリモートファイルのパスを含む.failed
属性とnot .failed
と同等の.succeeded
属性を提示します。remote_path
はダウンロードするリモートファイルもしくはリモートディレクトリのパスで、例えば"/var/log/apache2/*.log"
などのシェルglogシンタックスを含むことができ、チルダはリモートのホームディレクトリに置き換えます。相対パスはリモートのユーザーのホームディレクトリからの相対位置として、もしくは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')
のような呼び出しは、var/log/apache2/access.log
ではなくローカルのファイル名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
属性を持つ場合、デフォルトの<file obj>
の代わりにそれがFabricの出力に使われます。バージョン 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
はshell=True
が有効化されているPythonビルトインのsubprocess
モジュールの便利なラッパーです。なにか特別なことをする必要がある場合はsubprocess
モジュールを直接使うことを検討してください。shell
はダイレクトに subprocess.Popen のexecute
引き数(これが利用するローカルのシェルを決めます)に渡されます。リンク先のドキュメントにあるように、Unixではデフォルトでは/bin/sh
を使います。したがって、例えばこの値を/bin/bash
などに設定したい場合に便利です。local
はいまのところrun
/sudo
のように出力を同時にプリントしたりキャプチャしたりすることはできません。capture
キーワード引き数によって、必要に応じてプリントとキャプチャを切り替えることができ、デフォルトはFalse
になっています。capture=False
の時、ローカルのサブプロセスの標準出力と標準エラー出力のストリームはターミナルに直接繋がれます。これはグローバルの output controlsoutput.stdout
とoutput.stderr
を使って片方もしくは両方を必要に応じて隠すことができます。このモードでは返り値の標準出力/標準エラー出力は常に空になります。capture=True
の時には、ターミナルにはサブプロセスからのどんな出力も表示されませんが、返り値にはキャプチャされた標準出力/標準エラー出力が含まれます。どちらにせよ、
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)¶ リモート側で完全な対話式シェルを起動します。
command
が与えられると、起動ユーザーにコントロールが渡される前にそれがパイプに送り込まれます。この機能は、大量のシェルベースのコマンドや、デバッギング時やリモート側プログラムの障害に要する完全にインタラクティブなリカバリー作業時などの一連のコマンドとのやりとりが必要なときにとても役に立ちます。
Fabricスクリプトの途中にインタラクティブなシェルセッションを組み入れるのは簡単な方法とみなすべきで、
run
のドロップインの代替ではありません。また、リモート側とのやりとりが可能で(与えられたコマンドが実行されているときだけですが)、エラー処理や標準出力/標準エラー出力のキャプチャのようなとても強いプログラム能力を持ちます。厳密には、
open_shell
はrun
よりも良いインタラクティブな体験をもたらします。しかし完全なリモートシェルの利用は、シェル内でのプログラムの起動に失敗したのかどうかをFabricが判別するのを妨げ、ログインバナー、プロンプト、エコーされた標準入力などのシェルの出力で標準出力/標準エラー出力が判別しにくくなります。そのため、この関数は返り値を持たず、どんなリモートプログラムがエラーで終わっても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")
のような呼び出しは ([foo]
の後ろにスペースをともなった)What hostname? [foo]
のプロンプトとして表示されます。オプションのキーワード引き数
validate
は呼び出し可能なもの、もしくは文字列です:- 呼び出し可能なものの場合、ユーザーの入力とともに呼び出され、成功時に格納される値を返します。失敗時には例外メッセージとともに例外を発生させ、ユーザーに表示されます。
- 文字列の場合、
validate
に渡される値は正規表現として使用されます。そのため、この場合は生の文字列を使用することをおすすめします。正規表現に関する注意点ですが、(^
と$
で区切られた)完全マッチではない場合は、そうなるようにします。つまり、入力は正規表現に完全にマッチさせます。
どちらにせよ、バリデーションに通るまで(もしくはユーザーが
Ctrl-C
を押すまで)prompt
は再度入力を待ちます。注釈
prompt
は env.abort_on_prompts を優先し、このフラグがTrue
にセットされている場合はプロンプトを表示する代わりにabort
を呼び出します。もそこれにかかわらずユーザーの入力をブロックしたい場合は、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
属性を提示します。local_path
はローカルのファイルもしくはディレクトリの相対もしくは絶対パスで、Pythonのglob
モジュールによって理解されるよう(この挙動を無効にしたい場合はuse_glob=False
としてください)、シェルスタイルのワイルドカードを含むことがあります。(os.path.expanduser
によって実装されている)チルダの展開も実行されます。local_path
は、open('path')
の結果やStringIO
のインスタンスなど、ファイルライクなオブジェクトであることも可能です。注釈
この場合、
put
はseek
を使ってリワインドすることによりファイル形式オブジェクトのコンテンツ全体を読み取ろうとします(そして前回のファイル位置を保存するためにその後にtell
を使います)。remote_path
は相対的もしくは絶対的な場所で、リモートホストに適用されるものです。相対パスはリモートユーザーのホームディレクトリに対する相対で、必要に応じてチルダ展開(例えば~/.ssh/
)が実施されます。どちらのパス引き数も空の文字列の場合、適切な側のカレントワーキングディレクトリによって置き換えられます。
SFTPプロトコル(
put
が利用します)には接続ユーザーによって所有されていない場所へファイルをアップロードする直接的な方法はありませんが、use_sudo=True
と指定することによりこれが可能になります。これがセットされたとき、この設定によりput
はローカルファイルをリモート側の一時フィアル保管場所(デフォルトではリモートユーザーの$HOME
ですが、temp_dir
によって上書き可能です)にアップロードし、それからsudo
を利用してそれらのファイルをremote_path
に移動します。場合によっては、新しくアップロードしたファイルのモードを強制的にローカル側のものと一致させたほうが望ましいこともあります(実行可能ファイルをアップロードした時など)。これを行うには
mirror_local_mode=True
を指定します。代わりに、
os.chmod
もしくはUnixのchmod
コマンドと同様にmode
キーワード引き数を使って同じモードを指定することもできます。put
はcd
を優先するので、もしあれば、remote_path
の相対値がリモートのカレントワーキングディレクトリによって追加されます。したがって、以下の例では~/files/test.txt
ではなく/tmp/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
属性を持つ場合、デフォルトの<file obj>
の代わりにそれがFabricの出力に使われます。バージョン 1.0 で変更:
local_path
引き数にファイルライクなオブジェクトが使えます。バージョン 1.0 で変更: ディレクトリは
local_path
引き数で明示することができ、再帰的なアップロードを実行します。バージョン 1.0 で変更: 返り値はアップロードされたローカルファイルのパスの反復可能オブジェクトで、
.failed
と.succeeded
属性を提示します。バージョン 1.5 で変更: ログ出力にファイルライクなオブジェクトへの
name
属性を許可するようになりました。バージョン 1.7 で変更: globを無効にできるように
use_glob
オプションを追加。
-
fabric.operations.
reboot
(*args, **kwargs)¶ リモートシステムを再起動します。
これは一時的にFabricの再接続設定 (timeout と connection_attempts) を調整し、少なくとも
wait
秒は再接続を止めないようにします。注釈
Fabric 1.4以降では一つのセッション途中での再接続の機能は内部APIの利用を必要とはしません。この機能を公式には非推奨とはしませんが、これにさらに機能を追加することは優先度としては低いです。
より細かく制御したいユーザーは、この関数のソースコード(6行で、よくコメントしてあります)をチェックし、異なるタイムアウト/試行値または追加のロジックを使用して独自の変更を書くことを奨励します。
バージョン 0.9.2 で追加.
バージョン 1.4 で変更:
wait
キーワード引き数を任意に変更し、新しい再接続機能を活用するようにリファクタリング。実際には、再接続前にwait
秒待つ必要はないかもしれない。
-
fabric.operations.
require
(*keys, **kwargs)¶ 共有環境辞書に与えられているキーをチェックし、なければ中止します。
位置指定引数は文字列で、どの環境変数をチェックするのかを指定します。与えられた引き数がどれでも存在しない場合は、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
が True (デフォルト)の場合、run
はシェルインタープリター経由で渡されるコマンドを実行します。この値はenv.shell
(デフォルトは/bin/bash -l -c "<command>"
と同様なものです)の設定によって制御可能です。shell
が True のとき、コマンド内の二重引用符 ("
) またはドルマーク ($
) 文字は自動的にエスケープされます。run
は単一の文字列(おそらくは複数行)としてリモートプログラムの標準出力の結果を返します。この文字列はそのコマンドが成功したか失敗したかを明記するためfailed
とsucceeded
の真偽値属性を提示し、return_code
属性としてのリターンコードも含みます。さらに、それぞれ.command
と.real_command
として、リクエストされ、実際に実行されたコマンド文字列のコピーも含んでいます。ローカルのターミナルに入力したすべてのテキストは、それが実行されるたびにリモートに送られます。つまり、パスワードやその他のプロンプトと自然な感じでやりとりできるようにします。この挙動の詳細は リモートプログラムとのやりとり をご覧ください。
該当のコマンドにとってその存在が問題になる場合は、リモート側の擬似ターミナルの生成に先立って
pty=False
を渡すこともできます。とは言え、そうするとそのコマンドの実行中はタイプした入力をパスワードも含めてすべてエコーするようFabricに強制します。(pty=True
であれば、リモートの擬似ターミナルはエコーするものの、パスワードスタイルのプロンプトは賢く扱います) 詳細は 擬似ターミナル をご覧ください。同じように、リモートプログラムの標準エラー出力ストリーム(この関数の返り値に
stderr
として明示されます)をプログラム的に調べる必要がある場合は、combine_stderr=False
をセットすることができます。これを設定すると高い確率で自分のターミナルでの出力を文字化けさせてしまいます(run
によって返される結果文字列は適切に分離されていますが)詳細は 標準出力と標準エラー出力の結合 をご覧ください。ゼロ以外のリターンコードを無視するには
warn_only=True
を指定します。ゼロ以外のコードの無視とコマンドのサイレント実行の強制の両方を行うにはquiet=True
を指定します。リモート側の標準出力および/もしくは標準エラー出力の表示にどのローカルのストリームを使用するかをオーバーライドするには
stdout
もしくはstderr
を指定します。例えば、
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
キーワード引き数、インタラクティブな挙動。バージョン 1.0 で変更:
pty
のデフォルト値をTrue
に変更しました。バージョン 1.0.2 で変更:
combine_stderr
のデフォルト値がTrue
ではなくNone
になりました。しかし、デフォルトの 挙動 に変更はなく、グローバルなセッティングはTrue
のままです。バージョン 1.5 で追加:
quiet
、warn_only
、stdout
、stderr
キーワード引き数。バージョン 1.5 で追加: 返り値属性の
.command
と.real_command
。バージョン 1.6 で追加:
timeout
引き数。バージョン 1.7 で追加:
shell_escape
引き数。
-
fabric.operations.
sudo
(*args, **kwargs)¶ リモートホストに対してスーパーユーザー権限でシェルコマンドを実行します。
sudo
はスーパーユーザー権限を提供するために与えられたcommand
をsudo
プログラムへの呼び出し内にラップする以外は、あらゆる点でrun
と同一です。sudo
は追加でuser
とgroup
の引き数を取ります。これはsudo
に渡され、root以外のuserやgroupとして実行できるようにします。たいていのシステムでは、sudo
プログラムはusername/groupの文字列もしくはuserid/groupid (uid/gid) の整数値をとることができます。user
とgroup
は同じように文字列もしくは整数値となります。モジュールレベル、もしくは同じ
user
の値を持つ複数のsudo
呼び出しを行う場合は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
キーワード引き数。バージョン 1.5 で追加: 返り値属性の
.command
と.real_command
。バージョン 1.7 で追加:
shell_escape
引き数。