"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

   入力ソースを一度にパースするのではなく、ドキュメントのチャンクが利
   用可能になるごとに取得したいことがあります。SAX リーダは通常、ファ
   イル全体を一気に読み込まず、チャンク単位で処理するのですが、全体の
   処理が終わるまで "parse()" は返りません。そのため、 "parse()" の排
   他的挙動を望まないときにこれらのインターフェースを使用してください
   。

   パーサのインスタンスが作成されるとすぐに、feed メソッドを通じてデー
   タを受け入れられるようになります。パースが完了して閉じるための呼び
   出しが行われた後、パーサがフィードからまたはパースメソッドを使用し
   て新しいデータを受け入れられるように、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(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" オブジェクトか *path-like* オブジェクトま
   たは "InputSource" オブジェクトです。 "parse()" が return したとき
   、入力データの処理は完了し、パーサ・オブジェクトは破棄ないしリセッ
   トされます。

   バージョン 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.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()

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