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])

SAX XMLReader オブジェクトを生成し、返します。最初に見つかったパーサが使用されます。parser_list を与える場合、それは create_parser() という名前の関数をもつモジュール名のリストでなければなりません。 parser_list に列挙されているモジュールは、パーサのデフォルトリストにあるモジュールよりも先に使われます。

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