xml.sax —- Support for SAX2 parsers

Source code:Lib/xml/sax/init.py

The xml.sax package provides a number of modules which implement theSimple API for XML (SAX) interface for Python. The package itself provides theSAX exceptions and the convenience functions which will be most used by users ofthe SAX API.

警告

The xml.sax module is not secure against maliciouslyconstructed data. If you need to parse untrusted or unauthenticated data seeXML 漏洞.

在 3.7.1 版更改: The SAX parser no longer processes general external entities by defaultto increase security. Before, the parser created network connectionsto fetch remote files or loaded local files from the filesystem for DTD and entities. The feature can be enabled again with methodsetFeature() on the parser objectand argument feature_external_ges.

The convenience functions are:

  • xml.sax.makeparser(_parser_list=[])
  • Create and return a SAX XMLReader object. Thefirst parser found willbe used. If parser_list is provided, it must be a list of strings whichname modules that have a function named createparser(). Modules listedin _parser_list will be used before modules in the default list of parsers.
  • xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())
  • Create a SAX parser and use it to parse a document. The document, passed in asfilename_or_stream, can be a filename or a file object. The handler_parameter needs to be a SAX ContentHandler instance. If_error_handler is given, it must be a SAX ErrorHandlerinstance; ifomitted, SAXParseException will be raised on all errors. There is noreturn value; all work must be done by the handler passed in.
  • xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())
  • Similar to parse(), but parses from a buffer string received as aparameter. string must be a str instance or abytes-like object.

在 3.5 版更改: Added support of str instances.

A typical SAX application uses three kinds of objects: readers, handlers andinput sources. "Reader" in this context is another term for parser, i.e. somepiece of code that reads the bytes or characters from the input source, andproduces a sequence of events. The events then get distributed to the handlerobjects, i.e. the reader invokes a method on the handler. A SAX applicationmust therefore obtain a reader object, create or open the input sources, createthe handlers, and connect these objects all together. As the final step ofpreparation, the reader is called to parse the input. During parsing, methods onthe handler objects are called based on structural and syntactic events from theinput data.

For these objects, only the interfaces are relevant; they are normally notinstantiated by the application itself. Since Python does not have an explicitnotion of interface, they are formally introduced as classes, but applicationsmay use implementations which do not inherit from the provided classes. TheInputSource, Locator,Attributes, AttributesNS,and XMLReader interfaces are defined in themodule xml.sax.xmlreader. The handler interfaces are defined inxml.sax.handler. For convenience,InputSource (which is ofteninstantiated directly) and the handler classes are also available fromxml.sax. These interfaces are described below.

In addition to these classes, xml.sax provides the following exceptionclasses.

  • exception xml.sax.SAXException(msg, exception=None)
  • Encapsulate an XML error or warning. This class can contain basic error orwarning information from either the XML parser or the application: it can besubclassed to provide additional functionality or to add localization. Notethat although the handlers defined in theErrorHandler interfacereceive instances of this exception, it is not required to actually raise theexception —- it is also useful as a container for information.

When instantiated, msg should be a human-readable description of the error.The optional exception parameter, if given, should be None or an exceptionthat was caught by the parsing code and is being passed along as information.

This is the base class for the other SAX exception classes.

  • exception xml.sax.SAXParseException(msg, exception, locator)
  • Subclass of SAXException raised on parse errors. Instances of thisclass are passed to the methods of the SAXErrorHandler interface to provide informationabout the parse error. This class supports the SAXLocator interface as well as theSAXException interface.
  • exception xml.sax.SAXNotRecognizedException(msg, exception=None)
  • Subclass of SAXException raised when a SAXXMLReader isconfronted with an unrecognized feature or property. SAX applications andextensions may use this class for similar purposes.
  • exception xml.sax.SAXNotSupportedException(msg, exception=None)
  • Subclass of SAXException raised when a SAXXMLReader is asked toenable a feature that is not supported, or to set a property to a value that theimplementation does not support. SAX applications and extensions may use thisclass for similar purposes.

参见

  • SAX: The Simple API for XML

  • This site is the focal point for the definition of the SAX API. It provides aJava implementation and online documentation. Links to implementations andhistorical information are also available.

  • Module xml.sax.handler

  • Definitions of the interfaces for application-provided objects.

  • Module xml.sax.saxutils

  • Convenience functions for use in SAX applications.

  • Module xml.sax.xmlreader

  • Definitions of the interfaces for parser-provided objects.

SAXException Objects

The SAXException exception class supports the following methods:

  • SAXException.getMessage()
  • Return a human-readable message describing the error condition.
  • SAXException.getException()
  • Return an encapsulated exception object, or None.