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

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

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

class xml.sax.handler.ContentHandler?

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

class xml.sax.handler.DTDHandler?

處理 DTD 事件。

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

class xml.sax.handler.EntityResolver?

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

class xml.sax.handler.ErrorHandler?

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

class xml.sax.handler.LexicalHandler?

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

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

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: 報告原始的帶前綴名稱和用于命名空間聲明的屬性。
false: 不報告用于命名空間聲明的屬性，可選擇不報告原始的帶前綴名稱（默認）。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_string_interning?
值: "http://xml.org/sax/features/string-interning"
true: 所有元素名稱、前綴、屬性名稱、命名空間 URI 以及本地名稱都使用內(nèi)置的 intern 函數(shù)進行內(nèi)化。
false: 名稱不要求被內(nèi)化，但也可以被內(nèi)化（默認）。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_validation?
值: "http://xml.org/sax/features/validation"
true: 報告所有的驗證錯誤（包括 external-general-entities 和 external-parameter-entities）。
false: 不報告驗證錯誤。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_external_ges?
值: "http://xml.org/sax/features/external-general-entities"
true: 包括所有的外部通用（文本）實體。
false: 不包括外部通用實體。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.feature_external_pes?
值: "http://xml.org/sax/features/external-parameter-entities"
true: 包括所有的外部參數(shù)實體，也包括外部 DTD 子集。
false: 不包括任何外部參數(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 中不受支持)
描述: 可選的擴展處理句柄，用于注釋等詞法事件。
訪問: 讀/寫
xml.sax.handler.property_declaration_handler?
值: "http://xml.org/sax/properties/declaration-handler"
數(shù)據(jù)類型: xml.sax.sax2lib.DeclHandler (在 Python 2 中不受支持)
描述: 可選的擴展處理句柄，用于標注和未解析實體以外的 DTD 相關事件。
訪問: 讀/寫
xml.sax.handler.property_dom_node?
值: "http://xml.org/sax/properties/dom-node"
數(shù)據(jù)類型: org.w3c.dom.Node (在 Python 2 中不受支持)
描述: 在解析時，如果這是一個 DOM 迭代器則為當前被訪問的 DOM 節(jié)點；不在解析時，則將根 DOM 節(jié)點用于迭代。
access: (解析) 只讀; (不解析) 讀/寫
xml.sax.handler.property_xml_string?
值: "http://xml.org/sax/properties/xml-string"
data type: Bytes
描述: 作為當前事件來源的字符串字面值。
訪問: 只讀
xml.sax.handler.all_properties?

已知屬性名稱列表。

ContentHandler 對象?

用戶應當子類化 ContentHandler 來支持他們的應用程序。 以下方法會由解析器在輸入文檔的適當事件上調用:

ContentHandler.setDocumentLocator(locator)?

由解析器調用來給予應用程序一個定位器以確定文檔事件來自何處。

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

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

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

ContentHandler.startDocument()?

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

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

ContentHandler.endDocument()?

接收一個文檔結束的通知。

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

ContentHandler.startPrefixMapping(prefix, uri)?

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

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

但是也存在一些情況，當應用程序需要在字符數(shù)據(jù)或屬性值中使用前綴，而它們無法被安全地自動擴展；startPrefixMapping() 和 endPrefixMapping() 事件會向應用程序提供信息以便在這些上下文內(nèi)部擴展前綴，如果有必要的話。

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

ContentHandler.endPrefixMapping(prefix)?

結束一個前綴 URI 映射的范圍。

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

ContentHandler.startElement(name, attrs)?

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

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

ContentHandler.endElement(name)?

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

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

ContentHandler.startElementNS(name, qname, attrs)?

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

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

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

ContentHandler.endElementNS(name, qname)?

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

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

ContentHandler.characters(content)?

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

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

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

備注

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

ContentHandler.ignorableWhitespace(whitespace)?

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

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

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

ContentHandler.processingInstruction(target, data)?

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

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

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

ContentHandler.skippedEntity(name)?

接收一個已跳過實體的通知。

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

DTDHandler 對象?

DTDHandler 實例提供了下列方法:

DTDHandler.notationDecl(name, publicId, systemId)?

處理標注聲明事件。

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

處理未解析的實體聲明事件。

EntityResolver 對象?

EntityResolver.resolveEntity(publicId, systemId)?

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

ErrorHandler 對象?

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

ErrorHandler.error(exception)?

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

ErrorHandler.fatalError(exception)?

當解析器遇到一個不可恢復的錯誤時調用；在此方法返回時解析應當終止。

ErrorHandler.warning(exception)?

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

LexicalHandler 對象?

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

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

通過使用帶有屬性標識符 'http://xml.org/sax/properties/lexical-handler' 的 setProperty 方法來設置一個 XMLReader 的 LexicalHandler。

LexicalHandler.comment(content)?

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

LexicalHandler.startDTD(name, public_id, system_id)?

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

LexicalHandler.endDTD()?

報告 DTD 聲明的結束。

LexicalHandler.startCDATA()?

報告 CDATA 標記部分的開始。

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

LexicalHandler.endCDATA()?

報告 CDATA 標記部分的結束。