xml.sax.handler --- SAX 處理句柄的基類?

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

SAX API 定義了五種處理句柄：內(nèi)容句柄、DTD 句柄、錯(cuò)誤句柄、實(shí)體解析器以及詞法句柄。 應(yīng)用程序通常只需要實(shí)現(xiàn)他們感興趣的事件對(duì)應(yīng)的接口；他們可以在單個(gè)對(duì)象或多個(gè)對(duì)象中實(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)接口，也是對(duì)應(yīng)用程序來說最重要的一個(gè)接口。 此接口中事件的順序反映了文檔中信息的順序。

class xml.sax.handler.DTDHandler?

處理 DTD 事件。

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

class xml.sax.handler.EntityResolver?

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

class xml.sax.handler.ErrorHandler?

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

class xml.sax.handler.LexicalHandler?

解析器用來代表低頻度事件的接口，這些事件可能是許多應(yīng)用程序都不感興趣的。

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

xml.sax.handler.feature_namespaces?
值: "http://xml.org/sax/features/namespaces"
true: 執(zhí)行命名空間處理。
false: 可選擇不執(zhí)行命名空間處理 (這意味著 namespace-prefixes; default)。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_namespace_prefixes?
值: "http://xml.org/sax/features/namespace-prefixes"
true: 報(bào)告原始的帶前綴名稱和用于命名空間聲明的屬性。
false: 不報(bào)告用于命名空間聲明的屬性，可選擇不報(bào)告原始的帶前綴名稱（默認(rèn)）。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_string_interning?
值: "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?
值: "http://xml.org/sax/features/validation"
true: 報(bào)告所有的驗(yàn)證錯(cuò)誤（包括 external-general-entities 和 external-parameter-entities）。
false: 不報(bào)告驗(yàn)證錯(cuò)誤。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_external_ges?
值: "http://xml.org/sax/features/external-general-entities"
true: 包括所有的外部通用（文本）實(shí)體。
false: 不包括外部通用實(shí)體。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_external_pes?
值: "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?
值: "http://xml.org/sax/properties/lexical-handler"
數(shù)據(jù)類型: xml.sax.handler.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 中不受支持)
描述: 在解析時(shí)，如果這是一個(gè) DOM 迭代器則為當(dāng)前被訪問的 DOM 節(jié)點(diǎn)；不在解析時(shí)，則將根 DOM 節(jié)點(diǎn)用于迭代。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.property_xml_string?
值: "http://xml.org/sax/properties/xml-string"
data type: Bytes
描述: 作為當(dāng)前事件來源的字符串字面值。
訪問: 只讀
xml.sax.handler.all_properties?

已知屬性名稱列表。

ContentHandler 對(duì)象?

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

ContentHandler.setDocumentLocator(locator)?

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

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

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

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

ContentHandler.startDocument()?

接收一個(gè)文檔開始的通知。

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

ContentHandler.endDocument()?

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

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

ContentHandler.startPrefixMapping(prefix, uri)?

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

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

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

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

ContentHandler.endPrefixMapping(prefix)?

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

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

ContentHandler.startElement(name, attrs)?

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

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

ContentHandler.endElement(name)?

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

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

ContentHandler.startElementNS(name, qname, attrs)?

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

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

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

ContentHandler.endElementNS(name, qname)?

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

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

ContentHandler.characters(content)?

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

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

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

備注

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

ContentHandler.ignorableWhitespace(whitespace)?

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

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

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

ContentHandler.processingInstruction(target, data)?

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

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

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

ContentHandler.skippedEntity(name)?

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

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

DTDHandler 對(duì)象?

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

DTDHandler.notationDecl(name, publicId, systemId)?

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

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

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

EntityResolver 對(duì)象?

EntityResolver.resolveEntity(publicId, systemId)?

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

ErrorHandler 對(duì)象?

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

ErrorHandler.error(exception)?

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

ErrorHandler.fatalError(exception)?

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

ErrorHandler.warning(exception)?

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

LexicalHandler 對(duì)象?

可選的詞法事件 SAX2 處理句柄。

這個(gè)處理句柄被用來獲取一個(gè) XML 文檔的相關(guān)詞法信息。 詞法信息包括描述所使用的文檔編碼格式和嵌入文檔中的 XML 注釋，以及 DTD 和任何 CDATA 部分的節(jié)邊界。 詞法處理句柄的使用方式與內(nèi)容處理句柄相同。

通過使用帶有屬性標(biāo)識(shí)符 'http://xml.org/sax/properties/lexical-handler' 的 setProperty 方法來設(shè)置一個(gè) XMLReader 的 LexicalHandler。

LexicalHandler.comment(content)?

報(bào)告在文檔中任何地方（包括 DTD 和文檔元素以外）的注釋。

LexicalHandler.startDTD(name, public_id, system_id)?

如果文檔有關(guān)聯(lián)的 DTD 則報(bào)告 DTD 聲明的開始。

LexicalHandler.endDTD()?

報(bào)告 DTD 聲明的結(jié)束。

LexicalHandler.startCDATA()?

報(bào)告 CDATA 標(biāo)記部分的開始。

CDATA 標(biāo)記部分的內(nèi)容將通過字符處理句柄來報(bào)告。

LexicalHandler.endCDATA()?

報(bào)告 CDATA 標(biāo)記部分的結(jié)束。