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.

There are also experimental methods that give this class more mapping behavior. You can use them or you can use the standardized getAttribute*() family of methods on the Element objects.

Αντικείμενα 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 δεν απαιτεί από τις υλοποιήσεις να εφαρμόζουν τέτοιες απαιτήσεις.