Содержание страницы

19.13. `xml.sax.xmlreader` – Интерфейс для XML-парсеров¶xml.sax.xmlreader – Interface for XML parsers

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

class xml.sax.xmlreader.XMLReader¶: Базовый класс, который могут наследовать парсеры SAX.

class xml.sax.xmlreader.IncrementalParser¶

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

После создания экземпляра парсер готов начать немедленно принимать данные через метод feed. После завершения разбора вызовом close необходимо вызвать метод reset, чтобы парсер снова был готов принимать новые данные, либо через feed, либо с помощью 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).

19.13.1. Объекты XMLReader¶XMLReader Objects

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

XMLReader.parse(source)¶: Обрабатывает входной источник, генерируя события SAX. Объект source может быть системным идентификатором (строкой, идентифицирующей входной источник – обычно имя файла или URL), файлоподобным объектом или объектом InputSource. Когда parse() возвращает управление, входные данные полностью обработаны, и объект анализатора может быть отброшен или сброшен. Ограничение: текущая реализация принимает только байтовые потоки; обработка символьных потоков – предмет дальнейшего изучения.

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.

19.13.2. Объекты IncrementalParser¶IncrementalParser Objects

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

IncrementalParser.feed(data)¶: Обрабатывает фрагмент data.

IncrementalParser.close()¶: Принимает конец документа. Это позволяет проверить условия корректности, которые могут быть проверены только в конце, вызвать обработчики и, возможно, освободить ресурсы, выделенные во время разбора.

IncrementalParser.reset()¶: Этот метод вызывается после вызова close для сброса парсера, чтобы он был готов к разбору новых документов. Результаты вызова parse или feed после close без вызова reset не определены.

19.13.3. Объекты Locator¶Locator Objects

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

Locator.getColumnNumber()¶: Возвращает номер столбца, в котором заканчивается текущее событие.

Locator.getLineNumber()¶: Возвращает номер строки, в которой заканчивается текущее событие.

Locator.getPublicId()¶: Возвращает общедоступный идентификатор текущего события.

Locator.getSystemId()¶: Возвращает системный идентификатор текущего события.

19.13.4. Объекты InputSource¶InputSource Objects

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)¶

Устанавливает байтовый поток (Python-подобный файловый объект, который не выполняет преобразование байтов в символы) для этого источника ввода.

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

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

InputSource.getByteStream()¶

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

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

InputSource.setCharacterStream(charfile)¶

Устанавливает символьный поток для этого источника ввода. (Поток должен быть файловым объектом, обёрнутым в Unicode Python 1.6, который выполняет преобразование в строки.)

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

InputSource.getCharacterStream()¶: Получить поток символов для этого источника ввода.

19.13.5. Интерфейс `Attributes`¶The Attributes Interface

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

Attributes.getLength()¶: Возвращает количество атрибутов.

Attributes.getNames()¶: Возвращает имена атрибутов.

Attributes.getType(name)¶: Возвращает тип атрибута name, который обычно равен 'CDATA'.

Attributes.getValue(name)¶: Возвращает значение атрибута имя.

19.13.6. Интерфейс `AttributesNS`¶The AttributesNS Interface

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

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

AttributesNS.getValueByQName(name)¶: Возвращает значение для полного имени.

AttributesNS.getNameByQName(name)¶: Возвращает пару (namespace, localname) для уточнённого name.

AttributesNS.getQNameByName(name)¶: Возвращает уточнённое имя для пары (namespace, localname).

AttributesNS.getQNames()¶: Возвращает полные имена всех атрибутов.