19.14. "xml.sax.xmlreader" --- XML パーサのインタフェース
*********************************************************

バージョン 2.0 で追加.

各 SAX パーサは Python モジュールとして "XMLReader" インタフェースを実
装しており、関数 "create_parser()" を提供しています。この関数は新たな
パーサ・オブジェクトを生成する際、 "xml.sax.make_parser()" から引数な
しで呼び出されます。

class xml.sax.xmlreader.XMLReader

   SAX パーサが継承可能な基底クラスです。

class xml.sax.xmlreader.IncrementalParser

   入力ソースを一度にパースせずに、利用可能なように文書のチャンクを入
   力したい場合があります。 SAX リーダは、通常はファイル全体を読み込み
   ませんが、チャンクで読み込むことに注意してください。 それでも
   "parse()" は文書全体が処理されるまで return しません。 そのため、
   "parse()" のブロックする挙動を望まない場合はこれらのインターフェイ
   スを使用してください。

   パーサのインスタンスが作成されると、feed メソッドを通じてすぐに、デ
   ータを受け入れられるようになります。close メソッドの呼出しでパース
   が終わると、パーサは新しいデータを受け入れられるように、reset メソ
   ッドを呼び出されなければなりません。

   これらのメソッドをパース処理の途中で呼び出すことはできません。つま
   り、パースが実行された後で、パーサから return する前に呼び出す必要
   があるのです。

   デフォルトでは、SAX 2.0 ドライバを書く人のために、このクラスは
   IncrementalParser の feed、close、reset メソッドを使って XMLReader
   インタフェースの parse メソッドを実装しています。

class xml.sax.xmlreader.Locator

   SAX イベントと文書の位置を関連付けるインタフェースです。locator オ
   ブジェクトは DocumentHandler メソッドを呼び出している間だけ正しい結
   果を返し、それ以外とのときは、予測できない結果を返します。情報を利
   用できない場合、メソッドは "None" を返すこともあります。

class xml.sax.xmlreader.InputSource([systemId])

   "XMLReader" がエンティティを読み込むために必要な情報をカプセル化し
   ます。

   このクラスには公開識別子、システム識別子、(場合によっては文字エンコ
   ーディング情報を含む) バイト・ストリーム、そしてエンティティの文字
   ストリームなどの情報が含まれます。

   アプリケーションは "XMLReader.parse()" メソッドでの使用や
   EntityResolver.resolveEntity の戻り値としてこのオブジェトを作成しま
   す。

   "InputSource" はアプリケーションに属します。 "XMLReader" はアプリケ
   ーションから渡された "InputSource" オブジェクトの変更を許可されてい
   ませんが、コピーを作ってそれを変更することは可能です。

class xml.sax.xmlreader.AttributesImpl(attrs)

   "Attributes" インタフェース (Attributes インタフェース 参照) の実装
   です。これは辞書風のオブジェクトで、 "startElement()" 内で要素の属
   性を表示します。最も有用な辞書操作に加え、インタフェースに記述され
   ているメソッドを多数サポートしています。このクラスのオブジェクトは
   リーダによってインスタンス化されなければなりません。*attrs* は属性
   名と属性値の対応付けを含む辞書風オブジェクトでなければなりません。

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

   "AttributesImpl" を名前空間認識型に改良したクラスで、
   "startElementNS()" に渡されます。 "AttributesImpl" の派生クラスです
   が、 *namespaceURI* と *localname* の2要素のタプルを解釈します。さ
   らに、元の文書に出てくる修飾名を返す多くのメソッドを提供します。こ
   のクラスは "AttributesNS" インタフェース (AttributesNS インタフェー
   ス 参照) の実装です。


19.14.1. XMLReader オブジェクト
===============================

"XMLReader" は次のメソッドをサポートします:

XMLReader.parse(source)

   入力ソースを処理し、SAX イベントを作成します。 *source* オブジェク
   トはシステム識別子 (入力ソースを特定する文字列 -- 一般にファイル名
   や URL)、ファイル様オブジェクト、または "InputSource" オブジェクト
   です。 "parse()" が return したとき、入力データの処理は完了し、パー
   サ・オブジェクトは破棄ないしリセットされます。制限として、現在の実
   装はバイト・ストリームのみをサポートしており、文字ストリームの処理
   は将来の課題になっています。

XMLReader.getContentHandler()

   現在の "ContentHandler" を返します。

XMLReader.setContentHandler(handler)

   現在の "ContentHandler" を設定します。 "ContentHandler" が設定され
   ていない場合、内容イベントは破棄されます。

XMLReader.getDTDHandler()

   現在の "DTDHandler" を返します。

XMLReader.setDTDHandler(handler)

   現在の "DTDHandler" を返します。 "DTDHandler" が設定されていな場合
   、DTD イベントは破棄されます。

XMLReader.getEntityResolver()

   現在の "EntityResolver" を返します。

XMLReader.setEntityResolver(handler)

   現在の "EntityResolver" を返します。 "EntityResolver" が設定されて
   いない場合、外部エンティティの解決を試行することでエンティティのシ
   ステム識別子が開かれます。利用出来ない場合は失敗します。

XMLReader.getErrorHandler()

   現在の "ErrorHandler" を返します。

XMLReader.setErrorHandler(handler)

   現在のエラーハンドラを設定します。"ErrorHandler" が設定されていない
   場合、エラーが例外として送出され、警告が表示されます。

XMLReader.setLocale(locale)

   アプリケーションにエラーや警告のロケール設定を許可します。

   SAX パーサにとって、エラーや警告の地域化は必須ではありません。しか
   し、パーサが要求されたロケールをサポートしていない場合、SAX 例外を
   送出しなければなりません。アプリケーションはパースの途中でロケール
   の変更を要求することができます。

XMLReader.getFeature(featurename)

   機能 *featurename* の現在の設定を返します。その機能が認識できないと
   きは、 "SAXNotRecognizedException" を送出します。有名な機能名はモジ
   ュール "xml.sax.handler" に列挙されています。

XMLReader.setFeature(featurename, value)

   機能名 *featurename* に値 *value* を設定します。その機能が認識でき
   ないときは、 "SAXNotRecognizedException" を送出します。また、パーサ
   が指定された機能や設定をサポートしていないときは、
   "SAXNotSupportedException" を送出します。

XMLReader.getProperty(propertyname)

   属性名 *propertyname* の現在の値を返します。その属性が認識できない
   ときは、 "SAXNotRecognizedException" を送出します。有名な属性名はモ
   ジュール "xml.sax.handler" に列挙されています。

XMLReader.setProperty(propertyname, value)

   属性名 *propertyname* に値 *value* を設定します。その機能が認識でき
   ないときは、 "SAXNotRecognizedException" を送出します。また、パーサ
   が指定された機能や設定をサポートしていないときは、
   "SAXNotSupportedException" を送出します。


19.14.2. IncrementalParser オブジェクト
=======================================

"IncrementalParser" のインスタンスは次の追加メソッドを提供します:

IncrementalParser.feed(data)

   *data* のチャンクを処理します。

IncrementalParser.close()

   文書の終端を決定します。文書の適格性を調べ (終端でのみ可能)、ハンド
   ラを起動し、パース時に割り当てた資源を解放します。

IncrementalParser.reset()

   このメソッドは close が呼び出された後、新しい文書をパースできるよう
   に、パーサをリセットするのに呼び出されます。close 後 reset を呼び出
   さずに parse や feed を呼び出した場合の戻り値は未定義です。


19.14.3. Locator オブジェクト
=============================

"Locator" のインスタンスは次のメソッドを提供します:

Locator.getColumnNumber()

   現在のイベントが開始する列番号を返します。

Locator.getLineNumber()

   現在のイベントが開始する行番号を返します。

Locator.getPublicId()

   現在の文書イベントの公開識別子を返します。

Locator.getSystemId()

   現在のイベントのシステム識別子を返します。


19.14.4. InputSource オブジェクト
=================================

InputSource.setPublicId(id)

   この "InputSource" の公開識別子を設定します。

InputSource.getPublicId()

   この "InputSource" の公開識別子を返します。

InputSource.setSystemId(id)

   この "InputSource" のシステム識別子を設定します。

InputSource.getSystemId()

   この "InputSource" のシステム識別子を返します。

InputSource.setEncoding(encoding)

   この "InputSource" の文字エンコーディングを設定します。

   エンコーディングは XML エンコーディング宣言として受け入れられる文字
   列でなければなりません (XML 勧告の 4.3.3 節を参照)。

   "InputSource" も文字ストリームを含んでいた場合、"InputSource" のエ
   ンコーディング属性は無視されます。

InputSource.getEncoding()

   この "InputSource" の文字エンコーディングを取得します。

InputSource.setByteStream(bytefile)

   この入力ソースのバイトストリーム (Python のファイル様オブジェクトで
   すが、バイト列と文字の相互変換はサポートしません) を設定します。

   指定された文字ストリームもあった場合 SAX パーサはこれを無視しますが
   、URI 接続開始自身に優先してバイトストリームを使います。

   アプリケーションがバイトストリームの文字エンコーディングを知ってい
   る場合は、setEncoding メソッドで設定する必要があります。

InputSource.getByteStream()

   この入力ソースのバイトストリームを取得します。

   getEncoding メソッドは、このバイトストリームの文字エンコーディング
   を返します。不明なときは "None" を返します。

InputSource.setCharacterStream(charfile)

   この入力ソースの文字ストリームをセットします(ストリームは Python
   1.6 の Unicode-wrapped なファイル風オブジェクトで、Unicode 文字列へ
   の変換をサポートしていなければなりません)。

   文字ストリームが指定された場合、SAX パーサは全バイトストリームを無
   視し、システム識別子への URI 接続の開始を試みません。

InputSource.getCharacterStream()

   この入力ソースの文字ストリームを取得します。


19.14.5. "Attributes" インタフェース
====================================

"Attributes" オブジェクトは   "copy()", "get()", "has_key()",
"items()", "keys()",  "values()" を含むマッピングプロトコルの一部を実
装しています。以下のメソッドも提供されています:

Attributes.getLength()

   属性の数を返します。

Attributes.getNames()

   属性の名前を返します。

Attributes.getType(name)

   属性名 *name* のタイプを返します。通常は "'CDATA'" です。

Attributes.getValue(name)

   属性 *name* の値を返します。


19.14.6. "AttributesNS" インタフェース
======================================

このインタフェースは "Attributes" インタフェース (Attributes インタフ
ェース 参照) のサブタイプです。 Attributes インタフェースがサポートし
ているすべてのメソッドは "AttributesNS" オブジェクトでも利用可能です。

次のメソッドもサポートされています:

AttributesNS.getValueByQName(name)

   修飾名の値を返します。

AttributesNS.getNameByQName(name)

   修飾名 *name* に対応する "(namespace, localname)" のペアを返します
   。

AttributesNS.getQNameByName(name)

   "(namespace, localname)" のペアに対応する修飾名を返します。

AttributesNS.getQNames()

   全ての属性の修飾名を返します。
