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.

Класс HTTPServer должен быть снабжен 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

Содержит путь запроса.

request_version

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

headers

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

rfile

Содержит поток ввода, размещённый в начале необязательных входных данных.

wfile

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

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

server_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. Заголовки не буферизуются и отправляются непосредственно в поток вывода. Если message не указан, то отправляется HTTP-сообщение, соответствующее коду code.

Добавлена в версии 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() применяются в качестве входных данных для форматирования. К каждому зарегистрированному сообщению добавляются адрес клиента и текущее время и дата.

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)

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

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

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

server_version

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

extensions_map

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

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

do_HEAD()

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

do_GET()

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

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

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

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

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

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

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

import http.server
import socketserver

PORT = 8000

Handler = http.server.SimpleHTTPRequestHandler

httpd = socketserver.TCPServer(("", PORT), Handler)

print("serving at port", PORT)
httpd.serve_forever()

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

python -m http.server 8000

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

python -m http.server 8000 --bind 127.0.0.1

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