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. Информация о документе доступна из атрибута doctype объекта 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)

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

Document.createTextNode(data)

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

Document.createComment(data)

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

Document.createProcessingInstruction(target, data)

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

Document.createAttribute(name)

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

Document.createAttributeNS(namespaceURI, qualifiedName)

Создаёт и возвращает узел атрибута с пространством имён. Имя атрибута tagName может содержать префикс. Этот метод не связывает узел атрибута с каким-либо конкретным элементом. Вам необходимо использовать 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)

Удаляет атрибут по имени. Обратите внимание, что используется 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. «Сеттеры» никогда не должны предоставляться для атрибутов readonly.

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