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

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

Также можно наследовать от SimpleHTTPRequestHandler для улучшения поведения, например, используя разные имена файлов индексов, переопределив атрибут класса index_pages.

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/

По умолчанию сервер соответствует HTTP/1.0. Опция -p/--protocol указывает версию HTTP, с которой сервер соответствует. Например, следующая команда запускает сервер, соответствующий HTTP/1.1:

python -m http.server --protocol HTTP/1.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-адрес.

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

Устарело начиная с версии 3.13, будет удалено в версии 3.15: CGIHTTPRequestHandler удаляется в версии 3.15. CGI уже не считается хорошим способом работы уже более десятилетия. Этот код некоторое время не поддерживался и имеет очень небольшое практическое применение. Сохранение его может привести к дальнейшим учитываниям безопасности.

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

python -m http.server --cgi