オペレーション¶
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引き数。
