xml.sax.xmlreader --- Giao diện cho trình phân tích cú pháp XML

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

Trình phân tích cú pháp SAX triển khai giao diện XMLReader. Chúng được triển khai trong mô-đun Python, mô-đun này phải cung cấp hàm create_parser(). Hàm này được xml.sax.make_parser() gọi mà không có đối số để tạo đối tượng trình phân tích cú pháp mới.

class xml.sax.xmlreader.XMLReader

Lớp cơ sở có thể được kế thừa bởi trình phân tích cú pháp SAX.

class xml.sax.xmlreader.IncrementalParser

Trong một số trường hợp, không nên phân tích cú pháp nguồn đầu vào cùng một lúc mà cung cấp các phần của tài liệu khi chúng có sẵn. Lưu ý rằng người đọc thường sẽ không đọc toàn bộ tệp mà đọc nó theo từng đoạn; parse() vẫn không quay lại cho đến khi toàn bộ tài liệu được xử lý. Vì vậy, nên sử dụng các giao diện này nếu hành vi chặn của parse() là không mong muốn.

Khi trình phân tích cú pháp được khởi tạo, nó sẵn sàng bắt đầu chấp nhận dữ liệu từ phương thức nguồn cấp dữ liệu ngay lập tức. Sau khi quá trình phân tích cú pháp kết thúc bằng lệnh gọi đóng, phương thức đặt lại phải được gọi để làm cho trình phân tích cú pháp sẵn sàng chấp nhận dữ liệu mới, từ nguồn cấp dữ liệu hoặc sử dụng phương thức phân tích cú pháp.

Lưu ý rằng các phương thức này phải được gọi not trong quá trình phân tích cú pháp, nghĩa là sau khi phân tích cú pháp được gọi và trước khi nó trả về.

Theo mặc định, lớp này cũng triển khai phương thức phân tích cú pháp của giao diện XMLReader bằng cách sử dụng các phương thức cấp dữ liệu, đóng và đặt lại của giao diện IncrementalParser để thuận tiện cho người viết trình điều khiển SAX 2.0.

class xml.sax.xmlreader.Locator

Giao diện để liên kết sự kiện SAX với vị trí tài liệu. Một đối tượng định vị sẽ chỉ trả về kết quả hợp lệ trong khi gọi các phương thức DocumentHandler; vào bất kỳ thời điểm nào khác, kết quả là không thể đoán trước. Nếu không có thông tin, các phương thức có thể trả về None.

class xml.sax.xmlreader.InputSource(system_id=None)

Đóng gói thông tin cần thiết của XMLReader để đọc các thực thể.

Lớp này có thể bao gồm thông tin về mã định danh công khai, mã định danh hệ thống, luồng byte (có thể có thông tin mã hóa ký tự) và/hoặc luồng ký tự của một thực thể.

Các ứng dụng sẽ tạo các đối tượng của lớp này để sử dụng trong phương thức XMLReader.parse() và để trả về từ EntityResolver.resolveEntity.

Một InputSource thuộc về ứng dụng, XMLReader không được phép sửa đổi các đối tượng InputSource được truyền cho nó từ ứng dụng, mặc dù nó có thể tạo các bản sao và sửa đổi chúng.

class xml.sax.xmlreader.AttributesImpl(attrs)

Đây là cách triển khai giao diện Attributes (xem phần Giao diện Attributes). Đây là một đối tượng giống như từ điển đại diện cho các thuộc tính phần tử trong lệnh gọi startElement(). Ngoài các thao tác từ điển hữu ích nhất, nó còn hỗ trợ một số phương pháp khác như được mô tả trong giao diện. Các đối tượng của lớp này phải được người đọc khởi tạo; attrs phải là một đối tượng giống từ điển chứa ánh xạ từ tên thuộc tính đến giá trị thuộc tính.

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

Biến thể nhận biết không gian tên của AttributesImpl, sẽ được chuyển cho startElementNS(). Nó có nguồn gốc từ AttributesImpl, nhưng hiểu tên thuộc tính là hai bộ namespaceURI và localname. Ngoài ra, nó còn cung cấp một số phương thức mong đợi những tên đủ điều kiện khi chúng xuất hiện trong tài liệu gốc. Lớp này triển khai giao diện AttributesNS (xem phần Giao diện AttributesNS).

Đối tượng XMLReader

Giao diện XMLReader hỗ trợ các phương thức sau:

XMLReader.parse(source)

Xử lý nguồn đầu vào, tạo ra các sự kiện SAX. Đối tượng source có thể là mã nhận dạng hệ thống (một chuỗi xác định nguồn đầu vào -- thường là tên tệp hoặc URL), đối tượng pathlib.Path hoặc path-like hoặc đối tượng InputSource. Khi parse() trả về, đầu vào được xử lý hoàn toàn và đối tượng trình phân tích cú pháp có thể bị loại bỏ hoặc đặt lại.

Thay đổi trong phiên bản 3.5: Đã thêm hỗ trợ cho các luồng ký tự.

Thay đổi trong phiên bản 3.8: Đã thêm hỗ trợ cho các đối tượng giống như đường dẫn.

XMLReader.getContentHandler()

Trả về ContentHandler hiện tại.

XMLReader.setContentHandler(handler)

Đặt ContentHandler hiện tại. Nếu không đặt ContentHandler, các sự kiện nội dung sẽ bị loại bỏ.

XMLReader.getDTDHandler()

Trả về DTDHandler hiện tại.

XMLReader.setDTDHandler(handler)

Đặt DTDHandler hiện tại. Nếu không thiết lập DTDHandler, các sự kiện DTD sẽ bị loại bỏ.

XMLReader.getEntityResolver()

Trả về EntityResolver hiện tại.

XMLReader.setEntityResolver(handler)

Đặt EntityResolver hiện tại. Nếu không đặt EntityResolver, các nỗ lực giải quyết một thực thể bên ngoài sẽ dẫn đến việc mở mã định danh hệ thống cho thực thể đó và sẽ thất bại nếu nó không khả dụng.

XMLReader.getErrorHandler()

Trả về ErrorHandler hiện tại.

XMLReader.setErrorHandler(handler)

Đặt trình xử lý lỗi hiện tại. Nếu không đặt ErrorHandler, lỗi sẽ xuất hiện dưới dạng ngoại lệ và cảnh báo sẽ được in.

XMLReader.setLocale(locale)

Cho phép ứng dụng đặt ngôn ngữ cho lỗi và cảnh báo.

Trình phân tích cú pháp SAX không bắt buộc phải cung cấp bản địa hóa cho các lỗi và cảnh báo; Tuy nhiên, nếu họ không thể hỗ trợ ngôn ngữ được yêu cầu, họ phải đưa ra ngoại lệ SAX. Các ứng dụng có thể yêu cầu thay đổi ngôn ngữ ở giữa quá trình phân tích cú pháp.

XMLReader.getFeature(featurename)

Trả về cài đặt hiện tại cho tính năng featurename. Nếu tính năng này không được nhận dạng, SAXNotRecognizedException sẽ được nâng lên. Các tên tính năng nổi tiếng được liệt kê trong mô-đun xml.sax.handler.

XMLReader.setFeature(featurename, value)

Đặt featurename thành value. Nếu tính năng này không được nhận dạng, SAXNotRecognizedException sẽ được nâng lên. Nếu tính năng hoặc cài đặt của nó không được trình phân tích cú pháp hỗ trợ, SAXNotSupportedException sẽ được nâng lên.

XMLReader.getProperty(propertyname)

Trả về cài đặt hiện tại cho thuộc tính propertyname. Nếu thuộc tính không được nhận dạng, SAXNotRecognizedException sẽ được nâng lên. Tên thuộc tính nổi tiếng được liệt kê trong mô-đun xml.sax.handler.

XMLReader.setProperty(propertyname, value)

Đặt propertyname thành value. Nếu thuộc tính không được nhận dạng, SAXNotRecognizedException sẽ được nâng lên. Nếu thuộc tính hoặc cài đặt của nó không được trình phân tích cú pháp hỗ trợ, SAXNotSupportedException sẽ được nâng lên.

Đối tượng IncrementalParser

Các phiên bản của IncrementalParser cung cấp các phương thức bổ sung sau:

IncrementalParser.feed(data)

Xử lý một đoạn data.

IncrementalParser.close()

Giả sử phần cuối của tài liệu. Điều đó sẽ kiểm tra các điều kiện về tính đúng đắn mà chỉ có thể được kiểm tra ở cuối, gọi các trình xử lý và có thể dọn sạch các tài nguyên được phân bổ trong quá trình phân tích cú pháp.

IncrementalParser.reset()

Phương thức này được gọi sau khi lệnh close được gọi để thiết lập lại trình phân tích cú pháp để nó sẵn sàng phân tích các tài liệu mới. Kết quả của việc gọi phân tích cú pháp hoặc nguồn cấp dữ liệu sau khi đóng mà không gọi lại thiết lập lại là không xác định.

Đối tượng định vị

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

Locator.getColumnNumber()

Trả về số cột nơi sự kiện hiện tại bắt đầu.

Locator.getLineNumber()

Trả về số dòng nơi sự kiện hiện tại bắt đầu.

Locator.getPublicId()

Trả về mã định danh công khai cho sự kiện hiện tại.

Locator.getSystemId()

Trả về mã định danh hệ thống cho sự kiện hiện tại.

Đối tượng nguồn đầu vào

InputSource.setPublicId(id)

Đặt mã định danh công khai của InputSource này.

InputSource.getPublicId()

Trả về mã định danh công khai của InputSource này.

InputSource.setSystemId(id)

Đặt mã định danh hệ thống của InputSource này.

InputSource.getSystemId()

Trả về mã định danh hệ thống của InputSource này.

InputSource.setEncoding(encoding)

Đặt mã hóa ký tự của InputSource này.

Mã hóa phải là một chuỗi được chấp nhận cho khai báo mã hóa XML (xem phần 4.3.3 của đề xuất XML).

Thuộc tính mã hóa của InputSource bị bỏ qua nếu InputSource cũng chứa luồng ký tự.

InputSource.getEncoding()

Lấy mã hóa ký tự của Nguồn đầu vào này.

InputSource.setByteStream(bytefile)

Đặt luồng byte (binary file) cho nguồn đầu vào này.

Trình phân tích cú pháp SAX sẽ bỏ qua điều này nếu cũng có luồng ký tự được chỉ định, nhưng nó sẽ sử dụng luồng byte ưu tiên hơn là mở chính kết nối URI.

Nếu ứng dụng biết mã hóa ký tự của luồng byte thì nó sẽ đặt nó bằng phương thức setEncoding.

InputSource.getByteStream()

Nhận luồng byte cho nguồn đầu vào này.

Phương thức getEncoding sẽ trả về mã hóa ký tự cho luồng byte này hoặc None nếu không xác định.

InputSource.setCharacterStream(charfile)

Đặt luồng ký tự (text file) cho nguồn đầu vào này.

Nếu có một luồng ký tự được chỉ định, trình phân tích cú pháp SAX sẽ bỏ qua bất kỳ luồng byte nào và sẽ không cố mở kết nối URI tới mã định danh hệ thống.

InputSource.getCharacterStream()

Lấy luồng ký tự cho nguồn đầu vào này.

Giao diện Attributes

Các đối tượng Attributes triển khai một phần của mapping protocol, bao gồm các phương thức copy(), get(), __contains__(), items(), keys() và values(). Các phương pháp sau đây cũng được cung cấp:

Attributes.getLength()

Trả về số lượng thuộc tính.

Attributes.getNames()

Trả về tên của các thuộc tính.

Attributes.getType(name)

Trả về loại thuộc tính name, thường là 'CDATA'.

Attributes.getValue(name)

Trả về giá trị của thuộc tính name.

Giao diện AttributesNS

Giao diện này là một kiểu con của giao diện Attributes (xem phần Giao diện Attributes). Tất cả các phương thức được giao diện đó hỗ trợ cũng có sẵn trên các đối tượng AttributesNS.

Các phương pháp sau đây cũng có sẵn:

AttributesNS.getValueByQName(name)

Trả về giá trị cho một tên đủ điều kiện.

AttributesNS.getNameByQName(name)

Trả lại cặp (namespace, localname) để có name đủ điều kiện.

AttributesNS.getQNameByName(name)

Trả lại tên đủ điều kiện cho cặp (namespace, localname).

AttributesNS.getQNames()

Trả về tên đủ điều kiện của tất cả các thuộc tính.