20.10. xml.sax.handler --- SAX ハンドラの基底クラス¶
ソースコード: Lib/xml/sax/handler.py
SAX API はコンテント・ハンドラ、DTD ハンドラ、エラー・ハンドラ、エンティティ・リゾルバという4種類のハンドラを定義しています。通常アプリケーション側で実装する必要があるインターフェースは、使用したいイベントを発生させるものだけです。インターフェースは1つのオブジェクトにまとめることも、複数のオブジェクトに分けることも可能です。ハンドラの実装は、 xml.sax.handler で提供される基底クラスを継承して、すべてのメソッドがデフォルトで実装されるようにしてください。
-
class
xml.sax.handler.ContentHandler¶ アプリケーションにとって最も重要なメインの SAX コールバック・インターフェースです。このインターフェースで発生するイベントの順序はドキュメント内の情報の順序を反映しています。
-
class
xml.sax.handler.DTDHandler¶ DTD イベントのハンドラです。
パースされていないエンティティや属性など、基本的なパースに必要な DTD イベントの指定だけを行うインターフェースです。
-
class
xml.sax.handler.EntityResolver¶ エンティティ解決用の基本インターフェースです。このインターフェースを実装したオブジェクトを作成しパーサに登録することで、パーサはすべての外部エンティティを解決するメソッドを呼び出すようになります。
-
class
xml.sax.handler.ErrorHandler¶ エラーや警告メッセージをアプリケーションに通知するためにパーサが使用するインターフェースです。このオブジェクトのメソッドが、エラーをただちに例外に変換するか、あるいは別の方法で処理するかの制御をしています。
これらのクラスに加え、 xml.sax.handler は機能やプロパティ名のシンボル定数を提供しています。
-
xml.sax.handler.feature_namespaces¶ - 値:
"http://xml.org/sax/features/namespaces"真: 名前空間を処理します。偽: オプションで名前空間を処理しません (暗黙に名前空間接頭辞も無効にします; デフォルト)。アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可
-
xml.sax.handler.feature_namespace_prefixes¶ - 値:
"http://xml.org/sax/features/namespace-prefixes"真: 名前空間宣言で用いられている元々の接頭辞付きの名前と属性を報告します。偽: 名前空間宣言で用いられている属性を報告しません。オプションで元々の接頭辞付きの名前も報告しません (デフォルト)。アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可
-
xml.sax.handler.feature_string_interning¶ - 値:
"http://xml.org/sax/features/string-interning"真: 全ての要素名、接頭辞、属性名、名前空間 URI、ローカル名を組込みの intern 関数を使ってシンボルに登録します。偽: 名前を必ずしもシンボルに登録しませんが、されるかもしれません (デフォルト)。アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可
-
xml.sax.handler.feature_validation¶ - 値:
"http://xml.org/sax/features/validation"真: 全ての妥当性検査エラーを報告します (外部一般エンティティと外部変数エンティティが暗示されます)。偽: 妥当性検査エラーを報告しません。アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可
-
xml.sax.handler.feature_external_ges¶ - 値:
"http://xml.org/sax/features/external-general-entities"真: 全ての外部一般 (テキスト) エンティティを取り込みます。偽: 外部一般エンティティを取り込みません。アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可
-
xml.sax.handler.feature_external_pes¶ - 値:
"http://xml.org/sax/features/external-parameter-entities"真: 外部 DTD サブセットを含む全ての外部変数エンティティを取り込みます。偽: 外部 DTD サブセットであっても外部変数エンティティを取り込みません。アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可
-
xml.sax.handler.all_features¶ 全機能のリスト。
-
xml.sax.handler.property_lexical_handler¶ - 値:
"http://xml.org/sax/properties/lexical-handler"データ型: xml.sax.sax2lib.LexicalHandler (Python 2 では未サポート)説明: コメントなど字句解析イベント用のオプション拡張ハンドラ。アクセス: 読み書き可
-
xml.sax.handler.property_declaration_handler¶ - 値:
"http://xml.org/sax/properties/declaration-handler"データ型: xml.sax.sax2lib.DeclHandler (Python 2 では未サポート)説明: 表記や未解析エンティティをのぞく DTD 関連イベント用のオプション拡張ハンドラ。アクセス: 読み書き可
-
xml.sax.handler.property_dom_node¶ - 値:
"http://xml.org/sax/properties/dom-node"データ型: org.w3c.dom.Node (Python 2 では未サポート)説明: パース時は DOM イテレータならば現在の DOM ノードです。非パース時はイテレートのルート DOM ノードです。アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可
-
xml.sax.handler.property_xml_string¶ - 値:
"http://xml.org/sax/properties/xml-string"データ型: 文字列説明: 現在のイベントの元になったリテラル文字列。アクセス: 読み出し専用
-
xml.sax.handler.all_properties¶ 既知の全プロパティ名のリスト。
20.10.1. ContentHandler オブジェクト¶
ContentHandler はアプリケーション側でサブクラス化して利用することが前提になっています。パーサは入力ドキュメントのイベントにより、それぞれに対応する以下のメソッドを呼び出します:
-
ContentHandler.setDocumentLocator(locator)¶ アプリケーションにドキュメントイベントの発生位置を指すロケータを与えるためにパーサから呼び出されます。
SAX パーサによるロケータの提供は強く推奨されています(必須ではありません)。もし提供する場合は、DocumentHandler インターフェースのどのメソッドよりも先にこのメソッドが呼び出されるようにしなければなりません。
パーサがエラーを報告しない場合でも、ロケータによってアプリケーションは全てのドキュメント関連イベントの終了位置を知ることが出来ます。 通常、アプリケーションは自身のエラー (例えば文字コンテンツがアプリケーションの規則に適合しない場合) を報告するためにこれを使用します。 ロケータが返す情報は検索エンジンでの利用にはおそらく不充分です。
ロケータが正しい情報を返すのは、このインターフェースからイベントの呼出しが実行されている間だけです。それ以外のときは使用すべきでありません。
-
ContentHandler.startDocument()¶ ドキュメントの開始通知を受け取ります。
SAX パーサはこのインターフェースやDTDHandler のどのメソッド (
setDocumentLocator()を除く) よりも先にこのメソッドを一度だけ呼び出します。
-
ContentHandler.endDocument()¶ ドキュメントの終了通知を受け取ります。
SAX パーサはこのメソッドを一度だけ呼び出します。パース中に呼び出す最後のメソッドです。パーサは (回復不能なエラーで) パース処理を中断するか、あるいは入力の最後に到達するまでこのメソッドを呼び出しません。
-
ContentHandler.startPrefixMapping(prefix, uri)¶ 接頭辞と URI 名前空間の関連付けのスコープを開始します。
このイベントからの情報は名前空間処理に必須ではありません。SAX XML リーダは
feature_namespaces機能が有効な場合 (デフォルト)、要素と属性名の接頭辞を自動的に置換します。しかしながら、接頭辞の自動展開を安全に行えないために、アプリケーションが文字データや属性値の中で接頭辞を使わなければならない場合があります。 必要ならば
startPrefixMapping()やendPrefixMapping()イベントはアプリケーションにコンテクスト自身の中で接頭辞を展開するための情報を提供します。startPrefixMapping()とendPrefixMapping()イベントは相互に正しい入れ子関係になることが保証されていないので注意が必要です。すべてのstartPrefixMapping()は対応するstartElement()の前に発生し、endPrefixMapping()イベントは対応するendElement()の後で発生しますが、その順序は保証されていません。
-
ContentHandler.endPrefixMapping(prefix)¶ 接頭辞と URI の関連付けのスコープを終了します。
詳しくは
startPrefixMapping()を参照してください。このイベントは常に対応するendElement()の後で発生しますが、複数のendPrefixMapping()イベントの順序は特に保証されません。
-
ContentHandler.startElement(name, attrs)¶ 非名前空間モードでの要素の開始を通知します。
name 引数は要素型の生の XML 1.0 名を文字列として持ち、attrs 引数は要素の属性を持つ
Attributesインターフェイス (Attributes インタフェース を参照) のオブジェクトを保持します。 attrs ととして渡されたオブジェクトはパーサに再利用されるかもしれません。 そのため、それへの参照を確保するのは属性のコピーを保持する確実な方法ではありません。 属性のコピーを保持するには attrs 属性のcopy()メソッドを使用してください。
-
ContentHandler.endElement(name)¶ 非名前空間モードでの要素の終了を通知します。
name 引数は
startElement()イベントとまったく同じ要素型名を持ちます。
-
ContentHandler.startElementNS(name, qname, attrs)¶ 名前空間モードでの要素の開始を通知します。
name 引数は要素型の名前を
(uri, localname)というタプルとして持ち、qname 引数は元の文書で使われている生の XML 1.0 名を持ち、要素の属性を持つAttributesNSインターフェイス (AttributesNS インタフェース を参照) のインスタンスを保持します。 名前空間が要素に関連付けられていない場合、name の uri 要素はNoneです。 attrs ととして渡されたオブジェクトはパーサに再利用されるかもしれません。 そのため、それへの参照を確保するのは属性のコピーを保持する確実な方法ではありません。 属性のコピーを保持するには attrs 属性のcopy()メソッドを使用してください。feature_namespace_prefixes機能が有効でなければ、パーサで qname をNoneに設定することも可能です。
-
ContentHandler.endElementNS(name, qname)¶ 名前空間モードでの要素の終了を通知します。
name 引数は
startElementNS()イベントとまったく同じ要素型を持ちます。 qname 引数も同様です。
-
ContentHandler.characters(content)¶ 文字データの通知を受け取ります。
パーサはこのメソッドを呼び出して文字データの各チャンクを報告します。SAX パーサは一連の文字データを単一のチャンクとして返す場合と複数のチャンクに分けて返す場合がありますが、ロケータの情報が正しく保たれるように、一つのイベントの文字データは常に同じ外部エンティティのものでなければなりません。
content は文字列、バイト列のどちらでもかまいませんが、
expatリーダ・モジュールは常に文字列を生成するようになっています。注釈
Python XML SIG が提供していた初期 SAX 1 では、このメソッドにもっと JAVA 風のインターフェースが用いられています。しかし Python で採用されている大半のパーサでは古いインターフェースを有効に使うことができないため、よりシンプルなものに変更されました。古いコードを新しいインターフェースに変更するには、古い offset と length パラメータでスライスせずに、content を指定するようにしてください。
-
ContentHandler.ignorableWhitespace(whitespace)¶ 要素内容中の無視できる空白文字の通知を受け取ります。
妥当性検査を行うパーサはこのメソッドを使って、無視できる空白文字 (W3C XML 1.0 勧告の 2.10 節参照) の各チャンクを報告しなければなりません。妥当性検査をしないパーサもコンテンツモデルの利用とパースが可能な場合、このメソッドを利用することが可能です。
SAX パーサは連続する複数の空白文字を単一のチャンクとして返す場合と複数のチャンクに分けて返す場合があります。しかし、ロケータが有用な情報を提供できるように、単一のイベント中のすべての文字は同じ外部エンティティからのものでなければなりません。
-
ContentHandler.processingInstruction(target, data)¶ 処理命令の通知を受け取ります。
パーサは処理命令が見つかるたびにこのメソッドを呼び出します。処理命令はメインのドキュメント要素の前や後にも発生することがあるので注意してください。
SAX パーサがこのメソッドを使って XML 宣言 (XML 1.0 のセクション 2.8) やテキスト宣言 (XML 1.0 のセクション 4.3.1) の通知をすることはありません。
-
ContentHandler.skippedEntity(name)¶ スキップしたエンティティの通知を受け取ります。
パーサはエンティティをスキップするたびにこのメソッドを呼び出します。妥当性検査をしないプロセッサは (外部 DTD サブセットで宣言されているなどの理由で) 宣言が見当たらないエンティティをスキップします。すべてのプロセッサは
feature_external_gesおよびfeature_external_pes属性の値によっては外部エンティティをスキップすることがあります。
20.10.2. DTDHandler オブジェクト¶
DTDHandler インスタンスは以下のメソッドを提供します:
-
DTDHandler.notationDecl(name, publicId, systemId)¶ 表記宣言イベントの通知を扱います。
-
DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)¶ 未パースのエンティティ宣言イベントの通知を扱います。
20.10.3. EntityResolver オブジェクト¶
-
EntityResolver.resolveEntity(publicId, systemId)¶ エンティティのシステム識別子を解決し、文字列として読み込んだシステム識別子あるいは InputSource オブジェクトのいずれかを返します。デフォルトの実装では systemId を返します。
20.10.4. ErrorHandler オブジェクト¶
このインターフェイスのあるオブジェクトを使って XMLReader からエラーと警告情報を受け取ります。
このインターフェイスを実装しているオブジェクトを作った場合、それを XMLReader に登録します。そうすると、パーサはすべての警告とエラーを報告するためにオブジェクトのメソッドを呼びます。
利用可能なエラーには、次の3つのレベルがあります: 警告、(おそらく) 回復可能なエラー、回復不能なエラーです。
全てのメソッドは唯一の引数として SAXParseException を受け取ります。
警告とエラーは、渡された例外オブジェクトを送出することにより、例外に変換される場合があります。
-
ErrorHandler.error(exception)¶ パーサが回復可能なエラーに遭遇すると呼び出されます。このメソッドが例外を送出しない場合パースは継続されますが、アプリケーションは更なるドキュメント情報を期待すべきではありません。パーサの処理を継続を認めることで入力ドキュメント内の他のエラーを見つけることができます。
-
ErrorHandler.fatalError(exception)¶ パーサが回復不能なエラーに遭遇すると呼び出されます。このメソッドが return したとき、パースの停止が求められています。
-
ErrorHandler.warning(exception)¶ パーサが軽微な警告情報をアプリケーションに通知するときに呼び出されます。このメソッドが return したときはパースの継続が求められ、ドキュメント情報はアプリケーションに送り続けられます。このメソッドでの例外の送出はパースを終了します。