xml.sax.handler
--- SAX 處理句柄的基類(lèi)?
SAX API 定義了五種處理句柄:內容句柄、DTD 句柄、錯誤句柄、實(shí)體解析器以及詞法句柄。 應用程序通常只需要實(shí)現他們感興趣的事件對應的接口;他們可以在單個(gè)對象或多個(gè)對象中實(shí)現這些接口。 處理句柄的實(shí)現應當繼承自 xml.sax.handler
模塊所提供的基類(lèi),以便所有方法都能獲得默認的實(shí)現。
- class xml.sax.handler.ContentHandler?
這是 SAX 中的主回調接口,也是對應用程序來(lái)說(shuō)最重要的一個(gè)接口。 此接口中事件的順序反映了文檔中信息的順序。
- class xml.sax.handler.DTDHandler?
處理 DTD 事件。
這個(gè)接口僅指定了基本解析(未解析的實(shí)體和屬性)所需的那些 DTD 事件。
- class xml.sax.handler.EntityResolver?
用于解析實(shí)體的基本接口。 如果你創(chuàng )建了實(shí)現此接口的對象,然后用你的解析器注冊該對象,該解析器將調用你的對象中的方法來(lái)解析所有外部實(shí)體。
- class xml.sax.handler.ErrorHandler?
解析器用來(lái)向應用程序表示錯誤和警告的接口。 這個(gè)對象的方法控制錯誤是要立即轉換為異常還是以某種其他該來(lái)來(lái)處理。
- class xml.sax.handler.LexicalHandler?
解析器用來(lái)代表低頻度事件的接口,這些事件可能是許多應用程序都不感興趣的。
除了這些類(lèi),xml.sax.handler
還提供了表示特性和屬性名稱(chēng)的符號常量。
- xml.sax.handler.feature_namespaces?
- 值:
"http://xml.org/sax/features/namespaces"
true: 執行命名空間處理。false: 可選擇不執行命名空間處理 (這意味著(zhù) namespace-prefixes; default)。access: (解析) 只讀; (不解析) 讀/寫(xiě)
- xml.sax.handler.feature_namespace_prefixes?
- 值:
"http://xml.org/sax/features/namespace-prefixes"
true: 報告原始的帶前綴名稱(chēng)和用于命名空間聲明的屬性。false: 不報告用于命名空間聲明的屬性,可選擇不報告原始的帶前綴名稱(chēng)(默認)。access: (解析) 只讀; (不解析) 讀/寫(xiě)
- xml.sax.handler.feature_string_interning?
- 值:
"http://xml.org/sax/features/string-interning"
true: 所有元素名稱(chēng)、前綴、屬性名稱(chēng)、命名空間 URI 以及本地名稱(chēng)都使用內置的 intern 函數進(jìn)行內化。false: 名稱(chēng)不要求被內化,但也可以被內化(默認)。access: (解析) 只讀; (不解析) 讀/寫(xiě)
- xml.sax.handler.feature_validation?
- 值:
"http://xml.org/sax/features/validation"
true: 報告所有的驗證錯誤(包括 external-general-entities 和 external-parameter-entities)。false: 不報告驗證錯誤。access: (解析) 只讀; (不解析) 讀/寫(xiě)
- xml.sax.handler.feature_external_ges?
- 值:
"http://xml.org/sax/features/external-general-entities"
true: 包括所有的外部通用(文本)實(shí)體。false: 不包括外部通用實(shí)體。access: (解析) 只讀; (不解析) 讀/寫(xiě)
- xml.sax.handler.feature_external_pes?
- 值:
"http://xml.org/sax/features/external-parameter-entities"
true: 包括所有的外部參數實(shí)體,也包括外部 DTD 子集。false: 不包括任何外部參數實(shí)體,也不包括外部 DTD 子集。access: (解析) 只讀; (不解析) 讀/寫(xiě)
- xml.sax.handler.all_features?
全部特性列表。
- xml.sax.handler.property_lexical_handler?
- 值:
"http://xml.org/sax/properties/lexical-handler"
數據類(lèi)型: xml.sax.handler.LexicalHandler (在 Python 2 中不受支持)描述: 可選的擴展處理句柄,用于注釋等詞法事件。訪(fǎng)問(wèn): 讀/寫(xiě)
- xml.sax.handler.property_declaration_handler?
- 值:
"http://xml.org/sax/properties/declaration-handler"
數據類(lèi)型: xml.sax.sax2lib.DeclHandler (在 Python 2 中不受支持)描述: 可選的擴展處理句柄,用于標注和未解析實(shí)體以外的 DTD 相關(guān)事件。訪(fǎng)問(wèn): 讀/寫(xiě)
- xml.sax.handler.property_dom_node?
- 值:
"http://xml.org/sax/properties/dom-node"
數據類(lèi)型: org.w3c.dom.Node (在 Python 2 中不受支持)描述: 在解析時(shí),如果這是一個(gè) DOM 迭代器則為當前被訪(fǎng)問(wèn)的 DOM 節點(diǎn);不在解析時(shí),則將根 DOM 節點(diǎn)用于迭代。access: (解析) 只讀; (不解析) 讀/寫(xiě)
- xml.sax.handler.property_xml_string?
- 值:
"http://xml.org/sax/properties/xml-string"
data type: Bytes描述: 作為當前事件來(lái)源的字符串字面值。訪(fǎng)問(wèn): 只讀
- xml.sax.handler.all_properties?
已知屬性名稱(chēng)列表。
ContentHandler 對象?
用戶(hù)應當子類(lèi)化 ContentHandler
來(lái)支持他們的應用程序。 以下方法會(huì )由解析器在輸入文檔的適當事件上調用:
- ContentHandler.setDocumentLocator(locator)?
由解析器調用來(lái)給予應用程序一個(gè)定位器以確定文檔事件來(lái)自何處。
強烈建議(雖然不是絕對的要求) SAX 解析器提供一個(gè)定位器:如果提供的話(huà),它必須在發(fā)起調用 DocumentHandler 接口的任何其他方法之前通過(guò)發(fā)起調用此方法來(lái)提供定位器。
定位器允許應用程序確定任何文檔相關(guān)事件的結束位置,即使解析器沒(méi)有報告錯誤。 通常,應用程序將使用這些信息來(lái)報告它自己的錯誤(例如未匹配到應用程序業(yè)務(wù)規則的字符內容)。 定位器所返回的信息可能不足以與搜索引擎配合使用。
請注意定位器只有在發(fā)起調用此接口中的事件時(shí)才會(huì )返回正確的信息。 應用程序不應試圖在其他任何時(shí)刻使用它。
- ContentHandler.startDocument()?
接收一個(gè)文檔開(kāi)始的通知。
SAX 解析器將只發(fā)起調用這個(gè)方法一次,并且會(huì )在調用這個(gè)接口或 DTDHandler 中的任何其他方法之前 (
setDocumentLocator()
除外)。
- ContentHandler.endDocument()?
接收一個(gè)文檔結束的通知。
SAX 解析器將只發(fā)起調用這個(gè)方法一次,并且它將是在解析過(guò)程中最后發(fā)起調用的方法。 解析器在(因不可恢復的錯誤)放棄解析或到達輸入的終點(diǎn)之前不應發(fā)起調用這個(gè)方法。
- ContentHandler.startPrefixMapping(prefix, uri)?
開(kāi)始一個(gè)前綴 URI 命名空間映射的范圍。
來(lái)自此事件的信息對于一般命名空間處理來(lái)說(shuō)是不必要的:當
feature_namespaces
特性被啟用時(shí)(默認)SAX XML 讀取器將自動(dòng)為元素和屬性名稱(chēng)替換前綴。但是也存在一些情況,當應用程序需要在字符數據或屬性值中使用前綴,而它們無(wú)法被安全地自動(dòng)擴展;
startPrefixMapping()
和endPrefixMapping()
事件會(huì )向應用程序提供信息以便在這些上下文內部擴展前綴,如果有必要的話(huà)。請注意
startPrefixMapping()
和endPrefixMapping()
事件并不保證能夠相對彼此被正確地嵌套:所有startPrefixMapping()
事件都將在對應的startElement()
事件之前發(fā)生,而所有endPrefixMapping()
事件都將在對應的endElement()
事件之后發(fā)生,但它們的并不保證一致。
- ContentHandler.endPrefixMapping(prefix)?
結束一個(gè)前綴 URI 映射的范圍。
請參看
startPrefixMapping()
了解詳情。 此事件將總是會(huì )在對應的endElement()
事件之后發(fā)生,但endPrefixMapping()
事件的順序則并沒(méi)有保證。
- ContentHandler.startElement(name, attrs)?
在非命令空間模式下指示一個(gè)元素的開(kāi)始。
name 形參包含字符串形式的元素類(lèi)型原始 XML 1.0 名稱(chēng)而 attrs 形參存放包含元素屬性的
Attributes
接口對象 (參見(jiàn) Attributes 接口)。 作為 attrs 傳入的對象可能被解析器所重用;維持一個(gè)對它的引用不是保持屬性副本的可靠方式。 要保持這些屬性的一個(gè)副本,請使用 attrs 對象的copy()
方法。
- ContentHandler.endElement(name)?
在非命名空間模式下指示一個(gè)元素的結束。
name 形參包含元素類(lèi)型的名稱(chēng),與
startElement()
事件的一樣。
- ContentHandler.startElementNS(name, qname, attrs)?
在命名空間模式下指示一個(gè)元素的開(kāi)始。
name 形參包含以
(uri, localname)
元組表示的元素類(lèi)型名稱(chēng),qname 形參包含源文檔中使用的原始 XML 1.0 名稱(chēng),而 attrs 形參存放包含元素屬性的AttributesNS
接口實(shí)例 (參見(jiàn) AttributesNS 接口)。 如果沒(méi)有命名空間被關(guān)聯(lián)到元素,則 name 的 uri 部分將為None
。 作為 attrs 傳入的對象可能被解析器所重用;維持一個(gè)對它的引用不是保持屬性副本的可靠方式。 要保持這些屬性的一個(gè)副本,請使用 attrs 對象的copy()
方法。解析器可將 qname 形參設為
None
,除非feature_namespace_prefixes
特性已被激活。
- ContentHandler.endElementNS(name, qname)?
在命名空間模式下指示一個(gè)元素的結束。
name 形參包含元素類(lèi)型的名稱(chēng),與
startElementNS()
方法的一樣,qname 形參也是類(lèi)似的。
- ContentHandler.characters(content)?
接收字符數據的通知。
解析器將調用此方法來(lái)報告每一個(gè)字符數據分塊。 SAX 解析器可以將所有連續字符數據返回為一個(gè)單獨分塊,或者將其拆成幾個(gè)分塊;但是,在任意單個(gè)事件中的所有字符都必須來(lái)自同一個(gè)外部實(shí)體以便定位器提供有用的信息。
content 可以是一個(gè)字符串或字節串實(shí)例;
expat
讀取器模塊總是會(huì )產(chǎn)生字符串。備注
Python XML 特別關(guān)注小組所提供的早期 SAX 1 接口針對此方法使用了一個(gè)更類(lèi)似于 Java 的接口。 由于 Python 所使用的大多數解析器都沒(méi)有利用老式的接口,因而選擇了更簡(jiǎn)單的簽名來(lái)替代它。 要將舊代碼轉換為新接口,請使用 content 而不要通過(guò)舊的 offset 和 length 形參來(lái)對內容進(jìn)行切片。
- ContentHandler.ignorableWhitespace(whitespace)?
接收元素內容中可忽略空白符的通知。
驗證解析器必須使用此方法來(lái)報告每個(gè)可忽略的空白符分塊(參見(jiàn) W3C XML 1.0 建議第 2.10 節):非驗證解析器如果能夠解析并使用內容模型的話(huà)也可以使用此方法。
SAX 解析器可以將所有連續字符數據返回為一個(gè)單獨分塊,或者將其拆成幾個(gè)分塊;但是,在任意單個(gè)事件中的所有字符都必須來(lái)自同一個(gè)外部實(shí)體以便定位器提供有用的信息。
- ContentHandler.processingInstruction(target, data)?
接受一條處理指令的通知。
解析器將為已找到的每條處理指令發(fā)起調用該方法一次:請注意處理指令可能出現在主文檔元素之前或之后。
SAX 解析器絕不應當使用此方法來(lái)報告 XML 聲明(XML 1.0 第 2.8 節)或文本聲明(XML 1.0 第 4.3.1 節)。
- ContentHandler.skippedEntity(name)?
接收一個(gè)已跳過(guò)實(shí)體的通知。
解析器將為每個(gè)已跳過(guò)實(shí)體發(fā)起調用此方法一次。 非驗證處理程序可能會(huì )跳過(guò)未看到聲明的實(shí)體(例如,由于實(shí)體是在一個(gè)外部because, for example, the entity was declared in an external DTD 子集中聲明的)。 所有處理程序都可以跳過(guò)外部實(shí)體,具體取決于
feature_external_ges
和feature_external_pes
屬性的值。
DTDHandler 對象?
DTDHandler
實(shí)例提供了下列方法:
- DTDHandler.notationDecl(name, publicId, systemId)?
處理標注聲明事件。
- DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)?
處理未解析的實(shí)體聲明事件。
EntityResolver 對象?
- EntityResolver.resolveEntity(publicId, systemId)?
求解一個(gè)實(shí)體的系統標識符并返回一個(gè)字符串形式的系統標識符作為讀取源,或是一個(gè) InputSource 作為讀取源。 默認的實(shí)現會(huì )返回 systemId。
ErrorHandler 對象?
帶有這個(gè)接口的對象被用于接收來(lái)自 XMLReader
的錯誤和警告信息。 如果你創(chuàng )建了一個(gè)實(shí)現這個(gè)接口的對象,然后用你的 XMLReader
注冊這個(gè)對象,則解析器將調用你的對象中的這個(gè)方法來(lái)報告所有的警告和錯誤。 有三個(gè)可用的錯誤級別:警告、(或許)可恢復的錯誤和不可恢復的錯誤。 所有方法都接受 SAXParseException
作為唯一的形參。 錯誤和警告可以通過(guò)引發(fā)所傳入的異常對象來(lái)轉換為異常。
- ErrorHandler.error(exception)?
當解析器遇到一個(gè)可恢復的錯誤時(shí)調用。 如果此方法沒(méi)有引發(fā)異常,則解析可能會(huì )繼續,但是應用程序不能預期獲得更多的文檔信息。 允許解析器繼續可能會(huì )允許在輸入文檔中發(fā)現額外的錯誤。
- ErrorHandler.fatalError(exception)?
當解析器遇到一個(gè)不可恢復的錯誤時(shí)調用;在此方法返回時(shí)解析應當終止。
- ErrorHandler.warning(exception)?
當解析器向應用程序提供次要警告信息時(shí)調用。 在此方法返回時(shí)解析應當繼續,并且文檔信息將繼續被傳遞給應用程序。 在此方法中引發(fā)異常將導致解析結束。
LexicalHandler 對象?
可選的詞法事件 SAX2 處理句柄。
這個(gè)處理句柄被用來(lái)獲取一個(gè) XML 文檔的相關(guān)詞法信息。 詞法信息包括描述所使用的文檔編碼格式和嵌入文檔中的 XML 注釋?zhuān)约?DTD 和任何 CDATA 部分的節邊界。 詞法處理句柄的使用方式與內容處理句柄相同。
通過(guò)使用帶有屬性標識符 'http://xml.org/sax/properties/lexical-handler'
的 setProperty 方法來(lái)設置一個(gè) XMLReader 的 LexicalHandler。
- LexicalHandler.comment(content)?
報告在文檔中任何地方(包括 DTD 和文檔元素以外)的注釋。
- LexicalHandler.startDTD(name, public_id, system_id)?
如果文檔有關(guān)聯(lián)的 DTD 則報告 DTD 聲明的開(kāi)始。
- LexicalHandler.endDTD()?
報告 DTD 聲明的結束。
- LexicalHandler.startCDATA()?
報告 CDATA 標記部分的開(kāi)始。
CDATA 標記部分的內容將通過(guò)字符處理句柄來(lái)報告。
- LexicalHandler.endCDATA()?
報告 CDATA 標記部分的結束。