Документация Python неофициальный перевод
Содержание страницы

xml.dom.minidom – Минимальная реализация DOMxml.dom.minidom – Minimal DOM implementation

Исходный код: Lib/xml/dom/minidom.py

xml.dom.minidom – это минимальная реализация интерфейса Document Object Model с API, похожим на API в других языках. Она призвана быть проще, чем полный DOM, и значительно меньше. Пользователям, которые ещё недостаточно знакомы с DOM, стоит рассмотреть использование модуля xml.etree.ElementTree для обработки XML.

Предупреждение

Модуль xml.dom.minidom не защищён от вредоносных данных. Если нужно разобрать непроверенные или неаутентифицированные данные, см. уязвимости XML.

Приложения, работающие с DOM, обычно начинают с разбора XML в DOM. С xml.dom.minidom это делается с помощью функций parse:

from xml.dom.minidom import parse, parseString

dom1 = parse('c:\\temp\\mydata.xml')  # разобрать XML-файл по имени

datasource = open('c:\\temp\\mydata.xml')
dom2 = parse(datasource)  # разобрать открытый файл

dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')

Функция parse() может принимать имя файла или открытый файловый объект.

xml.dom.minidom.parse(filename_or_file, parser=None, bufsize=None)

Возвращает Document из переданных входных данных. filename_or_file может быть либо именем файла, либо объектом, похожим на файл. parser, если указан, должен быть объектом парсера SAX2. Эта функция изменит обработчик документа парсера и включит поддержку пространств имён; остальные настройки парсера (например, установка обработчика сущностей) должны быть выполнены заранее.

Если XML находится в строке, можно использовать функцию parseString() вместо этого:

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

Возвращает Document, представляющий строку. Этот метод создаёт объект io.StringIO для строки и передаёт его в parse().

Обе функции возвращают объект Document, представляющий содержимое документа.

Функции parse() и parseString() связывают XML парсер с «DOM-построителем», который может принимать события разбора от любого SAX-парсера и преобразовывать их в DOM-дерево. Названия функций, возможно, вводят в заблуждение, но их легко понять при изучении интерфейсов. Разбор документа завершится до того, как эти функции вернут управление; просто эти функции сами не предоставляют реализацию парсера.

Можно также создать Document, вызвав метод объекта «DOM Implementation» (реализация DOM). Получить этот объект можно либо вызовом функции getDOMImplementation() в пакете xml.dom, либо в модуле xml.dom.minidom. Получив Document, можно добавлять в него дочерние узлы, чтобы заполнить DOM:

from xml.dom.minidom import getDOMImplementation

impl = getDOMImplementation()

newdoc = impl.createDocument(None, "some_tag", None)
top_element = newdoc.documentElement
text = newdoc.createTextNode('Some textual content.')
top_element.appendChild(text)

Получив объект DOM-документа, можно обращаться к частям XML-документа через его свойства и методы. Эти свойства определены в спецификации DOM. Основное свойство объекта документа – это свойство documentElement. Оно даёт доступ к корневому элементу XML-документа: тому, который содержит все остальные. Вот пример программы:

dom3 = parseString("<myxml>Some data</myxml>")
assert dom3.documentElement.tagName == "myxml"

Когда работа с DOM-деревом завершена, можно дополнительно вызвать метод unlink(), чтобы стимулировать раннюю очистку более не нужных объектов. unlink() – это xml.dom.minidom-специфичное расширение DOM API, которое делает узел и его потомков фактически бесполезными. В противном случае сборщик мусора Python в конечном итоге позаботится об объектах в дереве.

См. также

Спецификация объектной модели документа (DOM) уровня 1

Рекомендация W3C для DOM, поддерживаемая xml.dom.minidom.

Объекты DOMDOM Objects

Определение DOM API для Python даётся как часть документации модуля xml.dom. В этом разделе перечислены отличия между API и xml.dom.minidom.

Разрывает внутренние ссылки внутри DOM, чтобы он мог быть собран сборщиком мусора на версиях Python без циклического GC. Даже если циклический GC доступен, использование этого метода может освободить большие объёмы памяти раньше, поэтому вызов его для DOM-объектов, как только они больше не нужны, является хорошей практикой. Этот метод нужно вызывать только для объекта Document, но его можно вызывать и для дочерних узлов, чтобы удалить потомков этого узла.

Можно избежать явного вызова этого метода, используя оператор with. Следующий код автоматически вызовет unlink для dom при выходе из блока with:

with xml.dom.minidom.parse(datasource) as dom:
    ... # Работать с DOM.
Node.writexml(writer, indent="", addindent="", newl="", encoding=None, standalone=None)

Записывает XML в объект writer. Writer принимает на вход тексты, а не байты; у него должен быть метод write(), соответствующий интерфейсу файлового объекта. Параметр indent задаёт отступ текущего узла. Параметр addindent задаёт дополнительный отступ для подузлов текущего узла. Параметр newl указывает строку, используемую для завершения строк.

Для узла Document можно использовать дополнительный именованный аргумент encoding для указания поля кодировки в заголовке XML.

Аналогично, явное указание аргумента standalone приводит к добавлению объявлений standalone в пролог XML-документа. Если значение установлено в True, добавляется standalone=”yes”, в противном случае оно устанавливается в “no”. Если аргумент не указан, объявление будет опущено из документа.

Изменено в версии 3.8: Метод writexml() теперь сохраняет порядок атрибутов, заданный пользователем.

Изменено в версии 3.9: Добавлен параметр standalone.

Node.toxml(encoding=None, standalone=None)

Возвращает строку или байтовую строку, содержащую XML, представленный узлом DOM.

При явном указании аргумента encoding 1 результат представляет собой байтовую строку в указанной кодировке. Если аргумент encoding не указан, результатом является строка Unicode, и XML-объявление в результирующей строке не указывает кодировку. Кодирование этой строки в кодировку, отличную от UTF-8, скорее всего, некорректно, поскольку UTF-8 является кодировкой XML по умолчанию.

Аргумент standalone ведёт себя точно так же, как в writexml().

Изменено в версии 3.8: Метод toxml() теперь сохраняет порядок атрибутов, заданный пользователем.

Изменено в версии 3.9: Добавлен параметр standalone.

Node.toprettyxml(indent="\t", newl="\n", encoding=None, standalone=None)

Возвращает версию документа с красивым форматированием. indent задаёт строку отступа, по умолчанию – символ табуляции; newl задаёт строку, добавляемую в конце каждой строки, по умолчанию \n.

Аргумент encoding ведёт себя как соответствующий аргумент toxml().

Аргумент standalone ведёт себя точно так же, как в writexml().

Изменено в версии 3.8: Метод toprettyxml() теперь сохраняет порядок атрибутов, заданный пользователем.

Изменено в версии 3.9: Добавлен параметр standalone.

Пример DOMDOM Example

Эта примерная программа – довольно реалистичный пример простой программы. В данном конкретном случае мы не используем гибкость DOM в полной мере.

import xml.dom.minidom

document = """\
<slideshow>
<title>Demo slideshow</title>
<slide><title>Slide title</title>
<point>This is a demo</point>
<point>Of a program for processing slides</point>
</slide>

<slide><title>Another demo slide</title>
<point>It is important</point>
<point>To have more than</point>
<point>one slide</point>
</slide>
</slideshow>
"""

dom = xml.dom.minidom.parseString(document)

def getText(nodelist):
    rc = []
    for node in nodelist:
        if node.nodeType == node.TEXT_NODE:
            rc.append(node.data)
    return ''.join(rc)

def handleSlideshow(slideshow):
    print("<html>")
    handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])
    slides = slideshow.getElementsByTagName("slide")
    handleToc(slides)
    handleSlides(slides)
    print("</html>")

def handleSlides(slides):
    for slide in slides:
        handleSlide(slide)

def handleSlide(slide):
    handleSlideTitle(slide.getElementsByTagName("title")[0])
    handlePoints(slide.getElementsByTagName("point"))

def handleSlideshowTitle(title):
    print("<title>%s</title>" % getText(title.childNodes))

def handleSlideTitle(title):
    print("<h2>%s</h2>" % getText(title.childNodes))

def handlePoints(points):
    print("<ul>")
    for point in points:
        handlePoint(point)
    print("</ul>")

def handlePoint(point):
    print("<li>%s</li>" % getText(point.childNodes))

def handleToc(slides):
    for slide in slides:
        title = slide.getElementsByTagName("title")[0]
        print("<p>%s</p>" % getText(title.childNodes))

handleSlideshow(dom)

minidom и стандарт DOMminidom and the DOM standard

Модуль xml.dom.minidom по сути является DOM, совместимым с DOM 1.0, с некоторыми возможностями DOM 2 (в первую очередь, поддержкой пространств имён).

Использование интерфейса DOM в Python интуитивно понятно. Применяются следующие правила отображения:

  • Интерфейсы доступны через объекты экземпляров. Приложения не должны создавать экземпляры классов напрямую – для этого следует использовать функции-создатели, доступные на объекте Document. Производные интерфейсы поддерживают все операции (и атрибуты) базовых интерфейсов, а также любые новые операции.

  • Операции используются как методы. Поскольку DOM использует только параметры in, аргументы передаются в обычном порядке (слева направо). Необязательных аргументов нет. Операции void возвращают None.

  • Атрибуты IDL отображаются в атрибуты экземпляра. Для совместимости с отображением языка OMG IDL для Python, атрибут foo также может быть доступен через методы доступа _get_foo() и _set_foo(). readonly атрибуты не должны изменяться; во время выполнения это не контролируется.

  • Типы short int, unsigned int, unsigned long long и boolean все отображаются на целочисленные объекты Python.

  • Тип DOMString отображается на строки Python. xml.dom.minidom поддерживает как байты, так и строки, но обычно возвращает строки. Значения типа DOMString также могут быть None, если по спецификации DOM от W3C допускается значение IDL null.

  • Объявления const отображаются на переменные в соответствующей области видимости (например, xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE); они не должны изменяться.

  • DOMException в настоящее время не поддерживается в xml.dom.minidom. Вместо этого xml.dom.minidom использует стандартные исключения Python, такие как TypeError и AttributeError.

  • Объекты NodeList реализованы с использованием встроенного типа list Python. Эти объекты предоставляют интерфейс, определённый в спецификации DOM, но в ранних версиях Python они не поддерживают официальный API. Однако они гораздо более «питоничны», чем интерфейс, определённый в рекомендациях W3C.

Следующие интерфейсы не имеют реализации в xml.dom.minidom:

  • DOMTimeStamp

  • EntityReference

Большинство из них отражают информацию в XML-документе, которая не представляет общей ценности для большинства пользователей DOM.

Сноски

1

Название кодировки в XML-выводе должно соответствовать соответствующим стандартам. Например, «UTF-8» допустимо, а «UTF8» недопустимо в объявлении XML-документа, хотя Python принимает её как название кодировки. См. https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl и https://www.iana.org/assignments/character-sets/character-sets.xhtml.