`xml.sax.handler.md`

258 строк · 27.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/xml.sax.handler.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `xml.sax.handler` – Базовые классы для обработчиков SAX89API SAX определяет четыре вида обработчиков: обработчики содержимого, обработчики DTD, обработчики ошибок и разрешители сущностей. Обычно приложениям нужно реализовывать только те интерфейсы, события которых их интересуют; они могут реализовать интерфейсы в одном объекте или в нескольких объектах. Реализации обработчиков должны наследоваться от базовых классов, предоставляемых модулем `xml.sax.handler`, чтобы все методы получили реализации по умолчанию.1011#### `[xml.sax.handler.ContentHandler]class xml.sax.handler.ContentHandler`1213Это главный интерфейс колбэков в SAX, самый важный для приложений. Порядок событий в этом интерфейсе соответствует порядку информации в документе.1415#### `[xml.sax.handler.DTDHandler]class xml.sax.handler.DTDHandler`1617Обработка событий DTD.1819Этот интерфейс определяет только те события DTD, которые необходимы для базового разбора (неразобранные сущности и атрибуты).2021#### `[xml.sax.handler.EntityResolver]class xml.sax.handler.EntityResolver`2223Базовый интерфейс для разрешения сущностей. Если создать объект, реализующий этот интерфейс, и зарегистрировать его в анализаторе, анализатор будет вызывать метод этого объекта для разрешения всех внешних сущностей.2425#### `[xml.sax.handler.ErrorHandler]class xml.sax.handler.ErrorHandler`2627Интерфейс, используемый анализатором для передачи сообщений об ошибках и предупреждениях приложению. Методы этого объекта управляют, преобразуются ли ошибки сразу в исключения или обрабатываются иным способом.2829В дополнение к этим классам, `xml.sax.handler` предоставляет символические константы для имён функций и свойств.3031#### `[xml.sax.handler.feature_namespaces]xml.sax.handler.feature_namespaces`3233Значение:3435`"http://xml.org/sax/features/namespaces"`3637– true: Выполнять обработку пространств имён. false: По желанию не выполнять обработку пространств имён (подразумевает namespace-prefixes; по умолчанию). – доступ: (при разборе) только чтение; (не при разборе) чтение/запись3839#### `[xml.sax.handler.feature_namespace_prefixes]xml.sax.handler.feature_namespace_prefixes`4041Значение:4243`"http://xml.org/sax/features/namespace-prefixes"`4445– true: Сообщать исходные имена с префиксами и атрибуты, используемые для объявлений пространств имён. false: Не сообщать атрибуты, используемые для объявлений пространств имён, и по желанию не сообщать исходные имена с префиксами (по умолчанию). – доступ: (при разборе) только чтение; (не при разборе) чтение/запись4647#### `[xml.sax.handler.feature_string_interning]xml.sax.handler.feature_string_interning`4849Значение:5051`"http://xml.org/sax/features/string-interning"`5253– true: Все имена элементов, префиксы, имена атрибутов, URI пространств имён и локальные имена интернируются с помощью встроенной функции intern. false: Имена не обязательно интернируются, хотя могут быть (по умолчанию). – доступ: (при разборе) только чтение; (не при разборе) чтение/запись5455#### `[xml.sax.handler.feature_validation]xml.sax.handler.feature_validation`5657Значение:5859`"http://xml.org/sax/features/validation"`6061– true: Сообщать все ошибки валидации (подразумевает external-general-entities и external-parameter-entities). false: Не сообщать ошибки валидации. – доступ: (при разборе) только чтение; (не при разборе) чтение/запись6263#### `[xml.sax.handler.feature_external_ges]xml.sax.handler.feature_external_ges`6465Значение:6667`"http://xml.org/sax/features/external-general-entities"`6869– true: Включать все внешние общие (текстовые) сущности. false: Не включать внешние общие сущности. – доступ: (при разборе) только чтение; (не при разборе) чтение/запись7071#### `[xml.sax.handler.feature_external_pes]xml.sax.handler.feature_external_pes`7273Значение:7475`"http://xml.org/sax/features/external-parameter-entities"`7677– true: Включать все внешние параметрические сущности, включая внешнее подмножество DTD. – false: Не включать никакие внешние параметрические сущности, даже внешнее подмножество DTD. – доступ: (при разборе) только чтение; (не при разборе) чтение/запись7879#### `[xml.sax.handler.all_features]xml.sax.handler.all_features`8081Список всех возможностей.8283#### `[xml.sax.handler.property_lexical_handler]xml.sax.handler.property_lexical_handler`8485Значение:8687`"http://xml.org/sax/properties/lexical-handler"`8889– тип данных: xml.sax.sax2lib.LexicalHandler (не поддерживается в Python 2) – описание: Необязательный расширенный обработчик для лексических событий, таких как комментарии. – доступ: чтение/запись9091#### `[xml.sax.handler.property_declaration_handler]xml.sax.handler.property_declaration_handler`9293Значение:9495`"http://xml.org/sax/properties/declaration-handler"`9697– тип данных: xml.sax.sax2lib.DeclHandler (не поддерживается в Python 2) – описание: Необязательный расширенный обработчик для событий, связанных с DTD, кроме нотаций и неразобранных сущностей. – доступ: чтение/запись9899#### `[xml.sax.handler.property_dom_node]xml.sax.handler.property_dom_node`100101Значение:102103`"http://xml.org/sax/properties/dom-node"`104105– тип данных: org.w3c.dom.Node (не поддерживается в Python 2) – описание: При разборе – текущий узел DOM, который посещается, если это итератор DOM; при отсутствии разбора – корневой узел DOM для итерации. – доступ: (при разборе) только чтение; (не при разборе) чтение/запись106107#### `[xml.sax.handler.property_xml_string]xml.sax.handler.property_xml_string`108109Значение:110111`"http://xml.org/sax/properties/xml-string"`112113– тип данных: String – описание: Буквенная строка символов, которая была источником текущего события. – доступ: только чтение114115#### `[xml.sax.handler.all_properties]xml.sax.handler.all_properties`116117Список всех известных имен свойств.118119## Объекты ContentHandler120121Ожидается, что пользователи будут создавать подклассы [`ContentHandler`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler) для поддержки своего приложения. Следующие методы вызываются анализатором при соответствующих событиях во входном документе:122123#### `[xml.sax.handler.ContentHandler.setDocumentLocator]ContentHandler.setDocumentLocator(locator)`124125Вызывается парсером, чтобы предоставить приложению локатор для определения источника событий документа.126127SAX-парсерам настоятельно рекомендуется (хотя это не является обязательным) предоставлять локатор: если он это делает, то должен передать локатор приложению, вызвав этот метод до вызова любого другого метода в интерфейсе DocumentHandler.128129Локатор позволяет приложению определить конечную позицию любого события, связанного с документом, даже если парсер не сообщает об ошибке. Обычно приложение использует эту информацию для сообщения о собственных ошибках (например, содержимое символов, не соответствующее бизнес-правилам приложения). Информация, возвращаемая локатором, вероятно, недостаточна для использования в поисковой системе.130131Обратите внимание, что локатор будет возвращать корректную информацию только во время вызова событий этого интерфейса. Приложение не должно пытаться использовать его в любое другое время.132133#### `[xml.sax.handler.ContentHandler.startDocument]ContentHandler.startDocument()`134135Получает уведомление о начале документа.136137Парсер SAX вызывает этот метод только один раз, до любого другого метода в этом интерфейсе или в DTDHandler (за исключением [`setDocumentLocator()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.setDocumentLocator)).138139#### `[xml.sax.handler.ContentHandler.endDocument]ContentHandler.endDocument()`140141Получает уведомление о конце документа.142143SAX-парсер вызовет этот метод только один раз, и это будет последний метод, вызванный во время разбора. Парсер не должен вызывать этот метод, пока он не прекратил разбор (из-за невосстановимой ошибки) или не достиг конца входных данных.144145#### `[xml.sax.handler.ContentHandler.startPrefixMapping]ContentHandler.startPrefixMapping(prefix, uri)`146147Начинает область действия отображения префикса на URI пространства имен.148149Информация из этого события не требуется для обычной обработки пространств имён: SAX XML-ридер автоматически заменяет префиксы для имён элементов и атрибутов, когда свойство `feature_namespaces` включено (по умолчанию включено).150151Однако бывают случаи, когда приложениям необходимо использовать префиксы в символьных данных или в значениях атрибутов, где их нельзя безопасно раскрыть автоматически; события [`startPrefixMapping()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startPrefixMapping) и [`endPrefixMapping()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endPrefixMapping) предоставляют приложению информацию для самостоятельного раскрытия префиксов в этих контекстах, если это необходимо.152153Обратите внимание, что события [`startPrefixMapping()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startPrefixMapping) и [`endPrefixMapping()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endPrefixMapping) не гарантируют правильной вложенности друг относительно друга: все события [`startPrefixMapping()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startPrefixMapping) происходят до соответствующего события [`startElement()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startElement), а все события [`endPrefixMapping()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endPrefixMapping) происходят после соответствующего события [`endElement()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endElement), но их порядок не гарантируется.154155#### `[xml.sax.handler.ContentHandler.endPrefixMapping]ContentHandler.endPrefixMapping(prefix)`156157Завершает область действия отображения префикса на URI.158159Подробнее см. [`startPrefixMapping()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startPrefixMapping). Это событие всегда происходит после соответствующего события [`endElement()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endElement), но в остальном порядок событий [`endPrefixMapping()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endPrefixMapping) не гарантируется.160161#### `[xml.sax.handler.ContentHandler.startElement]ContentHandler.startElement(name, attrs)`162163Сигнализирует о начале элемента в режиме без пространств имен.164165Параметр *name* содержит необработанное имя типа элемента в формате XML 1.0 в виде строки, а параметр *attrs* содержит объект интерфейса `Attributes` (см. [*Интерфейс Attributes*](https://python-all.ru/3.0/library/xml.sax.reader.html#attributes-objects)), который хранит атрибуты элемента. Объект, переданный как *attrs*, может быть повторно использован парсером; хранить на него ссылку – ненадёжный способ сохранить копию атрибутов. Чтобы сохранить копию атрибутов, используйте метод `copy()` объекта *attrs*.166167#### `[xml.sax.handler.ContentHandler.endElement]ContentHandler.endElement(name)`168169Сигнализирует о конце элемента в режиме без пространства имён.170171Параметр *name* содержит имя типа элемента, точно так же, как и в событии [`startElement()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startElement).172173#### `[xml.sax.handler.ContentHandler.startElementNS]ContentHandler.startElementNS(name, qname, attrs)`174175Сигнализирует о начале элемента в режиме пространства имён.176177Параметр *name* содержит имя типа элемента в виде кортежа `(uri, localname)`, параметр *qname* содержит необработанное имя в формате XML 1.0, использованное в исходном документе, а параметр *attrs* содержит экземпляр интерфейса `AttributesNS` (см. [*Интерфейс AttributesNS*](https://python-all.ru/3.0/library/xml.sax.reader.html#attributes-ns-objects)), хранящий атрибуты элемента. Если с элементом не связано пространство имён, компонент *uri* в *name* будет `None`. Объект, переданный как *attrs*, может быть повторно использован парсером; хранить на него ссылку – ненадёжный способ сохранить копию атрибутов. Чтобы сохранить копию атрибутов, используйте метод `copy()` объекта *attrs*.178179Парсеры могут устанавливать параметр *qname* в значение `None`, если только не активировано свойство `feature_namespace_prefixes`.180181#### `[xml.sax.handler.ContentHandler.endElementNS]ContentHandler.endElementNS(name, qname)`182183Сигнализирует о конце элемента в режиме пространства имён.184185Параметр *name* содержит имя типа элемента, точно так же, как и метод [`startElementNS()`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startElementNS), и аналогично параметр *qname*.186187#### `[xml.sax.handler.ContentHandler.characters]ContentHandler.characters(content)`188189Получает уведомление о символьных данных.190191Анализатор вызывает этот метод для сообщения каждого блока символьных данных. Анализаторы SAX могут возвращать все смежные символьные данные одним блоком или разбивать их на несколько блоков; однако все символы в любом отдельном событии должны происходить из одной и той же внешней сущности, чтобы Locator предоставлял полезную информацию.192193*content* может быть экземпляром строки или байтов; модуль ридера `expat` всегда создаёт строки.194195> **Примечание**196>197> Более ранний интерфейс SAX 1, предоставленный Python XML Special Interest Group, использовал более похожий на Java интерфейс для этого метода. Поскольку большинство анализаторов, используемых из Python, не использовали преимущества старого интерфейса, была выбрана более простая сигнатура для его замены. Чтобы преобразовать старый код в новый интерфейс, используйте *content* вместо нарезки content с помощью старых параметров *offset* и *length*.198199#### `[xml.sax.handler.ContentHandler.ignorableWhitespace]ContentHandler.ignorableWhitespace(whitespace)`200201Получает уведомление об игнорируемых пробельных символах в содержимом элемента.202203Валидирующие анализаторы должны использовать этот метод для сообщения каждого блока игнорируемых пробельных символов (см. рекомендацию W3C XML 1.0, раздел 2.10): невалидирующие анализаторы также могут использовать этот метод, если они способны анализировать и использовать модели содержимого.204205Анализаторы SAX могут возвращать все смежные пробельные символы одним блоком или разбивать их на несколько блоков; однако все символы в любом отдельном событии должны происходить из одной и той же внешней сущности, чтобы Locator предоставлял полезную информацию.206207#### `[xml.sax.handler.ContentHandler.processingInstruction]ContentHandler.processingInstruction(target, data)`208209Получает уведомление об инструкции по обработке.210211Анализатор вызывает этот метод один раз для каждой найденной инструкции по обработке; обратите внимание, что инструкции по обработке могут встречаться до или после основного элемента документа.212213Анализатор SAX никогда не должен сообщать об объявлении XML (XML 1.0, раздел 2.8) или объявлении текста (XML 1.0, раздел 4.3.1) с помощью этого метода.214215#### `[xml.sax.handler.ContentHandler.skippedEntity]ContentHandler.skippedEntity(name)`216217Получает уведомление о пропущенной сущности.218219Парсер вызывает этот метод один раз для каждой пропущенной сущности. Некоторые процессоры, не выполняющие проверку, могут пропускать сущности, если они не видели объявлений (например, потому что сущность была объявлена во внешнем подмножестве DTD). Все процессоры могут пропускать внешние сущности в зависимости от значений свойств `feature_external_ges` и `feature_external_pes`.220221## Объекты DTDHandler222223Экземпляры [`DTDHandler`](https://python-all.ru/3.0/library/xml.sax.handler.html#xml.sax.handler.DTDHandler) предоставляют следующие методы:224225#### `[xml.sax.handler.DTDHandler.notationDecl]DTDHandler.notationDecl(name, publicId, systemId)`226227Обрабатывает событие объявления нотации.228229#### `[xml.sax.handler.DTDHandler.unparsedEntityDecl]DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)`230231Обрабатывает событие объявления неразобранной сущности.232233## Объекты EntityResolver234235#### `[xml.sax.handler.EntityResolver.resolveEntity]EntityResolver.resolveEntity(publicId, systemId)`236237Разрешает системный идентификатор сущности и возвращает либо системный идентификатор для чтения в виде строки, либо InputSource для чтения. Реализация по умолчанию возвращает238239*systemId*240241.242243## Объекты ErrorHandler244245Объекты с этим интерфейсом используются для получения информации об ошибках и предупреждениях от `XMLReader`. Если создать объект, реализующий этот интерфейс, а затем зарегистрировать его в `XMLReader`, парсер будет вызывать методы этого объекта для сообщения обо всех предупреждениях и ошибках. Доступно три уровня ошибок: предупреждения, (возможно) исправимые ошибки и неисправимые ошибки. Все методы принимают `SAXParseException` в качестве единственного параметра. Ошибки и предупреждения могут быть преобразованы в исключение путём возбуждения переданного объекта исключения.246247#### `[xml.sax.handler.ErrorHandler.error]ErrorHandler.error(exception)`248249Вызывается, когда парсер встречает восстанавливаемую ошибку. Если этот метод не возбуждает исключение, разбор может продолжиться, но приложению не следует ожидать дальнейшей информации о документе. Разрешение парсеру продолжить может позволить обнаружить дополнительные ошибки во входном документе.250251#### `[xml.sax.handler.ErrorHandler.fatalError]ErrorHandler.fatalError(exception)`252253Вызывается, когда парсер встречает ошибку, из которой невозможно восстановиться; ожидается, что разбор завершится при возврате этого метода.254255#### `[xml.sax.handler.ErrorHandler.warning]ErrorHandler.warning(exception)`256257Вызывается, когда парсер передает приложению информацию о незначительном предупреждении. Ожидается, что разбор продолжится при возврате этого метода, и информация о документе будет по-прежнему передаваться приложению. Возбуждение исключения в этом методе приведет к завершению разбора.258