# `xml.dom` — The Document Object Model API

Πηγαίος κώδικας: Lib/xml/dom/__init__.py

Το Μοντέλο Αντικειμένων Εγγράφου, ή αλλιώς «DOM,» είναι ένα API πολλών γλωσσών από το World Wide Web Consortium (W3C) για την πρόσβαση και την τροποποίηση εγγράφων XML. Μια υλοποίηση DOM παρουσιάζει ένα έγγραφο XML ως μια δενδρική δομή, ή επιτρέπει στον χρήστη να κατασκευάσει μια τέτοια δομή από το μηδέν. Στη συνέχεια, παρέχει πρόσβαση στη δομή μέσω ενός συνόλου αντικειμένων που προσφέρουν καθορισμένες διεπαφές.

Το DOM είναι εξαιρετικά χρήσιμο για εφαρμογές με τυχαία πρόσβαση. Το SAX σου επιτρέπει μόνο, να βλέπεις μόνο ένα κομμάτι του εγγράφου κάθε φορά. Αν εξετάζεις ένα στοιχείο SAX, δεν έχεις πρόσβαση σε κάποιο άλλο. Αν εξετάζεις έναν κόμβο κειμένου, δεν έχεις πρόσβαση στο στοιχείο που τον περιέχει. Όταν γράφεις μια εφαρμογή με χρήση του SAX, πρέπει να παρακολουθείς τη θέση του προγράμματος σου μέσα στο έγγραφο στον δικό σου κώδικα - το SAX δεν το κάνει αυτό για εσένα. Επίσης, αν χρειαστεί να κοιτάξεις μπροστά στο XML έγγραφο, δεν έχεις αυτή τη δυνατότητα.

Ορισμένες εφαρμογές είναι απλώς αδύναμες σε ένα μοντέλο βασισμένο σε γεγονότα χωρίς πρόσβαση σε δέντρο. Φυσικά, θα μπορούσες να κατασκευάσεις ένα δέντρο μόνος σου μέσω των γεγονότων του SAX, αλλά το DOM σου επιτρέπει να αποφύγεις την υλοποίηση αυτού του κώδικα. Το DOM είναι μια πρότυπη αναπαράσταση δέντρου για δεδομένα XML.

Το Document Object Model ορίζεται από το W3C σε στάδια, ή «επίπεδα» σύμφωνα με την ορολογία τους. Η αντιστοίχιση της διεπαφής προγραμματισμού εφαρμογών (API) στην Python βασίζεται σε μεγάλο βαθμό στη σύσταση του DOM Επιπέδου 2.

Οι εφαρμογές DOM συνήθως ξεκινούν αναλύοντας κάποιο XML σε DOM. Το πως επιτυγχάνεται αυτό δεν καλύπτεται καθόλου από το DOM Επίπεδο 1, ενώ το Επίπεδο 2 παρέχει μόνο περιορισμένες βελτιώσεις: Υπάρχει μια κλάση αντικειμένου `DOMImplementation` που παρέχει πρόσβαση σε μεθόδους δημιουργίας `Document`, αλλά δεν υπάρχει τρόπος πρόσβασης σε αναγνώστη XML/αναλυτή/κατασκευαστή εγγράφων με τρόπο ανεξάρτητο από την υλοποίηση. Επίσης, δεν υπάρχει καλά ορισμένος τρόπος πρόσβασης σε αυτές τις μεθόδους χωρίς ένα υπάρχον αντικείμενο `Document`. Στην Python, κάθε υλοποίηση DOM θα παρέχει μια συνάρτηση `getDOMImplementation()`. Το DOM Επίπεδο 3 προσθέτει μια προδιαγραφή Load/Store, η οποία ορίζει μια διεπαφή προς τον αναγνώστη, αλλά αυτή δεν είναι ακόμα διαθέσιμη στη στάνταρ βιβλιοθήκη της Python.

Αφού έχετε ένα αντικείμενο εγγράφου DOM, μπορείτε να αποκτήσετε πρόσβαση στα τμήματα του XML εγγράφου σας μέσω των ιδιοτήτων και των μεθόδων του. Αυτές οι ιδιότητες ορίζονται στις προδιαγραφές του DOM· αυτό το τμήμα του εγχειριδίου αναφοράς περιγράφει την ερμηνεία των προδιαγραφών στην Python.

Η προδιαγραφή που παρέχεται από το W3C ορίζει το API του DOM για τις γλώσσες Java, ECMAScript και OMG IDL. Η παρούσα αντιστοίχιση στην Python βασίζεται σε μεγάλο βαθμό στην έκδοση της προδιαγραφής με χρήση IDL, αλλά δεν απαιτείται αυστηρή συμμόρφωση (αν και οι υλοποιήσεις είναι ελεύθερες να υποστηρίζουν την αυστηρή αντιστοίχιση από IDL). Δείτε την ενότητα Συμμόρφωση για μια λεπτομερή συζήτηση των απαιτήσεων αντιστοίχισης.

Δείτε επίσης

Document Object Model (DOM) Level 2 Specification

  Η σύσταση του W3C πάνω στην οποία βασίζεται το DOM API της Python.

Document Object Model (DOM) Level 1 Specification

  Η σύσταση του W3C για το DOM που υποστηρίζεται από το `xml.dom.minidom`.

Python Language Mapping Specification

  Αυτό καθορίζει την αντιστοίχιση από το OMG IDL στην Python.

## Περιεχόμενα Module

Το `xml.dom` περιέχει τις παρακάτω συναρτήσεις:

xml.dom.registerDOMImplementation(name, factory)

  Καταχωρεί την συνάρτηση factory με το όνομα name. Η συνάρτηση factory θα πρέπει να επιστρέφει ένα αντικείμενο που υλοποιεί το interface `DOMImplementation`. Η συνάρτηση factory μπορεί να επιστρέφει το ίδιο αντικείμενο κάθε φορά ή ένα νέο αντικείμενο σε κάθε κλήση, ανάλογα με την υλοποίηση (π.χ. αν η υλοποίηση υποστηρίζει κάποια παραμετροποίηση).

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

  Επιστρέφει μια κατάλληλη υλοποίηση DOM. Το name είναι είτε ένα γνωστό όνομα, είτε το όνομα ενός module που υλοποιεί DOM, είτε `None`. Αν δεν είναι `None`, το αντίστοιχο module γίνεται import και επιστρέφεται ένα αντικείμενο `DOMImplementation` αν το import πετύχει. Αν δεν δοθεί όνομα και έχει οριστεί η μεταβλητή περιβάλλοντος `PYTHON_DOM`, τότε χρησιμοποιείται αυτή η μεταβλητή για την εύρεση της υλοποίησης.

  Αν δεν δοθεί το όνομα, τότε εξετάζονται οι διαθέσιμες υλοποιήσεις για να βρεθεί μία που να υποστηρίζει το απαιτούμενο σύνολο χαρακτηριστικών. Αν δεν βρεθεί κατάλληλη υλοποίηση, γίνεται raise `ImportError`. Η λίστα χαρακτηριστικών πρέπει να είναι μία ακολουθία από ζεύγη `(feature, version)`, τα οποία περνιούνται στη μέθοδο `hasFeature()` των διαθέσιμων αντικειμένων `DOMImplementation`.

Παρέχονται επίσης μερικές σταθερές ευκολίας:

xml.dom.EMPTY_NAMESPACE

  Η τιμή που χρησιμοποιείται για να υποδείξει ότι δεν συνδέεται κάποιο namespace με έναν κόμβο στο DOM. Συνήθως, αυτή η τιμή εμφανίζεται ως το `namespaceURI` ενός κόμβου ή χρησιμοποιείται ως παράμετρος namespaceURI σε μεθόδους που σχετίζονται με namespaces.

xml.dom.XML_NAMESPACE

  Το URI του namespace που σχετίζεται με το δεσμευμένο πρόθεμα `xml`, όπως ορίζεται από το έγγραφο Namespaces in XML (ενότητα 4).

xml.dom.XMLNS_NAMESPACE

  Το URI του namespace για δηλώσεις namespaces, όπως ορίζεται από το Document Object Model (DOM) Level 2 Core Specification (ενότητα 1.1.8).

xml.dom.XHTML_NAMESPACE

  Το URL του namespace XHTML όπως ορίζεται από το XHTML 1.0: The Extensible HyperText Markup Language (ενότητα 3.1.1).

Επιπλέον, το `xml.dom` περιέχει την βασική κλάση `Node` και τις εξαιρέσεις DOM. Η κλάση `Node` που παρέχεται από αυτό το module δεν υλοποιεί καμία από τις μεθόδους ή τα χαρακτηριστικά που ορίζονται από την προδιαγραφή DOM. Οι συγκεκριμένες υλοποιήσεις DOM πρέπει να παρέχουν αυτά τα χαρακτηριστικά. Η κλάση `Node` που παρέχεται ως μέρος αυτού του module παρέχει τις σταθερές που χρησιμοποιούνται για το χαρακτηριστικό `nodeType` σε συγκεκριμένα αντικείμενα `Node`· αυτές βρίσκονται μέσα στην κλάση και όχι στο επίπεδο του module, προκειμένου να συμβαδίζουν με τις προδιαγραφές DOM.

## Αντικείμενα στο DOM

Η οριστική τεκμηρίωση για το DOM είναι η προδιαγραφή DOM από το W3C.

Σημειώστε ότι τα χαρακτηριστικά του DOM μπορεί να χειρίζονται και ως κόμβοι αντί για απλές συμβολοσειρές. Ωστόσο, είναι αρκετά σπάνιο να πρέπει να το κάνετε αυτό, οπότε αυτή η χρήση δεν έχει τεκμηριωθεί ακόμα.

Διεπαφή | Ενότητα | Σκοπός
--- | --- | ---
`DOMImplementation` | Αντικείμενα DOMImplementation | Διεπαφή με την υποκείμενη υλοποίηση.
`Node` | Αντικείμενα κόμβων | Βασική διεπαφή για τα περισσότερα αντικείμενα σε ένα έγγραφο.
`NodeList` | Αντικείμενα NodeList | Διεπαφή για μια ακολουθία κόμβων.
`DocumentType` | Αντικείμενα DocumentType | Πληροφορίες για τις δηλώσεις που απαιτούνται για την επεξεργασία ενός εγγράφου.
`Document` | Αντικείμενα Document | Αντικείμενο που αναπαριστά ολόκληρο το έγγραφο.
`Element` | Αντικείμενα Element | Κόμβοι στοιχείων στην ιεραρχία του εγγράφου.
`Attr` | Αντικείμενα Attr | Κόμβοι τιμών χαρακτηριστικών στους κόμβους στοιχείων.
`Comment` | Αντικείμενα Comment | Αναπαράσταση σχολίων στο αρχικό έγγραφο.
`Text` | Αντικείμενα Text και CDATASection | Κόμβοι που περιέχουν το κειμενικό περιεχόμενο του εγγράφου.
`ProcessingInstruction` | Αντικείμενα ProcessingInstruction | Αναπαράσταση εντολής επεξεργασίας.

Μια επιπλέον ενότητα περιγράφει τις εξαιρέσεις που ορίζονται για την εργασία με το DOM στην Python.

### Αντικείμενα DOMImplementation

Η διεπαφή `DOMImplementation` παρέχει έναν τρόπο για τις εφαρμογές να προσδιορίζουν τη διαθεσιμότητα συγκεκριμένων δυνατοτήτων στο DOM που χρησιμοποιούν. Το DOM Επιπέδου 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`. Στο API του DOM για την Python, τα δύο πρώτα ορίσματα μπορούν επίσης να είναι `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 αποτελούνται και από άλλα στοιχεία εκτός από tags, οπότε ο προηγούμενος αδελφικός κόμβος μπορεί να είναι κείμενο, σχόλιο ή κάτι άλλο. Αν αυτός ο κόμβος είναι το πρώτο παιδί του γονέα, αυτό το χαρακτηριστικό θα είναι `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 που χρησιμοποιούν αρχιτεκτονική proxy (καθώς περισσότερα από ένα αντικείμενα μπορούν να αναφέρονται στον ίδιο κόμβο).

  Σημείωση

  Αυτό βασίζεται σε μια προτεινόμενη διεπαφή του DOM Επιπέδου 3 που βρίσκεται ακόμη στο στάδιο του «προσωρινού σχεδίου», αλλά αυτή η συγκεκριμένη διεπαφή φαίνεται να είναι ανεπίμαχη. Οι αλλαγές από το W3C δεν θα επηρεάσουν απαραίτητα αυτή την μέθοδο στην διεπαφή DOM της Python (αν και οποιοδήποτε νέο API του W3C για αυτό θα υποστηρίζεται επίσης).

Node.appendChild(newChild)

  Προσθέτει έναν νέο παιδικό κόμβο σε αυτόν τον κόμβο στο τέλος της λίστας των παιδιών, επιστρέφοντας το newChild. Αν ο κόμβος υπήρχε ήδη στο δέντρο, αφαιρείται πρώτα.

Node.insertBefore(newChild, refChild)

  Εισάγει έναν νέο παιδικό κόμβο πριν από έναν υπάρχοντα παιδικό κόμβο. Το refChild πρέπει να είναι παιδί αυτού του κόμβου· διαφορετικά, γίνεται raise μια εξαίρεση `ValueError`. Επιστρέφεται το newChild. Αν το refChild είναι `None`, το newChild εισάγεται στο τέλος της λίστας των παιδιών.

Node.removeChild(oldChild)

  Αφαιρεί έναν παιδικό κόμβο. Το oldChild πρέπει να είναι παιδί αυτού του κόμβου· διαφορετικά, γίνεται raise μια εξαίρεση `ValueError`. Επιστρέφεται το oldChild σε περίπτωση επιτυχίας. Αν το oldChild δεν πρόκειται να χρησιμοποιηθεί ξανά, θα πρέπει να κληθεί η μέθοδος `unlink()`.

Node.replaceChild(newChild, oldChild)

  Αντικαθιστά έναν υπάρχοντα κόμβο με νέο κόμβο. Το oldChild πρέπει να είναι παιδί αυτού του κόμβου· διαφορετικά, γίνεται raise μια εξαίρεση `ValueError`.

Node.normalize()

  Συγκεντρώνει γειτονικούς κόμβους κειμένου έτσι ώστε όλα τα τμήματα κειμένου να αποθηκεύονται ως μεμονωμένα αντικείμενα `Text`. Αυτό απλοποιεί την επεξεργασία του κειμένου από ένα DOM δέντρο για πολλές εφαρμογές.

Node.cloneNode(deep)

  Κλωνοποιεί αυτόν τον κόμβο. Η ρύθμιση του deep σημαίνει την κλωνοποίηση όλων των παιδικών κόμβων επίσης. Αυτό επιστρέφει τον κλώνο.

### Αντικείμενα NodeList

Μια `NodeList` αντιπροσωπεύει μια ακολουθία κόμβων. Αυτά τα αντικείμενα χρησιμοποιούνται με δύο τρόπους στην σύσταση του DOM Core: ένα αντικείμενο `Element` παρέχει μια ως τη λίστα των παιδικών κόμβων του, και οι μέθοδοι `getElementsByTagName()` και `getElementsByTagNameNS()` του `Node` επιστρέφουν αντικείμενα με αυτή τη διεπαφή για να αντιπροσωπεύσουν τα αποτελέσματα ενός ερωτήματος.

Η σύσταση DOM Επιπέδου 2 ορίζει μια μέθοδο και ένα χαρακτηριστικό για αυτά τα αντικείμενα:

NodeList.item(i)

  Επιστρέφει το i-οστό στοιχείο από τη σειρά, αν υπάρχει, ή `None`. O δείκτης i δεν επιτρέπεται να είναι μικρότερος από το μηδέν ή ίσος με το μήκος της σειράς.

NodeList.length

  Ο αριθμός των κόμβων στη σειρά.

Επιπλέον, η διεπαφή Python DOM απαιτεί να παρέχεται κάποια επιπλέον υποστήριξη για να επιτρέπεται η χρήση των αντικειμένων `NodeList` ως ακολουθίες Python. Όλες οι υλοποιήσεις `NodeList` πρέπει να περιλαμβάνουν υποστήριξη για τις μεθόδους `__len__()` και `__getitem__()` · αυτό επιτρέπει την επανάληψη μέσω του `NodeList` σε δηλώσεις `for` και την κατάλληλη υποστήριξη για τη συνάρτηση `len()`.

Αν μια υλοποίηση του DOM υποστηρίζει την τροποποίηση του εγγράφου, η υλοποίηση της `NodeList` πρέπει επίσης να υποστηρίζει τις μεθόδους `__setitem__()` και `__delitem__()`.

### Αντικείμενα DocumentType

Πληροφορίες σχετικά με τις σημειώσεις και τις οντότητες που δηλώνονται από ένα έγγραφο (συμπεριλαμβανομένου του εξωτερικού υποσυνόλου, εφόσον ο αναλυτής το χρησιμοποιεί και μπορεί να παρέχει τις πληροφορίες) είναι διαθέσιμες μέσω ενός αντικειμένου `DocumentType`. Το `DocumentType` ενός εγγράφου είναι προσβάσιμο από το χαρακτηριστικό `doctype` του αντικειμένου `Document`. Αν δεν υπάρχει δήλωση `DOCTYPE` στο έγγραφο, το χαρακτηριστικό `doctype` του εγγράφου θα έχει τιμή `None` αντί για ένα στιγμιότυπο αυτής της διεπαφής.

Η κλάση `DocumentType` είναι μια εξειδίκευση της κλάσης `Node` και προσθέτει τις παρακάτω ιδιότητες:

DocumentType.publicId

  Ο δημόσιος αναγνωριστικός χαρακτήρας για το εξωτερικό υποσύνολο του ορισμού τύπου εγγράφου. Θα είναι μια συμβολοσειρά ή `None`.

DocumentType.systemId

  Ο αναγνωριστικός χαρακτήρας συστήματος για το εξωτερικό υποσύνολο του ορισμού τύπου εγγράφου. Θα είναι ένα URI ως συμβολοσειρά ή `None`.

DocumentType.internalSubset

  Μια συμβολοσειρά που παρέχει το πλήρες εσωτερικό υποσύνολο από το έγγραφο. Δεν περιλαμβάνει τις αγκύλες που περικλείουν το υποσύνολο. Αν το έγγραφο δεν έχει εσωτερικό υποσύνολο, αυτή η τιμή πρέπει να είναι `None`.

DocumentType.name

  Το όνομα του ριζικού αρχείου όπως δίνεται στη δήλωση `DOCTYPE`, αν υπάρχει.

DocumentType.entities

  Αυτό είναι ένα αντικείμενο `NamedNodeMap` που περιέχει τους ορισμούς των εξωτερικών οντοτήτων. Για ονόματα οντοτήτων που ορίζονται περισσότερες από μία φορές, παρέχεται μόνο ο πρώτος ορισμός (οι υπόλοιποι αγνοούνται, όπως απαιτείται από τη σύσταση XML). Αυτό μπορεί να είναι `None` αν οι πληροφορίες δεν παρέχονται από τον αναλυτή ή αν δεν έχουν οριστεί οντότητες.

DocumentType.notations

  Αυτό είναι ένα αντικείμενο `NamedNodeMap` που περιέχει τους ορισμούς των σημειώσεων. Για ονόματα σημειώσεων που ορίζονται περισσότερες από μια φορές, παρέχεται μόνο ο πρώτος ορισμός (οι υπόλοιποι αγνοούνται, όπως απαιτείται από τη σύσταση XML). Αυτό μπορεί να είναι `None` αν οι πληροφορίες δεν παρέχονται από τον αναλυτή ή αν δεν έχουν οριστεί σημειώσεις.

### Αντικείμενα Document

Μια `Document` αντιπροσωπεύει ένα ολόκληρο XML έγγραφο, συμπεριλαμβανομένων των συστατικών του στοιχείων, των χαρακτηριστικών, των οδηγιών επεξεργασίας, των σχολίων κ.λπ. Να θυμάστε ότι κληρονομεί ιδιότητες από την `Node`.

Document.documentElement

  Το μοναδικό στοιχείο ρίζας του εγγράφου.

Document.createElement(tagName)

  Δημιουργεί και επιστρέφει ένα νέο κόμβο στοιχείου. Το στοιχείο δεν εισάγεται στο έγγραφο όταν δημιουργείται. Πρέπει να το εισάγετε ρητά με μία από τις άλλες μεθόδους όπως `insertBefore()` ή `appendChild()`.

Document.createElementNS(namespaceURI, tagName)

  Δημιουργεί και επιστρέφει ένα νέο στοιχείο με έναν χώρο ονομάτων. Το tagName μπορεί να έχει πρόθεμα. Το στοιχείο δεν εισάγεται στο έγγραφο όταν δημιουργείται. Πρέπει να το εισάγετε ρητά με μια από τις άλλες μεθόδους όπως `insertBefore()` ή `appendChild()`.

Document.createTextNode(data)

  Δημιουργεί και επιστρέφει έναν κόμβο κειμένου που περιέχει τα δεδομένα που περνιούνται ως παράμετρος. Όπως και με τις άλλες μεθόδους δημιουργίας, αυτή η μέθοδος δεν εισάγει τον κόμβο στο δέντρο.

Document.createComment(data)

  Δημιουργεί και επιστρέφει έναν κόμβο σχολίου που περιέχει τα δεδομένα που περνιούνται ως παράμετρος. Όπως και με τις άλλες μεθόδους δημιουργίας, αυτή η μέθοδος δεν εισάγει τον κόμβο στο δέντρο.

Document.createProcessingInstruction(target, data)

  Δημιουργεί και επιστρέφει έναν κόμβο οδηγίας επεξεργασίας που περιέχει το target και τα data που περνιούνται ως παράμετροι. Όπως και με τις άλλες μεθόδους δημιουργίας, αυτή η μέθοδος δεν εισάγει τον κόμβο στο δέντρο.

Document.createAttribute(name)

  Δημιουργεί και επιστρέφει έναν κόμβο χαρακτηριστικού. Αυτή η μέθοδος δεν συνδέει τον κόμβο χαρακτηριστικού με κάποιο συγκεκριμένο στοιχείο. Πρέπει να χρησιμοποιήσετε τη μέθοδο `setAttributeNode()` στο κατάλληλο αντικείμενο `Element` για να χρησιμοποιήσετε το νέο δημιουργημένο χαρακτηριστικό.

Document.createAttributeNS(namespaceURI, qualifiedName)

  Δημιουργεί και επιστρέφει έναν κόμβο χαρακτηριστικού με ένα namespace. Το tagName μπορεί να έχει πρόθεμα. Αυτή η μέθοδος δεν συνδέει τον κόμβο χαρακτηριστικού με κάποιο συγκεκριμένο στοιχείο. Πρέπει να χρησιμοποιήσετε τη μέθοδο `setAttributeNode()` στο κατάλληλο αντικείμενο `Element` για να χρησιμοποιήσετε το νέο δημιουργημένο χαρακτηριστικό.

Document.getElementsByTagName(tagName)

  Αναζητήστε όλους τους απογόνους (άμεσα παιδιά, παιδιά των παιδιών κ.λπ.) με ένα συγκεκριμένο όνομα τύπου στοιχείου.

Document.getElementsByTagNameNS(namespaceURI, localName)

  Αναζητήστε όλους τους απογόνους (άμεσα παιδιά, παιδιά των παιδιών κ.λπ.) με ένα συγκεκριμένο URI ονόματος χώρου ονομάτων και τοπικό όνομα. Το τοπικό όνομα είναι το μέρος του ονόματος χώρου μετά το πρόθεμα.

### Αντικείμενα Element

Η `Element` είναι υποκλάση της `Node`, επομένως κληρονομεί όλα τα χαρακτηριστικά αυτής της κλάσης.

Element.tagName

  Το όνομα του τύπου του στοιχείου. Σε έγγραφα που χρησιμοποιούν namespace μπορεί να περιέχει άνω κάτω τελείες. Η τιμή είναι μια συμβολοσειρά.

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)

  Αφαιρεί ένα χαρακτηριστικό με βάση το όνομα του. Αν δεν υπάρχει αντίστοιχη ιδιότητα, γίνεται raise μια εξαίρεση `NotFoundErr`.

Element.removeAttributeNode(oldAttr)

  Αφαιρεί και επιστρέφει το oldAttr από την λίστα των χαρακτηριστικών, εάν υπάρχει. Αν το oldAttr δεν υπάρχει, γίνεται raise μια εξαίρεση `NotFoundErr`.

Element.removeAttributeNS(namespaceURI, localName)

  Αφαιρεί ένα χαρακτηριστικό με το όνομα. Σημειώστε ότι χρησιμοποιεί το localName, όχι το qname. Δεν γίνεται raise μια εξαίρεση αν δεν υπάρχει το αντίστοιχο χαρακτηριστικό.

Element.setAttribute(name, value)

  Ορίζει μια τιμή χαρακτηριστικού από μια συμβολοσειρά.

Element.setAttributeNode(newAttr)

  Προσθέτει ένα νέο κόμβο χαρακτηριστικού στο στοιχείο, αντικαθιστώντας ένα υπάρχον χαρακτηριστικό αν είναι απαραίτητο, εάν το χαρακτηριστικό `name` ταιριάζει. Εάν γίνει αντικατάσταση, ο παλιός κόμβος χαρακτηριστικού θα επιστραφεί. Εάν το newAttr είναι ήδη σε χρήση, θα γίνει raise η εξαίρεση `InuseAttributeErr`.

Element.setAttributeNodeNS(newAttr)

  Προσθέτει ένα νέο κόμβο χαρακτηριστικού στο στοιχείο, αντικαθιστώντας ένα υπάρχον χαρακτηριστικό αν είναι απαραίτητο, εάν τα χαρακτηριστικά `namespaceURI` και `localName` ταιριάζουν. Εάν γίνει αντικατάσταση, ο παλιός κόμβος χαρακτηριστικού θα επιστραφεί. Εάν το newAttr είναι ήδη σε χρήση, θα γίνει raise μια εξαίρεση `InuseAttributeErr`.

Element.setAttributeNS(namespaceURI, qname, value)

  Ορίζει την τιμή ενός χαρακτηριστικού από μια συμβολοσειρά, δεδομένα τα namespaceURI και qname. Σημειώστε ότι το qname είναι το πλήρες όνομα του χαρακτηριστικού. Αυτό διαφέρει από τα παραπάνω.

### Αντικείμενα Attr

Η `Attr` κληρονομεί από την `Node`, οπότε κληρονομεί όλα τα χαρακτηριστικά της.

Attr.name

  Το όνομα του χαρακτηριστικού. Σε έγγραφο που χρησιμοποιεί namespaces μπορεί να περιλαμβάνει άνω κάτω τελεία.

Attr.localName

  Το μέρος του ονόματος μετά την άνω κάτω τελεία αν υπάρχει, αλλιώς το πλήρες όνομα. Αυτό είναι ένα χαρακτηριστικό για ανάγνωση μόνο.

Attr.prefix

  Το μέρος του ονόματος πριν την άνω κάτω τελεία αν υπάρχει, αλλιώς η κενή συμβολοσειρά.

Attr.value

  Η τιμή κειμένου του χαρακτηριστικού. Αυτό είναι συνώνυμο με το χαρακτηριστικό `nodeValue`.

### Αντικείμενα NamedNodeMap

Η κλάση `NamedNodeMap` δεν κληρονομεί από την κλάση `Node`.

NamedNodeMap.length

  Το μήκος της λίστας των χαρακτηριστικών.

NamedNodeMap.item(index)

  Επιστρέφει ένα χαρακτηριστικό με έναν συγκεκριμένο δείκτη. Η σειρά με την οποία παίρνετε τα χαρακτηριστικά είναι αυθαίρετη, αλλά θα παραμείνει συνεπής κατά τη διάρκεια ζωής του DOM. Κάθε στοιχείο είναι ένας κόμβος χαρακτηριστικού. Αποκτήστε την τιμή του με το χαρακτηριστικό `value`.

Υπάρχουν επίσης πειραματικές μέθοδοι που παρέχουν αυτή την κλάση περισσότερη συμπεριφορά τύπου αντιστοίχισης. Μπορείτε να χρησιμοποιήσετε αυτές ή να χρησιμοποιήσετε τις τυποποιημένες μεθόδους `getAttribute*()` στην κλάση `Element`.

### Αντικείμενα Comment

Η κλάση `Comment` αναπαριστά ένα σχόλιο στο XML έγγραφο. Είναι υποκλάση της κλάσης `Node`, αλλά δεν μπορεί να έχει κόμβους παιδιών.

Comment.data

  Το περιεχόμενο του σχολίου ως συμβολοσειρά. Το χαρακτηριστικό περιέχει όλους τους χαρακτήρες μεταξύ του αρχικού `<-``-` και του τελικού `-` `->`, αλλά δεν τους περιλαμβάνει.

### Αντικείμενα Text και CDATASection

Η διεπαφή `Text` αντιπροσωπεύει το κείμενο στο έγγραφο XML. Εάν ο αναλυτής και η υλοποίηση του DOM υποστηρίζουν την επέκταση XML του DOM, τα μέρη του κειμένου που περιβάλλονται από τμήματα που έχουν σημειωθεί ως CDATA αποθηκεύονται σε αντικείμενα `CDATASection`. Αυτές οι δύο διεπαφές είναι ταυτόσημες, αλλά παρέχουν διαφορετικές τιμές για την ιδιότητα `nodeType`.

Αυτές οι διεπαφές επεκτείνουν τη διεπαφή `Node`. Δεν μπορούν να έχουν κόμβους παιδιά.

Text.data

  Το περιεχόμενο του κόμβου κειμένου ως συμβολοσειρά.

Σημείωση

Η χρήση ενός κόμβου `CDATASection` δεν υποδηλώνει ότι ο κόμβος αντιπροσωπεύει ένα πλήρες τμήμα CDATA, αλλά μόνο ότι το περιεχόμενο του ήταν μέρος ενός τμήματος CDATA. Ένα μόνο τμήμα CDATA μπορεί να αναπαρασταθεί από περισσότερους από έναν κόμβους στο δέντρο του εγγράφου. Δεν υπάρχει τρόπος να προσδιοριστεί εάν δύο γειτονικοί κόμβοι `CDATASection` αντιπροσωπεύουν διαφορετικά τμήματα CDATA.

### Αντικείμενα ProcessingInstruction

Αντιπροσωπεύει μια εντολή επεξεργασίας στο έγγραφο XML· αυτή κληρονομεί από τη διεπαφή `Node` και δεν μπορεί να έχει κόμβους παιδιά.

ProcessingInstruction.target

  Το περιεχόμενο της εντολής επεξεργασίας μέχρι τον πρώτο χαρακτήρα κενού. Αυτό είναι ένα χαρακτηριστικό για ανάγνωση μόνο.

ProcessingInstruction.data

  Το περιεχόμενο της εντολής επεξεργασίας που ακολουθεί τον πρώτο χαρακτήρα κενού.

### Εξαιρέσεις

Η σύσταση του DOM Επιπέδου 2 ορίζει μία μόνο εξαίρεση, την `DOMException`, και μια σειρά από σταθερές που επιτρέπουν στις εφαρμογές να προσδιορίσουν το είδος του σφάλματος που προέκυψε. Τα στιγμιότυπα `DOMException` μεταφέρουν ένα χαρακτηριστικό `code` που παρέχει την κατάλληλη τιμή για την συγκεκριμένη εξαίρεση.

Η διεπαφή Python DOM παρέχει τις σταθερές, αλλά επεκτείνει επίσης το σύνολο των εξαιρέσεων, ώστε να υπάρχει μια συγκεκριμένη εξαίρεση για κάθε έναν από τους κωδικούς εξαιρέσεων που ορίζονται από το DOM. Οι υλοποιήσεις πρέπει να κάνουν raise την κατάλληλη εξαίρεση, καθεμία από τις οποίες μεταφέρει την κατάλληλη τιμή για το χαρακτηριστικό `code`.

exception xml.dom.DOMException

  Βασική κλάση εξαίρεσης που χρησιμοποιείται για όλες τις συγκεκριμένες εξαιρέσεις DOM. Αυτή η κλάση εξαίρεσης δεν μπορεί να δημιουργηθεί άμεσα.

exception xml.dom.DomstringSizeErr

  Γίνεται raise όταν μια καθορισμένη περιοχή κειμένου δεν χωράει σε μία συμβολοσειρά. Αυτό δεν είναι γνωστό ότι χρησιμοποιείται στις υλοποιήσεις Python DOM, αλλά μπορεί να ληφθεί από υλοποιήσεις DOM που δεν είναι γραμμένες σε Python.

exception xml.dom.HierarchyRequestErr

  Γίνεται raise όταν γίνεται προσπάθεια εισαγωγής ενός κόμβου όπου ο τύπος του κόμβου δεν επιτρέπεται.

exception xml.dom.IndexSizeErr

  Γίνεται raise όταν μια παράμετρος ευρετηρίου ή μεγέθους σε μια μέθοδο είναι αρνητική ή υπερβαίνει τις επιτρεπόμενες τιμές.

exception xml.dom.InuseAttributeErr

  Γίνεται raise όταν γίνεται προσπάθεια εισαγωγής ενός κόμβου `Attr` που υπάρχει ήδη αλλού στο έγγραφο.

exception xml.dom.InvalidAccessErr

  Γίνεται raise εάν μια παράμετρος ή μια λειτουργία δεν υποστηρίζεται στο υποκείμενο αντικείμενο.

exception xml.dom.InvalidCharacterErr

  Αυτή η παράμετρος γίνεται raise όταν μια παράμετρος συμβολοσειράς περιέχει έναν χαρακτήρα που δεν επιτρέπεται στο πλαίσιο χρήσης του σύμφωνα με τη σύσταση XML 1.0. Για παράδειγμα, η προσπάθεια δημιουργίας ενός κόμβου `Element` με κενό στο όνομα του τύπου του στοιχείου θα προκαλέσει αυτό το σφάλμα.

exception xml.dom.InvalidModificationErr

  Γίνεται raise όταν γίνεται προσπάθεια τροποποίησης ενός κόμβου.

exception xml.dom.InvalidStateErr

  Γίνεται raise όταν γίνεται προσπάθεια χρήσης ενός αντικειμένου που δεν είναι ορισμένο ή δεν είναι πλέον χρησιμοποιήσιμο.

exception xml.dom.NamespaceErr

  Εάν γίνει προσπάθεια αλλαγής οποιουδήποτε αντικειμένου με τρόπο που δεν επιτρέπεται σύμφωνα με τη σύσταση Namespaces in XML, γίνεται raise αυτή η εξαίρεση.

exception xml.dom.NotFoundErr

  Εξαίρεση όταν ένας κόμβος δεν υπάρχει στο αναφερόμενο πλαίσιο. Για παράδειγμα το `NamedNodeMap.removeNamedItem()` θα κάνει raise αυτή την εξαίρεση αν ο κόμβος που περνάει δεν υπάρχει στο χάρτη.

exception xml.dom.NotSupportedErr

  Γίνεται raise όταν η υλοποίηση δεν υποστηρίζει τον ζητούμενο τύπο αντικειμένου ή λειτουργίας.

exception xml.dom.NoDataAllowedErr

  Γίνεται raise εάν καθορίζονται δεδομένα για έναν κόμβο που δεν υποστηρίζει δεδομένα.

exception xml.dom.NoModificationAllowedErr

  Γίνεται raise σε προσπάθειες τροποποίησης ενός αντικειμένου όπου οι τροποποιήσεις δεν επιτρέπονται (όπως για κόμβους μόνο για ανάγνωση).

exception xml.dom.SyntaxErr

  Γίνεται raise όταν καθορίζεται μια μη έγκυρη ή παράνομη συμβολοσειρά.

exception xml.dom.WrongDocumentErr

  Γίνεται raise όταν ένας κόμβος εισάγεται σε διαφορετικό έγγραφο από αυτό που ανήκει, και η υλοποίηση δεν υποστηρίζει τη μετεγκατάσταση του κόμβου από το ένα έγγραφο στο άλλο.

Οι κωδικοί εξαιρέσεων που ορίζονται στη σύσταση DOM αντιστοιχούν στις εξαιρέσεις που περιγράφονται παραπάνω σύμφωνα με τον παρακάτω πίνακα:

Σταθερά | Εξαίρεση
--- | ---
`DOMSTRING_SIZE_ERR` | `DomstringSizeErr`
`HIERARCHY_REQUEST_ERR` | `HierarchyRequestErr`
`INDEX_SIZE_ERR` | `IndexSizeErr`
`INUSE_ATTRIBUTE_ERR` | `InuseAttributeErr`
`INVALID_ACCESS_ERR` | `InvalidAccessErr`
`INVALID_CHARACTER_ERR` | `InvalidCharacterErr`
`INVALID_MODIFICATION_ERR` | `InvalidModificationErr`
`INVALID_STATE_ERR` | `InvalidStateErr`
`NAMESPACE_ERR` | `NamespaceErr`
`NOT_FOUND_ERR` | `NotFoundErr`
`NOT_SUPPORTED_ERR` | `NotSupportedErr`
`NO_DATA_ALLOWED_ERR` | `NoDataAllowedErr`
`NO_MODIFICATION_ALLOWED_ERR` | `NoModificationAllowedErr`
`SYNTAX_ERR` | `SyntaxErr`
`WRONG_DOCUMENT_ERR` | `WrongDocumentErr`

## Συμμόρφωση

Αυτή η ενότητα περιγράφει τις απαιτήσεις συμμόρφωσης και τις σχέσεις μεταξύ της Python DOM API, των συστάσεων W3C DOM και της αντιστοίχισης OMG IDL για την Python.

### Αντιστοίχηση Τύπων

Οι τύποι IDL που χρησιμοποιούνται στις προδιαγραφές DOM αντιστοιχίζονται σε τύπους Python σύμφωνα με τον παρακάτω πίνακα.

Τύπος IDL | Τύπος Python
--- | ---
`boolean` | `bool` ή `int`
`int` | `int`
`long int` | `int`
`unsigned int` | `int`
`DOMString` | `str` ή `bytes`
`null` | `None`

### Μέθοδοι Πρόσβασης

Η αντιστοίχιση από 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` δεν απαιτείται να λειτουργεί και μπορεί να κάνει raise `AttributeError`.

Ωστόσο, η Python DOM API απαιτεί η κανονική πρόσβαση στα χαρακτηριστικά να λειτουργεί. Αυτό σημαίνει ότι οι τυπικοί εκπρόσωποι που δημιουργούνται από μεταγλωττιστές Python IDL πιθανόν να μην λειτουργούν, και ενδέχεται να απαιτούνται wrapper αντικείμενα από την πλευρά του client εάν τα DOM αντικείμενα προσπελαύνονται μέσω CORBA. Παρόλο που αυτό απαιτεί κάποια επιπλέον προσοχή για CORBA DOM clients, οι υλοποιητές με εμπειρία στη χρήση DOM μέσω CORBA από Python δεν το θεωρούν πρόβλημα. Τα χαρακτηριστικά που δηλώνονται ως `readon` ενδέχεται να μην περιορίζουν την εγγραφή σε όλες τις DOM υλοποιήσεις.

Στην Python DOM API, οι συναρτήσεις πρόσβασης δεν απαιτούνται. Εάν παρέχονται, θα πρέπει να ακολουθούν τη μορφή που ορίζεται από την αντιστοίχιση Python IDL, αλλά αυτές οι μέθοδοι θεωρούνται αναγκαίες μόνο όταν τα attributes δεν είναι άμεσα προσβάσιμα από Python. Για `readonly` χαρακτηριστικά, δεν θα πρέπει ποτέ να παρέχονται συναρτήσεις «Set» πρόσβασης.

Οι ορισμοί IDL δεν ενσωματώνουν πλήρως τις απαιτήσεις της W3C DOM API, όπως η έννοια ορισμένων αντικειμένων για παράδειγμα, η τιμή επιστροφής της `getElementsByTagName()` να είναι «live». Η Python DOM API δεν απαιτεί από τις υλοποιήσεις να εφαρμόζουν τέτοιες απαιτήσεις.