Note:

This page is primarily intended for developers of Mercurial.

エクステンションの作り方

Mercurial には、コマンドを追加するためにエクステンション機構が用意されています。

エクステンションを使えば、まるで組み込みコマンドのように hg コマンドから直接実行可能な機能を作ることができます。 エクステンションからは全ての 内部 MercurialApi にアクセス可能です。

/!\ Mercurial の内部 API を使うなら、十中八九あなたのコードは Mercurial のライセンスの影響を受けるでしょう。 始める前に、まず License ページを確認してください。

/!\ There are NO guarantees that third-party code calling into Mercurial's internals won't break from release to release. If you do use Mercurial's API for published third-party code, we expect you to test your code before each major Mercurial release (see TimeBasedReleasePlan). This will prevent various bug reports from your users when they upgrade their copy of Mercurial.

Contents

  1. ファイル構造
  2. コマンドテーブル
    1. cmdtable 辞書
    2. 引数の一覧
    3. cmdtable の例
  3. コマンド関数のシグネチャ
  4. コマンド関数の docstrings
  5. ユーザとのやり取り
  6. コールバックの設定
    1. ui setup
    2. Extension setup
    3. Command table setup
    4. Repository setup
  7. フックの設定
  8. 互換バージョン表記
  9. サンプルエクステンション
  10. サンプルエクステンションのテスト
  11. まとめ: 何をどこに書くべき?
    1. uisetup
    2. extsetup
    3. reposetup
  12. エクステンションの公開

1. ファイル構造

エクステンションは、たいてい単なる Python モジュールです。 大きめのエクステンションなら、単一パッケージの複数モジュールへ分割した方が良いでしょう(参考: ConvertExtension)。 その場合、パッケージのルートモジュールがエクステンションの名前になり、次に説明する cmdtable と任意のコールバックを提供します。

2. コマンドテーブル

エクステンションを作る際に、個々のコマンドを記した辞書を cmdtable という名前で Python モジュールに追加することができます。

2.1. cmdtable 辞書

cmdtable は、コマンド名をキーに取り、値に以下の tuple を取る辞書(dict)です:

  1. コマンド実行時に呼び出す関数。
  2. コマンドが受け取る引数の一覧(list)。
  3. コマンドラインの概要(関数の docstring がコマンドのヘルプになります)。

2.2. 引数の一覧

コマンドフラグ引数の説明は、全て mercurial/fancyopts.py のソースにあります。

引数の一覧は、以下を含む tuple の list です:

  1. 短い引数文字か、それが無いことを示す '' (例: o は-o 引数を意味)。

  2. 長い引数名 (例: option は --option 引数を意味)。

  3. 引数のデフォルト値。
  4. 引数のヘルプ ("hg newcommand" の部分は省略可能で、引数名とパラメーター文字列のみ必要)。

2.3. cmdtable の例

cmdtable = {
    # "command-name": (function-call, options-list, help-string)
    "print-parents": (printparents,
                     [('s', 'short', None, 'print short form'),
                      ('l', 'long', None, 'print long form')],
                     "hg print-parents [options] node")
}

3. コマンド関数のシグネチャ

新しいコマンドを実装する関数は、常に ui と(たいていの場合) repo を引数に取ります。 この引数の使い方については MercurialApi を参照してください。 残りの引数には、コマンドラインで指定されたハイフン始まりではない項目が順番に入ります。 引数リストにデフォルト値が指定されていなければ、その引数は必須です。

コマンドにリポジトリが関係せず repo が不要であるなら、 commands を mercurial から import して commands.norepo に名前を追加してください。 例えば: 

from mercurial import commands
...
commands.norepo += " mycommand"

norepo の例は RcpathExtension (RcpathExtension/rcpath.py のソースへの直リンク)または ConvertExtension (convert のソースへの直リンク)にあります。

4. コマンド関数の docstrings

関数の docstring は hg help mycommand で表示されるヘルプの本文になります。 docstring は reStructuredText の単純なサブセット形式で書いて下さい。 サポートされている構造は:

段落: 

This is a paragraph.

Paragraphs are separated
by blank lines.

コロン 2 つに続く字下げされたブロックはそのまま表示されます。 二重のコロンは、コロン 1 つとして表示されます: 

Some text::

  verbatim
    text
     !!

フィールドリスト: 

:key1: value1
:key2: value2

リスト: 

- foo
- bar

順序づきリスト: 

1. foo
2. bar

インラインマークアップ: *太字*, ``等幅`` 。 Mercurial のコマンドを :hg:`command` で括ると、適切なドキュメントへリンクを張ってくれます。 新しい構造が追加された際に、それをサポートするのに大した手間はかからないでしょう。

5. ユーザとのやり取り

MercurialApi に挙げた(ui.write(*msg) や ui.prompt(msg, default="y") などの) ui メソッド以外に、エクステンション自体や個々のコマンドについてヘルプを書くことも大切です。

モジュールの docstring は hg help extensionname を実行した時に表示され、同様に、コマンドのヘルプとその関数の docstring は hg help command で表示されます。

6. コールバックの設定

Mercurial はエクステンションを段階的にロードします。 全てのエクステンションに対してある段階の処理が行われた後、次の段階へ進みます。 最初の段階では、エクステンションモジュールを全てロードし、 Mercurial に登録します。 つまり、以下に示す段階では、 extensions.find を使って有効化されたエクステンションを知ることができます。

6.1. ui setup

uisetup は任意のコールバックです。 エクステンションを初めてロードした際に、 ui オブジェクトを引数に uisetup を呼び出します: 

def uisetup(ui):
    # ...

6.2. Extension setup

extsetup は任意のコールバックです。 エクステンションを全てロードした後に呼び出され、エクステンションが他のエクステンションに依存しているケースで役に立ちます。 シグネチャ: 

def extsetup():
    # ...

Mercurial version 8e6019b16a7d 以降(1.3.1 以降)では、 extsetup は ui 引数を取ることができます: 

def extsetup(ui):
    # ...

6.3. Command table setup

extsetup の後、 cmdtable を Mercurial のグローバルコマンドテーブルへコピーします。

6.4. Repository setup

reposetup は任意のコールバックです。 Mercurial リポジトリの初期化が終わった後に呼び出され、エクステンションで必要なローカルステートを設定する時に使えます。

コマンド関数と同様に、 ui オブジェクトと repo オブジェクトを受け取ります(追加の引数はありません): 

def reposetup(ui, repo):
    #do initialization here.

reposetup 関数が受け取る ui オブジェクトは、 uisetup や extsetup 関数が受け取るものと異なります。 この点を考慮することが大切です。 特に、(以下の節で説明しますが)フックを設定する際には、全てのフックが同一の ui オブジェクトを使うわけではないので、フックによって異なるセットアップ関数で設定しなければなりません。

7. フックの設定

エクステンションはフックを使う必要に迫られることがあります。 ユーザーが手で hgrc の [hooks] セクションを書き換え、必要なフックを設定することもできますが、 ui.setconfig('hooks', ...) 関数を先ほど説明したセットアップ関数から呼び出すことで、自動的に設定することも可能です。

hgrc の hooks セクションを手で書き換えることと ui.setconfig() を使うことの主な違いは、 ui.setconfig() では実際のフック関数オブジェクトにアクセス可能なので、関数自体を ui.setconfig() へ渡せるという点です。 一方、 hgrc ファイルの hooks セクションでは、フック関数を "python:modulename.functioname" 表記(例: "python:hgext.notify.hook")で参照する必要があります。

例: 

# Define hooks -- note that the actual function name it irrelevant.
def preupdatehook(ui, repo, **kwargs):
    ui.write("Pre-update hook triggered\n")

def updatehook(ui, repo, **kwargs):
    ui.write("Update hook triggered\n")

def uisetup(ui):
    # When pre-<cmd> and post-<cmd> hooks are configured by means of
    # the ui.setconfig() function, you must use the ui object passed
    # to uisetup or extsetup.
    ui.setconfig("hooks", "pre-update.myextension", preupdatehook)

def reposetup(ui, repo):
    # Repository-specific hooks can be configured here. These include
    # the update hook.
    ui.setconfig("hooks", "update.myextension", updatehook)

フックによって異なるセットアップ関数で設定する必要があることにご注意を。 この例から、 update フックは reposetup 関数で設定しなければならず、一方で pre-update は uisetup か extsetup 関数で設定しなければならいことが分かるでしょう。

8. 互換バージョン表記

互換性が確認されている Mercurial リリースを testedwith 変数に表記すべきです。 開発者やユーザーが問題の出処を調査する上で役に立ちます。 

   1 testedwith = '2.0 2.0.1 2.1 2.1.1 2.1.2'

サードパーティーエクステンションで internal マークを使ってはいけません。もし見かけたら、そのエクステンションが記されたバグレポートは一切読みませんよ。

同様に、エクステンションの不具合報告の方法については buglink 変数で指定してください。 エクステンションでエラーが発生した際に、このリンクがエラーメッセージに記載されます。 

   1 buglink = 'https://bitbucket.org/USER/REPO/issues'

9. サンプルエクステンション

   1 """printparents
   2 
   3 Prints the parents of a given revision.
   4 """
   5 from mercurial import util
   6 
   7 # Every command must take ui and and repo as arguments.
   8 # opts is a dict where you can find other command line flags.
   9 #
  10 # Other parameters are taken in order from items on the command line that
  11 # don't start with a dash. If no default value is given in the parameter list,
  12 # they are required.
  13 #
  14 # For experimenting with Mercurial in the python interpreter:
  15 # Getting the repository of the current dir:
  16 #    >>> from mercurial import hg, ui
  17 #    >>> repo = hg.repository(ui.ui(), path = ".")
  18 
  19 
  20 def printparents(ui, repo, node, **opts):
  21     # The doc string below will show up in hg help.
  22     """Print parent information."""
  23     # repo can be indexed based on tags, an sha1, or a revision number.
  24     ctx = repo[node]
  25     parents = ctx.parents()
  26 
  27     try:
  28         if opts['short']:
  29             # The string representation of a context returns a smaller portion
  30             # of the sha1.
  31             ui.write('short %s %s\n' % (parents[0], parents[1]))
  32         elif opts['long']:
  33             # The hex representation of a context returns the full sha1.
  34             ui.write('long %s %s\n' % (parents[0].hex(), parents[1].hex()))
  35         else:
  36             ui.write('default %s %s\n' % (parents[0], parents[1]))
  37     except IndexError:
  38         # Raise an Abort exception if the node has only one parent.
  39         raise util.Abort('revision %s has only one parent' % node)
  40 
  41 
  42 cmdtable = {
  43     # cmd name        function call
  44     'print-parents': (printparents,
  45         # See mercurial/fancyopts.py for all of the command flag options.
  46         [('s', 'short', None, 'print short form'),
  47         ('l', 'long', None, 'print long form')],
  48         '[options] REV')
  49 }
  50 
  51 testedwith = '2.2'

cmdtable や reposetup なしでもエクステンションは機能します。 つまり、エクステンションは「無言で」機能し、コマンドラインインターフェースから直接見える機能を追加しなくても構わないということです。

10. サンプルエクステンションのテスト

上記のサンプルエクステンションのテストです: 

Test printparents extension.

Activate the printparents extension:
  $ echo "[extensions]" >> $HGRCPATH
  $ echo "printparents=" >> $HGRCPATH

Create a new repo:
  $ hg init r
  $ cd r

Add two new files and commit them separately:
  $ echo c1 > f1
  $ hg commit -Am 0
  adding f1
  $ echo c2 > f2
  $ hg commit -Am 1
  adding f2

Update to revision 0. Add and commit a third file creating a new head:
  $ hg up 0
  0 files updated, 0 files merged, 1 files removed, 0 files unresolved
  $ echo c3 > f3
  $ hg commit -Am 2
  adding f3
  created new head

Merge the two heads and commit:
  $ hg merge
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  (branch merge, don't forget to commit)
  $ hg commit -m 3

Test printparents with the (merged) tip:
  $ hg print-parents tip
  default 33960aadc16f c3adabd1a5f4

Testing printparents with revision 2 will fail (because there is only one parent):
  $ hg print-parents 2
  abort: revision 2 has only one parent
  [255]

Mercurial のテストについて詳細は: WritingTests

11. まとめ: 何をどこに書くべき?

Mercurial にバンドルされたエクステンションのセットアップを元に、よくある作業をリストアップしました。

11.1. uisetup

11.2. extsetup

11.3. reposetup

12. エクステンションの公開

あなたのエクステンションが汎用的で、良くできていて、他の人が興味を持ちそうであれば、 PublishingExtensions を参照してください。

CategoryJapanese

English

JapaneseWritingExtensions (last edited 2014-07-21 14:36:15 by YuyaNishihara)