xml.sax — Support for SAX2 parsers

Вихідний код: Lib/xml/sax/__init__.py

Пакет xml.sax містить кілька модулів, які реалізують інтерфейс Simple API for XML (SAX) для Python. Сам пакет надає винятки SAX і зручні функції, якими найчастіше користуватимуться користувачі SAX API.

Примітка

If you need to parse untrusted or unauthenticated data, see XML security.

Змінено в версії 3.7.1: Синтаксичний аналізатор SAX більше не обробляє загальні зовнішні сутності за замовчуванням для підвищення безпеки. Раніше аналізатор створював мережеві підключення для отримання віддалених файлів або завантажував локальні файли з файлової системи для DTD і об’єктів. Цю функцію можна знову ввімкнути за допомогою методу setFeature() в об’єкті аналізатора та аргументі feature_external_ges.

Функції зручності:

xml.sax.make_parser(parser_list=[])

Створіть і поверніть об’єкт SAX XMLReader. Буде використано перший знайдений парсер. Якщо надається parser_list, це має бути ітерація рядків, які іменують модулі, які мають функцію з назвою create_parser(). Модулі, перелічені в parser_list, використовуватимуться перед модулями в стандартному списку аналізаторів.

Змінено в версії 3.8: Аргумент parser_list може бути будь-яким ітерованим, а не просто списком.

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

Створіть аналізатор SAX і використовуйте його для аналізу документа. Документ, переданий як filename_or_stream, може бути ім’ям файлу або об’єктом файлу. Параметр handler має бути екземпляром SAX ContentHandler. Якщо задано error_handler, це має бути екземпляр SAX ErrorHandler; якщо опущено, SAXParseException буде викликано для всіх помилок. Немає значення, що повертається; усю роботу має виконувати переданий обробник.

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

Подібно до parse(), але аналізує з рядка буфера, отриманого як параметр. рядок має бути екземпляром str або bytes-like object.

Змінено в версії 3.5: Додано підтримку екземплярів str.

Типова програма SAX використовує три види об’єктів: читачі, обробники та джерела введення. У цьому контексті «зчитувач» — це ще один термін для парсера, тобто деякого фрагмента коду, який зчитує байти або символи з джерела вхідних даних і створює послідовність подій. Потім події розподіляються на об’єкти обробника, тобто читач викликає метод обробника. Таким чином, програма SAX повинна отримати об’єкт читача, створити або відкрити джерела введення, створити обробники та з’єднати ці об’єкти разом. На останньому етапі підготовки читач викликається для аналізу введених даних. Під час синтаксичного аналізу методи об’єктів-обробників викликаються на основі структурних і синтаксичних подій із вхідних даних.

Для цих об’єктів актуальні лише інтерфейси; вони зазвичай не створюються самою програмою. Оскільки Python не має явного поняття інтерфейсу, вони формально представлені як класи, але програми можуть використовувати реалізації, які не успадковуються від наданих класів. InputSource, Locator, Attributes, AttributesNS та XMLReader визначені в модулі xml.sax.xmlreader. Інтерфейси обробника визначені в xml.sax.handler. Для зручності InputSource (який часто створюється безпосередньо) і класи обробників також доступні з xml.sax. Ці інтерфейси описані нижче.

На додаток до цих класів, xml.sax надає наступні класи винятків.

exception xml.sax.SAXException(msg, exception=None)

Інкапсулювати помилку XML або попередження. Цей клас може містити основну інформацію про помилку або попередження від синтаксичного аналізатора XML або програми: його можна розділити на підкласи, щоб забезпечити додаткові функції або додати локалізацію. Зауважте, що незважаючи на те, що обробники, визначені в інтерфейсі ErrorHandler, отримують екземпляри цього винятку, не обов’язково створювати виняток — він також корисний як контейнер для інформації.

Після створення msg має бути зрозумілим для людини описом помилки. Необов’язковий параметр exception, якщо його надано, має бути None або винятком, який був перехоплений кодом аналізу та передається як інформація.

Це базовий клас для інших класів винятків SAX.

exception xml.sax.SAXParseException(msg, exception, locator)

Підклас SAXException викликаний помилками аналізу. Екземпляри цього класу передаються методам інтерфейсу SAX ErrorHandler для надання інформації про помилку аналізу. Цей клас підтримує інтерфейс SAX Locator, а також інтерфейс SAXException.

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

Підклас SAXException викликається, коли SAX XMLReader стикається з нерозпізнаною функцією або властивістю. Програми та розширення SAX можуть використовувати цей клас для подібних цілей.

exception xml.sax.SAXNotSupportedException(msg, exception=None)

Підклас SAXException викликається, коли SAX XMLReader просять увімкнути функцію, яка не підтримується, або встановити для властивості значення, яке реалізація не підтримує . Програми та розширення SAX можуть використовувати цей клас для подібних цілей.

Дивись також

SAX: простий API для XML

Цей сайт є центром для визначення SAX API. Він надає реалізацію Java та онлайн-документацію. Також доступні посилання на впровадження та історичну інформацію.

Модуль xml.sax.handler

Визначення інтерфейсів для об’єктів, що надаються програмою.

Модуль xml.sax.saxutils

Функції зручності для використання в програмах SAX.

Модуль xml.sax.xmlreader

Визначення інтерфейсів для об’єктів, що надаються парсером.

Об’єкти SAXException

Клас винятків SAXException підтримує такі методи:

SAXException.getMessage()

Повернути зрозуміле для людини повідомлення з описом стану помилки.

SAXException.getException()

Повертає інкапсульований об’єкт винятку або None.