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.

The convenience functions and data are:

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, errorHandler=handler.ErrorHandler())

Create a SAX parser and use it to parse a document. The document, passed in as filename_or_stream, can be a system identifier (a string identifying the input source – typically a file name or a URL), a path-like object, or a file object. A system identifier which does not refer to an existing file is opened with urllib.request.urlopen(). The handler parameter needs to be a SAX ContentHandler instance. If errorHandler is given, it must be a SAX ErrorHandler instance; if omitted, SAXParseException will be raised on all errors. There is no return value; all work must be done by the handler passed in.

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

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

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

xml.sax.default_parser_list

The list of the names of modules which are tried by make_parser() after the modules named in its parser_list argument. It contains 'xml.sax.expatreader', or, if the PY_SAX_PARSER environment variable is set and the environment is not ignored, the comma-separated list of module names taken from it.

Типова програма 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 можуть використовувати цей клас для подібних цілей.

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

Subclass of SAXNotSupportedException raised when no parser is available. A parser module raises it when it is imported or during parsing if the parser it provides cannot be used, and make_parser() raises it if no module from the tried ones provides a usable parser.

Дивись також

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

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

Модуль xml.sax.handler

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

Модуль xml.sax.saxutils

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

Модуль xml.sax.xmlreader

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

Об’єкти SAXException

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

SAXException.getMessage()

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

SAXException.getException()

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