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 δεν συνιστάται πλέον.

This module provides the following exception, type object and data items:

exception xml.parsers.expat.ExpatError

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

exception xml.parsers.expat.error

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

xml.parsers.expat.XMLParserType

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

xml.parsers.expat.EXPAT_VERSION

The version string of the Expat library loaded by the interpreter, like 'expat_2.8.4'.

xml.parsers.expat.version_info

The version of the Expat library loaded by the interpreter, as a tuple of three integers: major, minor and micro version.

xml.parsers.expat.features

The list of the features with which the loaded Expat library was compiled, as (name, value) pairs. The value is only meaningful for features which have one, like 'XML_CONTEXT_BYTES' or the default protection limits 'XML_BLAP_ACT_THRES' and 'XML_AT_MAX_AMP'; for other features, like 'XML_DTD' and 'XML_NS', the value is 0 and only the presence of the name is significant.

The xml.parsers.expat module contains two functions:

xml.parsers.expat.ErrorString(errno)

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

xml.parsers.expat.ParserCreate(encoding=None, namespace_separator=None, intern=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

intern, if given, must be a dictionary. It is used to intern the names of elements and attributes, and is available as the intern attribute. By default a new empty dictionary is created for every parser.

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

Δείτε επίσης

The Expat XML Parser

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

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

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

xmlparser.Parse(data[, isfinal])

Parses the contents of data, calling the appropriate handler functions to process the parsed data. data can be a bytes-like object or a string. If it is a string, the encoding declaration in the XML data is ignored, and the data is parsed as already decoded text. isfinal must be true on the final call to this method; it allows the parsing of a single file in fragments, not the submission of multiple files. data can be empty at any time.

xmlparser.ParseFile(file)

Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, which returns bytes, and an empty bytes object when there’s no more data. Text files are not supported; use Parse() for data which is already decoded.

xmlparser.SetBase(base)

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

xmlparser.GetBase()

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

xmlparser.GetInputContext()

Returns the input data which generated the current event as a bytes object. The data is in the encoding of the entity which contains the text. It extends to the end of the currently buffered input, therefore it can contain also the data of the following events, and if the event was generated by a large amount of text, not all of it may be available. When called while an event handler is not active, the return value is 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 objects have the following methods to tune protections against some common XML vulnerabilities.

xmlparser.SetBillionLaughsAttackProtectionActivationThreshold(threshold, /)

Sets the number of output bytes needed to activate protection against billion laughs attacks.

The number of output bytes includes amplification from entity expansion and reading DTD files.

Parser objects usually have a protection activation threshold of 8 MiB, but the actual default value depends on the underlying Expat library.

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

Σημείωση

Activation thresholds below 4 MiB are known to break support for DITA 1.3 payload and are hence not recommended.

Added in version 3.14.6.

xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification(max_factor, /)

Sets the maximum tolerated amplification factor for protection against billion laughs attacks.

The amplification factor is calculated as (direct + indirect) / direct while parsing, where direct is the number of bytes read from the primary document in parsing and indirect is the number of bytes added by expanding entities and reading of external DTD files.

The max_factor value must be a non-NaN float value greater than or equal to 1.0. Peak amplifications of factor 15,000 for the entire payload and of factor 30,000 in the middle of parsing have been observed with small benign files in practice. In particular, the activation threshold should be carefully chosen to avoid false positives.

Parser objects usually have a maximum amplification factor of 100, but the actual default value depends on the underlying Expat library.

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

Σημείωση

The maximum amplification factor is only considered if the threshold that can be adjusted by SetBillionLaughsAttackProtectionActivationThreshold() is exceeded.

Added in version 3.14.6.

xmlparser.SetAllocTrackerActivationThreshold(threshold, /)

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

Parser objects usually have an allocation activation threshold of 64 MiB, but the actual default value depends on the underlying Expat library.

Γίνεται 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 μπορούν να παρατηρηθούν κοντά στην αρχή της ανάλυσης ακόμη και με ακίνδυνα αρχεία στην πράξη. Ειδικότερα, το όριο ενεργοποίησης πρέπει να επιλεγεί προσεκτικά για να αποφευχθούν ψευδώς θετικά.

Parser objects usually have a maximum amplification factor of 100, but the actual default value depends on the underlying Expat library.

Γίνεται 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.intern

The dictionary used to intern the names of elements and attributes. It is either the dictionary passed as the intern argument of ParserCreate(), or a new dictionary created for this parser.

xmlparser.namespace_prefixes

If set to a true value, and namespace processing is enabled, the namespace prefix is reported as the third part of the expanded name, separated by the namespace separator. Names which have no prefix are not affected. By default, this attribute is false; it may be changed at any time.

Τα ακόλουθα χαρακτηριστικά περιέχουν τιμές που σχετίζονται με το πιο πρόσφατο σφάλμα που αντιμετωπίστηκε από ένα αντικείμενο 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)

Called when the XML declaration is parsed. The XML declaration is the (optional) declaration of the applicable version of the XML recommendation, the encoding of the document text, and an optional «standalone» declaration. version and encoding will be strings, and standalone will be 1 if the document is declared standalone, 0 if it is declared not to be standalone, or -1 if the standalone clause was omitted.

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.

xmlparser.EndDoctypeDeclHandler()

Called when Expat is done parsing the document type declaration.

xmlparser.ElementDeclHandler(name, model)

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

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

Called for each declared attribute for an element type. If an attribute list declaration declares three attributes, this handler is called three times, once for each attribute. elname is the name of the element to which the declaration applies and attname is the name of the attribute declared. The The attribute type is a string passed as type: 'CDATA', 'ID', 'IDREF', 'IDREFS', 'ENTITY', 'ENTITIES', 'NMTOKEN' or 'NMTOKENS', an enumeration like '(x|y)', or a notation list like 'NOTATION(n1|n2)'. default gives the default value for the attribute used when the attribute is not specified by the document instance, or None if there is no default value (#IMPLIED values). If the attribute is required to be given in the document instance, required will be true.

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)

Called for unparsed (NDATA) entity declarations. If this handler is not set, such declarations are reported by EntityDeclHandler, which is preferred for new code. (The underlying function in the Expat library has been declared obsolete.)

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

Called for all entity declarations. For parameter and internal entities, value will be a string giving the declared contents of the entity; this will be None for external entities. The notationName parameter will be None for parsed entities, and the name of the notation for unparsed entities. is_parameter_entity will be true if the entity is a parameter entity or false for general entities (most applications only need to be concerned with general entities).

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)

This is the same as the DefaultHandler, but doesn’t inhibit expansion of internal entities. The entity reference will not be passed to the default handler.

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, εάν παρέχεται.

xmlparser.SkippedEntityHandler(entityName, is_parameter_entity)

Called for entity references which are not expanded, because the parser did not read the declaration of the entity. This happens when the external DTD subset or an external parameter entity is not parsed. is_parameter_entity is true for a parameter entity and false for a general entity.

Εξαιρέσεις 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

The named element allows character data, optionally interspersed with the named children; this is used for content models such as (#PCDATA) and (#PCDATA | A | B)*.

xml.parsers.expat.model.XML_CTYPE_NAME

The model names a single element, as for A.

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, ή “�”).

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

The document contains no elements (XML requires all documents to contain exactly one top-level element).

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

There was an error parsing the XML declaration.

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.

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

[1]

Η συμβολοσειρά κωδικοποίησης που περιλαμβάνεται στην έξοδο XML θα πρέπει να συμμορφώνεται με τα κατάλληλα πρότυπα. Για παράδειγμα, το «UTF-8» είναι έγκυρο, αλλά το «UTF8» δεν είναι. Δείτε https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl και https://www.iana.org/assignments/character-sets/character-sets.xhtml.