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"

資料型別：位元組

描述：作為當前事件來源的字元的字面字串。

訪問許可權：只讀

xml.sax.handler.all_properties

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

ContentHandler 物件

使用者需要對 ContentHandler 進行子類化，以支援他們的應用程式。以下方法由解析器在輸入文件中的相應事件上呼叫

ContentHandler.setDocumentLocator(locator)

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

強烈鼓勵（雖然不是絕對要求）SAX 解析器提供定位器：如果它這樣做，它必須在呼叫 DocumentHandler 介面中的任何其他方法之前，透過呼叫此方法嚮應用程式提供定位器。

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

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

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 介面的例項（請參閱 AttributesNS 介面），其中包含元素的屬性。如果元素沒有與名稱空間關聯，則 name 的 uri 元件將為 None。作為 attrs 傳遞的物件可能被解析器重用；保留對其的引用不是保留屬性副本的可靠方法。要保留屬性的副本，請使用 attrs 物件的 copy() 方法。

除非啟用 feature_namespace_prefixes 功能，否則解析器可能會將 qname 引數設定為 None。

ContentHandler.endElementNS(name, qname)

發出在名稱空間模式下元素結束的訊號。

name 引數包含元素型別的名稱，就像 startElementNS() 方法一樣，qname 引數也是如此。

ContentHandler.characters(content)

接收字元資料的通知。

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

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

注意

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

ContentHandler.ignorableWhitespace(whitespace)

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

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

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

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 部分的節邊界。詞法處理程式的使用方式與內容處理程式相同。

透過使用屬性識別符號 'http://xml.org/sax/properties/lexical-handler' 的 setProperty 方法設定 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 標記部分的結束。