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

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

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

Добавлена в версии 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)

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

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

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

server_version

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

extensions_map

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

directory

Если не указано, то директория для обслуживания — текущая рабочая директория.

Класс 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() в модуле http.server.

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

python -m http.server 8000

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

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