`http.server` --- HTTP サーバー¶

このモジュールは HTTP サーバを実装するためのクラスを提供しています。

警告

http.server は本番環境での利用には推奨しません。基本的なセキュリティチェックだけを実装しています。

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォームを見てください。

クラス HTTPServer は socketserver.TCPServer のサブクラスです。 HTTPServer は HTTP ソケットを生成してリクエスト待ち (listen) を行い、リクエストをハンドラに渡します。サーバを作成して動作させるためのコードは以下のようになります:

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 インスタンス変数を通じてサーバーにアクセスできます。

server_name¶: HTTP サーバーの完全修飾ドメイン名。

server_port¶: server_address から取得した HTTP サーバーのポート番号。

class http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)¶: このクラスは HTTPServer と同じですが、ThreadingMixIn を使い、スレッドでリクエストを処理します。ウェブブラウザーがあらかじめ開いたソケットに対応するのに便利です。このようなソケットでは HTTPServer は無期限に待機してしまいます。

Added in version 3.7.

class http.server.HTTPSServer(server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)¶

ssl モジュールでソケットをラップした HTTPServer のサブクラスです。 ssl モジュールが利用できない場合、HTTPSServer オブジェクトのインスタンス化は RuntimeError で失敗します。

certfile 引数は SSL 証明書チェーンファイルのパス、keyfile は秘密鍵を含むファイルのパスです。

PKCS#8 で保護しラップしたファイルには password を指定できますが、コードに埋め込んだパスワードが平文で露出する可能性がある点に注意してください。

参考

certfile、keyfile、password に指定できる値については、ssl.SSLContext.load_cert_chain() を参照してください。

alpn_protocols 引数を指定する場合、サーバーがサポートする「Application-Layer Protocol Negotiation」(ALPN) のプロトコルを表す文字列のシーケンスでなければなりません。 ALPN を使うと、TLS ハンドシェイク中にサーバーとクライアントがアプリケーションプロトコルをネゴシエートできます。

デフォルトは ["http/1.1"] で、サーバーが HTTP/1.1 をサポートすることを意味します。

Added in version 3.14.

class http.server.ThreadingHTTPSServer(server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)¶: このクラスは HTTPSServer と同じですが、ThreadingMixIn を継承し、スレッドでリクエストを処理します。 ThreadingHTTPServer に相当するクラスで、HTTPSServer を使う点だけが異なります。

Added in version 3.14.

The HTTPServer, ThreadingHTTPServer, HTTPSServer and ThreadingHTTPSServer must be given a RequestHandlerClass on instantiation, of which this module provides three different variants:

class http.server.BaseHTTPRequestHandler(request, client_address, server)¶

このクラスは、サーバーに届いた HTTP リクエストを処理するために使います。このクラス単独では実際の HTTP リクエストに応答できません。サブクラスを作り、各リクエストメソッド ('GET' や 'POST' など) を処理する必要があります。 BaseHTTPRequestHandler は、サブクラスが利用するためのさまざまなクラス変数、インスタンス変数、メソッドを提供します。

ハンドラーはリクエストとヘッダーを解析してから、リクエストの種類に対応するメソッドを呼び出します。メソッド名はリクエストから組み立てます。例えば、リクエストメソッドが SPAM なら、do_SPAM() メソッドを引数なしで呼び出します。関連する情報はすべてハンドラーのインスタンス変数に格納されます。サブクラスで __init__() メソッドをオーバーライドしたり拡張したりする必要はないはずです。

BaseHTTPRequestHandler は以下のインスタンス変数を持っています:

client_address¶: HTTP クライアントのアドレスを参照している、(host, port) の形式をとるタプルが入っています。

server¶: server インスタンスが入っています。

close_connection¶: handle_one_request() が返る前に設定すべき真偽値で、別のリクエストが期待されているかどうか、もしくはコネクションを切断すべきかどうかを指し示しています。

requestline¶: HTTP リクエスト行の文字列表現を保持しています。末尾の CRLF は除去されています。この属性は handle_one_request() によって設定されるべきです。妥当なリクエスト行が1行も処理されなかった場合は、空文字列に設定されるべきです。

command¶: HTTP 命令 (リクエスト形式) が入っています。例えば 'GET' です。

path¶: リクエストのパスを保持します。 URL にクエリー部分がある場合、path にはクエリーも含まれます。 RFC 3986 の用語では、ここでの path には hier-part と query が含まれます。

request_version¶: リクエストのバージョン文字列が入っています。例えば 'HTTP/1.0' です。

headers¶: MessageClass クラス変数で指定したクラスのインスタンスを保持します。このインスタンスは、HTTP リクエストのヘッダーを解析し管理します。解析には http.client の parse_headers() 関数を使うため、HTTP リクエストは有効な RFC 5322 形式のヘッダーを提供する必要があります。

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() メソッドがクライアントへのエラーレスポンスを組み立てる際に使う書式文字列を指定します。デフォルトでは、send_error() に渡したステータスコードに応じて responses から得た値を文字列に埋め込みます。

error_content_type¶: エラーレスポンスをクライアントに送信する時に使う Content-Type HTTP ヘッダを指定します。デフォルトでは 'text/html' です。

protocol_version¶: サーバーが準拠する HTTP バージョンを指定します。この値はレスポンスで送信され、後続のリクエストで使えるサーバーの通信機能をクライアントに知らせます。 'HTTP/1.1' にすると HTTP の持続的接続を許可しますが、その場合はクライアントへのすべてのレスポンスに、 (send_header() を使って) 正確な Content-Length ヘッダーを含める 必要があります。後方互換性のため、デフォルトは 'HTTP/1.0' です。

MessageClass¶: HTTP ヘッダを解釈するための email.message.Message 類似のクラスを指定します。通常この値が上書きされることはなく、デフォルトの http.client.HTTPMessage になっています。

responses¶: この属性は、整数のエラーコードから、短いメッセージと長いメッセージを含む 2 要素タプルへのマッピングを保持します。例えば {code: (shortmessage, longmessage)} です。通常、shortmessage はエラーレスポンスの message キー、longmessage は explain キーとして使います。 send_response_only() メソッドと send_error() メソッドがこの属性を使います。

BaseHTTPRequestHandler インスタンスは以下のメソッドを持っています:

handle()¶: handle_one_request() を 1 回 (持続的接続が有効な場合は複数回) 呼び出し、届いた HTTP リクエストを処理します。このメソッドをオーバーライドする必要はないはずです。代わりに、適切な do_*() メソッドを実装してください。

handle_one_request()¶: このメソッドは、リクエストを解析して適切な do_*() メソッドに振り分けます。このメソッドをオーバーライドする必要はないはずです。

handle_expect_100()¶: HTTP/1.1 に準拠するサーバーが Expect: 100-continue リクエストヘッダーを受信すると、100 Continue に続けて 200 OK ヘッダーを返します。サーバーがクライアントに処理を続けさせたくない場合、このメソッドをオーバーライドしてエラーを返せます。例えば、レスポンスヘッダーとして 417 Expectation Failed を送信し、return False を実行できます。

Added in version 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() を呼び出してください。

このメソッドは、CRLF シーケンスを含む入力を拒否しません。

バージョン 3.2 で変更: ヘッダは内部バッファに保存されます。

send_response_only(code, message=None)¶

Sends the response header only, used for the purposes when 100 Continue response is sent by the server to the client. The headers are not buffered and sent directly the output stream. If the message is not specified, the HTTP message corresponding the response code is sent.

このメソッドは、CRLF シーケンスを含む message を拒否しません。

Added in version 3.2.

end_headers()¶: ヘッダーバッファーに空行 (レスポンスの HTTP ヘッダーの終わりを示す行) を追加し、flush_headers() を呼び出します。

バージョン 3.2 で変更: バッファされたヘッダは出力ストリームに書き出されます。

flush_headers()¶: 最終的にヘッダを出力ストリームに送り、内部ヘッダバッファをフラッシュします。

Added in version 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, extra_response_headers=None)¶

このクラスは、ディレクトリ構造を HTTP リクエストに直接対応付け、directory とその下位ディレクトリにあるファイルを配信します。 directory を省略すると、現在のディレクトリを使います。

バージョン 3.7 で変更: directory 引数を追加しました。

バージョン 3.9 で変更: directory 引数が path-like object を受け付けるようになりました。

バージョン 3.15 で変更: extra_response_headers 引数を追加しました。

リクエストの解釈のような、多くの作業は基底クラス BaseHTTPRequestHandler で行われます。このクラスは関数 do_GET() および do_HEAD() を実装しています。

SimpleHTTPRequestHandler では以下のメンバ変数を定義しています:

server_version¶: この値は "SimpleHTTP/" + __version__ になります。__version__ はこのモジュールで定義されている値です。

default_content_type¶: リクエストされた URL のファイル拡張子から MIME 型を推測できない場合に送信する、Content-Type ヘッダーの値を指定します。デフォルトは 'application/octet-stream' です。

Added in version 3.15.

index_pages¶

ディレクトリのインデックスページとして扱うファイル名を指定します。

デフォルトは ("index.html", "index.htm") です。

Added in version 3.12.

extensions_map¶: 拡張子から MIME 型へのマッピングで、システムのデフォルトのマッピングを上書きする独自の設定を保持する辞書です。大文字と小文字を区別せずに使うため、キーには小文字だけを含めてください。

バージョン 3.9 で変更: この辞書にシステムのデフォルトのマッピングを格納しなくなり、上書きする設定だけを含むようになりました。

extra_response_headers¶

HTTP ステータス 200 の成功レスポンスごとに追加する、利用者定義の HTTP レスポンスヘッダーを含む (name, value) ペアのシーケンスです。これらのヘッダーは、他のステータスコードのレスポンスには含めません。

Content-Type などのサーバーが自動で送信するヘッダーは、extra_response_headers では上書きされません。

SimpleHTTPRequestHandler では以下のメソッドを定義しています:

do_HEAD()¶: このメソッドは 'HEAD' 型のリクエスト処理を実行します: すなわち、 GET リクエストの時に送信されるものと同じヘッダを送信します。送信される可能性のあるヘッダについての完全な説明は do_GET() メソッドを参照してください。

do_GET()¶

リクエストを現在の作業ディレクトリからの相対的なパスとして解釈することで、リクエストをローカルシステム上のファイルと対応付けます。

リクエストがディレクトリに対応する場合、index_pages で指定されたインデックスページがあるか調べます。見つかればそのファイルの内容を返し、なければ list_directory() メソッドを呼び出してディレクトリ一覧を生成します。このメソッドは os.listdir() でディレクトリを調べ、listdir() が失敗した場合は 404 エラーレスポンスを返します。

リクエストがファイルに対応する場合、そのファイルを開きます。ファイルを開く際に発生した OSError 例外は、404、'File not found' エラーに対応付けます。リクエストに 'If-Modified-Since' ヘッダーがあり、ファイルがその日時より後に変更されていなければ、304、'Not Modified' レスポンスを送信します。そうでなければ、extensions_map 変数を使う guess_type() メソッドを呼び出してコンテントタイプを推測し、ファイルの内容を返します。

出力は 'Content-type:' と推測されたコンテントタイプで、その後にファイルサイズを示す 'Content-Length:' ヘッダと、ファイルの更新日時を示す 'Last-Modified:' ヘッダが続きます。

インスタンス属性 extra_response_headers は、利用者定義の追加のレスポンスヘッダーを含む (name, value) ペアのシーケンスです。

続いてヘッダーの終わりを示す空行を出力し、その後にファイルの内容を出力します。

使用例は Lib/http/server.py の test 関数の実装を参照してください。

バージョン 3.7 で変更: 'If-Modified-Since' ヘッダーをサポートしました。

list_directory(path)¶

インデックスページがない場合に、path の内容を一覧表示するためのヘルパーです。

file-like object (呼び出し側が閉じる必要があります) を返すか、エラーを示す None を返します。後者の場合、呼び出し側がそれ以上行うことはありません。どちらの場合もヘッダーを送信します。

guess_type(path)¶

指定された path にあるファイルの型を推測します。

MIME の Content-type ヘッダーに使える type/subtype 形式の文字列を返します。

デフォルトの実装は extensions_map でファイルの拡張子を調べ、見つからなければ mimetypes.guess_file_type()、さらに default_content_type の順に試します。

バージョン 3.13 で変更: フォールバックとして mimetypes.guess_file_type() を追加しました。

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 [OPTIONS] [port]

以下のオプションが使用できます:

port¶

サーバーはデフォルトでポート 8000 で待ち受けます。使いたいポート番号を引数として渡すと変更できます。

python -m http.server 9000

-b, --bind <address>¶

バインド先のアドレスを指定します。 IPv4 と IPv6 の両方に対応しています。デフォルトでは、サーバーはすべてのインターフェースにバインドします。例えば、次のコマンドでは localhost だけにバインドします。

python -m http.server --bind 127.0.0.1

Added in version 3.4.

バージョン 3.8 で変更: --bind オプションで IPv6 をサポートしました。

-d, --directory <dir>¶

ファイルを配信するディレクトリを指定します。デフォルトでは現在のディレクトリを使います。例えば、次のコマンドでは特定のディレクトリを使います。

python -m http.server --directory /tmp/

Added in version 3.7.

-p, --protocol <version>¶

サーバーが準拠する HTTP バージョンを指定します。デフォルトでは HTTP/1.0 に準拠します。例えば、次のコマンドでは HTTP/1.1 に準拠するサーバーを実行します。

python -m http.server --protocol HTTP/1.1

Added in version 3.11.

--content-type <content_type>¶

URL のファイル拡張子から MIME 型を推測できない場合に使う、デフォルトの Content-Type HTTP ヘッダーを指定します。デフォルトでは 'application/octet-stream' を使います。

python -m http.server --content-type text/html

Added in version 3.15.

--tls-cert¶

HTTPS 接続に使う TLS 証明書チェーンを指定します。

python -m http.server --tls-cert fullchain.pem

Added in version 3.14.

--tls-key¶

HTTPS 接続に使う秘密鍵ファイルを指定します。

このオプションには --tls-cert の指定が必要です。

Added in version 3.14.

--tls-password-file¶

パスワードで保護された秘密鍵のパスワードファイルを指定します。

python -m http.server \
       --tls-cert cert.pem \
       --tls-key key.pem \
       --tls-password-file password.txt

このオプションには --tls-cert の指定が必要です。

Added in version 3.14.

-H, --header <header> <value>¶: HTTP 200 の成功レスポンスで送信する追加の HTTP レスポンスヘッダーを指定します。複数回指定して、独自のレスポンスヘッダーを追加できます。 Content-Type などサーバーが自動で送信するヘッダーは上書きされません。

Added in version 3.15.

セキュリティで考慮すべき点¶

SimpleHTTPRequestHandler はリクエストの処理時にシンボリックリンクをたどるため、指定したディレクトリの外にあるファイルを配信できてしまいます。

BaseHTTPRequestHandler.send_header() メソッドと BaseHTTPRequestHandler.send_response_only() メソッドは、入力が安全な形に処理されていると想定し、CRLF シーケンスの有無の確認などの入力検証を行いません。信頼できない入力により、HTTP ヘッダーインジェクション攻撃を受ける可能性があります。

以前の Python では、python -m http.server や BaseHTTPRequestHandler のデフォルトの .log_message 実装が stderr に出力するログメッセージから、制御文字を除去していませんでした。そのため、サーバーに接続したリモートクライアントが、悪意のある制御コードを端末に送信できる可能性がありました。

バージョン 3.12 で変更: stderr のログから制御文字を除去するようになりました。

`http.server` --- HTTP サーバー¶

コマンドライン・インターフェース¶

セキュリティで考慮すべき点¶

目次

前のトピックへ

次のトピックへ

このページ

http.server --- HTTP サーバー¶

コマンドライン・インターフェース¶

セキュリティで考慮すべき点¶

`http.server` --- HTTP サーバー¶