xml.dom.pulldom --- 部分的な DOM ツリー構築のサポート

Source code: Lib/xml/dom/pulldom.py

xml.dom.pulldom モジュールは "プルパーザ" を提供します。 プルパーザは必要に応じて文書の DOM アクセス可能な断片を生成することができます。 基本概念は、入力 XML のストリームから "イベント" を取り出し (pull し) て処理することです。 SAX とは、コールバックつきのイベント駆動処理モデルを採用しているという点で同様ですが、SAX とは対照的に、プルパーザの使用者には処理が完了するかエラー状態が発生するまで、明示的にストリームからイベントを取り出し、イベントに対しループを回す責任があります。

注釈

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

バージョン 3.7.1 で変更: セキュリティを向上させるため、SAX パーサーはデフォルトでは外部一般エンティティを処理しなくなりました。 外部エンティティの処理を有効にするには、次のようにカスタムのパーサーインスタンスを渡します。

from xml.dom.pulldom import parse
from xml.sax import make_parser
from xml.sax.handler import feature_external_ges

parser = make_parser()
parser.setFeature(feature_external_ges, True)
parse(filename, parser=parser)

以下はプログラム例です:

from xml.dom import pulldom

doc = pulldom.parse('sales_items.xml')
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'item':
        if int(node.getAttribute('price')) > 50:
            doc.expandNode(node)
            print(node.toxml())

event is one of the following constants, and node is the node which the event is about. The nodes implement the xml.dom interfaces; they are created by the DOM implementation given to PullDOM, which is xml.dom.minidom by default.

xml.dom.pulldom.START_DOCUMENT
xml.dom.pulldom.END_DOCUMENT

The start and the end of the document. node is the Document.

xml.dom.pulldom.START_ELEMENT
xml.dom.pulldom.END_ELEMENT

The start tag and the end tag of an element. node is the Element.

xml.dom.pulldom.CHARACTERS

Character data. node is the Text node.

xml.dom.pulldom.IGNORABLE_WHITESPACE

White space in element content, as declared in the DTD. node is the Text node.

xml.dom.pulldom.COMMENT

A comment. node is the Comment node.

xml.dom.pulldom.PROCESSING_INSTRUCTION

A processing instruction. node is the ProcessingInstruction node.

文書を「平坦な」イベントの流れとして扱うため、文書の「木」は暗黙的に走査され、木の中の深さにかかわらず目的の要素を見つけられます。 つまり、文書ノードを再帰的に検索するなど、階層構造を考慮する必要はありません。 ただし、要素の文脈が重要な場合は、文脈に関する状態を管理する (文書中のどの位置にいるかを常に記憶する) か、 DOMEventStream.expandNode() メソッドを使って DOM による処理に切り替える必要があります。

class xml.dom.pulldom.PullDOM(documentFactory=None)

Subclass of xml.sax.handler.ContentHandler which turns SAX events into the events of the pull parser. The nodes are created, but they are not added to the tree, unless expandNode() is called. documentFactory, if given, is a DOM implementation used to create the document; by default the implementation of xml.dom.minidom is used.

class xml.dom.pulldom.SAX2DOM(documentFactory=None)

Subclass of PullDOM which also adds every created node to the tree, so that the complete document is built.

xml.dom.pulldom.parse(stream_or_string, parser=None, bufsize=None)

与えられた入力から DOMEventStream を返します。stream_or_string はファイル名かファイル様オブジェクトのいずれかです。parser は、与えれた場合、 XMLReader オブジェクトでなければなりません。この関数はパーザの文書ハンドラを変えて名前空間のサポートを有効にします。パーザの他の設定 (例えばエンティティリゾルバ) は前もってしておかなければなりません。

XML データを文字列で持っている場合、 parseString() を代わりに使うことができます:

xml.dom.pulldom.parseString(string, parser=None)

Return a DOMEventStream that represents the string. string must be a str instance; to parse bytes, pass a binary file object to parse().

xml.dom.pulldom.default_bufsize

parse() の bufsize パラメタのデフォルト値です。

この変数の値は parse() を呼び出す前に変更することができます。その場合、その新しい値が有効になります。

DOMEventStream オブジェクト

class xml.dom.pulldom.DOMEventStream(stream, parser, bufsize)

Produce the events for the data read from the file object stream by the XMLReader parser. The data is read by bufsize bytes, or characters for a text stream, at a time.

バージョン 3.11 で変更: __getitem__() メソッドのサポートは削除されました。

getEvent()

Return the next (event, node) tuple, or None at the end of the document. See above for the events and the corresponding nodes. The current node does not contain information about its children, unless expandNode() is called.

expandNode(node)

node の全子ノードを node に展開します。例:

from xml.dom import pulldom

xml = '<html><title>Foo</title> <p>Some text <div>and more</div></p> </html>'
doc = pulldom.parseString(xml)
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'p':
        # 次の文は '<p/>' だけを表示する。
        print(node.toxml())
        doc.expandNode(node)
        # 次の文はすべての子を含むノード '<p>Some text <div>and more</div></p>' を表示する。
        print(node.toxml())
reset()

Discard the events which are not read yet and prepare the object for parsing a new document.

clear()

Release the parser and the document. The stream is not closed, and the object can no longer be used.