xml.sax.handler --- Các lớp cơ sở cho trình xử lý SAX

Source code: Lib/xml/sax/handler.py

SAX API xác định năm loại trình xử lý: trình xử lý nội dung, trình xử lý DTD, trình xử lý lỗi, trình xử lý thực thể và trình xử lý từ vựng. Các ứng dụng thông thường chỉ cần triển khai những giao diện có sự kiện mà chúng quan tâm; họ có thể triển khai các giao diện trong một đối tượng hoặc trong nhiều đối tượng. Việc triển khai trình xử lý phải kế thừa từ các lớp cơ sở được cung cấp trong mô-đun xml.sax.handler để tất cả các phương thức đều có được cách triển khai mặc định.

class xml.sax.handler.ContentHandler

Đây là giao diện gọi lại chính trong SAX và là giao diện quan trọng nhất đối với các ứng dụng. Thứ tự của các sự kiện trong giao diện này phản ánh thứ tự của thông tin trong tài liệu.

class xml.sax.handler.DTDHandler

Xử lý các sự kiện DTD.

Giao diện này chỉ chỉ định những sự kiện DTD cần thiết cho phân tích cú pháp cơ bản (các thực thể và thuộc tính chưa được phân tích cú pháp).

class xml.sax.handler.EntityResolver

Giao diện cơ bản để phân giải các thực thể. Nếu bạn tạo một đối tượng triển khai giao diện này, thì hãy đăng ký đối tượng đó với Trình phân tích cú pháp của bạn, trình phân tích cú pháp sẽ gọi phương thức trong đối tượng của bạn để phân giải tất cả các thực thể bên ngoài.

class xml.sax.handler.ErrorHandler

Giao diện được trình phân tích cú pháp sử dụng để hiển thị các thông báo lỗi và cảnh báo cho ứng dụng. Các phương thức của đối tượng này kiểm soát xem lỗi có được chuyển đổi ngay lập tức thành ngoại lệ hay được xử lý theo cách khác hay không.

class xml.sax.handler.LexicalHandler

Giao diện được trình phân tích cú pháp sử dụng để thể hiện các sự kiện tần suất thấp có thể không được nhiều ứng dụng quan tâm.

Ngoài các lớp này, xml.sax.handler còn cung cấp các hằng số ký hiệu cho tên tính năng và thuộc tính.

xml.sax.handler.feature_namespaces
giá trị: "http://xml.org/sax/features/namespaces"
true: Thực hiện xử lý không gian tên.
sai: Tùy chọn không thực hiện xử lý Không gian tên (ngụ ý tiền tố không gian tên; mặc định).
truy cập: (phân tích cú pháp) chỉ đọc; (không phân tích cú pháp) đọc/ghi
xml.sax.handler.feature_namespace_prefixes
giá trị: "http://xml.org/sax/features/namespace-prefixes"
true: Báo cáo các tên và thuộc tính có tiền tố ban đầu được sử dụng để khai báo Không gian tên.
sai: Không báo cáo các thuộc tính được sử dụng để khai báo Không gian tên và tùy ý không báo cáo các tên có tiền tố gốc (mặc định).
truy cập: (phân tích cú pháp) chỉ đọc; (không phân tích cú pháp) đọc/ghi
xml.sax.handler.feature_string_interning
giá trị: "http://xml.org/sax/features/string-interning"
true: Tất cả tên thành phần, tiền tố, tên thuộc tính, URI không gian tên và tên cục bộ đều được thực hiện bằng hàm thực tập tích hợp sẵn.
sai: Tên không nhất thiết phải được đặt nội bộ, mặc dù chúng có thể (mặc định).
truy cập: (phân tích cú pháp) chỉ đọc; (không phân tích cú pháp) đọc/ghi
xml.sax.handler.feature_validation
giá trị: "http://xml.org/sax/features/validation"
true: Báo cáo tất cả các lỗi xác thực (ngụ ý các thực thể bên ngoài-chung và các thực thể tham số bên ngoài).
sai: Không báo cáo lỗi xác thực.
truy cập: (phân tích cú pháp) chỉ đọc; (không phân tích cú pháp) đọc/ghi
xml.sax.handler.feature_external_ges

Cảnh báo

Việc kích hoạt sẽ mở ra lỗ hổng cho external entity attacks nếu trình phân tích cú pháp được sử dụng với nội dung XML do người dùng cung cấp. Vui lòng suy nghĩ về threat model của bạn trước khi kích hoạt tính năng này.

giá trị: "http://xml.org/sax/features/external-general-entities"
đúng: Bao gồm tất cả các thực thể (văn bản) chung bên ngoài.
sai: Không bao gồm các thực thể chung bên ngoài.
truy cập: (phân tích cú pháp) chỉ đọc; (không phân tích cú pháp) đọc/ghi
xml.sax.handler.feature_external_pes
giá trị: "http://xml.org/sax/features/external-parameter-entities"
true: Bao gồm tất cả các thực thể tham số bên ngoài, bao gồm tập hợp con DTD bên ngoài.
sai: Không bao gồm bất kỳ thực thể tham số bên ngoài nào, ngay cả tập hợp con DTD bên ngoài.
truy cập: (phân tích cú pháp) chỉ đọc; (không phân tích cú pháp) đọc/ghi
xml.sax.handler.all_features

Danh sách tất cả các tính năng.

xml.sax.handler.property_lexical_handler
giá trị: "http://xml.org/sax/properties/lexical-handler"
kiểu dữ liệu: xml.sax.handler.LexicalHandler (không được hỗ trợ trong Python 2)
mô tả: Trình xử lý tiện ích mở rộng tùy chọn cho các sự kiện từ vựng như nhận xét.
truy cập: đọc/ghi
xml.sax.handler.property_declaration_handler
giá trị: "http://xml.org/sax/properties/declaration-handler"
kiểu dữ liệu: xml.sax.sax2lib.DeclHandler (không được hỗ trợ trong Python 2)
mô tả: Trình xử lý tiện ích mở rộng tùy chọn cho các sự kiện liên quan đến DTD ngoài các ký hiệu và thực thể chưa được phân tích cú pháp.
truy cập: đọc/ghi
xml.sax.handler.property_dom_node
giá trị: "http://xml.org/sax/properties/dom-node"
kiểu dữ liệu: org.w3c.dom.Node (không được hỗ trợ trong Python 2)
mô tả: Khi phân tích cú pháp, nút DOM hiện tại đang được truy cập nếu đây là trình vòng lặp DOM; khi không phân tích cú pháp, nút DOM gốc để lặp lại.
truy cập: (phân tích cú pháp) chỉ đọc; (không phân tích cú pháp) đọc/ghi
xml.sax.handler.property_xml_string
giá trị: "http://xml.org/sax/properties/xml-string"
kiểu dữ liệu: Byte
mô tả: Chuỗi ký tự bằng chữ là nguồn của sự kiện hiện tại.
truy cập: chỉ đọc
xml.sax.handler.all_properties

Danh sách tất cả các tên tài sản được biết đến.

Đối tượng ContentHandler

Người dùng dự kiến sẽ phân lớp ContentHandler để hỗ trợ ứng dụng của họ. Các phương thức sau đây được trình phân tích cú pháp gọi dựa trên các sự kiện thích hợp trong tài liệu đầu vào:

ContentHandler.setDocumentLocator(locator)

Được trình phân tích cú pháp gọi để cung cấp cho ứng dụng một bộ định vị nhằm xác định nguồn gốc của các sự kiện tài liệu.

Trình phân tích cú pháp SAX được khuyến khích (mặc dù không hoàn toàn bắt buộc) cung cấp bộ định vị: nếu làm như vậy, nó phải cung cấp bộ định vị cho ứng dụng bằng cách gọi phương thức này trước khi gọi bất kỳ phương thức nào khác trong giao diện DocumentHandler.

Trình định vị cho phép ứng dụng xác định vị trí kết thúc của bất kỳ sự kiện nào liên quan đến tài liệu, ngay cả khi trình phân tích cú pháp không báo cáo lỗi. Thông thường, ứng dụng sẽ sử dụng thông tin này để báo cáo lỗi của chính nó (chẳng hạn như nội dung ký tự không khớp với quy tắc kinh doanh của ứng dụng). Thông tin được bộ định vị trả về có thể không đủ để sử dụng với công cụ tìm kiếm.

Lưu ý rằng bộ định vị sẽ chỉ trả về thông tin chính xác trong quá trình gọi các sự kiện trong giao diện này. Ứng dụng không nên cố gắng sử dụng nó vào bất kỳ lúc nào khác.

ContentHandler.startDocument()

Nhận thông báo về sự bắt đầu của một tài liệu.

Trình phân tích cú pháp SAX sẽ chỉ gọi phương thức này một lần, trước bất kỳ phương thức nào khác trong giao diện này hoặc trong DTDHandler (ngoại trừ setDocumentLocator()).

ContentHandler.endDocument()

Nhận thông báo kết thúc tài liệu.

Trình phân tích cú pháp SAX sẽ chỉ gọi phương thức này một lần và đây sẽ là phương thức cuối cùng được gọi trong quá trình phân tích cú pháp. Trình phân tích cú pháp sẽ không gọi phương thức này cho đến khi nó ngừng phân tích cú pháp (vì lỗi không thể khôi phục) hoặc đã đến cuối đầu vào.

ContentHandler.startPrefixMapping(prefix, uri)

Bắt đầu phạm vi ánh xạ không gian tên prefix-URI.

Thông tin từ sự kiện này không cần thiết cho quá trình xử lý Không gian tên thông thường: trình đọc SAX XML sẽ tự động thay thế tiền tố cho tên thành phần và thuộc tính khi tính năng feature_namespaces được bật (mặc định).

Tuy nhiên, có những trường hợp khi ứng dụng cần sử dụng tiền tố trong dữ liệu ký tự hoặc giá trị thuộc tính thì chúng không thể được mở rộng tự động một cách an toàn; các sự kiện startPrefixMapping() và endPrefixMapping() cung cấp thông tin cho ứng dụng để mở rộng tiền tố trong chính các ngữ cảnh đó, nếu cần.

Lưu ý rằng các sự kiện startPrefixMapping() và endPrefixMapping() không được đảm bảo được lồng đúng cách so với nhau: tất cả các sự kiện startPrefixMapping() sẽ xảy ra trước sự kiện startElement() tương ứng và tất cả các sự kiện endPrefixMapping() sẽ xảy ra sau sự kiện endElement() tương ứng, nhưng thứ tự của chúng không được đảm bảo.

ContentHandler.endPrefixMapping(prefix)

Kết thúc phạm vi ánh xạ prefix-URI.

Xem startPrefixMapping() để biết chi tiết. Sự kiện này sẽ luôn xảy ra sau sự kiện endElement() tương ứng, nhưng thứ tự của các sự kiện endPrefixMapping() không được đảm bảo.

ContentHandler.startElement(name, attrs)

Báo hiệu sự bắt đầu của một phần tử ở chế độ không có không gian tên.

Tham số name chứa tên XML 1.0 thô của loại phần tử dưới dạng một chuỗi và tham số attrs chứa một đối tượng của giao diện Attributes chứa các thuộc tính của phần tử. Đối tượng được truyền dưới dạng attrs có thể được trình phân tích cú pháp sử dụng lại; giữ một tham chiếu đến nó không phải là cách đáng tin cậy để giữ một bản sao của các thuộc tính. Để giữ một bản sao của các thuộc tính, hãy sử dụng phương thức copy() của đối tượng attrs.

ContentHandler.endElement(name)

Báo hiệu sự kết thúc của một phần tử ở chế độ không có không gian tên.

Tham số name chứa tên của loại phần tử, giống như sự kiện startElement().

ContentHandler.startElementNS(name, qname, attrs)

Báo hiệu sự bắt đầu của một phần tử trong chế độ không gian tên.

Tham số name chứa tên của loại phần tử dưới dạng bộ (uri, localname), tham số qname chứa tên XML 1.0 thô được sử dụng trong tài liệu nguồn và tham số attrs giữ một phiên bản của giao diện AttributesNS chứa các thuộc tính của phần tử. Nếu không có không gian tên nào được liên kết với phần tử thì thành phần uri của name sẽ là None. Đối tượng được truyền dưới dạng attrs có thể được trình phân tích cú pháp sử dụng lại; giữ một tham chiếu đến nó không phải là cách đáng tin cậy để giữ một bản sao của các thuộc tính. Để giữ một bản sao của các thuộc tính, hãy sử dụng phương thức copy() của đối tượng attrs.

Trình phân tích cú pháp có thể đặt tham số qname thành None, trừ khi tính năng feature_namespace_prefixes được kích hoạt.

ContentHandler.endElementNS(name, qname)

Báo hiệu sự kết thúc của một phần tử trong chế độ không gian tên.

Tham số name chứa tên của loại phần tử, giống như phương thức startElementNS(), tương tự như tham số qname.

ContentHandler.characters(content)

Nhận thông báo về dữ liệu ký tự.

Trình phân tích cú pháp sẽ gọi phương thức này để báo cáo từng đoạn dữ liệu ký tự. Trình phân tích cú pháp SAX có thể trả về tất cả dữ liệu ký tự liền kề trong một đoạn duy nhất hoặc chúng có thể chia dữ liệu đó thành nhiều đoạn; tuy nhiên, tất cả các ký tự trong bất kỳ sự kiện nào đều phải đến từ cùng một thực thể bên ngoài để Bộ định vị cung cấp thông tin hữu ích.

content có thể là một phiên bản chuỗi hoặc byte; mô-đun đầu đọc expat luôn tạo ra các chuỗi.

Ghi chú

Giao diện SAX 1 trước đó do Nhóm quan tâm đặc biệt Python XML cung cấp đã sử dụng giao diện giống Java hơn cho phương thức này. Vì hầu hết các trình phân tích cú pháp được sử dụng từ Python không tận dụng được giao diện cũ hơn nên chữ ký đơn giản hơn đã được chọn để thay thế nó. Để chuyển đổi mã cũ sang giao diện mới, hãy sử dụng content thay vì cắt nội dung với thông số offset và length cũ.

ContentHandler.ignorableWhitespace(whitespace)

Nhận thông báo về khoảng trắng có thể bỏ qua trong nội dung phần tử.

Trình phân tích cú pháp xác thực phải sử dụng phương pháp này để báo cáo từng đoạn khoảng trắng không thể bỏ qua (xem đề xuất W3C XML 1.0, phần 2.10): các trình phân tích cú pháp không xác thực cũng có thể sử dụng phương pháp này nếu chúng có khả năng phân tích cú pháp và sử dụng các mô hình nội dung.

Trình phân tích cú pháp SAX có thể trả về tất cả khoảng trắng liền kề trong một đoạn hoặc chúng có thể chia nó thành nhiều đoạn; tuy nhiên, tất cả các ký tự trong bất kỳ sự kiện nào đều phải đến từ cùng một thực thể bên ngoài để Bộ định vị cung cấp thông tin hữu ích.

ContentHandler.processingInstruction(target, data)

Nhận thông báo hướng dẫn xử lý.

Trình phân tích cú pháp sẽ gọi phương thức này một lần cho mỗi lệnh xử lý được tìm thấy: lưu ý rằng các lệnh xử lý có thể xảy ra trước hoặc sau thành phần tài liệu chính.

Trình phân tích cú pháp SAX không bao giờ được báo cáo khai báo XML (XML 1.0, phần 2.8) hoặc khai báo văn bản (XML 1.0, mục 4.3.1) bằng phương pháp này.

ContentHandler.skippedEntity(name)

Nhận thông báo về một thực thể bị bỏ qua.

Trình phân tích cú pháp sẽ gọi phương thức này một lần cho mỗi thực thể bị bỏ qua. Các bộ xử lý không xác thực có thể bỏ qua các thực thể nếu chúng chưa nhìn thấy các phần khai báo (ví dụ: vì thực thể đó đã được khai báo trong tập hợp con DTD bên ngoài). Tất cả các bộ xử lý có thể bỏ qua các thực thể bên ngoài, tùy thuộc vào giá trị của thuộc tính feature_external_ges và feature_external_pes.

Đối tượng DTDHandler

Các phiên bản DTDHandler cung cấp các phương thức sau:

DTDHandler.notationDecl(name, publicId, systemId)

Xử lý sự kiện khai báo ký hiệu.

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

Xử lý sự kiện khai báo thực thể chưa được phân tích cú pháp.

Đối tượng EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

Giải quyết mã định danh hệ thống của một thực thể và trả về mã định danh hệ thống để đọc dưới dạng chuỗi hoặc Nguồn đầu vào để đọc từ đó. Việc triển khai mặc định trả về systemId.

Đối tượng ErrorHandler

Các đối tượng có giao diện này được sử dụng để nhận thông tin lỗi và cảnh báo từ XMLReader. Nếu bạn tạo một đối tượng triển khai giao diện này, sau đó đăng ký đối tượng đó bằng XMLReader của bạn, trình phân tích cú pháp sẽ gọi các phương thức trong đối tượng của bạn để báo cáo tất cả các cảnh báo và lỗi. Có ba cấp độ lỗi: cảnh báo, (có thể) lỗi có thể khôi phục và lỗi không thể khôi phục. Tất cả các phương thức đều lấy SAXParseException làm tham số duy nhất. Lỗi và cảnh báo có thể được chuyển đổi thành ngoại lệ bằng cách nâng cao đối tượng ngoại lệ được truyền vào.

ErrorHandler.error(exception)

Được gọi khi trình phân tích cú pháp gặp lỗi có thể phục hồi được. Nếu phương pháp này không đưa ra một ngoại lệ, việc phân tích cú pháp có thể tiếp tục, nhưng ứng dụng sẽ không mong đợi thêm thông tin tài liệu. Việc cho phép trình phân tích cú pháp tiếp tục có thể khiến phát hiện thêm các lỗi khác trong tài liệu đầu vào.

ErrorHandler.fatalError(exception)

Được gọi khi trình phân tích cú pháp gặp lỗi mà nó không thể phục hồi được; phân tích cú pháp dự kiến ​​​​sẽ chấm dứt khi phương thức này trả về.

ErrorHandler.warning(exception)

Được gọi khi trình phân tích cú pháp đưa ra thông tin cảnh báo nhỏ cho ứng dụng. Dự kiến, quá trình phân tích cú pháp sẽ tiếp tục khi phương thức này trả về và thông tin tài liệu sẽ tiếp tục được chuyển đến ứng dụng. Đưa ra một ngoại lệ trong phương pháp này sẽ khiến quá trình phân tích cú pháp kết thúc.

Đối tượng LexicalHandler

Trình xử lý SAX2 tùy chọn cho các sự kiện từ vựng.

Trình xử lý này được sử dụng để lấy thông tin từ vựng về tài liệu XML. Thông tin từ vựng bao gồm thông tin mô tả mã hóa tài liệu được sử dụng và các nhận xét XML được nhúng trong tài liệu, cũng như ranh giới phần cho DTD và cho bất kỳ phần CDATA nào. Trình xử lý từ vựng được sử dụng theo cách tương tự như trình xử lý nội dung.

Đặt LexicalHandler của XMLReader bằng cách sử dụng phương thức setProperty với mã định danh thuộc tính 'http://xml.org/sax/properties/lexical-handler'.

LexicalHandler.comment(content)

Báo cáo nhận xét ở bất kỳ đâu trong tài liệu (bao gồm DTD và bên ngoài thành phần tài liệu).

LexicalHandler.startDTD(name, public_id, system_id)

Báo cáo sự bắt đầu của các khai báo DTD nếu tài liệu có DTD liên quan.

LexicalHandler.endDTD()

Báo cáo kết thúc khai báo DTD.

LexicalHandler.startCDATA()

Báo cáo sự bắt đầu của phần được đánh dấu CDATA.

Nội dung của phần được đánh dấu CDATA sẽ được báo cáo thông qua trình xử lý ký tự.

LexicalHandler.endCDATA()

Báo cáo phần cuối của phần được đánh dấu CDATA.