"xml.sax.saxutils" --- SAX ユーティリティー
*******************************************

**ソースコード:** Lib/xml/sax/saxutils.py

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

モジュール "xml.sax.saxutils" には SAX アプリケーションの作成に役立つ
多くの関数やクラスも含まれており、直接利用したり、基底クラスとして使う
ことができます。

xml.sax.saxutils.escape(data, entities={})

   文字列データ内の "'&'", "'<'", "'>'" をエスケープします。

   オプションの *entities* 引数に辞書を渡すことで、そのほかの文字列デ
   ータをエスケープすることも可能です。辞書のキーと値はすべて文字列で
   、キーは対応する値に置換されます。*entities* が与えられている場合で
   も、 "'&'", "'<'", "'>'" は常にエスケープされます。

   注釈:

     この関数は、 XML 内で直接使用できない文字のエスケープにのみ使用す
     るべきです。この関数を一般的な文字列変換関数のように使用してはな
     りません。

xml.sax.saxutils.unescape(data, entities={})

   エスケープされた文字列 "'&amp;'", "'&lt;'", "'&gt;'" を元の文字に戻
   します。

   オプションの *entities* 引数に辞書を渡すことで、そのほかの文字列デ
   ータをエスケープ解除することも可能です。辞書のキーと値はすべて文字
   列で、キーは対応する値に置換されます。*entities* が与えられている場
   合でも、"'&amp'", "'&lt;'", and "'&gt;'" は常に元の文字に戻されます
   。

xml.sax.saxutils.quoteattr(data, entities={})

   "escape()" に似ていますが、 *data* は属性値の作成に使われます。戻り
   値はクォート済みの *data* で、置換する文字の追加も可能です。
   "quoteattr()" はクォートすべき文字を *data* の文脈から判断し、クォ
   ートすべき文字を残さないように文字列をエンコードします。 *data* の
   中にシングル・クォート、ダブル・クォートがあれば、両方ともエンコー
   ドし、全体をダブルクォートで囲みます。戻り値の文字列はそのままで属
   性値として利用できます:

      >>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef"))
      <element attr="ab ' cd &quot; ef">

   この関数は参照具象構文を使って、 HTML や SGML の属性値を生成するの
   に便利です。

class xml.sax.saxutils.XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False)

   このクラスは SAX イベントを XML 文書に書き戻すことで
   "ContentHandler" インターフェースを実装しています。 つまり、
   "XMLGenerator" をコンテントハンドラとして用いることで、パースしてい
   る元々の文書を複製することが出来ます。 *out* にはファイル様オブジェ
   クトでなければなりません。 デフォルトは *sys.stdout* です。
   *encoding* は出力ストリームのエンコーディングで、デフォルトは
   "'iso-8859-1'" です。 *short_empty_elements* は 内容を持たない要素
   のフォーマットを制御します。 "False" (デフォルト) の場合、開始/終了
   タグのペアとなり、 "True" の場合、1つの空タグになります。

   バージョン 3.2 で変更: *short_empty_elements* 引数を追加しました。

class xml.sax.saxutils.XMLFilterBase(base)

   このクラスは "XMLReader" とクライアント・アプリケーションのイベント
   ・ハンドラとの間に位置するものとして設計されています。デフォルトで
   は何もせず、ただリクエストをリーダに、イベントをハンドラに、それぞ
   れ加工せず渡すだけです。しかし、サブクラスでメソッドをオーバーライ
   ドすると、イベント・ストリームやリクエストを加工してから渡すように
   変更可能です。

xml.sax.saxutils.prepare_input_source(source, base='')

   この関数は引数に入力ソース、オプションとして URL を取り、読み取り可
   能な解決済み "InputSource" オブジェクトを返します。入力ソースは文字
   列、ファイル風オブジェクト、 "InputSource" のいずれでも良く、この関
   数を使うことで、パーサは様々な *source* 引数を "parse()" メソッドに
   実装することが可能になります。
