xml.sax --- SAX2 パーサーのサポート¶
ソースコード: Lib/xml/sax/__init__.py
xml.sax パッケージは、Simple API for XML (SAX) インターフェースを Python 向けに実装する複数のモジュールを提供します。
パッケージ自体は、SAX の例外と、SAX API の利用者がよく使う便利な関数を提供します。
注釈
信頼できないデータや、認証されていないデータを解析する場合は、XML のセキュリティ を参照してください。
バージョン 3.7.1 で変更: セキュリティを向上させるため、SAX パーサーはデフォルトでは外部一般エンティティを処理しなくなりました。
以前は DTD やエンティティを処理するために、ネットワークに接続してリモートファイルを取得したり、ファイルシステムからローカルファイルを読み込んだりしていました。
この機能を再び有効にするには、パーサーオブジェクトの setFeature() メソッドに feature_external_ges を引数として渡します。
以下の便利な関数とデータがあります。
- 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, errorHandler=handler.ErrorHandler())¶
SAX パーサーを作成し、それを使って文書を解析します。 filename_or_stream に渡す文書は、システム識別子 (入力元を識別する文字列で、通常はファイル名か URL)、 パス類似 オブジェクト、またはファイルオブジェクトで指定できます。 システム識別子が既存のファイルを指していない場合は、
urllib.request.urlopen()で開きます。 handler 引数には SAX のContentHandlerインスタンスが必要です。 errorHandler を指定する場合は SAX のErrorHandlerインスタンスでなければなりません。 省略すると、すべてのエラーでSAXParseExceptionを送出します。 戻り値はありません。 すべての処理は、渡した handler で行う必要があります。
- xml.sax.parseString(string, handler, errorHandler=handler.ErrorHandler())¶
parse()と同様ですが、こちらは引数で受け取ったバッファ string をパースします。 string はstrインスタンスか bytes-like object でなければなりません。バージョン 3.5 で変更:
strインスタンスがサポートされました。
- xml.sax.default_parser_list¶
make_parser()が parser_list 引数に指定されたモジュールの後に試す、モジュール名のリストです。 通常は'xml.sax.expatreader'を含みますが、PY_SAX_PARSER環境変数が設定されていて環境変数が無視されない場合は、 そこから取得したカンマ区切りのモジュール名のリストになります。
典型的な 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 アプリケーションや拡張でも、同様の目的にこのクラスを使えます。
- exception xml.sax.SAXReaderNotAvailable(msg, exception=None)¶
利用できるパーサーがないときに送出する
SAXNotSupportedExceptionのサブクラスです。 パーサーモジュールは、提供するパーサーを利用できない場合、インポート時または解析中にこの例外を送出します。 また、make_parser()は、試したどのモジュールも利用可能なパーサーを提供しなかった場合にこの例外を送出します。
参考
- 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を返します。