http.server — HTTP 服务器¶
源代码: Lib/http/server.py
此模块定义了用于实现 HTTP 服务器的类。
警告
不建议在生产环境中使用http.server。它仅实现基本安全检查。
可用性: 不适用于 WASI。
此模块在 WebAssembly 上不起作用或不可用。 有关更多信息，请参阅 WebAssembly 平台。
其中一个类 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)¶
此类通过将服务器地址存储为名为
server_name和server_port的实例变量来构建TCPServer类。 处理程序可以访问服务器，通常通过处理程序的server实例变量。
- class http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)¶
此类与 HTTPServer 相同，但使用线程通过
ThreadingMixIn来处理请求。这对于处理 Web 浏览器预先打开的套接字很有用，在这些套接字上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'。
- 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响应的情况。头部信息不会被缓冲，而是直接发送到输出流。如果未指定message，则会发送与响应code对应的 HTTP 消息。在 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_GET()¶
通过将请求解释为相对于当前工作目录的路径，将请求映射到本地文件。
如果请求映射到一个目录，则会检查该目录中是否存在名为
index.html或index.htm（按此顺序）的文件。如果找到，则返回该文件的内容；否则，通过调用list_directory()方法生成目录列表。此方法使用os.listdir()扫描目录，如果listdir()失败，则返回404错误响应。如果请求被映射到一个文件，则该文件会被打开。任何在打开请求文件时发生的
OSError异常都会被映射为404，'File not found'错误。如果请求中存在'If-Modified-Since'标头，并且文件在此时间后未被修改，则会发送304，'Not Modified'响应。否则，通过调用guess_type()方法来猜测内容类型，该方法会使用 extensions_map 变量，然后返回文件内容。输出一个带有猜测内容类型的
'Content-type:'标头，后跟一个带有文件大小的'Content-Length:'标头和一个带有文件修改时间的'Last-Modified:'标头。接下来是一个空行，表示标头的结束，然后输出文件内容。如果文件的 MIME 类型以
text/开头，则以文本模式打开文件；否则使用二进制模式。有关用法示例，请参阅 Lib/http/server.py 中
test函数的实现。3.7 版本更改: 支持
'If-Modified-Since'标头。
SimpleHTTPRequestHandler 类可以通过以下方式使用，以创建一个非常基本的 Web 服务器，该服务器提供相对于当前目录的文件：
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 来使用不同的索引文件名。
也可以使用解释器的 -m 开关直接调用 http.server。与前面的示例类似，这会提供相对于当前目录的文件：
python -m http.server
默认情况下，服务器侦听 8000 端口。可以通过传递所需的端口号作为参数来覆盖默认值：
python -m http.server 9000
默认情况下，服务器会绑定到所有接口。选项 -b/--bind 指定它应绑定到的特定地址。支持 IPv4 和 IPv6 地址。例如，以下命令使服务器仅绑定到 localhost：
python -m http.server --bind 127.0.0.1
3.4 版本更改: 添加了 --bind 选项。
3.8 版本更改: 在 --bind 选项中支持 IPv6。
默认情况下，服务器使用当前目录。选项 -d/--directory 指定它应提供文件的目录。例如，以下命令使用特定目录：
python -m http.server --directory /tmp/
3.7 版本更改: 添加了 --directory 选项。
默认情况下，服务器符合 HTTP/1.0。选项 -p/--protocol 指定服务器符合的 HTTP 版本。例如，以下命令运行符合 HTTP/1.1 的服务器：
python -m http.server --protocol HTTP/1.1
3.11 版本更改: 添加了 --protocol 选项。
- class http.server.CGIHTTPRequestHandler(request, client_address, server)¶
此类用于提供当前目录及其下方的文件或 CGI 脚本的输出。请注意，HTTP 分层结构到本地目录结构的映射与
SimpleHTTPRequestHandler中的完全相同。注意
CGIHTTPRequestHandler类运行的 CGI 脚本无法执行重定向（HTTP 代码 302），因为代码 200（脚本输出如下）在执行 CGI 脚本之前发送。这会抢占状态码。但是，如果该类猜测它是 CGI 脚本，则会运行 CGI 脚本，而不是将其作为文件提供。仅使用基于目录的 CGI — 其他常见的服务器配置是将特殊扩展名视为表示 CGI 脚本。
如果请求指向
cgi_directories路径下的某个位置，则修改do_GET()和do_HEAD()函数以运行 CGI 脚本并提供输出，而不是提供文件。CGIHTTPRequestHandler定义以下数据成员：- cgi_directories¶
此默认值为
['/cgi-bin', '/htbin']，并描述要视为包含 CGI 脚本的目录。
CGIHTTPRequestHandler定义以下方法：- do_POST()¶
此方法提供
'POST'请求类型，仅允许用于 CGI 脚本。当尝试向非 CGI URL 发送 POST 请求时，会输出错误 501，“只能向 CGI 脚本发送 POST 请求”。
请注意，出于安全原因，CGI 脚本将以用户 nobody 的 UID 运行。CGI 脚本的问题将转换为错误 403。
3.13 版本已弃用，将在 3.15 版本中移除:
CGIHTTPRequestHandler将在 3.15 中移除。CGI 已被认为是不好的处理方式，已经超过十年了。此代码已经有一段时间没有维护，并且很少在实际中使用。保留它可能会导致进一步的 安全考虑。
可以通过传递 --cgi 选项在命令行中启用 CGIHTTPRequestHandler：
python -m http.server --cgi
3.13 版本已弃用，将在 3.15 版本中移除: http.server 命令行 --cgi 支持将被删除，因为 CGIHTTPRequestHandler 将被删除。
警告
CGIHTTPRequestHandler 和 --cgi 命令行选项不适合不受信任的客户端使用，并且可能容易受到利用。始终在安全环境中使用。
安全注意事项¶
在处理请求时，SimpleHTTPRequestHandler 将遵循符号链接，这使得可以提供指定目录之外的文件。
Python 的早期版本不会从 python -m http.server 或默认的 BaseHTTPRequestHandler .log_message 实现发出的 stderr 日志消息中清除控制字符。这可能允许连接到您的服务器的远程客户端将恶意控制代码发送到您的终端。
3.12 版本更改: 在 stderr 日志中清除了控制字符。