http.server — HTTP серверы

Исходный код: Lib/http/server.py

В этом модуле определены классы для реализации HTTP-серверов (веб-серверов).

Один класс, HTTPServer, является подклассом socketserver.TCPServer. Он создаёт и прослушивает HTTP-сокет, перенаправляя запросы обработчику. Код для создания и запуска сервера выглядит так:

def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()

class http.server.HTTPServer(server_address, RequestHandlerClass)

Этот класс основан на классе TCPServer, храня адреса сервера в переменных экземпляра, именованных server_name и server_port. Сервер доступен обработчику, обычно через переменную экземпляра обработчика server.

class http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)

Этот класс идентичен HTTPServer, но использует потоки для обработки запросов с помощью ThreadingMixIn. Это полезно для обработки случаев, когда веб-браузеры предварительно открывают сокеты, на которых HTTPServer мог бы ждать неопределённо долго.

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

Классы HTTPServer и ThreadingHTTPServer должны быть снабжены классом RequestHandlerClass при создании экземпляра, из которых этот модуль предоставляет три различные варианты:

class http.server.BaseHTTPRequestHandler(request, client_address, server)

Этот класс используется для обработки HTTP-запросов, поступающих на сервер. Сам по себе он не может отвечать на реальные HTTP-запросы; он должен быть расширен, чтобы обрабатывать каждый метод запроса (например, GET или POST). BaseHTTPRequestHandler предоставляет ряд переменных класса и экземпляра, а также методы для использования подклассами.

Обработчик проанализирует запрос и заголовки, а затем вызовет метод, специфичный для типа запроса. Имя метода формируется из запроса. Например, для метода запроса SPAM, будет вызван метод do_SPAM() без аргументов. Вся релевантная информация хранится в переменных экземпляра обработчика. Подклассам не нужно переопределять или расширять метод __init__().

BaseHTTPRequestHandler имеет следующие переменные экземпляра:

client_address

Содержит кортеж вида (host, port), относящийся к адресу клиента.

server

Содержит экземпляр сервера.

close_connection

Логический флаг, который должен быть установлен перед тем, как handle_one_request() вернёт значение, указывающее, ожидается ли другой запрос или соединение должно быть закрыто.

requestline

Содержит строковое представление строки HTTP-запроса. Заключительный CRLF удаляется. Это свойство должно быть установлено методом handle_one_request(). Если не был обработан допустимый запрос, то значение должно быть пустой строкой.

command

Содержит команду (тип запроса). Например, 'GET'.

path

Содержит путь запроса. Если в URL присутствует компонент запроса, то path включает запрос. Используя терминологию RFC 3986, path здесь включает hier-part и query.

request_version

Содержит строку версии из запроса. Например, 'HTTP/1.0'.

headers

Содержит экземпляр класса, указанного переменной класса MessageClass. Этот экземпляр анализирует и управляет заголовками в HTTP-запросе. Функция parse_headers() из http.client используется для анализа заголовков и требует, чтобы HTTP-запрос предоставлял допустимый заголовок в стиле RFC 2822.

rfile

Поток ввода io.BufferedIOBase, готовый для чтения с начала необязательных данных ввода.

wfile

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

Изменено в версии 3.6: Это поток io.BufferedIOBase.

BaseHTTPRequestHandler имеет следующие атрибуты:

server_version

Указывает версию программного обеспечения сервера. Вы можете переопределить её. Формат — несколько разделенных пробелами строк, где каждая строка имеет вид name[/version]. Например, 'BaseHTTP/0.2'.

sys_version

Содержит версию системы Python в формате, используемом методом version_string и переменной класса server_version. Например, 'Python/1.4'.

error_message_format

Указывает строку формата, которая должна использоваться методом send_error() для построения ответа об ошибке для клиента. Строка по умолчанию заполняется переменными из responses на основе кода состояния, переданного методу send_error().

error_content_type

Указывает заголовок Content-Type HTTP для ответов об ошибках, отправляемых клиенту. Значение по умолчанию — 'text/html'.

protocol_version

Указывает версию HTTP-протокола, используемую в ответах. Если установлено значение 'HTTP/1.1', сервер позволит HTTP-постоянные соединения; однако, ваш сервер обязательно должен включать точный заголовок Content-Length (с помощью send_header()) во всех ответах клиентам. Для обратной совместимости значение по умолчанию — 'HTTP/1.0'.

MessageClass

Указывает класс, похожий на email.message.Message для анализа заголовков HTTP. Обычно это не переопределяется, и по умолчанию оно равно http.client.HTTPMessage.

responses

Этот атрибут содержит отображение целых чисел кодов ошибок на кортежи из двух элементов, содержащих короткое и длинное сообщение. Например, {code: (shortmessage, longmessage)}. shortmessage обычно используется в качестве ключа message в ответе об ошибке, а longmessage — как ключ explain. Используется методами send_response_only() и send_error().

У экземпляра BaseHTTPRequestHandler есть следующие методы:

handle()

Вызывает handle_one_request() один раз (или, если включены постоянные соединения, несколько раз) для обработки входящих HTTP-запросов. Вам никогда не нужно его переопределять; вместо этого реализуйте соответствующие методы do_*().

handle_one_request()

Этот метод анализирует и отправляет запрос соответствующему методу do_*(). Вам никогда не нужно его переопределять.

handle_expect_100()

Когда HTTP/1.1-совместимый сервер получает заголовок запроса Expect: 100-continue, он отвечает с 100 Continue и последующими заголовками 200 OK . Этот метод можно переопределить, чтобы вызывать ошибку, если сервер не хочет, чтобы клиент продолжал. Например, сервер может выбрать отправку 417 Expectation Failed в качестве заголовка ответа и return False.

Добавлено в версии 3.2.

send_error(code, message=None, explain=None)

Отправляет и записывает в журнал полный ответ об ошибке клиенту. Численное значение code указывает код HTTP-ошибки, а message — необязательное короткое удобочитаемое описание ошибки. Аргумент explain может быть использован для предоставления более подробной информации об ошибке; он будет отформатирован с использованием атрибута error_message_format и выведен после полного набора заголовков в качестве тела ответа. Атрибут responses содержит значения по умолчанию для message и explain, которые будут использованы, если значения не указаны; для неизвестных кодов значение по умолчанию для обоих — строка ???. Тело будет пустым, если метод — HEAD или код ответа — один из следующих: 1xx, 204 No Content, 205 Reset Content, 304 Not Modified.

Изменено в версии 3.4: Ответ об ошибке включает заголовок Content-Length. Добавлен аргумент explain.

send_response(code, message=None)

Добавляет заголовок ответа в буфер заголовков и записывает в журнал принятый запрос. Строка HTTP-ответа записывается во внутренний буфер, за ней следуют заголовки Server и Date. Значения этих двух заголовков берутся из методов version_string() и date_time_string() соответственно. Если сервер не намерен отправлять другие заголовки с помощью метода send_header(), то за вызовом send_response() должен следовать вызов end_headers().

Изменено в версии 3.3: Заголовки хранятся во внутреннем буфере, и необходимо явно вызвать end_headers().

send_header(keyword, value)

Добавляет HTTP-заголовок во внутренний буфер, который будет записан в поток вывода при вызове end_headers() или flush_headers(). keyword должен указывать ключевое слово заголовка, а value — его значение. Обратите внимание, что после выполнения вызовов send_header необходимо ВЫЗВАТЬ end_headers() для завершения операции.

Изменено в версии 3.2: Заголовки хранятся во внутреннем буфере.

send_response_only(code, message=None)

Отправляет только заголовок ответа, используется в случаях, когда сервер отправляет клиенту ответ 100 Continue. Заголовки не буферизуются и отправляются непосредственно в поток вывода.

Добавлен в версии 3.2.

end_headers()

Добавляет пустую строку (указывающую конец HTTP-заголовков в ответе) в буфер заголовков и вызывает flush_headers().

Изменено в версии 3.2: Буферизованные заголовки записываются в поток вывода.

flush_headers()

Наконец, отправляет заголовки в поток вывода и очищает внутренний буфер заголовков.

Добавлен в версии 3.3.

log_request(code='-', size='-')

Записывает в журнал принятый (успешный) запрос. code должен указывать числовой HTTP-код, связанный с ответом. Если размер ответа доступен, то он должен быть передан как параметр size.

log_error(...)

Записывает в журнал ошибку, когда запрос не может быть выполнен. По умолчанию он передает сообщение в log_message(), поэтому принимает те же аргументы (format и дополнительные значения).

log_message(format, ...)

Записывает произвольное сообщение в sys.stderr. Обычно это переопределяется для создания собственных механизмов ведения журнала ошибок. Аргумент format — стандартная строка формата в стиле printf, где дополнительные аргументы к log_message() применяются как входные данные для форматирования. К каждому записанному сообщению добавляются IP-адрес клиента и текущая дата и время.

version_string()

Возвращает строку версии программного обеспечения сервера. Это сочетание атрибутов server_version и sys_version.

date_time_string(timestamp=None)

Возвращает дату и время, заданные timestamp (который должен быть None или в формате, возвращаемом time.time()), отформатированном для заголовка сообщения. Если timestamp опущен, используется текущая дата и время.

Результат выглядит так: 'Sun, 06 Nov 1994 08:49:37 GMT'.

log_date_time_string()

Возвращает текущую дату и время, отформатированную для ведения журнала.

address_string()

Возвращает адрес клиента.

Изменено в версии 3.3: Ранее выполнялся поиск имени. Для избежания задержек при разрешении имен теперь всегда возвращается IP-адрес.

class http.server.SimpleHTTPRequestHandler(request, client_address, server, directory=None)

Этот класс обслуживает файлы из текущей директории и ниже, напрямую сопоставляя структуру директорий с HTTP-запросами.

Большая часть работы, например, разбор запроса, выполняется базовым классом BaseHTTPRequestHandler. Этот класс реализует функции do_GET() и do_HEAD().

Следующие значения определены как атрибуты класса SimpleHTTPRequestHandler:

server_version

Это будет "SimpleHTTP/" + __version__, где __version__ определено на уровне модуля.

extensions_map

Словарь, сопоставляющий суффиксы с типами MIME. По умолчанию пустая строка, и считается application/octet-stream. Сопоставление выполняется без учета регистра, поэтому в нем должны быть только ключи в нижнем регистре.

directory

Если не указано, то директория для обслуживания — это текущая рабочая директория.

Класс SimpleHTTPRequestHandler определяет следующие методы:

do_HEAD()

Этот метод обслуживает запрос типа 'HEAD': он отправляет заголовки, которые он отправил бы для эквивалентного запроса GET. Смотрите метод do_GET() для более полного объяснения возможных заголовков.

do_GET()

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

Если запрос был сопоставлен с директорией, проверяется наличие файла с именем index.html или index.htm (в указанном порядке). Если найден, содержимое файла возвращается; в противном случае генерируется список директорий путем вызова метода list_directory(). Этот метод использует os.listdir() для сканирования директории и возвращает ответ с ошибкой 404, если listdir() завершился ошибкой.

Если запрос был сопоставлен с файлом, он открывается. Любая исключительная ситуация OSError при открытии запрошенного файла отображается как ошибка 404, 'File not found'. Если в запросе был заголовок 'If-Modified-Since', и файл не изменялся после этого времени, отправляется ответ 304, 'Not Modified'. В противном случае тип содержимого определяется путем вызова метода guess_type(), который, в свою очередь, использует переменную extensions_map, и содержимое файла возвращается.

Выводится заголовок 'Content-type:' с определённым типом содержимого, за которым следует заголовок 'Content-Length:' с размером файла и заголовок 'Last-Modified:' с временем изменения файла.

За этим следует пустая строка, обозначающая конец заголовков, а затем выводится содержимое файла. Если MIME-тип файла начинается с text/, файл открывается в текстовом режиме; в противном случае используется двоичный режим.

Пример использования см. в вызове функции test() в модуле http.server.

Изменено в версии 3.7: Поддержка заголовка 'If-Modified-Since'.

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

import http.server
import socketserver

PORT = 8000

Handler = http.server.SimpleHTTPRequestHandler

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print("serving at port", PORT)
    httpd.serve_forever()

http.server также можно вызвать напрямую, используя переключатель -m интерпретатора с аргументом port number. Аналогично предыдущему примеру, это обслуживает файлы относительно текущей директории:

python -m http.server 8000

По умолчанию сервер связывается со всеми интерфейсами. Опция -b/--bind задаёт конкретный адрес, к которому он должен подключиться. Поддерживаются как IPv4, так и IPv6 адреса. Например, следующая команда заставляет сервер связываться только с localhost:

python -m http.server 8000 --bind 127.0.0.1

По умолчанию сервер использует текущую директорию. Опция -d/--directory задаёт директорию, из которой он должен обслуживать файлы. Например, следующая команда использует определённую директорию:

python -m http.server --directory /tmp/

class http.server.CGIHTTPRequestHandler(request, client_address, server)

Этот класс используется для обслуживания файлов или вывода CGI-скриптов из текущей директории и ниже. Обратите внимание, что сопоставление иерархии HTTP с локальной структурой директорий точно такое же, как и в SimpleHTTPRequestHandler.

Примечание

CGI-скрипты, выполняемые классом CGIHTTPRequestHandler, не могут выполнять перенаправления (HTTP-код 302), потому что код 200 (выход скрипта следует) отправляется до выполнения CGI-скрипта. Это предвосхищает код статуса.

Однако, класс выполнит CGI-скрипт вместо обслуживания файла, если он определит его как CGI-скрипт. Используются только CGI на основе директорий — другая распространённая конфигурация сервера — обрабатывать специальные расширения как указывающие на CGI-скрипты.

Функции do_GET() и do_HEAD() изменены для выполнения CGI-скриптов и обслуживания вывода вместо обслуживания файлов, если запрос ведёт к пути ниже cgi_directories.

Класс CGIHTTPRequestHandler определяет следующие данные члена:

cgi_directories

По умолчанию это ['/cgi-bin', '/htbin'] и описывает директории, которые следует рассматривать как содержащие CGI-скрипты.

Класс CGIHTTPRequestHandler определяет следующие методы:

do_POST()

Этот метод обслуживает запрос типа 'POST', разрешенный только для CGI-скриптов. Ошибка 501, «Можно выполнять POST только для CGI-скриптов», выводится при попытке POST к не-CGI URL.

Обратите внимание, что CGI-скрипты будут выполняться с UID пользователя nobody по соображениям безопасности. Проблемы с CGI-скриптом будут переведены в ошибку 403.

CGIHTTPRequestHandler можно включить в командной строке, передав опцию --cgi:

python -m http.server --cgi 8000