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

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

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

The module "xml.sax.saxutils" contains a number of classes and
functions that are commonly useful when creating SAX applications,
either in direct use, or as base classes.

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

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

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

   注釈:

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

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

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

   You can unescape other strings of data by passing a dictionary as
   the optional *entities* parameter.  The keys and values must all be
   strings; each key will be replaced with its corresponding value.
   "'&amp;'", "'&lt;'", and "'&gt;'" are always unescaped, even if
   *entities* is provided.

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()

      Return the parent reader, or "None" if it is not set.

   setParent(parent)

      Set the parent reader, which the events are read from.

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

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