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 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

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