pytho****@googl*****
pytho****@googl*****
2011年 4月 23日 (土) 17:39:17 JST
2 new revisions: Revision: 51a3cdcaf1a4 Author: MATSUI Tetsushi <matsu****@gmail*****> Date: Fri Apr 22 08:40:19 2011 Log: 2.6.6: library/intro http://code.google.com/p/python-doc-ja/source/detail?r=51a3cdcaf1a4 Revision: 795ee8a3ad22 Author: MATSUI Tetsushi <matsu****@gmail*****> Date: Sat Apr 23 01:31:56 2011 Log: 2.6.6: library/difflib http://code.google.com/p/python-doc-ja/source/detail?r=795ee8a3ad22 ============================================================================== Revision: 51a3cdcaf1a4 Author: MATSUI Tetsushi <matsu****@gmail*****> Date: Fri Apr 22 08:40:19 2011 Log: 2.6.6: library/intro http://code.google.com/p/python-doc-ja/source/detail?r=51a3cdcaf1a4 Modified: /library/intro.rst ======================================= --- /library/intro.rst Sat Mar 28 22:01:29 2009 +++ /library/intro.rst Fri Apr 22 08:40:19 2011 @@ -48,7 +48,7 @@ ての関数やモジュール、用語を探すことだってできます。もしランダムな項目 について勉強してみたいのなら、ランダムにページを選び (:mod:`random` 参 照)、そこから 1, 2 節読むこともできます。このマニュアルの各節をどんな -順番で読むかに関わらず、第 :ref:`builtin` 章から始めるとよいでしょう。 +順番で読むかに関わらず、 :ref:`built-in-funcs` の章から始めるとよいでしょ う。 マニュアルの他の部分は、この節の内容について知っているものとして書かれ ているからです。 ============================================================================== Revision: 795ee8a3ad22 Author: MATSUI Tetsushi <matsu****@gmail*****> Date: Sat Apr 23 01:31:56 2011 Log: 2.6.6: library/difflib http://code.google.com/p/python-doc-ja/source/detail?r=795ee8a3ad22 Modified: /library/difflib.rst ======================================= --- /library/difflib.rst Sun Mar 20 19:52:28 2011 +++ /library/difflib.rst Sat Apr 23 01:31:56 2011 @@ -1,5 +1,5 @@ - -:mod:`difflib` --- 差異の計算を助ける + +:mod:`difflib` --- 差分の計算を助ける ===================================== .. module:: difflib @@ -21,45 +21,60 @@ .. diffs. For comparing directories and files, see also, the :mod:`filecmp` module. このモジュールは、シーケンスを比較するためのクラスや関数を提供しています。 -例えば、ファイルの差分を計算して、それをHTMLやcontext diff, unified diff +例えば、ファイルの差分を計算して、それを HTML や context diff, unified diff などいろいろなフォーマットで出力するために、このモジュールを利用することが できます。 ディレクトリやファイル群を比較するためには、 :mod:`filecmp` モジュールも参 照してください。 .. class:: SequenceMatcher - 柔軟性のあるクラスで、シーケンスの要素の型は、ハッシュ化できる (:term:`hashable`)限り何でも比較可能です。基礎的なアルゴリズムは - 可塑的なものであり、1980年代の後半に発表されたRatcliffとObershelp による アルゴリズム、大げさに名づけられた"ゲシュタルトパターン - マッチング"よりはもう少し良さそうなものです。その考え方は、 "junk"要素を 含まない最も長いマッチ列を探すことです（Ratcliffと - Obershelpのアルゴリズムではjunkを示しません）。このアイデアは、下位のマ ッチ列から左または右に伸びる列の断片に対して再帰的に - あてはまります。これは小さな文字列に対して効率良いものではありませんが、 人間の目からみて「良く見える」ようにマッチする傾向があります。 - - **実行時間:** 基本的なRatcliff-Obershelpアルゴリズムは、最悪の場合3乗、 期待値でも2乗となります。 - :class:`SequenceMatcher` オブジェクトは、最悪のケースで4乗、期待値はシー ケンスの - 中の要素数に非常にややこしく依存しています。最良の場合は線形時間になりま す。 - + 柔軟性のあるクラスで、二つのシーケンスの要素は、 + ハッシュ化できる(:term:`hashable`)型である限り何でも比較可能です。 + 基本的なアルゴリズムは、1980年代の後半に発表された + Ratcliff と Obershelp による"ゲシュタルトパターンマッチング"と大げさに名 づけられた + アルゴリズム以前から知られている、やや凝ったアルゴリズムです。 + その考え方は、"junk" 要素を含まない最も長い互いに隣接したマッチ列を探す ことです + (Ratcliff と Obershelp のアルゴリズムでは junk を示しません)。 + このアイデアは、マッチ列から左または右に伸びる断片に対して再帰的に + あてはめられます。この方法では編集を最小にする列は取り出されませんが、 + 人間の目からみて「正しい感じ」にマッチする傾向があります。 + + **実行時間:** 基本的な Ratcliff-Obershelp アルゴリズムは、 + 最悪の場合3乗、期待値で2乗となります。 + :class:`SequenceMatcher` オブジェクトでは、最悪のケースで2乗、期待値は比 較される + シーケンス中に共通に現れる要素数に非常にややこしく依存しています。 + 最良の場合は線形時間になります。 + + **ヒューリスティック:** マッチングの速度を向上させるために、1% 以上の時 間を費やす + 少なくとも 200 アイテムは junk として扱います。 + 少数のアイテムから構成された列に対しては、 + 残念ながらこの仕様により酷い結果を与えることになってしまいます。 + 将来のバージョンではこのヒューリスティックを使わなくするオプションを加え る予定です。 .. class:: Differ - テキスト行からなるシーケンスを比較するクラスです。人が読むことのできる差 異を作成します。Differクラスは :class:`SequenceMatcher` - クラスを利用して、行からなるシーケンスを比較したり、行内の(ほぼ)同一の文 字を比較します。 - - :class:`Differ` クラスによる差異の各行は、2文字のコードではじめられま す。 - - +----------+--------------------------------------+ - | コード | 意味 | - +==========+======================================+ - | ``'- '`` | 列は文字列1にのみ存在する | - +----------+--------------------------------------+ - | ``'+ '`` | 列は文字列2にのみ存在する | - +----------+--------------------------------------+ - | ``' '`` | 列は両方の文字列で同一 | - +----------+--------------------------------------+ - | ``'? '`` | 列は入力文字列のどちらにも存在しない | - +----------+--------------------------------------+ - - '? 'で始まる列は線内の差異に注意を向けようとします。その差異は、入力され たシーケンスのどちらにも存在しません。シーケンスが - タブ文字を含むとき、これらのラインは判別しづらいものになることがありま す。 + テキスト行からなるシーケンスを比較するクラスです。 + 人が読むことのできる差分を作成します。 + Differ クラスは :class:`SequenceMatcher` + クラスを利用して、行からなるシーケンスを比較したり、(ほぼ)同一の行内の文 字を比較したりします。 + + :class:`Differ` クラスによる差分の各行は、2文字のコードで始まります。 + + +----------+------------------------------------------+ + | コード | 意味 | + +==========+==========================================+ + | ``'- '`` | 行はシーケンス1にのみ存在する | + +----------+------------------------------------------+ + | ``'+ '`` | 行はシーケンス2にのみ存在する | + +----------+------------------------------------------+ + | ``' '`` | 行は両方のシーケンスで同一 | + +----------+------------------------------------------+ + | ``'? '`` | 行は入力シーケンスのどちらにも存在しない | + +----------+------------------------------------------+ + + '? 'で始まる行は、行内のどこに差異が存在するかに注意を向けようとします。 + その行は、入力されたシーケンスのどちらにも存在しません。シーケンスが + タブ文字を含むとき、これらの行は判別しづらいものになることがあります。 .. class:: HtmlDiff @@ -93,11 +108,17 @@ *fromdesc* および *todesc* はオプションのキーワード引数で、差分表示 テーブルにおけるそれぞれ差分元、差分先ファイルのカラムの ヘッダになる文字列を指定します (いずれもデフォルト値は空文字列です)。 - *context* および *numlines* はともにオプションのキーワード引数です。 *contest* を ``True`` にするとコンテキスト差分を - 表示し、デフォルトの ``False`` にすると完全なファイル差分を表示しま す。*numlines* のデフォルト値は ``5`` で、 *context* - が ``True`` の場合、 *numlines* は強調部分の前後にあるコンテキスト行 の数を制御します。*context* が ``False`` - の場合、*numlines* は "next" と書かれたハイパーリンクをたどった時に到 達する場所が次の変更部分より何行前にあるかを制御します - (値をゼロにした場合、"next" ハイパーリンクを辿ると変更部分の強調表示 がブラウザの最上部に表示されるようになります)。 + *context* および *numlines* はともにオプションのキーワード引数です。 + *contest* を ``True`` にするとコンテキスト差分を表示し、 + デフォルトの ``False`` にすると完全なファイル差分を表示します。 + *numlines* のデフォルト値は ``5`` で、 + *context* が ``True`` の場合、 + *numlines* は強調部分の前後にあるコンテキスト行の数を制御します。 + *context* が ``False`` の場合、 + *numlines* は "next" と書かれたハイパーリンクをたどった時に到達する場 所が + 次の変更部分より何行前にあるかを制御します + (値をゼロにした場合、"next" ハイパーリンクを辿ると変更部分の強調表示 が + ブラウザの最上部に表示されるようになります)。 .. function:: make_table(fromlines, tolines [, fromdesc][, todesc][, context][, numlines]) @@ -114,20 +135,27 @@ .. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm]) - *a* と *b* (文字列のリスト) を比較し、差異 (差異のある行を生成するジェネ レータ(:term:`generator`)) を、 - context diff のフォーマットで返します。 - - コンテクスト形式は、変更があった行に前後数行を加えてある、コンパクトな表 現方法です。変更箇所は、変更前/変更後に分けて表します。コンテクスト（変 - 更箇所前後の行）の行数は *n* で指定し、デフォルト値は 3 です。 - - デフォルトでは、diff の制御行 (``***`` や ``---`` を含む行) の最 - 後には、改行文字が付加されます。この場合、入出力共、行末に改行文字を持つ ので、 :func:`file.readlines` で得た入力から生成した差異を、 - :func:`file.writelines` に渡す場合に便利です。行末に改行文字を持たない入 力に対しては、出力でも改行文字を付加しないように + *a* と *b* (文字列のリスト) を比較し、差分 + (差分形式の行を生成するジェネレータ(:term:`generator`)) を、 + context diff のフォーマット(以下「コンテクスト形式」)で返します。 + + コンテクスト形式は、変更があった行に前後数行を加えてある、コンパクトな表 現方法です。 + 変更箇所は、変更前/変更後に分けて表します。コンテクスト (変更箇所前後の 行) + の行数は *n* で指定し、デフォルト値は 3 です。 + + デフォルトでは、diff の制御行 (``***`` や ``---`` を含む行) の最後には、 + 改行文字が付加されます。この場合、入出力とも、行末に改行文字を持つので、 + :func:`file.readlines` で得た入力から生成した差分を、 + :func:`file.writelines` に渡す場合に便利です。 + + 行末に改行文字を持たない入力に対しては、出力でも改行文字を付加しないよう に *lineterm* 引数に ``""`` を渡してください。 - diff コンテクスト形式は、通常、ヘッダにファイル名と変更時刻を持っていま す。この情報は、文字列 - *fromfile*, *tofile*, *fromfiledate*, *tofiledate* で指定できます。変更 時刻の書式は、通常、 - :func:`time.ctime` の戻り値と同じものを使います。指定しなかった場合のデ フォルト値は、空文字列です。 + コンテクスト形式は、通常、ヘッダにファイル名と変更時刻を持っています。こ の情報は、文字列 + *fromfile*, *tofile*, *fromfiledate*, *tofiledate* で指定できます。 + 変更時刻の書式は、通常、 + :func:`time.ctime` の戻り値と同じものを使います。 + 指定しなかった場合のデフォルト値は、空文字列です。 >>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n'] >>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n'] @@ -156,15 +184,19 @@ .. function:: get_close_matches(word, possibilities[, n][, cutoff]) - 最も「十分」なマッチのリストを返します。 *word* は、なるべくマッチして欲 しい（一般的には文字列の）シーケンスです。 - *possibilities* は *word* にマッチさせる（一般的には文字列）シーケンスの リストです。 - - オプションの引数 *n* (デフォルトでは ``3``)はメソッドの返すマッチの最大 数です。 *n* は ``0`` より大きくなければなりません。 - - オプションの引数 *cutoff* (デフォルトでは ``0.6``)は、 [0, 1]の間となる floatの値です。可能性として、少なくとも *word* - が無視されたのと同様の数値にはなりません。 - - 可能性のある、（少なくとも *n* に比べて）最もよいマッチはリストによって 返され、同一性を表す数値に応じて最も近いものから順に格納されます。 + 「十分」なマッチの上位のリストを返します。 + *word* はマッチさせたいシーケンス (大概は文字列) です。 + *possibilities* は *word* にマッチさせるシーケンスのリスト (大概は文字列 のリスト) です。 + + オプションの引数 *n* (デフォルトでは ``3``)はメソッドの返すマッチの最大 数です。 + *n* は ``0`` より大きくなければなりません。 + + オプションの引数 *cutoff* (デフォルトでは ``0.6``)は、 + 区間 [0, 1] に入る小数の値です。 + *word* との一致率がそれ未満の *possibilities* の要素は無視されます。 + + *possibilities* の要素でマッチした上位(多くても *n* 個)は、 + 類似度のスコアに応じて(一番似たものを先頭に)ソートされたリストとして返さ れます。 >>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy']) ['apple', 'ape'] @@ -179,18 +211,27 @@ .. function:: ndiff(a, b[, linejunk[, charjunk]]) - *a* と *b* （文字列からなるリスト）を比較し、 :class:`Differ` オブジェク ト形式の差異(差異のある列を生成する :term:`generator`)を返します。 - - オプションのパラメータ *linejunk* と *charjunk* は、filter 機能のための キーワードです（使わないときは空にする）。 - - *linejunk*: string型の引数ひとつを受け取る関数で、文字列が junkか否かに よってtrueを（違うときにはtrueを）返します。Python - 2.3以降、デフォルトでは(``None``)になります。それまでは、モジュールレべ ルの関数 :func:`IS_LINE_JUNK` であり、それは - 少なくともひとつのシャープ記号(``'#'``)をのぞく、可視のキャラクタを含ま ない行をフィルタリングします。 Python - 2.3では、下位にある :class:`SequenceMatcher` クラスが、雑音となるくらい 頻繁に登場する列であるか否かを、動的に分析します。 - これは、バージョン2.3以前でのデフォルト値よりうまく動作します。 - - *charjunk*: 長さ1の文字を受け取る関数です。デフォルトでは、モジュールレ べルの関数 IS_CHARACTER_JUNK()であり、これは空白文字列 - （空白またはタブ、注：改行文字をこれに含めるのは悪いアイデア！）をフィル タリングします。 + *a* と *b* (文字列のリスト) を比較し、差分 + (差分形式の行を生成するジェネレータ(:term:`generator`)) を、 + :class:`Differ` のスタイルで返します。 + + オプションのキーワードパラメータ *linejunk* と *charjunk* は、 + フィルタ関数を渡します (使わないときは ``None``)。 + + *linejunk*: 文字列型の引数ひとつを受け取る関数で、文字列が junk ならば真 を、 + 違うときには偽を返します。 + Python 2.3 以降、デフォルトでは(``None``)になります。 + それまでは、モジュールレべルの関数 :func:`IS_LINE_JUNK` であり、それは + 高々ひとつのシャープ記号(``'#'``)を除いて可視のキャラクタを含まない行 + をフィルタリングするものです。 + Python 2.3 から、下位にある :class:`SequenceMatcher` クラスが、 + 雑音となるくらい頻繁に登場する行であるか否かを、動的に分析します。 + これは、バージョン 2.3 以前のデフォルト値よりたいていうまく動作します。 + + *charjunk*: 文字(長さ1の文字列)を受け取る関数です。 + デフォルトでは、モジュールレべルの関数 :func:`IS_CHARACTER_JUNK` であ り、 + これは空白文字類 (空白またはタブ、注：改行文字をこれに含めるのは悪いアイ デア！) + をフィルタリングします。 :file:`Tools/scripts/ndiff.py` は、この関数のコマンドラインのフロントエ ンド（インターフェイス）です。 @@ -210,10 +251,11 @@ .. function:: restore(sequence, which) - 差異を生成したシーケンスのひとつを返します。 - - 与えられる *sequence* は :meth:`Differ.compare` または :meth:`ndiff` に よって生成され、ファイル1または2（引数 - *which* で指定される）によって元の列に復元され、行頭のプレフィクスが取り のぞかれます。 + 差分を生成した元の二つのシーケンスのうち一つを返します。 + + :meth:`Differ.compare` または :meth:`ndiff` によって生成された *sequence* + を与えられると、行頭のプレフィクスを取りのぞいて + ファイル 1 または 2 (引数 *which* で指定される) に由来する行を復元しま す。 例: @@ -232,19 +274,26 @@ .. function:: unified_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm]) - *a* と *b* (共に文字列のリスト) を比較し、unified diff フォーマットで、 差異 (差分行を生成するジェネレータ(:term:`generator`)) を返します。 - - unified 形式は変更があった行に前後数行を加えた、コンパクトな表現方法で す。変更箇所は (変更前/変更後を分離したブロックではなく) インライン・ス - タイルで表されます。コンテクスト（変更箇所前後の行）の行数は、*n* で指定 し、デフォルト値は 3 です。 - - デフォルトでは、diff の制御行 (``---``、``+++``、``@@`` を含む行) - は行末で改行します。この場合、入出力共、行末に改行文字を持つの で、 :func:`file.readlines` で得た入力を処理して生成した差異を、 + *a* と *b* (文字列のリスト) を比較し、差分 + (差分形式の行を生成するジェネレータ(:term:`generator`)) を、 + unified diff フォーマット(以下「ユニファイド形式」)で返します。 + + ユニファイド形式は変更があった行に前後数行を加えた、コンパクトな表現方法 です。 + 変更箇所は (変更前/変更後を分離したブロックではなく) インライン・スタイ ルで表されます。 + コンテクスト（変更箇所前後の行）の行数は、 *n* で指定し、デフォルト値は 3 です。 + + デフォルトでは、diff の制御行 (``---``, ``+++``, ``@@`` を含む行) + は行末の改行を含めて生成されます。 + このようにしてあると、入出力とも行末に改行文字を持つので、 + :func:`file.readlines` で得た入力を処理して生成した差分を、 :func:`file.writelines` に渡す場合に便利です。 - 行末に改行文字を持たない入力には、出力も同じように改行なしになるように、 *lineterm* 引数を ``""`` にセットしてください - - diff コンテクスト形式は、通常、ヘッダにファイル名と変更時刻を持っていま す。 この情報は、文字列 *fromfile*, *tofile*, - *fromfiledate*, *tofiledate* で指定できます。変更時刻の書式は、通 常、 :func:`time.ctime` + 行末に改行文字を持たない入力には、出力も同じように改行なしになるように、 + *lineterm* 引数を ``""`` にセットしてください + + ユニファイド形式は、通常、ヘッダにファイル名と変更時刻を持っています。 + この情報は、文字列 *fromfile*, *tofile*, *fromfiledate*, *tofiledate* + で指定できます。変更時刻の書式は、通常、 :func:`time.ctime` の戻り値と同じものを使います。指定しなかった場合のデフォルト値は、空文字 列です。 >>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n'] @@ -269,21 +318,25 @@ .. function:: IS_LINE_JUNK(line) - 無視できる列のときtrueを返します。列 *line* が空白、または ``'#"'`` ひ とつのときには無視できます。それ以外の時には - 無視できません。 :func:`ndiff` の引数 *linkjunk* としてデフォルトで使用 されます。 - :func:`ndiff` の *linejunk* はPython 2.3以前のものです。 + 無視できる行のとき真を返します。 + 行 *line* は空白、または ``'#'`` ひとつのときに無視できます。 + それ以外のときには無視できません。 + Python 2.3 以前は :func:`ndiff` の引数 *linkjunk* にデフォルトで使用され ました。 .. function:: IS_CHARACTER_JUNK(ch) - 無視できる文字のときtrueを返します。文字 *ch* が空白、またはタブ文字のと きには無視できます。それ以外の時には無視できません。 + 無視できる文字のとき真を返します。 + 文字 *ch* が空白、またはタブ文字のときには無視できます。 + それ以外の時には無視できません。 :func:`ndiff` の引数 *charjunk* としてデフォルトで使用されます。 .. seealso:: `Pattern Matching: The Gestalt Approach （パターンマッチング: 全体アプ ローチ） <http://www.ddj.com/184407970?pgno=5>`_ - John W. Ratcliff と D. E. Metzener による同一性アルゴリズムに関する 議論。 `Dr. Dobb's Journal + John W. Ratcliff と D. E. Metzener による類似のアルゴリズムに関する 議論。 + `Dr. Dobb's Journal <http://www.ddj.com/>`_ 1988年7月号掲載。 @@ -292,14 +345,16 @@ SequenceMatcherオブジェクト --------------------------- -The :class:`SequenceMatcher` クラスには、以下のようなコンストラクタがありま す。 +:class:`SequenceMatcher` クラスには、以下のようなコンストラクタがあります。 .. class:: SequenceMatcher([isjunk[, a[, b]]]) - オプションの引数 *isjunk* は、 ``None`` (デフォルトの値です) にするか、 単一の引数をとる関数にせねばなりません。後者の場合、関数は - シーケンスの要素を受け取り、要素が "junk" であり、無視すべきである場合に 限り真をかえすようにせねばなりません。 *isjunk* に ``None`` - を渡すと、 ``lambda x: 0`` を渡したのと同じになります; すなわち、いかな る要素も無視しなくなります。 + オプションの引数 *isjunk* は、 ``None`` (デフォルトの値です) にするか、 + 単一の引数をとる関数にせねばなりません。後者の場合、関数は + シーケンスの要素を受け取り、要素が junk であり、無視すべきである場合に限 り + 真をかえすようにせねばなりません。 *isjunk* に ``None`` を渡すと、 + ``lambda x: 0`` を渡したのと同じになります; すなわち、いかなる要素も無視 しなくなります。 例えば以下のような引数を渡すと、空白とタブ文字を無視して文字のシーケンス を比較します。 :: lambda x: x in " \t" @@ -334,21 +389,24 @@ ``a[alo:ahi]`` と ``b[blo: bhi]`` の中から、最長のマッチ列を探しま す。 - *isjunk* が省略されたか ``None`` の時、 :meth:`get_longest_match` は ``a[i:i+k]``が``b[j:j+k]`` - と等しいような ``(i, j, k)`` を返します。その値は ``alo <= i <= i+k <= ahi`` かつ ``blo <= j <= j+k <= bhi`` - となります。 ``(i', j', k')`` でも、同じようになります。さらに ``k >= k', i <= i'`` が ``i == i', j <= j'`` + *isjunk* が省略されたか ``None`` の時、 :meth:`get_longest_match` は + ``a[i:i+k]`` が ``b[j:j+k]`` と等しいような ``(i, j, k)`` を返しま す。 + その値は ``alo <= i <= i+k <= ahi`` かつ ``blo <= j <= j+k <= bhi`` + となります。 ``(i', j', k')`` でも、同じようになります。 + さらに ``k >= k', i <= i'`` が ``i == i', j <= j'`` でも同様です。言い換えると、いくつものマッチ列すべてのうち、 - *a* 内で最初に始まるものを返します。そしてその *a* 内で最初のマッチ列 すべてのうち *b* 内で最初に始まるものを返します。 + *a* 内で最初に始まるものを返します。そしてその *a* 内で最初のマッチ列 すべてのうち + *b* 内で最初に始まるものを返します。 >>> s = SequenceMatcher(None, " abcd", "abcd abcd") >>> s.find_longest_match(0, 5, 0, 9) Match(a=0, b=4, size=5) - 引数 *isjunk* が与えられている場合、上記の通り、はじめに再長のマッチ 列を判定します。ブロック内にjunk要素が見当たらないような - 追加条件の際はこれに該当しません。次にそのマッチ列を、その両側の junk要素にマッチするよう、できる限り広げていきます。そのため結果 - となる列は、探している列のたまたま直前にあった同一のjunk以外のjunkに はマッチしません。 - - 以下は前と同じサンプルですが、空白をjunkとみなしています。これは ``' abcd'`` が2つ目の列の末尾にある ``' abcd'`` にマッチしない + 引数 *isjunk* が与えられている場合、上記の通り、はじめに最長のマッチ 列を判定します。ブロック内に junk 要素が見当たらないような + 追加条件の際はこれに該当しません。次にそのマッチ列を、その両側の junk 要素にマッチするよう、できる限り広げていきます。そのため結果 + となる列は、探している列のたまたま直前にあった同一の junk 以外の junk にはマッチしません。 + + 以下は前と同じサンプルですが、空白を junk とみなしています。これは ``' abcd'`` が2つ目の列の末尾にある ``' abcd'`` にマッチしない ようにしています。代わりに ``'abcd'`` にはマッチします。そして 2つ目 の文字列中、一番左の ``'abcd'`` にマッチします。 >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd") @@ -371,10 +429,12 @@ もし ``(i, j, n)`` と ``(i', j', n')`` がリストで並んでいる3つ組で、 2つ目が最後の3つ組でなければ、 ``i+n != i'`` または ``j+n != j'`` です。言い換えると並んでいる3つ組は常に隣接して いない同じブロックを表しています。 + .. XXX Explain why a dummy is used! + .. versionchanged:: 2.5 隣接する3つ組は常に隣接しないブロックを表すと保証するようになりま した. -.. XXX .. doctest:: + .. doctest:: >>> s = SequenceMatcher(None, "abxcd", "abcd") >>> s.get_matching_blocks() @@ -384,8 +444,9 @@ *a* を *b* にするための方法を記述する5つのタプルを返します。 それぞれのタプルは ``(tag, i1, i2, j1, j2)`` という形式であらわされま す。 - 最初のタプルは ``i1 == j1 == 0`` であり、 *i1* はその前にあるタプル の *i2* と同じ値です。 - 同様に*j1*は前の*j2*と同じ値になります。 + 最初のタプルは ``i1 == j1 == 0`` であり、 + *i1* はその前にあるタプルの *i2* と同じ値です。 + 同様に *j1* は前の *j2* と同じ値になります。 *tag* の値は文字列であり、次のような意味です。 @@ -394,9 +455,9 @@ +===============+===========================================================+ | ``'replace'`` | ``a[i1:i2]`` は ``b[ j1:j2]`` に置き換えられ る | +---------------+-----------------------------------------------------------+ - | ``'delete'`` | ``a[i1:i2]`` は削除される。この時、 ``j1 == j2`` で ある | + | ``'delete'`` | ``a[i1:i2]`` は削除される。この時、 ``j1 == j2`` で ある | +---------------+-----------------------------------------------------------+ - | ``'insert'`` | ``b[j1:j2]`` が ``a [i1:i1]`` に挿入される。この 時 | + | ``'insert'`` | ``b[j1:j2]`` が ``a [i1:i1]`` に挿入される。この 時 | | | ``i1 == i2`` であ る。 | +---------------+-----------------------------------------------------------+ | ``'equal'`` | ``a[i1:i2] == b[j1:j2]`` (この部分シーケンスは同値 ) | @@ -427,37 +488,38 @@ .. versionadded:: 2.3 - .. method:: ratio() - - [0, 1]の範囲の浮動小数点で、シーケンスの同一性を測る値を返します。 - - Tが2つのシーケンスそれぞれがもつ要素の総数だと仮定し、Mをマッチした 数とすると、この値は 2.0\*M / T であらわされます。もしシーケンスがまったく - 同じ場合、値は ``1.0`` となり、まったく異なる場合には ``0.0`` となり ます。 - - このメソッドは :meth:`get_matching_blocks` また は :meth:`get_opcodes` - がまだ呼び出されていない場合には非常にコストが高いです。 - この場合、上限を素早く計算するために、 :meth:`quick_ratio` もしくは - :meth:`real_quick_ratio` を最初に試してみることができます。 - - .. method:: quick_ratio() - - :meth:`ratio` の上界を、より高速に計算します。 - - この関数は、 :meth:`ratio` の値の上界（これ以上になることはないとい う値）を、 - :meth:`ratio` より高速に計算します。 - この関数の計算方法について、詳細な定義はありません。 - - .. method:: real_quick_ratio() - - :meth:`ratio` の上界を、非常に高速に計算します。 - - この関数は、 :meth:`ratio` の値の上界（これ以上になることはないとい う値）を、\ - :meth:`ratio` や :meth:`real_quick_ratio` より高速に計算します。 - この関数の計算方法について、詳細な定義はありません。 + .. method:: ratio() + + [0, 1] の範囲の浮動小数点数で、シーケンスの類似度を測る値を返します。 + + T が2つのシーケンスの要素数の総計だと仮定し、M をマッチした数とする と、 + この値は 2.0\*M / T であらわされます。もしシーケンスがまったく + 同じ場合、値は ``1.0`` となり、まったく異なる場合には ``0.0`` となり ます。 + + このメソッドは :meth:`get_matching_blocks` または :meth:`get_opcodes` + がまだ呼び出されていない場合には非常にコストが高いです。 + この場合、上限を素早く計算するために、 :meth:`quick_ratio` もしくは + :meth:`real_quick_ratio` を最初に試してみる方がいいかもしれません。 + + .. method:: quick_ratio() + + :meth:`ratio` の上界を、より高速に計算します。 + + この関数は、 :meth:`ratio` の値の上界（これ以上になることはないという 値）を、 + :meth:`ratio` より高速に計算します。 + この関数の計算方法について、詳細な定義はありません。 + + .. method:: real_quick_ratio() + + :meth:`ratio` の上界を、非常に高速に計算します。 + + この関数は、 :meth:`ratio` の値の上界（これ以上になることはないという 値）を、 + :meth:`ratio` や :meth:`quick_ratio` より高速に計算します。 + この関数の計算方法について、詳細な定義はありません。 この文字列全体のマッチ率を返す3つのメソッドは、精度の異なる近似値を返しま す。 :meth:`quick_ratio` と :meth:`real_quick_ratio` は、常に :meth:`ratio` -より大きな値を返します。 +以上の値を返します。 >>> s = SequenceMatcher(None, "abcd", "bcde") >>> s.ratio() @@ -473,13 +535,14 @@ SequenceMatcher の例 -------------------- -この例は2つの文字列を比較します。空白を"junk"とします。 +この例は2つの文字列を比較します。空白を junk とします。 >>> s = SequenceMatcher(lambda x: x == " ", ... "private Thread currentThread;", ... "private volatile Thread currentThread;") -:meth:`ratio` は、[0, 1] の範囲の値を返し、シーケンスの同一性を測ります。経 験によると、 :meth:`ratio` +:meth:`ratio` は、[0, 1] の範囲の値を返し、シーケンスの類似度を測ります。 +経験によると、 :meth:`ratio` の値が0.6を超えると、シーケンスがよく似ていることを示します。 >>> print round(s.ratio(), 3) @@ -504,47 +567,60 @@ insert a[8:8] b[8:17] equal a[8:29] b[17:38] -:class:`SequenceMatcher` を使った、シンプルで使えるコードを知るには、このモ ジュールの関数 -:func:`get_close_matches` を参照してください。 - +.. seealso:: + + * :class:`SequenceMatcher` を使った、シンプルで使えるコードを知るには、 + このモジュールの関数 :func:`get_close_matches` を参照してください。 + + * `Simple version control recipe + <http://code.activestate.com/recipes/576729/>`_ + :class:`SequenceMatcher` で作った小規模アプリケーション。 .. _differ-objects: Differ オブジェクト ------------------- -:class:`Differ` オブジェクトによって抽出された差分は、 **最小単位** の差分 を見ても問題なく抽出されます。反対に、最小の差分の場合にはこれとは -反対のように見えます。それらが、どこれも可能ときに同期するからです。時折、 思いがけなく100ページもの部分にマッチします。隣接するマッチ列の -同期するポイントを制限することで、より長い差異を算出する再帰的なコストで の、局所性の概念を制限します。 +:class:`Differ` オブジェクトによって生成された差分が **最小** であるなどと は言いません。 +むしろ、最小の差分はしばしば直観に反しています。 +その理由は、どこでもできるとなれば一致を見いだしてしまうからで、 +ときには思いがけなく100ページも離れたマッチになってしまうのです。 +一致点を互いに隣接したマッチに制限することで、 +場合によって長めの差分を出力するというコストを掛けることにはなっても、 +ある種の局所性を保つことができるのです。 :class:`Differ` は、以下のようなコンストラクタを持ちます。 .. class:: Differ([linejunk[, charjunk]]) - オプションのパラメータ *linejunk* と *charjunk* はfilter関数のために指定 します（もしくは ``None`` を指定）。 - - *linejunk*: ひとつの文字列引数を受け取れるべき関数です。文字列がjunkのと きにtrueを返します。デフォルトでは、 ``None`` - であり、どんな行であってもjunkとは見なされません。 - - *charjunk*: この関数は（長さ1の）文字列を引数として受け取り、文字列が - junkであるときにtrueを返します。デフォルトは ``None`` であり、どんな文字 列も junkとは見なされません。 - -:class:`Differ` オブジェクトは、以下の1つのメソッドを通して利用されます。 （差分を生成します）。 + オプションのパラメータ *linejunk* と *charjunk* はフィルタ関数の指定用で す + (もしくは ``None`` を指定)。 + + *linejunk*: ひとつの文字列引数を受け取る関数です。 + 文字列が junk のときに真を返します。 + デフォルトでは、 ``None`` であり、どんな行であっても junk とは見なされま せん。 + + *charjunk*: この関数は文字(長さ1の文字列)を引数として受け取り、文字が + junk であるときに真を返します。 + デフォルトは ``None`` であり、どんな文字も junk とは見なされません。 + + :class:`Differ` オブジェクトは、以下の1つのメソッドを通して利用されま す。（差分を生成します）。 - .. method:: compare(a, b) - - 文字列からなる2つのシーケンスを比較し、差異（を表す文字列からなる シーケンス）を生成します。 - -.. Each sequence must contain individual single-line strings ending with newlines. -.. Such sequences can be obtained from the :meth:`readlines` method of file-like -.. objects. The delta generated also consists of newline-terminated strings, ready -.. to be printed as-is via the :meth:`writelines` method of a file-like object. + .. method:: compare(a, b) + + 文字列からなる2つのシーケンスを比較し、差分（を表す文字列からなる シーケンス）を生成します。 + + .. Each sequence must contain individual single-line strings ending with newlines. + .. Such sequences can be obtained from the :meth:`readlines` method of file-like + .. objects. The delta generated also consists of newline-terminated strings, ready + .. to be printed as-is via the :meth:`writelines` method of a file-like object. それぞれのシーケンスは、改行文字によって終了する、独立したひと連なり の文字列でなければなりません。そのようなシーケンスは、ファイル形式オブジェク トの - :meth:`readline` メソッドによって得ることができます。（得られる）差 異は - 改行文字で終了する文字列として得られ、ファイル形式オブジェクト の :meth:`writeline` メソッドによって出力できる形になっています。 + :meth:`readlines` メソッドによって得ることができます。（得られる）差 分は + 改行文字で終了する文字列として得られ、ファイル形式オブジェクトの + :meth:`writelines` メソッドによって出力できる形になっています。 .. _differ-examples: @@ -552,8 +628,10 @@ Differ の例 ----------- -この例では2つのテキストを比較します。初めに、改行文字で終了する独立した 1行 の連続した（ファイル形式オブジェクトの :meth:`readlines` メソッドに -よって得られるような）テキストを用意します。 +この例では2つのテキストを比較します。 +初めに、改行文字で終了する独立した1行の連続した +(ファイル形式オブジェクトの :meth:`readlines` メソッドによって得られるよう な) +テキストを用意します。 >>> text1 = ''' 1. Beautiful is better than ugly. ... 2. Explicit is better than implicit. @@ -570,11 +648,12 @@ ... 5. Flat is better than nested. ... '''.splitlines(1) -次にDifferオブジェクトをインスタンス化します。 +次に Differ オブジェクトをインスタンス化します。 >>> d = Differ() -注意： :class:`Differ` オブジェクトをインスタンス化するとき、 "junk."である 列と文字をフィルタリングす関数を渡すことができます。 +注意： :class:`Differ` オブジェクトをインスタンス化するとき、 +行 junk と文字 junk をフィルタリングする関数を渡すことができます。 詳細は :meth:`Differ` コンストラクタを参照してください。 最後に、2つを比較します。 @@ -623,8 +702,8 @@ .. It is also contained in the Python source distribution, as .. :file:`Tools/scripts/diff.py`. -この例は、difflibを使って ``diff`` に似たユーティリティーを作成する方法を示 します。 -これは、Pythonのソース配布物にも、 :file:`Tools/scripts/diff.py` として含ま れています。 +この例は、 difflib を使って ``diff`` に似たユーティリティーを作成する方法を 示します。 +これは、 Python のソース配布物にも、 :file:`Tools/scripts/diff.py` として含 まれています。 .. testcode::
