「翻訳ドキュメント/WritingPlugins」の編集履歴（バックアップ）一覧はこちら

「翻訳ドキュメント/WritingPlugins」(2009/02/11 (水) 19:41:35) の最新版変更点

追加された行は緑色になります。

削除された行は赤色になります。

このページは[[Bazaar 公式 Using Bazaar WritingPlugins>>http://bazaar-vcs.org/WritingPlugins]] の日本語訳です。

----

#contents()

( Bazaar 開発者ドキュメントの [[Plugin API>>http://doc.bazaar-vcs.org/bzr.dev/developers/plugin-api.html]] も参照してください)

*プラグインを作成する
プラグインは、bzr のコード変更なしに bzr の機能の拡張、または bzr の振る舞いの置き換えをすることができます。プラグインを書くことは、新しいコマンドを作成したり現在のコマンドの振る舞いを置き換えるための推奨されている方法です。

通常、プラグインは特定のユーザの ~/.bazaar/plugins/ にインストールされています。
これらのプラグインはたいがいシンプルな Python モジュール ( 例. foo.py ) か、Python パッケージ ( ディレクトリの中に __init__.py ファイルが含まれている ) です。
一般に、私たちはそれらがディレクトリであることをお勧めしています、そしてあなたのプラグインのバージョンコントロールをすることができます ( もちろん Bazaar を使用して ) :

 cd ~/.bazaar
 mkdir plugins
 bzr init foo
 cd foo
 touch __init__.py

*新しいコマンドを定義する
Bzr コマンドは、bzrlib.commands.Command クラスのサブクラスとして定義されます。コマンド名はサブクラス名によって指定されます。そしてそれらをインポートするときに、bzrlib.commands.register_command 関数を使用して bzr に登録しなければなりません。

foo-bar コマンドを bzr に定義する:
 from bzrlib.commands import Command, register_command
 
 class cmd_foo_bar(Command):
   # see bzrlib/builtins.py for information about what to put here
   pass
 
 register_command(cmd_foo_bar)

If the class name starts with cmd, the prefix will get dropped and _ will be replaced by - characters.

**コマンドクラスの属性
Base class for commands. Commands are the heart of the command-line bzr interface.

The command object mostly handles the mapping of command-line parameters into one or more bzrlib operations, and of the results into textual output.

Commands normally don't have any state. All their arguments are passed in to the run method. (Subclasses may take a different policy if the behaviour of the instance needs to depend on e.g. a shell plugin and not just its Python class.)

The docstring for an actual command should give a single-line summary, then a complete description of the command. A grammar description will be inserted.

:aliases|Other accepted names for this command.

:takes_args|List of argument forms, marked with whether they are optional, repeated, etc.&br()For example: ['to_location', 'from_branch?', 'file*'] means:&br()
-'to_location' is required
-'from_branch' is optional
-'file' can be specified 0 or more times

:takes_options|List of options that may be given for this command. These can be either strings, referring to globally-defined options, or option objects. Retrieve through options().

:hidden|If true, this command isn't advertised. This is typically for commands intended for expert users.

**Command.run メソッド
Actually run the command.

This is invoked with the options and arguments bound to keyword parameters.

Return 0 or None if the command was successful, or a non-zero shell error code if not. It's OK for this method to allow an exception to raise up.

**register_command 機能
Utility function to help register a command.

:param cmd|Command subclass to register
:param decorate|If true, allow overriding an existing command of the same name; the old command is returned by this function. Otherwise it is an error to try to override an existing command.

*プラグインのテスト
"bzr selftest" コマンドを実行すると、Bazaar はすべてのプラグインをスキャンしてプラグインに test_suite() 関数が含まれているかどうかを調べます。それぞれのプラグインのスキャンが完了すると test_suite() 関数を実行し、テスト結果をマスターテストスイートに追加します。

*プラグインと起動時間
bzr は起動時にすべてのプラグインをインポートしますので、使われていないプラグインがあると性能を下げてしまいます。しかしながら main name 以外のサブモジュールはロードされません。

このスローダウンを回避する一つの方法は、コードの大部分をサブモジュールに入れてしまい、プラグイン自体を小さくしてしまうことです。本当に __init__.py で必要とされているのは、プラグインのコマンドクラス、それらを登録するコマンドと、オプションで test_suite() だけです。

別の方法であなたのプラグインのオーバーヘッドを削減する方法は、bzrlib lazy_import 機能を使用することです。これはこのようになっています。

 from bzrlib.lazy_import import lazy_import
 lazy_import(globals(), """
 from bzrlib import (
     branch as _mod_branch,
     option,
     workingtree,
     )
 """)

Lazy インポートは、パッケージとモジュールだけに使用することができます。クラスや関数には使用することができません。これは本当に必要になるまでパッケージやモジュールをインポートしません。

*進んだ設定
ユーザのプラグインを見つけるフォルダ ( ~/.bazaar/plugins  デフォルトで ) を 環境変数BZR_PLUGIN_PATH を設定することでオーバーライドすることができます。

bzr の bzrlib/plugins にインストールされているプラグインはシステム全体で使用できます。

**コールバックでプラグインの機能を起動する
Bazaar のブランチ 0.15 からは、複数のフックをする方法があります。新しいフックを追加するには以下のようにします。

 import bzrlib.branch
 bzrlib.branch.Branch.hooks.install_hook(HOOK_NAME, MY_FUNCTION)

**現在のフック
http://doc.bazaar-vcs.org/bzr.dev/en/user-reference/bzr_man.html#hooks をご覧ください。

*さらなる情報
[[Integrating_with_Bazaar>>http://bazaar-vcs.org/Integrating_with_Bazaar]] で、add, commit, log などなどをどのようにして操作をするか説明されています。

このページは[[Bazaar 公式 Using Bazaar WritingPlugins>>http://bazaar-vcs.org/WritingPlugins]] の日本語訳です。

----

#contents()

( Bazaar 開発者ドキュメントの [[Plugin API>>http://doc.bazaar-vcs.org/bzr.dev/developers/plugin-api.html]] も参照してください)

*プラグインを作成する
プラグインは、bzr のコード変更なしに bzr の機能の拡張、または bzr の振る舞いの置き換えをすることができます。プラグインを書くことは、新しいコマンドを作成したり現在のコマンドの振る舞いを置き換えるための推奨されている方法です。

通常、プラグインは特定のユーザの ~/.bazaar/plugins/ にインストールされています。
これらのプラグインはたいがいシンプルな Python モジュール ( 例. foo.py ) か、Python パッケージ ( ディレクトリの中に __init__.py ファイルが含まれている ) です。
一般に、私たちはそれらがディレクトリであることをお勧めしています、そしてあなたのプラグインのバージョンコントロールをすることができます ( もちろん Bazaar を使用して ) :

 cd ~/.bazaar
 mkdir plugins
 bzr init foo
 cd foo
 touch __init__.py

*新しいコマンドを定義する
Bzr コマンドは、bzrlib.commands.Command クラスのサブクラスとして定義されます。コマンド名はサブクラス名によって指定されます。そしてそれらをインポートするときに、bzrlib.commands.register_command 関数を使用して bzr に登録しなければなりません。

foo-bar コマンドを bzr に定義する:
 from bzrlib.commands import Command, register_command
 
 class cmd_foo_bar(Command):
   # see bzrlib/builtins.py for information about what to put here
   pass
 
 register_command(cmd_foo_bar)

If the class name starts with cmd, the prefix will get dropped and _ will be replaced by - characters.

**コマンドクラスの属性
Base class for commands. Commands are the heart of the command-line bzr interface.

The command object mostly handles the mapping of command-line parameters into one or more bzrlib operations, and of the results into textual output.

Commands normally don't have any state. All their arguments are passed in to the run method. (Subclasses may take a different policy if the behaviour of the instance needs to depend on e.g. a shell plugin and not just its Python class.)

The docstring for an actual command should give a single-line summary, then a complete description of the command. A grammar description will be inserted.

:aliases|Other accepted names for this command.

:takes_args|List of argument forms, marked with whether they are optional, repeated, etc.&br()For example: ['to_location', 'from_branch?', 'file*'] means:&br()
-'to_location' is required
-'from_branch' is optional
-'file' can be specified 0 or more times

:takes_options|List of options that may be given for this command. These can be either strings, referring to globally-defined options, or option objects. Retrieve through options().

:hidden|If true, this command isn't advertised. This is typically for commands intended for expert users.

**Command.run メソッド
Actually run the command.

This is invoked with the options and arguments bound to keyword parameters.

コマンド実行が成功した場合 0 もしくは None が返ります、成功ではない場合は 0 以外の Shell エラーコードが帰ります。

Return 0 or None if the command was successful, or a non-zero shell error code if not. It's OK for this method to allow an exception to raise up.

**register_command 機能
Utility function to help register a command.

:param cmd|Command subclass to register
:param decorate|If true, allow overriding an existing command of the same name; the old command is returned by this function. Otherwise it is an error to try to override an existing command.

*プラグインのテスト
"bzr selftest" コマンドを実行すると、Bazaar はすべてのプラグインをスキャンしてプラグインに test_suite() 関数が含まれているかどうかを調べます。それぞれのプラグインのスキャンが完了すると test_suite() 関数を実行し、テスト結果をマスターテストスイートに追加します。

*プラグインと起動時間
bzr は起動時にすべてのプラグインをインポートしますので、使われていないプラグインがあると性能を下げてしまいます。しかしながら main name 以外のサブモジュールはロードされません。

このスローダウンを回避する一つの方法は、コードの大部分をサブモジュールに入れてしまい、プラグイン自体を小さくしてしまうことです。本当に __init__.py で必要とされているのは、プラグインのコマンドクラス、それらを登録するコマンドと、オプションで test_suite() だけです。

別の方法であなたのプラグインのオーバーヘッドを削減する方法は、bzrlib lazy_import 機能を使用することです。これはこのようになっています。

 from bzrlib.lazy_import import lazy_import
 lazy_import(globals(), """
 from bzrlib import (
     branch as _mod_branch,
     option,
     workingtree,
     )
 """)

Lazy インポートは、パッケージとモジュールだけに使用することができます。クラスや関数には使用することができません。これは本当に必要になるまでパッケージやモジュールをインポートしません。

*進んだ設定
ユーザのプラグインを見つけるフォルダ ( ~/.bazaar/plugins  デフォルトで ) を 環境変数BZR_PLUGIN_PATH を設定することでオーバーライドすることができます。

bzr の bzrlib/plugins にインストールされているプラグインはシステム全体で使用できます。

**コールバックでプラグインの機能を起動する
Bazaar のブランチ 0.15 からは、複数のフックをする方法があります。新しいフックを追加するには以下のようにします。

 import bzrlib.branch
 bzrlib.branch.Branch.hooks.install_hook(HOOK_NAME, MY_FUNCTION)

**現在のフック
http://doc.bazaar-vcs.org/bzr.dev/en/user-reference/bzr_man.html#hooks をご覧ください。

*さらなる情報
[[Integrating_with_Bazaar>>http://bazaar-vcs.org/Integrating_with_Bazaar]] で、add, commit, log などなどをどのようにして操作をするか説明されています。