xml.dom — API модели объекта документа

Объекты DOMImplementation

Интерфейс DOMImplementation предоставляет приложениям способ определить наличие определенных функций в используемом DOM. DOM Level 2 добавил возможность создавать новые объекты Document и DocumentType с использованием DOMImplementation тоже.

DOMImplementation.hasFeature(feature, version)

Возвращает True, если функция, определённая парой строк feature и version, реализована.

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

Возвращает новый объект Document (корень DOM) с дочерним объектом Element, имеющим заданный namespaceUri и qualifiedName. doctype должен быть объектом DocumentType , созданным функцией createDocumentType(), или None. В API Python DOM первые два аргумента также могут быть None для указания, что дочерний объект Element создавать не нужно.

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

Возвращает новый объект DocumentType, который описывает предоставленные строки qualifiedName, publicId и systemId, представляющие информацию, содержащуюся в декларации типа XML-документа.

Объекты узлов

Все компоненты XML-документа являются подклассами Node.

Node.nodeType

Целое число, представляющее тип узла. Символьные константы для типов находятся в объекте Node: ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, ENTITY_NODE, PROCESSING_INSTRUCTION_NODE, COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE. Это атрибут только для чтения.

Node.parentNode

Родитель текущего узла или None для узла документа. Значение всегда является объектом Node или None. Для узлов Element, это будет родительский элемент, за исключением корневого элемента, в котором случае это будет объект Document. Для узлов Attr это всегда None. Это атрибут только для чтения.

Node.attributes

Список объектов атрибутов. Только у элементов есть фактические значения для этого; другие предоставляют None для этого атрибута. Это атрибут только для чтения.

Node.previousSibling

Узел, непосредственно предшествующий данному узлу с тем же родителем. Например, элемент с закрывающим тегом, который находится непосредственно перед открывающим тегом элемента self. Конечно, XML-документы состоят из большего, чем просто элементов, поэтому предыдущий брат может быть текстом, комментарием или чем-то другим. Если этот узел является первым дочерним узлом родителя, этот атрибут будет None. Это атрибут только для чтения.

Node.nextSibling

Узел, непосредственно следующий за данным узлом с тем же родителем. См. также previousSibling. Если это последний дочерний узел родителя, этот атрибут будет None. Это атрибут только для чтения.

Node.childNodes

Список узлов, содержащихся в этом узле. Это атрибут только для чтения.

Node.firstChild

Первый дочерний узел узла, если таковые имеются, или None. Это атрибут только для чтения.

Node.lastChild

Последний дочерний узел узла, если таковые имеются, или None. Это атрибут только для чтения.

Node.localName

Часть tagName после двоеточия, если она есть, в противном случае весь tagName. Значение является строкой.

Node.prefix

Часть tagName перед двоеточием, если она есть, в противном случае пустая строка. Значение — строка или None.

Node.namespaceURI

Пространство имен, связанное с именем элемента. Будет строкой или None. Это атрибут только для чтения.

Node.nodeName

Это имеет разное значение для каждого типа узла; см. спецификацию DOM для получения подробностей. Вы всегда можете получить информацию, которую вы получите здесь, из другого свойства, например, из свойства tagName для элементов или свойства name для атрибутов. Для всех типов узлов значение этого атрибута будет строкой или None. Это атрибут только для чтения.

Node.nodeValue

Это имеет разное значение для каждого типа узла; см. спецификацию DOM для получения подробностей. Ситуация аналогична ситуации с nodeName. Значение является строкой или None.

Node.hasAttributes()

Возвращает True, если у узла есть атрибуты.

Node.hasChildNodes()

Возвращает True, если у узла есть дочерние узлы.

Node.isSameNode(other)

Возвращает True, если other ссылается на тот же узел, что и этот узел. Это особенно полезно для реализаций DOM, которые используют любую форму прокси-архитектуры (поскольку более одного объекта может ссылаться на один и тот же узел).

Примечание

Это основано на предлагаемом API DOM уровня 3, который все еще находится на стадии «рабочего проекта», но этот конкретный интерфейс, похоже, не вызывает споров. Изменения со стороны W3C не обязательно повлияют на этот метод в интерфейсе Python DOM (хотя любой новый API W3C для этого также будет поддерживаться).

Node.appendChild(newChild)

Добавляет новый дочерний узел к этому узлу в конец списка дочерних узлов, возвращая newChild. Если узел уже находился в дереве, он удаляется сначала.

Node.insertBefore(newChild, refChild)

Вставить новый дочерний узел перед существующим дочерним узлом. Необходимо, чтобы refChild был дочерним узлом этого узла; в противном случае возникает ValueError. Возвращается newChild. Если refChild равен None, он вставляет newChild в конец списка дочерних узлов.

Node.removeChild(oldChild)

Удалить дочерний узел. oldChild должен быть дочерним узлом этого узла; в противном случае возникает ValueError. oldChild возвращается при успехе. Если oldChild больше не будет использоваться, для него следует вызвать метод unlink().

Node.replaceChild(newChild, oldChild)

Заменить существующий узел новым узлом. Необходимо, чтобы oldChild был дочерним узлом этого узла; в противном случае возникает ValueError.

Node.normalize()

Объединить смежные текстовые узлы, чтобы все участки текста хранились как отдельные экземпляры Text. Это упрощает обработку текста из дерева DOM для многих приложений.

Node.cloneNode(deep)

Клонировать этот узел. Установка deep означает клонирование всех дочерних узлов тоже. Возвращает клон.

Объекты NodeList

NodeList представляет собой последовательность узлов. Эти объекты используются двумя способами в рекомендации DOM Core: объект Element предоставляет его как список дочерних узлов, и методы getElementsByTagName() и getElementsByTagNameNS() объекта Node возвращают объекты с этим интерфейсом для представления результатов запроса.

Рекомендация DOM уровня 2 определяет один метод и один атрибут для этих объектов:

NodeList.item(i)

Возвращает i-й элемент из последовательности, если он есть, или None. Индекс i не может быть меньше нуля или больше или равен длине последовательности.

NodeList.length

Количество узлов в последовательности.

Кроме того, интерфейс Python DOM требует, чтобы была предоставлена дополнительная поддержка, позволяющая использовать объекты NodeList в качестве последовательностей Python. Все реализации NodeList должны включать поддержку __len__() и __getitem__(); это позволяет итерировать по NodeList в операторах for и надлежащую поддержку встроенной функции len().

Если реализация DOM поддерживает модификацию документа, реализация NodeList также должна поддерживать методы __setitem__() и __delitem__().

Объекты DocumentType

Информация о обозначениях и сущностях, объявленных документом (включая внешний подмножество, если парсер использует его и может предоставить информацию), доступна из объекта DocumentType. Объект DocumentType для документа доступен из атрибута Document объекта; если для документа нет объявления DOCTYPE, атрибут doctype документа будет установлен в None вместо экземпляра этого интерфейса.

DocumentType является специализацией Node, и добавляет следующие атрибуты:

DocumentType.publicId

Общедоступный идентификатор внешнего подмножества определения типа документа. Это будет строка или None.

DocumentType.systemId

Системный идентификатор внешнего подмножества определения типа документа. Это будет URI в виде строки или None.

DocumentType.internalSubset

Строка, содержащая полное внутреннее подмножество из документа. Она не включает скобки, которые обрамляют подмножество. Если в документе нет внутреннего подмножества, это должно быть None.

DocumentType.name

Имя корневого элемента, как указано в объявлении DOCTYPE, если оно присутствует.

DocumentType.entities

Это NamedNodeMap, содержащий определения внешних сущностей. Для имен сущностей, определенных более одного раза, предоставляется только первое определение (другие игнорируются в соответствии с рекомендациями XML). Это может быть None, если информация не предоставлена парсером или если сущности не определены.

DocumentType.notations

Это NamedNodeMap список определений обозначений. Для имён обозначений, определенных более одного раза, предоставляется только первое определение (другие игнорируются в соответствии с рекомендациями XML). Это может быть None, если информация не предоставлена парсером или если обозначения не определены.

Объекты Document

Объект Document представляет собой весь XML-документ, включая составляющие элементы, атрибуты, инструкции обработки, комментарии и т. д. Помните, что он наследует свойства от Node.

Document.documentElement

Единственный корневой элемент документа.

Document.createElement(tagName)

Создаёт и возвращает новый узел элемента. Элемент не вставляется в документ при создании. Вам нужно явно вставить его с помощью одного из других методов, таких как insertBefore() или appendChild().

Document.createElementNS(namespaceURI, tagName)

Создаёт и возвращает новый элемент с пространством имён. Имя_тега может иметь префикс. Элемент не вставляется в документ при создании. Вам нужно явно вставить его с помощью одного из других методов, таких как insertBefore() или appendChild().

Document.createTextNode(data)

Создаёт и возвращает текстовый узел, содержащий переданные данные в качестве параметра. Как и другие методы создания, этот метод не вставляет узел в дерево.

Document.createComment(data)

Создаёт и возвращает узел комментария, содержащий переданные данные в качестве параметра. Как и другие методы создания, этот метод не вставляет узел в дерево.

Document.createProcessingInstruction(target, data)

Создаёт и возвращает узел инструкции обработки, содержащий цель и данные, переданные в качестве параметров. Как и другие методы создания, этот метод не вставляет узел в дерево.

Document.createAttribute(name)

Создаёт и возвращает узел атрибута. Этот метод не связывает узел атрибута с каким-либо конкретным элементом. Вам необходимо использовать setAttributeNode() на соответствующем объекте Element для использования вновь созданного экземпляра атрибута.

Document.createAttributeNS(namespaceURI, qualifiedName)

Создаёт и возвращает узел атрибута с пространством имён. Имя_тега может иметь префикс. Этот метод не связывает узел атрибута с каким-либо конкретным элементом. Вам необходимо использовать setAttributeNode() на соответствующем объекте Element для использования вновь созданного экземпляра атрибута.

Document.getElementsByTagName(tagName)

Ищет всех потомков (прямых детей, детей детей и т.д.) с определённым именем типа элемента.

Document.getElementsByTagNameNS(namespaceURI, localName)

Ищет всех потомков (прямых детей, детей детей и т.д.) с определённым URI пространства имён и локальным именем. Локальное имя — часть имени пространства имён после префикса.

Объекты Element

Element является подклассом Node, поэтому наследует все атрибуты этого класса.

Element.tagName

Имя типа элемента. В документе, использующем пространства имён, оно может содержать двоеточия. Значение — строка.

Element.getElementsByTagName(tagName)

То же, что и эквивалентный метод в классе Document.

Element.getElementsByTagNameNS(namespaceURI, localName)

То же, что и эквивалентный метод в классе Document.

Element.hasAttribute(name)

Возвращает True, если у элемента есть атрибут с именем name.

Element.hasAttributeNS(namespaceURI, localName)

Возвращает True, если у элемента есть атрибут с именем namespaceURI и localName.

Element.getAttribute(name)

Возвращает значение атрибута с именем name в виде строки. Если такого атрибута нет, возвращается пустая строка, как если бы атрибут не имел значения.

Element.getAttributeNode(attrname)

Возвращает узел Attr атрибута с именем attrname.

Element.getAttributeNS(namespaceURI, localName)

Возвращает значение атрибута с именем namespaceURI и localName в виде строки. Если такого атрибута нет, возвращается пустая строка, как если бы атрибут не имел значения.

Element.getAttributeNodeNS(namespaceURI, localName)

Возвращает значение атрибута в виде узла, заданного namespaceURI и localName.

Element.removeAttribute(name)

Удаляет атрибут по имени. Если соответствующего атрибута нет, поднимается исключение NotFoundErr.

Element.removeAttributeNode(oldAttr)

Удаляет и возвращает oldAttr из списка атрибутов, если он присутствует. Если oldAttr отсутствует, поднимается исключение NotFoundErr.

Element.removeAttributeNS(namespaceURI, localName)

Удаляет атрибут по имени. Обратите внимание, что используется локальное имя, а не полное имя. Если соответствующего атрибута нет, исключение не поднимается.

Element.setAttribute(name, value)

Устанавливает значение атрибута из строки.

Element.setAttributeNode(newAttr)

Добавляет новый узел атрибута к элементу, заменяя существующий атрибут, если необходимо, если атрибут name совпадает. Если произошла замена, возвращается старый узел атрибута. Если newAttr уже используется, будет поднято исключение InuseAttributeErr.

Element.setAttributeNodeNS(newAttr)

Добавляет новый узел атрибута к элементу, заменяя существующий атрибут, если необходимо, если атрибуты namespaceURI и localName совпадают. Если произошла замена, возвращается старый узел атрибута. Если newAttr уже используется, будет поднято исключение InuseAttributeErr.

Element.setAttributeNS(namespaceURI, qname, value)

Устанавливает значение атрибута из строки, задав namespaceURI и qname. Обратите внимание, что qname — это полное имя атрибута. Это отличается от предыдущего.

Объекты Attr

Attr наследуется от Node, поэтому наследует все его атрибуты.

Attr.name

Имя атрибута. В документе с именованными пространствами имён оно может содержать двоеточие.

Attr.localName

Часть имени, следующая за двоеточием, если оно есть, иначе всё имя. Это атрибут только для чтения.

Attr.prefix

Часть имени, предшествующая двоеточию, если оно есть, иначе пустая строка.

Attr.value

Текстовое значение атрибута. Это синоним для атрибута nodeValue.

Объекты NamedNodeMap

NamedNodeMap не наследуется от Node.

NamedNodeMap.length

Длина списка атрибутов.

NamedNodeMap.item(index)

Возвращает атрибут с заданным индексом. Порядок получения атрибутов произвольный, но будет постоянным на протяжении всего жизненного цикла DOM. Каждый элемент — это узел атрибута. Получите его значение с помощью атрибута value.

Также есть экспериментальные методы, которые предоставляют этому классу больше возможностей по работе со словарями. Вы можете использовать их или использовать стандартный набор методов getAttribute*() для объектов Element.

Объекты Comment

Comment представляет собой комментарий в документе XML. Это подкласс Node, но не может иметь дочерние узлы.

Comment.data

Содержимое комментария в виде строки. Атрибут содержит все символы между ведущим <!-- и заключительным -->, но не включает их.

Объекты Text и CDATASection

Интерфейс Text представляет текст в документе XML. Если парсер и реализация DOM поддерживают расширение DOM для XML, части текста, заключённые в секции с обозначением CDATA, хранятся в объектах CDATASection. Эти два интерфейса идентичны, но предоставляют разные значения для атрибута nodeType.

Эти интерфейсы расширяют интерфейс Node. Они не могут иметь дочерних узлов.

Text.data

Содержимое узла текста в виде строки.

Объекты ProcessingInstruction

Представляет инструкцию обработки в документе XML; это наследуется от интерфейса Node и не может иметь дочерних узлов.

ProcessingInstruction.target

Содержимое инструкции обработки до первого пробела. Это атрибут только для чтения.

ProcessingInstruction.data

Содержимое инструкции обработки после первого пробела.

Исключения

Рекомендация DOM Level 2 определяет одно исключение, DOMException, и ряд констант, которые позволяют приложениям определить тип ошибки. DOMException экземпляры содержат атрибут code, предоставляющий соответствующее значение для конкретного исключения.

Интерфейс Python DOM предоставляет константы, но также расширяет набор исключений, так что для каждого кода исключения, определенного DOM, существует отдельное исключение. Реализации должны поднимать соответствующее специфическое исключение, каждое из которых содержит соответствующее значение для атрибута code.

exception xml.dom.DOMException

Базовый класс исключений, используемый для всех специфических исключений DOM. Этот класс исключений нельзя создавать напрямую.

exception xml.dom.DomstringSizeErr

Вызывается, когда указанный диапазон текста не помещается в строку. Известно, что это не используется в реализациях Python DOM, но может быть получено от реализаций DOM, написанных не на Python.

exception xml.dom.HierarchyRequestErr

Вызывается при попытке вставить узел, где тип узла недопустим.

exception xml.dom.IndexSizeErr

Вызывается, когда индекс или параметр размера метода отрицателен или превышает допустимые значения.

exception xml.dom.InuseAttributeErr

Вызывается при попытке вставить узел Attr, который уже присутствует в другом месте документа.

exception xml.dom.InvalidAccessErr

Вызывается, если параметр или операция не поддерживаются базовым объектом.

exception xml.dom.InvalidCharacterErr

Это исключение возникает, когда строковый параметр содержит символ, который не разрешен в контексте, в котором он используется, согласно рекомендации XML 1.0. Например, попытка создания узла Element с пробелом в имени элемента типа вызовет эту ошибку.

exception xml.dom.InvalidModificationErr

Вызывается при попытке изменить тип узла.

exception xml.dom.InvalidStateErr

Вызывается при попытке использовать объект, который не определен или больше недоступен.

exception xml.dom.NamespaceErr

Если предпринимается попытка изменить любой объект способом, который не разрешен в соответствии с рекомендацией Пространства имен в XML, возникает это исключение.

exception xml.dom.NotFoundErr

Исключение, когда узел не существует в указанном контексте. Например, NamedNodeMap.removeNamedItem() вызовет это исключение, если переданный узел не существует в карте.

exception xml.dom.NotSupportedErr

Вызывается, когда реализация не поддерживает запрашиваемый тип объекта или операции.

exception xml.dom.NoDataAllowedErr

Это исключение возникает, если для узла указаны данные, которые он не поддерживает.

exception xml.dom.NoModificationAllowedErr

Возникает при попытках модифицировать объект, где модификации не разрешены (например, для узлов только для чтения).

exception xml.dom.SyntaxErr

Вызывается, когда указана недопустимая или некорректная строка.

exception xml.dom.WrongDocumentErr

Вызывается, когда узел вставляется в другой документ, чем тот, к которому он в данный момент принадлежит, и реализация не поддерживает перемещение узла из одного документа в другой.

Коды исключений, определенные в рекомендации DOM, соответствуют описанным выше исключениям в соответствии со следующей таблицей:

Сопоставление типов

Типы IDL, используемые в спецификации DOM, сопоставляются с типами Python в соответствии со следующей таблицей.

Методы-акцессоры

Сопоставление из OMG IDL в Python определяет функции-акцессоры для IDL attribute объявлений примерно так же, как и в Java-отображении. Сопоставление IDL-объявлений

readonly attribute string someValue;
         attribute string anotherValue;

дает три функции-акцессора: метод «get» для someValue (_get_someValue()), и методы «get» и «set» для anotherValue (_get_anotherValue() и _set_anotherValue()). Сопоставление, в частности, не требует, чтобы атрибуты IDL были доступны как обычные атрибуты Python: object.someValue не требуется для работы, и может вызвать AttributeError.

Однако API Python DOM требует, чтобы работала обычная работа с атрибутами. Это означает, что типичные суррогаты, сгенерированные компиляторами Python IDL, вряд ли будут работать, и могут потребоваться обёртки объектов на клиенте, если объекты DOM доступны через CORBA. Хотя это требует некоторого дополнительного рассмотрения для клиентов CORBA DOM, разработчики с опытом использования DOM через CORBA из Python не считают это проблемой. Атрибуты, объявленные readonly, могут не ограничивать доступ к записи во всех реализациях DOM.

В API Python DOM функции-акцессоры не требуются. Если они предоставлены, они должны иметь форму, определенную сопоставлением Python IDL, но эти методы считаются излишними, так как к атрибутам можно напрямую обратиться из Python. Функции-акцессоры «set» никогда не должны предоставляться для атрибутов readonly.

IDL-определения не полностью отражают требования API W3C DOM, такие как понятие о некоторых объектах, таких как возвращаемое значение getElementsByTagName(), являющихся «живыми». API Python DOM не требует от реализаций принудительного соблюдения таких требований.