`wsgiref` --- WSGI 工具與參考實作¶

網頁伺服器閘道介面 (WSGI) 是一個標準介面，用於連接網頁伺服器軟體與使用 Python 撰寫的網頁應用程式，擁有一個標準介面使得支援 WSGI 的應用程式可以與多個不同的網頁伺服器運行。

只有網頁伺服器與程式框架的作者需要瞭解 WSGI 設計的每個細節與邊角案例，你並不需要為了安裝 WSGI 應用程式或是使用現有框架撰寫網頁應用程式而必須理解每個細節。

wsgiref 是 WSGI 規格的參考實作，可用於新增 WSGI 來支援網頁伺服器或框架，它提供操作 WSGI 環境變數以及回應標頭的工具，用於實作 WSGI 伺服器的基本類別，提供用於示範 HTTP 伺服器的 WSGI 應用程式、靜態型別檢查、以及驗證 WSGI 伺服器與應用程式是否符合 WSGI 規格的驗證工具 (PEP 3333)。

參閱 wsgi.readthedocs.io 更多 WSGI 相關資訊，以及教學連結與其他資源。

`wsgiref.util` -- WSGI 環境工具¶

這個模組提供許多用於處理 WSGI 環境運作的功能。WSGI 環境是一個包含 HTTP 請求變數的字典，如 PEP 3333 所述。所有接受 environ 的參數的函式都需要提供符合 WSGI 標準的字典；請參閱 PEP 3333 獲取詳細規格，以及 WSGIEnvironment 獲取可用於使用型別註釋的型別別名。

wsgiref.util.guess_scheme(environ)¶

透過檢查 environ 字典中的 HTTPS 環境變數，回傳 wsgi.url_scheme 應該是 "http" 或 "https" 的猜測。回傳值為一個字串。

當建立一個包裝 CGI 或類似 FastCGI 的 CGI-like 協議閘道時，此函式非常有用。例如 FastCGI，通常提供這類協議的伺服器在通過 SSL 接收到請求時會包含 "1"，"yes"，或 "on" 的 HTTPS 變數，因此，如果找到這樣的值，此函式回傳 "https"，否則回傳 "http"。

wsgiref.util.request_uri(environ, include_query=True)¶: 根據 PEP 3333 中 "URL Reconstruction" 章節所找到的演算法，回傳完整的請求 URI，可選擇性的包含查詢字串，如果 include_query 設為 false，查詢字串不會被包含在結果的 URI 中。

wsgiref.util.application_uri(environ)¶: 類似於 request_uri()，但忽略 PATH_INFO 和 QUERY_STRING 變數。結果是請求地址的應用程式物件的的基本 URI。

wsgiref.util.shift_path_info(environ)¶

將單一名稱從 PATH_INFO 移到 SCRIPT_NAME 並回傳該名稱。environ 字典會在適當時機被 modified；如果你需要保留原始完好無損的 PATH_INFO 或 SCRIPT_NAME 請使用副本。

如果在 PATH_INFO 中沒有剩餘的路徑片段，則回傳 None。

通常，此程式用於處理請求 URI 的每一部分路徑，例如將路徑視為一系列的字典鍵此程式會修改傳入的環境，使其適用於呼叫位於目標 URI 的 WSGI 應用程式。例如，如果在 /foo 上有一個 WSGI 應用程式且請求 URI 路徑為 /foo/bar/baz，並且位於 /foo 的 WSGI 應用程式呼叫 shift_path_info()，它將接收字串 "bar"，而環境將被更新為適用於傳遞給位於 /foo/bar 的 WSGI 應用程式。換句話說，SCRIPT_NAME 將從 /foo 變更為 /foo/bar，而 PATH_INFO 將從 /bar/baz 變更為 /baz。

當 PATH_INFO 只是一個 "/" 時，此程式會回傳一個空字串，並在 SCRIPT_NAME 後添加尾部斜號，即使空路徑片段通常是被忽略的，而且 SCRIPT_NAME 通常不會以斜號結尾。這是刻意行為，以確保應用程式在使用這個程式進行物件遍歷時可以區分結尾為 /x 和結尾為 /x/ 的 URIs。

wsgiref.util.setup_testing_defaults(environ)¶

為測試目的，以簡單的預設值更新 environ 。

這個程式新增 WSGI 所需的各種參數，包括 HTTP_HOST、SERVER_NAME、SERVER_PORT、REQUEST_METHOD、SCRIPT_NAME、PATH_INFO，以及所有 PEP 3333 定義的 wsgi.* 變數，它只提供預設值，並且不會取代現有的這些變數設定。

這個程式目的為了讓 WSGI 伺服器和應用程式的單元測試更容易建置虛擬環境。實際的 WSGI 伺服器或應用程式不應該使用它，因為所產生的數據是假的！

用法範例：

from wsgiref.util import setup_testing_defaults
from wsgiref.simple_server import make_server

# A relatively simple WSGI application. It's going to print out the
# environment dictionary after being updated by setup_testing_defaults
def simple_app(environ, start_response):
    setup_testing_defaults(environ)

    status = '200 OK'
    headers = [('Content-type', 'text/plain; charset=utf-8')]

    start_response(status, headers)

    ret = [("%s: %s\n" % (key, value)).encode("utf-8")
           for key, value in environ.items()]
    return ret

with make_server('', 8000, simple_app) as httpd:
    print("Serving on port 8000...")
    httpd.serve_forever()

除了上述的環境功能外，wsgiref.util 模組還提供以下各類工具：

wsgiref.util.is_hop_by_hop(header_name)¶: 如果 'header_name' 是根據 RFC 2616 所定義的 HTTP/1.1 "Hop-by-Hop" 標頭，則回傳 True。

class wsgiref.util.FileWrapper(filelike, blksize=8192)¶

wsgiref.types.FileWrapper 協議的具體實作，用於將類檔案物件轉換為 iterator。產生的物件是 iterable。當物件進行疊代時，將可選的 blksize 引數重複傳遞給 filelike 物件的 read() 方法來獲得將產生（yield）的位元組字串。當 read() 回傳一個空位元組字串，代表疊代已結束且無法回復。

如果 filelike 有 close() 方法，則回傳的物件也會具有 close() 方法，並在呼叫時呼叫 filelike 物件的 close() 方法。

用法範例：

from io import StringIO
from wsgiref.util import FileWrapper

# We're using a StringIO-buffer for as the file-like object
filelike = StringIO("This is an example file-like object"*10)
wrapper = FileWrapper(filelike, blksize=5)

for chunk in wrapper:
    print(chunk)

在 3.11 版的變更: 已移除對 __getitem__() 方法的支援。

`wsgiref.headers` -- WSGI 回應標頭工具¶

這個模組提供單一類別 Headers，用於使用類似對映的介面方便地操作 WSGI 回應標頭。

class wsgiref.headers.Headers([headers])¶

建立一個類似對映物件並包裝 headers，並且必須是符合 PEP 3333 描述的 name/value 元組的標頭串列。headers 的預設值是一個空串列。

Headers 物件支援典型對映操作包括 __getitem__()、get()、__setitem__()、setdefault()、__delitem__() 以及 __contains__()。對於這些方法中的每一個，鍵是標頭名稱（以不區分大小寫方式處理），而值則是與該標頭名稱關聯的第一個值。設定標頭會刪除該標頭的所有現有值，然後將新值添加到包裝的標頭串列末尾。標頭的現有順序通常保持不變，新標頭會添加到包裝串列的末尾。

不同於字典，當你嘗試取得或刪除包裝的標頭串列不存在的鍵，Headers 物件不會引發例外錯誤。取得不存在的標頭只會回傳 None，而刪除不存在的標頭則不會有任何效果。

Headers 物件還支援 keys()、value()、和 items() 方法。由 keys() 和 items() 回傳的串列在存在多值標頭時可能會包含相同的鍵。Headers 物件的 len() 與 items() 的長度相同，也與包裝標頭串列的長度相同。實際上，items() 方法只是回傳包裝的標頭串列的副本。

對 Header 物件呼叫 bytes() 會回傳適合作為 HTTP 傳輸回應標頭的格式化的位元組字串。每個標頭都與其值一起置於一行上，由冒號與空格分隔。每行以回車（carriage return）和換行（line feed）結束，而該位元組字串則以空行結束。

除了對映介面和格式化功能外，Headers 物件還具有以下查詢及附加多值標頭的以及附加 MIME 參數標頭的方法：

get_all(name)¶

回傳指定標頭的所有值的串列。

回傳的串列按照它們在在原始的標頭串列出現的順序或是被添加到此實例的順序進行排序，並且可能包含重複的內容。任何被刪除並重新插入的欄位都會被添加到標頭串列的末尾。如果不存在指定名稱的欄位，則回傳空串列。

add_header(name, value, **_params)¶

添加一個（可能是多值的）標頭，可通過關鍵字引數來指定選擇性的 MIME 參數。

name 是要添加的標頭欄位。關鍵字引數可使於設定標頭欄位的 MIME 參數。每一個參數必須是字串或是 None。由於破折號在 Python 識別符中是非法的，但是許多 MIME 參數名稱包含破折號，因此參數名稱的底線會轉換成破折號。如果參數值是字串，則以 name="value" 的形式添加到標頭值參數中。如果它是 None，則僅添加參數名稱。（這使用於沒有值的 MIME 參數）使用範例：

h.add_header('content-disposition', 'attachment', filename='bud.gif')

上述操作將添加看起來像這樣的標頭：

Content-Disposition: attachment; filename="bud.gif"

在 3.5 版的變更: headers 參數是可選的。

`wsgiref.simple_server` -- 一個簡單的 WSGI HTTP 伺服器¶

這個模組實作一個簡單的的 HTTP 伺服器（基於 http.server）用於提供 WSGI 應用程式。每個伺服器執行個體在特定的主機與埠提供單一的 WSGI 應用程式。如果你想要在單一主機與埠上提供多個應用程式，你應該建立一個 WSGI 應用程式以剖析 PATH_INFO 去選擇為每個請求呼叫哪個應用程式。（例如，使用來自 wsgiref.util 的 shift_path_info() 函式。）

wsgiref.simple_server.make_server(host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler)¶

建立一個新的 WSGI 伺服器監聽 host 和 port，接受 app 的連線。回傳值是提供 server_class 的實例，並將使用指定的 handler_class 處理請求。app 必須是一個 WSGI 應用程式物件，如 PEP 3333 所定義。

用法範例：

from wsgiref.simple_server import make_server, demo_app

with make_server('', 8000, demo_app) as httpd:
    print("Serving HTTP on port 8000...")

    # Respond to requests until process is killed
    httpd.serve_forever()

    # Alternative: serve one request, then exit
    httpd.handle_request()

wsgiref.simple_server.demo_app(environ, start_response)¶: 這個函式是一個簡單但完整的 WSGI 應用程式，它回傳一個包含訊息 "Hello world!" 和在 environ 參數中提供的鍵值對串列的文字頁面。這對於驗證 WSGI 伺服器（例如 wsgiref.simple_server）是否能正確執行簡單的 WSGI 應用程式非常有用。

class wsgiref.simple_server.WSGIServer(server_address, RequestHandlerClass)¶

建立一個 WSGIServer 實例。server_address 應該是一個 (host, port) 元組，而 RequestHandlerClass 應該是 http.server.BaseHTTPRequestHandler 的子類別，將用於處理請求。

通常你不需要呼叫這個建構函式（constructor），因為 make_server() 函式可以為你處理所有細節。

WSGIServer 是 http.server.HTTPServer 的子類別，因此它的所有方法（例如 serve_forever() 和 handle_request()）都可用。WSGIServer 也提供這些特定於 WSGI 的方法：

set_app(application)¶: 將可呼叫的 application 設定為接收請求的 WSGI 應用程式。

get_app()¶: 回傳目前設定應用程式的可呼叫物件。

然而，通常情況下你不需要去使用這些額外方法，因為 set_app() 通常會被 make_server() 呼叫而 get_app() 主要存在於請求處理程式（handler）實例的好處上。

class wsgiref.simple_server.WSGIRequestHandler(request, client_address, server)¶

為給定的 request*（即一個 socket）、*client_address*（一個 ``(host,port)`` 位元組）、*server (WSGIServer 實例) 建立一個 HTTP 處理程式（handler）。

你不需要直接建立這個類別的實例；它們會在需要時由 WSGIServer 物件自動建立。不過，你可以建立這個類別的子類別並將其作為 handler_class 提供給 make_server() 函式。一些可能相關的方法可以在子類別中進行覆寫：

get_environ()¶: 唯一個請求回傳一個 WSGIEnvironment 字典。預設的實作會複製 WSGIServer 物件的 base_environ 字典屬性的內容以及添加從 HTTP 請求中衍生的各種標頭。每次呼叫這個方法都應該回傳一個包含所有如 PEP 3333 所指定的相關 CGI 環境變數的新字典。

get_stderr()¶: 回傳的物件應該被用作 wsgi.errors 串流。預設實作只會回傳 sys.stderr。

handle()¶: 處理 HTTP 請求。預設實作會使用 wsgiref.handler 類別來建立處置程式（handler）實例來實作實際 WSGI 應用程式介面。

`wsgiref.validate` --- WSGI 符合性檢查¶

當建立新的 WSGI 應用程式物件、框架、伺服器、或是中介軟體（middleware）時，使用 wsgiref.validate 來驗證新程式碼的符合性可能會很有用。這個模組提供一個函式用於建立 WSGI 應用程式物件，並用於驗證 WSGI 伺服器或是閘道與 WSGI 應用程式物件之間的通訊，以檢查雙方協議的符合性。

請注意這個工具並不保證完全符合 PEP 3333；這個模組中的錯誤不一定代表不存在錯誤。但是，如果如果這個模組產生錯誤，那麼幾乎可以確定伺服器或應用程式不是 100% 符合標準。

這個模組基於 Ian Bicking 的 "Python Paste" 函式庫的 paste.lint 模組。

wsgiref.validate.validator(application)¶

包裝 application 並回傳一個新的 WSGI 應用程式物件。回傳的應用程式將轉發所有請求給原始的 application，並檢查 application 和呼叫它的伺服器是否符合 WSGI 規範和 RFC 2616。

任何在 AssertionError 中偵測不符合結果都會發起例外；但請注意，如何處理這些錯誤取決於伺服器。例如，基於 wsgiref.handlers 的 wsgiref.simple_server 以及其他伺服器（未覆蓋錯誤處理方法以執行其他操作的伺服器）將僅輸出一條錯誤訊息，指示發生錯誤，並將回溯訊息輸出到 sys.stderr 或是其他錯誤串流。

這個包裝器也可以使用 warnings 模組生成輸出去指示一些可能有疑慮但實際上可能不會被 PEP 3333 禁止的行為。除非使用 Python 命令列選項或 warnings API，抑制了這些警告，否則這類警告將被寫入到 sys.stderr（not wsgi.errors，除非它們碰巧是相同的物件）。

用法範例：

from wsgiref.validate import validator
from wsgiref.simple_server import make_server

# Our callable object which is intentionally not compliant to the
# standard, so the validator is going to break
def simple_app(environ, start_response):
    status = '200 OK'  # HTTP Status
    headers = [('Content-type', 'text/plain')]  # HTTP Headers
    start_response(status, headers)

    # This is going to break because we need to return a list, and
    # the validator is going to inform us
    return b"Hello World"

# This is the application wrapped in a validator
validator_app = validator(simple_app)

with make_server('', 8000, validator_app) as httpd:
    print("Listening on port 8000....")
    httpd.serve_forever()

`wsgiref.handlers` -- 伺服器 / 閘道基本類別¶

這個模組提供實作 WSGI 伺服器和閘道的基礎處理程式（handler）類別。這些基底類別處理程式大部分與 WSGI 應用程式通訊的工作，只要它們被提供 CGI-like 環境，以及輸入、輸出和錯誤串流。

class wsgiref.handlers.CGIHandler¶

這是基於 CGI 的呼叫方式並透過 sys.stdin、sys.stdout、sys.stderr 和 os.environ。當你擁有一個 WSGI 應用程式並希望將其作為 CGI 腳本運行時是很有用的。只需呼叫 CGIHandler().run(app)，其中 app 是你希望呼叫的 WSGI 應用程式物件。

這個類別是 BaseCGIHandler 的子類別將 wsgi.run_once 設置為 true，wsgi.multithread 設置為 false，並將 wsgi.multiprocess 設置為 true，並且始終使用 sys 和 os 來獲取所需的 CGI 串流以及環境。

class wsgiref.handlers.IISCGIHandler¶

這是用於在 Microsoft 的 IIS 網頁伺服器上部署時使用的 CGIHandler 的一個專門替代選擇，無需設置 config 的 allowPathInfo 選項（IIS>=7），或 metabase 的 allowPathInfoForScriptMappings 選項（IIS<7）。

預設情況下，IIS 提供的 PATH_INFO 會在前面複製 SCRIPT_NAME，對於希望實作路由的 WSGI 應用程式造成問題。這個處理程式（handler）會移除任何這樣的重複路徑。

IIS 可以配置去傳遞正確的 PATH_INFO，但這會導致 PATH_TRANSLATED 是錯誤的問題。幸運的是這個變數很少被使用並且不受 WSGI 保證。然而，在 IIS<7 上，這個設置只能在虛擬主機層級進行，影響所有其他腳本的對映，其中許多在暴露 PATH_TRANSLATED 問題時會中斷。由於這個原因幾乎從不會使用修復的 IIS<7（即使是 IIS7 也很少使用它，因為它仍然沒有相應的 UI）。

CGI 程式碼無法知道是否已設置該選項，因此提供了一個獨立的處理程式（handler）類別。它的使用方式與 CGIHandler 相同，即透過呼叫 IISCGIHandler().run(app) 來使用，其中 app 是你希望呼叫的 WSGI 應用程式物件。

在 3.2 版被加入.

class wsgiref.handlers.BaseCGIHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)¶

類似於 CGIHandler，但不是使用 sys 和 os 模組，而是明確指定 CGI 環境與 I/O 串流。multithread 和 multiprocess 值用於設置由處理程式（handler）實例運行的任何應用程式的旗標。

這個類別是專門為除了 HTTP "origin servers" 以外的軟體一起使用的 SimpleHandler 的子類別。如果你正在撰寫一個使用 Status: 標頭來發送 HTTP 狀態的閘道協議實作（例如 CGI、FastCGI、SCGI 等），你可能會想要子類化這個類別來替代 SimpleHandler。

class wsgiref.handlers.SimpleHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)¶

類似於 BaseCGIHandler，但是被設計使用在 HTTP origin 伺服器。如果你正在撰寫 HTTP 伺服器的實作，你可能會想要子類別化這個類別來替代 BaseCGIHandler。

這個類別是 BaseHandler 的子類別。它透過建構器去覆寫 __init__()、get_stdin()、get_stderr()、add_cgi_vars()、_write()、和 _flush() 方法來明確提供設置環境與串流。提供的環境與串流被儲存在 stdin、stdout、stderr、和 environ 環境中。

stdout 的 write() 方法應該完整地寫入每個塊（chunk），像是 io.BufferedIOBase。

class wsgiref.handlers.BaseHandler¶

這是一個運行 WSGI 應用程式的抽象基底類別。每個實例將處理單個 HTTP 請求，儘管原則上你可以建立一個可重用於多個請求的子類別。

BaseHandler 實例只有一個供外部使用的方法：

run(app)¶: 運行指定 WSGI 應用程式，app。

此方法在運行應用程式的過程中呼叫了所有其他 BaseHandler 的方法，因此這些方法主要存在是為了允許自定義整個過程。

以下方法必須在子類別中覆寫：

_write(data)¶: 緩衝要傳送給用戶端的位元組 data。如果這個方法實際上傳送了數據也是可以的；當底層系統實際具有這種區分時，BaseHandler 為了更好的效能進而分離寫入和刷新操作。

_flush()¶: 強制將緩衝數據傳送到用戶端。如果這是一個無操作（no-op）的方法（即，如果 _write() 實際上發送了數據），那麼是可以的。

get_stdin()¶: 回傳一個與 InputStream 相容的物件並適用於用作當前正在處理請求的 wsgi.input。

get_stderr()¶: 回傳一個與 ErrorStream 相容的物件並適用於用作當前正在處理請求的 wsgi.errors。

add_cgi_vars()¶: 將當前請求的 CGI 變數插入到 environ 屬性中。

以下是你可能希望覆寫的其他方法和屬性。這個列表只是一個摘要，然而，不包括可以被覆寫的每個方法。在嘗試建立自定義的 BaseHandler 子類別之前，你應該參考文件說明和原始碼以獲得更多資訊。

用於自定義 WSGI 環境的屬性和方法：

wsgi_multithread¶: 用於 wsgi.multithread 環境變數的值。在 BaseHandler 中預設為 true，但在其他子類別中可能有不同的預設值（或由建構函式設置）。

wsgi_multiprocess¶: 用於 wsgi.multiprocess 環境變數的值。在 BaseHandler 中預設為 true，但在其他子類別中可能有不同的預設值（或由建構函式設置）。

wsgi_run_once¶: 用於 wsgi.run_once 環境變數的值。在 BaseHandler 中預設為 false，但 CGIHandler 預設將其設置為 true。

os_environ¶: 預設環境變數包含在每一個請求的 WSGI 環境中。預設情況下，這是在載入 wsgiref.handlers 時的 os.environ 副本，但子類別可以在類別或實例層級建立自己的副本。注意字典應該被視為唯讀，因為預設值在多個類別與實例中共享。

server_software¶: 如果設置 origin_server 屬性，則此屬性的值將用於設置預設的 SERVER_SOFTWARE WSGI 環境變數，並且還將用於設置 HTTP 回應中的預設 Server: 標頭。對於不是 HTTP origin 伺服器的處置程式（例如 BaseCGIHandler 和 CGIHandler），此屬性將被忽略。

在 3.3 版的變更: 將術語 "Python" 替換為特定實作的術語，如 "CPython"、"Jython" 等。

get_scheme()¶: 回傳用於當前請求的 URL scheme。預設的實作使用 wsgiref.util 中的 guess_scheme() 函式去猜測 scheme 是 "http" 或是 "https"，基於目前請求的 environ 變數。

setup_environ()¶: 將 environ 屬性設置為完全填充的 WSGI 環境。預設的實作使用上述所有方法和屬性，以及 get_stdin()、get_stderr() 和 add_cgi_vars() 方法以及 wsgi_file_wrapper 屬性。如果不呈現它也會插入一個 SERVER_SOFTWARE 關鍵字，只要 origin_server 屬性是一個 true 值並且 server_software 屬性被設置。

用於自定義例外處理的屬性和方法：

log_exception(exc_info)¶: 將 exc_info 元組記錄到伺服器日誌中。exc_info 是一個 (type, value, traceback) 元組。預設實作只是將追蹤資訊寫入到請求的 wsgi.errors 串流中並刷新它。子類別可以覆蓋此方法以更改格式或重新定向輸出，將追蹤資訊發送給管理員，或執行其他被認為合適的操作。

traceback_limit¶: 預設的 log_exception() 方法追蹤輸出中包含的最大幀數。如果為 None，則包含所有幀。

error_output(environ, start_response)¶

這個方法是一個為使用者去產生錯誤頁面的 WSGI 應用程式。只有在標頭傳送給用戶端前如果發生錯誤才會被呼叫。

此方法使用 sys.exception() 存取當前的錯誤，當呼叫它（如 PEP 3333 的 "Error Handling" 部分所描述）時應該傳遞資訊給 start_response。

預設的實作只是使用 error_status、error_headers 和 error_body 屬性產生輸出頁面。子類別可以覆蓋此方法以生成更動態的錯誤輸出。

然而，從安全的角度並不建議向任何普通使用者顯示診斷資訊；理想情況下，你應該需要採取特殊措施才能啟用診斷輸出，這就是預設實作不包括任何診斷資訊的原因。

error_status¶: 用於錯誤回應的 HTTP 狀態。這應該是一個按照 PEP 3333 定義的狀態字串；預設為 500 狀態碼和訊息。

error_headers¶: 用於錯誤回應的 HTTP 標頭。這應該是一個 WSGI 回應標頭的串列（(name, value) 元組），如 PEP 3333 中所描述。預設串列只設置內容種類為 text/plain。

error_body¶: 錯誤回應的主體。這應該是一個 HTTP 回應內容的位元組字串。預設為純文字 "A server error occurred. Please contact the administrator."

用於 PEP 3333 中的 "Optional Platform-Specific File Handling" 功能的方法和屬性：

wsgi_file_wrapper¶: 一個 wsgi.file_wrapper 工廠函式（factory），與 wsgiref.types.FileWrapper 相容，或者為 None。這個屬性的預設值是 wsgiref.util.FileWrapper 類別。

sendfile()¶: 覆蓋以實作特定平台的檔案傳輸。只有當應用程式的回傳值是由 wsgi_file_wrapper 屬性指定的類別實例時才會呼叫此方法。如果它能夠成功傳輸檔案應該回傳一個 true 值，以便不執行預設的傳輸程式碼。該方法的預設實作只回傳一個 false 值。

其他方法和屬性：

origin_server¶

這個屬性應該被設置為 true 值，如果處理程式（handler）的 _write() 和 _flush() 被用於直接與用戶端通訊，而不是透過 CGI-like 的閘道協議希望 HTTP 狀態在特殊的 Status: 標頭中。

這個屬性在 BaseCGIHandler 預設值為 true，但是在 BaseCGIHandler 和 CGIHandler 為 false。

http_version¶: 如果 origin_server 為 true，則此字串屬性用於設定傳送給用戶端的回應的 HTTP 版本。預設為 "1.0"。

wsgiref.handlers.read_environ()¶

從 os.environ 轉碼 CGI 變數到 PEP 3333 中的 "bytes in unicode" 字串，並回傳一個新字典。這個函式被 CGIHandler 和 IISCGIHandler 使用來直接替代 os.environ，在所有平台和使用 Python 3 的網頁伺服器上不一定符合 WSGI 標準，具體來說，在 OS 的實際環境是 Unicode（例如 Windows）的情況下，或者在環境是位元組的情況下，但 Python 用於解碼它的系統編碼不是 ISO-8859-1 （例如使用 UTF-8 的 Unix 系統）。

如果你自己正在實作 CGI-based 處理程式（handler），你可能想要使用這個函式來替換單純直接從 os.environ 中複製值。

在 3.2 版被加入.

`wsgiref.types` -- 用於靜態型別檢查的 WSGI 型別¶

這個模組提供在 PEP 3333 中所描述的各種用於靜態型別檢查的型別。

在 3.11 版被加入.

class wsgiref.types.StartResponse¶: 一個描述 start_response() 可呼叫物件的 typing.Protocol (PEP 3333)。

wsgiref.types.WSGIEnvironment¶: 一個描述 WSGI 環境字典的型別別名。

wsgiref.types.WSGIApplication¶: 一個描述 WSGI 應用程式可呼叫物件的型別別名。

class wsgiref.types.InputStream¶: 一個描述 WSGI 輸入串流的 typing.Protocol。

class wsgiref.types.ErrorStream¶: 一個描述 WSGI 錯誤串流的 typing.Protocol。

class wsgiref.types.FileWrapper¶: 一個描述檔案包裝器的 typing.Protocol。請參閱 wsgiref.util.FileWrapper 來瞭解此協議的具體實作。

範例¶

這個一個運作中的 "Hello World" WSGI 應用程式：

"""
Every WSGI application must have an application object - a callable
object that accepts two arguments. For that purpose, we're going to
use a function (note that you're not limited to a function, you can
use a class for example). The first argument passed to the function
is a dictionary containing CGI-style environment variables and the
second variable is the callable object.
"""
from wsgiref.simple_server import make_server


def hello_world_app(environ, start_response):
    status = "200 OK"  # HTTP Status
    headers = [("Content-type", "text/plain; charset=utf-8")]  # HTTP Headers
    start_response(status, headers)

    # The returned object is going to be printed
    return [b"Hello World"]

with make_server("", 8000, hello_world_app) as httpd:
    print("Serving on port 8000...")

    # Serve until process is killed
    httpd.serve_forever()

提供當前目錄的 WSGI 應用程式範例，並接受命令列上的可選目錄和埠號（預設：8000）：

"""
Small wsgiref based web server. Takes a path to serve from and an
optional port number (defaults to 8000), then tries to serve files.
MIME types are guessed from the file names, 404 errors are raised
if the file is not found.
"""
import mimetypes
import os
import sys
from wsgiref import simple_server, util


def app(environ, respond):
    # Get the file name and MIME type
    fn = os.path.join(path, environ["PATH_INFO"][1:])
    if "." not in fn.split(os.path.sep)[-1]:
        fn = os.path.join(fn, "index.html")
    mime_type = mimetypes.guess_type(fn)[0]

    # Return 200 OK if file exists, otherwise 404 Not Found
    if os.path.exists(fn):
        respond("200 OK", [("Content-Type", mime_type)])
        return util.FileWrapper(open(fn, "rb"))
    else:
        respond("404 Not Found", [("Content-Type", "text/plain")])
        return [b"not found"]


if __name__ == "__main__":
    # Get the path and port from command-line arguments
    path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
    port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000

    # Make and start the server until control-c
    httpd = simple_server.make_server("", port, app)
    print(f"Serving {path} on port {port}, control-C to stop")
    try:
        httpd.serve_forever()
    except KeyboardInterrupt:
        print("Shutting down.")
        httpd.server_close()

`wsgiref` --- WSGI 工具與參考實作¶

`wsgiref.util` -- WSGI 環境工具¶

`wsgiref.headers` -- WSGI 回應標頭工具¶

`wsgiref.simple_server` -- 一個簡單的 WSGI HTTP 伺服器¶

`wsgiref.validate` --- WSGI 符合性檢查¶

`wsgiref.handlers` -- 伺服器 / 閘道基本類別¶

`wsgiref.types` -- 用於靜態型別檢查的 WSGI 型別¶

範例¶

目錄

上個主題

下個主題

此頁面

wsgiref --- WSGI 工具與參考實作¶

wsgiref.util -- WSGI 環境工具¶

wsgiref.headers -- WSGI 回應標頭工具¶

wsgiref.simple_server -- 一個簡單的 WSGI HTTP 伺服器¶

wsgiref.validate --- WSGI 符合性檢查¶

wsgiref.handlers -- 伺服器 / 閘道基本類別¶

wsgiref.types -- 用於靜態型別檢查的 WSGI 型別¶

範例¶

`wsgiref` --- WSGI 工具與參考實作¶

`wsgiref.util` -- WSGI 環境工具¶

`wsgiref.headers` -- WSGI 回應標頭工具¶

`wsgiref.simple_server` -- 一個簡單的 WSGI HTTP 伺服器¶

`wsgiref.validate` --- WSGI 符合性檢查¶

`wsgiref.handlers` -- 伺服器 / 閘道基本類別¶

`wsgiref.types` -- 用於靜態型別檢查的 WSGI 型別¶