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 для документа доступен из атрибута 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)

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

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 уровня 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

Если делается попытка изменить любой объект способом, не разрешенным рекомендацией Namespaces in 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 не требует от реализаций соблюдения таких требований.