# 20.12. `xml.sax.xmlreader` - XML解析器的接口

源代码： Lib / xml / sax / xmlreader.py

SAX解析器实现`XMLReader`接口。它们在Python模块中实现，必须提供函数`create_parser()`。此函数由`xml.sax.make_parser()`调用，不带参数以创建新的解析器对象。

class `xml.sax.xmlreader.``XMLReader`

  可以由SAX解析器继承的基类。

class `xml.sax.xmlreader.``IncrementalParser`

  在一些情况下，期望不立即解析输入源，而是在文档可用时馈送文档的块。注意，读取器通常不会读取整个文件，而是读取它的块；仍然`parse()`将不会返回，直到整个文档被处理。因此，如果不希望`parse()`的阻塞行为，则应使用这些接口。

  当解析器被实例化时，它准备好立即开始从feed方法接受数据。解析完成后，调用关闭reset方法必须被调用以使解析器准备接受新数据，从feed或使用parse方法。

  请注意，这些方法必须在解析期间调用，而不是，也就是说，在解析被调用之后，在返回之前。

  默认情况下，类还使用IncrementalParser接口的feed，close和reset方法实现XMLReader接口的parse方法，以方便SAX 2.0驱动程序作者。

class `xml.sax.xmlreader.``Locator`

  用于将SAX事件与文档位置相关联的接口。定位器对象只有在调用DocumentHandler方法时才会返回有效的结果；在任何其他时间，结果是不可预测的。如果信息不可用，方法可能返回`None`。

class `xml.sax.xmlreader.``InputSource`(system_id=None)

  封装`XMLReader`读取实体所需的信息。

  该类可以包括关于公共标识符，系统标识符，字节流（可能具有字符编码信息）和/或实体的字符流的信息。

  应用程序将创建此类的对象以用于`XMLReader.parse()`方法和从EntityResolver.resolveEntity返回。

  `InputSource`属于应用程序，`XMLReader`不允许修改从应用程序传递给它的`InputSource`对象，修改这些。

class `xml.sax.xmlreader.``AttributesImpl`(attrs)

  这是`Attributes`接口的实现（参见The Attributes Interface一节）。这是一个类似字典的对象，它表示`startElement()`调用中的元素属性。除了最有用的字典操作，它支持接口所描述的许多其他方法。这个类的对象应该由读者实例化； attrs必须是包含从属性名称到属性值的映射的类字典对象。

class `xml.sax.xmlreader.``AttributesNSImpl`(attrs, qnames)

  知道`AttributesImpl`的命名空间变量，将传递到`startElementNS()`。它源自`AttributesImpl`，但将属性名称理解为namespaceURI和localname的两元组。此外，它提供了一些方法，期望在原始文档中出现的限定名称。此类实现`AttributesNS`接口（参见The AttributesNS Interface一节）。

## 20.12.1. XMLReader Objects

`XMLReader`接口支持以下方法：

`XMLReader.``parse`(source)

  处理输入源，生成SAX事件。源对象可以是系统标识符（标识输入源的字符串，通常是文件名或URL），类似文件的对象或`InputSource`对象。当`parse()`返回时，输入被完全处理，并且解析器对象可以被丢弃或重置。

  在版本3.5中更改：添加了字符流的支持。

`XMLReader.``getContentHandler`()

  返回当前`ContentHandler`。

`XMLReader.``setContentHandler`(handler)

  设置当前`ContentHandler`。如果未设置`ContentHandler`，内容事件将被丢弃。

`XMLReader.``getDTDHandler`()

  返回当前`DTDHandler`。

`XMLReader.``setDTDHandler`(handler)

  设置当前`DTDHandler`。如果未设置`DTDHandler`，则DTD事件将被丢弃。

`XMLReader.``getEntityResolver`()

  返回当前`EntityResolver`。

`XMLReader.``setEntityResolver`(handler)

  设置当前`EntityResolver`。如果未设置`EntityResolver`，则尝试解析外部实体将导致打开实体的系统标识符，如果不可用，则会失败。

`XMLReader.``getErrorHandler`()

  返回当前的`ErrorHandler`。

`XMLReader.``setErrorHandler`(handler)

  设置当前错误处理程序。如果未设置`ErrorHandler`，则错误将作为异常引发，并将打印警告。

`XMLReader.``setLocale`(locale)

  允许应用程序设置错误和警告的区域设置。

  SAX解析器不需要提供错误和警告的本地化；如果它们不能支持请求的语言环境，则它们必须引发SAX异常。应用程序可以在解析的中间请求区域设置更改。

`XMLReader.``getFeature`(featurename)

  返回featurename的当前设置。如果该功能未被识别，则会引发`SAXNotRecognizedException`。众所周知的特征名称在模块`xml.sax.handler`中列出。

`XMLReader.``setFeature`(featurename, value)

  将featurename设置为值。如果该功能未被识别，则会引发`SAXNotRecognizedException`。如果解析器不支持该功能或其设置，则会引发SAXNotSupportedException。

`XMLReader.``getProperty`(propertyname)

  返回属性属性名的当前设置。如果该属性未被识别，则会引发`SAXNotRecognizedException`。众所周知的属性名称在模块`xml.sax.handler`中列出。

`XMLReader.``setProperty`(propertyname, value)

  将属性名设置为值。如果该属性未被识别，则会引发`SAXNotRecognizedException`。如果解析器不支持属性或其设置，则会引发SAXNotSupportedException。

## 20.12.2. IncrementalParser Objects

`IncrementalParser`的实例提供以下附加方法：

`IncrementalParser.``feed`(data)

  处理一小块数据。

`IncrementalParser.``close`()

  假设文档结束。这将检查只能在结束时检查的良好形成条件，调用处理程序，并可以清理在解析期间分配的资源。

`IncrementalParser.``reset`()

  此方法在调用close之后调用以重置解析器，以便它可以解析新文档。关闭后调用解析或feed的结果未调用reset将被定义。

## 20.12.3. Locator Objects

`Locator`的实例提供以下方法：

`Locator.``getColumnNumber`()

  返回当前事件开始的列号。

`Locator.``getLineNumber`()

  返回当前事件开始的行号。

`Locator.``getPublicId`()

  返回当前事件的公共标识符。

`Locator.``getSystemId`()

  返回当前事件的系统标识符。

## 20.12.4. InputSource Objects

`InputSource.``setPublicId`(id)

  设置此`InputSource`的公共标识符。

`InputSource.``getPublicId`()

  返回此`InputSource`的公共标识符。

`InputSource.``setSystemId`(id)

  设置此`InputSource`的系统标识符。

`InputSource.``getSystemId`()

  返回此`InputSource`的系统标识符。

`InputSource.``setEncoding`(encoding)

  设置此`InputSource`的字符编码。

  编码必须是XML编码声明可接受的字符串（请参阅XML建议的第4.3.3节）。

  如果`InputSource`还包含字符流，则会忽略`InputSource`的编码属性。

`InputSource.``getEncoding`()

  获取此InputSource的字符编码。

`InputSource.``setByteStream`(bytefile)

  为此输入源设置字节流（binary file）。

  如果还有一个字符流被指定，SAX解析器将忽略它，但它将使用一个字节流优先于打开一个URI连接本身。

  如果应用程序知道字节流的字符编码，则应使用setEncoding方法设置它。

`InputSource.``getByteStream`()

  获取此输入源的字节流。

  getEncoding方法将返回此字节流的字符编码，如果未知，则返回None。

`InputSource.``setCharacterStream`(charfile)

  设置此输入源的字符流（text file）。

  如果指定了字符流，则SAX解析器将忽略任何字节流，并且不会尝试打开与系统标识符的URI连接。

`InputSource.``getCharacterStream`()

  获取此输入源的字符流。

## 20.12.5. The `Attributes` Interface

`Attributes` objects implement a portion of the mapping protocol, including the methods `copy()`, `get()`, `__contains__()`, `items()`, `keys()`, and `values()`. 还提供以下方法：

`Attributes.``getLength`()

  返回属性的数量。

`Attributes.``getNames`()

  返回属性的名称。

`Attributes.``getType`(name)

  返回属性name的类型，通常为`'CDATA'`。

`Attributes.``getValue`(name)

  返回属性name的值。

## 20.12.6. The `AttributesNS` Interface

此接口是`Attributes`接口的子类型（请参见The Attributes Interface一节）。该接口支持的所有方法也可在`AttributesNS`对象上使用。

还有以下方法：

`AttributesNS.``getValueByQName`(name)

  返回限定名称的值。

`AttributesNS.``getNameByQName`(name)

  返回符合条件的名称的`（命名空间， 本地名称）`

`AttributesNS.``getQNameByName`(name)

  返回`（命名空间， 本地名称）`对的限定名称。

`AttributesNS.``getQNames`()

  返回所有属性的限定名称。