"xml.sax.handler" --- SAX ハンドラーの基底クラス
************************************************

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

======================================================================

SAX API は、コンテンツハンドラ、DTD ハンドラ、エラーハンドラ、エンティ
ティリゾルバ、字句ハンドラの 5 種類を定義しています。 通常、アプリケー
ションは必要なイベントのインターフェースだけを実装すれば足ります。 複
数のインターフェースを 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

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

class xml.sax.handler.LexicalHandler

   多くのアプリケーションでは関心のない、発生頻度の低いイベントを通知
   するためにパーサが使うインターフェースです。

これらのクラスに加え、"xml.sax.handler" は機能名とプロパティ名を表すシ
ンボル定数を提供します。

xml.sax.handler.feature_namespaces

      値: ""http://xml.org/sax/features/namespaces""
      真: 名前空間を処理します。
      偽: 名前空間処理を行わないことを許可します (namespace-prefixes が有効であることを意味します; デフォルト)。
      アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.feature_namespace_prefixes

      値: ""http://xml.org/sax/features/namespace-prefixes""
      真: 名前空間宣言で用いられている元々の接頭辞付きの名前と属性を報告します。
      偽: 名前空間宣言で用いられている属性を報告しません。オプションで元々の接頭辞付きの名前も報告しません (デフォルト)。
      アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

   "xml.parsers.expat" を使うパーサはこの機能に対応していません。

xml.sax.handler.feature_string_interning

      値: ""http://xml.org/sax/features/string-interning""
      真: すべての要素名、接頭辞、属性名、名前空間 URI、ローカル名を辞書にインターンします ("property_interning_dict" を参照)。
      偽: 名前を必ずしもシンボルに登録しませんが、されるかもしれません (デフォルト)。
      アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

xml.sax.handler.feature_validation

      値: ""http://xml.org/sax/features/validation""
      真: すべての妥当性検査エラーを報告します (external-general-entities と external-parameter-entities が有効であることを意味します)。
      偽: 妥当性検査エラーを報告しません。
      アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

   Expat は妥当性検査を行わないパーサなので、"xml.parsers.expat" を使
   うパーサはこの機能に対応していません。

xml.sax.handler.feature_external_ges

   警告:

     この機能を有効にして利用者から受け取った XML を解析すると、外部エ
     ンティティ攻撃 に対して脆弱になります。 有効にする前に、脅威モデ
     ル を検討してください。

      値: ""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.parsers.expat" を使うパーサはこの機能に対応していません。

xml.sax.handler.all_features

   全機能のリスト。

xml.sax.handler.property_lexical_handler

      値: ""http://xml.org/sax/properties/lexical-handler""
      データ型: "LexicalHandler"
      説明: コメントなど字句解析イベント用のオプション拡張ハンドラ。
      アクセス: 読み書き可

xml.sax.handler.property_declaration_handler

      値: ""http://xml.org/sax/properties/declaration-handler""
      データ型: SAX2 の "DeclHandler" インターフェースを実装するオブジェクト
      説明: 表記や未解析エンティティをのぞく DTD 関連イベント用のオプション拡張ハンドラ。
      アクセス: 読み書き可

   標準ライブラリのパーサはどれもこのプロパティに対応しておらず、標準
   ライブラリにはこのハンドラもありません。

xml.sax.handler.property_dom_node

      値: ""http://xml.org/sax/properties/dom-node""
      データ型: "xml.dom.Node"
      説明: パース時は DOM イテレータならば現在の DOM ノードです。非パース時はイテレートのルート DOM ノードです。
      アクセス: (パース時) 読み込み専用; (パース時以外) 読み書き可

   標準ライブラリのパーサはどれもこのプロパティに対応していません。

xml.sax.handler.property_xml_string

      値: ""http://xml.org/sax/properties/xml-string""
      データ型: バイト列
      説明: 現在のイベントの元になったリテラル文字列。
      アクセス: 読み取り専用で、ハンドラのコールバック中だけ利用可能

xml.sax.handler.property_encoding

      値: ""http://www.python.org/sax/properties/encoding""
      データ型: 文字列
      説明: 入力データのエンコーディングとして仮定する名前。
      アクセス: 読み書き可

   標準ライブラリのパーサはどれもこのプロパティに対応していません。

xml.sax.handler.property_interning_dict

      値: ""http://www.python.org/sax/properties/interning-dict""
      データ型: 辞書
      説明: 名前のインターンに使う辞書。
      名前をインターンしない場合は "None"。
      これを設定すると、"feature_string_interning" 機能と同様にインターンが有効になります。
      アクセス: 読み書き可

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 インターフェースの
   オブジェクトを保持します。 *attrs* として渡されたオブジェクトはパー
   サが再利用する場合があるため、参照を保持するだけでは属性のコピーを
   確実に保存できません。 属性のコピーを保持するには、*attrs* オブジェ
   クトの "copy()" メソッドを使ってください。

ContentHandler.endElement(name)

   非名前空間モードでの要素の終了を通知します。

   *name* 引数は "startElement()" イベントとまったく同じ要素型名を持ち
   ます。

ContentHandler.startElementNS(name, qname, attrs)

   名前空間モードでの要素の開始を通知します。

   *name* 引数は要素型の名前を "(uri, localname)" タプルで保持し、
   *qname* 引数は元の文書で使われた XML 1.0 名を保持します。 *attrs*
   引数は、その要素の属性を含む 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 オブジェクト
=========================

このインターフェースを持つオブジェクトは、"XMLReader" からエラーと警告
の情報を受け取るために使います。 このインターフェースを実装したオブジ
ェクトを作成して "XMLReader" に登録すると、 パーサはそのメソッドを呼び
出してすべての警告とエラーを報告します。 エラーには、警告、回復できる
可能性のあるエラー、回復不能なエラーの 3 つのレベルがあります。 どのメ
ソッドも "SAXParseException" だけを引数に取ります。 渡された例外オブジ
ェクトを送出することで、エラーや警告を例外に変換できます。

ErrorHandler.error(exception)

   パーサが回復可能なエラーに遭遇したときに呼び出されます。 このメソッ
   ドが例外を送出しなければ解析を続ける場合がありますが、アプリケーシ
   ョンはそれ以上の文書情報が得られると期待すべきではありません。 解析
   の継続を許すと、入力文書の他のエラーを発見できることがあります。

ErrorHandler.fatalError(exception)

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

ErrorHandler.warning(exception)

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


LexicalHandler オブジェクト
===========================

字句イベント用の省略可能な SAX2 ハンドラです。

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.

"XMLReader" の "LexicalHandler" を設定するには、"setProperty()" メソッ
ドにプロパティ識別子 "'http://xml.org/sax/properties/lexical-handler'"
を指定します。

LexicalHandler.comment(content)

   文書内のあらゆる場所にあるコメントを報告します (DTD 内や文書要素の
   外も含みます)。

LexicalHandler.startDTD(name, public_id, system_id)

   文書に DTD が関連付けられている場合、DTD 宣言の開始を報告します。

LexicalHandler.endDTD()

   DTD 宣言の終了を報告します。

LexicalHandler.startCDATA()

   CDATA セクションの開始を報告します。

   CDATA セクションの内容は、"characters()" ハンドラを通じて報告されま
   す。

LexicalHandler.endCDATA()

   CDATA セクションの終了を報告します。
