sgmllib — Простой парсер SGML

Устарело начиная с версии 2.6: Модуль sgmllib был удалён в Python 3.

Этот модуль определяет класс SGMLParser, который служит основой для разбора текстовых файлов, отформатированных в формате SGML (Стандартный обобщённый язык разметки). Фактически, он не предоставляет полнофункциональный парсер SGML — он анализирует SGML только в той мере, в какой это используется в HTML, и модуль существует только как база для модуля htmllib. Другой парсер HTML, который поддерживает XHTML и предлагает несколько иной интерфейс, доступен в модуле HTMLParser.

class sgmllib.SGMLParser

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

Открывающие и закрывающие теги вида <tag attr="value" ...> и </tag>, соответственно.
Числовые ссылки на символы вида &#name;.
Ссылки на сущности вида &name;.
Комментарии SGML вида . Обратите внимание, что пробелы, табуляции и новые строки разрешены между последующей > и непосредственно предшествующей --.

Также определена одна исключительная ситуация:

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(). Аргумент tag — имя тега, преобразованное в нижний регистр, и аргумент method — связанный метод, который должен использоваться для поддержки семантической интерпретации стартового тега. Аргумент attributes — список пар (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/')]). Базовая реализация просто вызывает method с attributes в качестве единственного аргумента.

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

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

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.

END_OF_DOCUMENT_MARKER

SGMLParser.handle_comment(comment): Этот метод вызывается при обнаружении комментария. Аргумент comment — это строка, содержащая текст между разделителями , но без самих разделителей. Например, комментарий  вызовет вызов этого метода с аргументом 'text'. По умолчанию этот метод ничего не делает.

SGMLParser.handle_decl(data): Метод, вызываемый при чтении объявления SGML парсером. На практике, объявление DOCTYPE является единственным наблюдаемым в HTML, но парсер не различает различные (или некорректные) объявления. Вложенные подмножества в объявлении 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() имеет приоритет.