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

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

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

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

class xml.sax.xmlreader.XMLReader

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

class xml.sax.xmlreader.IncrementalParser

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

   パーサのインスタンスを作成すると、すぐに "feed()" メソッドからデー
   タを受け入れられる状態になります。 "close()" を呼び出してパースを終
   えた後、"feed()" または "parse()" で新しいデータを受け入れられるよ
   うにするには、"reset()" メソッドを呼び出す必要があります。

   これらのメソッドはパース処理中、つまり "parse()" を呼び出してから戻
   るまでの間に呼び出しては *いけません*。

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

class xml.sax.xmlreader.Locator

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

class xml.sax.xmlreader.InputSource(system_id=None)

   "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 インターフェース 参照) の実装です。


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

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

XMLReader.parse(source)

   入力ソースを処理して SAX イベントを生成します。 *source* オブジェク
   トには、システム識別子 (入力ソースを識別する文字列で、通常はファイ
   ル名または URL)、"pathlib.Path" または *パス風* オブジェクト、
   "InputSource" オブジェクトを指定できます。 "parse()" が戻ると入力の
   処理は完了しており、パーサオブジェクトを破棄またはリセットできます
   。

   バージョン 3.5 で変更: 文字ストリームがサポートされました。

   バージョン 3.8 で変更: path-like オブジェクトのサポートが追加されま
   した。

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" を送出します。


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

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

IncrementalParser.feed(data)

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

IncrementalParser.close()

   文書が終わったものとして処理します。 終端でのみ確認できる整形式の条
   件を検査し、ハンドラを呼び出します。 また、パース中に割り当てたリソ
   ースを解放する場合があります。

IncrementalParser.prepareParser(source)

   "InputSource" インスタンスである *source* をパースする準備をします
   。 データを渡す前に "parse()" から呼び出されます。 パーサの実装はこ
   のメソッドをオーバーライドしなければなりません。 デフォルトの実装は
   "NotImplementedError" を送出します。

IncrementalParser.reset()

   "close()" を呼び出した後、新しい文書をパースできるようにパーサをリ
   セットするためのメソッドです。 "close()" の後で "reset()" を呼ばず
   に "parse()" や "feed()" を呼び出した場合の動作は未定義です。


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

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

Locator.getColumnNumber()

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

Locator.getLineNumber()

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

Locator.getPublicId()

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

Locator.getSystemId()

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


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)

   この入力ソースのバイトストリーム (*binary file*) を設定します。

   文字ストリームも指定されている場合、SAX パーサーはこのバイトストリ
   ームを無視します。 それ以外の場合は、自ら URI への接続を開くよりも
   、指定されたバイトストリームを優先して使います。

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

InputSource.getByteStream()

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

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

InputSource.setCharacterStream(charfile)

   この入力ソースの文字ストリーム (*text file*) を設定します。

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

InputSource.getCharacterStream()

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


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

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

Attributes.getLength()

   属性の数を返します。

Attributes.getNames()

   属性の名前を返します。

Attributes.getType(name)

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

Attributes.getValue(name)

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


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

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

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

AttributesNS.getValueByQName(name)

   修飾名の値を返します。

AttributesNS.getNameByQName(name)

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

AttributesNS.getQNameByName(name)

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

AttributesNS.getQNames()

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