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)

Этот класс служит файлами из каталога 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/

По умолчанию сервер соответствует 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 URL.

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

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

python -m http.server --cgi