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()

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