xml.sax.handler --- Base classes for SAX handlers

ソースコード: Lib/xml/sax/handler.py

---

The SAX API defines five kinds of handlers: content handlers, DTD handlers, error handlers, entity resolvers and lexical handlers. Applications normally only need to implement those interfaces whose events they are interested in; they can implement the interfaces in a single object or in multiple objects. Handler implementations should inherit from the base classes provided in the module xml.sax.handler, so that all methods get default implementations.

class xml.sax.handler.ContentHandler

アプリケーションにとって最も重要なメインの SAX コールバック・インターフェースです。このインターフェースで発生するイベントの順序はドキュメント内の情報の順序を反映しています。

class xml.sax.handler.DTDHandler

DTD イベントのハンドラです。

パースされていないエンティティや属性など、基本的なパースに必要な DTD イベントの指定だけを行うインターフェースです。

class xml.sax.handler.EntityResolver

エンティティ解決用の基本インターフェースです。このインターフェースを実装したオブジェクトを作成しパーサに登録することで、パーサはすべての外部エンティティを解決するメソッドを呼び出すようになります。

class xml.sax.handler.ErrorHandler

エラーや警告メッセージをアプリケーションに通知するためにパーサが使用するインターフェースです。このオブジェクトのメソッドが、エラーをただちに例外に変換するか、あるいは別の方法で処理するかの制御をしています。

class xml.sax.handler.LexicalHandler

Interface used by the parser to represent low frequency events which may not be of interest to many applications.

これらのクラスに加え、 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"

data type: xml.sax.handler.LexicalHandler (not supported in 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"

data type: Bytes

説明: 現在のイベントの元になったリテラル文字列。

アクセス: 読み出し専用

xml.sax.handler.all_properties

既知の全プロパティ名のリスト。

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 属性の値によっては外部エンティティをスキップすることがあります。

DTDHandler オブジェクト

DTDHandler インスタンスは以下のメソッドを提供します:

DTDHandler.notationDecl(name, publicId, systemId)

表記宣言イベントの通知を扱います。

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

未パースのエンティティ宣言イベントの通知を扱います。

EntityResolver オブジェクト

EntityResolver.resolveEntity(publicId, systemId)

エンティティのシステム識別子を解決し、文字列として読み込んだシステム識別子あるいは InputSource オブジェクトのいずれかを返します。デフォルトの実装では systemId を返します。

ErrorHandler オブジェクト

Objects with this interface are used to receive error and warning information from the XMLReader. If you create an object that implements this interface, then register the object with your XMLReader, the parser will call the methods in your object to report all warnings and errors. There are three levels of errors available: warnings, (possibly) recoverable errors, and unrecoverable errors. All methods take a SAXParseException as the only parameter. Errors and warnings may be converted to an exception by raising the passed-in exception object.

ErrorHandler.error(exception)

パーサが回復可能なエラーに遭遇すると呼び出されます。このメソッドが例外を送出しない場合パースは継続されますが、アプリケーションは更なるドキュメント情報を期待すべきではありません。パーサの処理を継続を認めることで入力ドキュメント内の他のエラーを見つけることができます。

ErrorHandler.fatalError(exception)

パーサが回復不能なエラーに遭遇すると呼び出されます。このメソッドが return したとき、パースの停止が求められています。

ErrorHandler.warning(exception)

パーサが軽微な警告情報をアプリケーションに通知するときに呼び出されます。このメソッドが return したときはパースの継続が求められ、ドキュメント情報はアプリケーションに送り続けられます。このメソッドでの例外の送出はパースを終了します。

LexicalHandler Objects

Optional SAX2 handler for lexical events.

This handler is used to obtain lexical information about an XML document. Lexical information includes information describing the document encoding used and XML comments embedded in the document, as well as section boundaries for the DTD and for any CDATA sections. The lexical handlers are used in the same manner as content handlers.

Set the LexicalHandler of an XMLReader by using the setProperty method with the property identifier 'http://xml.org/sax/properties/lexical-handler'.

LexicalHandler.comment(content)

Reports a comment anywhere in the document (including the DTD and outside the document element).

LexicalHandler.startDTD(name, public_id, system_id)

Reports the start of the DTD declarations if the document has an associated DTD.

LexicalHandler.endDTD()

Reports the end of DTD declaration.

LexicalHandler.startCDATA()

Reports the start of a CDATA marked section.

The contents of the CDATA marked section will be reported through the characters handler.

LexicalHandler.endCDATA()

Reports the end of a CDATA marked section.