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 方法接收数据。在使用 close 方法调用完成解析后,必须调用 reset 方法以使解析器准备好接收新数据,无论是来自 feed 还是使用 parse 方法。

请注意,这些方法在解析期间 *不得* 调用,也就是说,在调用 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 接口的实现(请参阅 Attributes 接口 部分)。这是一个类似字典的对象,表示 startElement() 调用中的元素属性。除了最有用的字典操作之外,它还支持接口描述的许多其他方法。此类的对象应由读取器实例化;*attrs* 必须是一个类似字典的对象,其中包含从属性名称到属性值的映射。

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

AttributesImpl 的命名空间感知变体,它将被传递给 startElementNS()。它派生自 AttributesImpl,但将属性名称理解为 *namespaceURI* 和 *localname* 的二元组。此外,它还提供了一些方法,这些方法期望限定名称在原始文档中出现。此类实现了 AttributesNS 接口(请参阅 AttributesNS 接口 部分)。

XMLReader 对象

XMLReader 接口支持以下方法

XMLReader.parse(source)

处理输入源,生成 SAX 事件。*source* 对象可以是系统标识符(标识输入源的字符串 - 通常是文件名或 URL)、pathlib.Path类路径 对象,或 InputSource 对象。当 parse() 返回时,输入已完全处理,解析器对象可以被丢弃或重置。

在 3.5 版更改: 添加了对字符流的支持。

在 3.8 版更改: 添加了对类路径对象的的支持。

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。已知的 featurename 列在模块 xml.sax.handler 中。

XMLReader.setFeature(featurename, value)

featurename 设置为 value。如果无法识别该功能,则会引发 SAXNotRecognizedException。如果解析器不支持该功能或其设置,则会引发 SAXNotSupportedException

XMLReader.getProperty(propertyname)

返回属性 propertyname 的当前设置。如果无法识别该属性,则会引发 SAXNotRecognizedException。已知的 propertyname 列在模块 xml.sax.handler 中。

XMLReader.setProperty(propertyname, value)

propertyname 设置为 value。如果无法识别该属性,则会引发 SAXNotRecognizedException。如果解析器不支持该属性或其设置,则会引发 SAXNotSupportedException

增量解析器对象

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

IncrementalParser.feed(data)

处理一块 data

IncrementalParser.close()

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

IncrementalParser.reset()

此方法在调用 close 后调用,用于重置解析器,使其准备好解析新文档。在调用 close 后但在调用 reset 之前调用 parse 或 feed 的结果是未定义的。

定位器对象

Locator 的实例提供以下方法

Locator.getColumnNumber()

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

Locator.getLineNumber()

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

Locator.getPublicId()

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

Locator.getSystemId()

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

InputSource 对象

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)

为此输入源设置字节流(二进制文件)。

如果还指定了字符流,则 SAX 解析器将忽略此项,但它将优先使用字节流,而不是自己打开 URI 连接。

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

InputSource.getByteStream()

获取此输入源的字节流。

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

InputSource.setCharacterStream(charfile)

为此输入源设置字符流(文本文件)。

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

InputSource.getCharacterStream()

获取此输入源的字符流。

Attributes 接口

Attributes 对象实现了 映射协议 的一部分,包括方法 copy()get()__contains__()items()keys()values()。还提供了以下方法

Attributes.getLength()

返回属性的数量。

Attributes.getNames()

返回属性的名称。

Attributes.getType(name)

返回属性 *name* 的类型,通常为 'CDATA'

Attributes.getValue(name)

返回属性 *name* 的值。

AttributesNS 接口

此接口是 Attributes 接口的子类型(请参阅 Attributes 接口 部分)。该接口支持的所有方法也可用于 AttributesNS 对象。

还提供了以下方法

AttributesNS.getValueByQName(name)

返回限定名称的值。

AttributesNS.getNameByQName(name)

返回限定 *name* 的 (namespace, localname) 对。

AttributesNS.getQNameByName(name)

返回 (命名空间, 本地名称) 对的限定名称。

AttributesNS.getQNames()

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