20.9. xml.sax — SAX2 パーサのサポート¶
ソースコード: Lib/xml/sax/__init__.py
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()という名前の関数をもつモジュール名のシーケンスでなければなりません。
-
xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())¶ SAX パーサを生成し、ドキュメントの解析に使用します。filename_or_stream として与えられるドキュメントは、ファイル名でもファイルオブジェクトでもかまいません。 handler パラメータは SAX
ContentHandlerのインスタントである必要があります。もし error_handler が与える場合は、それは SAXErrorHandlerのインスタンスでなければなりません。引数で指定しない場合は、例外SAXParseExceptionを発生します。 戻り値はありません。すべての動作は handler が行われなければなりません。
-
xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())¶ parse()と同様ですが、こちらは引数で受け取ったバッファ string をパースします。 string はstrインスタンスか bytes-like object でなければなりません。バージョン 3.5 で変更:
strインスタンスがサポートされました。
典型的な 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=None)¶ XML エラーと警告をカプセル化します。このクラスには XML パーサとアプリケーションで発生するエラーおよび警告の基本的な情報を持たせることができます。また機能追加や地域化のためにサブクラス化することも可能です。なお
ErrorHandlerで定義されているハンドラがこの例外のインスタンスを受け取ることに注意してください。実際に例外を発生させることは必須でなく、情報のコンテナとして利用されることもあるからです。インスタンスを作成する際 msg はエラー内容を示す可読データにしてください。オプションの exception パラメータは
Noneもしくはパース用コードで補足、渡って来る情報でなければなりません。このクラスはSAX 例外の基底クラスになります。
-
exception
xml.sax.SAXParseException(msg, exception, locator)¶ パースエラー時に発生する
SAXExceptionのサブクラスです。パースエラーに関する情報として、このクラスのインスタンスが SAXErrorHandlerインターフェースのメソッドに渡されます。このクラスはSAXException同様 SAXLocatorインターフェースもサポートしています。
-
exception
xml.sax.SAXNotRecognizedException(msg, exception=None)¶ SAX
XMLReaderが認識できない機能やプロパティに遭遇したとき発生させるSAXExceptionのサブクラスです。 SAX アプリケーションや拡張モジュールにおいて同様の目的にこのクラスを利用することもできます。
-
exception
xml.sax.SAXNotSupportedException(msg, exception=None)¶ 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モジュールパーサが提供するオブジェクトのインターフェース定義。
20.9.1. SAXException オブジェクト¶
SAXException 例外クラスは以下のメソッドをサポートしています:
-
SAXException.getMessage()¶ エラー状態を示す可読メッセージを返します。
-
SAXException.getException()¶ カプセル化した例外オブジェクトまたは
Noneを返します。