xml.dom --- API مدل شیء سند

کد منبع: Lib/xml/dom/__init__.py

---

مدل شیء سند یا «DOM»، یک API میان‌زبانی از کنسرسیوم وب جهان‌گستر (W3C) برای دسترسی و اصلاح اسناد XML است. یک پیاده‌سازی DOM، سند XML را به‌عنوان یک ساختار درختی ارائه می‌کند یا به کد کلاینت اجازه می‌دهد چنین ساختاری را از پایه بسازد. سپس از طریق مجموعه‌ای از شیءها که رابط‌های شناخته‌شده را فراهم می‌کنند، به این ساختار دسترسی می‌دهد.

DOM برای برنامه‌های دسترسی تصادفی بسیار مفید است. SAX تنها به شما اجازه می‌دهد در هر زمان نمایی از یک بخش از سند را داشته باشید. اگر به یک عنصر SAX نگاه می‌کنید، به عنصر دیگری دسترسی ندارید. اگر به یک گره متنی نگاه می‌کنید، به عنصر حاوی آن دسترسی ندارید. هنگامی که یک برنامه SAX می‌نویسید، باید موقعیت برنامه‌تان در سند را در جایی از کد خودتان پیگیری کنید. SAX این کار را برای شما انجام نمی‌دهد. همچنین، اگر نیاز داشته باشید در سند XML جلوتر را ببینید، شانسی ندارید.

برخی برنامه‌ها به‌سادگی در یک مدل رویدادمحور بدون دسترسی به یک درخت امکان‌پذیر نیستند. البته شما می‌توانید خودتان نوعی درخت را در رویدادهای SAX بسازید، اما DOM به شما امکان می‌دهد از نوشتن آن کد اجتناب کنید. DOM یک نمایش درختی استاندارد برای داده‌های XML است.

مدل شیء سند (DOM) توسط W3C به‌صورت مرحله‌ای، یا به اصطلاح آن‌ها در «سطوح»، تعریف می‌شود. نگاشت پایتون برای این API عمدتاً بر پایه توصیه‌نامه DOM سطح ۲ است.

برنامه‌های DOM معمولاً با تجزیه‌ی مقداری XML به یک DOM آغاز می‌شوند. نحوه‌ی انجام این کار به‌هیچ‌وجه در سطح ۱ DOM پوشش داده نشده است و سطح ۲ فقط بهبودهای محدودی ارائه می‌دهد: یک کلاس شیء DOMImplementation وجود دارد که دسترسی به متدهای ایجاد Document را فراهم می‌کند، اما هیچ راهی برای دسترسی به یک خواننده/پارسر/سازنده‌ی Document برای XML به‌صورت مستقل از پیاده‌سازی وجود ندارد. همچنین هیچ راه خوش‌تعریفی برای دسترسی به این متدها بدون یک شیء Document موجود وجود ندارد. در پایتون، هر پیاده‌سازی DOM تابع getDOMImplementation() را ارائه خواهد داد. سطح ۳ DOM مشخصات Load/Store را اضافه می‌کند که رابطی برای خواننده تعریف می‌کند، اما این مورد هنوز در کتابخانه استاندارد پایتون در دسترس نیست.

هنگامی که یک شیء سند DOM داشته باشید، می‌توانید از طریق ویژگی‌ها و متدهای آن به بخش‌های سند XML خود دسترسی داشته باشید. این ویژگی‌ها در مشخصات DOM تعریف شده‌اند؛ این بخش از راهنمای مرجع، تفسیر این مشخصات در پایتون را توضیح می‌دهد.

مشخصات ارائه‌شده توسط W3C، DOM API را برای Java، ECMAScript و OMG IDL تعریف می‌کند. نگاشت پایتون تعریف‌شده در اینجا تا حد زیادی بر نسخه‌ی IDL این مشخصات مبتنی است، اما رعایت دقیق الزامی نیست (اگرچه پیاده‌سازی‌ها آزادند از نگاشت دقیق IDL پشتیبانی کنند). برای بحث مفصل درباره‌ی الزامات نگاشت، بخش انطباق را ببینید.

همچنین ملاحظه نمائید

مشخصات سطح ۲ مدل شیء سند (DOM)

توصیه‌نامه‌ی W3C که API DOM پایتون بر آن مبتنی است.

مشخصات سطح ۱ مدل شیء سند (DOM)

توصیه‌نامه‌ی W3C برای DOM که توسط xml.dom.minidom پشتیبانی می‌شود.

مشخصات نگاشت زبان پایتون

این، نگاشت از OMG IDL به پایتون را مشخص می‌کند.

محتوای ماژول

xml.dom شامل توابع زیر است:

xml.dom.registerDOMImplementation(name, factory)

تابع factory را با نام name ثبت کنید. تابع کارخانه باید شیءای را برگرداند که رابط DOMImplementation را پیاده‌سازی می‌کند. تابع کارخانه می‌تواند هر بار همان شیء را برگرداند، یا برای هر فراخوانی یک شیء جدید را برگرداند، بسته به آنچه برای پیاده‌سازی خاص مناسب است (مثلاً اگر آن پیاده‌سازی از برخی سفارشی‌سازی‌ها پشتیبانی کند).

xml.dom.getDOMImplementation(name=None, features=())

Return a suitable DOM implementation. The name is either well-known, the module name of a DOM implementation, or None. If it is not None, imports the corresponding module and returns a DOMImplementation object if the import succeeds. If no name is given, and if the environment variable PYTHON_DOM is set, this variable is used to find the implementation. The only well-known name in the standard library is 'minidom', for xml.dom.minidom.

If name is not given, this examines the available implementations to find one with the required feature set. If no implementation can be found, raise an ImportError. The features list must be a sequence of (feature, version) pairs which are passed to the hasFeature() method on available DOMImplementation objects.

همچنین برخی ثابت‌های کاربردی نیز ارائه شده‌اند:

xml.dom.EMPTY_NAMESPACE

The value used to indicate that no namespace is associated with a node in the DOM. This is typically found as the namespaceURI of a node, or used as the namespaceURI parameter to a namespaces-specific method.

xml.dom.XML_NAMESPACE

URI فضای نام مرتبط با پیشوند محفوظ xml، همان‌طور که در Namespaces in XML (بخش ۴) تعریف شده است.

xml.dom.XMLNS_NAMESPACE

URI فضای نام برای اعلان‌های فضای نام، همان‌طور که در Document Object Model (DOM) Level 2 Core Specification (بخش ۱.۱.۸) تعریف شده است.

xml.dom.XHTML_NAMESPACE

URI فضای نام XHTML، همان‌طور که در XHTML 1.0: The Extensible HyperText Markup Language (بخش 3.1.1) تعریف شده است.

In addition, xml.dom contains a base Node class and the DOM exception classes. The Node class provided by this module does not implement any of the methods or attributes defined by the DOM specification; concrete DOM implementations must provide those. The Node class provided as part of this module does provide the constants used for the nodeType attribute on concrete Node objects; they are located within the class rather than at the module level to conform with the DOM specifications.

اشیاء در DOM

مستندات قطعی برای DOM، مشخصات DOM از W3C است.

The names documented in this section are DOM interfaces. With the exception of Node and the exception classes, they are not provided by the xml.dom module itself, but by concrete DOM implementations, such as xml.dom.minidom.

توجه داشته باشید که ویژگی‌های DOM را می‌توان به‌جای رشته‌های ساده، به‌عنوان گره‌ها نیز دستکاری کرد. با این حال، نیاز به انجام این کار نسبتاً نادر است، بنابراین این کاربرد هنوز مستند نشده است.

رابط	بخش	هدف
DOMImplementation	اشیاء DOMImplementation	رابطی برای پیاده‌سازی زیربنایی.
Node	اشیای Node	رابط پایه برای بیشتر شیء‌ها در یک سند.
NodeList	اشیای NodeList	رابطی برای دنباله‌ای از گره‌ها.
DocumentType	اشیای DocumentType	اطلاعات مربوط به اعلان‌های مورد نیاز برای پردازش یک سند.
Document	اشیای سند	شیءای که نشان‌دهنده‌ی یک سند کامل است.
Element	اشیاء عنصر	گره‌های عنصر در سلسله‌مراتب سند.
Attr	اشیای Attr	گره‌های مقدار صفت روی گره‌های عنصر.
Comment	اشیای کامنت	بازنمایی کامنت‌ها در سند منبع.
Text	اشیای Text و CDATASection	گره‌های حاوی محتوای متنی سند.
ProcessingInstruction	اشیای ProcessingInstruction	بازنمایی دستورالعمل پردازش.

بخش دیگری، استثناهای تعریف‌شده برای کار با DOM در پایتون را شرح می‌دهد.

اشیاء DOMImplementation

رابط DOMImplementation راهی را برای برنامه‌ها فراهم می‌کند تا در دسترس بودن ویژگی‌های خاصی را در DOM مورد استفاده‌شان تعیین کنند. سطح ۲ DOM همچنین توانایی ایجاد اشیای جدید Document و DocumentType را با استفاده از DOMImplementation افزود.

DOMImplementation.hasFeature(feature, version)

اگر قابلیت مشخص‌شده با جفت رشته‌ی feature و version پیاده‌سازی شده باشد، True برگردانده می‌شود.

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

یک شیء جدید Document (ریشه‌ی DOM) را برمی‌گرداند، به‌همراه یک شیء فرزند از نوع Element که دارای namespaceUri و qualifiedName داده‌شده است. doctype باید یک شیء DocumentType باشد که با createDocumentType() ایجاد شده است، یا None باشد. در API DOM پایتون، دو آرگومان نخست نیز می‌توانند None باشند تا نشان دهند که هیچ فرزندی از نوع Element قرار نیست ایجاد شود.

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

یک شیء جدید DocumentType برمی‌گرداند که رشته‌های qualifiedName، publicId و systemId داده‌شده را دربر می‌گیرد و نشان‌دهنده اطلاعات موجود در اعلان نوع سند XML است.

اشیای Node

همه‌ی کامپوننت‌های یک سند XML، زیرکلاس‌هایی از Node هستند.

Only nodes of the following types can have children, and only children of the listed types:

Document

at most one Element, at most one DocumentType, ProcessingInstruction and Comment

DocumentFragment and Element

Element, Text, CDATASection, ProcessingInstruction and Comment

Attr

Text

Nodes of other types cannot have children. Inserting a child of a not allowed type raises HierarchyRequestErr.

Node.nodeType

An integer representing the node type. Symbolic constants for the types are on the Node object. This is a read-only attribute.

Node.ELEMENT_NODE

Node.ATTRIBUTE_NODE

Node.TEXT_NODE

Node.CDATA_SECTION_NODE

Node.ENTITY_REFERENCE_NODE

Node.ENTITY_NODE

Node.PROCESSING_INSTRUCTION_NODE

Node.COMMENT_NODE

Node.DOCUMENT_NODE

Node.DOCUMENT_TYPE_NODE

Node.DOCUMENT_FRAGMENT_NODE

Node.NOTATION_NODE

Integer constants for the possible values of the nodeType attribute.

Node.parentNode

والد گره فعلی، یا None برای گره سند. مقدار همیشه یک شیء Node یا None است. برای گره‌های Element، این، عنصر والد خواهد بود، به‌جز عنصر ریشه، که در این صورت شیء Document خواهد بود. برای گره‌های Attr، این همیشه None است. این یک ویژگی فقط‌خواندنی است.

Node.attributes

یک NamedNodeMap از اشیای صفت. تنها عناصر برای این ویژگی مقادیر واقعی دارند؛ سایر موارد برای این ویژگی None ارائه می‌دهند. این یک ویژگی فقط‌خواندنی است.

Node.previousSibling

گره‌ای که بلافاصله پیش از این گره و با همان والد قرار دارد. برای مثال، المانی که برچسب پایانی آن درست پیش از برچسب آغازین المان self قرار می‌گیرد. البته، اسناد XML تنها از المان‌ها تشکیل نشده‌اند، بنابراین هم‌سطح قبلی (previous sibling) می‌تواند متن، کامنت یا چیز دیگری باشد. اگر این گره اولین فرزند والد باشد، این ویژگی None خواهد بود. این یک ویژگی فقط‌خواندنی است.

Node.nextSibling

گره‌ای که بلافاصله پس از این گره و با همان والد می‌آید. همچنین previousSibling را ببینید. اگر این گره آخرین فرزند والد باشد، این ویژگی None خواهد بود. این ویژگی فقط‌خواندنی است.

Node.childNodes

A NodeList of the children of this node. If the node has no children, the list is empty. This is a read-only attribute.

Node.firstChild

اولین فرزند گره، در صورت وجود، یا None. این یک ویژگی فقط‌خواندنی است.

Node.lastChild

آخرین فرزند گره، در صورت وجود، یا None. این یک ویژگی فقط‌خواندنی است.

Node.localName

The part of the tagName following the colon if there is one, else the entire tagName. The value is a string.

Node.prefix

The part of the tagName preceding the colon if there is one, else the empty string. The value is a string, or None.

Node.namespaceURI

فضای نام مرتبط با نام عنصر. این مقدار یک رشته یا None خواهد بود. این یک ویژگی فقط‌خواندنی است.

Node.ownerDocument

The Document object to which this node belongs, or None for a document itself. This is a read-only attribute.

Node.isSupported(feature, version)

Return whether the DOM implementation supports a particular feature, as DOMImplementation.hasFeature() does.

Node.setUserData(key, data, handler)

Associate data with key on this node and return the data previously associated with key, or None. If data is None, the association is removed. handler is called when the node is cloned, imported, renamed or deleted; pass None if no notification is needed.

Node.getUserData(key)

Return the data associated with key on this node by setUserData(), or None.

Node.nodeName

The name of this node, depending on its type; see the table below. You can always get the information you would get here from another property such as the tagName property for elements or the name property for attributes. This is a read-only attribute.

Node.nodeValue

The value of this node, depending on its type; see the table below. The value is a string or None.

The values of nodeName and nodeValue for each node type are:

Node type	nodeName	nodeValue
Attr	name	value
CDATASection	'#cdata-section'	the content
Comment	'#comment'	the content
Document	'#document'	None
DocumentFragment	'#document-fragment'	None
DocumentType	name	None
Element	tagName	None
Entity	the name of the entity	None
Notation	the name of the notation	None
ProcessingInstruction	target	data
Text	'#text'	the content

Node.hasAttributes()

اگر گره دارای ویژگی‌ای باشد، True را برمی‌گرداند.

Node.hasChildNodes()

اگر گره دارای گره‌های فرزند باشد، True را برمی‌گرداند.

Node.isSameNode(other)

اگر other به همان گره‌ای اشاره کند که این گره به آن اشاره دارد، True را برمی‌گرداند. این موضوع به‌ویژه برای پیاده‌سازی‌های DOM که از هر نوع معماری پراکسی (proxy architecture) استفاده می‌کنند، مفید است (زیرا بیش از یک شیء می‌تواند به یک گره اشاره کند).

توجه

این مبتنی بر یک API پیشنهادی DOM سطح ۳ است که هنوز در مرحله‌ی «پیش‌نویس کاری» قرار دارد، اما به نظر می‌رسد این رابط خاص بدون مناقشه است. تغییرات از سوی W3C لزوماً این متد را در رابط DOM پایتون تحت تأثیر قرار نخواهد داد (اگرچه هر API جدید W3C برای این منظور نیز پشتیبانی خواهد شد).

Node.appendChild(newChild)

یک گره فرزند جدید را در انتهای فهرست فرزندان به این گره اضافه می‌کند و newChild را برمی‌گرداند. اگر گره از قبل در درخت وجود داشته باشد، ابتدا حذف می‌شود.

Node.insertBefore(newChild, refChild)

Insert a new child node before an existing child. It must be the case that refChild is a child of this node; if not, NotFoundErr is raised. newChild is returned. If refChild is None, it inserts newChild at the end of the children's list.

Node.removeChild(oldChild)

Remove a child node. oldChild must be a child of this node; if not, NotFoundErr is raised. oldChild is returned on success. If oldChild will not be used further, its unlink() method should be called.

Node.replaceChild(newChild, oldChild)

Replace an existing node with a new node. It must be the case that oldChild is a child of this node; if not, NotFoundErr is raised.

Node.normalize()

گره‌های متنی مجاور را ادغام کنید تا تمام بخش‌های متن به‌عنوان نمونه‌های واحد Text ذخیره شوند. این کار پردازش متن از درخت DOM را برای بسیاری از کاربردها ساده‌تر می‌کند.

Node.cloneNode(deep)

این گره را رونویسی کنید. تنظیم deep به معنای رونوشت تمام گره‌های فرزند نیز است. این، گره رونوشت‌شده را بازمی‌گرداند.

اشیای NodeList

A NodeList represents a sequence of nodes. These objects are used in two ways in the DOM Core recommendation: an Element object provides one as its list of child nodes, and the getElementsByTagName() and getElementsByTagNameNS() methods of Node return objects with this interface to represent query results.

NodeList does not inherit from Node.

توصیه‌نامه‌ی DOM Level 2 یک متد و یک ویژگی برای این اشیاء تعریف می‌کند:

NodeList.item(i)

Return the i'th item from the sequence, or None if i is out of range. Negative indices are not supported.

NodeList.length

تعداد گره‌های موجود در دنباله.

علاوه بر این، رابط DOM پایتون نیاز دارد که پشتیبانی بیشتری ارائه شود تا امکان استفاده از اشیاء NodeList به‌عنوان دنباله‌های پایتون فراهم شود. تمام پیاده‌سازی‌های NodeList باید شامل پشتیبانی از __len__() و __getitem__() باشند؛ این امر امکان پیمایش روی NodeList در دستورات for و پشتیبانی مناسب از تابع توکار len() را فراهم می‌کند.

اگر یک پیاده‌سازی DOM از تغییر سند پشتیبانی کند، پیاده‌سازی NodeList نیز باید از متدهای __setitem__() و __delitem__() پشتیبانی کند.

اشیای DocumentType

Information about the notations and entities declared by a document (including the external subset if the parser uses it and can provide the information) is available from a DocumentType object. The DocumentType for a document is available from the Document object's doctype attribute; if there is no DOCTYPE declaration for the document, the document's doctype attribute will be set to None instead of an instance of this interface.

DocumentType یک نوع تخصصی از Node است و ویژگی‌های زیر را اضافه می‌کند:

DocumentType.publicId

The public identifier for the external subset of the document type definition, or None if the DOCTYPE declaration does not specify it.

DocumentType.systemId

The system identifier, a URI, for the external subset of the document type definition, or None if the DOCTYPE declaration does not specify it.

DocumentType.internalSubset

رشته‌ای که زیرمجموعه‌ی داخلی کامل سند را ارائه می‌دهد. این شامل کروشه‌هایی که زیرمجموعه را دربرمی‌گیرند، نمی‌شود. اگر سند زیرمجموعه‌ی داخلی نداشته باشد، این مقدار باید None باشد.

DocumentType.name

نام عنصر ریشه، همان‌گونه که در اعلامیه DOCTYPE آمده است، در صورت وجود.

DocumentType.entities

This is a NamedNodeMap of Entity nodes giving the definitions of external entities. For entity names defined more than once, only the first definition is provided (others are ignored as required by the XML recommendation). This may be None if the information is not provided by the parser, or if no entities are defined.

DocumentType.notations

This is a NamedNodeMap of Notation nodes giving the definitions of notations. For notation names defined more than once, only the first definition is provided (others are ignored as required by the XML recommendation). This may be None if the information is not provided by the parser, or if no notations are defined.

اشیای سند

یک Document نشان‌دهنده‌ی یک سند XML کامل است، شامل عناصر تشکیل‌دهنده‌ی آن، ویژگی‌ها، دستورالعمل‌های پردازشی، کامنت‌ها و غیره. به خاطر داشته باشید که این کلاس خصوصیات را از Node به ارث می‌برد.

Document.documentElement

یگانه عنصر ریشه‌ی سند.

Document.doctype

The DocumentType node of the document, or None. This is a read-only attribute.

Document.implementation

The DOMImplementation object which created this document. This is a read-only attribute.

Document.strictErrorChecking

Whether error checking is enforced.

Document.documentURI

The location of the document, or None if it is unknown.

Document.createDocumentFragment()

Create and return an empty DocumentFragment node.

Document.createCDATASection(data)

Create and return a CDATASection node containing data.

Document.importNode(importedNode, deep)

Return a copy of importedNode which belongs to this document. The original node is not removed from its document. If deep is true, the descendants of the node are copied too.

Document.createElement(tagName)

Create and return a new element node. The element is not inserted into the document when it is created. You need to explicitly insert it with one of the other methods such as insertBefore() or appendChild().

Document.createElementNS(namespaceURI, tagName)

Create and return a new element with a namespace. The tagName may have a prefix. The element is not inserted into the document when it is created. You need to explicitly insert it with one of the other methods such as insertBefore() or appendChild().

Document.createTextNode(data)

یک گره متنی حاوی داده‌ای که به‌عنوان پارامتر داده شده است را ایجاد می‌کند و برمی‌گرداند. مانند سایر متدهای ایجاد، این متد گره را در درخت درج نمی‌کند.

Document.createComment(data)

یک گره کامنت حاوی داده‌ای که به‌عنوان پارامتر ارسال می‌شود ایجاد می‌کند و آن را برمی‌گرداند. همانند سایر متدهای ایجاد، این متد گره را در درخت درج نمی‌کند.

Document.createProcessingInstruction(target, data)

یک گره دستور پردازش حاوی target و data که به‌عنوان پارامتر ارسال شده‌اند ایجاد می‌کند و بازمی‌گرداند. مانند سایر متدهای ایجاد، این متد گره را در درخت درج نمی‌کند.

Document.createAttribute(name)

Create and return an attribute node. This method does not associate the attribute node with any particular element. You must use setAttributeNode() on the appropriate Element object to use the newly created attribute instance.

Document.createAttributeNS(namespaceURI, qualifiedName)

Create and return an attribute node with a namespace. The tagName may have a prefix. This method does not associate the attribute node with any particular element. You must use setAttributeNode() on the appropriate Element object to use the newly created attribute instance.

Document.getElementById(id)

Return the element with the given ID, or None. Only attributes declared as being of type ID in the DTD or by Element.setIdAttribute() are searched.

Document.getElementsByTagName(tagName)

جستجو برای همه‌ی نوادگان (فرزندان مستقیم، فرزندان فرزندان و غیره) با نام نوع عنصر معین.

Document.getElementsByTagNameNS(namespaceURI, localName)

جست‌وجوی همه‌ی نوادگان (فرزندان مستقیم، فرزندان فرزندان و غیره) با یک URI فضای نام و نام محلی (localname) معین. نام محلی (localname) بخشی از فضای نام است که پس از پیشوند قرار دارد.

Document.renameNode(n, namespaceURI, name)

Rename the element or attribute node n and return it. namespaceURI is the new namespace URI, or EMPTY_NAMESPACE if the node does not belong to a namespace. name is the new qualified name.

Raise WrongDocumentErr if n was created by another document, and NotSupportedErr if it is neither an element nor an attribute.

اشیاء عنصر

Element زیرکلاسی از Node است، بنابراین تمام ویژگی‌های آن کلاس را به ارث می‌برد.

Element.tagName

نام نوع عنصر. در سندی که از فضای نام استفاده می‌کند، ممکن است حاوی دونقطه باشد. مقدار آن یک رشته است.

Element.setIdAttribute(name)

Declare that the attribute name is of type ID, so that the element is found by Document.getElementById(). Raise NotFoundErr if the element has no such attribute.

Element.setIdAttributeNS(namespaceURI, localName)

The same as setIdAttribute(), but for an attribute specified by its namespace URI and local name.

Element.setIdAttributeNode(idAttr)

The same as setIdAttribute(), but for an already retrieved attribute node.

Element.getElementsByTagName(tagName)

مشابه متد معادل در کلاس Document.

Element.getElementsByTagNameNS(namespaceURI, localName)

مشابه متد معادل در کلاس Document.

Element.hasAttribute(name)

اگر عنصر دارای ویژگی‌ای به نام name باشد، True را بازمی‌گرداند.

Element.hasAttributeNS(namespaceURI, localName)

اگر عنصر دارای صفتی باشد که با namespaceURI و localName نام‌گذاری شده است، True برمی‌گرداند.

Element.getAttribute(name)

مقدار ویژگی با نام name را به‌صورت یک رشته برمی‌گرداند. اگر چنین ویژگی‌ای وجود نداشته باشد، یک رشته خالی برگردانده می‌شود، گویی که ویژگی مقداری ندارد.

Element.getAttributeNode(attrname)

گره Attr برای صفتی با نام attrname را برمی‌گرداند.

Element.getAttributeNS(namespaceURI, localName)

مقدار ویژگی با نام تعیین‌شده توسط namespaceURI و localName را به‌صورت یک رشته برمی‌گرداند. اگر چنین ویژگی‌ای وجود نداشته باشد، یک رشته خالی برگردانده می‌شود، گویی که ویژگی مقداری ندارد.

Element.getAttributeNodeNS(namespaceURI, localName)

مقدار یک ویژگی را با توجه به namespaceURI و localName به‌صورت یک گره برمی‌گرداند.

Element.removeAttribute(name)

Remove an attribute by name.

Element.removeAttributeNode(oldAttr)

در صورت وجود، oldAttr را از فهرست ویژگی‌ها حذف و برمی‌گرداند. اگر oldAttr وجود نداشته باشد، NotFoundErr پرتاب می‌شود.

Element.removeAttributeNS(namespaceURI, localName)

Remove an attribute by name. Note that it uses a localName, not a qname.

Element.setAttribute(name, value)

تنظیم مقدار یک ویژگی از یک رشته.

Element.setAttributeNode(newAttr)

Add a new attribute node to the element, replacing an existing attribute if necessary if the name attribute matches. If a replacement occurs, the old attribute node will be returned. If newAttr is already in use, InuseAttributeErr will be raised.

Element.setAttributeNodeNS(newAttr)

Add a new attribute node to the element, replacing an existing attribute if necessary if the namespaceURI and localName attributes match. If a replacement occurs, the old attribute node will be returned. If newAttr is already in use, InuseAttributeErr will be raised.

Element.setAttributeNS(namespaceURI, qname, value)

مقدار یک ویژگی را از یک رشته، با داشتن namespaceURI و qname تنظیم کنید. توجه داشته باشید که qname کل نام ویژگی است. این مورد با مورد بالا متفاوت است.

اشیای Attr

Attr از Node ارث می‌برد، بنابراین تمام ویژگی‌های آن را به ارث می‌برد.

Attribute nodes are not part of the document tree. They are contained in the attributes map of an element, not in its children, and their parentNode, previousSibling and nextSibling are always None.

Attr.name

نام ویژگی. در سندی که از فضای نام استفاده می‌کند، ممکن است شامل دونقطه باشد.

Attr.localName

بخشی از نام که پس از دونقطه می‌آید، اگر دونقطه‌ای وجود داشته باشد، در غیر این صورت کل نام. این یک ویژگی فقط‌خواندنی است.

Attr.prefix

بخشی از نام که پیش از دونقطه قرار دارد، در صورت وجود دونقطه، و در غیر این صورت رشته خالی.

Attr.isId

Whether this attribute is of type ID, either because it is declared as such in the DTD or because Element.setIdAttribute() was used. This is a read-only attribute.

Attr.ownerElement

The Element node to which this attribute belongs, or None if it is not used. This is a read-only attribute.

Attr.specified

Whether the value of the attribute was explicitly set in the document, as opposed to being defaulted from the DTD. This is a read-only attribute.

Attr.value

The text value of the attribute. This is a synonym for the nodeValue attribute.

اشیای NamedNodeMap

NamedNodeMap از Node ارث نمی‌برد.

NamedNodeMap.length

طول فهرست ویژگی‌ها.

NamedNodeMap.item(index)

Return an attribute with a particular index. The order you get the attributes in is arbitrary but will be consistent for the life of a DOM. Each item is an attribute node. Get its value with the value attribute.

NamedNodeMap.getNamedItem(name)

Return the node with the given name, or None if there is no such node.

NamedNodeMap.getNamedItemNS(namespaceURI, localName)

Return the node with the given namespace URI and local name, or None if there is no such node.

NamedNodeMap.setNamedItem(node)

Add node to the map, using its name as the key. Return the node which it replaces, or None if it replaces no node.

NamedNodeMap.setNamedItemNS(node)

Add node to the map, using its namespace URI and local name as the key. Return the node which it replaces, or None if it replaces no node.

NamedNodeMap.removeNamedItem(name)

Remove and return the node with the given name. Raise NotFoundErr if there is no such node.

NamedNodeMap.removeNamedItemNS(namespaceURI, localName)

Remove and return the node with the given namespace URI and local name. Raise NotFoundErr if there is no such node.

You can also use the standardized getAttribute*() family of methods on the Element objects.

DocumentFragment Objects

DocumentFragment is a lightweight container of nodes. It is a subclass of Node. When it is inserted into the document tree, its children are inserted instead of it, and it becomes empty.

CharacterData Objects

CharacterData represents text-like data in the XML document. It is a subclass of Node, and the base class of Text, CDATASection and Comment. Such nodes cannot have child nodes.

CharacterData.data

The content of the node as a string.

CharacterData.length

The number of characters in data. This is a read-only attribute.

CharacterData.substringData(offset, count)

Return the substring of data of count characters starting at offset.

CharacterData.appendData(arg)

Append the string arg to data.

CharacterData.insertData(offset, arg)

Insert the string arg into data at offset.

CharacterData.deleteData(offset, count)

Remove count characters from data starting at offset.

CharacterData.replaceData(offset, count, arg)

Replace count characters of data starting at offset with the string arg.

اشیای کامنت

Comment represents a comment in the XML document. It is a subclass of CharacterData.

Comment.data

محتوای کامنت به‌صورت یک رشته. این ویژگی تمام نویسه‌های بین <!-- آغازین و --> پایانی را در بر دارد، اما خود آن‌ها را شامل نمی‌شود.

اشیای Text و CDATASection

The Text interface represents text in the XML document. If the parser and DOM implementation support the DOM's XML extension, portions of the text enclosed in CDATA marked sections are stored in CDATASection objects. These two interfaces are identical, but provide different values for the nodeType attribute.

Text extends the CharacterData interface, and CDATASection extends Text.

Text.data

محتوای گره متنی به‌عنوان یک رشته.

Text.wholeText

The text of all Text nodes logically adjacent to this node, concatenated in document order. This is a read-only attribute.

Text.replaceWholeText(content)

Replace the text of all Text nodes logically adjacent to this node with content, removing the other nodes. Return this node, or None if content is empty.

Text.splitText(offset)

Split this node into two nodes at offset, keeping the first part in this node and returning a new sibling node with the rest.

توجه

استفاده از یک گره CDATASection نشان نمی‌دهد که آن گره یک بخش نمادگذاری‌شده‌ی CDATA کامل را نمایندگی می‌کند، بلکه تنها نشان می‌دهد که محتوای گره بخشی از یک بخش CDATA بوده است. یک بخش CDATA ممکن است توسط بیش از یک گره در درخت سند نمایندگی شود. هیچ راهی برای تعیین این‌که آیا دو گره CDATASection مجاور، بخش‌های نمادگذاری‌شده‌ی CDATA متفاوتی را نمایندگی می‌کنند یا خیر، وجود ندارد.

اشیای ProcessingInstruction

نشان‌دهنده‌ی یک دستور پردازشی (processing instruction) در سند XML است؛ این مورد از رابط Node ارث‌بری می‌کند و نمی‌تواند دارای گره‌های فرزند باشد.

ProcessingInstruction.target

محتوای دستورالعمل پردازشی تا نخستین نویسه فضای سفید. این یک ویژگی فقط‌خواندنی است.

ProcessingInstruction.data

محتوای دستورالعمل پردازش پس از نخستین نویسه فضای سفید.

Entity Objects

Entity represents a parsed or unparsed entity declared in the DTD. It is a subclass of Node. Entity nodes are contained in DocumentType.entities and cannot be inserted into the document tree. The name of the entity is its nodeName.

Entity.publicId

The public identifier of the entity, or None if it is not specified. This is a read-only attribute.

Entity.systemId

The system identifier of the entity, or None if it is not specified. This is a read-only attribute.

Entity.notationName

The name of the notation for an unparsed entity, or None for a parsed entity. This is a read-only attribute.

Notation Objects

Notation represents a notation declared in the DTD. It is a subclass of Node and cannot have child nodes. Notation nodes are contained in DocumentType.notations and cannot be inserted into the document tree. The name of the notation is its nodeName.

Notation.publicId

The public identifier of the notation, or None if it is not specified. This is a read-only attribute.

Notation.systemId

The system identifier of the notation, or None if it is not specified. This is a read-only attribute.

استثناها

توصیه‌نامه‌ی DOM Level 2 یک استثنای واحد، DOMException، و تعدادی ثابت تعریف می‌کند که به برنامه‌ها امکان می‌دهند تعیین کنند چه نوع خطایی رخ داده است. نمونه‌های DOMException دارای ویژگی code هستند که مقدار مناسب برای آن استثنای خاص را فراهم می‌کند.

رابط DOM پایتون ثابت‌ها را فراهم می‌کند، اما مجموعه استثناها را نیز گسترش می‌دهد تا برای هر یک از کدهای استثنای تعریف‌شده توسط DOM، یک استثنای مشخص وجود داشته باشد. پیاده‌سازی‌ها باید استثنای مشخص مناسب را پرتاب کنند، که هر کدام مقدار مناسبی برای ویژگی code دارند.

exception xml.dom.DOMException

کلاس استثنای پایه که برای تمام استثناهای خاص DOM استفاده می‌شود. این کلاس استثنا نمی‌تواند مستقیماً نمونه‌سازی شود.

exception xml.dom.DomstringSizeErr

زمانی پرتاب می‌شود که محدوده‌ی مشخص‌شده‌ای از متن در یک رشته جا نشود. شناخته نیست که این مورد در پیاده‌سازی‌های DOM پایتون استفاده شود، اما ممکن است از پیاده‌سازی‌های DOM که با پایتون نوشته نشده‌اند دریافت شود.

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

Raised when an operation would make the document invalid with respect to partial validity. This is not known to be used in the Python DOM implementations, but may be received from DOM implementations not written in Python.

exception xml.dom.WrongDocumentErr

زمانی پرتاب می‌شود که گره‌ای در سندی متفاوت از سندی که در حال حاضر به آن تعلق دارد درج شود، و پیاده‌سازی از انتقال گره از یک سند به سند دیگر پشتیبانی نکند.

کدهای استثنای تعریف‌شده در توصیه‌نامه DOM، مطابق این جدول به استثناهای شرح‌داده‌شده در بالا نگاشت می‌شوند:

ثابت	استثنا
xml.dom.DOMSTRING_SIZE_ERR	DomstringSizeErr
xml.dom.HIERARCHY_REQUEST_ERR	HierarchyRequestErr
xml.dom.INDEX_SIZE_ERR	IndexSizeErr
xml.dom.INUSE_ATTRIBUTE_ERR	InuseAttributeErr
xml.dom.INVALID_ACCESS_ERR	InvalidAccessErr
xml.dom.INVALID_CHARACTER_ERR	InvalidCharacterErr
xml.dom.INVALID_MODIFICATION_ERR	InvalidModificationErr
xml.dom.INVALID_STATE_ERR	InvalidStateErr
xml.dom.NAMESPACE_ERR	NamespaceErr
xml.dom.NOT_FOUND_ERR	NotFoundErr
xml.dom.NOT_SUPPORTED_ERR	NotSupportedErr
xml.dom.NO_DATA_ALLOWED_ERR	NoDataAllowedErr
xml.dom.NO_MODIFICATION_ALLOWED_ERR	NoModificationAllowedErr
xml.dom.SYNTAX_ERR	SyntaxErr
xml.dom.VALIDATION_ERR	ValidationErr
xml.dom.WRONG_DOCUMENT_ERR	WrongDocumentErr

انطباق

این بخش الزامات انطباق و روابط میان API DOM پایتون، توصیه‌نامه‌های DOM W3C و نگاشت OMG IDL برای پایتون را شرح می‌دهد.

نگاشت نوع

انواع IDL استفاده‌شده در مشخصات DOM، مطابق جدول زیر به انواع پایتون نگاشت می‌شوند.

نوع IDL	نوع پایتون
boolean	bool یا int
int	int
long int	int
unsigned int	int
DOMString	str یا bytes
null	None

متدهای دسترسی

نگاشت از OMG IDL به پایتون، توابع دسترسی‌گر را برای اعلان‌های attribute در IDL تقریباً به همان شیوه‌ای که نگاشت جاوا انجام می‌دهد، تعریف می‌کند. نگاشت اعلان‌های IDL

readonly attribute string someValue;
         attribute string anotherValue;

yields three accessor functions: a "get" method for someValue (_get_someValue()), and "get" and "set" methods for anotherValue (_get_anotherValue() and _set_anotherValue()). The mapping, in particular, does not require that the IDL attributes are accessible as normal Python attributes: object.someValue is not required to work, and may raise an AttributeError.

با این حال، API DOM پایتون الزام می‌کند که دسترسی عادی به ویژگی‌ها کار کند. این بدان معناست که جانشین‌های معمول (surrogates) تولیدشده توسط کامپایلرهای IDL پایتون احتمالاً کار نخواهند کرد، و اگر به اشیاء DOM از طریق CORBA دسترسی پیدا شود، ممکن است در سمت کلاینت به اشیاء پوششی نیاز باشد. اگرچه این موضوع مستلزم ملاحظات اضافی برای کلاینت‌های DOM CORBA است، پیاده‌سازان باتجربه در استفاده از DOM بر بستر CORBA از پایتون، این را مشکل نمی‌دانند. ویژگی‌هایی که readonly اعلام شده‌اند، ممکن است در همه پیاده‌سازی‌های DOM دسترسی نوشتن را محدود نکنند.

در API DOM پایتون، نیازی به توابع دسترسی (accessor) نیست. در صورت ارائه، این توابع باید از شکل تعریف‌شده در نگاشت IDL پایتون (Python IDL mapping) پیروی کنند، اما این متدها غیرضروری تلقی می‌شوند، زیرا ویژگی‌ها مستقیماً از پایتون قابل‌دسترسی هستند. برای ویژگی‌های readonly هرگز نباید توابع دسترسی "Set" ارائه شوند.

The IDL definitions do not fully embody the requirements of the W3C DOM API, such as the notion of certain objects, such as the return value of getElementsByTagName(), being "live". The Python DOM API does not require implementations to enforce such requirements.