19.2. sgmllib – простой парсер SGML¶sgmllib – Simple SGML parser

Этот модуль определяет класс SGMLParser, который служит основой для разбора текстовых файлов в формате SGML (Standard Generalized Mark-up Language). На самом деле он не предоставляет полного парсера SGML – он разбирает SGML лишь настолько, насколько он используется в HTML, и существует только как база для модуля htmllib. Другой парсер HTML, поддерживающий XHTML и предлагающий несколько иной интерфейс, доступен в модуле HTMLParser.

class sgmllib.SGMLParser¶

Класс SGMLParser создаётся без аргументов. Парсер жёстко закодирован на распознавание следующих конструкций:

• Открывающие и закрывающие теги вида <tag attr="value" ...> и </tag> соответственно.

• Числовые символьные ссылки вида &#name;.

• Сущностные ссылки вида &name;.

• Комментарии SGML вида <!--text-->. Обратите внимание, что между завершающим > и непосредственно предшествующим -- допускаются пробелы, табуляции и символы новой строки.

Также определено одно исключение:

exception sgmllib.SGMLParseError¶

Исключение, вызываемое классом SGMLParser при обнаружении ошибки во время разбора.

Новое в версии 2.1.

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

SGMLParser.reset()¶

Сбрасывает экземпляр. Теряет все необработанные данные. Вызывается неявно при создании экземпляра.

SGMLParser.setnomoretags()¶

Прекратить обработку тегов. Всё последующее содержимое обрабатывается как литерал (CDATA). (Это предусмотрено только для того, чтобы можно было реализовать тег HTML <PLAINTEXT>.)

SGMLParser.setliteral()¶

Войти в литеральный режим (режим CDATA).

SGMLParser.feed(data)¶

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

SGMLParser.close()¶

Принудительно обработать все буферизированные данные так, как если бы за ними следовал маркер конца файла. Этот метод может быть переопределён в производном классе для задания дополнительной обработки в конце входных данных, но переопределённая версия всегда должна вызывать close().

SGMLParser.get_starttag_text()¶

Возвращает текст самого последнего открытого начального тега. Обычно это не требуется для структурированной обработки, но может пригодиться при работе с HTML «как есть» или при повторной генерации входных данных с минимальными изменениями (пробелы между атрибутами можно сохранить и т.д.).

SGMLParser.handle_starttag(tag, method, attributes)¶

Этот метод вызывается для обработки открывающих тегов, для которых определён метод start_tag() или do_tag(). Аргумент тег – это имя тега, приведённое к нижнему регистру, а аргумент метод – это привязанный метод, который следует использовать для семантической интерпретации открывающего тега. Аргумент атрибуты – это список пар (name, value), содержащих атрибуты, найденные внутри угловых скобок <> тега.

Имя name переведено в нижний регистр. Двойные кавычки и обратная косая черта в значении value интерпретированы, как и известные символьные ссылки и известные сущностные ссылки, завершающиеся точкой с запятой (обычно сущностные ссылки могут завершаться любым неалфавитно-цифровым символом, но это нарушило бы очень распространённый случай <A HREF="url?spam=1&eggs=2">, когда eggs – это допустимое имя сущности).

Например, для тега <A HREF="http://www.cwi.nl/"> этот метод был бы вызван как unknown_starttag('a', [('href', 'http://www.cwi.nl/')]). Базовая реализация просто вызывает метод с атрибуты в качестве единственного аргумента.

Новое в версии 2.5: Обработка сущностных и символьных ссылок внутри значений атрибутов.

SGMLParser.handle_endtag(tag, method)¶

Этот метод вызывается для обработки закрывающих тегов, для которых определён метод end_tag(). Аргумент тег – это имя тега, приведённое к нижнему регистру, а аргумент метод – это привязанный метод, который следует использовать для семантической интерпретации закрывающего тега. Если для закрывающего элемента не определён метод end_tag(), этот обработчик не вызывается. Базовая реализация просто вызывает метод.

SGMLParser.handle_data(data)¶

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

SGMLParser.handle_charref(ref)¶

Этот метод вызывается для обработки символьной ссылки вида &#ref;. Базовая реализация использует convert_charref() для преобразования ссылки в строку. Если этот метод возвращает строку, она передаётся в handle_data(), в противном случае вызывается unknown_charref(ref) для обработки ошибки.

Изменено в версии 2.5: Используется convert_charref() вместо жёстко заданного преобразования.

SGMLParser.convert_charref(ref)¶

Преобразовать символьную ссылку в строку или None. ref – это ссылка, переданная в виде строки. В базовой реализации ref должно быть десятичным числом в диапазоне 0–255. Кодовая точка преобразуется с помощью метода convert_codepoint(). Если ref недопустима или выходит за пределы диапазона, этот метод возвращает None. Этот метод вызывается реализацией handle_charref() по умолчанию и парсером значений атрибутов.

Новое в версии 2.5.

SGMLParser.convert_codepoint(codepoint)¶

Преобразовать кодовую точку в значение str. При необходимости здесь можно обрабатывать кодировки, хотя остальная часть sgmllib не обращает на это внимания.

Новое в версии 2.5.

SGMLParser.handle_entityref(ref)¶

Этот метод вызывается для обработки общей сущностной ссылки вида &ref;, где ref – это имя общей сущности. Он преобразует ref, передавая его в convert_entityref(). Если перевод возвращён, он вызывает метод handle_data() с этим переводом; в противном случае он вызывает метод unknown_entityref(ref). Метод entitydefs по умолчанию определяет переводы для &, ', >, < и ".

Изменено в версии 2.5: Используется convert_entityref() вместо жёстко заданного преобразования.

SGMLParser.convert_entityref(ref)¶

Преобразовать именованную сущностную ссылку в значение str или None. Результирующее значение не будет разбираться. ref будет содержать только имя сущности. Реализация по умолчанию ищет ref в переменной экземпляра (или класса) entitydefs, которая должна быть отображением имён сущностей в соответствующие переводы. Если перевод для ref не найден, этот метод возвращает None. Этот метод вызывается реализацией handle_entityref() по умолчанию и парсером значений атрибутов.

Новое в версии 2.5.

SGMLParser.handle_comment(comment)¶

Этот метод вызывается, когда встречается комментарий. Аргумент comment – это строка, содержащая текст между разделителями <!-- и -->, но не сами разделители. Например, комментарий <!--text--> приведёт к вызову этого метода с аргументом 'text'. Метод по умолчанию ничего не делает.

SGMLParser.handle_decl(data)¶

Метод, вызываемый, когда парсер читает объявление SGML. На практике в HTML встречается только объявление DOCTYPE, но парсер не различает разные (или некорректные) объявления. Внутренние подмножества в объявлении DOCTYPE не поддерживаются. Параметр data будет содержать всё содержимое объявления внутри разметки <!…>. Реализация по умолчанию ничего не делает.

SGMLParser.report_unbalanced(tag)¶

Этот метод вызывается, когда найден закрывающий тег, который не соответствует ни одному открытому элементу.

SGMLParser.unknown_starttag(tag, attributes)¶

Этот метод вызывается для обработки неизвестного открывающего тега. Он предназначен для переопределения в производном классе; реализация базового класса ничего не делает.

SGMLParser.unknown_endtag(tag)¶

Этот метод вызывается для обработки неизвестного закрывающего тега. Он предназначен для переопределения в производном классе; реализация базового класса ничего не делает.

SGMLParser.unknown_charref(ref)¶

Этот метод вызывается для обработки неразрешимых числовых символьных ссылок. Обратитесь к handle_charref(), чтобы узнать, что обрабатывается по умолчанию. Он предназначен для переопределения в производном классе; реализация базового класса ничего не делает.

SGMLParser.unknown_entityref(ref)¶

Этот метод вызывается для обработки неизвестной ссылки на сущность. Он предназначен для переопределения в производном классе; реализация базового класса ничего не делает.

Помимо переопределения или расширения перечисленных выше методов, производные классы могут также определять методы следующего вида для обработки конкретных тегов. Имена тегов во входном потоке не зависят от регистра; tag, встречающееся в именах методов, должно быть в нижнем регистре:

SGMLParser.start_tag(attributes)

Этот метод вызывается для обработки открывающего тега tag. Он имеет приоритет над do_tag(). Аргумент attributes имеет то же значение, что описано для handle_starttag() выше.

SGMLParser.do_tag(attributes)

Этот метод вызывается для обработки открывающего тега tag, для которого не определён метод start_tag(). Аргумент attributes имеет то же значение, что описано для handle_starttag() выше.

SGMLParser.end_tag()

Этот метод вызывается для обработки закрывающего тега tag.

Обратите внимание, что парсер ведёт стек открытых элементов, для которых ещё не найден закрывающий тег. В этот стек помещаются только теги, обработанные методом start_tag(). Определение метода end_tag() для этих тегов необязательно. Для тегов, обработанных методами do_tag() или unknown_tag(), не должен быть определён метод end_tag(); если он определён, он не будет использоваться. Если для тега существуют оба метода start_tag() и do_tag(), то метод start_tag() имеет приоритет.