xml.sax.handler --- SAX 處理句柄的基類(lèi)?

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


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)到元素,則 nameuri 部分將為 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ò)舊的 offsetlength 形參來(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_gesfeature_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 標記部分的結束。