xml.sax --- SAX2 バーサーのサポート

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

The xml.sax package provides a number of modules which implement the Simple API for XML (SAX) interface for Python. The package itself provides the SAX exceptions and the convenience functions which will be most used by users of the SAX API.

注釈

If you need to parse untrusted or unauthenticated data, see XML security.

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

The convenience functions and data are:

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())

Create a SAX parser and use it to parse a document. The document, passed in as filename_or_stream, can be a system identifier (a string identifying the input source -- typically a file name or a URL), a path-like object, or a file object. A system identifier which does not refer to an existing file is opened with urllib.request.urlopen(). The handler parameter needs to be a SAX ContentHandler instance. If errorHandler is given, it must be a SAX ErrorHandler instance; if omitted, SAXParseException will be raised on all errors. There is no return value; all work must be done by the handler passed in.

xml.sax.parseString(string, handler, errorHandler=handler.ErrorHandler())

parse() と同様ですが、こちらは引数で受け取ったバッファ string をパースします。 string は str インスタンスか bytes-like object でなければなりません。

バージョン 3.5 で変更: str インスタンスがサポートされました。

xml.sax.default_parser_list

The list of the names of modules which are tried by make_parser() after the modules named in its parser_list argument. It contains 'xml.sax.expatreader', or, if the PY_SAX_PARSER environment variable is set and the environment is not ignored, the comma-separated list of module names taken from it.

典型的な SAX アプリケーションでは3種類のオブジェクト(リーダ、ハンドラ、入力元)が用いられます。ここで言うリーダとはパーサを指しています。つまり、入力元からバイト列または文字列を読み込み、一連のイベントを発生させるコード片のことです。発生したイベントはハンドラ・オブジェクトに割り振られます。言い換えると、リーダがハンドラのメソッドを呼び出すわけです。つまり、 SAX アプリケーションは、リーダ・オブジェクトを作成し、入力元のオブジェクトを作成するか開き、ハンドラ・オブジェクトを作成し、これら3つのオブジェクトを連携させる必要があります。準備の最終段階では、リーダが呼び出され、入力をパースします。パース中には、入力データからの構造イベントや構文イベントに基づいて、ハンドラ・オブジェクトのメソッドが呼び出されます。

For these objects, only the interfaces are relevant; they are normally not instantiated by the application itself. Since Python does not have an explicit notion of interface, they are formally introduced as classes, but applications may use implementations which do not inherit from the provided classes. The InputSource, Locator, Attributes, AttributesNS, and XMLReader interfaces are defined in the module xml.sax.xmlreader. The handler interfaces are defined in xml.sax.handler. For convenience, InputSource (which is often instantiated directly) and the handler classes are also available from xml.sax. These interfaces are described below.

In addition to these classes, xml.sax provides the following exception classes.

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 アプリケーションや拡張モジュールにおいて同様の目的にこのクラスを利用することもできます。

exception xml.sax.SAXReaderNotAvailable(msg, exception=None)

Subclass of SAXNotSupportedException raised when no parser is available. A parser module raises it when it is imported or during parsing if the parser it provides cannot be used, and make_parser() raises it if no module from the tried ones provides a usable 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 を返します。