[ Россум, Дрейк, Откидач ] Язык программирования Python

NotationDeclHandler(notationName, base, systemId, publicId)

Вызывается для обработки объявлений примечаний (‘<!NOTATION ...>’).

StartNamespaceDeclHandler(prefix, uri)

Вызывается, если элемент (открывающий тег) содержит объявление пространства имен.

EndNamespaceDeclHandler(prefix)

Вызывается для закрывающего тега элемента, содержащего объявление пространства имен.

CommentHandler(data)

Вызывается для комментариев.

StartCdataSectionHandler()

Вызывается в начале секции CDATA.

EndCdataSectionHandler()

Вызывается в конце секции CDATA.

DefaultHandler(data)

Вызывается для частей XML-документа, для которых не определен соответствующий обработчик. Части документа передаются в качестве аргумента data в исходном виде.

DefaultHandlerExpand(data)

Вызывается для частей XML-документа, для которых не определен соответствующий обработчик. Части документа передаются в качестве аргумента data после замены ссылок на сущности.

NotStandaloneHandler()

Вызывается, если XML-документ был объявлен как несамостоятельный (‘standalone="no"’ в заголовке).

ExternalEntityRefHandler(context, base, systemId,

publicId)

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

Приведем простейший пример использования модуля:

from xml.parsers import expat

def start_element(name, attrs):

print ’оБЮБМП ЬМЕНЕОФБ:’, name, attrs def end_element(name):

print ’лПОЕГ ЬМЕНЕОФБ:’, name def char_data(data):

print ’уЙНЧПМШОЩЕ ДБООЩЕ:’, repr(data)

p = expat.ParserCreate()

p.returns_unicode = 0 p.StartElementHandler = start_element p.EndElementHandler = end_element p.CharacterDataHandler = char_data

p.Parse("""\

<?xml version="1.0"?> <parent id="top">

<child1 name="paul">Text goes here</child1> <child2 name="fred">More text</child2>

</parent>""")

Вывод этой программы будет следующим:

оБЮБМП ЬМЕНЕОФБ: parent {’id’: ’top’} оБЮБМП ЬМЕНЕОФБ: child1 {’name’: ’paul’} уЙНЧПМШОЩЕ ДБООЩЕ: ’Text goes here’ лПОЕГ ЬМЕНЕОФБ: child1

уЙНЧПМШОЩЕ ДБООЩЕ: ’\012’

оБЮБМП ЬМЕНЕОФБ: child2 {’name’: ’fred’} уЙНЧПМШОЩЕ ДБООЩЕ: ’More text’

лПОЕГ ЬМЕНЕОФБ: child2 уЙНЧПМШОЩЕ ДБООЩЕ: ’\012’ лПОЕГ ЬМЕНЕОФБ: parent

29.5xml.sax — SAX2 интерфейс к синтаксическим анализаторам XML-документов

Этот модуль доступен, начиная с версии 2.0 и реализует SAX (Simple API for XML, простой программный интерфейс для XML) интерфейс.

Модуль xml.sax определяет следующие функции:

объект с SAX интерфейсом (экземпляр xml.sax.xmlreader.XMLReader или производного от него класса), реализующий синтаксический анализ XML-документа. Для этого используется первый найденный анализатор. Поиск модулей синтаксических анализаторов производится в списке parser_list (список имен модулей), если он задан, затем в списке модулей по умолчанию.

parse(filename_or_stream, handler [, error_handler])

Создает объект, реализующий синтаксический анализ XML-документа,

и использует его для анализа файла filename_or_stream. Аргумент filename_or_stream должен быть файловым (или подобным) объектом или строкой с именем файла. Аргумент handler должен быть экземпляром класса ContentHandler, реализующим обработку событий для содержимого документа. С помощью аргумента error_handler (должен быть экземпляром класса ErrorHandler) Вы можете задать способ обработки ошибок, по умолчанию для всех ошибок будет генерироваться исключение SAXParseException.

parseString(string, handler [, error_handler])

Работает аналогично функции parse(), но обрабатывает XML-документ, содержащийся в строке string.

Типичное SAX-приложение состоит из объекта, реализующего чтение и синтаксический анализ документа, преобразуя его в поток SAX-событий, объектов-обработчиков событий и объекта, представляющего сам XML-документ. Для всех этих объектов существенными являются только интерфейсы, формально представленные различными классами. Классы InputSource, Locator, + AttributesImpl и XMLReader определены в модуле xml.sax.xmlreader, интерфейсные классы обработчиков событий — в модуле xml.sax.handler. Для удобства модуль xml.sax импортирует в свое глобальное пространство имен классы InputSource, ContentHandler и ErrorHandler.

Модуль также определяет иерархию исключений:

SAXException

Этот класс является базовым для всех исключений модуля. Экземпляры SAXException и производных от него классов заключают в себе сообщение об ошибке и, часто, реальное исключение, сгенерированное выбранным синтаксическим анализатором. Эта информация доступна через методы исключения и getException() соответственно (последний может возвра-

класса генерируются при обнаружении синтаксианализируемом XML-документе. Экземпляры класса

SAXParseException имеют дополнительные методы getColumnNumber(), getLineNumber(), getPublicId() и getSystemId(), которые возвращают, соответственно, позицию в строке и номер строки, в которой возникла ошибка, и публичный и системный идентификаторы сущностей или None.

SAXNotRecognizedException

Исключения этого класса генерируются, если синтаксический анализатор сталкивается с неизвестной особенностью или свойством.

SAXNotSupportedException

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

SAXReaderNotAvailable

Исключения этого класса генерируются, если запрошенный анализатор не

может быть импортирован или не может выполнить внешнюю программу, необходимую для его работы.

29.6xml.sax.handler — базовые классы для обработчиков SAX-событий

Этот модуль (доступен, начиная с версии 2.0) определяет базовые классы с интерфейса SAX (см. описание модуля xml.sax) для обработки содержимого XML-документа, его DTD (Document Type Definition, определение типа документа), ошибок и ссылок на сущности. В производных классах необходимо переопределить только методы для интересующих Вас событий.

ContentHandler()

Этот класс определяет интерфейс обработчиков SAX-событий для содержимого XML-документа и является наиболее важным в SAX.

DTDHandler()

Определяет интерфейс обработчика событий для DTD (объявлений необрабатываемых сущностей и примечаний).

ErrorHandler()

Определяет интерфейс обработчика ошибок.

EntityResolver()

Определяет интерфейс обработчика ссылок на внешние сущности.

Помимо интерфейсных классов модуль xml.sax.handler определяет символические константы для имен функциональных особенностей (feature_*) и свойств (property_*). Эти константы могут быть использованы в качестве аргументов ме-

тодов getFeature(), setFeature(), getProperty() и setProperty() экземпляров xml.sax.xmlreader.XMLReader или производных от него классов. Заметим, что включение/выключение используемых особенностей возможно только до начала синтаксического анализа XML-документа.

feature_namespaces

Выполнять обработку пространств имен (является истиной по умолчанию).

feature_namespace_prefixes

Сообщать исходные имена с приставками элементов и атрибутов, используемые при объявлении пространств имен (по умолчанию является ложью).

feature_string_interning

Обрабатывать с помощью встроенной функции intern() все приставки, имена элементов и атрибутов, URI пространств имен и т. д. (по умолчанию является ложью, то есть такая обработка не обязательна).

feature_validation

Сообщать о несоответствии документа DTD.

feature_external_ges

Подключать внешние объявления текстовых сущностей.

feature_external_pes

Подключать внешние объявления сущностей параметров, включая внешнее подмножество DTD.

all_features

Список, содержащий все известные особенности.

property_lexical_handler

Необязательный обработчик лексических событий (например, комментариев). В версии 2.0 не поддерживается.

property_declaration_handler

Необязательный обработчик событий, связанных с DTD (кроме необрабатываемых сущностей и примечаний). В версии 2.0 не поддерживается.

property_dom_node

До начала синтаксического анализа — корневой, во время анализа — текущий узел объектной модели документа (DOM). Изменение этого свойства возможно только до начала анализа документа.

property_xml_string

Строка, содержащая фрагмент исходного текста документа для текущего события. Свойство доступно только для чтения.

all_properties

Список всех известных имен свойств.

29.6.1Интерфейс класса ContentHandler

Интерфейс класса ContentHandler составляют следующие методы:

setDocumentLocator(locator)

Вызывается синтаксическим анализатором XML-документа перед началом анализа. Объект locator (должен быть экземпляром xml.sax.xmlreader.Locator) предоставляет возможность получить информацию о позиции в документе соответствующей текущему событию. Эта информация обычно используется для вывода сообщений об ошибке. Заметим, что методы объекта locator должны возвращать корректный результат только во время обработки события.

startDocument()

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

endDocument()

Вызывается один раз для извещения о конце документа (при достижении конца ввода или возникновении ошибки, не допускающей восстановления).

startPrefixMapping(prefix, uri)

Вызывается в начале области действия пространства имен. Обработка этого события не является необходимой: синтаксический анализатор XML-документа автоматически заменяет приставку prefix на URI uri в именах элементов и атрибутов, если включена возможность feature_namespaces (эта возможность включена по умолчанию). Метод startPrefixMapping() всегда вызывается до соответствующего метода startElement(), однако правильный порядок следования нескольких событий startPrefixMapping() не гарантируется.

endPrefixMapping(prefix)

Вызывается в конце области действия пространства имен. Метод endPrefixMapping() всегда вызывается до соответствующего метода endElement(), однако правильный порядок следования нескольких событий endPrefixMapping() не гарантируется.

startElement(name, attrs)

Вызывается в начале элемента (без учета пространств имен). В качестве аргумента name используется строка с необработанным именем элемента, в качестве attrs — экземпляр класса xml.sax.xmlreader.AttributesImpl, описывающий атрибуты элемента.

endElement(name)

Вызывается в начале элемента (без учета пространств имен). В качестве аргумента name используется строка с необработанным именем элемента.

startElementNS(name, qname, attrs)

Вызывается в начале элемента (с учетом пространств имен). В качестве аргумента name используется кортеж, содержащий URI и имя элемента, в качестве qname — строка с необработанным именем элемента (может быть None, если отключена возможность feature_namespaces) и в качестве attrs — экземпляр класса xml.sax.xmlreader.AttributesNSImpl, описывающий атрибуты элемента.

endElementNS(name, qname)

Вызывается в конце элемента (с учетом пространств имен). В качестве аргумента name используется кортеж, содержащий URI и имя элемента, в качестве qname — строка с необработанным именем элемента (может быть None, если отключена возможность feature_namespaces).

characters(content)

Вызывается для символьных данных (аргумент content). Синтаксический анализатор документа может передавать непрерывный поток символьных данных этому методу несколькими порциями. Все символы, переданные методу одной порцией должны быть из одного элемента. Аргумент content может быть как обычной строкой, так и строкой Unicode.

ignorableWhitespace(whitespace)

Вызывается для символов пропуска (аргумент whitespace) в содержимом элемента, которые могут быть проигнорированы. Синтаксический анализатор документа может передавать непрерывный поток символов пропуска этому методу несколькими порциями. Все символы пропуска, переданные методу одной порцией должны быть из одного элемента.

processingInstruction(target, data)

Вызывается для инструкций обработки вида ‘<?target data?>’. Этот метод не должен вызываться для объявлений вида ‘<?xml ...>’.

skippedEntity(name)

Вызывается для всех сущностей, обработка которых синтаксическим анализатором не выполняется (например, если сущность объявлена во внешнем подмножестве DTD).

29.6.2Интерфейс класса DTDHandler

Интерфейс класса DTDHandler составляют следующие методы:

notationDecl(name, publicId, systemId)

Вызывается для обработки объявлений примечаний (‘<!NOTATION ...>’).

unparsedEntityDecl(name, publicId, systemId, ndata)

Вызывается для обработки объявлений необрабатываемых сущностей (NDATA).

29.6.3Интерфейс класса ErrorHandler

Интерфейс класса ErrorHandler составляют следующие методы:

error(exception)

Вызывается для обработки ошибок, допускающих продолжение дальнейшей работы. Исходная реализация генерирует исключение exception.

fatalError(exception)

Вызывается для обработки фатальных ошибок, то есть, не допускающих продолжение дальнейшей работы. Исходная реализация генерирует исключение exception.

warning(exception)

Вызывается для предупреждений. Исходная реализация выводит на стандартный поток вывода (sys.stdout) строковое представление исключения exception.

29.6.4 Интерфейс класса EntityResolver

Интерфейс класса EntityResolver составляют следующие методы:

resolveEntity(publicId, systemId)

Вызывается для необрабатываемых сущностей. Должен возвращать либо строку с системным идентификатором, либо экземпляр класса xml.sax.xmlreader.InputSource, который будет использован для считывания данных. Исходная реализация возвращает systemId.

29.7xml.sax.saxutils — вспомогательные средства для приложений, использующих SAX

Этот модуль (доступен, начиная с версии 2.0) определяет несколько классов и функций, которые обычно полезны при создании приложений, использующих SAX.

escape(data [, entities])

Заменяет символы ‘&’, ‘<’ и ‘>’ в строке data соответствующими ссылками на сущности и возвращает полученную строку. Вы можете произвести дополнительные замены, передав в качестве аргумента entities словарь, ключи которого будут заменены соответствующими им значениями.

XMLGenerator([out [, encoding]])

Этот класс является производным от ContentHandler, его методы реализуют запись SAX-событий назад в XML-документ. Другими словами, при использовании экземпляра класса XMLGenerator в качестве объекта, реализующего обработку содержимого XML-документа, будет воспроизведен исходный документ. Запись документа производится в файловый (или подобный) объект out, по умолчанию используется sys.stdout. Аргумент encoding задает кодировку создаваемого документа (по умолчанию используется ’iso-8859-1’).

XMLFilterBase(base)

Этот класс предназначен для использования в качестве “прослойки” между объектом base (экземпляр xml.sax.xmlreader.XMLReader или производного от него класса), реализующим синтаксический анализ XML-документа, и обработчиками SAX-событий. Исходная реализация просто переадресует события соответствующим обработчикам. В производных классах Вы можете переопределить определенные методы для того, чтобы изменять поток событий при их поступлении.

prepare_input_source(source [, base])

Возвращает экземпляр класса xml.sax.xmlreader.InputSource, готовый для чтения документа. Аргумент source может быть строкой с системным идентификатором, файловым (или подобным) объектом или экземпляром класса

xml.sax.xmlreader.InputSource. Аргумент base (по умолчанию равен пустой строке) используется в качестве основы URL (точки отсчета).

Функция prepare_input_source() обычно используется для реализации полиморфного восприятия аргумента source метода parse() объектов, реализующих чтение и синтаксический анализ XML-документов.

29.8xml.sax.xmlreader — интерфейс объектов, реализующих чтение и синтаксический анализ XMLдокументов

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

Модуль xml.sax.xmlreader определяет следующие классы:

XMLReader()

Базовый класс для всех синтаксических анализаторов XML-документов. Его методы ничего не делают и лишь определяют SAX-интерфейс.

IncrementalParser()

Метод parse() блокирует выполнение до тех пор, пока не будет прочитан весь документ. Данный класс предоставляет несколько дополнительных методов, которые позволяют подавать документ анализатору по частям. Класс IncrementalParser() также определяет метод parse(), реализованный с использованием этих методов. Этот класс является наиболее удобным для использования в качестве базового при написании синтаксических анализаторов.

Locator()

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

InputSource([systemId])

Экземпляры этого класса заключают в себе информацию о документе, необходимую для его анализа: публичный и системный идентификаторы, файловый объект, информацию о кодировке. Синтаксический анализатор не должен вносить изменения в этот объект, но может сделать его копию.

AttributesImpl(attrs)

Экземпляры этого класса используются для представления атрибутов элемента при вызове метода startElement() обработчика событий. Аргумент attrs должен быть отображением имен атрибутов к их значениям.

AttributesNSImpl(attrs, qnames)

Этот класс является производным от AttributesImpl, его экземпляры используются для представления атрибутов элемента с учетом пространства имен при вызове метода startElement() обработчика событий. Аргументы attrs и qnames должны быть отображениями, в качестве ключей в которых используются кортежи с URI пространства имен и локальным именем, а в качестве значений — значения и полные имена атрибутов соответственно.

29.8.1Интерфейс класса XMLReader

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

parse(source)

Анализирует XML-документ, формируя поток событий. Аргумент source должен быть строкой с системным идентификатором (обычно имя файла или URL), файловым (или подобным) объектом или экземпляром класса InputSource.

getContentHandler()

Возвращает текущий объект, реализующий обработку событий, касающихся содержимого документа (экземпляр xml.sax.handler.ContentHandler или производного от него класса).

setContentHandler(handler)

Запоминает handler как объект, реализующий обработку событий, касающихся содержимого документа (экземпляр xml.sax.handler.ContentHandler или производного от него класса). По умолчанию (до вызова этого метода) используется объект, игнорирующий все события.

getDTDHandler()

Возвращает текущий объект, реализующий обработку событий, касающихся DTD (экземпляр xml.sax.handler.DTDHandler или производного от него класса).

setDTDHandler(handler)

Запоминает handler как объект, реализующий обработку событий, касающихся DTD (экземпляр xml.sax.handler.DTDHandler или производного от него класса). По умолчанию (до вызова этого метода) используется объект, игнорирующий все события.

getEntityResolver()

Возвращает текущий объект, реализующий обработку ссылок на внешние сущности (экземпляр xml.sax.handler.EntityResolver или производного от него класса).

setEntityResolver(resolver)

Запоминает resolver как объект, реализующий обработку ссылок на внешние сущности (экземпляр xml.sax.handler.EntityResolver или производного от