Комментарии Python в стиле HTML

Содержание

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

Каждый, кто когда-нибудь пытался запускать скачанные из Интернета в виде html-страниц сценарии Python, знает, сколько усилий порой приходится прилагать, чтобы восстановить правильное оформление кода Python.

С другой стороны, классически оформленные программы в виде кода с простыми текстовыми комментариями слишком аскетичны. Где возможности для выделения текста курсивом, изменения размера шрифта, где гиперссылки, таблицы, формулы и иллюстрации? Встроенные в текст программы текстовые комментарии более приспособлены для компилятора/интерпретатора, чем для человека-программиста. И требования к идеальной программе в наши дни должны включать в себя не только структурированность, кроссплатформенность, открытость кода и т.п., но и легкость восприятия кода. Особенно это касается образцовых, учебных программ.

В свое время для решения этой задачи была разработана особая концепция "литературного программирования" (вольный перевод оригинального термина "literate programming" - методология программирования и документирования, согласно которой код должен писаться таким образом, чтобы он был понятен людям, читающим его; разработана Дональдом Кнутом в 1981 году при создании системы компьютерной верстки TeX). В ней для облегчения понимания программного кода человеком вводилась система макросов, создаваемая из фраз на человеческом языке, которые становились своего рода "метаязыком" над конкретным языком программирования.

К сожалению, на практике применение этой красивой идеи столкнулось с рядом проблем.

Дополнительное оформление текста требует больших затрат времени и сил. Нужно искать компромисс между красотой оформления кода и быстротой программирования.

Использование метаязыка, каким бы интуитивно простым он ни был, означает, что нужно изучить еще один язык (или псевдо-язык) программирования. (То же относится и к облегченным языкам разметки, таким как Markdown, Textile и т.п.) Кроме того, он становится дополнительным посредником между человеком и кодом. И того, и другого мне хотелось бы избежать.

Кажется, именно по этим причинам литературное программирование и не получило широкого распространения в программистской практике.

На наш взгляд, для понимания кода такого языка программирования как Python язык-посредник не нужен. Python и так достаточно прост. Также вполне легко читается написанная вручную html-разметка. Совмещение в рамках одного файла двух языков - Python для программного кода и HTML для комментариев - выглядит разумной и простой альтернативой литературному программированию.

Конечно, для большинства программ простые текстовые комментарии - это оптимальный вариант. Но есть ниши, в которых дополнительное оформление программного кода может быть оправданным. Речь идет, скажем, о программах с серьезным математическим и/или научным содержанием.

Предлагаются три простых инструмента для работы с файлами, в которых код Python совмещен с разметкой HTML:

• Процедура html2py() - это простой конвертер, способный преобразовывать html-страницы, содержащие код Python, в сценарии Python с расширением .py и запускать их на выполнение. Все, что не находится между тегами <CODE> и </CODE>, превращается в комментарии Python. А между этими тегами как раз и находятся "кусочки" кода Python. В целом они представляют собой законченную программу на Python, ее можно редактировать с использованием подсветки синтаксиса и сохранять в обычном редакторе, например в IDLE.
• Возможно и обратное преобразование: другая процедура py2html() убирает все добавленные комментарии, восстанавливая оформление исходного html-файла.
• Наконец, процедура html2code() выступает в роли фильтра, удаляющего все, что не находится между тегами <CODE> и </CODE>, и преобразующего html-страницы в "чистые" (без тегов html и объяснительного текста) сценарии Python.

Естественно, такие html-файлы должны быть оформлены по соответствующим правилам:

• кодировка html-файла - только UTF-8; первая строка программы: # -*- coding: UTF-8 -*- (с этой строкой не все так просто, см. пояснения к коду процедур html2py() и py2html() )
• в одном html-файле может содержаться только одна программа (целиком)
• текст программы должен быть правильно оформлен с соблюдением всех отступов, переносов строк и т.п.
• код программы должен быть заключен между тегами <CODE>…</CODE> (или <code>…</code>; чтобы браузер отображал переносы строк, лучше употребить конструкцию <PRE><CODE>…</CODE></PRE>)
• конвертер компонует программу из последовательно идущих друг за другом блоков, заключенных между тегами <CODE>…</CODE>
• при "закомментировании" html-разметки используется комбинация символов "##", превращающая всю оставшуюся справа часть строки в комментарий; следовательно: за тегами <PRE><CODE> на той же строке не должно быть кода Python, его следует размещать на следующей строке; и, наоборот, теги </CODE></PRE> можно размещать на одной строке с кодом Python
• если в текстовых комментариях внутри сценария Python встречаются сочетания символов: <!, <?, </, <br />, угловые скобки нужно заменять символическими описаниями (&lt; и &gt;); в противном случае сценарий Python будет сконвертирован корректно, но при отображении в браузере исходного html-файла эти сочетания будут трактоваться как комментарии и часть информации показана не будет
• если в тексте описания встречается выражение <CODE> либо </CODE>, угловые скобки нужно заменять символическими описаниями (&lt; и &gt;)
• если сочетания символов: <CODE> и </CODE> встречаются в самом коде Python и угловые скобки в них не могут быть заменены на символические описания (&lt; и &gt;), следует воспользоваться модулем code_tag, как это сделано в процедурах html2py(), py2html() и html2code()

html2py('',0,0)

холостой запуск: скрипт Python не создается, и код не запускается на выполнение

html2py('',0,1)

сценарий Python не создается, но код запускается на выполнение

html2py('',1,0)

генерируется скрипт Python, но код на выполнение не запускается

html2py('',1,1)

сценарий Python создается и запускается на выполнение

С другой стороны, процедура html2py может вызываться из других сценариев Python. В последнем случае имя html-файла с кодом задается через первый параметр этой процедуры.

Третий вариант - импортирование модуля, оформленного в виде html-файла. Тогда перед командой import имя_модуля в сценарии, использующем такой модуль, нужно вызвать процедуру с параметрами: html2py('имя_модуля',1,0).

Недостатки и сфера применения

• Повышается трудоемкость составления программы: оформление сверх обычных текстовых комментариев требует дополнительных усилий и затрат времени.

• Введение дополнительного оформления кода зачастую ухудшает, а не улучшает восприятие кода программы, даже при просмотре в браузере. Особенно это касается такого языка как Python, важной чертой которого является использование отступов.

• Одновременное использование двух языков программирования (HTML и Python) при написании кода не хорошо по эстетическим и стилистическим соображениям.

• Выбранный подход исключает подсветку синтаксиса Python в браузере.

• Не получается сразу писать сценарий в виде html-файла. Приходится разбивать работу на два этапа: сначала писать сценарий Python с обычными текстовыми комментариями, а потом на его основе составлять оформление html-файла.

  Делу могли бы помочь визуальные html-редакторы (WYSIWYG), но они, к сожалению, вносят свои изменения в html-код, что для меня неприемлемо. Попытка "с лету" приспособить под визуальное редактирование html-кода старый питоновский веб-браузер Grail не удалась. Программа очень сложная и внесение в нее дополнений требует от программиста много времени и высокой квалификации.

• При оформлении html-комментариев следует отказаться от принятой практики писать комментарий к отдельным строкам кода. Вместо этого лучше комментировать целые блоки кода (как абзацы в обычном тексте). В противном случае код Python в html-файле становится просто не читаемым. В результате получается как бы двуязычный текст: один и тот же абзац излагается сначала на обычном языке, а потом - на Python.

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

Очевидно, что простейший алгоритм, заложенный в процедуру html2code.py (которая удаляет все комментарии), может быть применен при небольшой доработке к программам практически на любом языке программирования.

Автор: Филипп Занько
Web-адрес: http://www.russianlutheran.org/python/python.html
Лицензия: Creative Commons Attribution-ShareAlike 3.0 Unported License