8.12. "UserDict" --- 辞書オブジェクトのためのクラスラッパー
***********************************************************

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

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

このモジュールは最小限のマッピングインターフェイスをすでに持っているク
ラスのために、すべての辞書メソッドを定義しているmixin、 "DictMixin" を
定義しています。これによって、 (shelveモジュールのような) 辞書の代わり
をする必要があるクラスを書くことが非常に簡単になります。

このモジュールでは "UserDict" クラスも定義しています。 これは辞書オブ
ジェクトのラッパーとして動作します。 これの必要性については既に "dict"
を直接的にサブクラス化出来るようになった (Python 2.2 から利用可能な機
能です) ことによって大幅に取って代わられています。 "dict" の導入以前に
は、 "UserDict" クラスはメソッドをオーバライドしたり新しいメソッドを追
加して、辞書風のサブクラスを作成するために使われていました。

"UserDict" モジュールは "UserDict" クラスと "DictMixin" を定義していま
す:

class UserDict.UserDict([initialdata])

   辞書をシミュレートするクラスです。 インスタンスの内容は通常の辞書に
   保存され、 "UserDict" インスタンスの "data" 属性を通してアクセスで
   きます。 *initialdata* が与えられた場合は、 "data" はその内容で初期
   化されます; 他の目的のために使えるように、 *initialdata* への参照が
   保存されないことがあるということに注意してください。

   注釈: 後方互換性のために、 "UserDict" のインスタンスはイテレート
     可能で はありません。

class UserDict.IterableUserDict([initialdata])

   "UserDict" のイテレーションをサポートするサブクラス (使用例: "for
   key in myDict").

マッピングのメソッドと演算 (マッピング型 --- dict を参照) に加えて、
"UserDict" 、 "IterableUserDict" インスタンスは次の属性を提供します:

IterableUserDict.data

   "UserDict" クラスの内容を保存するために使われる実際の辞書です。

class UserDict.DictMixin

   "__getitem__()" 、 "__setitem__()" 、 "__delitem__()" および
   "keys()" といった最小の辞書インタフェースを既に持っているクラスのた
   めに、全ての辞書メソッドを定義する mixin です。

   この mixin はスーパークラスとして使われるべきです。上のそれぞれのメ
   ソッドを追加することで、より多くの機能がだんだん追加されます。例え
   ば、 "__delitem__()" 以外の全てのメソッドを定義すると、使えないのは
   "pop()" と "popitem()" だけになります。

   4 つの基底メソッドに加えて、 "__contains__()" 、 "__iter__()" およ
   び "iteritems()" を定義すれば、順次能力を増やしていけます。

   mixin はサブクラスのコンストラクタについて何も知らないので、
   "__init__()" や "copy()" は定義していません。

   Python 2.6 からは、 "DictMixin" の代わりに、
   "collections.MutableMapping" を利用することが推奨されています。

   DictMixin は "viewkeys()", "viewvalues()", "viewitems()" メソッドを
   実装していないことに注意してください。


8.13. "UserList" --- リストオブジェクトのためのクラスラッパー
*************************************************************

注釈: Python 2.2 がリリースされた際、 "list" から直接的にサブクラス
  化する ことがこのクラスの多くのユースケースを包含することとなりまし
  た。です がわずかばかりのユースケースが健在です。このモジュールは下
  層のデータ ストアを包むリストインターフェイスを提供します。デフォル
  トではデータ ストアは "list" ですが、(例えば永続化記憶のような) 他の
  オブジェクト に対してリストのようなインターフェイスで包むのに使うこ
  とが出来ます。 加えて、このクラスは多重継承を使って、組み込みクラス
  に mixin できま す。 これが役に立つときがあって、例えば "UserList"
  と "str" の両方を 同時に継承できます。 本物の "list" と本物の "str"
  ではこれはできない でしょう。

このモジュールはリストオブジェクトのラッパーとして働くクラスを定義しま
す。独自のリストに似たクラスのために役に立つ基底クラスで、これを継承し
既存のメソッドをオーバーライドしたり、あるいは、新しいものを追加したり
することができます。このような方法で、リストに新しい振る舞いを追加でき
ます。

"UserList" モジュールは "UserList" クラスを定義しています:

class UserList.UserList([list])

   リストをシミュレートするクラスです。 インスタンスの内容は通常のリス
   トに保存され、 "UserList" インスタンスの "data" 属性を通してアクセ
   スできます。 インスタンスの内容は最初に *list* のコピーに設定されま
   すが、デフォルトでは空リスト "[]" です。 *list* は何らかのイテラブ
   ル、例えば通常の Python リストや "UserList" オブジェクトです。

   注釈: "UserList" モジュールは、Python 3 では "collections" に移動
     しまし た。 *2to3* ツールは、ソースコードの import を自動的に
     Python 3 向けに修正します。

可変シーケンスのメソッドと演算 (シーケンス型 --- str, unicode, list,
tuple, bytearray, buffer, xrange を参照) に加えて、 "UserList" インス
タンスは次の属性を提供します:

UserList.data

   "UserList" クラスの内容を保存するために使われる実際の Python リスト
   オブジェクト。

**サブクラス化の要件:** "UserList" のサブクラスは引数なしか、あるいは
一つの引数のどちらかとともに呼び出せるコンストラクタを提供することが期
待されています。 新しいシーケンスを返すリスト演算は現在の実装クラスの
インスタンスを作成しようとします。 そのために、データ元として使われる
シーケンスオブジェクトである一つのパラメータとともにコンストラクタを呼
び出せると想定しています。

派生クラスがこの要求に従いたくないならば、このクラスがサポートしている
すべての特殊メソッドはオーバーライドされる必要があります。その場合に提
供される必要のあるメソッドについての情報は、ソースを参考にしてください
。

バージョン 2.0 で変更: Python バージョン 1.5.2 と 1.6 では、コンストラ
クタが引数なしで呼び出し可能であることと変更可能な "data" 属性を提供す
るということも要求されていました。Pythonの初期のバージョンでは、派生ク
ラスのインスタンスを作成しようとはしません。


8.14. "UserString" --- 文字列オブジェクトのためのクラスラッパー
***************************************************************

注釈: このモジュールの "UserString" クラスは後方互換性のためだけに残
  されて います。 書いているコードが Python 2.2 より前のバージョンの
  Python で動作する必要が無いのならば、 "UserString" を使う代わりに組
  み込み "str" 型から直接サブクラス化することを検討してください (組み
  込みの "MutableString" と等価なものはありません)。

このモジュールは文字列オブジェクトのラッパーとして働くクラスを定義しま
す。独自の文字列に似たクラスのために役に立つ基底クラスで、これを継承し
既存のメソッドをオーバーライドしたり、あるいは、新しいものを追加したり
することができます。このような方法で、文字列に新しい振る舞いを追加でき
ます。

これらのクラスは本物の文字列や Unicode オブジェクトに比べてとてつもな
く非効率であるということに注意すべきです。これは特に "MutableString"
に対して当てはまります。

"UserString" モジュールは次のクラスを定義しています:

class UserString.UserString([sequence])

   文字列または Unicode 文字列オブジェクトをシミュレートするクラスです
   。 インスタンスの内容は通常の文字列または Unicode 文字列オブジェク
   トに保存され、 "UserString" インスタンスの "data" 属性を通してアク
   セスできます。 インスタンスの内容は最初に *sequence* のコピーに設定
   されます。 *sequence* は通常の Python 文字列または Unicode 文字列、
   "UserString" (またはサブクラス) のインスタンス、あるいは組み込み
   "str()" 関数を使って文字列に変換できる任意のシーケンスのいずれかで
   す。

   注釈: "UserString" クラスは、Python 3 では "collections" に移動し
     ました 。 *2to3* ツールは、ソースコードの import を自動的に
     Python 3 向 けに修正します。

class UserString.MutableString([sequence])

   このクラスは上の "UserString" から派生し、 *可変に* なるように文字
   列を再定義します。 可変な文字列は辞書のキーとして使うことができませ
   ん。 なぜなら、辞書はキーとして *不変な* オブジェクトを要求するから
   です。 このクラスの主な目的は、辞書のキーとして可変なオブジェクトを
   使うという試みを捕捉するために、継承と "__hash__()" メソッドを取り
   除く (オーバーライドする) 必要があることを示す教育的な例を提供する
   ことです。 そうしなければ、非常にエラーになりやすく、その原因を突き
   止めることが困難でしょう。

   バージョン 2.6 で非推奨: "MutableString" クラスは Python 3 で削除さ
   れました。

文字列および Unicode オブジェクトのメソッドと演算 (文字列メソッド を参
照) に加えて、 "UserString" インスタンスは次の属性を提供します:

MutableString.data

   "UserString" クラスの内容を保存するために使われる実際の Python 文字
   列または Unicode オブジェクト。
