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

   getParent()

      親リーダを返します。 設定されていなければ "None" を返します。

   setParent(parent)

      イベントの読み取り元となる親リーダを設定します。

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

   入力ソースと省略可能なベース URL を受け取り、必要な解決をすべて行っ
   た読み取り可能な "InputSource" オブジェクトを返します。 入力ソース
   には文字列、ファイル風オブジェクト、"InputSource" オブジェクトを指
   定できます。 パーサはこの関数を使い、"parse()" メソッドの *source*
   引数が複数の型を受け取れるように実装します。
