formatter —一般的な出力フォーマット—Pythonドキュメント

formatter —一般的な出力フォーマット

バージョン3.4以降非推奨：使用法がないため、フォーマッターモジュールは非推奨になりました。

---

このモジュールは、それぞれが複数の実装を持つ2つのインターフェイス定義をサポートします。 formatter インターフェイスと、formatterインターフェイスに必要な writer インターフェイスです。

フォーマッターオブジェクトは、フォーマットイベントの抽象的なフローをライターオブジェクトの特定の出力イベントに変換します。 フォーマッターはいくつかのスタック構造を管理して、ライターオブジェクトのさまざまなプロパティを変更および復元できるようにします。 ライターは、相対的な変更や「元に戻す」操作を処理できる必要はありません。 フォーマッタオブジェクトを介して制御できる特定のライタープロパティは、水平方向の配置、フォント、および左マージンのインデントです。 ライターへの任意の非排他的なスタイル設定の提供もサポートするメカニズムが提供されます。 追加のインターフェースは、段落の分離など、元に戻せないイベントのフォーマットを容易にします。

ライターオブジェクトは、デバイスインターフェイスをカプセル化します。 物理デバイスだけでなく、ファイル形式などの抽象デバイスもサポートされています。 提供されている実装はすべて、抽象デバイスで機能します。 このインターフェースは、フォーマッターオブジェクトが管理するプロパティを設定し、データを出力に挿入するためのメカニズムを利用できるようにします。

フォーマッタインターフェイス

フォーマッターを作成するためのインターフェースは、インスタンス化される特定のフォーマッタークラスに依存します。 以下で説明するインターフェースは、初期化後にすべてのフォーマッターがサポートする必要のある必須インターフェースです。

1つのデータ要素がモジュールレベルで定義されます。

formatter.AS_IS

以下に説明するpush_font()メソッドに渡されるフォント仕様で使用できる値、または他のpush_property()メソッドに新しい値として使用できる値。 AS_IS値を押すと、プロパティが変更されたかどうかを追跡しなくても、対応するpop_property()メソッドを呼び出すことができます。

フォーマッタインスタンスオブジェクトには、次の属性が定義されています。

formatter.writer

フォーマッターが対話するライターインスタンス。

formatter.end_paragraph(blanklines)

開いている段落をすべて閉じ、次の段落の前に少なくとも空白行を挿入します。

formatter.add_line_break()

まだ存在しない場合は、改行を追加します。 これは論理的な段落を壊しません。

formatter.add_hor_rule(*args, **kw)

出力に水平ルールを挿入します。 現在の段落にデータがあるが、論理段落が壊れていない場合、ハードブレークが挿入されます。 引数とキーワードは、ライターのsend_line_break()メソッドに渡されます。

formatter.add_flowing_data(data)

折りたたまれた空白でフォーマットする必要があるデータを提供します。 add_flowing_data（）の前後の呼び出しからの空白も、空白の折りたたみが実行されるときに考慮されます。 このメソッドに渡されるデータは、出力デバイスによってワードラップされることが期待されます。 デバイスとフォントの情報に依存する必要があるため、ワードラップはライターオブジェクトで実行する必要があることに注意してください。

formatter.add_literal_data(data)

変更せずにライターに渡す必要のあるデータを提供します。 data の値では、改行文字とタブ文字を含む空白が正当であると見なされます。

formatter.add_label_data(format, counter)

現在の左マージンの左側に配置する必要があるラベルを挿入します。 これは、箇条書きまたは番号付きリストを作成するために使用する必要があります。 format 値が文字列の場合、 counter のフォーマット指定として解釈されます。これは整数である必要があります。 このフォーマットの結果がラベルの値になります。 format が文字列でない場合は、ラベル値として直接使用されます。 ラベル値は、ライターのsend_label_data()メソッドへの唯一の引数として渡されます。 文字列以外のラベル値の解釈は、関連するライターによって異なります。

フォーマット仕様は、カウンター値と組み合わせてラベル値を計算するために使用される文字列です。 フォーマット文字列の各文字はラベル値にコピーされ、一部の文字はカウンタ値の変換を示すために認識されます。 具体的には、文字'1'は、カウンター値フォーマッターをアラビア数字で表し、文字'A'および'a'は、それぞれ大文字と小文字のカウンター値のアルファベット表現を表します。 'I'および'i'は、大文字と小文字のローマ数字でカウンター値を表します。 アルファベットとローマ字の変換では、カウンター値がゼロより大きい必要があることに注意してください。

formatter.flush_softspace()

add_flowing_data（）への前回の呼び出しでバッファリングされた保留中の空白を関連するライターオブジェクトに送信します。 これは、ライターオブジェクトを直接操作する前に呼び出す必要があります。

formatter.push_alignment(align)

新しい配置設定を配置スタックにプッシュします。 変更が必要ない場合、これは AS_IS の場合があります。 アラインメント値が以前の設定から変更された場合、ライターのnew_alignment()メソッドが align 値で呼び出されます。

formatter.pop_alignment()

以前の配置を復元します。

formatter.push_font((size, italic, bold, teletype))

ライターオブジェクトの一部またはすべてのフォントプロパティを変更します。 AS_IS に設定されていないプロパティは渡された値に設定され、他のプロパティは現在の設定に維持されます。 ライターのnew_font()メソッドは、完全に解決されたフォント仕様で呼び出されます。

formatter.pop_font()

以前のフォントを復元します。

formatter.push_margin(margin)

論理タグ margin を新しいインデントに関連付けて、左マージンのインデントの数を1つ増やします。 初期マージンレベルは0です。 論理タグの変更された値は真の値でなければなりません。 AS_IS 以外のfalse値は、マージンを変更するのに十分ではありません。

formatter.pop_margin()

以前のマージンを復元します。

formatter.push_style(*styles)

任意のスタイル仕様をいくつでもプッシュします。 すべてのスタイルが順番にスタイルスタックにプッシュされます。 AS_IS 値を含むスタック全体を表すタプルは、ライターのnew_styles()メソッドに渡されます。

formatter.pop_style(n=1)

push_style（）に渡された最後の n スタイル仕様をポップします。 AS_IS 値を含む、改訂されたスタックを表すタプルが、ライターのnew_styles()メソッドに渡されます。

formatter.set_spacing(spacing)

ライターの間隔スタイルを設定します。

formatter.assert_line_data(flag=1)

データが帯域外で現在の段落に追加されたことをフォーマッターに通知します。 これは、ライターが直接操作された場合に使用する必要があります。 オプションの flag 引数は、ライターの操作によって出力の最後に改行が生成された場合にfalseに設定できます。

フォーマッターの実装

このモジュールでは、フォーマッタオブジェクトの2つの実装が提供されます。 ほとんどのアプリケーションは、変更やサブクラス化なしでこれらのクラスの1つを使用できます。

class formatter.NullFormatter(writer=None)

何もしないフォーマッター。 writer を省略すると、 NullWriter インスタンスが作成されます。 ライターのメソッドは、 NullFormatter インスタンスによって呼び出されません。 ライターインターフェイスを実装する場合、実装はこのクラスから継承する必要がありますが、実装を継承する必要はありません。

class formatter.AbstractFormatter(writer)

標準のフォーマッタ。 この実装は、多くのライターに広く適用できることを示しており、ほとんどの状況で直接使用できます。 これは、フル機能のWorld WideWebブラウザーを実装するために使用されています。

ライターインターフェイス

ライターを作成するためのインターフェースは、インスタンス化される特定のライタークラスに依存します。 以下で説明するインターフェースは、初期化後にすべてのライターがサポートする必要のある必須インターフェースです。 ほとんどのアプリケーションは AbstractFormatter クラスをフォーマッターとして使用できますが、ライターは通常、アプリケーションによって提供される必要があることに注意してください。

writer.flush()

バッファリングされた出力またはデバイス制御イベントをフラッシュします。

writer.new_alignment(align)

配置スタイルを設定します。 align 値は任意のオブジェクトにすることができますが、慣例により、文字列またはNoneになります。ここで、Noneは、ライターの「優先」配置を使用する必要があることを示します。 従来の align の値は、'left'、'center'、'right'、および'justify'です。

writer.new_font(font)

フォントスタイルを設定します。 font の値はNoneになり、デバイスのデフォルトフォントを使用するか、(size, italic, bold, teletype)の形式のタプルを使用する必要があることを示します。 サイズは、使用するフォントのサイズを示す文字列になります。 特定の文字列とその解釈は、アプリケーションで定義する必要があります。 イタリック、ボールド、およびテレタイプの値は、これらのフォント属性のどれを使用するかを指定するブール値です。

writer.new_margin(margin, level)

マージンレベルを整数レベルに設定し、論理タグをマージンに設定します。 論理タグの解釈は、作成者の裁量に委ねられています。 論理タグの値に対する唯一の制限は、 level のゼロ以外の値に対してfalse値にならないことです。

writer.new_spacing(spacing)

間隔スタイルを spacing に設定します。

writer.new_styles(styles)

追加のスタイルを設定します。 styles 値は、任意の値のタプルです。 値 AS_IS は無視する必要があります。 styles タプルは、アプリケーションとライターの実装の要件に応じて、セットまたはスタックとして解釈できます。

writer.send_line_break()

現在の行を中断します。

writer.send_paragraph(blankline)

少なくとも空白行空白行または同等の段落区切りを作成します。 blankline の値は整数になります。 改行が必要な場合、実装はこの呼び出しの前に send_line_break（）の呼び出しを受け取ることに注意してください。 この方法には、段落の最後の行を終了することを含めないでください。 段落間の垂直方向の間隔にのみ責任があります。

writer.send_hor_rule(*args, **kw)

出力デバイスに水平ルールを表示します。 このメソッドの引数は完全にアプリケーションおよびライターに固有であり、注意して解釈する必要があります。 メソッドの実装では、 send_line_break（）を介して改行がすでに発行されていると想定する場合があります。

writer.send_flowing_data(data)

必要に応じてワードラップおよびリフローできる文字データを出力します。 このメソッドの呼び出しのシーケンス内で、ライターは、複数の空白文字のスパンが単一の空白文字に折りたたまれていると想定する場合があります。

writer.send_literal_data(data)

表示用にフォーマット済みの文字データを出力します。 一般に、これは、改行文字で示される改行を保持し、新しい改行を導入しないことを意味すると解釈する必要があります。 send_formatted_data()インターフェイスに提供されるデータとは異なり、データには改行文字とタブ文字が埋め込まれている場合があります。

writer.send_label_data(data)

可能であれば、 data を現在の左マージンの左側に設定します。 data の値は制限されていません。 文字列以外の値の処理は、アプリケーションとライターに完全に依存します。 このメソッドは、行の先頭でのみ呼び出されます。

ライターの実装

このモジュールでは、ライターオブジェクトインターフェイスの3つの実装が例として提供されています。 ほとんどのアプリケーションは、 NullWriter クラスから新しいライタークラスを派生させる必要があります。

class formatter.NullWriter

インターフェイス定義のみを提供するライター。 どのメソッドに対してもアクションは実行されません。 これは、実装メソッドを継承する必要のないすべてのライターの基本クラスである必要があります。

class formatter.AbstractWriter

フォーマッターのデバッグに使用できるライターですが、それ以外はあまり使用できません。 各メソッドは、その名前と引数を標準出力に出力することで、それ自体をアナウンスするだけです。

class formatter.DumbWriter(file=None, maxcol=72)

ファイルオブジェクトにファイルとして渡された出力、またはファイルが省略されている場合は標準出力に出力を書き込む単純なライタークラス。 出力は、 maxcol で指定された列数に単純にワードラップされます。 このクラスは、一連の段落をリフローするのに適しています。