"reprlib" --- もう一つの "repr()" の実装
****************************************

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

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

"reprlib" モジュールは、結果の文字列のサイズに対する制限付きでオブジェ
クト表現を生成するための手段を提供します。これは Python デバッガの中で
使用されており、他の文脈でも同様に役に立つかもしれません。

このモジュールはクラスとインスタンス、それに関数を提供します:

class reprlib.Repr

   組み込み関数 "repr()" に似た関数を実装するために役に立つフォーマッ
   ト用サービスを提供します。 過度に長い表現を作り出さないようにするた
   めの大きさの制限をオブジェクト型ごとに設定できます。

reprlib.aRepr

   これは下で説明される "repr()" 関数を提供するために使われる "Repr"
   のインスタンスです。このオブジェクトの属性を変更すると、 "repr()"
   と Python デバッガが使うサイズ制限に影響します。

reprlib.repr(obj)

   これは "aRepr" の "repr()" メソッドです。同じ名前の組み込み関数が返
   す文字列と似ていますが、最大サイズに制限のある文字列を返します。

サイズを制限するツールに加えて、このモジュールはさらに  "__repr__()"
に対する再帰呼び出しの検出とプレースホルダー文字列による置換のためのデ
コレータを提供します。

@reprlib.recursive_repr(fillvalue='...')

   "__repr__()" メソッドに対する同一スレッド内の再帰呼び出しを検出する
   デコレータです。再帰呼び出しが行われている場合 *fillvalue* が返され
   ます。そうでなければ通常の "__repr__()" 呼び出しが行われます。例え
   ば:

   >>> from reprlib import recursive_repr
   >>> class MyList(list):
   ...     @recursive_repr()
   ...     def __repr__(self):
   ...         return '<' + '|'.join(map(repr, self)) + '>'
   ...
   >>> m = MyList('abc')
   >>> m.append(m)
   >>> m.append('x')
   >>> print(m)
   <'a'|'b'|'c'|...|'x'>

   バージョン 3.2 で追加.


Reprオブジェクト
================

"Repr" インスタンスはオブジェクト型毎に表現する文字列のサイズを制限す
るために使えるいくつかの属性と、特定のオブジェクト型をフォーマットする
メソッドを提供します。

Repr.maxlevel

   再帰的な表現を作る場合の深さ制限。デフォルトは "6" です。

Repr.maxdict
Repr.maxlist
Repr.maxtuple
Repr.maxset
Repr.maxfrozenset
Repr.maxdeque
Repr.maxarray

   指定されたオブジェクト型に対するエントリ表現の数についての制限。
   "maxdict" に対するデフォルトは "4" で、 "maxarray" は "5" 、その他
   に対しては "6" です。

Repr.maxlong

   整数の表現のおける文字数の最大値。中央の数字が抜け落ちます。デフォ
   ルトは "40" です。

Repr.maxstring

   文字列の表現における文字数の制限。文字列の"通常の"表現は文字の「元
   」として使われることに注意してください。表現にエスケープシーケンス
   が必要とされる場合、表現が短縮されるときにこれらのエスケープシーケ
   ンスの形式は崩れます。デフォルトは "30" です。

Repr.maxother

   この制限は "Repr" オブジェクトに利用できる特定のフォーマットメソッ
   ドがないオブジェクト型のサイズをコントロールするために使われます。
   "maxstring" と同じようなやり方で適用されます。デフォルトは "20" で
   す。

Repr.repr(obj)

   このインスタンスで設定されたフォーマットを使う、組み込み "repr()"
   と等価なもの。

Repr.repr1(obj, level)

   "repr()" が使う再帰的な実装。 *obj* の型を使ってどのフォーマットメ
   ソッドを呼び出すかを決定し、それに *obj* と *level* を渡します。 再
   帰呼び出しにおいて *level* の値に対して "level - 1" を与える再帰的
   なフォーマットを実行するために、型に固有のメソッドは "repr1()" を呼
   び出します。

Repr.repr_TYPE(obj, level)

   型名に基づく名前をもつメソッドとして、特定の型に対するフォーマット
   メソッドは実装されます。メソッド名では、 **TYPE** は
   "'_'.join(type(obj).__name__.split())" に置き換えられます。これらの
   メソッドへのディスパッチは "repr1()" によって処理されます。再帰的に
   値をフォーマットする必要がある型固有のメソッドは、
   "self.repr1(subobj, level - 1)" を呼び出します。


Reprオブジェクトをサブクラス化する
==================================

更なる組み込みオブジェクト型へのサポートを追加するため、あるいはすでに
サポートされている型の扱いを変更するために、 "Repr.repr1()" による動的
なディスパッチは "Repr" のサブクラス化に対応しています。 この例はファ
イルオブジェクトのための特別なサポートを追加する方法を示しています:

   import reprlib
   import sys

   class MyRepr(reprlib.Repr):

       def repr_TextIOWrapper(self, obj, level):
           if obj.name in {'<stdin>', '<stdout>', '<stderr>'}:
               return obj.name
           return repr(obj)

   aRepr = MyRepr()
   print(aRepr.repr(sys.stdin))         # prints '<stdin>'
