オペレーション

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.pysrc/projectname などのリモートファイルパスのディレクトリ部分です。

  • basename: src/projectname/utils.pyutils.py などのリモートファイルパスのファイル名部分です。

  • path: src/projectname/utils.py などのリモートのフルパスです。

While the SFTP protocol (which get uses) has no direct ability to download files from locations not owned by the connecting user, you may specify use_sudo=True to work around this. When set, this setting allows get to copy (using sudo) the remote files to a temporary location on the remote end (defaults to remote user’s $HOME; this may be overridden via temp_dir), and then download them to local_path.

ノート

remote_path がディレクトリの絶対パスのとき、内部ディレクトリだけがローカルに作られて上記の変数に渡されます。例えば、get('/var/log', '%(path)s') は、ローカルのワーキングディレクトリで apache2/access.logpostgresql/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 が上記の変数(例えば、単純な場合では指定されたファイルパス)を使用していない場合、 scpcp と似た動作をします。必要に応じて既存のファイルを上書きし、ディレクトリが与えられた場合はそのディレクトリへのダウンロードされます(例えば、get('/path/to/remote_file.txt', 'local_directory')local_directory/remote_file.txt を作成します)。

もしくは local_path は、 open('path', 'w') の結果や StringIO のインスタンスなど、ファイルライクなオブジェクトであることも可能です。

ノート

ディレクトリをファイルライクなオブジェクトに get して入れようとするのは無効で、エラーになります。

ノート

この関数は seektell を使ってファイルライクなオブジェクトのコンテンツ全体を上書きします。これは put (ファイル全体も考慮します)の挙動と一致させるためです。とはいえ、 put とは違い、このファイルポインターは前のロケーションには戻されません。これは意味を成さないですし、不可能でもあります。

ノート

StringIO が name 属性を持つ場合、デフォルトの <file obj> の代わりにそれがFabricの出力に使われます。

バージョン 1.0 で変更: リモートのワーキングディレクトリを cd で操作されたものとしてみなし、ローカルのワーキングディレクトリを lcd で操作されたものとしてみなします。

バージョン 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)

ローカルシステム上でコマンドを実行します。

localshell=True が有効化されているPythonビルトインの subprocess モジュールの便利なラッパーです。なにか特別なことをする必要がある場合は subprocess モジュールを直接使うことを検討してください。

shell はダイレクトに subprocess.Popenexecute 引き数(これが利用するローカルのシェルを決めます)に渡されます。リンク先のドキュメントにあるように、Unixではデフォルトでは /bin/sh を使います。したがって、例えばこの値を /bin/bash などに設定したい場合に便利です。

local はいまのところ run/sudo のように出力を同時にプリントしたりキャプチャしたりすることはできません。 capture キーワード引き数によって、必要に応じてプリントとキャプチャを切り替えることができ、デフォルトは False になっています。

capture=False の時、ローカルのサブプロセスの標準出力と標準エラー出力のストリームはターミナルに直接繋がれます。これはグローバルの output controls output.stdoutoutput.stderr を使って片方もしくは両方を必要に応じて隠すことができます。このモードでは返り値の標準出力/標準エラー出力は常に空になります。

capture=True の時には、ターミナルにはサブプロセスからのどんな出力も表示されませんが、返り値にはキャプチャされた標準出力/標準エラー出力が含まれます。

In either case, as with run and sudo, this return value exhibits the return_code, stderr, failed, succeeded, command and real_command attributes. See run for details.

locallcd コンテキストマネージャーを優先し、これによりリモート側とは切り離して(これは cd を優先)カレントのワーキングディレクトリをコントロールできるようにします。

バージョン 1.0 で変更: succeededstderr 属性を追加しました。

バージョン 1.0 で変更: lcd コンテキストマネージャーを優先するようになりました。

バージョン 1.0 で変更: capture のデフォルト値を True から False に変更しました。

バージョン 1.9 で追加: 返り値属性の .command.real_command

fabric.operations.open_shell(*args, **kwargs)

リモート側で完全な対話式シェルを起動します。

command が与えられると、起動ユーザーにコントロールが渡される前にそれがパイプに送り込まれます。

この機能は、大量のシェルベースのコマンドや、デバッギング時やリモート側プログラムの障害に要する完全にインタラクティブなリカバリー作業時などの一連のコマンドとのやりとりが必要なときにとても役に立ちます。

Fabricスクリプトの途中にインタラクティブなシェルセッションを組み入れるのは簡単な方法とみなすべきで、run のドロップインの代替ではありません。また、リモート側とのやりとりが可能で(与えられたコマンドが実行されているときだけですが)、エラー処理や標準出力/標準エラー出力のキャプチャのようなとても強いプログラム能力を持ちます。

厳密には、open_shellrun よりも良いインタラクティブな体験をもたらします。しかし完全なリモートシェルの利用は、シェル内でのプログラムの起動に失敗したのかどうかを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 は再度入力を待ちます。

ノート

promptenv.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 のインスタンスなど、ファイルライクなオブジェクトであることも可能です。

ノート

この場合、putseek を使ってリワインドすることによりファイル形式オブジェクトのコンテンツ全体を読み取ろうとします(そして前回のファイル位置を保存するためにその後に 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 キーワード引き数を使って同じモードを指定することもできます。

putcd を優先するので、もしあれば、 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 で変更: リモートのワーキングディレクトリを cd で操作されたものとしてみなし、ローカルのワーキングディレクトリを lcd で操作されたものとしてみなします。

バージョン 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の再接続設定 (timeoutconnection_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 は単一の文字列(おそらくは複数行)としてリモートプログラムの標準出力の結果を返します。この文字列はそのコマンドが成功したか失敗したかを明記するため failedsucceeded の真偽値属性を提示し、 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 は秒の整数値で、これより時間がかかるとタイムアウトさせます。これは runCommandTimeout の例外を発生させます。

引用符やドルマークなどに対する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 で追加: succeededstderr の返り値の属性、combine_stderr キーワード引き数、インタラクティブな挙動。

バージョン 1.0 で変更: pty のデフォルト値を True に変更しました。

バージョン 1.0.2 で変更: combine_stderr のデフォルト値が True ではなく None になりました。しかし、デフォルトの 挙動 に変更はなく、グローバルなセッティングは True のままです。

バージョン 1.5 で追加: quietwarn_onlystdoutstderr キーワード引き数。

バージョン 1.5 で追加: 返り値属性の .command.real_command

バージョン 1.6 で追加: timeout 引き数。

バージョン 1.7 で追加: shell_escape 引き数。

fabric.operations.sudo(*args, **kwargs)

リモートホストに対してスーパーユーザー権限でシェルコマンドを実行します。

sudo はスーパーユーザー権限を提供するために与えられた commandsudo プログラムへの呼び出し内にラップする以外は、あらゆる点で run と同一です。

sudo は追加で usergroup の引き数を取ります。これは sudo に渡され、root以外のuserやgroupとして実行できるようにします。たいていのシステムでは、sudo プログラムはusername/groupの文字列もしくはuserid/groupid (uid/gid) の整数値をとることができます。usergroup は同じように文字列もしくは整数値となります。

モジュールレベル、もしくは同じ 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 で追加: quietwarn_onlystdoutstderr キーワード引き数。

バージョン 1.5 で追加: 返り値属性の .command.real_command

バージョン 1.7 で追加: shell_escape 引き数。