\section{\module{pprint} ---
         データ出力の整然化}

\declaremodule{standard}{pprint}
\modulesynopsis{Data pretty printer.}
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}


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

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

\versionchanged[辞書は出力を計算する前にキーでソートされます。
2.5以前では、辞書は1行以上必要な場合にのみソートされていましたが
ドキュメントには書かれていませんでした。 ]{2.5}

\module{pprint}モジュールには1つのクラスが定義されています：


% First the implementation class:

\begin{classdesc}{PrettyPrinter}{...}
\class{PrettyPrinter}インスタンスを作ります。
このコンストラクタにはいくつかのキーワードパラメータを設定できます。

\var{stream}キーワードで出力ストリームを設定できます；このストリームに対
して呼び出されるメソッドはファイルプロトコルの\method{write()}メソッドだ
けです。
もし設定されなければ、\class{PrettyPrinter}は\code{sys.stdout}を使用しま
す。
さらに3つのパラメータで出力フォーマットをコントロールできます。
そのキーワードは\var{indent}、\var{depth}と\var{width}です。

再帰的なレベルごとに加えるインデントの量は\var{indent}で設定できます；デ
フォルト値は1です。
他の値にすると出力が少しおかしく見えますが、ネスト化されたところが見分け
易くなります。

出力されるレベルは\var{depth}で設定できます；
出力されるデータ構造が深いなら、指定以上の深いレベルのものは\samp{...}で
置き換えられて表示されます。
デフォルトでは、オブジェクトの深さを制限しません。

\var{width}パラメータを使うと、出力する幅を望みの文字数に設定できます；
デフォルトでは80文字です。
もし指定した幅にフォーマットできない場合は、できるだけ近づけます。

\begin{verbatim}
>>> import pprint, sys
>>> stuff = sys.path[:]
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[   [   '',
        '/usr/local/lib/python1.5',
        '/usr/local/lib/python1.5/test',
        '/usr/local/lib/python1.5/sunos5',
        '/usr/local/lib/python1.5/sharedmodules',
        '/usr/local/lib/python1.5/tkinter'],
    '',
    '/usr/local/lib/python1.5',
    '/usr/local/lib/python1.5/test',
    '/usr/local/lib/python1.5/sunos5',
    '/usr/local/lib/python1.5/sharedmodules',
    '/usr/local/lib/python1.5/tkinter']
>>>
>>> import parser
>>> tup = parser.ast2tuple(
...     parser.suite(open('pprint.py').read()))[1][1][1]
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
(266, (267, (307, (287, (288, (...))))))
\end{verbatim}
\end{classdesc}


% Now the derivative functions:

\class{PrettyPrinter}クラスにはいくつかの派生する関数が提供されていま
す：

\begin{funcdesc}{pformat}{object\optional{, indent\optional{,
width\optional{, depth}}}}
\var{object}をフォーマット化して文字列として返します。
\var{indent}、\var{width}と、\var{depth}は\class{PrettyPrinter}コンス
トラクタにフォーマット指定引数として渡されます。
\versionchanged[引数 \var{indent}、 \var{width}と、\var{depth}が追加されました]{2.4}
\end{funcdesc}

\begin{funcdesc}{pprint}{object\optional{, stream\optional{,
indent\optional{, width\optional{, depth}}}}}
\var{object}をフォーマット化して\var{stream}に出力し、最後に改行します。
\var{stream}が省略されたら、\code{sys.stdout}に出力します。
これは対話型のインタープリタ上で、求める値を\keyword{print}する代わりに
使用できます。
\var{indent}、\var{width}と、\var{depth}は\class{PrettyPrinter}コンス
トラクタにフォーマット指定引数として渡されます。

\begin{verbatim}
>>> stuff = sys.path[:]
>>> stuff.insert(0, stuff)
>>> pprint.pprint(stuff)
[<Recursion on list with id=869440>,
 '',
 '/usr/local/lib/python1.5',
 '/usr/local/lib/python1.5/test',
 '/usr/local/lib/python1.5/sunos5',
 '/usr/local/lib/python1.5/sharedmodules',
 '/usr/local/lib/python1.5/tkinter']
\end{verbatim}
\versionchanged[引数 \var{indent}、 \var{width}と、\var{depth}が追加さ
  れました]{2.4}
\end{funcdesc}

\begin{funcdesc}{isreadable}{object}
\var{object}をフォーマット化して出力できる（``readable''）か、あるいは
\function{eval()}\bifuncindex{eval}を使って値を再構成できるかを返しま
す。
再帰的なオブジェクトに対しては常にfalseを返します。

\begin{verbatim}
>>> pprint.isreadable(stuff)
False
\end{verbatim}
\end{funcdesc}

\begin{funcdesc}{isrecursive}{object}
\var{object}が再帰的な表現かどうかを返します。
\end{funcdesc}


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

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

\end{funcdesc}

% This example is outside the {funcdesc} to keep it from running over
% the right margin.
\begin{verbatim}
>>> pprint.saferepr(stuff)
"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"
\end{verbatim}


\subsection{PrettyPrinter オブジェクト}
\label{PrettyPrinter Objects}

\class{PrettyPrinter}インスタンスには以下のメソッドがあります：

\begin{methoddesc}[PrettyPrinter]{pformat}{object}
\var{object}のフォーマット化した表現を返します。
これは\class{PrettyPrinter}のコンストラクタに渡されたオプションを考慮し
てフォーマット化されます。
\end{methoddesc}

\begin{methoddesc}[PrettyPrinter]{pprint}{object}
\var{object}のフォーマット化した表現を指定したストリームに出力し、最後に
改行します。
\end{methoddesc}

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

\begin{methoddesc}[PrettyPrinter]{isreadable}{object}
\var{object}をフォーマット化して出力できる（``readable''）か、あるいは
\function{eval()}\bifuncindex{eval}を使って値を再構成できるかを返しま
す。
これは再帰的なオブジェクトに対してfalseを返すことに注意して下さい。
もし\class{PrettyPrinter}の\var{depth}パラメータが設定されていて、オブ
ジェクトのレベルが設定よりも深かったら、falseを返します。
\end{methoddesc}

\begin{methoddesc}[PrettyPrinter]{isrecursive}{object}
オブジェクトが再帰的な表現かどうかを返します。
\end{methoddesc}

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

\begin{methoddesc}[PrettyPrinter]{format}{object, context, maxlevels, level}
3つの値を返します：\var{object}をフォーマット化して文字列にしたもの、そ
の結果が読み込み可能かどうかを示すフラグ、再帰が含まれているかどうかを示
すフラグ。

最初の引数は表示するオブジェクトです。
2つめの引数はオブジェクトの\function{id()}をキーとして含むディクショナリ
で、オブジェクトを含んでいる現在の（直接、間接に\var{object}のコンテナと
して表示に影響を与える）環境です。
ディクショナリ\var{context}の中でどのオブジェクトが表示されたか表示する
必要があるなら、3つめの返り値はtrueになります。
\method{format()}メソッドの再帰呼び出しではこのディクショナリのコンテナ
に対してさらにエントリを加えます。
3つめの引数\var{maxlevels}で再帰呼び出しのレベルを設定します；
もし制限しないなら、\code{0}にします。
この引数は再帰呼び出しでそのまま渡されます。
4つめの引数\var{level}で現在のレベルを設定します；
再帰呼び出しでは、現在の呼び出しより小さい値が渡されます。
\versionadded{2.3}
\end{methoddesc}
