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

Поток ввода 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

Указывает HTTP-заголовок Content-Type для ответов об ошибках, отправляемых клиенту. Значение по умолчанию — '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

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 указывает конкретный адрес, к которому он должен быть привязан. Например, следующая команда заставляет сервер привязываться только к 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