プロジェクトツール

コア以外の便利な機能。例えば複数オペレーションを構成する機能。

fabric.contrib.project.rsync_project(*args, **kwargs)

rsync 経由でリモートディレクトリとカレントのプロジェクトディレクトリを同期します。

upload_project() は実行されるたびに scp を利用してプロジェクト全体をコピーしますが、rsync_project() は rsync を利用し、リモート側のファイルよりも新しいファイルのみを転送します。

rsync_project() は rsync の単純なラッパーです。 rsync の動作に関する詳細はそのmanページをご覧ください。この操作が正しく動作するためにはローカルとリモートシステムの両方に rsync がインストールされている必要があります。

この機能はFabricの local() オペレーションを利用し、その関数呼び出しの出力を返します。つまり、(もしあれば) rsync の呼び出し結果の標準出力が返ってきます。

rsync_project() は次のパラメータを取ります:

  • remote_dir: 唯一の必須のパラメータで、リモートサーバー上のディレクトリへのパスです。 rsync がそのように実装されているため、その挙動は local_dir の値に依存します:

    • local_dir が末尾のスラッシュで終わっている場合、ファイルは remote_dir 内にアップロードされます。例えば、 rsync_project("/home/username/project/", "foldername/") は /home/username/project 内の foldername のコンテンツとなります。
    • local_dir が スラッシュで終わっていない 場合(これにはデフォルトのシナリオの local_dir が指定されていない場合も含まれます)、remote_dir は実質的に "親" ディレクトリとなり、その中に local_dir の名称の新しいディレクトリが作成されます。したがって、 rsync_project("/home/username", "foldername") は(必要であれば)新しいディレクトリ /home/username/foldername を作り、ファイルをそこにコピーします。

  • local_dir: デフォルトでは、rsync_project はカレントのワーキングディレクトリをソースディレクトリとして利用します。これは local_dir を指定することでオーバーライドすることができます。 local_dir は rsync にそのまま渡される文字列で、単一のディレクトリ ("my_directory") もしくは複数のディレクトリ ("dir1 dir2") とすることが可能です。詳細は rsync のドキュメントをご覧ください。

  • exclude: これはオプションで、単一の文字列、もしくは文字列の繰り返し可能オブジェクトとすることが可能で、単一もしくは複数の --exclude オプションとして rsync に渡されるために利用されます。

  • delete: rsync の --delete オプションを使用するかどうかをコントロールする真偽値です。True なら、 rsync に指示してローカルには存在しなくなったファイルをリモート側でも削除します。デフォルトでは False になっています。

  • extra_opts: オプションで、カスタムな引き数やオプションを rsync に渡すための任意の文字列です。

  • ssh_opts: extra_opts と似ていますが、SSH のオプション文字列 (rsync の --rsh フラグ) 用です。

  • capture: local 呼び出しの内部に直接送られます。

  • upload: ファイル同期の実行をアップストリームで行うのかダウンストリームで行うのかをコントロールする真偽値です。デフォルトはアップストリームです。

  • default_opts: デフォルトの rsync のオプションの -pthrvz で、必要に応じてオーバライドします(詳細表示(verbosity)をとりのぞくなど)。

さらに、この関数はFabricのポートとSSHキー設定を透過的に優先します。カレントホストの文字列に非標準のポートが含まれている場合や env.key_filename が空ではない場合にこの関数を呼び出すと、その指定したポート及び/もしくはSSH鍵ファイル名(複数可)を使用します。

参考までに、この関数によって構成される rsync コマンドラインの概要は次のようになっています:

rsync [--delete] [--exclude exclude[0][, --exclude[1][, ...]]] \
    [default_opts] [extra_opts] <local_dir> <host_string>:<remote_dir>

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

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

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

fabric.contrib.project.upload_project(local_dir=None, remote_dir='', use_sudo=False)

カレントのプロジェクトを tar/gzip 経由でリモートシステムにアップロードします。

local_dir はアップロードするローカルのプロジェクトディレクトリを指定します。デフォルトはカレントのワーキングディレクトリです。

remote_dir アップロード先のターゲットディレクトリを指定します(つまり、remote_dir のサブディレクトリとして local_dir のコピーができます)。デフォルトはリモートユーザーのホームディレクトリです。

use_sudo はリモートでコマンドを実行するさいの使用するメソッドを指定します。use_sudo が True のときは sudo が使用され、その他は run が使用されます。

この関数は tar と gzip のプログラム/ライブラリを利用します。そのため、Win32 システムでは Cygwin もしくは類似のものを使用しない限りうまく動作しないでしょう。実行後、たとえ失敗に終わっても、ローカルとリモートのtarファイルの削除を試みます。

バージョン 1.1 で変更: local_dir と remote_dir キーワード引き数を追加しました。

バージョン 1.7 で変更: use_sudo キーワード引き数を追加しました。