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

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

Модуль `xml.dom.pulldom` забезпечує «аналізатор витягування», який також може бути запрошений створити доступні для DOM фрагменти документа, де це необхідно. Основна концепція передбачає вилучення «подій» із потоку вхідного XML та їх обробку. На відміну від SAX, який також використовує керовану подіями модель обробки разом із зворотними викликами, користувач аналізатора вилучення відповідає за явне отримання подій із потоку, циклюючи ці події, доки обробка не завершиться або не виникне помилка.

Попередження

Модуль `xml.dom.pulldom` не захищений від зловмисно створених даних. Якщо вам потрібно проаналізувати ненадійні або неавтентифіковані дані, перегляньте Уразливості 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())

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

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