8.5.1 XMLParser Objects

xmlparser オブジェクトは以下のようなメソッドを持ちます。

Parse( data[, isfinal]): 文字列 data の内容を解析し、解析されたデータを処理するための適切な関数を呼び出します。このメソッドを最後に呼び出す時は isfinal を真にしなければなりません。 data は空の文字列を取ることもできます。

ParseFile( file): file オブジェクトから読み込んだXMLデータを解析します。 file には read(nbytes) メソッドのみが必要です。このメソッドはデータがなくなった場合に空文字列を返さねばなりません。。

SetBase( base): (XML) 宣言中のシステム識別子中の相対 URI を解決するための、基底 URI を設定します。相対識別子の解決はアプリケーションに任されます: この値は関数 ExternalEntityRefHandler や NotationDeclHandler、UnparsedEntityDeclHandler に引数 base としてそのまま渡されます。

GetBase( ): 以前の SetBase() によって設定された基底 URI を文字列の形で返します。SetBase()が呼ばれていないときには None を返します。

GetInputContext( ): 現在のイベントを発生させた入力データを文字列として返します。データはテキストの入っているエンティティが持っているエンコードになります。イベントハンドラがアクティブでないときに呼ばれると、戻り値は Noneとなります。バージョン 2.1 で新たに追加された仕様です。

ExternalEntityParserCreate( context[, encoding]): 親となるパーザで解析された内容が参照している、外部で解析されるエンティティを解析するために使える ``子の'' パーザを作成します。 context パラメータは、以下に記すように ExternalEntityRefHandler() ハンドラ関数に渡される文字列でなければなりません。子のパーザは ordered_attributes、returns_unicode、 specified_attributes が現在のパーザの値に設定されて生成されます。

UseForeignDTD( [flag])

flagの値をデフォルトのtrueにすると、Expatは代わりのDTDをロードするため、すべての引数にNone を設定して ExternalEntityRefHandler を呼び出します。XML文書が文書型定義を持っていなければ、 ExternalEntityRefHandler が呼び出しますが、StartDoctypeDeclHandler と EndDoctypeDeclHandlerは呼び出されません。

flag にfalseを与えると、メソッドが前回呼ばれた時のtrueの設定が解除されますが、他には何も起こりません。

このメソッドは Parse() または ParseFile() メソッドが呼び出される前にだけ呼び出されます;これら2つのメソッドのどちらかが呼び出されたあとにメソッドが呼ばれると、 code に定数 errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING が設定されて例外 ExpatError が送出されます。

バージョン 2.3 で新たに追加された仕様です。

xmlparser オブジェクトは次のような属性を持ちます:

buffer_size: buffer_text が真の時に使われるバッファのサイズです。この値は変更できません。バージョン 2.3 で新たに追加された仕様です。

buffer_text: この値を真にすると、xmlparser オブジェクトが Expatから返されたもとの内容をバッファに保持するようになります。これにより可能なときに何度も CharacterDataHandler() を呼び出してしまうようなことを避けることができます。Expatは通常、文字列のデータを行末ごと大量に破棄するため、かなりパフォーマンスを改善できるはずです。この属性はデフォルトでは偽で、いつでも変更可能です。バージョン 2.3 で新たに追加された仕様です。

buffer_used: buffer_text が利用可能なとき、バッファに保持されたバイト数です。これらのバイトはUTF-8でエンコードされたテキストを表します。この属性は buffer_text が偽の時には意味がありません。バージョン 2.3 で新たに追加された仕様です。

ordered_attributes: この属性をゼロ以外の整数にすると、報告される(XMLノードの) 属性を辞書型ではなくリスト型にします。属性は文書のテキスト中の出現順で示されます。それぞれの属性は、2つのリストのエントリ: 属性名とその値、が与えられます。 (このモジュールの古いバージョンでも、同じフォーマットが使われています。) デフォルトでは、この属性はデフォルトでは偽となりますが、いつでも変更可能です。バージョン 2.1 で新たに追加された仕様です。

returns_unicode: この属性をゼロ以外の整数にすると、ハンドラ関数に Unicode 文字列が渡されます。 returns_unicode が False の時には、UTF-8でエンコードされたデータを含む 8 ビット文字列がハンドラに渡されます。Pythonがユニコードサポートつきでビルドされている場合、この値はデフォルトでTrueです。バージョン 1.6 で変更された仕様: 戻り値の型がいつでも変更できるように変更されたはずです

specified_attributes: ゼロ以外の整数にすると、パーザは文書のインスタンスで特定される属性だけを報告し、属性宣言から導出された属性は報告しないようになります。この属性が指定されたアプリケーションでは、XMLプロセッサの振る舞いに関する標準に従うために必要とされる (文書型) 宣言によって、どのような付加情報が利用できるのかということについて特に注意を払わなければなりません。デフォルトで、この属性は偽となりますが、いつでも変更可能です。バージョン 2.1 で新たに追加された仕様です。

以下の属性には、 xmlparser オブジェクトで最も最近に起きたエラーに関する値が入っており、また Parse() または ParseFile()メソッドが xml.parsers.expat.ExpatError 例外を送出した際にのみ正しい値となります。

ErrorByteIndex: エラーが発生したバイトのインデクスです。

ErrorCode: エラーを特定する数値によるコードです。この値はErrorString() に渡したり、 errors オブジェクトで定義された内容と比較できます。

ErrorColumnNumber: エラーの発生したカラム番号です。

ErrorLineNumber: エラーの発生した行番号です。

以下の属性は xmlparser オブジェクトがその時パースしている位置に関する値を保持しています。コールバックがパースイベントを報告している間、これらの値はイベントの生成した文字列の先頭の位置を指し示します。コールバックの外から参照された時には、（対応するコールバックであるかにかかわらず）直前のパースイベントの位置を示します。バージョン 2.4 で新たに追加された仕様です。

CurrentByteIndex: パーサへの入力の、現在のバイトインデックス。

CurrentColumnNumber: パーサへの入力の、現在のカラム番号。

CurrentLineNumber: パーサへの入力の、現在の行番号。

以下に指定可能なハンドラのリストを示します。 xmlparser オブジェクト o にハンドラを指定するには、o.handlername = func を使用します。 handlername は、以下のリストに挙げた値をとらねばならず、また func は正しい数の引数を受理する呼び出し可能なオブジェクトでなければなりません。引数は特に明記しない限り、すべて文字列となります。

XmlDeclHandler( version, encoding, standalone): XML 宣言が解析された時に呼ばれます。XML宣言とは、XML勧告の適用バージョン (オプション)、文書テキストのエンコード、そしてオプションの ``スタンドアロン'' の宣言です。 version と encoding は returns_unicode 属性によって指示された型を示す文字列となり、 standalone は、文書がスタンドアロンであると宣言される場合には 1に、文書がスタンドアロンでない場合には 0 に、スタンドアロン宣言を省略する場合には -1 になります。このハンドラは Expat のバージョン1.95.0以降のみ使用できます。バージョン 2.1 で新たに追加された仕様です。

StartDoctypeDeclHandler( doctypeName, systemId, publicId, has_internal_subset): Expatが文書型宣言<!DOCTYPE ...)を解析し始めたときに呼び出されます。doctypeName は、与えられた値がそのまま Expat に提供されます。systemId と publicId パラメタが指定されている場合、それぞれシステムと公開識別子を与えます。省略する時にはNone にします。文書が内部的な文書宣言のサブセット (internal document declaration subset) を持つか、サブセット自体の場合、has_internal_subset は true になります。このハンドラには、Expat version 1.2以上が必要です。

EndDoctypeDeclHandler( ): Expatが文書型宣言の解析を終えたときに呼び出されます。このハンドラには、Expat version 1.2以上が必要です。

ElementDeclHandler( name, model): それぞれの要素型宣言ごとに呼び出されます。nameは要素型の名前であり、 model は内容モデル (content model) の表現です。

AttlistDeclHandler( elname, attname, type, default, required): ひとつの要素型で宣言される属性ごとに呼び出されます。属性リストの宣言が 3つの属性を宣言したとすると、このハンドラはひとつの属性に1度づつ、 3度呼び出されます。 elname は要素名であり、これに対して宣言が適用され、attnameが宣言された属性名となります。属性型は文字列で、type として渡されます; 取りえる値は、'CDATA', 'ID','IDREF', ... です。 defaultは、属性が文書のインスタンスによって指定されていないときに使用されるデフォルト値を与えます。デフォルト値(#IMPLIED values)が存在しないときにはNoneを与えます。文書のインスタンスによって属性値が与えられる必要のあるときにはrequiredがtrueになります。このメソッドはExpat version 1.95.0 以上が必要です。

StartElementHandler( name, attributes): 要素の開始を処理するごとに呼び出されます。name は要素名を格納した文字列で、attributes はその値に属性名を対応付ける辞書型です。

EndElementHandler( name): 要素の終端を処理するごとに呼び出されます。

ProcessingInstructionHandler( target, data): Called for every processing instruction. 処理命令を処理するごとに呼び出されます。

CharacterDataHandler( data): 文字データを処理するときに呼びだされます。このハンドラは通常の文字データ、 CDATAセクション、無視できる空白文字列のために呼び出されます。これらを識別しなければならないアプリケーションは、要求された情報を収集するために StartCdataSectionHandler, EndCdataSectionHandler, and ElementDeclHandlerコールバックメソッドを使用できます。

UnparsedEntityDeclHandler( entityName, base, systemId, publicId, notationName): 解析されていない (NDATA) エンティティ宣言を処理するために呼び出されます。このハンドラは Expat ライブラリのバージョン1.2のためだけに存在します; より最近のバージョンでは、代わりにEntityDeclHandlerを使用してください (根底にある Expat ライブラリ内の関数は、撤廃されたものであると宣言されています)。

EntityDeclHandler( entityName, is_parameter_entity, value, base, systemId, publicId, notationName): エンティティ宣言ごとに呼び出されます。パラメタと内部エンティティについて、value はエンティティ宣言の宣言済みの内容を与える文字列となります; 外部エンティティの時にはNone となります。解析済みエンティティの場合、notationName パラメタは None となり、解析されていないエンティティの時には記法 (notation) 名となります。 is_parameter_entity は、エンティティがパラメタエンティティの場合真に、一般エンティティ (general entitiy) の場合には偽になります (ほとんどのアプリケーションでは、一般エンティティのことしか気にする必要がありません)。このハンドラは Expat ライブラリのバージョン1.95.0 以降でのみ使用できます。バージョン 2.1 で新たに追加された仕様です。

NotationDeclHandler( notationName, base, systemId, publicId): 記法の宣言 (notation declaration) で呼び出されます。 notationName, base, systemId, および publicId を与える場合、文字列にします。public な識別子が省略された場合、 publicId は None になります。

StartNamespaceDeclHandler( prefix, uri): 要素が名前空間宣言を含んでいる場合に呼び出されます。名前空間宣言は、宣言が配置されている要素に対して StartElementHandler が呼び出される前に処理されます。

EndNamespaceDeclHandler( prefix): 名前空間宣言を含んでいたエレメントの終了タグに到達したときに呼び出されます。このハンドラは、要素に関する名前空間宣言ごとに、 StartNamespaceDeclHandler とは逆の順番で一度だけ呼び出され、各名前空間宣言のスコープが開始されたことを示します。このハンドラは、要素が終了する際、対応する EndElementHandler が呼ばれた後に呼び出されます。

CommentHandler( data): コメントで呼び出されます。data はコメントのテキストで、先頭の `' を除きます。

StartCdataSectionHandler( ): CDATA セクションの開始時に呼び出されます。CDATA セクションの構文的な開始と終了位置を識別できるようにするには、このハンドラと EndCdataSectionHandler が必要です。

EndCdataSectionHandler( ): CDATA セクションの終了時に呼び出されます。

DefaultHandler( data): XML 文書中で、適用可能なハンドラが指定されていない文字すべてに対して呼び出されます。この文字とは、検出されたことが報告されるが、ハンドラは指定されていないようなコンストラクト (construct) の一部である文字を意味します。

DefaultHandlerExpand( data): DefaultHandler と同じですが、内部エンティティの展開を禁止しません。エンティティ参照はデフォルトハンドラに渡されません。

NotStandaloneHandler( ): XML 文書がスタンドアロンの文書として宣言されていない場合に呼び出されます。外部サブセットやパラメタエンティティへの参照が存在するが、XML 宣言が XML 宣言中で standalone 変数を yes に設定していない場合に起きます。このハンドラが 0 を返すと、パーザは XML_ERROR_NOT_STANDALONE を送出します。このハンドラが設定されていなければ、パーザは前述の事態で例外を送出しません。

ExternalEntityRefHandler( context, base, systemId, publicId)

外部エンティティの参照時に呼び出されます。base は現在の基底 (base) で、以前の SetBase() で設定された値になっています。 public、および system の識別子である、systemId とpublicId が指定されている場合、値は文字列です; public 識別子が指定されていない場合、 publicId は None になります。 context の値は不明瞭なものであり、以下に記述するようにしか使ってはなりません。

外部エンティティが解析されるようにするには、このハンドラを実装しなければなりません。このハンドラは、 ExternalEntityParserCreate(context) を使って適切なコールバックを指定し、子パーザを生成して、エンティティを解析する役割を担います。このハンドラは整数を返さねばなりません; 0 を返した場合、パーザは XML_ERROR_EXTERNAL_ENTITY_HANDLING エラーを送出します。そうでないばあい、解析を継続します。

このハンドラが与えられておらず、 DefaultHandler コールバックが指定されていれば、外部エンティティはDefaultHandler で報告されます。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。