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

Примечание

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

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

Объект 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__().

Объекты типа документа¶

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

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

Document.createElementNS(namespaceURI, tagName)¶

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

Document.createTextNode(data)¶

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

Document.createComment(data)¶

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

Document.createProcessingInstruction(target, data)¶

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

Document.createAttribute(name)¶

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

Document.createAttributeNS(namespaceURI, qualifiedName)¶

Создает и возвращает узел атрибута с пространством имен. Имя tagName может иметь префикс. Этот метод не связывает узел атрибута с каким-либо конкретным элементом. Вы должны использовать setAttributeNode() на соответствующем объекте Element, чтобы использовать вновь созданный экземпляр атрибута.

Document.getElementsByTagName(tagName)¶

Поиск всех потомков (прямых детей, детей детей и т.д.) с определенным именем типа элемента.

Document.getElementsByTagNameNS(namespaceURI, localName)¶

Поиск всех потомков (прямых детей, детей детей и т.д.) с определенным URI пространства имен и локальным именем. Локальное имя - это часть пространства имен после префикса.

Элементы-объекты¶

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

Объекты 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¶

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

Текст и объекты CDATASection¶

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

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

Text.data¶

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

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

Представляет инструкцию обработки в документе 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¶

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

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

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

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