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

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-скрипты будут запускаться с идентификатором пользователя nobody по соображениям безопасности. Проблемы со скриптом CGI будут переведены в ошибку 403.

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

python -m http.server --cgi