xml.sax
--- SAX2 バーサーのサポート¶
ソースコード: Lib/xml/sax/__init__.py
xml.sax
パッケージは Python 用の Simple API for XML (SAX) インターフェースを実装した数多くのモジュールを提供しています。またパッケージには SAX 例外と SAX API 利用者が頻繁に利用するであろう有用な関数群も含まれています。
注釈
If you need to parse untrusted or unauthenticated data, see XML security.
バージョン 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 が与えられる場合は、 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
モジュールパーサが提供するオブジェクトのインターフェース定義。
SAXException オブジェクト¶
SAXException
例外クラスは以下のメソッドをサポートしています:
- SAXException.getMessage()¶
エラー状態を示す可読メッセージを返します。
- SAXException.getException()¶
カプセル化した例外オブジェクトまたは
None
を返します。