`xml.dom.md`

571 строк · 53.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/library/xml.dom.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 19.8. [`xml.dom`](https://python-all.ru/2.7/library/xml.dom.html#module-xml.dom) – API объектной модели документа89Новое в версии 2.0.1011Объектная модель документа (DOM) – это независимый от языка программирования API, разработанный Консорциумом Всемирной паутины (W3C) для доступа к XML-документам и их изменения. Реализация DOM представляет XML-документ в виде древовидной структуры или позволяет клиентскому коду создать такую структуру с нуля. Затем она предоставляет доступ к структуре через набор объектов, которые предоставляют хорошо известные интерфейсы.1213DOM чрезвычайно полезен для приложений с произвольным доступом. SAX позволяет видеть только один фрагмент документа за раз. Если рассматривается один элемент SAX, доступ к другому отсутствует. Если рассматривается текстовый узел, отсутствует доступ к содержащему его элементу. При написании приложения SAX необходимо отслеживать положение программы в документе в собственном коде – SAX не делает этого автоматически. Кроме того, если требуется заглянуть вперед в XML-документе, это просто невозможно.1415Некоторые приложения просто невозможны в событийно-ориентированной модели без доступа к дереву. Конечно, можно построить некоторое подобие дерева самостоятельно, обрабатывая события SAX, но DOM позволяет избежать написания такого кода. DOM – это стандартное древовидное представление XML-данных.1617Объектная модель документа (DOM) определяется W3C поэтапно, или, в их терминологии, по «уровням». Представление API в Python в значительной степени основано на рекомендации DOM уровня 2.1819Приложения DOM обычно начинают с разбора некоторого XML-документа в DOM. Как это делается, совершенно не описывается в DOM уровня 1, а уровень 2 предоставляет лишь ограниченные улучшения: существует класс объектов `DOMImplementation`, который предоставляет доступ к методам создания `Document`, но нет способа получить доступ к средству чтения/парсера/построителя Document независимо от реализации. Кроме того, нет четко определенного способа доступа к этим методам без существующего объекта `Document`. В Python каждая реализация DOM предоставляет функцию [`getDOMImplementation()`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.getDOMImplementation). DOM уровня 3 добавляет спецификацию Load/Store, которая определяет интерфейс к средству чтения, но она пока недоступна в стандартной библиотеке Python.2021После получения объекта DOM-документа можно получить доступ к частям XML-документа через его свойства и методы. Эти свойства определены в спецификации DOM; данная часть справочного руководства описывает интерпретацию спецификации в Python.2223Спецификация, предоставленная W3C, определяет DOM API для Java, ECMAScript и OMG IDL. Представленное здесь отображение на Python в значительной степени основано на IDL-версии спецификации, однако строгое соответствие не требуется (хотя реализации могут поддерживать строгое отображение из IDL). См. раздел [Соответствие](https://python-all.ru/2.7/library/xml.dom.html#dom-conformance) для подробного обсуждения требований к отображению.2425> **См. также**26>27> **[Спецификация объектной модели документа (DOM) уровня 2](https://python-all.ru/2.7/library/xml.dom.html)**28>29> Рекомендация W3C, на которой основан Python DOM API.30>31> **[Спецификация объектной модели документа (DOM) уровня 1](https://python-all.ru/2.7/library/xml.dom.html)**32>33> Рекомендация W3C для DOM, поддерживаемая [`xml.dom.minidom`](https://python-all.ru/2.7/library/xml.dom.minidom.html#module-xml.dom.minidom).34>35> **[Спецификация отображения языка Python](https://python-all.ru/2.7/library/xml.dom.html)**36>37> Она определяет отображение из OMG IDL на Python.3839## 19.8.1. Содержание модуля4041[`xml.dom`](https://python-all.ru/2.7/library/xml.dom.html#module-xml.dom) содержит следующие функции:4243#### `xml.dom.registerDOMImplementation(name, factory)`4445Регистрирует функцию *factory* с именем *name*. Функция-фабрика должна возвращать объект, реализующий интерфейс `DOMImplementation`. Функция-фабрика может возвращать один и тот же объект каждый раз или новый при каждом вызове, в зависимости от конкретной реализации (например, если эта реализация поддерживает некоторую настройку).4647#### `xml.dom.getDOMImplementation([name[, features]])`4849Возвращает подходящую реализацию DOM. *name* может быть широко известным именем, именем модуля реализации DOM или `None`. Если он не равен `None`, импортируется соответствующий модуль и возвращается объект `DOMImplementation`, если импорт успешен. Если имя не задано и установлена переменная окружения `PYTHON_DOM`, эта переменная используется для поиска реализации.5051Если имя не задано, функция проверяет доступные реализации, чтобы найти одну с требуемым набором возможностей. Если ни одна реализация не найдена, возбуждается исключение [`ImportError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ImportError). Список возможностей (features) должен быть последовательностью пар `(feature, version)`, которые передаются методу `hasFeature()` доступных объектов `DOMImplementation`.5253Также предоставляются некоторые вспомогательные константы:5455#### `xml.dom.EMPTY_NAMESPACE`5657Значение, используемое для указания того, что с узлом в DOM не связано ни одного пространства имен. Обычно встречается как `namespaceURI` узла или используется в качестве параметра *namespaceURI* в методах, работающих с пространствами имен.5859Новое в версии 2.2.6061#### `xml.dom.XML_NAMESPACE`6263URI пространства имен, связанный с зарезервированным префиксом `xml`, как определено в документе [Пространства имен в XML](https://python-all.ru/2.7/library/xml.dom.html) (раздел 4).6465Новое в версии 2.2.6667#### `xml.dom.XMLNS_NAMESPACE`6869URI пространства имен для объявлений пространств имен, как определено в спецификации [Объектной модели документа (DOM) уровня 2, базовая часть](https://python-all.ru/2.7/library/xml.dom.html) (раздел 1.1.8).7071Новое в версии 2.2.7273#### `xml.dom.XHTML_NAMESPACE`7475URI пространства имен XHTML, как определено в спецификации [XHTML 1.0: Расширяемый язык гипертекстовой разметки](https://python-all.ru/2.7/library/xml.dom.html) (раздел 3.1.1).7677Новое в версии 2.2.7879Кроме того, [`xml.dom`](https://python-all.ru/2.7/library/xml.dom.html#module-xml.dom) содержит базовый класс `Node` и классы исключений DOM. Класс `Node`, предоставляемый этим модулем, не реализует ни одного метода или атрибута, определенного спецификацией DOM; конкретные реализации DOM должны их предоставлять. Класс `Node`, предоставляемый как часть этого модуля, содержит константы, используемые для атрибута `nodeType` в конкретных объектах `Node`; они находятся внутри класса, а не на уровне модуля, чтобы соответствовать спецификациям DOM.8081## 19.8.2. Объекты в DOM8283Исчерпывающая документация по DOM – это спецификация DOM от W3C.8485Обратите внимание, что атрибуты DOM также могут обрабатываться как узлы, а не как простые строки. Однако это требуется довольно редко, поэтому данное использование ещё не задокументировано.8687| Интерфейс | Раздел | Назначение |88| --- | --- | --- |89| `DOMImplementation` | [Объекты DOMImplementation](https://python-all.ru/2.7/library/xml.dom.html#dom-implementation-objects) | Интерфейс для доступа к базовой реализации. |90| `Node` | [Объекты Node](https://python-all.ru/2.7/library/xml.dom.html#dom-node-objects) | Базовый интерфейс для большинства объектов в документе. |91| `NodeList` | [Объекты NodeList](https://python-all.ru/2.7/library/xml.dom.html#dom-nodelist-objects) | Интерфейс для последовательности узлов. |92| `DocumentType` | [Объекты DocumentType](https://python-all.ru/2.7/library/xml.dom.html#dom-documenttype-objects) | Информация об объявлениях, необходимых для обработки документа. |93| `Document` | [Объекты Document](https://python-all.ru/2.7/library/xml.dom.html#dom-document-objects) | Объект, представляющий весь документ. |94| `Element` | [Объекты Element](https://python-all.ru/2.7/library/xml.dom.html#dom-element-objects) | Узлы элементов в иерархии документа. |95| `Attr` | [Объекты Attr](https://python-all.ru/2.7/library/xml.dom.html#dom-attr-objects) | Узлы значений атрибутов на узлах элементов. |96| `Comment` | [Объекты Comment](https://python-all.ru/2.7/library/xml.dom.html#dom-comment-objects) | Представление комментариев в исходном документе. |97| `Text` | [Объекты Text и CDATASection](https://python-all.ru/2.7/library/xml.dom.html#dom-text-objects) | Узлы, содержащие текстовое содержимое документа. |98| `ProcessingInstruction` | [Объекты ProcessingInstruction](https://python-all.ru/2.7/library/xml.dom.html#dom-pi-objects) | Представление инструкций по обработке. |99100Дополнительный раздел описывает исключения, определённые для работы с DOM в Python.101102### 19.8.2.1. Объекты DOMImplementation103104Интерфейс `DOMImplementation` предоставляет приложениям возможность определять доступность определённых функций в используемом DOM. В DOM Level 2 также была добавлена возможность создавать новые объекты `Document` и `DocumentType` с помощью `DOMImplementation`.105106#### `DOMImplementation.hasFeature(feature, version)`107108Возвращает True, если возможность, заданная парой строк *feature* и *version*, реализована.109110#### `DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)`111112Возвращает новый объект `Document` (корень DOM) с дочерним объектом `Element`, имеющим указанные *namespaceUri* и *qualifiedName*. *doctype* должен быть объектом `DocumentType`, созданным с помощью [`createDocumentType()`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.DOMImplementation.createDocumentType), или `None`. В Python DOM API первые два аргумента также могут быть `None`, чтобы указать, что дочерний элемент `Element` не должен создаваться.113114#### `DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)`115116Возвращает новый объект `DocumentType`, инкапсулирующий заданные строки *qualifiedName*, *publicId* и *systemId*, представляющие информацию, содержащуюся в объявлении типа документа XML.117118### 19.8.2.2. Объекты Node119120Все компоненты XML-документа являются подклассами `Node`.121122#### `Node.nodeType`123124Целое число, представляющее тип узла. Символические константы для типов находятся в объекте `Node`: `ELEMENT_NODE`, `ATTRIBUTE_NODE`, `TEXT_NODE`, `CDATA_SECTION_NODE`, `ENTITY_NODE`, `PROCESSING_INSTRUCTION_NODE`, `COMMENT_NODE`, `DOCUMENT_NODE`, `DOCUMENT_TYPE_NODE`, `NOTATION_NODE`. Это атрибут только для чтения.125126#### `Node.parentNode`127128Родитель текущего узла или `None` для узла документа. Значение всегда является объектом `Node` или `None`. Для узлов `Element` это будет родительский элемент, за исключением корневого элемента, в этом случае это будет объект `Document`. Для узлов `Attr` это всегда `None`. Это атрибут только для чтения.129130#### `Node.attributes`131132`NamedNodeMap` объектов атрибутов. Только элементы имеют актуальные значения для этого; остальные предоставляют `None` для этого атрибута. Это атрибут только для чтения.133134#### `Node.previousSibling`135136Узел, непосредственно предшествующий данному и имеющий того же родителя. Например, элемент, закрывающий тег которого находится непосредственно перед открывающим тегом *самого* элемента. Разумеется, XML-документы состоят не только из элементов, поэтому предыдущим соседом может быть текст, комментарий или что-то ещё. Если этот узел является первым потомком родителя, этот атрибут будет равен `None`. Это атрибут только для чтения.137138#### `Node.nextSibling`139140Узел, непосредственно следующий за данным и имеющий того же родителя. См. также [`previousSibling`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.Node.previousSibling). Если это последний потомок родителя, этот атрибут будет равен `None`. Это атрибут только для чтения.141142#### `Node.childNodes`143144Список узлов, содержащихся в данном узле. Это атрибут только для чтения.145146#### `Node.firstChild`147148Первый потомок узла, если таковой имеется, или `None`. Это атрибут только для чтения.149150#### `Node.lastChild`151152Последний потомок узла, если таковой имеется, или `None`. Это атрибут только для чтения.153154#### `Node.localName`155156Часть `tagName`, следующая за двоеточием, если оно есть, иначе вся `tagName`. Значение – строка.157158#### `Node.prefix`159160Часть `tagName`, предшествующая двоеточию, если оно есть, иначе пустая строка. Значение – строка или `None`.161162#### `Node.namespaceURI`163164Пространство имён, связанное с именем элемента. Это будет строка или `None`. Это атрибут только для чтения.165166#### `Node.nodeName`167168Значение этого атрибута различается для каждого типа узла; подробности см. в спецификации DOM. Ту же информацию всегда можно получить из другого свойства, например, из свойства `tagName` для элементов или свойства `name` для атрибутов. Для всех типов узлов значение этого атрибута будет строкой или `None`. Это атрибут только для чтения.169170#### `Node.nodeValue`171172Значение этого атрибута различается для каждого типа узла; подробности см. в спецификации DOM. Ситуация аналогична [`nodeName`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.Node.nodeName). Значение – строка или `None`.173174#### `Node.hasAttributes()`175176Возвращает True, если у узла есть атрибуты.177178#### `Node.hasChildNodes()`179180Возвращает True, если у узла есть дочерние узлы.181182#### `Node.isSameNode(other)`183184Возвращает True, если *other* ссылается на тот же узел, что и данный узел. Это особенно полезно для реализаций DOM, использующих какую-либо прокси-архитектуру (поскольку несколько объектов могут ссылаться на один и тот же узел).185186> **Примечание**187>188> Это основано на предложенном API DOM Level 3, который всё ещё находится на стадии «рабочего черновика», но данный конкретный интерфейс выглядит не вызывающим споров. Изменения со стороны W3C не обязательно повлияют на этот метод в Python DOM интерфейсе (хотя любые новые API W3C для этого также будут поддерживаться).189190#### `Node.appendChild(newChild)`191192Добавляет новый дочерний узел в конец списка дочерних узлов данного узла, возвращая *newChild*. Если узел уже находился в дереве, он сначала удаляется.193194#### `Node.insertBefore(newChild, refChild)`195196Вставляет новый дочерний узел перед существующим потомком. Требуется, чтобы *refChild* был потомком данного узла; в противном случае возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Возвращается *newChild*. Если *refChild* равен `None`, то *newChild* вставляется в конец списка потомков.197198#### `Node.removeChild(oldChild)`199200Удаляет дочерний узел. *oldChild* должен быть потомком данного узла; в противном случае возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). В случае успеха возвращается *oldChild*. Если *oldChild* не будет использоваться в дальнейшем, следует вызвать его метод `unlink()`.201202#### `Node.replaceChild(newChild, oldChild)`203204Заменяет существующий узел новым узлом. Требуется, чтобы *oldChild* был потомком данного узла; в противном случае возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).205206#### `Node.normalize()`207208Объединяет соседние текстовые узлы так, чтобы все отрезки текста хранились в виде одиночных экземпляров `Text`. Это упрощает обработку текста из DOM-дерева для многих приложений.209210Новое в версии 2.1.211212#### `Node.cloneNode(deep)`213214Клонирует данный узел. Установка *deep* означает клонирование всех дочерних узлов. Возвращает клон.215216### 19.8.2.3. Объекты NodeList217218Объект `NodeList` представляет последовательность узлов. Эти объекты используются двумя способами в рекомендации DOM Core: объект `Element` предоставляет такую последовательность в виде списка дочерних узлов, а методы `getElementsByTagName()` и `getElementsByTagNameNS()` объекта `Node` возвращают объекты с таким интерфейсом для представления результатов запросов.219220Рекомендация DOM Level 2 определяет один метод и один атрибут для этих объектов:221222#### `NodeList.item(i)`223224Возвращает *i*-й элемент из последовательности, если он существует, или `None`. Индекс *i* не может быть меньше нуля или больше или равен длине последовательности.225226#### `NodeList.length`227228Количество узлов в последовательности.229230Кроме того, Python DOM интерфейс требует предоставления дополнительной поддержки, чтобы объекты `NodeList` можно было использовать как последовательности Python. Все реализации `NodeList` должны включать поддержку [`__len__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__len__) и [`__getitem__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__getitem__); это позволяет выполнять итерацию по `NodeList` в циклах [`for`](https://python-all.ru/2.7/reference/compound_stmts.html#for) и корректно поддерживать встроенную функцию [`len()`](https://python-all.ru/2.7/library/functions.html#len).231232Если реализация DOM поддерживает изменение документа, реализация `NodeList` также должна поддерживать методы [`__setitem__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__setitem__) и [`__delitem__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__delitem__).233234### 19.8.2.4. Объекты DocumentType235236Информация о нотациях и сущностях, объявленных в документе (включая внешнее подмножество, если анализатор его использует и может предоставить эту информацию), доступна из объекта `DocumentType`. Объект `DocumentType` для документа доступен через атрибут `doctype` объекта `Document`; если для документа нет объявления `DOCTYPE`, то атрибут документа `doctype` будет установлен в `None` вместо экземпляра этого интерфейса.237238`DocumentType` является специализацией `Node` и добавляет следующие атрибуты:239240#### `DocumentType.publicId`241242Общедоступный идентификатор для внешнего подмножества определения типа документа. Это строка или `None`.243244#### `DocumentType.systemId`245246Системный идентификатор внешнего подмножества определения типа документа. Это будет URI в виде строки или `None`.247248#### `DocumentType.internalSubset`249250Строка, содержащая полное внутреннее подмножество документа. В неё не входят скобки, обрамляющие подмножество. Если у документа нет внутреннего подмножества, значение должно быть `None`.251252#### `DocumentType.name`253254Имя корневого элемента, указанное в объявлении `DOCTYPE`, если оно присутствует.255256#### `DocumentType.entities`257258Это `NamedNodeMap`, содержащий определения внешних сущностей. Для имён сущностей, определённых более одного раза, предоставляется только первое определение (остальные игнорируются, как того требует рекомендация XML). Значение может быть `None`, если анализатор не предоставил эту информацию или не определено ни одной сущности.259260#### `DocumentType.notations`261262Это `NamedNodeMap`, содержащий определения нотаций. Для имён нотаций, определённых более одного раза, предоставляется только первое определение (остальные игнорируются, как того требует рекомендация XML). Значение может быть `None`, если анализатор не предоставил эту информацию или не определено ни одной нотации.263264### 19.8.2.5. Объекты Document265266Объект `Document` представляет целый XML-документ, включая элементы, атрибуты, инструкции обработки, комментарии и т. д. Помните, что он наследует свойства от `Node`.267268#### `Document.documentElement`269270Единственный корневой элемент документа.271272#### `Document.createElement(tagName)`273274Создаёт и возвращает новый узел элемента. При создании элемент не вставляется в документ. Его нужно явно вставить одним из других методов, например `insertBefore()` или `appendChild()`.275276#### `Document.createElementNS(namespaceURI, tagName)`277278Создаёт и возвращает новый элемент с пространством имён. *tagName* может содержать префикс. При создании элемент не вставляется в документ. Его нужно явно вставить одним из других методов, например `insertBefore()` или `appendChild()`.279280#### `Document.createTextNode(data)`281282Создаёт и возвращает текстовый узел, содержащий данные, переданные в качестве параметра. Как и другие методы создания, этот не вставляет узел в дерево.283284#### `Document.createComment(data)`285286Создаёт и возвращает узел комментария, содержащий данные, переданные в качестве параметра. Как и другие методы создания, этот не вставляет узел в дерево.287288#### `Document.createProcessingInstruction(target, data)`289290Создаёт и возвращает узел инструкции обработки, содержащий *target* и *data*, переданные в качестве параметров. Как и другие методы создания, этот не вставляет узел в дерево.291292#### `Document.createAttribute(name)`293294Создаёт и возвращает узел атрибута. Этот метод не связывает узел атрибута с каким-либо конкретным элементом. Чтобы использовать вновь созданный экземпляр атрибута, нужно применить `setAttributeNode()` к соответствующему объекту `Element`.295296#### `Document.createAttributeNS(namespaceURI, qualifiedName)`297298Создаёт и возвращает узел атрибута с пространством имён. *tagName* может содержать префикс. Этот метод не связывает узел атрибута с каким-либо конкретным элементом. Чтобы использовать вновь созданный экземпляр атрибута, нужно применить `setAttributeNode()` к соответствующему объекту `Element`.299300#### `Document.getElementsByTagName(tagName)`301302Ищет всех потомков (прямые дочерние элементы, дочерние элементы дочерних и т. д.) с определённым именем типа элемента.303304#### `Document.getElementsByTagNameNS(namespaceURI, localName)`305306Ищет всех потомков (прямые дочерние элементы, дочерние элементы дочерних и т. д.) с определённым URI пространства имён и локальным именем. Локальное имя – это часть пространства имён после префикса.307308### 19.8.2.6. Объекты Element309310`Element` является подклассом `Node`, поэтому наследует все атрибуты этого класса.311312#### `Element.tagName`313314Имя типа элемента. В документе, использующем пространства имён, может содержать двоеточия. Значение – строка.315316#### `Element.getElementsByTagName(tagName)`317318То же, что и эквивалентный метод в классе `Document`.319320#### `Element.getElementsByTagNameNS(namespaceURI, localName)`321322То же, что и эквивалентный метод в классе `Document`.323324#### `Element.hasAttribute(name)`325326Возвращает True, если у элемента есть атрибут с именем *name*.327328#### `Element.hasAttributeNS(namespaceURI, localName)`329330Возвращает true, если элемент имеет атрибут с именем *namespaceURI* и *localName*.331332#### `Element.getAttribute(name)`333334Возвращает значение атрибута с именем *name* в виде строки. Если такого атрибута нет, возвращается пустая строка, как если бы атрибут не имел значения.335336#### `Element.getAttributeNode(attrname)`337338Возвращает узел `Attr` для атрибута с именем *attrname*.339340#### `Element.getAttributeNS(namespaceURI, localName)`341342Возвращает значение атрибута с именами *namespaceURI* и *localName* в виде строки. Если такого атрибута нет, возвращается пустая строка, как если бы атрибут не имел значения.343344#### `Element.getAttributeNodeNS(namespaceURI, localName)`345346Возвращает значение атрибута в виде узла по заданным *namespaceURI* и *localName*.347348#### `Element.removeAttribute(name)`349350Удаляет атрибут по имени. Если подходящего атрибута нет, возбуждается [`NotFoundErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.NotFoundErr).351352#### `Element.removeAttributeNode(oldAttr)`353354Удаляет и возвращает *oldAttr* из списка атрибутов, если он присутствует. Если *oldAttr* отсутствует, возбуждается [`NotFoundErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.NotFoundErr).355356#### `Element.removeAttributeNS(namespaceURI, localName)`357358Удаляет атрибут по имени. Обратите внимание, что используется localName, а не qname. Если подходящего атрибута нет, исключение не возбуждается.359360#### `Element.setAttribute(name, value)`361362Устанавливает значение атрибута из строки.363364#### `Element.setAttributeNode(newAttr)`365366Добавляет новый узел атрибута к элементу, при необходимости заменяя существующий атрибут, если совпадает атрибут `name`. Если произошла замена, возвращается старый узел атрибута. Если *newAttr* уже используется, возбуждается [`InuseAttributeErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.InuseAttributeErr).367368#### `Element.setAttributeNodeNS(newAttr)`369370Добавляет новый узел атрибута к элементу, при необходимости заменяя существующий атрибут, если совпадают атрибуты `namespaceURI` и `localName`. Если произошла замена, возвращается старый узел атрибута. Если *newAttr* уже используется, возбуждается [`InuseAttributeErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.InuseAttributeErr).371372#### `Element.setAttributeNS(namespaceURI, qname, value)`373374Устанавливает значение атрибута из строки на основе *namespaceURI* и *qname*. Обратите внимание: qname – это полное имя атрибута. Это отличается от описанного выше.375376### 19.8.2.7. Объекты Attr377378`Attr` наследуется от `Node`, поэтому наследует все его атрибуты.379380#### `Attr.name`381382Имя атрибута. В документе, использующем пространства имён, оно может содержать двоеточие.383384#### `Attr.localName`385386Часть имени после двоеточия, если оно есть, иначе всё имя целиком. Это атрибут только для чтения.387388#### `Attr.prefix`389390Часть имени до двоеточия, если оно есть, иначе пустая строка.391392#### `Attr.value`393394Текстовое значение атрибута. Это синоним атрибута `nodeValue`.395396### 19.8.2.8. Объекты NamedNodeMap397398`NamedNodeMap` *не* наследуется от `Node`.399400#### `NamedNodeMap.length`401402Длина списка атрибутов.403404#### `NamedNodeMap.item(index)`405406Возвращает атрибут по указанному индексу. Порядок получения атрибутов произволен, но остаётся неизменным в течение всего времени существования DOM. Каждый элемент является узлом атрибута. Чтобы получить его значение, используйте атрибут `value`.407408Существуют также экспериментальные методы, которые добавляют этому классу поведение, схожее со словарём. Вы можете использовать их или воспользоваться стандартизированным семейством методов `getAttribute*()` для объектов `Element`.409410### 19.8.2.9. Объекты Comment411412`Comment` представляет комментарий в XML-документе. Является подклассом `Node`, но не может содержать дочерних узлов.413414#### `Comment.data`415416Содержимое комментария в виде строки. Атрибут содержит все символы между открывающим `<!-``-` и закрывающим `-``->`, но не включает их.417418### 19.8.2.10. Объекты Text и CDATASection419420Интерфейс `Text` представляет текст в XML-документе. Если анализатор и реализация DOM поддерживают XML-расширение DOM, части текста, заключённые в секции CDATA, сохраняются в объектах `CDATASection`. Эти два интерфейса идентичны, но предоставляют разные значения для атрибута `nodeType`.421422Эти интерфейсы расширяют интерфейс `Node`. Они не могут содержать дочерних узлов.423424#### `Text.data`425426Содержимое текстового узла в виде строки.427428> **Примечание**429>430> Использование узла `CDATASection` не означает, что узел представляет полную CDATA-секцию, а лишь то, что содержимое узла было частью CDATA-секции. Одна CDATA-секция может быть представлена более чем одним узлом в дереве документа. Невозможно определить, представляют ли два соседних узла `CDATASection` разные CDATA-секции.431432### 19.8.2.11. Объекты ProcessingInstruction433434Представляет инструкцию по обработке в XML-документе; наследуется от интерфейса `Node` и не может содержать дочерних узлов.435436#### `ProcessingInstruction.target`437438Содержимое инструкции по обработке до первого пробельного символа. Это атрибут только для чтения.439440#### `ProcessingInstruction.data`441442Содержимое инструкции по обработке, следующее за первым пробельным символом.443444### 19.8.2.12. Исключения445446Новое в версии 2.1.447448Рекомендация DOM Level 2 определяет одно исключение, [`DOMException`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.DOMException), и ряд констант, позволяющих приложениям определить, какая именно ошибка произошла. Экземпляры [`DOMException`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.DOMException) имеют атрибут [`code`](https://python-all.ru/2.7/library/code.html#module-code), который содержит соответствующее значение для конкретного исключения.449450Интерфейс DOM в Python предоставляет эти константы, а также расширяет набор исключений, так что для каждого кода исключения, определённого в DOM, существует своё специфическое исключение. Реализации должны возбуждать соответствующее специфическое исключение, каждое из которых содержит соответствующее значение для атрибута [`code`](https://python-all.ru/2.7/library/code.html#module-code).451452#### `exception xml.dom.DOMException`453454Базовый класс исключения, используемый для всех специфических исключений DOM. Этот класс исключения не может быть создан напрямую.455456#### `exception xml.dom.DomstringSizeErr`457458Возбуждается, когда указанный диапазон текста не помещается в строку. В реализациях DOM на Python это исключение не используется, но может быть получено от реализаций DOM, написанных не на Python.459460#### `exception xml.dom.HierarchyRequestErr`461462Возбуждается при попытке вставить узел туда, где тип узла не разрешён.463464#### `exception xml.dom.IndexSizeErr`465466Возбуждается, когда параметр индекса или размера, переданный методу, отрицателен или превышает допустимые значения.467468#### `exception xml.dom.InuseAttributeErr`469470Возбуждается при попытке вставить узел `Attr`, который уже присутствует в другом месте документа.471472#### `exception xml.dom.InvalidAccessErr`473474Возбуждается, если параметр или операция не поддерживается для базового объекта.475476#### `exception xml.dom.InvalidCharacterErr`477478Это исключение возбуждается, когда строковый параметр содержит символ, который не допускается в контексте его использования согласно рекомендации XML 1.0. Например, попытка создать узел `Element` с пробелом в имени типа элемента приведёт к возбуждению этой ошибки.479480#### `exception xml.dom.InvalidModificationErr`481482Возбуждается при попытке изменить тип узла.483484#### `exception xml.dom.InvalidStateErr`485486Возбуждается при попытке использовать объект, который не определён или больше не пригоден к использованию.487488#### `exception xml.dom.NamespaceErr`489490Если предпринимается попытка изменить объект способом, не разрешённым согласно рекомендации [Namespaces in XML](https://python-all.ru/2.7/library/xml.dom.html), возбуждается это исключение.491492#### `exception xml.dom.NotFoundErr`493494Исключение, когда узел не существует в указанном контексте. Например, `NamedNodeMap.removeNamedItem()` возбудит это исключение, если переданный узел не существует в отображении.495496#### `exception xml.dom.NotSupportedErr`497498Возбуждается, когда реализация не поддерживает запрошенный тип объекта или операции.499500#### `exception xml.dom.NoDataAllowedErr`501502Возбуждается, если данные указаны для узла, который не поддерживает данные.503504#### `exception xml.dom.NoModificationAllowedErr`505506Возбуждается при попытке изменить объект, в котором изменения не разрешены (например, для узлов, доступных только для чтения).507508#### `exception xml.dom.SyntaxErr`509510Возникает при указании недопустимой или неверной строки.511512#### `exception xml.dom.WrongDocumentErr`513514Возникает, когда узел вставляется в документ, отличный от того, к которому он в настоящее время принадлежит, и реализация не поддерживает перенос узла из одного документа в другой.515516Коды исключений, определённые в рекомендации DOM, сопоставляются с описанными выше исключениями согласно следующей таблице:517518| Константа | Исключение |519| --- | --- |520| `DOMSTRING_SIZE_ERR` | [`DomstringSizeErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.DomstringSizeErr) |521| `HIERARCHY_REQUEST_ERR` | [`HierarchyRequestErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.HierarchyRequestErr) |522| `INDEX_SIZE_ERR` | [`IndexSizeErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.IndexSizeErr) |523| `INUSE_ATTRIBUTE_ERR` | [`InuseAttributeErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.InuseAttributeErr) |524| `INVALID_ACCESS_ERR` | [`InvalidAccessErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.InvalidAccessErr) |525| `INVALID_CHARACTER_ERR` | [`InvalidCharacterErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.InvalidCharacterErr) |526| `INVALID_MODIFICATION_ERR` | [`InvalidModificationErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.InvalidModificationErr) |527| `INVALID_STATE_ERR` | [`InvalidStateErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.InvalidStateErr) |528| `NAMESPACE_ERR` | [`NamespaceErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.NamespaceErr) |529| `NOT_FOUND_ERR` | [`NotFoundErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.NotFoundErr) |530| `NOT_SUPPORTED_ERR` | [`NotSupportedErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.NotSupportedErr) |531| `NO_DATA_ALLOWED_ERR` | [`NoDataAllowedErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.NoDataAllowedErr) |532| `NO_MODIFICATION_ALLOWED_ERR` | [`NoModificationAllowedErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.NoModificationAllowedErr) |533| `SYNTAX_ERR` | [`SyntaxErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.SyntaxErr) |534| `WRONG_DOCUMENT_ERR` | [`WrongDocumentErr`](https://python-all.ru/2.7/library/xml.dom.html#xml.dom.WrongDocumentErr) |535536## 19.8.3. Соответствие537538В этом разделе описываются требования к соответствию и взаимосвязи между Python DOM API, рекомендациями W3C DOM и отображением OMG IDL для Python.539540### 19.8.3.1. Отображение типов541542Примитивные типы IDL, используемые в спецификации DOM, сопоставляются с типами Python согласно следующей таблице.543544| Тип IDL | Тип Python |545| --- | --- |546| `boolean` | `IntegerType` (со значением `0` или `1`) |547| `int` | `IntegerType` |548| `long int` | `IntegerType` |549| `unsigned int` | `IntegerType` |550551Кроме того, `DOMString`, определённый в рекомендации, сопоставляется со строкой Python или строкой Unicode. Приложения должны уметь работать с Unicode всякий раз, когда из DOM возвращается строка.552553Значение IDL `null` сопоставляется с `None`, которое может приниматься или предоставляться реализацией всякий раз, когда `null` разрешено API.554555### 19.8.3.2. Методы доступа556557Отображение из OMG IDL в Python определяет функции доступа для IDL-объявлений `attribute`, во многом так же, как и отображение Java. Сопоставление IDL-объявлений558559```python560readonly attribute string someValue;561         attribute string anotherValue;562```563564даёт три функции доступа: метод «get» для `someValue` (`_get_someValue()`) и методы «get» и «set» для `anotherValue` (`_get_anotherValue()` и `_set_anotherValue()`). Отображение, в частности, не требует, чтобы атрибуты IDL были доступны как обычные атрибуты Python: `object.someValue` *не* обязан работать и может вызывать исключение [`AttributeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.AttributeError).565566Однако Python DOM API *требует*, чтобы работал обычный доступ к атрибутам. Это означает, что типичные суррогаты, генерируемые компиляторами IDL Python, скорее всего, не будут работать, и могут потребоваться объекты-обёртки на стороне клиента, если объекты DOM доступны через CORBA. Хотя это требует дополнительного внимания для клиентов CORBA DOM, разработчики, имеющие опыт использования DOM через CORBA из Python, не считают это проблемой. Атрибуты, объявленные `readonly`, могут не ограничивать доступ на запись во всех реализациях DOM.567568В Python DOM API функции доступа не обязательны. Если они предоставляются, они должны принимать форму, определённую отображением IDL Python, но эти методы считаются ненужными, поскольку атрибуты доступны напрямую из Python. Методы доступа «set» никогда не должны предоставляться для атрибутов `readonly`.569570Определения IDL не в полной мере отражают требования W3C DOM API, например, понятие некоторых объектов, таких как возвращаемое значение `getElementsByTagName()`, как «живых». Python DOM API не требует от реализаций обеспечения таких требований.571