`cgi.md`

307 строк · 35.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/library/cgi.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`cgi`](https://python-all.ru/3.9/library/cgi.html#module-cgi) – поддержка Common Gateway Interface89**Исходный код:** [Lib/cgi.py](https://python-all.ru/src/3.9/Lib/cgi.py)1011Устарело с версии 3.11: Модуль [`cgi`](https://python-all.ru/3.9/library/cgi.html#module-cgi) устарел (подробнее и альтернативы см. в [**PEP 594**](https://python-all.ru/3.9/library/cgi.html)).1213---1415Вспомогательный модуль для скриптов Common Gateway Interface (CGI).1617Этот модуль определяет ряд утилит для использования CGI-скриптами, написанными на Python.1819## Введение2021CGI-скрипт вызывается HTTP-сервером, обычно для обработки пользовательского ввода, отправленного через элемент HTML `<FORM>` или `<ISINDEX>`.2223Чаще всего CGI-скрипты находятся в специальном каталоге сервера `cgi-bin`. HTTP-сервер помещает различную информацию о запросе (например, имя хоста клиента, запрошенный URL, строку запроса и множество других полезных данных) в окружение оболочки скрипта, выполняет скрипт и отправляет вывод скрипта обратно клиенту.2425Ввод скрипта также подключён к клиенту, и иногда данные формы читаются таким образом; в других случаях данные формы передаются через часть URL «строка запроса». Этот модуль предназначен для обработки различных ситуаций и предоставления более простого интерфейса для Python-скрипта. Он также предоставляет ряд утилит, помогающих при отладке скриптов, и последним дополнением является поддержка загрузки файлов из формы (если браузер это поддерживает).2627Вывод CGI-скрипта должен состоять из двух разделов, разделённых пустой строкой. Первый раздел содержит несколько заголовков, сообщающих клиенту, какие данные следуют. Код Python для генерации минимального раздела заголовков выглядит так:2829```python30print("Content-Type: text/html")    # Далее HTML31print()                             # пустая строка, конец заголовков32```3334Второй раздел обычно представляет собой HTML, что позволяет клиентскому программному обеспечению отображать красиво отформатированный текст с заголовками, встроенными изображениями и т.д. Вот код Python, выводящий простой фрагмент HTML:3536```python37print("<TITLE>CGI script output</TITLE>")38print("<H1>This is my first CGI script</H1>")39print("Hello, world!")40```4142## Использование модуля cgi4344Начать следует с написания `import cgi`.4546При написании нового скрипта стоит добавить следующие строки:4748```python49import cgitb50cgitb.enable()51```5253Это активирует специальный обработчик исключений, который будет выводить подробные отчеты в веб-браузере при возникновении ошибок. Если вы не хотите показывать пользователям вашего скрипта внутренности программы, можно вместо этого сохранять отчеты в файлы с помощью такого кода:5455```python56import cgitb57cgitb.enable(display=0, logdir="/path/to/logdir")58```5960Очень полезно использовать эту возможность при разработке скрипта. Отчёты, создаваемые [`cgitb`](https://python-all.ru/3.9/library/cgitb.html#module-cgitb), предоставляют информацию, которая может сэкономить много времени при поиске ошибок. Строку `cgitb` можно удалить позже, когда скрипт будет протестирован и будет уверенность, что он работает правильно.6162Для доступа к отправленным данным формы используйте класс `FieldStorage`. Если форма содержит символы, не входящие в ASCII, задайте параметр *encoding*, указав кодировку, определённую для документа. Обычно она указывается в теге META в разделе HEAD HTML-документа или в заголовке *Content-Type*. Этот класс читает содержимое формы из стандартного ввода или окружения (в зависимости от значений различных переменных окружения, установленных согласно стандарту CGI). Поскольку он может потреблять стандартный ввод, его следует создавать только один раз.6364Экземпляр `FieldStorage` можно индексировать как словарь Python. Он позволяет проверять наличие ключей оператором [`in`](https://python-all.ru/3.9/reference/expressions.html#in), а также поддерживает стандартный метод словаря [`keys()`](https://python-all.ru/3.9/library/stdtypes.html#dict.keys) и встроенную функцию [`len()`](https://python-all.ru/3.9/library/functions.html#len). Поля формы, содержащие пустые строки, игнорируются и не появляются в словаре; чтобы сохранить такие значения, укажите истинное значение для необязательного именованного параметра *keep\_blank\_values* при создании экземпляра `FieldStorage`.6566Например, следующий код (предполагается, что заголовок *Content-Type* и пустая строка уже выведены) проверяет, что поля `name` и `addr` установлены в непустую строку:6768```python69form = cgi.FieldStorage()70if "name" not in form or "addr" not in form:71    print("<H1>Error</H1>")72    print("Please fill in the name and addr fields.")73    return74print("<p>name:", form["name"].value)75print("<p>addr:", form["addr"].value)76...further form processing here...77```7879Здесь поля, доступные через `form[key]`, сами являются экземплярами `FieldStorage` (или `MiniFieldStorage`, в зависимости от кодировки формы). Атрибут `value` экземпляра даёт строковое значение поля. Метод `getvalue()` возвращает это строковое значение напрямую; он также принимает необязательный второй аргумент – значение по умолчанию, возвращаемое, если запрошенный ключ отсутствует.8081Если отправленные данные формы содержат несколько полей с одинаковым именем, объект, полученный через `form[key]`, будет не экземпляром `FieldStorage` или `MiniFieldStorage`, а списком таких экземпляров. Аналогично в этой ситуации `form.getvalue(key)` вернёт список строк. Если предполагается такая возможность (когда HTML-форма содержит несколько полей с одинаковым именем), используйте метод [`getlist()`](https://python-all.ru/3.9/library/cgi.html#cgi.FieldStorage.getlist), который всегда возвращает список значений (чтобы не требовалось обрабатывать случай одного элемента отдельно). Например, следующий код объединяет любое количество полей с именами пользователей через запятую:8283```python84value = form.getlist("username")85usernames = ",".join(value)86```8788Если поле представляет загруженный файл, чтение значения через атрибут `value` или метод `getvalue()` загружает весь файл в память в виде байтов. Это может быть нежелательно. Можно проверить, является ли поле загруженным файлом, проверив атрибут `filename` или атрибут `file`. Затем можно прочитать данные из атрибута `file` до того, как он будет автоматически закрыт при сборке мусора экземпляра `FieldStorage` (методы [`read()`](https://python-all.ru/3.9/library/io.html#io.RawIOBase.read) и [`readline()`](https://python-all.ru/3.9/library/io.html#io.IOBase.readline) возвращают байты):8990```python91fileitem = form["userfile"]92if fileitem.file:93    # Это загруженный файл; подсчитать строки94    linecount = 095    while True:96        line = fileitem.file.readline()97        if not line: break98        linecount = linecount + 199```100101Объекты `FieldStorage` также поддерживают использование в операторе [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with), который автоматически закроет их по завершении.102103Если при получении содержимого загруженного файла возникает ошибка (например, пользователь прерывает отправку формы, нажав кнопку «Назад» или «Отмена»), атрибут `done` объекта поля будет установлен в значение -1.104105Проект стандарта загрузки файлов предусматривает возможность загрузки нескольких файлов из одного поля (с использованием рекурсивной кодировки *multipart/\**). В этом случае элемент будет представлять собой словареподобный элемент `FieldStorage`. Это можно определить, проверив его атрибут `type`, который должен быть равен *multipart/form-data* (или, возможно, другому MIME-типу, соответствующему *multipart/\**). В этом случае его можно рекурсивно перебирать так же, как объект формы верхнего уровня.106107Когда форма отправляется в «старом» формате (как строка запроса или как одна часть данных типа *application/x-www-form-urlencoded*), элементы на самом деле будут экземплярами класса `MiniFieldStorage`. В этом случае атрибуты `list`, `file` и `filename` всегда равны `None`.108109Форма, отправленная через POST и имеющая также строку запроса, будет содержать элементы как `FieldStorage`, так и `MiniFieldStorage`.110111Изменено в версии 3.4: Атрибут `file` автоматически закрывается при сборке мусора создавшего его экземпляра `FieldStorage`.112113Изменено в версии 3.5: Добавлена поддержка протокола управления контекстом для класса `FieldStorage`.114115## Интерфейс более высокого уровня116117В предыдущем разделе объясняется, как читать данные CGI-формы с помощью класса `FieldStorage`. В этом разделе описывается интерфейс более высокого уровня, который был добавлен в этот класс, чтобы позволить делать это более читабельным и интуитивным способом. Этот интерфейс не делает методы, описанные в предыдущих разделах, устаревшими – они по-прежнему полезны, например, для эффективной обработки загрузки файлов.118119Интерфейс состоит из двух простых методов. С их помощью можно обрабатывать данные формы универсально, не задумываясь о том, было ли отправлено одно или несколько значений под одним именем.120121В предыдущем разделе было показано, как писать следующий код каждый раз, когда ожидается, что пользователь отправит несколько значений под одним именем:122123```python124item = form.getvalue("item")125if isinstance(item, list):126    # Пользователь запрашивает более одного элемента.127else:128    # Пользователь запрашивает только один элемент.129```130131Такая ситуация часто возникает, например, когда форма содержит группу флажков с одинаковым именем:132133```python134<input type="checkbox" name="item" value="1" />135<input type="checkbox" name="item" value="2" />136```137138Однако в большинстве случаев в форме есть только один элемент управления с определённым именем, и тогда ожидается и требуется только одно значение, связанное с этим именем. Поэтому пишется скрипт, содержащий, например, такой код:139140```python141user = form.getvalue("user").upper()142```143144Проблема в том, что не следует рассчитывать, что клиент всегда будет передавать корректные данные в скрипты. Например, если любопытный пользователь добавит ещё одну пару `user=foo` в строку запроса, скрипт аварийно завершится, потому что в этом случае вызов метода `getvalue("user")` вернёт список вместо строки. Вызов метода [`upper()`](https://python-all.ru/3.9/library/stdtypes.html#str.upper) для списка недопустим (поскольку у списков нет метода с таким именем) и приводит к исключению [`AttributeError`](https://python-all.ru/3.9/library/exceptions.html#AttributeError).145146Поэтому единственным правильным способом чтения значений данных формы было всегда использовать код, проверяющий, является ли полученное значение одиночным или списком значений. Это утомительно и снижает читаемость скриптов.147148Более удобный подход – использовать методы [`getfirst()`](https://python-all.ru/3.9/library/cgi.html#cgi.FieldStorage.getfirst) и [`getlist()`](https://python-all.ru/3.9/library/cgi.html#cgi.FieldStorage.getlist), предоставляемые этим интерфейсом более высокого уровня.149150#### `FieldStorage.getfirst(name, default=None)`151152Этот метод всегда возвращает только одно значение, связанное с полем формы *name*. Метод возвращает только первое значение, если под этим именем было отправлено несколько значений. Обратите внимание, что порядок получения значений может различаться в разных браузерах, и полагаться на него не стоит. [1](https://python-all.ru/3.9/library/cgi.html#id3) Если такого поля формы или значения не существует, метод возвращает значение, указанное в необязательном параметре *default*. Этот параметр по умолчанию равен `None`, если не указан.153154#### `FieldStorage.getlist(name)`155156Этот метод всегда возвращает список значений, связанных с полем формы *name*. Метод возвращает пустой список, если для *name* не существует такого поля или значения. Возвращает список из одного элемента, если существует только одно значение.157158С помощью этих методов можно писать компактный код:159160```python161import cgi162form = cgi.FieldStorage()163user = form.getfirst("user", "").upper()    # Так это безопасно.164for item in form.getlist("item"):165    do_something(item)166```167168## Функции169170Они полезны, если нужен более тонкий контроль или если требуется использовать некоторые алгоритмы, реализованные в этом модуле, в других ситуациях.171172#### `cgi.parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False, separator="&")`173174Разбирает запрос из окружения или из файла (по умолчанию файл – `sys.stdin`). Параметры *keep\_blank\_values*, *strict\_parsing* и *separator* передаются в [`urllib.parse.parse_qs()`](https://python-all.ru/3.9/library/urllib.parse.html#urllib.parse.parse_qs) без изменений.175176#### `cgi.parse_multipart(fp, pdict, encoding="utf-8", errors="replace", separator="&")`177178Разбирает ввод типа *multipart/form-data* (для загрузки файлов). Аргументы: *fp* – входной файл, *pdict* – словарь, содержащий другие параметры в заголовке *Content-Type*, и *encoding* – кодировка запроса.179180Возвращает словарь, как и [`urllib.parse.parse_qs()`](https://python-all.ru/3.9/library/urllib.parse.html#urllib.parse.parse_qs): ключи – это имена полей, каждое значение – список значений для этого поля. Для не файловых полей значение – список строк.181182Этот подход прост в использовании, но не очень подходит, если ожидается загрузка мегабайт – в таком случае лучше использовать класс `FieldStorage`, который гораздо гибче.183184Изменено в версии 3.7: Добавлены параметры *encoding* и *errors*. Для не файловых полей значение теперь представляет собой список строк, а не байтов.185186Изменено в версии 3.9.2: Добавлен параметр *separator*.187188#### `cgi.parse_header(string)`189190Разбирает MIME-заголовок (например, *Content-Type*) на основное значение и словарь параметров.191192#### `cgi.test()`193194Надёжный тестовый CGI-скрипт, который можно использовать как основную программу. Выводит минимальные HTTP-заголовки и форматирует всю переданную скрипту информацию в формате HTML.195196#### `cgi.print_environ()`197198Форматирует окружение оболочки в формате HTML.199200#### `cgi.print_form(form)`201202Форматирование формы в HTML.203204#### `cgi.print_directory()`205206Форматирование текущей директории в HTML.207208#### `cgi.print_environ_usage()`209210Вывод в HTML списка полезных переменных окружения (используемых CGI).211212## Забота о безопасности213214Есть одно важное правило: если вы вызываете внешнюю программу (через [`os.system()`](https://python-all.ru/3.9/library/os.html#os.system), [`os.popen()`](https://python-all.ru/3.9/library/os.html#os.popen) или другие функции с аналогичной функциональностью), убедитесь, что не передаете оболочке произвольные строки, полученные от клиента. Это хорошо известная уязвимость, с помощью которой умелые хакеры из любой точки Интернета могут использовать доверчивый CGI-скрипт для выполнения произвольных команд оболочки. Даже части URL или имена полей не заслуживают доверия, поскольку запрос может прийти не из вашей формы!215216Чтобы быть в безопасности, если вам всё же нужно передать строку из формы команде оболочки, стоит убедиться, что строка содержит только буквенно-цифровые символы, дефисы, символы подчёркивания и точки.217218## Установка CGI-скрипта в системе Unix219220Прочтите документацию вашего HTTP-сервера и уточните у местного системного администратора директорию, куда следует устанавливать CGI-скрипты; обычно это директория `cgi-bin` в дереве сервера.221222Убедитесь, что скрипт доступен для чтения и выполнения «другими»; файловая маска Unix должна быть `0o755` в восьмеричном виде (используйте `chmod 0755 filename`). Проверьте, что первая строка скрипта содержит `#!` начиная с первой позиции, за которым следует путь к интерпретатору Python, например:223224```python225#!/usr/local/bin/python226```227228Убедитесь, что интерпретатор Python существует и доступен для выполнения «другими».229230Убедитесь, что любые файлы, которые скрипт должен читать или писать, доступны для чтения или записи «другим» – их права должны быть `0o644` для чтения и `0o666` для записи. Это связано с тем, что из соображений безопасности HTTP-сервер выполняет скрипт от имени пользователя «nobody», без каких-либо особых привилегий. Он может только читать (писать, выполнять) файлы, которые доступны всем на чтение (запись, выполнение). Текущая директория во время выполнения тоже отличается (обычно это каталог cgi-bin сервера), и набор переменных окружения отличается от того, что получается при входе в систему. В частности, не рассчитывайте, что путь поиска исполняемых файлов оболочки (`PATH`) или путь поиска модулей Python ([`PYTHONPATH`](https://python-all.ru/3.9/using/cmdline.html#envvar-PYTHONPATH)) будут установлены во что-то содержательное.231232Если вам нужно загружать модули из директории, которой нет в пути поиска модулей Python по умолчанию, можно изменить путь в скрипте перед импортом других модулей. Например:233234```python235import sys236sys.path.insert(0, "/usr/home/joe/lib/python")237sys.path.insert(0, "/usr/local/lib/python")238```239240(Так директория, вставленная последней, будет просматриваться первой!)241242Инструкции для систем, отличных от Unix, различаются; ознакомьтесь с документацией вашего HTTP-сервера (обычно в ней есть раздел о CGI-скриптах).243244## Тестирование CGI-скрипта245246К сожалению, CGI-скрипт обычно не работает при запуске из командной строки, а скрипт, отлично работающий в командной строке, может таинственно отказываться при запуске через сервер. Но есть одна причина, по которой всё же стоит тестировать скрипт из командной строки: если в нём есть синтаксическая ошибка, интерпретатор Python вообще не выполнит его, и HTTP-сервер, скорее всего, отправит клиенту малопонятную ошибку.247248Если в скрипте нет синтаксических ошибок, но он всё равно не работает, ничего не остаётся, кроме как прочитать следующий раздел.249250## Отладка CGI-скриптов251252Прежде всего, проверьте наличие тривиальных ошибок установки – внимательное чтение раздела об установке CGI-скрипта выше может сэкономить много времени. Если вы сомневаетесь, правильно ли поняли процедуру установки, попробуйте установить копию этого файла модуля (`cgi.py`) в качестве CGI-скрипта. При вызове как скрипта этот файл выведет своё окружение и содержимое формы в формате HTML. Задайте правильные права и т.д., а затем отправьте ему запрос. Если он установлен в стандартную директорию `cgi-bin`, должно быть возможно отправить запрос, введя в браузере URL следующего вида:253254```text255http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home256```257258Если это даёт ошибку типа 404, сервер не может найти скрипт – возможно, нужно установить его в другую директорию. Если возникает другая ошибка, значит есть проблема с установкой, которую нужно исправить, прежде чем продолжать. Если вы получаете аккуратно отформатированный список окружения и содержимого формы (в этом примере поля должны отображаться как «addr» со значением «At Home» и «name» со значением «Joe Blow»), значит скрипт `cgi.py` установлен правильно. Если повторить ту же процедуру для вашего собственного скрипта, теперь вы сможете его отлаживать.259260Следующим шагом может быть вызов функции [`test()`](https://python-all.ru/3.9/library/test.html#module-test) модуля [`cgi`](https://python-all.ru/3.9/library/cgi.html#module-cgi) из вашего скрипта: замените его основной код единственным оператором261262```python263cgi.test()264```265266Это должно дать те же результаты, что и при установке самого файла `cgi.py`.267268Когда обычный скрипт Python вызывает необработанное исключение (по любой причине: опечатка в имени модуля, файл, который не удаётся открыть, и т.п.), интерпретатор Python печатает подробную трассировку и завершает работу. Хотя интерпретатор Python всё ещё делает это, когда ваш CGI-скрипт вызывает исключение, скорее всего, трассировка попадёт в один из журнальных файлов HTTP-сервера или вообще будет отброшена.269270К счастью, если вам удалось заставить ваш скрипт выполнить *какой-либо* код, вы можете легко отправлять трассировки в веб-браузер с помощью модуля [`cgitb`](https://python-all.ru/3.9/library/cgitb.html#module-cgitb). Если вы еще этого не сделали, просто добавьте строки:271272```python273import cgitb274cgitb.enable()275```276277в начало скрипта. Затем попробуйте запустить его снова; при возникновении проблемы вы увидите подробный отчёт, который, вероятно, укажет на причину сбоя.278279Если вы подозреваете, что может быть проблема с импортом модуля [`cgitb`](https://python-all.ru/3.9/library/cgitb.html#module-cgitb), можно использовать ещё более надёжный подход (использующий только встроенные модули):280281```python282import sys283sys.stderr = sys.stdout284print("Content-Type: text/plain")285print()286...your code here...287```288289Этот подход полагается на интерпретатор Python для печати трассировки. Тип содержимого вывода устанавливается в обычный текст, что отключает всю обработку HTML. Если ваш скрипт работает, сырой HTML будет отображён клиентом. Если он вызывает исключение, скорее всего, после вывода первых двух строк будет показана трассировка. Поскольку интерпретация HTML не происходит, трассировка будет читаемой.290291## Частые проблемы и их решения292293- Большинство HTTP-серверов буферизуют вывод CGI-скриптов до завершения скрипта. Это означает, что невозможно отображать индикатор выполнения на экране клиента во время работы скрипта.294- Проверьте инструкции по установке выше.295- Проверьте файлы журнала HTTP-сервера. (`tail -f logfile` в отдельном окне может оказаться полезным!)296- Всегда сначала проверяйте скрипт на синтаксические ошибки, выполнив что-то вроде `python script.py`.297- Если в скрипте нет синтаксических ошибок, попробуйте добавить `import cgitb; cgitb.enable()` в начало скрипта.298- При вызове внешних программ убедитесь, что они могут быть найдены. Обычно это означает использование абсолютных путей – `PATH` обычно не содержит полезного значения в CGI-скрипте.299- При чтении или записи внешних файлов убедитесь, что они могут быть прочитаны или записаны идентификатором пользователя (userid), от имени которого будет выполняться CGI-скрипт: обычно это идентификатор пользователя, под которым работает веб-сервер, или явно указанный идентификатор для функции `suexec` веб-сервера.300- Не пытайтесь установить CGI-скрипту режим set-uid. На большинстве систем это не работает и к тому же создаёт угрозу безопасности.301302Сноски303304**[1](https://python-all.ru/3.9/library/cgi.html#id2)**305306Обратите внимание, что некоторые последние версии спецификации HTML действительно определяют порядок, в котором должны передаваться значения полей, но определение того, был ли запрос получен от соответствующего спецификации браузера, или вообще от браузера, – задача утомительная и чреватая ошибками.307