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

Указывает версию программного обеспечения сервера. Вы можете это переопределить. Формат — это несколько разделенных пробелами строк, где каждая строка имеет вид имя[/версия]. Например, '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() применяются в качестве входных данных для форматирования. К каждому записанному сообщению добавляются адрес 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)

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

Введено в версии 3.7: Параметр directory.

Изменено в версии 3.9: Параметр directory принимает объект, похожий на путь.

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

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

server_version

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

extensions_map

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

Изменено в версии 3.9: Этот словарь больше не заполняется стандартными системными соответствиями, а содержит только переопределения.

Класс 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 в Lib/http/server.py.

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

python -m http.server

Сервер прослушивает порт 8000 по умолчанию. Умолчание можно изменить, передав желаемый номер порта в качестве аргумента:

python -m http.server 9000

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

python -m http.server --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