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