xml.sax --- Support for SAX2 parsers

ソースコード: Lib/xml/sax/__init__.py

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

警告

xml.sax モジュールは悪意を持って作成されたデータに対して安全ではありません。信頼できないデータや認証されていないデータをパースする必要がある場合は XML の脆弱性 を参照してください。

バージョン 3.7.1 で変更: SAXパーサーは、セキュリティーを向上させるために、デフォルトで一般的な外部エンティティーを処理しなくなりました。以前は、パーサーは、DTDおよびエンティティ用にファイルシステムからリモートファイルまたはロードされたローカルファイルをフェッチするためのネットワーク接続を作成していました。この機能は parser オブジェクトと(実) 引数 feature_external_ges の setFeature() メソッドで再度有効にすることができます。

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

xml.sax.make_parser(parser_list=[])

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

バージョン 3.8 で変更: parser_list 引数はリストだけでなく、イテラブルでもよくなりました。

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

SAX パーサを生成し、そのパーサをドキュメントの解析に使用します。filename_or_stream として与えられるドキュメントは、ファイル名でもファイルオブジェクトでもかまいません。 handler 引数は SAX ContentHandler のインスタントである必要があります。error_handler が与えられる場合は、 SAX ErrorHandler のインスタンスである必要があります。この引数を省略した場合、全ての例外に対して 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 のサブクラスです。パースエラーに関する情報として、このクラスのインスタンスが SAX ErrorHandler インターフェースのメソッドに渡されます。このクラスは SAXException 同様 SAX Locator インターフェースもサポートしています。

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 モジュール

パーサが提供するオブジェクトのインターフェース定義。

SAXException オブジェクト

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

SAXException.getMessage()

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

SAXException.getException()

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