xml.sax.xmlreader --- 用于 XML 解析器的接口

源代碼: Lib/xml/sax/xmlreader.py

---

SAX 解析器實(shí)現(xiàn)了 XMLReader 接口。 它們是在一個(gè) Python 模塊中實(shí)現(xiàn)的，該模塊必須提供一個(gè) create_parser() 函數(shù)。 該函數(shù)由 xml.sax.make_parser() 不帶參數(shù)地發(fā)起調(diào)用來創(chuàng)建新的解析器對象。

class xml.sax.xmlreader.XMLReader

可由 SAX 解析器繼承的基類。

class xml.sax.xmlreader.IncrementalParser

在某些情況下，最好不要一次性地解析輸入源，而是在可用的時(shí)候分塊送入。 請注意讀取器通常不會讀取整個(gè)文件，它同樣也是分塊讀取的； 并且 parse() 在處理完整個(gè)文檔之前不會返回。 所以如果不希望 parse() 出現(xiàn)阻塞行為則應(yīng)當(dāng)使用這些接口。

當(dāng)解析器被實(shí)例化時(shí)它已準(zhǔn)備好立即開始接受來自 feed 方法的數(shù)據(jù)。 在通過調(diào)用 close 方法結(jié)束解析時(shí) reset 方法也必須被調(diào)用以使解析器準(zhǔn)備好接受新的數(shù)據(jù)，無論它是來自于 feed 還是使用 parse 方法。

請注意這些方法 不可 在解析期間被調(diào)用，即在 parse 被調(diào)用之后及其返回之前。

默認(rèn)情況下，該類還使用 IncrementalParser 接口的 feed, close 和 reset 方法來實(shí)現(xiàn) XMLReader 接口的 parse 方法以方便 SAX 2.0 驅(qū)動的編寫者。

class xml.sax.xmlreader.Locator

用于關(guān)聯(lián)一個(gè) SAX 事件與一個(gè)文檔位置的接口。 定位器對象只有在調(diào)用 DocumentHandler 的方法期間才會返回有效的結(jié)果；在其他任何時(shí)候，結(jié)果都是不可預(yù)測的。 如果信息不可用，這些方法可能返回 None。

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

XMLReader 讀取實(shí)體所需信息的封裝。

這個(gè)類可能包括了關(guān)于公有標(biāo)識符、系統(tǒng)標(biāo)識符、字節(jié)流（可能帶有字符編碼格式信息）和/或一個(gè)實(shí)體的字符流的信息。

應(yīng)用程序?qū)?chuàng)建這個(gè)類的對象以便在 XMLReader.parse() 方法中使用或是用于從 EntityResolver.resolveEntity 返回值。

InputSource 屬于應(yīng)用程序，XMLReader 不能修改從應(yīng)用程序傳遞給它的 InputSource 對象，但它可以創(chuàng)建副本并進(jìn)行修改。

class xml.sax.xmlreader.AttributesImpl(attrs)

這是 Attributes 接口（參見 Attributes 接口 一節(jié)）的具體實(shí)現(xiàn)。 這是一個(gè) startElement() 調(diào)用中的元素屬性的字典類對象。 除了最有用處的字典操作，它還支持接口所描述的一些其他方法。 該類的對象應(yīng)當(dāng)由讀取器來實(shí)例化；attrs 必須為包含從屬性名到屬性值的映射的字典類對象。

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

可感知命名空間的 AttributesImpl 變體形式，它將被傳遞給 startElementNS()。 它派生自 AttributesImpl，但會將屬性名稱解讀為 namespaceURI 和 localname 二元組。 此外，它還提供了一些期望接收在原始文檔中出現(xiàn)的限定名稱的方法。 這個(gè)類實(shí)現(xiàn)了 AttributesNS 接口（參見 AttributesNS 接口 一節(jié)）。

XMLReader 對象

XMLReader 接口支持下列方法:

XMLReader.parse(source)

Process an input source, producing SAX events. The source object can be a system identifier (a string identifying the input source -- typically a file name or a URL), a file-like object, or an InputSource object. When parse() returns, the input is completely processed, and the parser object can be discarded or reset.

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

XMLReader.getContentHandler()

返回當(dāng)前的 ContentHandler。

XMLReader.setContentHandler(handler)

設(shè)置當(dāng)前的 ContentHandler。 如果沒有設(shè)置 ContentHandler，內(nèi)容事件將被丟棄。

XMLReader.getDTDHandler()

返回當(dāng)前的 DTDHandler。

XMLReader.setDTDHandler(handler)

設(shè)置當(dāng)前的 DTDHandler。 如果沒有設(shè)置 DTDHandler，DTD 事件將被德育。

XMLReader.getEntityResolver()

返回當(dāng)前的 EntityResolver。

XMLReader.setEntityResolver(handler)

設(shè)置當(dāng)前的 EntityResolver。 如果沒有設(shè)置 EntityResolver，嘗試解析一個(gè)外部實(shí)體將導(dǎo)致打開該實(shí)體的系統(tǒng)標(biāo)識符，并且如果它不可用則操作將失敗。

XMLReader.getErrorHandler()

返回當(dāng)前的 ErrorHandler。

XMLReader.setErrorHandler(handler)

設(shè)置當(dāng)前的錯(cuò)誤處理句柄。 如果沒有設(shè)置 ErrorHandler，錯(cuò)誤將作為異常被引發(fā)，并將打印警告信息。

XMLReader.setLocale(locale)

允許應(yīng)用程序?yàn)殄e(cuò)誤和警告設(shè)置語言區(qū)域。

SAX 解析器不要求為錯(cuò)誤和警告提供本地化信息；但是如果它們無法支持所請求的語言區(qū)域，則必須引發(fā)一個(gè) SAX 異常。 應(yīng)用程序可以在解析的中途請求更改語言區(qū)域。

XMLReader.getFeature(featurename)

返回 featurename 特性的當(dāng)前設(shè)置。 如果特性無法被識別，則會引發(fā) SAXNotRecognizedException。 在 xml.sax.handler 模塊中列出了常見的特性名稱。

XMLReader.setFeature(featurename, value)

將 featurename 設(shè)為 value。 如果特性無法被識別，則會引發(fā) SAXNotRecognizedException。 如果特性或其設(shè)置不被解析器所支持，則會引發(fā) SAXNotSupportedException。

XMLReader.getProperty(propertyname)

返回 propertyname 屬性的當(dāng)前設(shè)置。 如果屬性無法被識別，則會引發(fā) SAXNotRecognizedException。 在 xml.sax.handler 模塊中列出了常見的屬性名稱。

XMLReader.setProperty(propertyname, value)

將 propertyname 設(shè)為 value。 如果屬性無法被識別，則會引發(fā) SAXNotRecognizedException。 如果屬性或其設(shè)置不被解析器所支持，則會引發(fā) SAXNotSupportedException。

IncrementalParser 對象

IncrementalParser 的實(shí)例額外提供了下列方法:

IncrementalParser.feed(data)

處理 data 的一個(gè)分塊。

IncrementalParser.close()

確定文檔的結(jié)尾。 這將檢查只能在結(jié)尾處檢查的格式是否良好的條件，發(fā)起調(diào)用處理程序，并可能會清理在解析期間分配的資源。

IncrementalParser.reset()

此方法會在調(diào)用 close 來重置解析器以便其準(zhǔn)備好解析新的文檔之后被調(diào)用。 在 close 之后未調(diào)用 reset 即調(diào)用 parse 或 feed 的結(jié)果是未定義的。

Locator 對象

Locator 的實(shí)例提供了下列方法:

Locator.getColumnNumber()

返回當(dāng)前事件開始位置的列號。

Locator.getLineNumber()

返回當(dāng)前事件開始位置的行號。

Locator.getPublicId()

返回當(dāng)前事件的公有標(biāo)識符。

Locator.getSystemId()

返回當(dāng)前事件的系統(tǒng)標(biāo)識符。

InputSource 對象

InputSource.setPublicId(id)

設(shè)置該 InputSource 的公有標(biāo)識符。

InputSource.getPublicId()

返回此 InputSource 的公有標(biāo)識符。

InputSource.setSystemId(id)

設(shè)置此 InputSource 的系統(tǒng)標(biāo)識符。

InputSource.getSystemId()

返回此 InputSource 的系統(tǒng)標(biāo)識符。

InputSource.setEncoding(encoding)

設(shè)置此 InputSource 的字符編碼格式。

編碼格式必須是 XML 編碼聲明可接受的字符串（參見 XML 建議規(guī)范第 4.3.3 節(jié)）。

如果 InputSource 還包含一個(gè)字符流則 InputSource 的 encoding 屬性會被忽略。

InputSource.getEncoding()

獲取此 InputSource 的字符編碼格式。

InputSource.setByteStream(bytefile)

設(shè)置此輸入源的字節(jié)流（為 binary file 對象）。

如果還指定了一個(gè)字符流被則 SAX 解析器會忽略此設(shè)置，但它將優(yōu)先使用字節(jié)流而不是自己打開一個(gè) URI 連接。

如果應(yīng)用程序知道字節(jié)流的字符編碼格式，它應(yīng)當(dāng)使用 setEncoding 方法來設(shè)置它。

InputSource.getByteStream()

獲取此輸入源的字節(jié)流。

getEncoding 方法將返回該字節(jié)流的字符編碼格式，如果未知?jiǎng)t返回 None。

InputSource.setCharacterStream(charfile)

設(shè)置此輸入源的字符流 (為 text file 對象)。

如果指定了一個(gè)字符流，SAX 解析器將忽略任何字節(jié)流并且不會嘗試打開一個(gè)指向系統(tǒng)標(biāo)識符的 URI 連接。

InputSource.getCharacterStream()

獲取此輸入源的字符流。

Attributes 接口

Attributes 對象實(shí)現(xiàn)了一部分 映射協(xié)議，包括 copy(), get(), __contains__(), items(), keys() 和 values() 等方法。 還提供了下列方法:

Attributes.getLength()

返回屬性的數(shù)量。

Attributes.getNames()

返回屬性的名稱。

Attributes.getType(name)

返回屬性 name 的類型，通常為 'CDATA'。

Attributes.getValue(name)

返回屬性 name 的值。

AttributesNS 接口

此接口是 Attributes 接口（參見 Attributes 接口 章節(jié)）的一個(gè)子類型。 那個(gè)接口所支持的所有方法在 AttributesNS 對象上也都可用。

下列方法也是可用的:

AttributesNS.getValueByQName(name)

返回一個(gè)限定名稱的值。

AttributesNS.getNameByQName(name)

返回限定名稱 name 的 (namespace, localname) 對。

AttributesNS.getQNameByName(name)

返回 (namespace, localname) 對的限定名稱。

AttributesNS.getQNames()

返回所有屬性的限定名稱。