xml.sax.handler — Βασικές κλάσεις για χειριστές SAX

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

Το SAX API ορίζει πέντε είδη χειριστών: χειριστές περιεχομένου, χειριστές DTD, χειριστές σφαλμάτων, χειριστές επίλυσης οντοτήτων και χειριστές λεξικών. Οι εφαρμογές συνήθως χρειάζεται να υλοποιήσουν μόνο τις διεπαφές των γεγονότων που τους ενδιαφέρουν. Μπορούν να υλοποιήσουν τις διεπαφές σε ένα μόνο αντικείμενο ή σε πολλαπλά αντικείμενα. Οι υλοποιήσεις χειριστών θα πρέπει να κληρονομούν από τις βασικές κλάσεις που παρέχονται στο module xml.sax.handler, έτσι ώστε όλες οι μέθοδοι να αποκτούν προεπιλεγμένες υλοποιήσεις.

class xml.sax.handler.ContentHandler

Αυτή είναι η κύρια διεπαφή callback στο SAX και η πιο σημαντική για τις εφαρμογές. Η σειρά των γεγονότων σε αυτή τη διεπαφή αντικατοπτρίζει τη σειρά των πληροφοριών στο έγγραφο.

class xml.sax.handler.DTDHandler

Χειρισμός DTD γεγονότων.

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

class xml.sax.handler.EntityResolver

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

class xml.sax.handler.ErrorHandler

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

class xml.sax.handler.LexicalHandler

Διεπαφή που χρησιμοποιείται από τον αναλυτή για να παρουσιάσει γεγονότα χαμηλής συχνότητας που μπορεί να μην ενδιαφέρουν πολλές εφαρμογές.

Εκτός από αυτές τις κλάσεις, το xml.sax.handler παρέχει συμβολικές σταθερές για τα ονόματα χαρακτηριστικών και ιδιοτήτων.

xml.sax.handler.feature_namespaces
value: "http://xml.org/sax/features/namespaces"
true: Εκτέλεση επεξεργασίας ονομάτων χώρου.
false: Προαιρετικά μη εκτέλεση επεξεργασίας ονομάτων χώρου (υπονοεί namespace-prefixes; προεπιλογή).
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή
xml.sax.handler.feature_namespace_prefixes
value: "http://xml.org/sax/features/namespace-prefixes"
true: Αναφορά των αρχικών ονομάτων με πρόθεμα και ιδιοτήτων που χρησιμοποιούνται για δηλώσεις ονομάτων χώρου.
false: Μη αναφορά ιδιοτήτων που χρησιμοποιούνται για δηλώσεις ονομάτων χώρου, και προαιρετικά μη αναφορά αρχικών ονομάτων με πρόθεμα (προεπιλογή).
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή
xml.sax.handler.feature_string_interning
value: "http://xml.org/sax/features/string-interning"
true: Όλα τα ονόματα στοιχείων, πρόθεμα, ονόματα ιδιοτήτων, URIs ονομάτων χώρου και τοπικά ονόματα εσωτερικεύονται χρησιμοποιώντας την ενσωματωμένη συνάρτηση εσωτερικοποίησης (intern).
false: Τα ονόματα δεν εσωτερικεύονται απαραίτητα, αν και μπορεί να είναι (προεπιλογή).
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή
xml.sax.handler.feature_validation
value: "http://xml.org/sax/features/validation"
true: Αναφορά όλων των σφαλμάτων επικύρωσης (υπονοεί external-general-entities και external-parameter-entities).
false: Μη αναφορά σφαλμάτων επικύρωσης.
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή
xml.sax.handler.feature_external_ges
value: "http://xml.org/sax/features/external-general-entities"
true: Συμπερίληψη όλων των εξωτερικών γενικών (κείμενο) οντοτήτων.
false: Μη συμπερίληψη εξωτερικών γενικών οντοτήτων.
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή
xml.sax.handler.feature_external_pes
value: "http://xml.org/sax/features/external-parameter-entities"
true: Συμπερίληψη όλων των εξωτερικών παραμέτρων οντοτήτων, συμπεριλαμβανομένου του εξωτερικού υποσυνόλου DTD.
false: Μη συμπερίληψη εξωτερικών παραμέτρων οντοτήτων, ακόμη και του εξωτερικού υποσυνόλου DTD.
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή
xml.sax.handler.all_features

Λίστα όλων των χαρακτηριστικών.

xml.sax.handler.property_lexical_handler
value: "http://xml.org/sax/properties/lexical-handler"
data type: xml.sax.handler.LexicalHandler (δεν υποστηρίζεται στην Python 2)
description: Ένας προαιρετικός χειριστής επέκτασης για λεξικά συμβάντα όπως τα σχόλια.
access: read/write
xml.sax.handler.property_declaration_handler
value: "http://xml.org/sax/properties/declaration-handler"
data type: xml.sax.sax2lib.DeclHandler (δεν υποστηρίζεται στην Python 2)
description: Ένας προαιρετικός χειριστής επέκτασης για γεγονότα που σχετίζονται με το DTD εκτός από τις δηλώσεις και τις μη αναλυμένες οντότητες.
access: read/write
xml.sax.handler.property_dom_node
value: "http://xml.org/sax/properties/dom-node"
data type: org.w3c.dom.Node (δεν υποστηρίζεται στην Python 2)
description: Κατά την ανάλυση, ο τρέχων DOM κόμβος που επισκέπτεται εάν αυτός είναι ένας επαναληπτικός DOM κόμβος∙ όταν δεν αναλύεται, ο ριζικός DOM κόμβος για την επανάληψη.
access: (ανάλυση) μόνο για ανάγνωση; (μη ανάλυση) ανάγνωση/εγγραφή
xml.sax.handler.property_xml_string
value: "http://xml.org/sax/properties/xml-string"
data type: Bytes
description: Η κυριολεκτική συμβολοσειρά χαρακτήρων που ήταν η πηγή για το τρέχον γεγονός.
access: μόνο για ανάγνωση
xml.sax.handler.all_properties

Λίστα όλων των γνωστών ονομάτων ιδιοτήτων.

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

Οι χρήστες αναμένεται να δημιουργήσουν υποκλάση ContentHandler για να υποστηρίξουν την εφαρμογή τους. Οι ακόλουθες μέθοδοι καλούνται από τον αναλυτή στα κατάλληλα γεγονότα στο έγγραφο εισόδου:

ContentHandler.setDocumentLocator(locator)

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

Οι αναλυτές SAX ενθαρρύνονται έντονα (αν και δεν απαιτείται απολύτως) να παρέχουν έναν εντοπιστή: εάν το κάνουν, πρέπει να παρέχουν τον εντοπιστή στην εφαρμογή καλώντας αυτή τη μέθοδο πριν από την κλήση οποιωνδήποτε άλλων μεθόδων στη διεπαφή DocumentHandler.

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

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

ContentHandler.startDocument()

Λήψη ειδοποίησης για την αρχή ενός εγγράφου.

Ο αναλυτής SAX θα καλέσει αυτή τη μέθοδο μόνο μία φορά, πριν από οποιαδήποτε άλλη μέθοδο σε αυτή τη διεπαφή ή σε DTDHandler (εκτός από setDocumentLocator()).

ContentHandler.endDocument()

Λήψη ειδοποίησης για το τέλος ενός εγγράφου.

Ο αναλυτής SAX θα καλέσει αυτή τη μέθοδο μόνο μία φορά, και θα είναι η τελευταία μέθοδος που θα κληθεί κατά τη διάρκεια της ανάλυσης. Ο αναλυτής δεν θα καλέσει αυτή τη μέθοδο μέχρι να εγκαταλείψει την ανάλυση (εξαιτίας ενός μη ανακτήσιμου σφάλματος) ή να φτάσει στο τέλος της εισόδου.

ContentHandler.startPrefixMapping(prefix, uri)

Αρχή της έκτασης ενός προθέματος-URI χαρτογράφησης ονόματος χώρου.

Οι πληροφορίες από αυτό το γεγονός δεν είναι απαραίτητες για την κανονική επεξεργασία ονομάτων χώρου: ο αναγνώστης SAX XML θα αντικαταστήσει αυτόματα τα προθέματα για τα ονόματα στοιχείων και ιδιοτήτων όταν είναι ενεργοποιημένο το χαρακτηριστικό feature_namespaces (η προεπιλογή).

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

Σημειώστε ότι τα γεγονότα startPrefixMapping() και endPrefixMapping() δεν εγγυώνται ότι θα είναι σωστά εγκατεστημένα σε σχέση με το ένα το άλλο: όλα τα γεγονότα startPrefixMapping() θα συμβούν πριν από το αντίστοιχο startElement() γεγονός, και όλα τα γεγονότα endPrefixMapping() θα συμβούν μετά το αντίστοιχο endElement() γεγονός, αλλά η σειρά τους δεν είναι εγγυημένη.

ContentHandler.endPrefixMapping(prefix)

Τέλος της έκτασης μιας χαρτογράφησης προθέματος-URI.

Δείτε startPrefixMapping() για λεπτομέρειες. Αυτό το γεγονός θα συμβεί πάντα μετά το αντίστοιχο γεγονός endElement(), αλλά η σειρά των γεγονότων endPrefixMapping() δεν είναι εγγυημένη.

ContentHandler.startElement(name, attrs)

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

The name parameter contains the raw XML 1.0 name of the element type as a string and the attrs parameter holds an object of the Attributes interface containing the attributes of the element. The object passed as attrs may be re-used by the parser; holding on to a reference to it is not a reliable way to keep a copy of the attributes. To keep a copy of the attributes, use the copy() method of the attrs object.

ContentHandler.endElement(name)

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

Η παράμετρος name περιέχει το όνομα του τύπου στοιχείου, όπως και με το startElement() γεγονός.

ContentHandler.startElementNS(name, qname, attrs)

Σηματοδοτεί την αρχή ενός στοιχείου σε λειτουργία ονομάτων χώρου.

The name parameter contains the name of the element type as a (uri, localname) tuple, the qname parameter contains the raw XML 1.0 name used in the source document, and the attrs parameter holds an instance of the AttributesNS interface containing the attributes of the element. If no namespace is associated with the element, the uri component of name will be None. The object passed as attrs may be re-used by the parser; holding on to a reference to it is not a reliable way to keep a copy of the attributes. To keep a copy of the attributes, use the copy() method of the attrs object.

Οι αναλυτές μπορούν να ορίσουν την παράμετρο qname σε None, εκτός εάν είναι ενεργοποιημένο το χαρακτηριστικό feature_namespace_prefixes.

ContentHandler.endElementNS(name, qname)

Σηματοδοτεί το τέλος ενός στοιχείου σε λειτουργία ονομάτων χώρου.

Η παράμετρος name περιέχει το όνομα του τύπου στοιχείου, όπως και με τη startElementNS() μέθοδο, όπως και η παράμετρος qname.

ContentHandler.characters(content)

Λήψη ειδοποίησης για δεδομένα χαρακτήρων.

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

Το content μπορεί να είναι μια συμβολοσειρά ή ένα στιγμιότυπο bytes. Το αναγνωστικό expat παράγει πάντα συμβολοσειρές.

Σημείωση

Η προηγούμενη διεπαφή SAX 1 που παρείχε η ομάδα ειδικού ενδιαφέροντος Python XML Group χρησιμοποιούσε μια διεπαφή που έμοιαζε περισσότερο με τη Java για αυτή τη μέθοδο. Δεδομένου ότι οι περισσότεροι αναλυτές που χρησιμοποιούνται από την Python δεν εκμεταλλεύονταν την παλαιότερη διεπαφή, επιλέχθηκε η απλούστερη υπογραφή για να την αντικαταστήσει. Για να μετατρέψετε τον παλιό κώδικα στη νέα διεπαφή, χρησιμοποιήστε content αντί να τεμαχίζετε το περιεχόμενο με τις παλιές παραμέτρους offset και length.

ContentHandler.ignorableWhitespace(whitespace)

Λήψη ειδοποίησης για αγνοήσιμα κενά σε περιεχόμενο στοιχείου.

Οι Επικυρωτικοί Αναλυτές πρέπει να χρησιμοποιούν αυτή τη μέθοδο για να αναφέρουν κάθε κομμάτι αγνοήσιμου κενού (βλ. την W3C XML 1.0 σύσταση, τμήμα 2.10): οι μη επικυρωτικοί αναλυτές μπορούν επίσης να χρησιμοποιούν αυτή τη μέθοδο εάν είναι ικανοί να αναλύουν και να χρησιμοποιούν μοντέλα περιεχομένου.

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

ContentHandler.processingInstruction(target, data)

Λήψη ειδοποίησης για μια οδηγία επεξεργασίας.

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

Ένας αναλυτής SAX δεν πρέπει ποτέ να αναφέρει μια δήλωση XML (XML 1.0, τμήμα 2.8) ή μια δήλωση κειμένου (XML 1.0, τμήμα 4.3.1) χρησιμοποιώντας αυτή τη μέθοδο.

ContentHandler.skippedEntity(name)

Λήψη ειδοποίησης για μια παράλειψη οντότητας.

Ο Αναλυτής θα καλέσει αυτή τη μέθοδο μία φορά για κάθε παράλειψη οντότητας. Οι μη επικυρωτικοί επεξεργαστές μπορεί να παραλείψουν οντότητες εάν δεν έχουν δει τις δηλώσεις (για παράδειγμα, η οντότητα δηλώθηκε σε ένα εξωτερικό υποσύνολο DTD). Όλοι οι επεξεργαστές μπορεί να παραλείψουν εξωτερικές οντότητες, ανάλογα με τις τιμές των ιδιοτήτων feature_external_ges και feature_external_pes.

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

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

DTDHandler.notationDecl(name, publicId, systemId)

Χειρισμός ενός γεγονότος δήλωσης σημείωσης.

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

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

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

EntityResolver.resolveEntity(publicId, systemId)

Επιλύστε τον αναγνωριστικό συστήματος μιας οντότητας και επιστρέψτε είτε τον αναγνωριστικό συστήματος για ανάγνωση ως συμβολοσειρά, είτε μια InputSource για ανάγνωση. Η προεπιλεγμένη υλοποίηση επιστρέφει το systemId.

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

Τα αντικείμενα με αυτή τη διεπαφή χρησιμοποιούνται για να λαμβάνουν πληροφορίες σφάλματος και προειδοποίησης από το XMLReader. Εάν δημιουργήσετε ένα αντικείμενο που υλοποιεί αυτή τη διεπαφή, τότε εγγράψτε το αντικείμενο με το σας XMLReader, ο αναλυτής θα καλέσει τις μεθόδους στο αντικείμενό σας για να αναφέρει όλες τις προειδοποιήσεις και τα σφάλματα. Υπάρχουν τρία επίπεδα σφαλμάτων διαθέσιμα: προειδοποιήσεις, (πιθανώς) ανακτήσιμα σφάλματα και μη ανακτήσιμα σφάλματα. Όλες οι μέθοδοι δέχονται ένα SAXParseException ως τη μόνη παράμετρο. Τα σφάλματα και οι προειδοποιήσεις μπορούν να μετατραπούν σε εξαίρεση κάνοντας raise το αντικείμενο της εξαίρεσης που περιέχεται.

ErrorHandler.error(exception)

Καλείται όταν ο αναλυτής συναντήσει ένα ανακτήσιμο σφάλμα. Εάν αυτή η μέθοδος δεν κάνει raise μια εξαίρεση, η ανάλυση μπορεί να συνεχιστεί, αλλά δεν θα πρέπει να αναμένεται περαιτέρω πληροφορίες εγγράφου από την εφαρμογή. Η επιτρεπόμενη συνέχιση του αναλυτή μπορεί να επιτρέψει την ανακάλυψη πρόσθετων σφαλμάτων στο έγγραφο εισόδου.

ErrorHandler.fatalError(exception)

Καλείται όταν ο αναλυτής συναντήσει ένα σφάλμα από το οποίο δεν μπορεί να ανακάμψει. Η ανάλυση αναμένεται να τερματιστεί όταν αυτή η μέθοδος επιστρέψει.

ErrorHandler.warning(exception)

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

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

Προαιρετικός χειριστής SAX2 για λεξικά γεγονότα.

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

Ορίστε τον LexicalHandler ενός XMLReader χρησιμοποιώντας τη μέθοδο setProperty με τον αναγνωριστικό ιδιότητας 'http://xml.org/sax/properties/lexical-handler'.

LexicalHandler.comment(content)

Αναφέρει ένα σχόλιο οπουδήποτε στο έγγραφο (συμπεριλαμβανομένου του DTD και εκτός του στοιχείου εγγράφου).

LexicalHandler.startDTD(name, public_id, system_id)

Αναφέρει την αρχή των δηλώσεων DTD εάν το έγγραφο έχει συσχετισμένο DTD.

LexicalHandler.endDTD()

Αναφέρει το τέλος της δήλωσης DTD.

LexicalHandler.startCDATA()

Αναφέρει την αρχή ενός τμήματος σημειωμένου ως CDATA.

Τα περιεχόμενα του τμήματος σημειωμένου ως CDATA θα αναφερθούν μέσω του χειριστή χαρακτήρων.

LexicalHandler.endCDATA()

Αναφέρει το τέλος ενός τμήματος σημειωμένου ως CDATA.