# `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;'` を元の文字に戻します。

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

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

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