xml.sax.xmlreader — Интерфейс для XML парсеров


SAX парсеры реализуют интерфейс XMLReader. Они определяются в Python модуле, предоставляющем функцию create_parser(). Данная функция вызывается xml.sax.make_parser() без аргументов для создания нового объекта парсера.

class xml.sax.xmlreader.XMLReader

Базовый класс, который может унаследоваться SAX парсерами.

class xml.sax.xmlreader.IncrementalParser

В некоторых случаях желательно не парсить источник сразу, а передавать фрагменты документа по мере их доступности. Обратите внимание, что программа чтения обычно не читает файл целиком, а также читает его по частям; по-прежнему parse() не возвратится, пока не будет обработан весь документ. Таким образом, данные интерфейсы следует использовать, если поведение блокировки parse() нежелательно.

Когда парсер создан, он готов немедленно начать принимать данные из метода feed. После того, как парсинг был завершён вызовом для закрытия, необходимо вызвать метод reset, чтобы парсер был готов принять новые данные либо из источника, либо с использованием метода parse.

Обратите внимание, что данные методы не должны вызываться во время парсинга, т. е. после вызова parse и до его возврата.

По умолчанию класс также реализует метод parse интерфейса XMLReader, используя методы feed, close и reset интерфейса IncrementalParser для удобства авторов драйверов SAX 2.0.

class xml.sax.xmlreader.Locator

Интерфейс для связывания SAX событий с местоположением документа. Объект локатора будет возвращать действительные результаты только во время вызовов методов DocumentHandler; в любое другое время результаты непредсказуемы. Если информация недоступна, методы могут возвращать None.

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

Инкапсуляция информации, необходимой XMLReader для чтения сущностей.

Данный класс может включать информацию об общедоступном идентификаторе, системном идентификаторе, потоке байтов (возможно, с информацией о кодировке символов) и/или потоке символов объекта.

Приложения будут создавать объекты класса для использования в методе XMLReader.parse() и для возврата из EntityResolver.resolveEntity.

InputSource принадлежит приложению, XMLReader не может изменять объекты InputSource, переданные ему из приложения, хотя он может делать копии и изменять их.

class xml.sax.xmlreader.AttributesImpl(attrs)

Реализация интерфейса Attributes (см. раздел Интерфейс Attributes). Это похожий на словарь объект, который представляет атрибуты элемента в вызове startElement(). Помимо наиболее полезных операций со словарями, он поддерживает ряд других методов, описанных в интерфейсе. Объекты класса должны создаваться читателями; attrs должен походить на словарный объект, содержащим сопоставление имён атрибутов со значениями атрибутов.

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

Вариант AttributesImpl с поддержкой пространства имён, передаваемый startElementNS(). Он является производным от AttributesImpl, но понимает имена атрибутов как два кортежа namespaceURI и localname. Кроме того, он предоставляет ряд методов, ожидающих использования полных имён в том виде, в каком они появляются в исходном документе. Данный класс реализует интерфейс AttributesNS (см. раздел Интерфейс AttributesNS).

Объекты XMLReader

Интерфейс XMLReader поддерживает следующие методы:

XMLReader.parse(source)

Процессинг источника ввода, создавая SAX события. Объект source может быть системным идентификатором (строка, идентифицирующая источник ввода — обычно имя файла или URL-адрес), объектом pathlib.Path или путеподобным объектом или объектом InputSource. Когда parse() возвращается, ввод полностью обрабатывается, и объект парсера может быть отброшен или сброшен.

Изменено в версии 3.5: Добавлена поддержка потоков символов.

Изменено в версии 3.8: Добавлена поддержка путеподобных объектов.

XMLReader.getContentHandler()

Возвращает текущий ContentHandler.

XMLReader.setContentHandler(handler)

Устанавливает текущий ContentHandler. Если ContentHandler не задан, события содержимого будут отброшены.

XMLReader.getDTDHandler()

Возвращает текущий DTDHandler.

XMLReader.setDTDHandler(handler)

Устанавливает текущий DTDHandler. Если DTDHandler не задан, события DTD будут отброшены.

XMLReader.getEntityResolver()

Возвращает текущий EntityResolver.

XMLReader.setEntityResolver(handler)

Устанавливает текущий EntityResolver. Если EntityResolver не задан, попытки разрешить внешний объект приведут к открытию системного идентификатора для объекта и завершатся ошибкой, если он недоступен.

XMLReader.getErrorHandler()

Возвращает текущий ErrorHandler.

XMLReader.setErrorHandler(handler)

Устанавливает текущий обработчик ошибок. Если ErrorHandler не задан, ошибки будут генерироваться как исключения, и будут напечатаны предупреждения.

XMLReader.setLocale(locale)

Разрешить приложению устанавливать языковой стандарт для ошибок и предупреждений.

SAX парсеры не обязаны обеспечивать локализацию ошибок и предупреждений; однако, если они не могут поддерживать запрошенную локаль, они должны вызвать SAX исключение. Приложения могут запросить изменение локали в середине парсера.

XMLReader.getFeature(featurename)

Возвращает текущую настройку для функции featurename. Если функция не распознана, вызывается SAXNotRecognizedException. Известные имена функций перечислены в модуле xml.sax.handler.

XMLReader.setFeature(featurename, value)

Устанавливает для featurename значение value. Если функция не распознана, вызывается SAXNotRecognizedException. Если функция или её настройка не поддерживаются парсером, вызывается SAXNotSupportedException.

XMLReader.getProperty(propertyname)

Возвращает текущую настройку для свойства propertyname. Если свойство не распознано, вызывается SAXNotRecognizedException. Известные имена свойств перечислены в модуле xml.sax.handler.

XMLReader.setProperty(propertyname, value)

Устанавливает propertyname на value. Если свойство не распознано, вызывается SAXNotRecognizedException. Если свойство или его настройка не поддерживаются парсером, вызывается SAXNotSupportedException.

Объекты IncrementalParser

Экземпляры IncrementalParser предлагают следующие дополнительные методы:

IncrementalParser.feed(data)

Обрабатывает кусок (chunk) data.

IncrementalParser.close()

Предположить конец документа. Проверит условия правильности, которые можно проверить только в конце, вызовет обработчики и может очистить ресурсы, выделенные во время парсинга.

IncrementalParser.reset()

Данный метод вызывается после вызова close для сброса парсера, чтобы он был готов к парсингу новых документов. Результаты вызова parse или feed после закрытия без вызова reset не определены.

Объекты Locator

Экземпляры Locator предоставляют данные методы:

Locator.getColumnNumber()

Возвращает номер столбца, с которого начинается текущее событие.

Locator.getLineNumber()

Возвращает номер строки, с которой начинается текущее событие.

Locator.getPublicId()

Возвращает общедоступный идентификатор текущего события.

Locator.getSystemId()

Возвращает системный идентификатор для текущего события.

Объекты InputSource

InputSource.setPublicId(id)

Устанавливает общедоступный идентификатор InputSource.

InputSource.getPublicId()

Возвращает общедоступный идентификатор InputSource.

InputSource.setSystemId(id)

Устанавливает системный идентификатор InputSource.

InputSource.getSystemId()

Возвращает системный идентификатор InputSource.

InputSource.setEncoding(encoding)

Устанавливает кодировку символов InputSource.

Кодировка должна быть строкой, приемлемой для объявления XML кодировки (см. раздел 4.3.3 рекомендаций по XML).

Атрибут кодирования InputSource игнорируется, если InputSource также содержит поток символов.

InputSource.getEncoding()

Получить кодировку символов InputSource.

InputSource.setByteStream(bytefile)

Устанавливает поток байтов (двоичный файл) для источника ввода.

SAX парсер проигнорирует это, если также указан поток символов, но он будет использовать поток байтов вместо открытия самого соединения URI.

Если приложению известна кодировка символов потока байтов, оно должно установить её с помощью метода setEncoding.

InputSource.getByteStream()

Получить поток байтов для источника ввода.

Метод getEncoding вернёт кодировку символов для потока байтов или None, если она неизвестна.

InputSource.setCharacterStream(charfile)

Устанавливает поток символов (текстовый файл) для источника ввода.

Если указан поток символов, SAX парсер будет игнорировать любой поток байтов и не будет пытаться открыть URI соединение с системным идентификатором.

InputSource.getCharacterStream()

Получает поток символов для источника ввода.

Интерфейс Attributes

Объекты Attributes реализуют часть протокола отображения, включая методы copy(), get(), __contains__(), items(), keys() и values(). Также предусмотрены следующие методы:

Attributes.getLength()

Возвращает количество атрибутов.

Attributes.getNames()

Возвращает имена атрибутов.

Attributes.getType(name)

Возвращает тип атрибута name, который обычно равен 'CDATA'.

Attributes.getValue(name)

Возвращает значение атрибута name.

Интерфейс AttributesNS

Данный интерфейс является подтипом интерфейса Attributes (см. раздел Интерфейс Attributes). Все методы, поддерживаемые этим интерфейсом, также доступны для объектов AttributesNS.

Также доступны следующие методы:

AttributesNS.getValueByQName(name)

Возвращает значение для квалифицированного имени.

AttributesNS.getNameByQName(name)

Возвращает пару (namespace, localname) для квалифицированного name.

AttributesNS.getQNameByName(name)

Возвращает полное имя для пары (namespace, localname).

AttributesNS.getQNames()

Возвращает полные имена всех атрибутов.