"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.
