8.18. "pprint" --- データ出力の整然化
*************************************

**ソースコード:** Lib/pprint.py

======================================================================

"pprint" モジュールを使うと、Pythonの任意のデータ構造をインタープリタ
への入力で使われる形式にして"pretty-print"できます。フォーマット化され
た構造の中にPythonの基本的なタイプではないオブジェクトがあるなら、表示
できないかもしれません。 Pythonの定数として表現できない多くの組み込み
オブジェクトと同様、ファイル、ソケット、クラスあるいはインスタンスのよ
うなオブジェクトが含まれていた場合は出力できません。

可能であればオブジェクトをフォーマット化して1行に出力しますが、与えら
れた幅に合わないなら複数行に分けて出力します。無理に幅を設定したいなら
、 "PrettyPrinter" オブジェクトを作成して明示してください。

バージョン 2.5 で変更: 辞書は出力を計算する前にキーでソートされます。
2.5 以前では、辞書は 1 行以上の出力が必要な場合にのみソートされていま
したがドキュメントには書かれていませんでした。

バージョン 2.6 で変更: "set" と "frozenset" がサポートされました。

"pprint" モジュールには1つのクラスが定義されています:

class pprint.PrettyPrinter(indent=1, width=80, depth=None, stream=None)

   "PrettyPrinter" インスタンスを作ります。このコンストラクタにはいく
   つかのキーワードパラメータを設定できます。 *stream* キーワードで出
   力ストリームを設定できます; このストリームに対して呼び出されるメソ
   ッドはファイルプロトコルの "write()" メソッドだけです。もし設定され
   なければ、 "PrettyPrinter" は "sys.stdout" を使用します。さらに3つ
   のパラメータで出力フォーマットをコントロールできます。そのキーワー
   ドは *indent* 、 *depth* と *width* です。再帰的なレベルごとに加え
   るインデントの量は *indent* で設定できます; デフォルト値は1です。他
   の値にすると出力が少しおかしく見えますが、ネスト化されたところが見
   分け易くなります。出力されるレベルは *depth* で設定できます; 出力さ
   れるデータ構造が深いなら、指定以上の深いレベルのものは "..." で置き
   換えられて表示されます。デフォルトでは、オブジェクトの深さを制限し
   ません。 *width* パラメータを使うと、出力する幅を望みの文字数に設定
   できます; デフォルトでは80文字です。もし指定した幅にフォーマットで
   きない場合は、できるだけ近づけます。

   >>> import pprint
   >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
   >>> stuff.insert(0, stuff[:])
   >>> pp = pprint.PrettyPrinter(indent=4)
   >>> pp.pprint(stuff)
   [   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
       'spam',
       'eggs',
       'lumberjack',
       'knights',
       'ni']
   >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
   ... ('parrot', ('fresh fruit',))))))))
   >>> pp = pprint.PrettyPrinter(depth=6)
   >>> pp.pprint(tup)
   ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))

"PrettyPrinter" クラスにはいくつかの派生する関数が提供されています:

pprint.pformat(object, indent=1, width=80, depth=None)

   *object* をフォーマット化して文字列として返します。 *indent* 、
   *width* と、 *depth* は "PrettyPrinter" コンストラクタにフォーマッ
   ト指定引数として渡されます。

   バージョン 2.4 で変更: 引数 *indent* 、 *width* と、 *depth* が追加
   されました.

pprint.pprint(object, stream=None, indent=1, width=80, depth=None)

   *stream* 上に *object* のフォーマットされた表現を出力して、その後に
   newline を続けます。 *stream* が "None" の場合、 "sys.stdout" が使
   用されます。これは、対話型インタプリタの中で値を調査するために
   "print" 文の代わりに使用されることがあります。 *indent*, *width*,
   *depth* は、フォーマットパラメータとして "PrettyPrinter" コンストラ
   クタに渡されます。

   >>> import pprint
   >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
   >>> stuff.insert(0, stuff)
   >>> pprint.pprint(stuff)
   [<Recursion on list with id=...>,
    'spam',
    'eggs',
    'lumberjack',
    'knights',
    'ni']

   バージョン 2.4 で変更: 引数 *indent* 、 *width* と、 *depth* が追加
   されました.

pprint.isreadable(object)

   *object* をフォーマット化して出力できる（"readable"）か、あるいは
   "eval()" を使って値を再構成できるかを返します。再帰的なオブジェクト
   に対しては常に "False" を返します。

   >>> pprint.isreadable(stuff)
   False

pprint.isrecursive(object)

   *object* が再帰的な表現かどうかを返します。

さらにもう1つ、関数が定義されています:

pprint.saferepr(object)

   *object* の文字列表現を、再帰的なデータ構造から保護した形式で返しま
   す。もし *object* の文字列表現が再帰的な要素を持っているなら、再帰
   的な参照は "<Recursion on typename with id=number>" で表示されます
   。出力は他と違ってフォーマット化されません。

   >>> pprint.saferepr(stuff)
   "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"


8.18.1. PrettyPrinter オブジェクト
==================================

"PrettyPrinter" インスタンスには以下のメソッドがあります:

PrettyPrinter.pformat(object)

   *object* のフォーマット化した表現を返します。これは "PrettyPrinter"
   のコンストラクタに渡されたオプションを考慮してフォーマット化されま
   す。

PrettyPrinter.pprint(object)

   *object* のフォーマット化した表現を指定したストリームに出力し、最後
   に改行します。

以下のメソッドは、対応する同じ名前の関数と同じ機能を持っています。以下
のメソッドをインスタンスに対して使うと、新たに "PrettyPrinter" オブジ
ェクトを作る必要がないのでちょっぴり効果的です。

PrettyPrinter.isreadable(object)

   *object* をフォーマット化して出力できる（"readable"）か、あるいは
   "eval()" を使って値を再構成できるかを返します。これは再帰的なオブジ
   ェクトに対して "False" を返すことに注意して下さい。もし
   "PrettyPrinter" の *depth* パラメータが設定されていて、オブジェクト
   のレベルが設定よりも深かったら、 "False" を返します。

PrettyPrinter.isrecursive(object)

   オブジェクトが再帰的な表現かどうかを返します。

このメソッドをフックとして、サブクラスがオブジェクトを文字列に変換する
方法を修正するのが可能になっています。デフォルトの実装では、内部で
"saferepr()" を呼び出しています。

PrettyPrinter.format(object, context, maxlevels, level)

   次の3つの値を返します。*object* をフォーマット化して文字列にしたも
   の、その結果が読み込み可能かどうかを示すフラグ、再帰が含まれている
   かどうかを示すフラグ。最初の引数は表示するオブジェクトです。 2つめ
   の引数はオブジェクトの "id()" をキーとして含むディクショナリで、オ
   ブジェクトを含んでいる現在の（直接、間接に *object* のコンテナとし
   て表示に影響を与える）環境です。ディクショナリ *context* の中でどの
   オブジェクトが表示されたか表示する必要があるなら、3つめの返り値は
   "True" になります。 "format()" メソッドの再帰呼び出しではこのディク
   ショナリのコンテナに対してさらにエントリを加えます。 3つめの引数
   *maxlevels* で再帰呼び出しのレベルを制限します。制限しない場合、
   "0" になります。この引数は再帰呼び出しでそのまま渡されます。 4つめ
   の引数 *level* で現在のレベルを設定します。再帰呼び出しでは、現在の
   呼び出しより小さい値が渡されます。

   バージョン 2.3 で追加.


8.18.2. pprint の例
===================

この例は "pprint()" 関数とその引数の幾つかの使い方を例示しています。

>>> import pprint
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> stuff = ['a' * 10, tup, ['a' * 30, 'b' * 30], ['c' * 20, 'd' * 20]]
>>> pprint.pprint(stuff)
['aaaaaaaaaa',
 ('spam',
  ('eggs',
   ('lumberjack',
    ('knights', ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
>>> pprint.pprint(stuff, depth=3)
['aaaaaaaaaa',
 ('spam', ('eggs', (...))),
 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
>>> pprint.pprint(stuff, width=60)
['aaaaaaaaaa',
 ('spam',
  ('eggs',
   ('lumberjack',
    ('knights',
     ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
  'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
