20.6. xml.dom – API объектной модели документа¶xml.dom – The Document Object Model API

20.6.2.1. Объекты DOMImplementation¶DOMImplementation Objects

Интерфейс 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.

20.6.2.2. Объекты Node¶Node Objects

Все компоненты 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¶

Узел, непосредственно предшествующий данному и имеющий того же родителя. Например, элемент, закрывающий тег которого находится непосредственно перед открывающим тегом самого элемента. Разумеется, 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 Level 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 означает клонирование всех дочерних узлов. Возвращает клон.

20.6.2.3. Объекты NodeList¶NodeList Objects

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

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

NodeList.item(i)¶

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

NodeList.length¶

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

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

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

20.6.2.4. Объекты DocumentType¶DocumentType Objects

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

20.6.2.5. Объекты Document¶Document Objects

Объект 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 пространства имён и локальным именем. Локальное имя – это часть пространства имён после префикса.

20.6.2.6. Объекты Element¶Element Objects

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, а не 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 – это полное имя атрибута. Это отличается от описанного выше.

20.6.2.7. Объекты Attr¶Attr Objects

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

Attr.name¶

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

Attr.localName¶

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

Attr.prefix¶

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

Attr.value¶

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

20.6.2.8. Объекты NamedNodeMap¶NamedNodeMap Objects

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

NamedNodeMap.length¶

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

NamedNodeMap.item(index)¶

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

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

20.6.2.9. Объекты Comment¶Comment Objects

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

Comment.data¶

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

20.6.2.10. Объекты Text и CDATASection¶Text and CDATASection Objects

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

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

Text.data¶

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

20.6.2.11. Объекты ProcessingInstruction¶ProcessingInstruction Objects

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

ProcessingInstruction.target¶

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

ProcessingInstruction.data¶

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

20.6.2.12. Исключения¶Exceptions

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

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

exception xml.dom.DOMException¶

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

exception xml.dom.DomstringSizeErr¶

Возбуждается, когда указанный диапазон текста не помещается в строку. В реализациях DOM на Python это исключение не используется, но может быть получено от реализаций 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, сопоставляются с описанными выше исключениями согласно следующей таблице:

20.6.3.1. Отображение типов¶Type Mapping

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

20.6.3.2. Методы доступа¶Accessor Methods

Отображение из 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.

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

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

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