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

Объекты доминирующей реализации¶

Интерфейс 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. В Python DOM API первые два аргумента также могут быть 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¶

NamedNodeMap объектов-атрибутов. Только элементы имеют фактические значения для этого атрибута; другие элементы предоставляют 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, которые используют любую архитектуру прокси-сервера (поскольку на один и тот же узел может ссылаться более одного объекта).

Примечание

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

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 также означает клонирование всех дочерних узлов. Это возвращает значение clone.

Объекты списка узлов¶

NodeList представляет собой последовательность узлов. В основной рекомендации DOM эти объекты используются двумя способами: объект 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 для документа доступен из атрибута Document объекта doctype; если для документа нет объявления 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 представляет собой полный XML-документ, включая его составные элементы, атрибуты, инструкции по обработке, комментарии и т.д. Помните, что он наследует свойства от Node.

Document.documentElement¶

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

Document.createElement(tagName)¶

Создайте и верните новый элемент node. Элемент не вставляется в документ при его создании. Вам необходимо явно вставить его с помощью одного из других методов, таких как 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 пространства имен и localname. Локальное имя - это часть пространства имен после префикса.

Объекты элементов¶

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

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

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 представляет собой комментарий в XML-документе. Это подкласс Node, но у него не может быть дочерних узлов.

Comment.data¶

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

Объекты Text и CDATASection¶

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

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

Text.data¶

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

Обработка объектов инфраструктуры¶

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

ProcessingInstruction.target¶

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

ProcessingInstruction.data¶

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

Исключения¶

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

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

exception xml.dom.DOMException¶

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

exception xml.dom.DomstringSizeErr¶

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

exception xml.dom.HierarchyRequestErr¶

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

exception xml.dom.IndexSizeErr¶

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

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 требует, чтобы работал обычный доступ к атрибутам. Это означает, что типичные заменители, генерируемые компиляторами IDL на Python, вряд ли будут работать, и клиенту могут потребоваться объекты-оболочки, если доступ к объектам DOM осуществляется через CORBA. Хотя для клиентов CORBA DOM это требует некоторого дополнительного рассмотрения, разработчики, имеющие опыт использования DOM поверх CORBA из Python, не считают это проблемой. Атрибуты, которые объявлены readonly, могут не ограничивать доступ на запись во всех реализациях DOM.

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

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