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 或 path-like 物件，或 InputSource 物件。當 parse() 返回時，輸入將完全處理完畢，並且可以丟棄或重置解析器物件。

在 3.5 版本中更改: 添加了對字元流的支援。

在 3.8 版本中更改: 添加了對 path-like 物件的支援。

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* 設定為 *value*。 如果該功能未被識別，則引發 SAXNotRecognizedException。如果解析器不支援該功能或其設定，則引發 *SAXNotSupportedException*。

XMLReader.getProperty(propertyname)

返回屬性 *propertyname* 的當前設定。 如果該屬性未被識別，則會引發 SAXNotRecognizedException。 模組 xml.sax.handler 中列出了眾所周知的屬性名稱。

XMLReader.setProperty(propertyname, value)

將 *propertyname* 設定為 *value*。如果該屬性未被識別，則引發 SAXNotRecognizedException。 如果解析器不支援該屬性或其設定，則引發 *SAXNotSupportedException*。

IncrementalParser 物件

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

IncrementalParser.feed(data)

處理一塊 *data*。

IncrementalParser.close()

假設文件結束。這將檢查只能在末尾檢查的格式良好條件，呼叫處理程式，並可能清理解析期間分配的資源。

IncrementalParser.reset()

此方法在呼叫 close 後呼叫，以重置解析器，使其準備好解析新文件。在呼叫 close 後未呼叫 reset 而呼叫 parse 或 feed 的結果是未定義的。

Locator 物件

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)

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

AttributesNS.getQNames()

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