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 したときはパースの継続が求められ、ドキ
   ュメント情報はアプリケーションに送り続けられます。このメソッドでの
   例外の送出はパースを終了します。
