# `xml.dom.pulldom` — Support for building partial DOM trees

Вихідний код: Lib/xml/dom/pulldom.py

The `xml.dom.pulldom` module provides a «pull parser» which can also be asked to produce DOM-accessible fragments of the document where necessary. The basic concept involves pulling «events» from a stream of incoming XML and processing them. In contrast to SAX which also employs an event-driven processing model together with callbacks, the user of a pull parser is responsible for explicitly pulling events from the stream, looping over those events until either processing is finished or an error condition occurs.

Примітка

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

`подія` є константою і може бути одним із:

- `START_ELEMENT`

- `END_ELEMENT`

- `COMMENT`

- `START_DOCUMENT`

- `END_DOCUMENT`

- `CHARACTERS`

- `INSTRUCTION_PROCESSING_INSTRUCTION`

- `IGNORABLE_WHITESPACE`

`вузол` є об’єктом типу `xml.dom.minidom.Document`, `xml.dom.minidom.Element` або `xml.dom.minidom.Text`.

Оскільки документ розглядається як «плоский» потік подій, «дерево» документа обходиться неявно, і потрібні елементи знаходять незалежно від їх глибини в дереві. Іншими словами, не потрібно розглядати ієрархічні проблеми, такі як рекурсивний пошук вузлів документа, хоча, якби контекст елементів був важливим, потрібно було б підтримувати певний контекстно-пов’язаний стан (тобто запам’ятовувати, де ви знаходитесь у документі) у будь-який момент) або використати метод `DOMEventStream.expandNode()` і перейти до обробки, пов’язаної з DOM.

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

  Підклас `xml.sax.handler.ContentHandler`.

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

  Підклас `xml.sax.handler.ContentHandler`.

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`, який представляє рядок (Unicode).

xml.dom.pulldom.default_bufsize

  Значення за замовчуванням для параметра bufsize — `parse()`.

  Значення цієї змінної можна змінити перед викликом `parse()`, і нове значення набуде чинності.

## Об’єкти DOMEventStream

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

  Змінено в версії 3.11: Support for `__getitem__()` method has been removed.

  getEvent()

    Повертає кортеж, що містить подію та поточний вузол як `xml.dom.minidom.Document`, якщо подія дорівнює `START_DOCUMENT`, `xml.dom.minidom.Element`, якщо подія дорівнює `START_ELEMENT` або `END_ELEMENT` або `xml.dom.minidom.Text`, якщо подія дорівнює `CHARACTERS`. Поточний вузол не містить інформації про своїх дочірніх вузлів, якщо не викликати `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()