xml.sax.handler.md

1> **Источник:** https://python-all.ru/3.10/library/xml.sax.handler.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`xml.sax.handler`](https://python-all.ru/3.10/library/xml.sax.handler.html#module-xml.sax.handler) – Базовые классы для обработчиков SAX89**Исходный код:** [Lib/xml/sax/handler.py](https://python-all.ru/src/3.10/Lib/xml/sax/handler.py)1011---1213API SAX определяет пять типов обработчиков: обработчики содержимого, обработчики DTD, обработчики ошибок, преобразователи сущностей и лексические обработчики. Приложениям обычно нужно реализовывать только те интерфейсы, события которых их интересуют; можно реализовать интерфейсы в одном или нескольких объектах. Реализации обработчиков должны наследовать от базовых классов из модуля [`xml.sax.handler`](https://python-all.ru/3.10/library/xml.sax.handler.html#module-xml.sax.handler), чтобы все методы получали реализации по умолчанию.1415#### `class xml.sax.handler.ContentHandler`1617Это главный интерфейс колбэков в SAX, самый важный для приложений. Порядок событий в этом интерфейсе соответствует порядку информации в документе.1819#### `class xml.sax.handler.DTDHandler`2021Обработка событий DTD.2223Этот интерфейс определяет только те события DTD, которые необходимы для базового разбора (неразобранные сущности и атрибуты).2425#### `class xml.sax.handler.EntityResolver`2627Базовый интерфейс для разрешения сущностей. Если создать объект, реализующий этот интерфейс, и зарегистрировать его в анализаторе, анализатор будет вызывать метод этого объекта для разрешения всех внешних сущностей.2829#### `class xml.sax.handler.ErrorHandler`3031Интерфейс, используемый анализатором для передачи сообщений об ошибках и предупреждениях приложению. Методы этого объекта управляют, преобразуются ли ошибки сразу в исключения или обрабатываются иным способом.3233#### `class xml.sax.handler.LexicalHandler`3435Интерфейс, используемый анализатором для представления редко возникающих событий, которые могут быть неинтересны многим приложениям.3637В дополнение к этим классам, [`xml.sax.handler`](https://python-all.ru/3.10/library/xml.sax.handler.html#module-xml.sax.handler) предоставляет символьные константы для имён возможностей и свойств.3839#### `xml.sax.handler.feature_namespaces`4041значение:4243`"http://xml.org/sax/features/namespaces"`4445true: Выполнять обработку пространства имён.4647false: По желанию не выполнять обработку пространства имён (подразумевает namespace-prefixes; по умолчанию).4849доступ: (при разборе) только чтение; (не при разборе) чтение/запись5051#### `xml.sax.handler.feature_namespace_prefixes`5253значение:5455`"http://xml.org/sax/features/namespace-prefixes"`5657true: Сообщать исходные имена с префиксами и атрибуты, используемые для объявлений пространства имён.5859false: Не сообщать атрибуты, используемые для объявлений пространства имён, и по желанию не сообщать исходные имена с префиксами (по умолчанию).6061доступ: (при разборе) только чтение; (не при разборе) чтение/запись6263#### `xml.sax.handler.feature_string_interning`6465значение:6667`"http://xml.org/sax/features/string-interning"`6869true: Все имена элементов, префиксы, имена атрибутов, URI пространства имён и локальные имена интернируются с помощью встроенной функции intern.7071false: Имена не обязательно интернируются, хотя могут (по умолчанию).7273доступ: (при разборе) только чтение; (не при разборе) чтение/запись7475#### `xml.sax.handler.feature_validation`7677значение:7879`"http://xml.org/sax/features/validation"`8081true: сообщать обо всех ошибках проверки (подразумеваются external-general-entities и external-parameter-entities).8283false: не сообщать об ошибках проверки.8485доступ: (при разборе) только чтение; (не при разборе) чтение/запись8687#### `xml.sax.handler.feature_external_ges`8889значение:9091`"http://xml.org/sax/features/external-general-entities"`9293true: включать все внешние общие (текстовые) сущности.9495false: не включать внешние общие сущности.9697доступ: (при разборе) только чтение; (не при разборе) чтение/запись9899#### `xml.sax.handler.feature_external_pes`100101значение:102103`"http://xml.org/sax/features/external-parameter-entities"`104105true: включать все внешние сущности параметров, включая внешнее подмножество DTD.106107false: не включать внешние сущности параметров, даже внешнее подмножество DTD.108109доступ: (при разборе) только чтение; (не при разборе) чтение/запись110111#### `xml.sax.handler.all_features`112113Список всех возможностей.114115#### `xml.sax.handler.property_lexical_handler`116117значение:118119`"http://xml.org/sax/properties/lexical-handler"`120121тип данных: xml.sax.handler.LexicalHandler (не поддерживается в Python 2)122123описание: необязательный обработчик-расширение для лексических событий, таких как комментарии.124125доступ: чтение/запись126127#### `xml.sax.handler.property_declaration_handler`128129значение:130131`"http://xml.org/sax/properties/declaration-handler"`132133тип данных: xml.sax.sax2lib.DeclHandler (не поддерживается в Python 2)134135описание: необязательный обработчик-расширение для событий, связанных с DTD, кроме нотаций и неразобранных сущностей.136137доступ: чтение/запись138139#### `xml.sax.handler.property_dom_node`140141значение:142143`"http://xml.org/sax/properties/dom-node"`144145тип данных: org.w3c.dom.Node (не поддерживается в Python 2)146147описание: при разборе – текущий узел DOM, который посещается, если это итератор DOM; при отсутствии разбора – корневой узел DOM для итерации.148149доступ: (при разборе) только чтение; (не при разборе) чтение/запись150151#### `xml.sax.handler.property_xml_string`152153значение:154155`"http://xml.org/sax/properties/xml-string"`156157тип данных: Bytes158159описание: буквальная строка символов, которая была источником для текущего события.160161доступ: только для чтения162163#### `xml.sax.handler.all_properties`164165Список всех известных имен свойств.166167## Объекты ContentHandler168169Ожидается, что пользователи будут создавать подклассы [`ContentHandler`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler) для поддержки своих приложений. Следующие методы вызываются парсером при соответствующих событиях во входном документе:170171#### `ContentHandler.setDocumentLocator(locator)`172173Вызывается парсером, чтобы предоставить приложению локатор для определения источника событий документа.174175SAX-парсерам настоятельно рекомендуется (хотя это не является обязательным) предоставлять локатор: если он это делает, то должен передать локатор приложению, вызвав этот метод до вызова любого другого метода в интерфейсе DocumentHandler.176177Локатор позволяет приложению определить конечную позицию любого события, связанного с документом, даже если парсер не сообщает об ошибке. Обычно приложение использует эту информацию для сообщения о собственных ошибках (например, содержимое символов, не соответствующее бизнес-правилам приложения). Информация, возвращаемая локатором, вероятно, недостаточна для использования в поисковой системе.178179Обратите внимание, что локатор будет возвращать корректную информацию только во время вызова событий этого интерфейса. Приложение не должно пытаться использовать его в любое другое время.180181#### `ContentHandler.startDocument()`182183Получает уведомление о начале документа.184185SAX-парсер вызовет этот метод только один раз, перед любыми другими методами в этом интерфейсе или в DTDHandler (за исключением [`setDocumentLocator()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.setDocumentLocator)).186187#### `ContentHandler.endDocument()`188189Получает уведомление о конце документа.190191SAX-парсер вызовет этот метод только один раз, и это будет последний метод, вызванный во время разбора. Парсер не должен вызывать этот метод, пока он не прекратил разбор (из-за невосстановимой ошибки) или не достиг конца входных данных.192193#### `ContentHandler.startPrefixMapping(prefix, uri)`194195Начинает область действия отображения префикса на URI пространства имен.196197Информация из этого события не требуется для обычной обработки пространств имен: SAX-ридер XML автоматически заменяет префиксы для имен элементов и атрибутов, когда включена функция `feature_namespaces` (по умолчанию).198199Однако бывают случаи, когда приложениям необходимо использовать префиксы в символьных данных или значениях атрибутов, где их нельзя безопасно расширить автоматически; события [`startPrefixMapping()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startPrefixMapping) и [`endPrefixMapping()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endPrefixMapping) предоставляют приложению информацию для самостоятельного расширения префиксов в этих контекстах, если это необходимо.200201Обратите внимание, что события [`startPrefixMapping()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startPrefixMapping) и [`endPrefixMapping()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endPrefixMapping) не гарантированно правильно вложены друг относительно друга: все события [`startPrefixMapping()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startPrefixMapping) произойдут до соответствующего события [`startElement()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startElement), а все события [`endPrefixMapping()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endPrefixMapping) произойдут после соответствующего события [`endElement()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endElement), но их порядок не гарантируется.202203#### `ContentHandler.endPrefixMapping(prefix)`204205Завершает область действия отображения префикса на URI.206207Подробнее см. [`startPrefixMapping()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startPrefixMapping). Это событие всегда происходит после соответствующего события [`endElement()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endElement), но порядок событий [`endPrefixMapping()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.endPrefixMapping) в остальном не гарантируется.208209#### `ContentHandler.startElement(name, attrs)`210211Сигнализирует о начале элемента в режиме без пространств имен.212213Параметр *name* содержит исходное XML 1.0 имя типа элемента в виде строки, а параметр *attrs* содержит объект интерфейса `Attributes` (см. [The Attributes Interface](https://python-all.ru/3.10/library/xml.sax.reader.html#attributes-objects)) с атрибутами элемента. Объект, передаваемый как *attrs*, может быть повторно использован парсером; хранение ссылки на него – ненадёжный способ сохранить копию атрибутов. Чтобы сохранить копию атрибутов, используйте метод [`copy()`](https://python-all.ru/3.10/library/copy.html#module-copy) объекта *attrs*.214215#### `ContentHandler.endElement(name)`216217Сигнализирует о конце элемента в режиме без пространства имён.218219Параметр *name* содержит имя типа элемента, как и событие [`startElement()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startElement).220221#### `ContentHandler.startElementNS(name, qname, attrs)`222223Сигнализирует о начале элемента в режиме пространства имён.224225Параметр *name* содержит имя типа элемента в виде кортежа `(uri, localname)`, параметр *qname* содержит исходное XML 1.0 имя, использованное в исходном документе, а параметр *attrs* содержит экземпляр интерфейса `AttributesNS` (см. [The AttributesNS Interface](https://python-all.ru/3.10/library/xml.sax.reader.html#attributes-ns-objects)) с атрибутами элемента. Если с элементом не связано пространство имён, компонент *uri* в *name* будет `None`. Объект, передаваемый как *attrs*, может быть повторно использован парсером; хранение ссылки на него – ненадёжный способ сохранить копию атрибутов. Чтобы сохранить копию атрибутов, используйте метод [`copy()`](https://python-all.ru/3.10/library/copy.html#module-copy) объекта *attrs*.226227Анализаторы могут установить параметр *qname* в `None`, если только не активирована функция `feature_namespace_prefixes`.228229#### `ContentHandler.endElementNS(name, qname)`230231Сигнализирует о конце элемента в режиме пространства имён.232233Параметр *name* содержит имя типа элемента, как и метод [`startElementNS()`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.ContentHandler.startElementNS), и аналогично параметр *qname*.234235#### `ContentHandler.characters(content)`236237Получает уведомление о символьных данных.238239Анализатор вызывает этот метод для сообщения каждого блока символьных данных. Анализаторы SAX могут возвращать все смежные символьные данные одним блоком или разбивать их на несколько блоков; однако все символы в любом отдельном событии должны происходить из одной и той же внешней сущности, чтобы Locator предоставлял полезную информацию.240241*content* может быть строкой или экземпляром bytes; модуль чтения `expat` всегда выдаёт строки.242243> **Примечание**244>245> Более ранний интерфейс SAX 1, предоставленный Python XML Special Interest Group, использовал более похожий на Java интерфейс для этого метода. Поскольку большинство анализаторов, используемых из Python, не использовали преимущества старого интерфейса, была выбрана более простая сигнатура для его замены. Чтобы преобразовать старый код в новый интерфейс, используйте *content* вместо нарезки content с помощью старых параметров *offset* и *length*.246247#### `ContentHandler.ignorableWhitespace(whitespace)`248249Получает уведомление об игнорируемых пробельных символах в содержимом элемента.250251Валидирующие анализаторы должны использовать этот метод для сообщения каждого блока игнорируемых пробельных символов (см. рекомендацию W3C XML 1.0, раздел 2.10): невалидирующие анализаторы также могут использовать этот метод, если они способны анализировать и использовать модели содержимого.252253Анализаторы SAX могут возвращать все смежные пробельные символы одним блоком или разбивать их на несколько блоков; однако все символы в любом отдельном событии должны происходить из одной и той же внешней сущности, чтобы Locator предоставлял полезную информацию.254255#### `ContentHandler.processingInstruction(target, data)`256257Получает уведомление об инструкции по обработке.258259Анализатор вызывает этот метод один раз для каждой найденной инструкции по обработке; обратите внимание, что инструкции по обработке могут встречаться до или после основного элемента документа.260261Анализатор SAX никогда не должен сообщать об объявлении XML (XML 1.0, раздел 2.8) или объявлении текста (XML 1.0, раздел 4.3.1) с помощью этого метода.262263#### `ContentHandler.skippedEntity(name)`264265Получает уведомление о пропущенной сущности.266267Анализатор вызывает этот метод один раз для каждой пропущенной сущности. Невалидирующие процессоры могут пропускать сущности, если они не видели объявления (например, если сущность была объявлена во внешнем подмножестве DTD). Все процессоры могут пропускать внешние сущности в зависимости от значений свойств `feature_external_ges` и `feature_external_pes`.268269## Объекты DTDHandler270271Экземпляры [`DTDHandler`](https://python-all.ru/3.10/library/xml.sax.handler.html#xml.sax.handler.DTDHandler) предоставляют следующие методы:272273#### `DTDHandler.notationDecl(name, publicId, systemId)`274275Обрабатывает событие объявления нотации.276277#### `DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)`278279Обрабатывает событие объявления неразобранной сущности.280281## Объекты EntityResolver282283#### `EntityResolver.resolveEntity(publicId, systemId)`284285Разрешает системный идентификатор сущности и возвращает либо системный идентификатор для чтения в виде строки, либо InputSource для чтения. Реализация по умолчанию возвращает *systemId*.286287## Объекты ErrorHandler288289Объекты с этим интерфейсом используются для получения информации об ошибках и предупреждениях от [`XMLReader`](https://python-all.ru/3.10/library/xml.sax.reader.html#xml.sax.xmlreader.XMLReader). Если вы создаете объект, реализующий этот интерфейс, и регистрируете его в своем [`XMLReader`](https://python-all.ru/3.10/library/xml.sax.reader.html#xml.sax.xmlreader.XMLReader), парсер будет вызывать методы вашего объекта для сообщения обо всех предупреждениях и ошибках. Доступны три уровня ошибок: предупреждения, (возможно) восстанавливаемые ошибки и невосстанавливаемые ошибки. Все методы принимают `SAXParseException` в качестве единственного параметра. Ошибки и предупреждения могут быть преобразованы в исключение путем возбуждения переданного объекта исключения.290291#### `ErrorHandler.error(exception)`292293Вызывается, когда парсер встречает восстанавливаемую ошибку. Если этот метод не возбуждает исключение, разбор может продолжиться, но приложению не следует ожидать дальнейшей информации о документе. Разрешение парсеру продолжить может позволить обнаружить дополнительные ошибки во входном документе.294295#### `ErrorHandler.fatalError(exception)`296297Вызывается, когда парсер встречает ошибку, из которой невозможно восстановиться; ожидается, что разбор завершится при возврате этого метода.298299#### `ErrorHandler.warning(exception)`300301Вызывается, когда парсер передает приложению информацию о незначительном предупреждении. Ожидается, что разбор продолжится при возврате этого метода, и информация о документе будет по-прежнему передаваться приложению. Возбуждение исключения в этом методе приведет к завершению разбора.302303## Объекты LexicalHandler304305Необязательный обработчик SAX2 для лексических событий.306307Этот обработчик используется для получения лексической информации об XML-документе. Лексическая информация включает сведения об используемой кодировке документа, XML-комментариях, встроенных в документ, а также о границах разделов для DTD и любых секций CDATA. Лексические обработчики используются так же, как и обработчики содержимого.308309Установите LexicalHandler для XMLReader с помощью метода setProperty с идентификатором свойства `'http://xml.org/sax/properties/lexical-handler'`.310311#### `LexicalHandler.comment(content)`312313Сообщает о комментарии в любом месте документа (включая DTD и вне корневого элемента).314315#### `LexicalHandler.startDTD(name, public_id, system_id)`316317Сообщает о начале объявлений DTD, если документ имеет связанную DTD.318319#### `LexicalHandler.endDTD()`320321Сообщает о конце объявления DTD.322323#### `LexicalHandler.startCDATA()`324325Сообщает о начале секции CDATA.326327Содержимое секции CDATA будет передано через обработчик символов.328329#### `LexicalHandler.endCDATA()`330331Сообщает о конце секции CDATA.332