19.11. "xml.sax" --- SAX2 パーサのサポート
******************************************

バージョン 2.0 で追加.

"xml.sax" パッケージは Python 用の Simple API for XML (SAX) インターフ
ェースを実装した数多くのモジュールを提供しています。またパッケージには
SAX 例外と SAX API 利用者が頻繁に利用するであろう有用な関数群も含まれ
ています。

警告: "xml.sax" モジュールは悪意を持って構築されたデータに対して安全
  ではあ りません。信頼できないデータや認証されていないデータを解析す
  る必要が あるばあいは、XML の脆弱性 を参照してください。

その関数群は以下の通りです:

xml.sax.make_parser([parser_list])

   Create and return a SAX "XMLReader" object.  The first parser found
   will be used.  If *parser_list* is provided, it must be a list of
   strings which name modules that have a function named
   "create_parser()".  Modules listed in *parser_list* will be used
   before modules in the default list of parsers.

xml.sax.parse(filename_or_stream, handler[, error_handler])

   SAX パーサを生成し、ドキュメントの解析に使用します。
   *filename_or_stream* として与えられるドキュメントは、ファイル名でも
   ファイルオブジェクトでもかまいません。 *handler* パラメータは SAX
   "ContentHandler" のインスタントである必要があります。もし
   *error_handler* が与える場合は、それは SAX "ErrorHandler"  のインス
   タンスでなければなりません。引数で指定しない場合は、例外
   "SAXParseException" を発生します。 戻り値はありません。すべての動作
   は *handler* が行われなければなりません。

xml.sax.parseString(string, handler[, error_handler])

   "parse()" に似ていますが、こちらはパラメータ *string* で指定された
   バッファをパースします。

典型的な SAX アプリケーションでは3種類のオブジェクト(リーダ、ハンドラ
、入力元)が用いられます(ここで言うリーダとはパーサを指しています)。言
い換えると、プログラムはまず入力元からバイト列、あるいは文字列を読み込
み、一連のイベントを発生させます。発生したイベントはハンドラ・オブジェ
クトによって振り分けられます。さらに言い換えると、リーダがハンドラのメ
ソッドを呼び出すわけです。つまり SAX アプリケーションには、リーダ・オ
ブジェクト、(作成またはオープンされる)入力元のオブジェクト、ハンドラ・
オブジェクト、そしてこれら3つのオブジェクトを連携させることが必須なの
です。前処理の最後の段階でリーダは入力をパースするために呼び出されます
。パースの過程で入力データの構造、構文にもとづいたイベントにより、ハン
ドラ・オブジェクトのメソッドが呼び出されます。

これらのオブジェクトでは、インタフェースだけに関係があります。通常は、
これらはアプリケーション自体はインスタンス化しません。 Python は明示的
なインタフェースの概念を持たないので、形式的にはクラスとして導入されま
す。しかし、アプリケーションは提供されたクラスを継承せずに実装をしても
かまいません。 インタフェース "InputSource", "Locator", "Attributes",
"AttributesNS", "XMLReader"  はモジュール "xml.sax.xmlreader". The
handler interfaces are defined in "xml.sax.handler" で定義されています
。ハンドラインタフェースは "xml.sax.handler" で定義されています。便利
なので、  "InputSource" (よく直接インスタンス化されるクラス) とハンド
ラクラスは "xml.sax" からもアクセスできます。これらのインタフェースは
下記で説明します。

このほかに "xml.sax" は次の例外クラスも提供しています。

exception xml.sax.SAXException(msg[, exception])

   XML エラーと警告をカプセル化します。このクラスには XML パーサとアプ
   リケーションで発生するエラーおよび警告の基本的な情報を持たせること
   ができます。また機能追加や地域化のためにサブクラス化することも可能
   です。なお "ErrorHandler" で定義されているハンドラがこの例外のイン
   スタンスを受け取ることに注意してください。実際に例外を発生させるこ
   とは必須でなく、情報のコンテナとして利用されることもあるからです。

   インスタンスを作成する際 *msg* はエラー内容を示す可読データにしてく
   ださい。オプションの *exception* パラメータは "None" もしくはパース
   用コードで補足、渡って来る情報でなければなりません。

   このクラスはSAX 例外の基底クラスになります。

exception xml.sax.SAXParseException(msg, exception, locator)

   パースエラー時に発生する "SAXException" のサブクラスです。パースエ
   ラーに関する情報として、このクラスのインスタンスが SAX
   "ErrorHandler" インターフェースのメソッドに渡されます。このクラスは
   "SAXException" 同様 SAX "Locator" インターフェースもサポートしてい
   ます。

exception xml.sax.SAXNotRecognizedException(msg[, exception])

   SAX "XMLReader" が認識できない機能やプロパティに遭遇したとき発生さ
   せる "SAXException" のサブクラスです。 SAX アプリケーションや拡張モ
   ジュールにおいて同様の目的にこのクラスを利用することもできます。

exception xml.sax.SAXNotSupportedException(msg[, exception])

   SAX "XMLReader" が要求された機能をサポートしていないとき発生させる
   "SAXException" のサブクラスです。 SAX アプリケーションや拡張モジュ
   ールにおいて同様の目的にこのクラスを利用することもできます。

参考:

  SAX: The Simple API for XML
     SAX API 定義に関し中心となっているサイトです。Java による実装とオ
     ンライン・ドキュメントが提供されています。実装と SAX API の歴史に
     関する情報のリンクも掲載されています。

  "xml.sax.handler" モジュール
     アプリケーションが提供するオブジェクトのインターフェース定義。

  "xml.sax.saxutils" モジュール
     SAX アプリケーション向けの有用な関数群。

  "xml.sax.xmlreader" モジュール
     パーサが提供するオブジェクトのインターフェース定義。


19.11.1. SAXException オブジェクト
==================================

"SAXException" 例外クラスは以下のメソッドをサポートしています:

SAXException.getMessage()

   エラー状態を示す可読メッセージを返します。

SAXException.getException()

   カプセル化した例外オブジェクトまたは "None" を返します。
