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 یکی از ثابت‌های زیر است، و node نودی است که رویداد درباره‌ی آن است. نودها رابط‌های xml.dom را پیاده‌سازی می‌کنند؛ آن‌ها توسط پیاده‌سازی DOM داده‌شده به PullDOM ایجاد می‌شوند که به‌صورت پیش‌فرض xml.dom.minidom است.

xml.dom.pulldom.START_DOCUMENT

xml.dom.pulldom.END_DOCUMENT

شروع و پایان سند. node کلاس Document است.

xml.dom.pulldom.START_ELEMENT

xml.dom.pulldom.END_ELEMENT

برچسب آغازین و برچسب پایانی یک المان. node کلاس Element است.

xml.dom.pulldom.CHARACTERS

داده‌های نویسه. node نود Text است.

xml.dom.pulldom.IGNORABLE_WHITESPACE

فضای خالی در محتوای المان، همان‌طور که در DTD اعلام‌شده است. node نود Text است.

xml.dom.pulldom.COMMENT

یک کامنت. node نود Comment است.

xml.dom.pulldom.PROCESSING_INSTRUCTION

یک دستور پردازش. node نود ProcessingInstruction است.

از آنجا که سند به‌عنوان یک جریان «تخت» از رویدادها در نظر گرفته می‌شود، «درخت» سند به‌طور ضمنی پیمایش می‌شود و عناصر مورد نظر صرف‌نظر از عمقشان در درخت یافت می‌شوند. به بیان دیگر، نیازی به در نظر گرفتن مسائل سلسله‌مراتبی مانند جستجوی بازگشتی گره‌های سند نیست، اگرچه اگر زمینه‌ی عناصر اهمیت داشته باشد، یا باید وضعیتی مرتبط با زمینه را حفظ کرد (یعنی به خاطر سپردن موقعیت در سند در هر نقطه مشخص) یا از متد DOMEventStream.expandNode() استفاده کرد و به پردازش مرتبط با DOM روی آورد.

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

زیرکلاس xml.sax.handler.ContentHandler که رویدادهای SAX را به رویدادهای پارسرِ کششی تبدیل می‌کند. نودها ایجاد می‌شوند، اما به درخت اضافه نمی‌شوند، مگر اینکه expandNode() فراخوانی شود. documentFactory، اگر داده شده باشد، یک پیاده‌سازی DOM است که برای ایجاد سند استفاده می‌شود؛ به طور پیش‌فرض پیاده‌سازی xml.dom.minidom استفاده می‌شود.

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

زیرکلاس PullDOM که همچنین هر نود ایجادشده را به درخت اضافه می‌کند، به طوری که سند کامل ساخته شود.

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)

یک DOMEventStream برمی‌گرداند که string را نشان می‌دهد. string باید یک نمونه str باشد؛ برای تجزیه بایت‌ها، یک شیء پرونده دودویی را به parse() بدهید.

xml.dom.pulldom.default_bufsize

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

می‌توان مقدار این متغیر را پیش از فراخوانی parse() تغییر داد و مقدار جدید اعمال خواهد شد.

اشیای DOMEventStream

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

رویدادها را برای داده‌های خوانده‌شده از شیء پرونده stream توسط پارسر XMLReader parser تولید می‌کند. داده‌ها به اندازه bufsize بایت، یا نویسه برای جریان متنی، در هر بار خوانده می‌شوند.

تغییر یافته در نسخه‌ی 3.11: پشتیبانی از متد __getitem__() حذف شده است.

getEvent()

تاپل بعدی (event, node) را برمی‌گرداند، یا None در پایان سند. برای رویدادها و نودهای متناظر به بالا مراجعه کنید. نود فعلی اطلاعاتی درباره فرزندان خود ندارد، مگر اینکه expandNode() فراخوانی شود.

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

رویدادهای خوانده‌نشده را حذف می‌کند و شیء را برای تجزیه سند جدید آماده می‌کند.

clear()

پارسر و سند را رها می‌کند. جریان بسته نمی‌شود، و شیء دیگر قابل استفاده نیست.