xml.sax.handler — SAXハンドラーの基本クラス—Pythonドキュメント
xml.sax.handler —SAXハンドラーの基本クラス
ソースコード： ：source： `Lib / xml / sax / handler.py`
SAX APIは、コンテンツハンドラー、DTDハンドラー、エラーハンドラー、エンティティリゾルバーの4種類のハンドラーを定義します。 アプリケーションは通常、イベントに関心のあるインターフェイスを実装するだけで済みます。 単一のオブジェクトまたは複数のオブジェクトにインターフェースを実装できます。 ハンドラーの実装は、モジュール 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
-
true：名前空間処理を実行します。
false：オプションで名前空間処理を実行しません（名前空間プレフィックスを意味します;デフォルト）。
アクセス:(解析）読み取り専用。 （解析しない）読み取り/書き込み
- xml.sax.handler.feature_namespace_prefixes
-
true：名前空間宣言に使用された元のプレフィックス名と属性を報告します。
false：名前空間宣言に使用される属性を報告せず、オプションで元のプレフィックス名を報告しません（デフォルト）。
アクセス:(解析）読み取り専用。 （解析しない）読み取り/書き込み
- xml.sax.handler.feature_string_interning
-
true：すべての要素名、プレフィックス、属性名、名前空間URI、およびローカル名は、組み込みのインターン関数を使用してインターンされます。
false：名前は必ずしもインターンされているとは限りません（デフォルト）。
アクセス:(解析）読み取り専用。 （解析しない）読み取り/書き込み
- xml.sax.handler.feature_validation
-
true：すべての検証エラーを報告します（external-general-entitiesおよびexternal-parameter-entitiesを意味します）。
false：検証エラーを報告しません。
アクセス:(解析）読み取り専用。 （解析しない）読み取り/書き込み
- xml.sax.handler.feature_external_ges
-
true：すべての外部一般（テキスト）エンティティを含めます。
false：外部の一般エンティティを含めないでください。
アクセス:(解析）読み取り専用。 （解析しない）読み取り/書き込み
- xml.sax.handler.feature_external_pes
-
true：外部DTDサブセットを含むすべての外部パラメーターエンティティを含めます。
false：外部DTDサブセットであっても、外部パラメーターエンティティを含めないでください。
アクセス:(解析）読み取り専用。 （解析しない）読み取り/書き込み
- xml.sax.handler.all_features
- すべての機能のリスト。
- xml.sax.handler.property_lexical_handler
-
データ型：xml.sax.sax2lib.LexicalHandler（Python 2ではサポートされていません）
説明：コメントなどの字句イベント用のオプションの拡張ハンドラー。
アクセス：読み取り/書き込み
- xml.sax.handler.property_declaration_handler
-
データ型：xml.sax.sax2lib.DeclHandler（Python 2ではサポートされていません）
説明：表記法および未解析エンティティ以外のDTD関連イベント用のオプションの拡張ハンドラー。
アクセス：読み取り/書き込み
- xml.sax.handler.property_dom_node
-
データ型：org.w3c.dom.Node（Python 2ではサポートされていません）
説明：解析時に、これがDOMイテレーターである場合、アクセスされている現在のDOMノード。 解析していない場合、反復用のルートDOMノード。
アクセス:(解析）読み取り専用。 （解析しない）読み取り/書き込み
- xml.sax.handler.property_xml_string
-
データ型：文字列
説明：現在のイベントのソースであった文字列。
アクセス：読み取り専用
- xml.sax.handler.all_properties
- 既知のすべてのプロパティ名のリスト。
ContentHandlerオブジェクト
ユーザーは、アプリケーションをサポートするために ContentHandler をサブクラス化することが期待されています。 次のメソッドは、入力ドキュメントの適切なイベントでパーサーによって呼び出されます。
- ContentHandler.setDocumentLocator(locator)
パーサーによって呼び出され、ドキュメントイベントの発生元を特定するためのロケーターをアプリケーションに提供します。
SAXパーサーは、ロケーターを提供することを強くお勧めします（絶対に必要というわけではありません）。そうする場合は、DocumentHandlerインターフェイスの他のメソッドを呼び出す前に、このメソッドを呼び出してロケーターをアプリケーションに提供する必要があります。
ロケーターを使用すると、パーサーがエラーを報告していなくても、アプリケーションはドキュメント関連のイベントの終了位置を判別できます。 通常、アプリケーションはこの情報を使用して、独自のエラー（アプリケーションのビジネスルールに一致しない文字コンテンツなど）を報告します。 ロケーターによって返される情報は、検索エンジンで使用するにはおそらく十分ではありません。
ロケーターは、このインターフェースでのイベントの呼び出し中にのみ正しい情報を返すことに注意してください。 アプリケーションは、それ以外のときにそれを使用しようとしないでください。
- ContentHandler.startDocument()
ドキュメントの開始の通知を受け取ります。
SAXパーサーは、このインターフェイスまたはDTDHandler（ setDocumentLocator（）を除く）の他のメソッドの前に、このメソッドを1回だけ呼び出します。
- ContentHandler.endDocument()
ドキュメントの終わりの通知を受け取ります。
SAXパーサーはこのメソッドを1回だけ呼び出し、解析中に呼び出される最後のメソッドになります。 パーサーは、（回復不能なエラーのために）解析を中止するか、入力の最後に到達するまで、このメソッドを呼び出さないものとします。
- ContentHandler.startPrefixMapping(prefix, uri)
プレフィックスURI名前空間マッピングのスコープを開始します。
このイベントからの情報は、通常の名前空間処理には必要ありません。
feature_namespaces機能が有効になっている場合（デフォルト）、SAXXMLリーダーは要素名と属性名のプレフィックスを自動的に置き換えます。ただし、アプリケーションが文字データまたは属性値でプレフィックスを使用する必要がある場合、それらを安全に自動的に展開できない場合があります。 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インターフェースのオブジェクトを保持します（を参照）。要素の属性を含む属性インターフェース）。 attrs として渡されたオブジェクトは、パーサーによって再利用される可能性があります。 それへの参照を保持することは、属性のコピーを保持するための信頼できる方法ではありません。 属性のコピーを保持するには、 attrs オブジェクトの copy（）メソッドを使用します。
- ContentHandler.endElement(name)
非名前空間モードで要素の終わりを通知します。
name パラメーターには、 startElement（）イベントと同様に、要素タイプの名前が含まれます。
- ContentHandler.startElementNS(name, qname, attrs)
名前空間モードで要素の開始を通知します。
name パラメーターには、要素タイプの名前が
(uri, localname)タプルとして含まれ、 qname パラメーターには、ソースドキュメントで使用される生のXML 1.0名が含まれ、[ X184X] attrs パラメーターは、要素の属性を含むAttributesNSインターフェース（ attributesNSインターフェースを参照）のインスタンスを保持します。 要素に名前空間が関連付けられていない場合、 name の uri コンポーネントはNoneになります。 attrs として渡されたオブジェクトは、パーサーによって再利用される可能性があります。 それへの参照を保持することは、属性のコピーを保持するための信頼できる方法ではありません。 属性のコピーを保持するには、 attrs オブジェクトの copy（）メソッドを使用します。feature_namespace_prefixes機能がアクティブになっていない限り、パーサーは qname パラメーターをNoneに設定できます。
- ContentHandler.endElementNS(name, qname)
名前空間モードで要素の終わりを通知します。
name パラメーターには、 startElementNS（）メソッドと同様に、 qname パラメーターと同様に、要素タイプの名前が含まれます。
- ContentHandler.characters(content)
文字データの通知を受け取ります。
パーサーはこのメソッドを呼び出して、文字データの各チャンクを報告します。 SAXパーサーは、連続するすべての文字データを1つのチャンクで返すことも、複数のチャンクに分割することもできます。 ただし、ロケーターが有用な情報を提供できるように、単一のイベントのすべての文字は同じ外部エンティティからのものである必要があります。
content は文字列またはバイトインスタンスです。
expatリーダーモジュールは常に文字列を生成します。ノート
Python XML Special InterestGroupによって提供された以前のSAX1インターフェースは、このメソッドに対してよりJavaに似たインターフェースを使用していました。 Pythonから使用されるほとんどのパーサーは古いインターフェースを利用していなかったため、より単純な署名がそれを置き換えるために選択されました。 古いコードを新しいインターフェイスに変換するには、古い offset および length パラメーターでコンテンツをスライスする代わりに、 content を使用します。
- ContentHandler.ignorableWhitespace(whitespace)
要素コンテンツの無視できる空白の通知を受け取ります。
検証パーサーは、このメソッドを使用して、無視できる空白の各チャンクを報告する必要があります（W3C XML 1.0の推奨事項のセクション2.10を参照）。非検証パーサーは、コンテンツモデルを解析および使用できる場合、このメソッドを使用することもできます。
SAXパーサーは、隣接するすべての空白を1つのチャンクで返すことも、複数のチャンクに分割することもできます。 ただし、ロケーターが有用な情報を提供できるように、単一のイベントのすべての文字は同じ外部エンティティからのものである必要があります。
- ContentHandler.processingInstruction(target, data)
処理命令の通知を受け取ります。
パーサーは、見つかった処理命令ごとにこのメソッドを1回呼び出します。処理命令は、メインのドキュメント要素の前または後に発生する可能性があることに注意してください。
SAXパーサーは、このメソッドを使用してXML宣言（XML 1.0、セクション2.8）またはテキスト宣言（XML 1.0、セクション4.3.1）を報告しないでください。
- ContentHandler.skippedEntity(name)
スキップされたエンティティの通知を受け取ります。
パーサーは、スキップされたエンティティごとに1回このメソッドを呼び出します。 非検証プロセッサは、宣言が表示されていない場合（たとえば、エンティティが外部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オブジェクト
このインターフェイスを備えたオブジェクトは、 XMLReader からエラーおよび警告情報を受け取るために使用されます。 このインターフェイスを実装するオブジェクトを作成し、そのオブジェクトを XMLReader に登録すると、パーサーはオブジェクトのメソッドを呼び出して、すべての警告とエラーを報告します。 使用可能なエラーには、警告、（場合によっては）回復可能なエラー、および回復不可能なエラーの3つのレベルがあります。 すべてのメソッドは、SAXParseExceptionを唯一のパラメーターとして使用します。 渡された例外オブジェクトを発生させることにより、エラーと警告を例外に変換できます。
- ErrorHandler.error(exception)
- パーサーで回復可能なエラーが発生したときに呼び出されます。 このメソッドで例外が発生しない場合は、解析が続行される可能性がありますが、アプリケーションがそれ以上のドキュメント情報を期待することはできません。 パーサーの続行を許可すると、入力ドキュメントで追加のエラーが検出される可能性があります。
- ErrorHandler.fatalError(exception)
- パーサーが回復できないエラーを検出したときに呼び出されます。 このメソッドが戻ると、解析は終了することが期待されます。
- ErrorHandler.warning(exception)
- パーサーがアプリケーションにマイナーな警告情報を提示したときに呼び出されます。 このメソッドが戻ったときに解析が続行されることが期待され、ドキュメント情報は引き続きアプリケーションに渡されます。 このメソッドで例外を発生させると、解析が終了します。
