xml.sax.handler --- SAX 處理程序的基類?

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

SAX API 定類了四種處理句柄：內(nèi)容句柄、DTD 句柄、錯誤句柄以及實(shí)體解析器。 應(yīng)用程序通常只需要實(shí)現(xiàn)他們感興趣的事件對應(yīng)的接口；他們可以在單個對象或多個對象中實(shí)現(xiàn)這些接口。 處理句柄的實(shí)現(xiàn)應(yīng)當(dāng)繼承自在 xml.sax.handler 模塊中提供的基類，以便所有方法都能獲得默認(rèn)的實(shí)現(xiàn)。

class xml.sax.handler.ContentHandler?

這是 SAX 中的主回調(diào)接口，也是對應(yīng)用程序來說最重要的一個接口。 此接口中事件的順序反映了文檔中信息的順序。

class xml.sax.handler.DTDHandler?

處理 DTD 事件。

這個接口僅指定了基本解析（未解析的實(shí)體和屬性）所需的那些 DTD 事件。

class xml.sax.handler.EntityResolver?

用于解析實(shí)體的基本接口。 如果你創(chuàng)建了實(shí)現(xiàn)此接口的對象，然后用你的解析器注冊該對象，該解析器將調(diào)用你的對象中的方法來解析所有外部實(shí)體。

class xml.sax.handler.ErrorHandler?

解析器用來向應(yīng)用程序表示錯誤和警告的接口。 這個對象的方法控制錯誤是要立即轉(zhuǎn)換為異常還是以某種其他該來來處理。

除了這些類，xml.sax.handler 還提供了表示特性和屬性名稱的符號常量。

xml.sax.handler.feature_namespaces?
value: "http://xml.org/sax/features/namespaces"
true: 執(zhí)行命名空間處理。
false: 可選擇不執(zhí)行命名空間處理 (這意味著 namespace-prefixes; default)。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_namespace_prefixes?
value: "http://xml.org/sax/features/namespace-prefixes"
true: 報告用于命名空間聲明的原始帶前綴名稱和屬性。
false: 不報告用于命名空間聲明的屬性，可選擇不報告原始帶前綴名稱（默認(rèn)）。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_string_interning?
value: "http://xml.org/sax/features/string-interning"
true: 所有元素名稱、前綴、屬性名稱、命名空間 URI 以及本地名稱都使用內(nèi)置的 intern 函數(shù)進(jìn)行內(nèi)化。
false: 名稱不要求被內(nèi)化，但也可以被內(nèi)化（默認(rèn)）。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_validation?
value: "http://xml.org/sax/features/validation"
true: 報告所有的驗(yàn)證錯誤（包括 external-general-entities 和 external-parameter-entities）。
false: 不報告驗(yàn)證錯誤。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_external_ges?
value: "http://xml.org/sax/features/external-general-entities"
true: 包括所有的外部通用（文本）實(shí)體。
false: 不包括外部通用實(shí)體。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_external_pes?
value: "http://xml.org/sax/features/external-parameter-entities"
true: 包括所有的外部參數(shù)實(shí)體，包括外部 DTD 子集。
false: 不包括任何外部參數(shù)實(shí)體，也不包括外部 DTD 子集。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.all_features?

全部特性列表。

xml.sax.handler.property_lexical_handler?
value: "http://xml.org/sax/properties/lexical-handler"
數(shù)據(jù)類型: xml.sax.sax2lib.LexicalHandler (在 Python 2 中不受支持)
描述: 可選的擴(kuò)展處理句柄，用于注釋等詞法事件。
訪問: 讀/寫
xml.sax.handler.property_declaration_handler?
值: "http://xml.org/sax/properties/declaration-handler"
數(shù)據(jù)類型: xml.sax.sax2lib.DeclHandler (在 Python 2 中不受支持)
描述: 可選的擴(kuò)展處理句柄，用于標(biāo)注和未解析實(shí)體以外的 DTD 相關(guān)事件。
訪問: 讀/寫
xml.sax.handler.property_dom_node?
值: "http://xml.org/sax/properties/dom-node"
數(shù)據(jù)類型: org.w3c.dom.Node (在 Python 2 中不受支持)
描述: 在解析時，如果這是一個 DOM 迭代器則為當(dāng)前被訪問的 DOM 節(jié)點(diǎn)；不在解析時，則將根 DOM 節(jié)點(diǎn)用于迭代。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.property_xml_string?
值: "http://xml.org/sax/properties/xml-string"
數(shù)據(jù)類型: String
描述: 作為當(dāng)前事件來源的字符串字面值。
訪問: 只讀
xml.sax.handler.all_properties?

已知屬性名稱列表。

ContentHandler 對象?

用戶應(yīng)當(dāng)子類化 ContentHandler 來支持他們的應(yīng)用程序。 以下方法會由解析器在輸入文檔的適當(dāng)事件上調(diào)用:

ContentHandler.setDocumentLocator(locator)?

由解析器調(diào)用來給予應(yīng)用程序一個定位器以確定文檔事件來自何處。

強(qiáng)烈建議（雖然不是絕對的要求） SAX 解析器提供一個定位器：如果提供的話，它必須在發(fā)起調(diào)用 DocumentHandler 接口的任何其他方法之前通過發(fā)起調(diào)用此方法來提供定位器。

定位器允許應(yīng)用程序確定任何文檔相關(guān)事件的結(jié)束位置，即使解析器沒有報告錯誤。 通常，應(yīng)用程序?qū)⑹褂眠@些信息來報告它自己的錯誤（例如未匹配到應(yīng)用程序業(yè)務(wù)規(guī)則的字符內(nèi)容）。 定位器所返回的信息可能不足以與搜索引擎配合使用。

請注意定位器只有在發(fā)起調(diào)用此接口中的事件時才會返回正確的信息。 應(yīng)用程序不應(yīng)試圖在其他任何時刻使用它。

ContentHandler.startDocument()?

接收一個文檔開始的通知。

SAX 解析器將只發(fā)起調(diào)用這個方法一次，并且會在調(diào)用這個接口或 DTDHandler 中的任何其他方法之前 (setDocumentLocator() 除外)。

ContentHandler.endDocument()?

接收一個文檔結(jié)束的通知。

SAX 解析器將只發(fā)起調(diào)用這個方法一次，并且它將是在解析過程中最后發(fā)起調(diào)用的方法。 解析器在（因不可恢復(fù)的錯誤）放棄解析或到達(dá)輸入的終點(diǎn)之前不應(yīng)發(fā)起調(diào)用這個方法。

ContentHandler.startPrefixMapping(prefix, uri)?

開始一個前綴 URI 命名空間映射的范圍。

來自此事件的信息對于一般命名空間處理來說是不必要的：當(dāng) feature_namespaces 特性被啟用時（默認(rèn)）SAX XML 讀取器將自動為元素和屬性名稱替換前綴。

但是也存在一些情況，當(dāng)應(yīng)用程序需要在字符數(shù)據(jù)或?qū)傩灾抵惺褂们熬Y，而它們無法被安全地自動擴(kuò)展；startPrefixMapping() 和 endPrefixMapping() 事件會向應(yīng)用程序提供信息以便在這些上下文內(nèi)部擴(kuò)展前綴，如果有必要的話。

請注意 startPrefixMapping() 和 endPrefixMapping() 事件并不保證能夠相對彼此被正確地嵌套：所有 startPrefixMapping() 事件都將在對應(yīng)的 startElement() 事件之前發(fā)生，而所有 endPrefixMapping() 事件都將在對應(yīng)的 endElement() 事件之后發(fā)生，但它們的并不保證一致。

ContentHandler.endPrefixMapping(prefix)?

結(jié)束一個前綴 URI 映射的范圍。

請參看 startPrefixMapping() 了解詳情。 此事件將總是會在對應(yīng)的 endElement() 事件之后發(fā)生，但 endPrefixMapping() 事件的順序則并沒有保證。

ContentHandler.startElement(name, attrs)?

在非命令空間模式下指示一個元素的開始。

name 形參包含字符串形式的元素類型原始 XML 1.0 名稱而 attrs 形參存放包含元素屬性的 Attributes 接口對象 (參見 Attributes 接口)。 作為 attrs 傳入的對象可能被解析器所重用；維持一個對它的引用不是保持屬性副本的可靠方式。 要保持這些屬性的一個副本，請使用 attrs 對象的 copy() 方法。

ContentHandler.endElement(name)?

在非命名空間模式下指示一個元素的結(jié)束。

name 形參包含元素類型的名稱，與 startElement() 事件的一樣。

ContentHandler.startElementNS(name, qname, attrs)?

在命名空間模式下指示一個元素的開始。

name 形參包含以 (uri, localname) 元組表示的元素類型名稱，qname 形參包含源文檔中使用的原始 XML 1.0 名稱，而 attrs 形參存放包含元素屬性的 AttributesNS 接口實(shí)例 (參見 AttributesNS 接口)。 如果沒有命名空間被關(guān)聯(lián)到元素，則 name 的 uri 部分將為 None。 作為 attrs 傳入的對象可能被解析器所重用；維持一個對它的引用不是保持屬性副本的可靠方式。 要保持這些屬性的一個副本，請使用 attrs 對象的 copy() 方法。

解析器可將 qname 形參設(shè)為 None，除非 feature_namespace_prefixes 特性已被激活。

ContentHandler.endElementNS(name, qname)?

在命名空間模式下指示一個元素的結(jié)束。

name 形參包含元素類型的名稱，與 startElementNS() 方法的一樣，qname 形參也是類似的。

ContentHandler.characters(content)?

接收字符數(shù)據(jù)的通知。

解析器將調(diào)用此方法來報告每一個字符數(shù)據(jù)分塊。 SAX 解析器可以將所有連續(xù)字符數(shù)據(jù)返回為一個單獨(dú)分塊，或者將其拆成幾個分塊；但是，在任意單個事件中的所有字符都必須來自同一個外部實(shí)體以便定位器提供有用的信息。

content 可以是一個字符串或字節(jié)串實(shí)例；expat 讀取器模塊總是會產(chǎn)生字符串。

注解

Python XML 特別關(guān)注小組所提供的早期 SAX 1 接口針對此方法使用了一個更類似于 Java 的接口。 由于 Python 所使用的大多數(shù)解析器都沒有利用老式的接口，因而選擇了更簡單的簽名來替代它。 要將舊代碼轉(zhuǎn)換為新接口，請使用 content 而不要通過舊的 offset 和 length 形參來對內(nèi)容進(jìn)行切片。

ContentHandler.ignorableWhitespace(whitespace)?

接收元素內(nèi)容中可忽略空白符的通知。

驗(yàn)證解析器必須使用此方法來報告每個可忽略的空白符分塊（參見 W3C XML 1.0 建議第 2.10 節(jié)）：非驗(yàn)證解析器如果能夠解析并使用內(nèi)容模型的話也可以使用此方法。

SAX 解析器可以將所有連續(xù)字符數(shù)據(jù)返回為一個單獨(dú)分塊，或者將其拆成幾個分塊；但是，在任意單個事件中的所有字符都必須來自同一個外部實(shí)體以便定位器提供有用的信息。

ContentHandler.processingInstruction(target, data)?

接受一條處理指令的通知。

解析器將為已找到的每條處理指令發(fā)起調(diào)用該方法一次：請注意處理指令可能出現(xiàn)在主文檔元素之前或之后。

SAX 解析器絕不應(yīng)當(dāng)使用此方法來報告 XML 聲明（XML 1.0 第 2.8 節(jié)）或文本聲明（XML 1.0 第 4.3.1 節(jié)）。

ContentHandler.skippedEntity(name)?

接收一個已跳過實(shí)體的通知。

解析器將為每個已跳過實(shí)體發(fā)起調(diào)用此方法一次。 非驗(yàn)證處理程序可能會跳過未看到聲明的實(shí)體（例如，由于實(shí)體是在一個外部because, for example, the entity was declared in an external DTD 子集中聲明的）。 所有處理程序都可以跳過外部實(shí)體，具體取決于 feature_external_ges 和 feature_external_pes 屬性的值。

DTDHandler 對象?

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

DTDHandler.notationDecl(name, publicId, systemId)?

處理標(biāo)注聲明事件。

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)?

處理未解析的實(shí)體聲明事件。

EntityResolver 對象?

EntityResolver.resolveEntity(publicId, systemId)?

求解一個實(shí)體的系統(tǒng)標(biāo)識符并返回一個字符串形式的系統(tǒng)標(biāo)識符作為讀取源，或是一個 InputSource 作為讀取源。 默認(rèn)的實(shí)現(xiàn)會返回 systemId。

ErrorHandler 對象?

帶有這個接口的對象被用于接收來自 XMLReader 的錯誤和警告信息。 如果你創(chuàng)建了一個實(shí)現(xiàn)這個接口的對象，然后用你的 XMLReader 注冊這個對象，則解析器將調(diào)用你的對象中的這個方法來報告所有的警告和錯誤。 有三個可用的錯誤級別：警告、（或許）可恢復(fù)的錯誤和不可恢復(fù)的錯誤。 所有方法都接受 SAXParseException 作為唯一的形參。 錯誤和警告可以通過引發(fā)所傳入的異常對象來轉(zhuǎn)換為異常。

ErrorHandler.error(exception)?

當(dāng)解析器遇到一個可恢復(fù)錯誤時調(diào)用。 如果此方法沒有引發(fā)異常，則解析可能會繼續(xù)，但是應(yīng)用程序不能預(yù)期獲得更多的文檔信息。 允許解析器繼續(xù)可能會允許在輸入文檔中發(fā)現(xiàn)額外的錯誤。

ErrorHandler.fatalError(exception)?

當(dāng)解析器遇到一個無法恢復(fù)的錯誤時調(diào)用；在此方法返回時解析應(yīng)當(dāng)終止。

ErrorHandler.warning(exception)?

當(dāng)解析器向應(yīng)用程序提供次要警告信息時調(diào)用。 在此方法返回時解析應(yīng)當(dāng)繼續(xù)，并且文檔信息將繼續(xù)被傳遞給應(yīng)用程序。 在此方法中引發(fā)異常將導(dǎo)致解析結(jié)束。