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 で定義されています。ハンドラインタフェースは 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を返します。