xml.parsers.expat — Γρήγορη ανάλυση XML χρησιμοποιώντας το Expat

Σημείωση

Εάν χρειάζεται να αναλύσετε μη αξιόπιστα ή μη πιστοποιημένα δεδομένα, δείτε XML security.

The xml.parsers.expat module is a Python interface to the Expat non-validating XML parser. The module provides a single extension type, xmlparser, that represents the current state of an XML parser. After an xmlparser object has been created, various attributes of the object can be set to handler functions. When an XML document is then fed to the parser, the handler functions are called for the character data and markup in the XML document.

Αυτό το module χρησιμοποιεί το pyexpat module για να παρέχει πρόσβαση στον αναλυτή Expat. Η άμεση χρήση του pyexpat module δεν συνιστάται πλέον.

Αυτό το module παρέχει μια εξαίρεση και έναν τύπο αντικειμένου:

exception xml.parsers.expat.ExpatError

Η εξαίρεση γίνεται raise όταν το Expat αναφέρει ένα σφάλμα. Δείτε την ενότητα Εξαιρέσεις ExpatError για περισσότερες πληροφορίες σχετικά με την ερμηνεία σφαλμάτων Expat.

exception xml.parsers.expat.error

Ψευδώνυμο για ExpatError.

xml.parsers.expat.XMLParserType

Ο τύπος των τιμών επιστροφής από τη συνάρτηση ParserCreate().

The xml.parsers.expat module contains two functions:

xml.parsers.expat.ErrorString(errno)

Επιστρέφει μια επεξηγηματική συμβολοσειρά για έναν δεδομένο αριθμό σφάλματος errno.

xml.parsers.expat.ParserCreate(encoding=None, namespace_separator=None)

Δημιουργεί και επιστρέφει ένα νέο αντικείμενο xmlparser. Το encoding, εάν καθοριστεί, πρέπει να είναι μια συμβολοσειρά που ονομάζει την κωδικοποίηση που χρησιμοποιείται από τα δεδομένα XML. Το Expat δεν υποστηρίζει τόσες πολλές κωδικοποιήσεις όσες η Python, και το ρεπερτόριό του από κωδικοποιήσεις δεν μπορεί να επεκταθεί· υποστηρίζει UTF-8, UTF-16, ISO-8859-1 (Latin1) και ASCII. Εάν δοθεί το encoding [1], θα αντικαταστήσει την έμμεση ή ρητή κωδικοποίηση του εγγράφου.

Οι αναλυτές που δημιουργούνται μέσω ParserCreate() ονομάζονται αναλυτές «ρίζας», με την έννοια ότι δεν έχουν συνδεδεμένο κανέναν γονικό αναλυτή. Οι μη ριζικοί αναλυτές δημιουργούνται από το parser.ExternalEntityParserCreate.

Το Expat μπορεί προαιρετικά να κάνει επεξεργασία χώρων ονομάτων XML για εσάς, εφόσον ενεργοποιηθεί με την παροχή μιας τιμής στο namespace_separator. Η τιμή πρέπει να είναι μια συμβολοσειρά ενός χαρακτήρα· διαφορετικά θα γίνει raise μια ValueError εάν το μήκος της συμβολοσειράς είναι μη έγκυρο (το None θεωρείται το ίδιο με το να μην δοθεί καθόλου τιμή). Όταν είναι ενεργοποιημένη η επεξεργασία χώρων ονομάτων, τα ονόματα τύπων στοιχείων και τα ονόματα χαρακτηριστικών που ανήκουν σε έναν χώρο ονομάτων θα επεκταθούν. Το όνομα στοιχείου που περνάει στους χειριστές στοιχείων StartElementHandler και EndElementHandler θα είναι ο συνδυασμός του URI χώρου ονομάτων, του χαρακτήρα διαχωρισμού χώρου ονομάτων και του τοπικού μέρους του ονόματος. Εάν ο διαχωριστής χώρου ονομάτων είναι ένα μηδενικό byte (chr(0)) τότε το URI χώρου ονομάτων και το τοπικό μέρος θα συνδυαστούν χωρίς κανέναν διαχωριστή.

Για παράδειγμα, εάν το namespace_separator οριστεί σε χαρακτήρα κενό (' ') και αναλυθεί το ακόλουθο έγγραφο:

<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>

Το χαρακτηριστικό StartElementHandler θα λάβει τις ακόλουθες συμβολοσειρές για κάθε στοιχείο:

http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2

Λόγω περιορισμών στη βιβλιοθήκη Expat που χρησιμοποιείται από το pyexpat, η αντικείμενη xmlparser που επιστρέφεται μπορεί να χρησιμοποιηθεί μόνο για την ανάλυση ενός μεμονωμένου εγγράφου XML. Καλέστε ParserCreate για κάθε έγγραφο για να παρέχετε μοναδικά στιγμιότυπα αναλυτών.

Δείτε επίσης

The Expat XML Parser

Αρχική σελίδα του έργου Expat.

Αντικείμενα XMLParser

Τα xmlparser αντικείμενα έχουν τις ακόλουθες μεθόδους:

xmlparser.Parse(data[, isfinal])

Αναλύει τα περιεχόμενα της συμβολοσειράς data, καλώντας τις κατάλληλες συναρτήσεις χειρισμού για την επεξεργασία των αναλυμένων δεδομένων. Το isfinal πρέπει να είναι true στην τελική κλήση αυτής της μεθόδου· επιτρέπει την ανάλυση ενός μεμονωμένου αρχείου σε θραύσματα, όχι την υποβολή πολλαπλών αρχείων. Το data μπορεί να είναι η κενή συμβολοσειρά οποιαδήποτε στιγμή.

xmlparser.ParseFile(file)

Αναλύει δεδομένα XML διαβάζοντας από το αντικείμενο file. Το file απαιτείται μόνο να παρέχει τη μέθοδο read(nbytes), επιστρέφοντας την κενή συμβολοσειρά όταν δεν υπάρχουν άλλα δεδομένα.

xmlparser.SetBase(base)

Ορίζει τη βάση που θα χρησιμοποιηθεί για την επίλυση σχετικών URI σε αναγνωριστικά συστήματος μέσα σε δηλώσεις. Η επίλυση σχετικών αναγνωριστικών αφήνεται στην εφαρμογή: αυτή η τιμή θα περαστεί ως όρισμα base στις συναρτήσεις ExternalEntityRefHandler(), NotationDeclHandler() και UnparsedEntityDeclHandler().

xmlparser.GetBase()

Επιστρέφει μια συμβολοσειρά που περιέχει τη βάση που ορίστηκε από μια προηγούμενη κλήση στο SetBase(), ή None εάν το SetBase() δεν έχει κληθεί.

xmlparser.GetInputContext()

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

xmlparser.ExternalEntityParserCreate(context[, encoding])

Δημιουργεί έναν «θυγατρικό» αναλυτή που μπορεί να χρησιμοποιηθεί για την ανάλυση μιας εξωτερικής αναλυμένης οντότητας που αναφέρεται από το περιεχόμενο που αναλύεται από τον γονικό αναλυτή. Η παράμετρος context πρέπει να είναι η συμβολοσειρά που περνάει στη συνάρτηση χειρισμού ExternalEntityRefHandler(), που περιγράφεται παρακάτω. Ο παιδικός αναλυτής δημιουργείται με τα ordered_attributes και specified_attributes ορισμένα στις τιμές αυτού του αναλυτή.

xmlparser.SetParamEntityParsing(flag)

Ελέγχει την ανάλυση των οντοτήτων παραμέτρων (συμπεριλαμβανομένου του εξωτερικού υποσυνόλου DTD). Οι πιθανές τιμές flag είναι XML_PARAM_ENTITY_PARSING_NEVER, XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE και XML_PARAM_ENTITY_PARSING_ALWAYS. Επιστρέφει true εάν ο ορισμός της σημαίας ήταν επιτυχής.

xmlparser.UseForeignDTD([flag])

Η κλήση αυτού με μια αληθή τιμή για το flag (η προεπιλογή) θα προκαλέσει το Expat να καλέσει το ExternalEntityRefHandler με None για όλα τα ορίσματα για να επιτρέψει τη φόρτωση ενός εναλλακτικού DTD. Εάν το έγγραφο δεν περιέχει δήλωση τύπου εγγράφου, το ExternalEntityRefHandler θα κληθεί ακόμα, αλλά το StartDoctypeDeclHandler και EndDoctypeDeclHandler δεν θα κληθούν.

Η μετάδοση μιας ψευδούς τιμής για το flag θα ακυρώσει μια προηγούμενη κλήση που πέρασε μια αληθή τιμή, αλλά διαφορετικά δεν έχει καμία επίδραση.

Αυτή η μέθοδος μπορεί να κληθεί μόνο πριν κληθούν οι μέθοδοι Parse() ή ParseFile(); η κλήση της μετά από οποιαδήποτε από αυτές θα προκαλέσει ExpatError να γίνει raise με το χαρακτηριστικό code ορισμένο σε errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING].

xmlparser.SetReparseDeferralEnabled(enabled)

Προειδοποίηση

Η κλήση SetReparseDeferralEnabled(False) έχει επιπτώσεις στην ασφάλεια, όπως αναλυτικά παρακάτω· βεβαιωθείτε ότι κατανοείτε αυτές τις συνέπειες πριν από τη χρήση της μεθόδου SetReparseDeferralEnabled.

Το Expat 2.6.0 εισήγαγε έναν μηχανισμό ασφάλειας που ονομάζεται «αναβολή επανεπεξεργασίας» όπου αντί να προκαλείται άρνηση υπηρεσίας μέσω τετραγωνικού χρόνου εκτέλεσης από την επανεπεξεργασία μεγάλων token, η επανεπεξεργασία μη ολοκληρωμένων token τώρα καθυστερείται από προεπιλογή μέχρι να φτάσει μια επαρκής ποσότητα εισόδου. Λόγω αυτής της καθυστέρησης, οι καταχωρημένοι χειριστές μπορεί — ανάλογα με το μέγεθος των τμημάτων εισόδου που ωθούνται στο Expat — να μην καλούνται αμέσως μετά την ώθηση νέας εισόδου στον αναλυτή. Όπου επιθυμείται άμεση ανατροφοδότηση και ανάληψη ευθύνης για την προστασία από την άρνηση υπηρεσίας από μεγάλα token, η κλήση SetReparseDeferralEnabled(False) απενεργοποιεί την αναβολή επανεπεξεργασίας για το τρέχον στιγμιότυπο αναλυτή Expat, προσωρινά ή συνολικά. Η κλήση SetReparseDeferralEnabled(True) επιτρέπει την επανενεργοποίηση της αναβολής επανεπεξεργασίας.

Σημειώστε ότι το SetReparseDeferralEnabled() έχει μεταφερθεί σε ορισμένες προηγούμενες εκδόσεις της CPython ως διόρθωση ασφαλείας. Ελέγξτε για τη διαθεσιμότητα του SetReparseDeferralEnabled() χρησιμοποιώντας τη hasattr() εάν χρησιμοποιείται σε κώδικα που εκτελείται σε μια ποικιλία εκδόσεων Python.

Added in version 3.13.

xmlparser.GetReparseDeferralEnabled()

Επιστρέφει εάν η αναβολή επανεπεξεργασίας είναι επί του παρόντος ενεργοποιημένη για το δεδομένο στιγμιότυπο αναλυτή Expat.

Added in version 3.13.

xmlparser αντικείμενα έχουν τις ακόλουθες μεθόδους για την μετρίαση ορισμένων κοινών ευπαθειών XML.

xmlparser.SetAllocTrackerActivationThreshold(threshold, /)

Ορίζει τον αριθμό των δεσμευμένων byte δυναμικής μνήμης που απαιτούνται για την ενεργοποίηση της προστασίας κατά της δυσανάλογης χρήσης RAM.

Από προεπιλογή, τα αντικείμενα αναλυτή έχουν ένα όριο ενεργοποίησης κατανομής 64 MiB, ή ισοδύναμα 67.108.864 byte.

Γίνεται raise ExpatError εάν αυτή η μέθοδος κληθεί σε έναν non-root αναλυτή. Τα αντίστοιχα lineno και offset δεν πρέπει να χρησιμοποιούνται καθώς μπορεί να μην έχουν καμία ειδική σημασία.

Added in version 3.14.1.

xmlparser.SetAllocTrackerMaximumAmplification(max_factor, /)

Ορίζει τον μέγιστο παράγοντα ενίσχυσης μεταξύ άμεσης εισόδου και byte δυναμικής μνήμης που έχουν δεσμευτεί.

Ο παράγοντας ενίσχυσης υπολογίζεται ως allocated / direct κατά την ανάλυση, όπου το direct είναι ο αριθμός των byte που διαβάστηκαν από το κύριο έγγραφο στην ανάλυση και το allocated είναι ο αριθμός των byte δυναμικής μνήμης που έχουν δεσμευτεί στην ιεραρχία αναλυτών.

Η τιμή max_factor πρέπει να είναι μια μη-NaN float τιμή μεγαλύτερη ή ίση του 1.0. Παράγοντες ενίσχυσης μεγαλύτεροι από 100.0 μπορούν να παρατηρηθούν κοντά στην αρχή της ανάλυσης ακόμη και με ακίνδυνα αρχεία στην πράξη. Ειδικότερα, το όριο ενεργοποίησης πρέπει να επιλεγεί προσεκτικά για να αποφευχθούν ψευδώς θετικά.

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

Γίνεται raise ExpatError εάν αυτή η μέθοδος κληθεί σε έναν non-root αναλυτή ή εάν το max_factor είναι εκτός του έγκυρου εύρους. Τα αντίστοιχα lineno και offset δεν πρέπει να χρησιμοποιούνται καθώς μπορεί να μην έχουν καμία ειδική σημασία.

Σημείωση

Ο μέγιστος παράγοντας ενίσχυσης λαμβάνεται υπόψιν μόνο εάν ξεπεραστεί το όριο ενεργοποίησης που μπορεί να προσαρμοστεί από το SetAllocTrackerActivationThreshold().

Added in version 3.14.1.

Τα xmlparser αντικείμενα έχουν τα ακόλουθα χαρακτηριστικά:

xmlparser.buffer_size

Το μέγεθος του buffer που χρησιμοποιείται όταν το buffer_text είναι true. Ένα νέο μέγεθος buffer μπορεί να οριστεί εκχωρώντας μια νέα ακέραια τιμή σε αυτό το χαρακτηριστικό. Όταν αλλάζει το μέγεθος, το buffer θα εκκενωθεί.

xmlparser.buffer_text

Ο ορισμός αυτού σε true προκαλεί το αντικείμενο xmlparser να αποθηκεύει σε buffer το κειμενικό περιεχόμενο που επιστρέφεται από το Expat για να αποφευχθούν πολλαπλές κλήσεις στην ανάκληση CharacterDataHandler() όποτε είναι δυνατόν. Αυτό μπορεί να βελτιώσει σημαντικά την απόδοση καθώς το Expat κανονικά διασπά τα δεδομένα χαρακτήρων σε θραύσματα σε κάθε αλλαγή γραμμής. Αυτό το χαρακτηριστικό είναι false από προεπιλογή, και μπορεί να αλλάξει οποιαδήποτε στιγμή. Σημειώστε ότι όταν είναι false, τα δεδομένα που δεν περιέχουν αλλαγές γραμμών μπορεί επίσης να διασπαστούν.

xmlparser.buffer_used

Εάν το buffer_text είναι ενεργοποιημένο, ο αριθμός των byte που αποθηκεύονται στο buffer. Αυτά τα byte αντιπροσωπεύουν κείμενο κωδικοποιημένο σε UTF-8. Αυτό το χαρακτηριστικό δεν έχει καμία ουσιαστική ερμηνεία όταν το buffer_text είναι false.

xmlparser.ordered_attributes

Ο ορισμός αυτού του χαρακτηριστικού σε έναν μη μηδενικό ακέραιο προκαλεί τα χαρακτηριστικά να αναφέρονται ως λίστα αντί για λεξικό. Τα χαρακτηριστικά παρουσιάζονται με τη σειρά που βρέθηκαν στο κείμενο του εγγράφου. Για κάθε χαρακτηριστικό, παρουσιάζονται δύο καταχωρήσεις λίστας: το όνομα του χαρακτηριστικού και η τιμή του χαρακτηριστικού. (Παλαιότερες εκδόσεις αυτού του module χρησιμοποιούσαν επίσης αυτή τη μορφή.) Από προεπιλογή, αυτό το χαρακτηριστικό είναι false· μπορεί να αλλάξει οποιαδήποτε στιγμή.

xmlparser.specified_attributes

Εάν οριστεί σε έναν μη μηδενικό ακέραιο, ο αναλυτής θα αναφέρει μόνο εκείνα τα χαρακτηριστικά που καθορίστηκαν στο παράδειγμα εγγράφου και όχι εκείνα που προέκυψαν από δηλώσεις χαρακτηριστικών. Οι εφαρμογές που το ορίζουν αυτό πρέπει να είναι ιδιαίτερα προσεκτικές στη χρήση των πρόσθετων πληροφοριών που είναι διαθέσιμες από τις δηλώσεις όπως απαιτείται για τη συμμόρφωση με τα πρότυπα για τη συμπεριφορά των επεξεργαστών XML. Από προεπιλογή, αυτό το χαρακτηριστικό είναι false· μπορεί να αλλάξει οποιαδήποτε στιγμή.

Τα ακόλουθα χαρακτηριστικά περιέχουν τιμές που σχετίζονται με το πιο πρόσφατο σφάλμα που αντιμετωπίστηκε από ένα αντικείμενο xmlparser, και θα έχουν σωστές τιμές μόνο όταν μια κλήση στο Parse() ή ParseFile() έχει προκαλέσει μια εξαίρεση xml.parsers.expat.ExpatError.

xmlparser.ErrorByteIndex

Δείκτης byte στον οποίο συνέβη ένα σφάλμα.

xmlparser.ErrorCode

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

xmlparser.ErrorColumnNumber

Αριθμός στήλης στον οποίο συνέβη ένα σφάλμα.

xmlparser.ErrorLineNumber

Αριθμός γραμμής στον οποίο συνέβη ένα σφάλμα.

Τα ακόλουθα χαρακτηριστικά περιέχουν τιμές που σχετίζονται με την τρέχουσα θέση ανάλυσης σε ένα αντικείμενο xmlparser. Κατά τη διάρκεια μιας ανάκλησης που αναφέρει ένα γεγονός ανάλυσης, υποδεικνύουν τη θέση της πρώτης από τη σειρά χαρακτήρων που δημιούργησαν το γεγονός. Όταν καλείται εκτός μιας ανάκλησης, η υποδεικνυόμενη θέση θα είναι ακριβώς μετά το τελευταίο γεγονός ανάλυσης (ανεξάρτητα από το αν υπήρχε μια σχετική ανάκληση).

xmlparser.CurrentByteIndex

Τρέχων δείκτης byte στην είσοδο του αναλυτή.

xmlparser.CurrentColumnNumber

Τρέχων αριθμός στήλης στην είσοδο του αναλυτή.

xmlparser.CurrentLineNumber

Τρέχων αριθμός γραμμής στην είσοδο του αναλυτή.

Εδώ είναι η λίστα των χειριστών που μπορούν να οριστούν. Για να ορίσετε έναν χειριστή σε ένα αντικείμενο xmlparser o, χρησιμοποιήστε o.handlername = func. Το handlername πρέπει να ληφθεί από την ακόλουθη λίστα, και το func πρέπει να είναι ένα αντικείμενο που μπορεί να κληθεί αποδεχόμενο τον σωστό αριθμό ορισμάτων. Τα ορίσματα είναι όλες συμβολοσειρές, εκτός εάν αναφέρεται διαφορετικά.

xmlparser.XmlDeclHandler(version, encoding, standalone)

Καλείται όταν αναλύεται η δήλωση XML. Η δήλωση XML είναι η (προαιρετική) δήλωση της εφαρμοστέας έκδοσης της σύστασης XML, της κωδικοποίησης του κειμένου του εγγράφου, και μια προαιρετική «αυτόνομη» δήλωση. Το version και το encoding θα είναι συμβολοσειρές, και το standalone θα είναι 1 εάν το έγγραφο δηλώνεται αυτόνομο, 0 εάν δηλώνεται ότι δεν είναι αυτόνομο, ή -1 εάν η ρήτρα αυτόνομης παραλείφθηκε. Αυτό είναι διαθέσιμο μόνο με την έκδοση 1.95.0 ή νεότερη του Expat.

xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)

Called when Expat begins parsing the document type declaration (<!DOCTYPE ...). The doctypeName is provided exactly as presented. The systemId and publicId parameters give the system and public identifiers if specified, or None if omitted. has_internal_subset will be true if the document contains an internal document declaration subset. This requires Expat version 1.2 or newer.

xmlparser.EndDoctypeDeclHandler()

Καλείται όταν το Expat ολοκληρώνει την ανάλυση της δήλωσης τύπου εγγράφου. Αυτό απαιτεί Expat έκδοσης 1.2 ή νεότερης.

xmlparser.ElementDeclHandler(name, model)

Καλείται μία φορά για κάθε δήλωση τύπου στοιχείου. Το name είναι το όνομα του τύπου στοιχείου, και το model είναι μια αναπαράσταση του μοντέλου περιεχομένου.

xmlparser.AttlistDeclHandler(elname, attname, type, default, required)

Καλείται για κάθε δηλωμένο χαρακτηριστικό για έναν τύπο στοιχείου. Εάν μια δήλωση λίστας χαρακτηριστικών δηλώνει τρία χαρακτηριστικά, αυτός ο χειριστής καλείται τρεις φορές, μία για κάθε χαρακτηριστικό. Το elname είναι το όνομα του στοιχείου στο οποίο εφαρμόζεται η δήλωση και το attname είναι το όνομα του δηλωμένου χαρακτηριστικού. Ο τύπος χαρακτηριστικού είναι μια συμβολοσειρά που περνάει ως type· οι πιθανές τιμές είναι 'CDATA', 'ID', 'IDREF', … το default δίνει την προεπιλεγμένη τιμή για το χαρακτηριστικό που χρησιμοποιείται όταν το χαρακτηριστικό δεν καθορίζεται από το παράδειγμα εγγράφου, ή None εάν δεν υπάρχει προεπιλεγμένη τιμή (τιμές #IMPLIED). Εάν το χαρακτηριστικό απαιτείται να δοθεί στο παράδειγμα εγγράφου, το required θα είναι true. Αυτό απαιτεί Expat έκδοση 1.95.0 ή νεότερης.

xmlparser.StartElementHandler(name, attributes)

Καλείται για την έναρξη κάθε στοιχείου. Το name είναι μια συμβολοσειρά που περιέχει το όνομα του στοιχείου, και το attributes είναι τα χαρακτηριστικά του στοιχείου. Εάν το ordered_attributes είναι true, αυτό είναι μια λίστα (δείτε το ordered_attributes για μια πλήρη περιγραφή). Διαφορετικά είναι ένα λεξικό που αντιστοιχίζει ονόματα σε τιμές.

xmlparser.EndElementHandler(name)

Καλείται για το τέλος κάθε στοιχείου.

xmlparser.ProcessingInstructionHandler(target, data)

Καλείται για κάθε οδηγία επεξεργασίας.

xmlparser.CharacterDataHandler(data)

Καλείται για δεδομένα χαρακτήρων. Αυτό θα κληθεί για κανονικά δεδομένα χαρακτήρων, περιεχόμενο επισημασμένο ως CDATA, και αγνοήσιμο κενό χώρο. Οι εφαρμογές που πρέπει να διακρίνουν αυτές τις περιπτώσεις μπορούν να χρησιμοποιήσουν τις ανακλήσεις StartCdataSectionHandler, EndCdataSectionHandler, και ElementDeclHandler για να συλλέξουν τις απαιτούμενες πληροφορίες. Σημειώστε ότι τα δεδομένα χαρακτήρων μπορεί να διασπαστούν ακόμη και αν είναι μικρά και έτσι μπορεί να λάβετε περισσότερες από μία κλήσεις στο CharacterDataHandler(). Ορίστε το χαρακτηριστικό στιγμιότυπου buffer_text σε True για να αποφύγετε αυτό.

xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)

Καλείται για δηλώσεις μη αναλυμένων (NDATA) οντοτήτων. Αυτό είναι παρόν μόνο για την έκδοση 1.2 της βιβλιοθήκης Expat· για πιο πρόσφατες εκδόσεις, χρησιμοποιήστε EntityDeclHandler αντ” αυτού. (Η υποκείμενη λειτουργία στη βιβλιοθήκη Expat έχει κηρυχθεί απαρχαιωμένη.)

xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

Καλείται για όλες τις δηλώσεις οντοτήτων. Για παραμετρικές και εσωτερικές οντότητες, το value θα είναι μια συμβολοσειρά που δίνει τα δηλωμένα περιεχόμενα της οντότητας· αυτό θα είναι None για εξωτερικές οντότητες. Η παράμετρος notationName θα είναι None για αναλυμένες οντότητες, και το όνομα της σημειογραφίας για μη αναλυμένες οντότητες. Το is_parameter_entity θα είναι true εάν η οντότητα είναι μια παραμετρική οντότητα ή false για γενικές οντότητες (οι περισσότερες εφαρμογές χρειάζεται να ασχολούνται μόνο με γενικές οντότητες). Αυτό είναι διαθέσιμο μόνο ξεκινώντας από την έκδοση 1.95.0 της βιβλιοθήκης Expat.

xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)

Καλείται για δηλώσεις σημειογραφίας. Το notationName, base, και systemId, και publicId είναι συμβολοσειρές εάν δίνονται. Εάν το δημόσιο αναγνωριστικό παραλείπεται, το publicId θα είναι None.

xmlparser.StartNamespaceDeclHandler(prefix, uri)

Καλείται όταν ένα στοιχείο περιέχει μια δήλωση χώρου ονομάτων. Οι δηλώσεις χώρων ονομάτων επεξεργάζονται πριν κληθεί ο StartElementHandler για το στοιχείο στο οποίο τοποθετούνται οι δηλώσεις.

xmlparser.EndNamespaceDeclHandler(prefix)

Καλείται όταν επιτευχθεί η ετικέτα κλεισίματος για ένα στοιχείο που περιείχε μια δήλωση χώρου ονομάτων. Αυτό καλείται μία φορά για κάθε δήλωση χώρου ονομάτων στο στοιχείο με την αντίστροφη σειρά για την οποία κλήθηκε ο StartNamespaceDeclHandler για να υποδείξει την έναρξη της εμβέλειας κάθε δήλωσης χώρου ονομάτων. Οι κλήσεις σε αυτόν τον χειριστή γίνονται μετά τον αντίστοιχο EndElementHandler για το τέλος του στοιχείου.

xmlparser.CommentHandler(data)

Καλείται για σχόλια. Το data είναι το κείμενο του σχολίου, εξαιρώντας το προκαταρκτικό '<!--' και το τελικό '-->'.

xmlparser.StartCdataSectionHandler()

Καλείται στην αρχή μιας ενότητας CDATA. Αυτό και το EndCdataSectionHandler είναι απαραίτητα για να μπορέσουμε να αναγνωρίσουμε την συντακτική έναρξη και το τέλος για τις ενότητες CDATA.

xmlparser.EndCdataSectionHandler()

Καλείται στο τέλος μιας ενότητας CDATA.

xmlparser.DefaultHandler(data)

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

xmlparser.DefaultHandlerExpand(data)

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

xmlparser.NotStandaloneHandler()

Καλείται εάν το έγγραφο XML δεν έχει δηλωθεί ως αυτόνομο έγγραφο. Αυτό συμβαίνει όταν υπάρχει ένα εξωτερικό υποσύνολο ή μια αναφορά σε μια παραμετρική οντότητα, αλλά η δήλωση XML δεν ορίζει το standalone σε yes σε μια δήλωση XML. Εάν αυτός ο χειριστής επιστρέψει 0, τότε ο αναλυτής θα προκαλέσει ένα σφάλμα XML_ERROR_NOT_STANDALONE. Εάν αυτός ο χειριστής δεν έχει οριστεί, δεν γίνεται raise καμία εξαίρεση από τον αναλυτή για αυτή την κατάσταση.

xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)

Προειδοποίηση

Η υλοποίηση ενός χειριστή που έχει πρόσβαση σε τοπικά αρχεία και/ή στο δίκτυο μπορεί να δημιουργήσει μια ευπάθεια σε external entity attacks <https://en.wikipedia.org/wiki/XML_external_entity_attack> εάν το xmlparser χρησιμοποιείται με περιεχόμενο XML που παρέχεται από τον χρήστη. Σκεφτείτε το threat model σας πριν υλοποιήσετε αυτόν τον χειριστή.

Καλείται για αναφορές σε εξωτερικές οντότητες. Το base είναι η τρέχουσα βάση, όπως ορίζεται από μια προηγούμενη κλήση στο SetBase(). Τα δημόσια και συστημικά αναγνωριστικά, systemId και publicId, είναι συμβολοσειρές εάν δίνονται· εάν το δημόσιο αναγνωριστικό δεν δίνεται, το publicId θα είναι None. Η τιμή context είναι αδιαφανής και πρέπει να χρησιμοποιείται μόνο όπως περιγράφεται παρακάτω.

Για να αναλυθούν εξωτερικές οντότητες, αυτός ο χειριστής πρέπει να υλοποιηθεί. Είναι υπεύθυνος για τη δημιουργία του υπο-αναλυτή χρησιμοποιώντας ExternalEntityParserCreate(context), την αρχικοποίηση του με τις κατάλληλες ανακλήσεις, και την ανάλυση της οντότητας. Αυτός ο χειριστής πρέπει να επιστρέψει έναν ακέραιο· εάν επιστρέψει 0, ο αναλυτής θα προκαλέσει ένα σφάλμα XML_ERROR_EXTERNAL_ENTITY_HANDLING, διαφορετικά η ανάλυση θα συνεχιστεί.

Εάν αυτός ο χειριστής δεν παρέχεται, οι εξωτερικές οντότητες αναφέρονται από την ανάκληση DefaultHandler, εάν παρέχεται.

Εξαιρέσεις ExpatError

Οι εξαιρέσεις ExpatError έχουν έναν αριθμό ενδιαφερόντων χαρακτηριστικών:

ExpatError.code

Ο εσωτερικός αριθμός σφάλματος του Expat για το συγκεκριμένο σφάλμα. Το errors.messages λεξικό αντιστοιχεί αυτούς τους αριθμούς σφάλματος στα μηνύματα σφαλμάτων του Expat. Για παράδειγμα:

from xml.parsers.expat import ParserCreate, ExpatError, errors

p = ParserCreate()
try:
    p.Parse(some_xml_document)
except ExpatError as err:
    print("Error:", errors.messages[err.code])

Το module errors παρέχει επίσης σταθερές μηνυμάτων σφαλμάτων και ένα λεξικό codes που αντιστοιχίζει αυτά τα μηνύματα πίσω στους κωδικούς σφαλμάτων, δείτε παρακάτω.

ExpatError.lineno

Αριθμός γραμμής στον οποίο ανιχνεύθηκε το σφάλμα. Η πρώτη γραμμή αριθμείται 1.

ExpatError.offset

Χαρακτήρας μετατόπισης στη γραμμή όπου συνέβη το σφάλμα. Η πρώτη στήλη αριθμείται 0.

Παράδειγμα

Το ακόλουθο πρόγραμμα ορίζει τρεις χειριστές που απλώς εκτυπώνουν τα ορίσματά τους.

import xml.parsers.expat

# 3 handler functions
def start_element(name, attrs):
    print('Start element:', name, attrs)
def end_element(name):
    print('End element:', name)
def char_data(data):
    print('Character data:', repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)

Η έξοδος από αυτό το πρόγραμμα είναι:

Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent

Περιγραφές Μοντέλου Περιεχομένου

Τα μοντέλα περιεχομένου περιγράφονται χρησιμοποιώντας εμφωλευμένες πλειάδες. Κάθε πλειάδα περιέχει τέσσερις τιμές: ο τύπος, ο ποσοτικός δείκτης, το όνομα, και μια πλειάδα παιδιών. Τα παιδιά είναι απλώς επιπλέον περιγραφές μοντέλου περιεχομένου.

The values of the first two fields are constants defined in the xml.parsers.expat.model module. These constants can be collected in two groups: the model type group and the quantifier group.

Οι σταθερές στην ομάδα τύπου μοντέλου είναι:

xml.parsers.expat.model.XML_CTYPE_ANY

Το στοιχείο που ονομάζεται από το όνομα μοντέλου δηλώθηκε ότι έχει ένα μοντέλο περιεχομένου ANY.

xml.parsers.expat.model.XML_CTYPE_CHOICE

Το ονομαζόμενο στοιχείο επιτρέπει μια επιλογή από έναν αριθμό επιλογών· αυτό χρησιμοποιείται για μοντέλα περιεχομένου όπως (A | B | C).

xml.parsers.expat.model.XML_CTYPE_EMPTY

Στοιχεία που δηλώνονται ως EMPTY έχουν αυτόν τον τύπο μοντέλου.

xml.parsers.expat.model.XML_CTYPE_MIXED
xml.parsers.expat.model.XML_CTYPE_NAME
xml.parsers.expat.model.XML_CTYPE_SEQ

Τα μοντέλα που αντιπροσωπεύουν μια σειρά μοντέλων που ακολουθούν το ένα το άλλο υποδεικνύονται με αυτόν τον τύπο μοντέλου. Αυτό χρησιμοποιείται για μοντέλα όπως (A, B, C).

Οι σταθερές στην ομάδα ποσοτικών δεικτών είναι:

xml.parsers.expat.model.XML_CQUANT_NONE

Δεν δίνεται κανένας τροποποιητής, οπότε μπορεί να εμφανιστεί ακριβώς μία φορά, όπως για A.

xml.parsers.expat.model.XML_CQUANT_OPT

Το μοντέλο είναι προαιρετικό: μπορεί να εμφανιστεί μία φορά ή καθόλου, όπως για A?.

xml.parsers.expat.model.XML_CQUANT_PLUS

Το μοντέλο πρέπει να εμφανίζεται μία ή περισσότερες φορές (όπως A+).

xml.parsers.expat.model.XML_CQUANT_REP

Το μοντέλο πρέπει να εμφανίζεται μηδέν ή περισσότερες φορές, όπως για A*.

Σταθερές σφαλμάτων Expat

The following constants are provided in the xml.parsers.expat.errors module. These constants are useful in interpreting some of the attributes of the ExpatError exception objects raised when an error has occurred. Since for backwards compatibility reasons, the constants” value is the error message and not the numeric error code, you do this by comparing its code attribute with errors.codes[errors.XML_ERROR_CONSTANT_NAME].

Το module errors έχει τα ακόλουθα χαρακτηριστικά:

xml.parsers.expat.errors.codes

Ένα λεξικό που αντιστοιχίζει περιγραφές συμβολοσειρών στους κωδικούς σφαλμάτων τους.

Added in version 3.2.

xml.parsers.expat.errors.messages

Ένα λεξικό που αντιστοιχίζει αριθμητικούς κωδικούς σφαλμάτων στις περιγραφές συμβολοσειρών τους.

Added in version 3.2.

xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY
xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

Μια αναφορά οντότητας σε μια τιμή χαρακτηριστικού αναφέρθηκε σε μια εξωτερική οντότητα αντί για μια εσωτερική οντότητα.

xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF

Μια αναφορά χαρακτήρα αναφέρθηκε σε έναν χαρακτήρα που είναι παράνομος στο XML (για παράδειγμα, ο χαρακτήρας 0, ή “&#0;”).

xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF

Μια αναφορά οντότητας αναφέρθηκε σε μια οντότητα που δηλώθηκε με μια σημειογραφία, οπότε δεν μπορεί να αναλυθεί.

xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE

Ένα χαρακτηριστικό χρησιμοποιήθηκε περισσότερες από μία φορές σε μια ετικέτα έναρξης.

xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING
xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN

Προκαλείται όταν ένα εισερχόμενο byte δεν μπορούσε να ανατεθεί σωστά σε έναν χαρακτήρα· για παράδειγμα, ένα byte NUL (τιμή 0) σε μια ροή εισόδου UTF-8.

xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Κάτι άλλο εκτός από κενό χώρο συνέβη μετά το στοιχείο εγγράφου.

xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI

Βρέθηκε μια δήλωση XML κάπου αλλού εκτός από την αρχή των δεδομένων εισόδου.

xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS

Το έγγραφο δεν περιέχει στοιχεία (το XML απαιτεί όλα τα έγγραφα να περιέχουν ακριβώς ένα στοιχείο κορυφαίου επιπέδου)..

xml.parsers.expat.errors.XML_ERROR_NO_MEMORY

Το Expat δεν ήταν σε θέση να δεσμεύσει μνήμη εσωτερικά.

xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF

Βρέθηκε μια αναφορά παραμετρικής οντότητας όπου δεν επιτρέπεται.

xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR

Βρέθηκε ένας ατελής χαρακτήρας στην είσοδο.

xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF

Μια αναφορά οντότητας περιείχε μια άλλη αναφορά στην ίδια οντότητα· πιθανώς μέσω ενός διαφορετικού ονόματος, και πιθανώς έμμεσα.

xml.parsers.expat.errors.XML_ERROR_SYNTAX

Συνέβη κάποιο μη καθορισμένο συντακτικό σφάλμα.

xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH

Μια ετικέτα λήξης δεν ταιριάζει με την πιο εσωτερική ανοιχτή ετικέτα έναρξης.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN

Κάποιο token (όπως μια ετικέτα έναρξης) δεν έκλεισε πριν το τέλος της ροής ή συναντήθηκε το επόμενο διακριτικό.

xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY

Έγινε αναφορά σε μια οντότητα που δεν ορίστηκε.

xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING

Η κωδικοποίηση εγγράφου δεν υποστηρίζεται από το Expat.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION

Μια ενότητα με σήμανση CDATA δεν έκλεισε.

xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING
xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE

Ο αναλυτής διαπίστωσε ότι το έγγραφο δεν ήταν «αυτόνομο» αν και το δήλωνε ότι ήταν στη δήλωση XML, και ο NotStandaloneHandler ορίστηκε και επέστρεψε 0.

xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE
xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE
xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD

An operation was requested that requires DTD support to be compiled in, but Expat was configured without DTD support. This should never be reported by a standard build of the xml.parsers.expat module.

xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

Ζητήθηκε μια αλλαγή συμπεριφοράς μετά την έναρξη της ανάλυσης που μπορεί να αλλάξει μόνο πριν ξεκινήσει η ανάλυση. Αυτό (προς το παρόν) προκαλείται μόνο από τη UseForeignDTD().

xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX

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

xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX

Το έγγραφο προσπάθησε να αφαιρέσει τη δήλωση χώρου ονομάτων που σχετίζεται με ένα πρόθεμα.

xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE

Μια παραμετρική οντότητα περιείχε ατελή σήμανση.

xml.parsers.expat.errors.XML_ERROR_XML_DECL

Το έγγραφο δεν περιείχε καθόλου στοιχείο εγγράφου.

xml.parsers.expat.errors.XML_ERROR_TEXT_DECL

Υπήρξε σφάλμα κατά την ανάλυση μιας δήλωσης κειμένου σε μια εξωτερική οντότητα.

xml.parsers.expat.errors.XML_ERROR_PUBLICID

Βρέθηκαν χαρακτήρες στο δημόσιο αναγνωριστικό που δεν επιτρέπονται.

xml.parsers.expat.errors.XML_ERROR_SUSPENDED

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

xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED

Έγινε μια προσπάθεια να συνεχιστεί ο αναλυτής όταν ο αναλυτής δεν είχε ανασταλεί.

xml.parsers.expat.errors.XML_ERROR_ABORTED

Αυτό δεν θα πρέπει να αναφέρεται σε εφαρμογές Python.

xml.parsers.expat.errors.XML_ERROR_FINISHED

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

xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE
xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML

Έγινε μια προσπάθεια να ακυρωθεί η δήλωση του δεσμευμένου προθέματος χώρου ονομάτων xml ή να το συνδέσει με ένα άλλο URI χώρου ονομάτων.

xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS

Έγινε μια προσπάθεια να δηλωθεί ή να ακυρωθεί η δήλωση του δεσμευμένου προθέματος χώρου ονομάτων xmlns.

xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI

Έγινε μια προσπάθεια να δεσμευτεί το URI ενός από τα δεσμευμένα προθέματα χώρου ονομάτων xml και xmlns σε ένα άλλο πρόθεμα χώρου ονομάτων.

xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT

Αυτό δεν θα πρέπει να αναφέρεται σε εφαρμογές Python.

xml.parsers.expat.errors.XML_ERROR_NO_BUFFER

Αυτό δεν θα πρέπει να αναφέρεται σε εφαρμογές Python.

xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH

Το όριο στον παράγοντα ενίσχυσης εισόδου (από DTD και οντότητες) έχει παραβιαστεί.

xml.parsers.expat.errors.XML_ERROR_NOT_STARTED

Ο αναλυτής προσπάθησε να σταματήσει ή να ανασταλεί πριν ξεκινήσει.

Added in version 3.14.

Υποσημειώσεις