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

20.12.1. XMLReader オブジェクト

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

XMLReader.parse(source)

入力ソースを処理し、SAX イベントを作成します。 source オブジェクトはシステム識別子 (入力ソースを特定する文字列 -- 一般にファイル名や URL)、ファイル様オブジェクト、あるいは InputSource オブジェクトです。 parse() が return したとき、入力データの処理は完了し、パーサ・オブジェクトは破棄ないしリセットされます。

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

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

20.12.2. IncrementalParser オブジェクト

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

IncrementalParser.feed(data)

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

IncrementalParser.close()

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

IncrementalParser.reset()

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

20.12.3. Locator オブジェクト

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

Locator.getColumnNumber()

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

Locator.getLineNumber()

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

Locator.getPublicId()

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

Locator.getSystemId()

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

20.12.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)

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

文字ストリームも指定されている場合、SAX パーサはこのバイトストリームを無視しますが、URI 接続自体を開くときには優先してバイトストリームを使います。

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

InputSource.getByteStream()

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

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

InputSource.setCharacterStream(charfile)

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

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

InputSource.getCharacterStream()

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

20.12.5. Attributes インタフェース

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

Attributes.getLength()

属性の数を返します。

Attributes.getNames()

属性の名前を返します。

Attributes.getType(name)

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

Attributes.getValue(name)

属性 name の値を返します。

20.12.6. AttributesNS インタフェース

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

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

AttributesNS.getValueByQName(name)

修飾名の値を返します。

AttributesNS.getNameByQName(name)

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

AttributesNS.getQNameByName(name)

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

AttributesNS.getQNames()

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