xml.sax.handler — SAX 處理器基類

原始碼: Lib/xml/sax/handler.py

---

SAX API 定義了五種處理器：內容處理器、DTD 處理器、錯誤處理器、實體解析器和詞法處理器。應用程式通常只需要實現它們感興趣的事件介面；它們可以在一個物件中或在多個物件中實現這些介面。處理器實現應該繼承自模組 xml.sax.handler 中提供的基類，以便所有方法都能獲得預設實現。

class xml.sax.handler.ContentHandler

這是 SAX 中主要的，也是對應用程式最重要的回撥介面。此介面中事件的順序反映了文件中資訊的順序。

class xml.sax.handler.DTDHandler

處理 DTD 事件。

此介面僅指定了基本解析所需的 DTD 事件（未解析實體和屬性）。

class xml.sax.handler.EntityResolver

用於解析實體的基本介面。如果您建立了一個實現此介面的物件，然後將其註冊到您的解析器，解析器將呼叫您物件中的方法來解析所有外部實體。

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: 執行名稱空間處理。

false: 可選地不執行名稱空間處理（暗示 namespace-prefixes；預設）。

訪問: (解析時) 只讀；(非解析時) 讀/寫

xml.sax.handler.feature_namespace_prefixes

值: "http://xml.org/sax/features/namespace-prefixes"

true: 報告用於名稱空間宣告的原始帶字首名稱和屬性。

false: 不報告用於名稱空間宣告的屬性，並且可選地不報告原始帶字首名稱（預設）。

訪問: (解析時) 只讀；(非解析時) 讀/寫

xml.sax.handler.feature_string_interning

值: "http://xml.org/sax/features/string-interning"

true: 所有元素名稱、字首、屬性名稱、名稱空間 URI 和本地名稱都使用內建的 intern 函式進行內部化。

false: 名稱不一定被內部化，儘管它們可能被內部化（預設）。

訪問: (解析時) 只讀；(非解析時) 讀/寫

xml.sax.handler.feature_validation

值: "http://xml.org/sax/features/validation"

true: 報告所有驗證錯誤（暗示 external-general-entities 和 external-parameter-entities）。

false: 不報告驗證錯誤。

訪問: (解析時) 只讀；(非解析時) 讀/寫

xml.sax.handler.feature_external_ges

值: "http://xml.org/sax/features/external-general-entities"

true: 包含所有外部通用（文字）實體。

false: 不包含外部通用實體。

訪問: (解析時) 只讀；(非解析時) 讀/寫

xml.sax.handler.feature_external_pes

值: "http://xml.org/sax/features/external-parameter-entities"

true: 包含所有外部引數實體，包括外部 DTD 子集。

false: 不包含任何外部引數實體，即使是外部 DTD 子集。

訪問: (解析時) 只讀；(非解析時) 讀/寫

xml.sax.handler.all_features

所有特性的列表。

xml.sax.handler.property_lexical_handler

值: "http://xml.org/sax/properties/lexical-handler"

資料型別: xml.sax.handler.LexicalHandler (Python 2 不支援)

描述: 一個可選的用於處理註釋等詞法事件的擴充套件處理器。

訪問: 讀/寫

xml.sax.handler.property_declaration_handler

值: "http://xml.org/sax/properties/declaration-handler"

資料型別: xml.sax.sax2lib.DeclHandler (Python 2 不支援)

描述: 一個可選的用於處理與 DTD 相關事件（除了符號和未解析實體）的擴充套件處理器。

訪問: 讀/寫

xml.sax.handler.property_dom_node

值: "http://xml.org/sax/properties/dom-node"

資料型別: org.w3c.dom.Node (Python 2 不支援)

描述: 解析時，如果是 DOM 迭代器，則為當前訪問的 DOM 節點；不解析時，則為迭代的根 DOM 節點。

訪問: (解析時) 只讀；(非解析時) 讀/寫

xml.sax.handler.property_xml_string

值: "http://xml.org/sax/properties/xml-string"

資料型別: Bytes

描述: 當前事件源的字面字串。

訪問: 只讀

xml.sax.handler.all_properties

所有已知屬性名稱的列表。

ContentHandler 物件

使用者需要子類化 ContentHandler 來支援其應用程式。以下方法在輸入文件中發生相應事件時由解析器呼叫

ContentHandler.setDocumentLocator(locator)

由解析器呼叫，嚮應用程式提供一個定位器，用於定位文件事件的來源。

強烈建議 SAX 解析器（儘管並非絕對要求）提供定位器：如果提供了，則必須在呼叫 DocumentHandler 介面中的任何其他方法之前（setDocumentLocator() 除外）透過呼叫此方法嚮應用程式提供定位器。

定位器允許應用程式確定任何文件相關事件的結束位置，即使解析器沒有報告錯誤。通常，應用程式將使用此資訊報告自己的錯誤（例如與應用程式業務規則不匹配的字元內容）。定位器返回的資訊可能不足以用於搜尋引擎。

請注意，定位器僅在此介面事件的呼叫期間返回正確的資訊。應用程式不應在任何其他時間嘗試使用它。

ContentHandler.startDocument()

接收文件開始的通知。

SAX 解析器將只調用此方法一次，在此介面或 DTDHandler 中的任何其他方法之前（setDocumentLocator() 除外）。

ContentHandler.endDocument()

接收文件結束的通知。

SAX 解析器將只調用此方法一次，並且它將是解析期間呼叫的最後一個方法。解析器只有在放棄解析（由於不可恢復的錯誤）或到達輸入結束時才會呼叫此方法。

ContentHandler.startPrefixMapping(prefix, uri)

開始字首-URI 名稱空間對映的範圍。

此事件中的資訊對於正常的名稱空間處理不是必需的：當 feature_namespaces 特性啟用時（預設），SAX XML 讀取器將自動替換元素和屬性名稱的字首。

然而，在某些情況下，應用程式需要在字元資料或屬性值中使用字首，而這些字首無法安全地自動擴充套件；startPrefixMapping() 和 endPrefixMapping() 事件嚮應用程式提供資訊，以便在必要時自行擴充套件這些上下文中的字首。

請注意，startPrefixMapping() 和 endPrefixMapping() 事件不保證彼此之間正確巢狀：所有 startPrefixMapping() 事件將在相應的 startElement() 事件之前發生，所有 endPrefixMapping() 事件將在相應的 endElement() 事件之後發生，但它們的順序不作保證。

ContentHandler.endPrefixMapping(prefix)

結束字首-URI 對映的範圍。

有關詳細資訊，請參閱 startPrefixMapping()。此事件將始終在相應的 endElement() 事件之後發生，但 endPrefixMapping() 事件的順序不作其他保證。

ContentHandler.startElement(name, attrs)

在非名稱空間模式下表示元素的開始。

name 引數包含元素型別的原始 XML 1.0 名稱作為字串，attrs 引數包含 Attributes 介面的物件，其中包含元素的屬性。傳遞給 attrs 的物件可能被解析器重用；保留對其的引用不是保留屬性副本的可靠方法。要保留屬性副本，請使用 attrs 物件的 copy() 方法。

ContentHandler.endElement(name)

在非名稱空間模式下表示元素的結束。

name 引數包含元素型別的名稱，與 startElement() 事件相同。

ContentHandler.startElementNS(name, qname, attrs)

在名稱空間模式下表示元素的開始。

name 引數包含元素型別的名稱，作為 (uri, localname) 元組，qname 引數包含源文件中使用的原始 XML 1.0 名稱，attrs 引數包含 AttributesNS 介面的例項，其中包含元素的屬性。如果元素沒有關聯的名稱空間，則 name 的 uri 部分將為 None。傳遞給 attrs 的物件可能被解析器重用；保留對其的引用不是保留屬性副本的可靠方法。要保留屬性副本，請使用 attrs 物件的 copy() 方法。

解析器可以將 qname 引數設定為 None，除非激活了 feature_namespace_prefixes 特性。

ContentHandler.endElementNS(name, qname)

在名稱空間模式下表示元素的結束。

name 引數包含元素型別的名稱，與 startElementNS() 方法相同，qname 引數也相同。

ContentHandler.characters(content)

接收字元資料的通知。

解析器將呼叫此方法來報告每個字元資料塊。SAX 解析器可以將所有連續字元資料作為一個塊返回，或者將其分成幾個塊；但是，任何單個事件中的所有字元都必須來自同一個外部實體，以便定位器提供有用的資訊。

content 可以是字串或位元組例項；expat 讀取器模組始終生成字串。

備註

Python XML 特別興趣小組提供的早期 SAX 1 介面為此方法提供了更像 Java 的介面。由於大多數從 Python 使用的解析器都沒有利用舊介面，因此選擇了更簡單的簽名來替換它。要將舊程式碼轉換為新介面，請使用 content 而不是使用舊的 offset 和 length 引數來切片內容。

ContentHandler.ignorableWhitespace(whitespace)

接收元素內容中可忽略空白的通知。

驗證解析器必須使用此方法報告每個可忽略空白塊（請參閱 W3C XML 1.0 推薦，第 2.10 節）：非驗證解析器如果能夠解析和使用內容模型，也可以使用此方法。

SAX 解析器可以將所有連續空白作為一個塊返回，或者將其分成幾個塊；但是，任何單個事件中的所有字元都必須來自同一個外部實體，以便定位器提供有用的資訊。

ContentHandler.processingInstruction(target, data)

接收處理指令的通知。

解析器將為找到的每個處理指令呼叫此方法一次：請注意，處理指令可能出現在主文件元素之前或之後。

SAX 解析器不應使用此方法報告 XML 宣告（XML 1.0，第 2.8 節）或文字宣告（XML 1.0，第 4.3.1 節）。

ContentHandler.skippedEntity(name)

接收跳過的實體的通知。

解析器將為每個跳過的實體呼叫此方法一次。非驗證處理器如果尚未看到宣告（例如，因為實體在外部 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)

解析實體的系統識別符號並返回要讀取的系統識別符號字串，或要讀取的 InputSource。預設實現返回 systemId。

ErrorHandler 物件

具有此介面的物件用於從 XMLReader 接收錯誤和警告資訊。如果您建立了一個實現此介面的物件，然後將該物件註冊到您的 XMLReader，解析器將呼叫您物件中的方法來報告所有警告和錯誤。錯誤分為三個級別：警告、（可能）可恢復錯誤和不可恢復錯誤。所有方法都將 SAXParseException 作為唯一引數。錯誤和警告可以透過引發傳入的異常物件來轉換為異常。

ErrorHandler.error(exception)

當解析器遇到可恢復錯誤時呼叫。如果此方法不引發異常，則解析可能會繼續，但應用程式不應期望進一步的文件資訊。允許解析器繼續可能會發現輸入文件中的其他錯誤。

ErrorHandler.fatalError(exception)

當解析器遇到無法恢復的錯誤時呼叫；預計此方法返回時解析將終止。

ErrorHandler.warning(exception)

當解析器嚮應用程式提供次要警告資訊時呼叫。預計此方法返回時解析將繼續，並且文件資訊將繼續傳遞給應用程式。在此方法中引發異常將導致解析結束。

LexicalHandler 物件

可選的 SAX2 詞法事件處理器。

此處理器用於獲取 XML 文件的詞法資訊。詞法資訊包括描述文件編碼、嵌入在文件中的 XML 註釋以及 DTD 和任何 CDATA 節的邊界。詞法處理器以與內容處理器相同的方式使用。

透過使用 setProperty 方法和屬性識別符號 'http://xml.org/sax/properties/lexical-handler' 來設定 XMLReader 的 LexicalHandler。

LexicalHandler.comment(content)

報告文件中任何位置（包括 DTD 和文件元素外部）的註釋。

LexicalHandler.startDTD(name, public_id, system_id)

如果文件具有關聯的 DTD，則報告 DTD 宣告的開始。

LexicalHandler.endDTD()

報告 DTD 宣告的結束。

LexicalHandler.startCDATA()

報告 CDATA 標記節的開始。

CDATA 標記節的內容將透過字元處理器報告。

LexicalHandler.endCDATA()

報告 CDATA 標記節的結束。