wsgirf-WSGI功能及参考实现

源码：Lib/wsgiref

Web服务器网关接口（Web Server Gateway Interface, WSGI），是用Python写的一个服务器软件和web应用之间的通用接口。使用通用接口，能够使同一个应用方便的被不同过的web服务器调用。

只有web服务器和软件框架作者需要知道WSGI设计的细节和极端情况。你只需要安装一个WSGI应用或者用现有框架写一个web应用，并不需要知道WSGI的全部细节。

wsgiref是WSGI细则的一个参考实现，用于给web服务器和框架提供WSGI支持。它提供了处理WSGI环境变量、response头和WSGI服务器基类的功能，一个服务于WSGI应用的HTTP服务器demo，以及检测WSGI服务器和应用是否和WSGI细则（PEP 3333）是否一致的验证工具。

去wsgi官网获取更多信息和相关教程。

wsgiref.util – WSGI环境工具

本模块提供了一些列用于WSGI环境的适用功能。 根据PEP 3333， WSGI环境是一个包含HTTP请求变量的字典。所有接受environ参数的函数都预期接受一个兼容于WSGI的字典。详见PEP 3333。

wsgiref.util.guess_scheme(environ)

通过检查环境变量中的HTTPS，返回wsgi.url_scheme是http还是https。
这个函数用于，创建一个包装CGI或者FastCGI协议的网关。一般来说，提供这些协议的服务器，当使用SSL时，会提供一个值为”1″, “yes”或者”on”的HTTPS变量。如果找到了，这个函数返回’https’；否则，返回’http’。

wsgiref.util.request_uri(environ, include_query=True)

返回请求的URI，可选参数决定是否返回查询字符串，使用PEP 3333中的”URL Reconstruction”算法。

wsgiref.util.application_uri(environ)

与request_uri方法类似，除了忽略PATH_INFO 还有QUERY_STRING变量。返回结果为发起请求的应用对象的基地址（base uri)。

wsgiref.util.shift_pathi_info(environ)

将环境变量中PAHT_INFO移动一个名字到SCRIPT_NAME，并返回。环境变量会被原地修改，如果你要保存原始值，存一个备份 。
如果PAHT_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。
当路径仅为"/"时，该例行程序返回空字符串，并在SCRIPT_NAME处添加末尾斜杠。尽管空路径片段一般都被忽略了。但SCRIPT_NAME一般不以斜杠结束。故意这样设计，是为了让应用在做对象遍历时，能够区分/x和/x/这两个不同的路径。

# 源码
# https://github.com/python/cpython/blob/master/Lib/wsgiref/util.py#L102
if not name and not script_name.endswith('/'):
    script_name += '/'

wsgiref.util.setup_testing_defaults(environ)

为了测试而更新环境变量。

这个例行程序为WSGI添加各种参数，包括HTTP_HOST, SERVER_NAME, SERVER_PORT, REQUESTS_METHOD, SCRIPT_NAME。以及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

# 这行代码我在3.6.1下运行会出错，make_server不支持上下文管理？
# 把with 语句改成普通的语句好像就没问题了。
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)

根据[RFC 2616](https://tools.ietf.org/html/rfc2616.html),如果`header_name`是`"Hop-by-Hop"`返回True.

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

一个把类文件对象转变为成迭代器的包装器。结果支持`__getitem__()`和`__iter__()`。当迭代遍历这个对象时，`blksize`参数会被重复地传给类文件对象地`read()`方法，获取产生的字节。当`read()`产生空字节时，迭代结束。
如果这个类文件对象有`close()`方法，返回的对象也有`close()`方法，当被调用时，会激活类文件对象的`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)

wsgi.headers WSGI response 头工具

本模块只提供一个类：Headers。使用(mapping-like interface)映射接口， 方便操作地操作WSGI地响应头。

wsgiref.headers.Headers([headers])类

创建一个映射对象包装headers。 headers，必须是按照PEP 3333中所规定地键值元组列表。默认值时一个空列表。】

Headers对象支持映射操作，包括__getitem()， get(), __setitem()， setdefault()， __delitem()， 以及__contain__()。key是name，值是该name下的第一个值。

与字典不同，在你试图删除或者get一个不存在key时，Headers对象不会抛出异常。Headers的长度等于它items()的长度，

bytes()函数，返回一个格式化的字符串，用于传输HTTP响应头。每个头占一行，用冒号和控开关白分割。行为时回车+换行。结尾是一个空行

get_all(name)

返回对应name下所有的值

返回顺序为他们在最初的头中的位置，或者他们被添加进实例的顺序。可能会重复。

add_header(name, value, **_params)

添加一个头，通过关键词参数可以添加MIME参数。

在参数名里的下划线会被转换成连接符。因为连接符在python标识符中不合法，但在MIME参数中有很多连接符。

wsgiref.simple_server一个简单的WSGI HTTP服务器

本模块提供了一个简单的基于http.server的，可服务于WSGI应用的HTTP服务器。每一个服务器实例，在一个给定的主机和端口上服务于一个WSGI应用。如果你想在一个主机和端口上，服务于多个应用，你应当创建一个WSGI应用，解析PATH_INFO决定对于每个请求，应该选择哪个应用。

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

在指定host和port上，创建一个新的WSGI服务器，接受来自app的连接。返回值是传入的server_class的一个实例。并会使用handler_class处理requests。app参数必须是一个符合PEP 3333定义的WSGI应用对象。

wsgirfe.simple_server.demo_app(environ, start_response)

本函数是一个小而完全的WSGI程序，返回一个包含”Hello world!”和环境变量k-v值对的文本页。用于确认WSGI服务器能够争取的处理WSGI程序。

wsgiref.simple_server.WSGIServer(server_address, RequestsHandlerClass)类

创建一个WSGISever实例，server_address应当是(host, port)元组，RequestHandlerClass应当是http.server.BasedHTTPRequestHandler的子类，用于处理requests。

你不需要正式调用构造器，因为make_server()函数会帮你处理细节。

WSGIServer是http.server.HTTPServer的子类，所以继承了其方法，如：serve_forever()和handle_request()。WSGIServer同时也提供了一些WSGI专有的方法。比如：

set_app(application)

设置一个可调用应用，作为接收requests的WSGI应用。

get_app()

返回目前设置的可调用应用。

一般来说，你不要调用这些额外的方法。 set_app()一般有make_server()调用，get_app()主要是为了requests handler实例而存在。

wsgiref.simple_server.WSGIRequestHandler(reqeust, client_address, server)类

对于给定的request（例如，一个socket）, client_address （一个(host, port)元组）server，创建一个HTTP handler。

你不需要直接创建这个类的实例，他们会由WSGIServer对象按需创建。单你可以创建一个该类的子类，作为handler_class参数，传给make_server()函数。以下为一些在子类中可能相关的需要重写的函数。

get_environ()

返回一个包含WSGI环境的字典。默认设置返回WSGIServer对象的base_environ字典属性，并加上来自HTTP request的各种头部。每次调用这个方法，都会放回一个新的字典，包含各种PEP 3333中规定的CGI环境变量。

get_stderr()

返回被用作wsgi.errors流的对象。默认设置返回sys.stderr。

handle()

处理HTTP请求，默认这是使用wsgiref.hanlder类创建一个handler实例，执行真实的WSGI应用接口。

wsgirref.validate WSGI一致性检查器

当创建新的WSGI应用对象、框架、服务器和中间件时，用wsgiref.validate检查新代码是否可用是非常有用过的。本模块提供了一个能创建WSGI应用对象的函数，使WSGI服务器和WSGI应用对象能够正常通信，检查两侧协议的一致性。

注意这个应用不保证完全符合PEP 3333。这个模块不报错，不意味着肯定没错。但是，如果这个模块报错，就意味着肯定有错误。不是100%兼容。

这个模块基于Python Paste。

wsgiref.validate.validator(application)`

包装application并返回一个新的WSGI应用对象，返回的应用将会把所有的请求发送给最初的应用。并且检查这个应用和启动它的服务器是否遵循WSGI规则和RFC 2616

任何检测到的不一致的结果，都会抛出一个AssertionError。但，如何处理这些异常取决于服务器。比如，wsgiref.simple_server和提前基于wsgiref.handlers的服务器，会直接输出错误信息，将回溯信息输出到sys.stderr或者其他错误流中。

这个包装器也可能用warning模块指明那些有问题的，但不完全违反PEP 3333的行为。除非用Python命令行选项或者是warning的api禁止，这些细心会被输出至sys.stderr。

wsgirf.handlers 服务器/网管基类

这个模块提供了配置WSGI服务器和网关的基类。这些基类处理了大部分与一个WSGI应用之间的通信，只要给与了他们一个CGI样的环境，以及输入/输出及错误流。

wsgiref.hanlder.CGIHandler类

通过sys.stdin, sys.stdout, sys.stderr和os.environ唤起CGI。当你想要通过一个CGI脚本运行一个WSGI程序时很有用。你可以使用CGIHandler().run(app)。

这个类是BaseCGIHandler的子类，并将wsgi.run()=True, wsgi.multithread=False, wsgi.multiprocess=True，并使用sys和os获取必要的CGI流和环境。(参见CGI部分和前驱知识)

wsgiref.handler.IISCGIHandler类

在微软的IIS服务器上激活CGIHandler。

wsgiref.handlers.BaseCGIHandler()类

和CGIHandler类 类似。

wsgiref.handlers.BaseHandler

一个抽象类。每个实例处理一个HTTP请求。尽管原则上你可以创建一个子类，从而能被多个请求服用。

只有一个方法能被外部调用。

run(app)