# 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` を返します。