# `xml.sax` — Support for SAX2 parsers

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

The `xml.sax` package provides a number of modules which implement the Simple API for XML (SAX) interface for Python. The package itself provides the SAX exceptions and the convenience functions which will be most used by users of the 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 повинна отримати об’єкт читача, створити або відкрити джерела введення, створити обробники та з’єднати ці об’єкти разом. На останньому етапі підготовки читач викликається для аналізу введених даних. Під час синтаксичного аналізу методи об’єктів-обробників викликаються на основі структурних і синтаксичних подій із вхідних даних.

For these objects, only the interfaces are relevant; they are normally not instantiated by the application itself. Since Python does not have an explicit notion of interface, they are formally introduced as classes, but applications may use implementations which do not inherit from the provided classes. The `InputSource`, `Locator`, `Attributes`, `AttributesNS`, and `XMLReader` interfaces are defined in the module `xml.sax.xmlreader`. The handler interfaces are defined in `xml.sax.handler`. For convenience, `InputSource` (which is often instantiated directly) and the handler classes are also available from `xml.sax`. These interfaces are described below.

In addition to these classes, `xml.sax` provides the following exception classes.

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`.