xml.dom.pulldom --- پشتیبانی از ساخت درخت‌های DOM جزئی

کد منبع: Lib/xml/dom/pulldom.py

---

ماژول xml.dom.pulldom یک «پارسر کششی (pull parser)» فراهم می‌کند که همچنین می‌توان از آن خواست در صورت لزوم بخش‌هایی از سند را که از طریق DOM قابل‌دسترسی هستند تولید کند. مفهوم پایه شامل کشیدن «رویدادها» از یک جریان XML ورودی و پردازش آن‌ها است. در مقابل SAX، که همچنین از یک مدل پردازش رویدادمحور به همراه کال‌بک‌ها استفاده می‌کند، کاربر یک پارسر کششی مسئول است که رویدادها را به‌صراحت از جریان بکشد و روی آن رویدادها حلقه بزند تا زمانی که پردازش به پایان برسد یا وضعیت خطایی رخ دهد.

توجه

اگر نیاز دارید داده‌های غیرقابل‌اعتماد یا احراز هویت‌نشده را تجزیه کنید، امنیت XML را ببینید.

تغییر یافته در نسخه‌ی 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

مقدار پیش‌فرض برای پارامتر bufsize در parse().

می‌توان مقدار این متغیر را پیش از فراخوانی 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':
        # Following statement only prints '<p/>'
        print(node.toxml())
        doc.expandNode(node)
        # Following statement prints node with all its children '<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.