xml.parsers.expat --- Phân tích cú pháp XML nhanh bằng Expat

Ghi chú

Nếu bạn cần phân tích dữ liệu không đáng tin cậy hoặc chưa được xác thực, hãy xem bảo mật XML.

Mô-đun xml.parsers.expat là giao diện Python cho trình phân tích cú pháp XML không xác thực của người nước ngoài. Mô-đun này cung cấp một loại tiện ích mở rộng duy nhất, xmlparser, đại diện cho trạng thái hiện tại của trình phân tích cú pháp XML. Sau khi một đối tượng xmlparser được tạo, các thuộc tính khác nhau của đối tượng có thể được đặt thành các hàm xử lý. Khi tài liệu XML được đưa vào trình phân tích cú pháp, các hàm xử lý sẽ được gọi cho dữ liệu ký tự và đánh dấu trong tài liệu XML.

Mô-đun này sử dụng mô-đun pyexpat để cung cấp quyền truy cập vào trình phân tích cú pháp người nước ngoài. Việc sử dụng trực tiếp mô-đun pyexpat không được dùng nữa.

Mô-đun này cung cấp một ngoại lệ và một loại đối tượng:

exception xml.parsers.expat.ExpatError

Ngoại lệ được đưa ra khi người nước ngoài báo cáo lỗi. Xem phần Ngoại lệExtError để biết thêm thông tin về cách giải thích lỗi Expat.

exception xml.parsers.expat.error

Bí danh cho ExpatError.

xml.parsers.expat.XMLParserType

Loại giá trị trả về từ hàm ParserCreate().

Mô-đun xml.parsers.expat chứa hai chức năng:

xml.parsers.expat.ErrorString(errno)

Trả về một chuỗi giải thích cho một số lỗi nhất định errno.

xml.parsers.expat.ParserCreate(encoding=None, namespace_separator=None)

Tạo và trả về một đối tượng xmlparser mới. encoding, nếu được chỉ định, phải là một chuỗi đặt tên mã hóa được dữ liệu XML sử dụng. Expat không hỗ trợ nhiều mã hóa như Python và không thể mở rộng danh mục mã hóa của nó; nó hỗ trợ UTF-8, UTF-16, ISO-8859-1 (Latin1) và ASCII. Nếu encoding [1] được cung cấp, nó sẽ ghi đè mã hóa ngầm hoặc rõ ràng của tài liệu.

Các trình phân tích cú pháp được tạo thông qua ParserCreate() được gọi là trình phân tích cú pháp "gốc", nghĩa là chúng không có bất kỳ trình phân tích cú pháp gốc nào được đính kèm. Trình phân tích cú pháp không phải root được tạo bởi parser.ExternalEntityParserCreate.

Người nước ngoài có thể tùy ý thực hiện xử lý không gian tên XML cho bạn, được bật bằng cách cung cấp giá trị cho namespace_separator. Giá trị phải là chuỗi một ký tự; ValueError sẽ được tăng lên nếu chuỗi có độ dài không hợp lệ (None được coi là giống như thiếu sót). Khi xử lý không gian tên được bật, tên loại phần tử và tên thuộc tính thuộc về không gian tên sẽ được mở rộng. Tên phần tử được truyền cho trình xử lý phần tử StartElementHandler và EndElementHandler sẽ là phần nối của không gian tên URI, ký tự phân tách vùng tên và phần cục bộ của tên. Nếu dấu phân cách vùng tên là byte 0 (chr(0)) thì vùng tên URI và phần cục bộ sẽ được nối mà không có bất kỳ dấu phân cách nào.

Ví dụ: nếu namespace_separator được đặt thành ký tự khoảng trắng (' ') và tài liệu sau được phân tích cú pháp:

<?xml phiên bản="1.0"?>
<gốc xmlns="http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</ gốc>

StartElementHandler sẽ nhận được các chuỗi sau cho mỗi phần tử

gốc http://default-namespace.org/
http://www.python.org/ns/ yếu tố1
yếu tố2

Do những hạn chế trong thư viện Expat được pyexpat sử dụng, phiên bản xmlparser được trả về chỉ có thể được sử dụng để phân tích một tài liệu XML duy nhất. Gọi ParserCreate cho mỗi tài liệu để cung cấp các phiên bản trình phân tích cú pháp duy nhất.

Xem thêm

The Expat XML Parser

Trang chủ của dự án Expat.

Đối tượng XMLParser

Các đối tượng xmlparser có các phương thức sau:

xmlparser.Parse(data[, isfinal])

Phân tích nội dung của chuỗi data, gọi các hàm xử lý thích hợp để xử lý dữ liệu được phân tích cú pháp. isfinal phải đúng trong lần gọi cuối cùng tới phương thức này; nó cho phép phân tích cú pháp một tệp thành từng đoạn chứ không phải gửi nhiều tệp. data có thể là chuỗi trống bất kỳ lúc nào.

xmlparser.ParseFile(file)

Phân tích dữ liệu XML đọc từ đối tượng file. file chỉ cần cung cấp phương thức read(nbytes), trả về chuỗi trống khi không còn dữ liệu.

xmlparser.SetBase(base)

Đặt cơ sở được sử dụng để phân giải các URI tương đối trong mã định danh hệ thống trong phần khai báo. Việc giải quyết các mã định danh tương đối được giao cho ứng dụng: giá trị này sẽ được chuyển qua dưới dạng đối số base cho các hàm ExternalEntityRefHandler(), NotationDeclHandler() và UnparsedEntityDeclHandler().

xmlparser.GetBase()

Trả về một chuỗi chứa cơ sở được đặt bởi lệnh gọi trước đó tới SetBase() hoặc None nếu SetBase() chưa được gọi.

xmlparser.GetInputContext()

Trả về dữ liệu đầu vào đã tạo ra sự kiện hiện tại dưới dạng chuỗi. Dữ liệu nằm trong mã hóa của thực thể chứa văn bản. Khi được gọi trong khi trình xử lý sự kiện không hoạt động, giá trị trả về là None.

xmlparser.ExternalEntityParserCreate(context[, encoding])

Tạo một trình phân tích cú pháp "con" có thể được sử dụng để phân tích cú pháp một thực thể được phân tích cú pháp bên ngoài được tham chiếu bởi nội dung được phân tích cú pháp bởi trình phân tích cú pháp gốc. Tham số context phải là chuỗi được truyền tới hàm xử lý ExternalEntityRefHandler(), được mô tả bên dưới. Trình phân tích cú pháp con được tạo với ordered_attributes và specified_attributes được đặt thành các giá trị của trình phân tích cú pháp này.

xmlparser.SetParamEntityParsing(flag)

Kiểm soát phân tích cú pháp các thực thể tham số (bao gồm tập hợp con DTD bên ngoài). Các giá trị flag có thể có là XML_PARAM_ENTITY_PARSING_NEVER, XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE và XML_PARAM_ENTITY_PARSING_ALWAYS. Trả về true nếu đặt cờ thành công.

xmlparser.UseForeignDTD([flag])

Việc gọi giá trị này bằng giá trị thực cho flag (mặc định) sẽ khiến người nước ngoài gọi ExternalEntityRefHandler bằng None cho tất cả các đối số để cho phép tải DTD thay thế. Nếu tài liệu không chứa khai báo loại tài liệu, ExternalEntityRefHandler sẽ vẫn được gọi, nhưng StartDoctypeDeclHandler và EndDoctypeDeclHandler sẽ không được gọi.

Việc chuyển giá trị sai cho flag sẽ hủy cuộc gọi trước đó đã chuyển giá trị đúng, nhưng nếu không thì sẽ không có hiệu lực.

Phương thức này chỉ có thể được gọi trước khi phương thức Parse() hoặc ParseFile() được gọi; gọi nó theo tên một trong hai cái đó đã được gọi khiến ExpatError được nâng lên với thuộc tính code được đặt thành errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING].

xmlparser.SetReparseDeferralEnabled(enabled)

Cảnh báo

Việc gọi SetReparseDeferralEnabled(False) có liên quan đến bảo mật, như chi tiết bên dưới; vui lòng đảm bảo hiểu rõ những hậu quả này trước khi sử dụng phương pháp SetReparseDeferralEnabled.

Expat 2.6.0 đã giới thiệu một cơ chế bảo mật được gọi là "trì hoãn phân tích lại", trong đó thay vì gây ra sự từ chối dịch vụ thông qua thời gian chạy bậc hai từ việc phân tích lại các mã thông báo lớn, việc phân tích lại các mã thông báo chưa hoàn thành hiện bị trì hoãn theo mặc định cho đến khi đạt đủ lượng đầu vào. Do sự chậm trễ này, các trình xử lý đã đăng ký có thể — tùy thuộc vào kích thước của các khối đầu vào được đẩy sang Người nước ngoài — không còn được gọi ngay sau khi đẩy đầu vào mới vào trình phân tích cú pháp. Trong trường hợp cả hai đều muốn phản hồi ngay lập tức và đảm nhận trách nhiệm bảo vệ chống lại việc từ chối dịch vụ từ các mã thông báo lớn, việc gọi SetReparseDeferralEnabled(False) sẽ vô hiệu hóa việc trì hoãn phân tích cú pháp cho phiên bản trình phân tích cú pháp Expat hiện tại, tạm thời hoặc hoàn toàn. Gọi SetReparseDeferralEnabled(True) cho phép kích hoạt lại tính năng trì hoãn phân tích cú pháp.

Lưu ý rằng SetReparseDeferralEnabled() đã được đưa vào một số bản phát hành CPython trước đó như một bản sửa lỗi bảo mật. Kiểm tra tính khả dụng của SetReparseDeferralEnabled() bằng hasattr() nếu được sử dụng trong mã chạy trên nhiều phiên bản Python.

Added in version 3.13.

xmlparser.GetReparseDeferralEnabled()

Trả về xem tính năng trì hoãn phân tích cú pháp hiện có được bật cho phiên bản trình phân tích cú pháp người nước ngoài đã cho hay không.

Added in version 3.13.

Các đối tượng xmlparser có các phương pháp sau để giảm thiểu một số lỗ hổng XML phổ biến.

xmlparser.SetAllocTrackerActivationThreshold(threshold, /)

Đặt số byte được phân bổ của bộ nhớ động cần thiết để kích hoạt tính năng bảo vệ chống lại việc sử dụng RAM không cân xứng.

Theo mặc định, các đối tượng trình phân tích cú pháp có ngưỡng kích hoạt phân bổ là 64 MiB hoặc tương đương 67.108.864 byte.

Một ExpatError được nâng lên nếu phương thức này được gọi trên trình phân tích cú pháp non-root. Không nên sử dụng lineno và offset tương ứng vì chúng có thể không có ý nghĩa đặc biệt.

Added in version 3.14.1.

xmlparser.SetAllocTrackerMaximumAmplification(max_factor, /)

Đặt hệ số khuếch đại tối đa giữa đầu vào trực tiếp và byte bộ nhớ động được phân bổ.

Hệ số khuếch đại được tính bằng allocated / direct trong khi phân tích cú pháp, trong đó direct là số byte được đọc từ tài liệu chính trong quá trình phân tích cú pháp và allocated là số byte bộ nhớ động được phân bổ trong hệ thống phân cấp của trình phân tích cú pháp.

Giá trị max_factor phải là giá trị float không phải NaN lớn hơn hoặc bằng 1,0. Hệ số khuếch đại lớn hơn 100,0 có thể được quan sát thấy ở gần thời điểm bắt đầu phân tích cú pháp, ngay cả với các tệp lành tính trong thực tế. Đặc biệt, ngưỡng kích hoạt cần được lựa chọn cẩn thận để tránh hiện tượng dương tính giả.

Theo mặc định, các đối tượng trình phân tích cú pháp có hệ số khuếch đại tối đa là 100,0.

Một ExpatError được nâng lên nếu phương thức này được gọi trên trình phân tích cú pháp non-root hoặc nếu max_factor nằm ngoài phạm vi hợp lệ. Không nên sử dụng lineno và offset tương ứng vì chúng có thể không có ý nghĩa đặc biệt.

Ghi chú

Hệ số khuếch đại tối đa chỉ được xem xét nếu vượt quá ngưỡng có thể điều chỉnh bởi SetAllocTrackerActivationThreshold().

Added in version 3.14.1.

Các đối tượng xmlparser có các thuộc tính sau:

xmlparser.buffer_size

Kích thước của bộ đệm được sử dụng khi buffer_text là đúng. Kích thước bộ đệm mới có thể được đặt bằng cách gán một giá trị số nguyên mới cho thuộc tính này. Khi kích thước được thay đổi, bộ đệm sẽ bị xóa.

xmlparser.buffer_text

Việc đặt giá trị này thành true sẽ khiến đối tượng xmlparser đệm nội dung văn bản do Expat trả về để tránh nhiều lệnh gọi đến lệnh gọi lại CharacterDataHandler() bất cứ khi nào có thể. Điều này có thể cải thiện đáng kể hiệu suất vì Expat thường chia dữ liệu ký tự thành nhiều phần ở cuối mỗi dòng. Thuộc tính này mặc định là sai và có thể thay đổi bất kỳ lúc nào. Lưu ý rằng khi giá trị này sai, dữ liệu không chứa dòng mới cũng có thể bị phân đoạn.

xmlparser.buffer_used

Nếu buffer_text được bật, số byte được lưu trong bộ đệm. Các byte này đại diện cho văn bản được mã hóa UTF-8. Thuộc tính này không có ý nghĩa gì khi buffer_text sai.

xmlparser.ordered_attributes

Việc đặt thuộc tính này thành số nguyên khác 0 sẽ khiến các thuộc tính được báo cáo dưới dạng danh sách thay vì từ điển. Các thuộc tính được trình bày theo thứ tự tìm thấy trong văn bản tài liệu. Đối với mỗi thuộc tính, hai mục danh sách được trình bày: tên thuộc tính và giá trị thuộc tính. (Các phiên bản cũ hơn của mô-đun này cũng sử dụng định dạng này.) Theo mặc định, thuộc tính này là sai; nó có thể được thay đổi bất cứ lúc nào.

xmlparser.specified_attributes

Nếu được đặt thành số nguyên khác 0, trình phân tích cú pháp sẽ chỉ báo cáo những thuộc tính đã được chỉ định trong phiên bản tài liệu chứ không phải những thuộc tính được lấy từ khai báo thuộc tính. Các ứng dụng thiết lập điều này cần phải đặc biệt cẩn thận trong việc sử dụng những thông tin bổ sung có sẵn từ các phần khai báo khi cần thiết để tuân thủ các tiêu chuẩn về hoạt động của bộ xử lý XML. Theo mặc định, thuộc tính này là sai; nó có thể được thay đổi bất cứ lúc nào.

Các thuộc tính sau chứa các giá trị liên quan đến lỗi gần đây nhất mà đối tượng xmlparser gặp phải và sẽ chỉ có giá trị chính xác khi lệnh gọi tới Parse() hoặc ParseFile() đã đưa ra ngoại lệ xml.parsers.expat.ExpatError.

xmlparser.ErrorByteIndex

Chỉ số byte tại đó xảy ra lỗi.

xmlparser.ErrorCode

Mã số xác định vấn đề. Giá trị này có thể được chuyển đến hàm ErrorString() hoặc được so sánh với một trong các hằng số được xác định trong đối tượng errors.

xmlparser.ErrorColumnNumber

Số cột xảy ra lỗi.

xmlparser.ErrorLineNumber

Số dòng xảy ra lỗi.

Các thuộc tính sau chứa các giá trị liên quan đến vị trí phân tích cú pháp hiện tại trong đối tượng xmlparser. Trong quá trình gọi lại báo cáo một sự kiện phân tích cú pháp, chúng cho biết vị trí của chuỗi ký tự đầu tiên đã tạo ra sự kiện. Khi được gọi bên ngoài lệnh gọi lại, vị trí được chỉ định sẽ nằm ngay sau sự kiện phân tích cú pháp cuối cùng (bất kể có lệnh gọi lại liên quan hay không).

xmlparser.CurrentByteIndex

Chỉ số byte hiện tại trong đầu vào của trình phân tích cú pháp.

xmlparser.CurrentColumnNumber

Số cột hiện tại trong đầu vào của trình phân tích cú pháp.

xmlparser.CurrentLineNumber

Số dòng hiện tại trong đầu vào của trình phân tích cú pháp.

Đây là danh sách các trình xử lý có thể được thiết lập. Để đặt trình xử lý trên đối tượng xmlparser o, hãy sử dụng o.handlername = func. handlername phải được lấy từ danh sách sau đây và func phải là đối tượng có thể gọi được chấp nhận số lượng đối số chính xác. Các đối số đều là chuỗi, trừ khi có quy định khác.

xmlparser.XmlDeclHandler(version, encoding, standalone)

Được gọi khi khai báo XML được phân tích cú pháp. Khai báo XML là khai báo (tùy chọn) của phiên bản áp dụng của đề xuất XML, mã hóa văn bản tài liệu và khai báo "độc lập" tùy chọn. version và encoding sẽ là chuỗi và standalone sẽ là 1 nếu tài liệu được khai báo độc lập, 0 nếu tài liệu được khai báo không độc lập hoặc -1 nếu mệnh đề độc lập bị bỏ qua. Tính năng này chỉ khả dụng với phiên bản Expat 1.95.0 hoặc mới hơn.

xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)

Được gọi khi Expat bắt đầu phân tích cú pháp khai báo loại tài liệu (<!DOCTYPE ...). Zz002zz được cung cấp chính xác như đã trình bày. Các tham số systemId và publicId cung cấp số nhận dạng công khai và hệ thống nếu được chỉ định hoặc None nếu bị bỏ qua. has_internal_subset sẽ đúng nếu tài liệu chứa tập hợp con khai báo tài liệu nội bộ. Điều này yêu cầu phiên bản Expat 1.2 hoặc mới hơn.

xmlparser.EndDoctypeDeclHandler()

Được gọi khi Expat phân tích xong phần khai báo loại tài liệu. Điều này yêu cầu phiên bản Expat 1.2 hoặc mới hơn.

xmlparser.ElementDeclHandler(name, model)

Được gọi một lần cho mỗi khai báo kiểu phần tử. name là tên của loại phần tử và model là đại diện cho mô hình nội dung.

xmlparser.AttlistDeclHandler(elname, attname, type, default, required)

Được gọi cho từng thuộc tính được khai báo cho một loại phần tử. Nếu một khai báo danh sách thuộc tính khai báo ba thuộc tính, trình xử lý này sẽ được gọi ba lần, một lần cho mỗi thuộc tính. elname là tên của phần tử được áp dụng khai báo và attname là tên của thuộc tính được khai báo. Loại thuộc tính là một chuỗi được truyền dưới dạng type; các giá trị có thể là 'CDATA', 'ID', 'IDREF', ... default cung cấp giá trị mặc định cho thuộc tính được sử dụng khi thuộc tính không được chỉ định bởi phiên bản tài liệu hoặc None nếu không có giá trị mặc định (giá trị #IMPLIED). Nếu thuộc tính bắt buộc phải được cung cấp trong phiên bản tài liệu, required sẽ đúng. Điều này yêu cầu phiên bản Expat 1.95.0 hoặc mới hơn.

xmlparser.StartElementHandler(name, attributes)

Được gọi để bắt đầu mọi phần tử. name là một chuỗi chứa tên thành phần và attributes là thuộc tính của thành phần. Nếu ordered_attributes đúng thì đây là danh sách (xem ordered_attributes để biết mô tả đầy đủ). Mặt khác, đó là từ điển ánh xạ tên tới các giá trị.

xmlparser.EndElementHandler(name)

Được gọi là sự kết thúc của mọi phần tử.

xmlparser.ProcessingInstructionHandler(target, data)

Được gọi cho mọi hướng dẫn xử lý.

xmlparser.CharacterDataHandler(data)

Được gọi cho dữ liệu ký tự. Điều này sẽ được gọi cho dữ liệu ký tự bình thường, nội dung được đánh dấu CDATA và khoảng trắng không thể bỏ qua. Các ứng dụng phải phân biệt các trường hợp này có thể sử dụng lệnh gọi lại StartCdataSectionHandler, EndCdataSectionHandler và ElementDeclHandler để thu thập thông tin cần thiết. Lưu ý rằng dữ liệu ký tự có thể bị phân đoạn ngay cả khi nó ngắn và do đó bạn có thể nhận được nhiều lệnh gọi tới CharacterDataHandler(). Đặt thuộc tính phiên bản buffer_text thành True để tránh điều đó.

xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)

Được gọi để khai báo thực thể chưa được phân tích cú pháp (NDATA). Tính năng này chỉ có ở phiên bản 1.2 của thư viện Expat; đối với các phiên bản mới hơn, thay vào đó hãy sử dụng EntityDeclHandler. (Chức năng cơ bản trong thư viện Expat đã được tuyên bố là lỗi thời.)

xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

Được gọi cho tất cả các khai báo thực thể. Đối với tham số và các thực thể bên trong, value sẽ là một chuỗi cung cấp nội dung khai báo của thực thể; đây sẽ là None cho các thực thể bên ngoài. Tham số notationName sẽ là None cho các thực thể được phân tích cú pháp và tên của ký hiệu cho các thực thể chưa được phân tích cú pháp. is_parameter_entity sẽ đúng nếu thực thể là thực thể tham số hoặc sai đối với các thực thể chung (hầu hết các ứng dụng chỉ cần quan tâm đến các thực thể chung). Tính năng này chỉ khả dụng bắt đầu từ phiên bản 1.95.0 của thư viện Expat.

xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)

Được gọi để khai báo ký hiệu. notationName, base, systemId và publicId là các chuỗi nếu được cung cấp. Nếu mã định danh công khai bị bỏ qua, publicId sẽ là None.

xmlparser.StartNamespaceDeclHandler(prefix, uri)

Được gọi khi một phần tử chứa khai báo vùng tên. Các khai báo không gian tên được xử lý trước khi StartElementHandler được gọi cho phần tử mà các khai báo được đặt trên đó.

xmlparser.EndNamespaceDeclHandler(prefix)

Được gọi khi đạt đến thẻ đóng cho một phần tử chứa khai báo vùng tên. Điều này được gọi một lần cho mỗi khai báo vùng tên trên phần tử theo ngược lại thứ tự mà StartNamespaceDeclHandler được gọi để cho biết điểm bắt đầu của phạm vi của mỗi vùng khai báo vùng tên. Các cuộc gọi đến trình xử lý này được thực hiện sau EndElementHandler tương ứng ở phần cuối của phần tử.

xmlparser.CommentHandler(data)

Đã kêu gọi bình luận. data là nội dung của nhận xét, không bao gồm '<!--' ở đầu và '-->' ở cuối.

xmlparser.StartCdataSectionHandler()

Được gọi khi bắt đầu phần CDATA. Điều này và EndCdataSectionHandler là cần thiết để có thể xác định phần bắt đầu và kết thúc cú pháp cho các phần CDATA.

xmlparser.EndCdataSectionHandler()

Được gọi ở cuối phần CDATA.

xmlparser.DefaultHandler(data)

Được gọi cho bất kỳ ký tự nào trong tài liệu XML mà không có trình xử lý thích hợp nào được chỉ định. Điều này có nghĩa là các ký tự là một phần của cấu trúc có thể được báo cáo nhưng không có trình xử lý nào được cung cấp.

xmlparser.DefaultHandlerExpand(data)

Điều này giống như DefaultHandler() nhưng không ngăn cản việc mở rộng các thực thể bên trong. Tham chiếu thực thể sẽ không được chuyển tới trình xử lý mặc định.

xmlparser.NotStandaloneHandler()

Được gọi nếu tài liệu XML chưa được khai báo là tài liệu độc lập. Điều này xảy ra khi có một tập hợp con bên ngoài hoặc một tham chiếu đến một thực thể tham số, nhưng khai báo XML không được đặt độc lập thành yes trong khai báo XML. Nếu trình xử lý này trả về 0 thì trình phân tích cú pháp sẽ đưa ra lỗi XML_ERROR_NOT_STANDALONE. Nếu trình xử lý này không được đặt, thì trình phân tích cú pháp sẽ không đưa ra ngoại lệ cho điều kiện này.

xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)

Cảnh báo

Việc triển khai trình xử lý truy cập các tệp cục bộ và/hoặc mạng có thể tạo ra lỗ hổng cho external entity attacks nếu xmlparser đượ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 triển khai trình xử lý này.

Được gọi để tham chiếu đến các thực thể bên ngoài. base là cơ sở hiện tại, được thiết lập bởi lệnh gọi SetBase() trước đó. Các mã định danh công khai và hệ thống, systemId và publicId, là các chuỗi nếu được cung cấp; nếu mã định danh công khai không được cung cấp, publicId sẽ là None. Giá trị context không rõ ràng và chỉ nên được sử dụng như mô tả bên dưới.

Để phân tích cú pháp các thực thể bên ngoài, trình xử lý này phải được triển khai. Nó chịu trách nhiệm tạo trình phân tích cú pháp phụ bằng cách sử dụng ExternalEntityParserCreate(context), khởi tạo nó bằng các lệnh gọi lại thích hợp và phân tích cú pháp thực thể. Trình xử lý này sẽ trả về một số nguyên; nếu nó trả về 0, trình phân tích cú pháp sẽ đưa ra lỗi XML_ERROR_EXTERNAL_ENTITY_HANDLING, nếu không quá trình phân tích cú pháp sẽ tiếp tục.

Nếu trình xử lý này không được cung cấp, các thực thể bên ngoài sẽ được báo cáo bằng lệnh gọi lại DefaultHandler, nếu được cung cấp.

Ngoại lệExtError

Các trường hợp ngoại lệ của ExpatError có một số thuộc tính thú vị:

ExpatError.code

Số lỗi nội bộ của người nước ngoài cho lỗi cụ thể. Từ điển errors.messages ánh xạ các số lỗi này tới các thông báo lỗi của Expat. Ví dụ:

từ xml.parsers.expat nhập ParserCreate, ExpatError, lỗi

p = Trình phân tích cú phápTạo()
thử:
    p.Parse(some_xml_document)
ngoại trừ ExpatError là lỗi:
    print("Lỗi:", Error.messages[err.code])

Mô-đun errors cũng cung cấp các hằng số thông báo lỗi và từ điển codes ánh xạ các thông báo này trở lại mã lỗi, xem bên dưới.

ExpatError.lineno

Số dòng mà lỗi được phát hiện. Dòng đầu tiên được đánh số 1.

ExpatError.offset

Ký tự lệch vào dòng xảy ra lỗi. Cột đầu tiên được đánh số 0.

Ví dụ

Chương trình sau đây xác định ba trình xử lý chỉ in ra các đối số của chúng.

nhập xml.parsers.expat

chức năng xử lý # 3
def start_element(tên, attrs):
    print('Phần tử bắt đầu:', tên, attrs)
def end_element(tên):
    print('Phần tử cuối:', name)
def char_data(dữ liệu):
    print('Dữ liệu ký tự:', Repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Văn bản ở đây</child1>
<child2 name="fred">Thêm văn bản</child2>
</parent>""", 1)

Đầu ra từ chương trình này là:

Phần tử bắt đầu: cha mẹ {'id': 'top'}
Phần tử bắt đầu: child1 {'name': 'paul'}
Dữ liệu ký tự: 'Văn bản ở đây'
Phần tử cuối: child1
Dữ liệu ký tự: '\n'
Phần tử bắt đầu: child2 {'name': 'fred'}
Dữ liệu ký tự: 'Thêm văn bản'
Phần tử cuối: child2
Dữ liệu ký tự: '\n'
Phần tử cuối: cha mẹ

Mô tả mẫu nội dung

Các mô hình nội dung được mô tả bằng cách sử dụng các bộ dữ liệu lồng nhau. Mỗi bộ chứa bốn giá trị: loại, bộ định lượng, tên và một bộ con. Trẻ em chỉ đơn giản là mô tả mô hình nội dung bổ sung.

Giá trị của hai trường đầu tiên là hằng số được xác định trong mô-đun xml.parsers.expat.model. Các hằng số này có thể được tập hợp thành hai nhóm: nhóm loại mô hình và nhóm định lượng.

Các hằng số trong nhóm loại mô hình là:

xml.parsers.expat.model.XML_CTYPE_ANY

Phần tử được đặt tên theo tên model đã được khai báo là có model nội dung là ANY.

xml.parsers.expat.model.XML_CTYPE_CHOICE

Phần tử được đặt tên cho phép lựa chọn từ một số tùy chọn; cái này được sử dụng cho các mô hình nội dung như (A | B | C).

xml.parsers.expat.model.XML_CTYPE_EMPTY

Các phần tử được khai báo là EMPTY có loại mô hình này.

xml.parsers.expat.model.XML_CTYPE_MIXED
xml.parsers.expat.model.XML_CTYPE_NAME
xml.parsers.expat.model.XML_CTYPE_SEQ

Các mô hình đại diện cho một loạt các mô hình nối tiếp nhau được biểu thị bằng loại mô hình này. Điều này được sử dụng cho các mô hình như (A, B, C).

Các hằng số trong nhóm định lượng là:

xml.parsers.expat.model.XML_CQUANT_NONE

Không có công cụ sửa đổi nào được cung cấp nên nó có thể xuất hiện chính xác một lần, như đối với A.

xml.parsers.expat.model.XML_CQUANT_OPT

Mô hình này là tùy chọn: nó có thể xuất hiện một lần hoặc không xuất hiện lần nào, như đối với A?.

xml.parsers.expat.model.XML_CQUANT_PLUS

Mô hình phải xuất hiện một hoặc nhiều lần (như A+).

xml.parsers.expat.model.XML_CQUANT_REP

Mô hình phải xuất hiện từ 0 lần trở lên, như đối với A*.

Hằng số lỗi của người nước ngoài

Các hằng số sau được cung cấp trong mô-đun xml.parsers.expat.errors. Các hằng số này rất hữu ích trong việc diễn giải một số thuộc tính của các đối tượng ngoại lệ ExpatError được đưa ra khi xảy ra lỗi. Vì lý do tương thích ngược, giá trị của hằng số là lỗi message chứ không phải lỗi số code, bạn thực hiện việc này bằng cách so sánh thuộc tính code của nó với errors.codes[errors.XML_ERROR_CONSTANT_NAME].

Mô-đun errors có các thuộc tính sau:

xml.parsers.expat.errors.codes

Từ điển ánh xạ chuỗi mô tả tới mã lỗi của chúng.

Added in version 3.2.

xml.parsers.expat.errors.messages

Từ điển ánh xạ mã lỗi số vào mô tả chuỗi của chúng.

Added in version 3.2.

xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY
xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

Tham chiếu thực thể trong giá trị thuộc tính đề cập đến thực thể bên ngoài thay vì thực thể bên trong.

xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF

Tham chiếu ký tự đề cập đến một ký tự không hợp lệ trong XML (ví dụ: ký tự 0 hoặc '&#0;').

xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF

Một tham chiếu thực thể đề cập đến một thực thể được khai báo bằng ký hiệu, do đó không thể phân tích cú pháp được.

xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE

Một thuộc tính đã được sử dụng nhiều lần trong thẻ bắt đầu.

xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING
xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN

Xảy ra khi byte đầu vào không thể được gán chính xác cho một ký tự; ví dụ: byte NUL (giá trị 0) trong luồng đầu vào UTF-8.

xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Đã xảy ra điều gì đó không phải là khoảng trắng sau phần tử tài liệu.

xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI

Một khai báo XML được tìm thấy ở đâu đó ngoài phần bắt đầu của dữ liệu đầu vào.

xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS

Tài liệu không chứa phần tử nào (XML yêu cầu tất cả tài liệu phải chứa chính xác một phần tử cấp cao nhất)..

xml.parsers.expat.errors.XML_ERROR_NO_MEMORY

Người nước ngoài không thể phân bổ bộ nhớ nội bộ.

xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF

Đã tìm thấy tham chiếu thực thể tham số ở nơi không được phép.

xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR

Một ký tự không đầy đủ được tìm thấy trong đầu vào.

xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF

Một tham chiếu thực thể chứa một tham chiếu khác đến cùng một thực thể; có thể thông qua một tên khác, và có thể gián tiếp.

xml.parsers.expat.errors.XML_ERROR_SYNTAX

Đã gặp phải một số lỗi cú pháp không xác định.

xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH

Thẻ kết thúc không khớp với thẻ bắt đầu mở trong cùng.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN

Một số mã thông báo (chẳng hạn như thẻ bắt đầu) không được đóng trước khi kết thúc luồng hoặc gặp mã thông báo tiếp theo.

xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY

Một tham chiếu đã được tạo cho một thực thể không được xác định.

xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING

Mã hóa tài liệu không được người nước ngoài hỗ trợ.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION

Phần được đánh dấu CDATA chưa được đóng.

xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING
xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE

Trình phân tích cú pháp xác định rằng tài liệu không "độc lập" mặc dù nó đã tự khai báo nằm trong phần khai báo XML và NotStandaloneHandler đã được đặt và trả về 0.

xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE
xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE
xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD

Một thao tác đã được yêu cầu yêu cầu biên dịch hỗ trợ DTD, nhưng Expat đã được định cấu hình mà không hỗ trợ DTD. Bản dựng tiêu chuẩn của mô-đun xml.parsers.expat sẽ không bao giờ báo cáo điều này.

xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

Một thay đổi hành vi đã được yêu cầu sau khi bắt đầu phân tích cú pháp. Thay đổi này chỉ có thể được thay đổi trước khi quá trình phân tích cú pháp bắt đầu. Điều này (hiện tại) chỉ được nâng lên bởi UseForeignDTD().

xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX

Đã tìm thấy tiền tố không được khai báo khi bật quá trình xử lý không gian tên.

xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX

Tài liệu đã cố gắng xóa khai báo vùng tên được liên kết với tiền tố.

xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE

Thực thể tham số chứa đánh dấu không đầy đủ.

xml.parsers.expat.errors.XML_ERROR_XML_DECL

Tài liệu không chứa thành phần tài liệu nào cả.

xml.parsers.expat.errors.XML_ERROR_TEXT_DECL

Đã xảy ra lỗi khi phân tích cú pháp khai báo văn bản trong một thực thể bên ngoài.

xml.parsers.expat.errors.XML_ERROR_PUBLICID

Các ký tự được tìm thấy trong id công khai không được phép.

xml.parsers.expat.errors.XML_ERROR_SUSPENDED

Thao tác được yêu cầu được thực hiện trên trình phân tích cú pháp bị treo nhưng không được phép. Điều này bao gồm các nỗ lực cung cấp đầu vào bổ sung hoặc dừng trình phân tích cú pháp.

xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED

Một nỗ lực để tiếp tục trình phân tích cú pháp đã được thực hiện khi trình phân tích cú pháp chưa bị tạm dừng.

xml.parsers.expat.errors.XML_ERROR_ABORTED

Điều này không nên được báo cáo cho các ứng dụng Python.

xml.parsers.expat.errors.XML_ERROR_FINISHED

Thao tác được yêu cầu được thực hiện trên một trình phân tích cú pháp đã phân tích xong thông tin đầu vào nhưng không được phép. Điều này bao gồm các nỗ lực cung cấp đầu vào bổ sung hoặc dừng trình phân tích cú pháp.

xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE
xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML

Một nỗ lực đã được thực hiện nhằm hủy khai báo tiền tố không gian tên dành riêng xml hoặc liên kết nó với một không gian tên khác URI.

xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS

Một nỗ lực đã được thực hiện để khai báo hoặc hủy khai báo tiền tố vùng tên dành riêng xmlns.

xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI

Một nỗ lực đã được thực hiện để liên kết URI của một tiền tố không gian tên dành riêng xml và xmlns với một tiền tố không gian tên khác.

xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT

Điều này không nên được báo cáo cho các ứng dụng Python.

xml.parsers.expat.errors.XML_ERROR_NO_BUFFER

Điều này không nên được báo cáo cho các ứng dụng Python.

xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH

Giới hạn về hệ số khuếch đại đầu vào (từ DTD và các thực thể) đã bị vi phạm.

xml.parsers.expat.errors.XML_ERROR_NOT_STARTED

Trình phân tích cú pháp đã được cố gắng dừng hoặc tạm dừng trước khi nó bắt đầu.

Added in version 3.14.

Chú thích cuối trang