Webob

在上一篇文章 WSGI 中我们提到的例子都是自己处理请求和响应、提供应用程序入口给服务端调用等。这样对我们学习 WSGI 本身是很好的，但如果我们每次在写应用逻辑的时候还要处理这些东西，就显得没有必要了，而且我们的处理方式不一定正确。这时 Webob 这类包的出现就很有意义了——让我们专注应用逻辑。

Webob 也是 OpenStack 里边用的比较多的包。本文主要介绍其 Request、Response、异常（webob.exc）及 WSGIfy 装饰器（webob.dec.wsgify）。

基本对象

Request

基本概念

官方对 Request 有一个简要的定义：

The request object is a wrapper around the WSGI environ dictionary.

也即，Request 是对 WSGI 中环境变量 environ 的一个封装。我们可以通过 req.environ 查看这些环境变量：

from webob import Request
from pprint import pprint

req = Request.blank('/')
pprint(req.environ)

# Results
# {'HTTP_HOST': 'localhost:80',
#  'PATH_INFO': '/',
#  'QUERY_STRING': '',
#  'REQUEST_METHOD': 'GET',
#  'SCRIPT_NAME': '',
#  'SERVER_NAME': 'localhost',
#  'SERVER_PORT': '80',
#  'SERVER_PROTOCOL': 'HTTP/1.0',
#  'wsgi.errors': <open file '<stderr>', mode 'w' at 0x030CD0D0>,
#  'wsgi.input': <_io.BytesIO object at 0x036A3F30>,
#  'wsgi.multiprocess': False,
#  'wsgi.multithread': False,
#  'wsgi.run_once': False,
#  'wsgi.url_scheme': 'http',
#  'wsgi.version': (1, 0)}

除此之外，它还有几个比较有用的成员变量：

• req.method：如 GET、POST 等。
• req.GET：包含查询字符串（query string）中的所有变量。注意要和 req.method 中的 GET 区分开来。
• req.POST：包含请求主体（body）中的所有变量。这里只有当请求是 POST 并且是表单提交时才有值。
• req.params：包含 req.GET 和 req.POST 的所有内容。
• req.body：请求的主体（string）。这对请求是 POST 但不是表单提交，或当请求是 PUT 时，是比较有用的。也可以通过 req.body_file 获得一个类似文件的对象。
• req.cookies：Cookies。
• req.headers：请求头部，注意这里大小写敏感。
• req.urlvars 和 req.urlargs：req.urlvars 是请求 url 中的关键字参数，req.urlargs 是位置参数（positional parameters）。它们由 Routes 和 Selector 这类工具来设定。

传递给 WSGI 应用

下边的例子摘自官方样例：

>>> req = Request.blank('/')
>>> def wsgi_app(environ, start_response):
...     start_response('200 OK', [('Content-type', 'text/plain')])
...     return ['Hi!']
>>> req.call_application(wsgi_app)
('200 OK', [('Content-type', 'text/plain')], ['Hi!'])

Response

基本概念

Response 跟 Request 很相似，虽然有一些不同点。Request 是对 environ 的封装；Response 则有 3 个根本的部分（基于 WSGI）：

• response.status：对应 WSGI 中 start_response 函数中的 status 参数
• response.headerlist：对应 WSGI 中 start_response 函数中的 response_headers 参数
• response.app_iter：对应应用程序返回值（body），需为可迭代对象。可通过 response.body、response.unicode_body 或 response.body_file 获取。

我们看下例子：

from webob import Response

res = Response('hey there')
print res.status
print res.headerlist
print res.body

# Results
# 200 OK
# [('Content-Type', 'text/html; charset=UTF-8'), ('Content-Length', '9')]
# hey there

Response 也是一个 WSGI 应用

Response 本身也是一个 WSGI 应用，通过源码就可以看得出来：

class Response(object):
    """
        Represents a WSGI response
    """
    ......

    def __call__(self, environ, start_response):
        """
        WSGI application interface
        """
        if self.conditional_response:
            return self.conditional_response_app(environ, start_response)
        headerlist = self._abs_headerlist(environ)
        start_response(self.status, headerlist)
        if environ['REQUEST_METHOD'] == 'HEAD':
            # Special case here...
            return EmptyResponse(self._app_iter)
        return self._app_iter

所以我们用 Request 来直接调用 Response 对象：

req = Request.blank('/')
status, headers, app_iter = req.call_application(res)

官方提供了一个样例如下：

>>> def my_app(environ, start_response):
...     req = Request(environ)
...     res = Response()
...     res.content_type = 'text/plain'
...     parts = []
...     for name, value in sorted(req.environ.items()):
...         parts.append('%s: %r' % (name, value))
...     res.body = '\n'.join(parts)
...     return res(environ, start_response)
>>> req = Request.blank('/')
>>> res = req.get_response(my_app)
>>> print res
200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: ...

HTTP_HOST: 'localhost:80'
PATH_INFO: '/'
QUERY_STRING: ''
REQUEST_METHOD: 'GET'
SCRIPT_NAME: ''
SERVER_NAME: 'localhost'
SERVER_PORT: '80'
SERVER_PROTOCOL: 'HTTP/1.0'
wsgi.errors: <open file '<stderr>', mode 'w' at ...>
wsgi.input: <...IO... object at ...>
wsgi.multiprocess: False
wsgi.multithread: False
wsgi.run_once: False
wsgi.url_scheme: 'http'
wsgi.version: (1, 0)

异常

Webob 异常（web.exc.WSGIHTTPException）本身既是一个 WSGI 应用也是一个 Response 对象，源码如下：

class WSGIHTTPException(Response, HTTPException):
    ......

    def __call__(self, environ, start_response):
        is_head = environ['REQUEST_METHOD'] == 'HEAD'
        if self.has_body or self.empty_body or is_head:
            app_iter = Response.__call__(self, environ, start_response)
        else:
            app_iter = self.generate_response(environ, start_response)
        if is_head:
            app_iter = []
        return app_iter

常见的异常如下：

Exception
	HTTPException
		HTTPOk
			200 - HTTPOk
			201 - HTTPCreated
			202 - HTTPAccepted
			203 - HTTPNonAuthoritativeInformation
			204 - HTTPNoContent
			205 - HTTPResetContent
			206 - HTTPPartialContent
		HTTPRedirection
			300 - HTTPMultipleChoices
			301 - HTTPMovedPermanently
			302 - HTTPFound
			303 - HTTPSeeOther
			304 - HTTPNotModified
			305 - HTTPUseProxy
			307 - HTTPTemporaryRedirect
			308 - HTTPPermanentRedirect
		HTTPError
			HTTPClientError
				400 - HTTPBadRequest
				401 - HTTPUnauthorized
				402 - HTTPPaymentRequired
				403 - HTTPForbidden
				404 - HTTPNotFound
				405 - HTTPMethodNotAllowed
				406 - HTTPNotAcceptable
				407 - HTTPProxyAuthenticationRequired
				408 - HTTPRequestTimeout
				409 - HTTPConflict
				410 - HTTPGone
				411 - HTTPLengthRequired
				412 - HTTPPreconditionFailed
				413 - HTTPRequestEntityTooLarge
				414 - HTTPRequestURITooLong
				415 - HTTPUnsupportedMediaType
				416 - HTTPRequestRangeNotSatisfiable
				417 - HTTPExpectationFailed
				422 - HTTPUnprocessableEntity
				423 - HTTPLocked
				424 - HTTPFailedDependency
				428 - HTTPPreconditionRequired
				429 - HTTPTooManyRequests
				431 - HTTPRequestHeaderFieldsTooLarge
				451 - HTTPUnavailableForLegalReasons
			HTTPServerError
				500 - HTTPInternalServerError
				501 - HTTPNotImplemented
				502 - HTTPBadGateway
				503 - HTTPServiceUnavailable
				504 - HTTPGatewayTimeout
				505 - HTTPVersionNotSupported
				511 - HTTPNetworkAuthenticationRequired

WSGIfy 装饰器

WSGIfy

相比较前文中的 Request、Response，个人感觉 wsgify 的作用显得更大，它让我们不用再多考虑 WSGI 接口，而是专注应用逻辑。例如，现在我们写一个 WSGI 应用就很简单了：

# -*- coding: utf-8 -*-

import webob
from webob.dec import wsgify  # webob 包的 __init__.py 文件没有导入 dec.py 文件，所以需要我们指明导入 dec 文件
from wsgiref.simple_server import make_server


@wsgify
def myfunc(req):
    return webob.Response('hey there')

httpd = make_server(
    '127.0.0.1',
    8051,
    myfunc
)

httpd.handle_request()

另外，我们还可以对 wsgify 装饰器进行定制，如官网提供的样例：

class MyRequest(webob.Request):
    @property
    def is_local(self):
        return self.remote_addr == '127.0.0.1'
@wsgify(RequestClass=MyRequest)
def myfunc(req):
    if req.is_local:
        return Response('hi!')
    else:
        raise webob.exc.HTTPForbidden

实现原理

对于装饰器基础，可参考之前博文【译】 Python 基础知识：装饰器（Decorator）。这里我们主要来看一下 wsgify 这个类是如何装饰函数的。直接看代码吧：

# webob/dec.py

class wsgify(object):
    ......

    def __init__(self, func=None, RequestClass=None,
                 args=(), kwargs=None, middleware_wraps=None):
        self.func = func
        if (RequestClass is not None
            and RequestClass is not self.RequestClass):
            self.RequestClass = RequestClass
        self.args = tuple(args)
        if kwargs is None:
            kwargs = {}
        self.kwargs = kwargs
        self.middleware_wraps = middleware_wraps

    ......

    def __call__(self, req, *args, **kw):
        """Call this as a WSGI application or with a request"""
        func = self.func
        if func is None:
            if args or kw:
                raise TypeError(
                    "Unbound %s can only be called with the function it "
                    "will wrap" % self.__class__.__name__)
            func = req
            return self.clone(func)
        if isinstance(req, dict):
            if len(args) != 1 or kw:
                raise TypeError(
                    "Calling %r as a WSGI app with the wrong signature" %
                    self.func)
            environ = req
            start_response = args[0]
            req = self.RequestClass(environ)
            req.response = req.ResponseClass()
            try:
                args = self.args
                if self.middleware_wraps:
                    args = (self.middleware_wraps,) + args
                resp = self.call_func(req, *args, **self.kwargs)
            except HTTPException as exc:
                resp = exc
            if resp is None:
                ## FIXME: I'm not sure what this should be?
                resp = req.response
            if isinstance(resp, text_type):
                resp = bytes_(resp, req.charset)
            if isinstance(resp, bytes):
                body = resp
                resp = req.response
                resp.write(body)
            if resp is not req.response:
                resp = req.response.merge_cookies(resp)
            return resp(environ, start_response)
        else:
            if self.middleware_wraps:
                args = (self.middleware_wraps,) + args
            return self.func(req, *args, **kw)

    ......

    def call_func(self, req, *args, **kwargs):
        """Call the wrapped function; override this in a subclass to
        change how the function is called."""
        return self.func(req, *args, **kwargs)

上边的 self.__call__ 函数是核心，除了表明该类 wsgify 可调用，还包装调用了真正的应用（第 35~43 行）。上边代码中的 resp 变量本身是一个 Response 对象，同时也是一个应用，所以最后传入 environ 和 start_response 向服务器返回结果。

wsgify.middleware

wsgify 除了作为一个装饰器，它还提供了中间件装饰器。如官方提供的一个样例（简单改造过）：

import webob
import webob.exc
from webob.dec import wsgify
from wsgiref.simple_server import make_server


@wsgify.middleware
def restrict_ip(req, app, ips):
    if req.remote_addr not in ips:
        raise webob.exc.HTTPForbidden('Bad IP: %s' % req.remote_addr)
    return app

@wsgify
def app(req):
    return 'hi'

wrapped = restrict_ip(app, ips=['127.0.0.1'])

httpd = make_server(
    '127.0.0.1',
    8051,
    wrapped
)

httpd.handle_request()

对于实现原理，理解起来有点绕。我们先来看一下 middleware 这个函数：

# webob/dec.py

class wsgify(object):
    ......

    @classmethod
    def middleware(cls, middle_func=None, app=None, **kw):
        """Creates middleware

        Use this like::

            @wsgify.middleware
            def restrict_ip(req, app, ips):
                if req.remote_addr not in ips:
                    raise webob.exc.HTTPForbidden('Bad IP: %s' % req.remote_addr)
                return app

            @wsgify
            def app(req):
                return 'hi'

            wrapped = restrict_ip(app, ips=['127.0.0.1'])

        Or as a decorator::

            @restrict_ip(ips=['127.0.0.1'])
            @wsgify
            def wrapped_app(req):
                return 'hi'

        Or if you want to write output-rewriting middleware::

            @wsgify.middleware
            def all_caps(req, app):
                resp = req.get_response(app)
                resp.body = resp.body.upper()
                return resp

            wrapped = all_caps(app)

        Note that you must call ``req.get_response(app)`` to get a WebOb
        response object.  If you are not modifying the output, you can just
        return the app.

        As you can see, this method doesn't actually create an application, but
        creates "middleware" that can be bound to an application, along with
        "configuration" (that is, any other keyword arguments you pass when
        binding the application).

        """
        if middle_func is None:
            return _UnboundMiddleware(cls, app, kw)
        if app is None:
            return _MiddlewareFactory(cls, middle_func, kw)
        return cls(middle_func, middleware_wraps=app, kwargs=kw)

其中，_MiddlewareFactory 定义如下：

# webob/dec.py

class _MiddlewareFactory(object):
    """A middleware that has not yet been bound to an application or
    configured.
    """

    def __init__(self, wrapper_class, middleware, kw):
        self.wrapper_class = wrapper_class
        self.middleware = middleware
        self.kw = kw

    def __repr__(self):
        return '<%s at %s wrapping %r>' % (self.__class__.__name__, id(self),
                                           self.middleware)

    def __call__(self, app=None, **config):
        kw = self.kw.copy()
        kw.update(config)
        return self.wrapper_class.middleware(self.middleware, app, **kw)

这里，我们本小结开头的中间件样例为例，来说明 wsgify.middleware 如何工作。

1. 初始化 restrict_ip 函数：restrict_ip = wsgify.middleware(restrict_ip)，返回一个 _MiddlewareFactory 对象。
2. 初始化 app 函数：app = wsgify(app)，返回一个应用 wsgify 对象。
3. wrapped = restrict_ip(app, ips=[‘127.0.0.1’])：调用 _MiddlewareFactory 对象（__call__），将 app 和 ips 传入该对象 __call__(self, app=None, **config) 函数，因为此时 _MiddlewareFactory 对象中的 self.wrapper_class 就是 wsgify，所以最终重新调用 wsgify.middleware。需要注意的是，此时传入该函数的参数跟之前的不一样，param:middle_func 还是 restrict_ip，但 param:app 和 param:kw 已经不为 None，分别为 app 和 ips。
4. 最后 wsgify.middleware 返回 cls(middle_func, middleware_wraps=app, kwargs=kw)，也即中间件 wsgify 对象，但需要注意的是此时 middleware_wraps 和 kwargs 已经不为 None。
5. 当有请求到达的时候，服务端开始调用（详细过程请参考之前博文 WSGIRef）该中间件 wsgify 对象，进入该对象的 __call__(self, req, *args, **kw) 函数，此时重点的地方在于以下：

   # webob/dec.py
   
   class wsgify(object):
       ......
   
   
       def __call__(self, req, *args, **kw):
           """Call this as a WSGI application or with a request"""
           ......
           if isinstance(req, dict):
               ......
               try:
                   args = self.args
                   if self.middleware_wraps:
                       args = (self.middleware_wraps,) + args	# 此时 args = (app,)，self.kwargs = ips
                   resp = self.call_func(req, *args, **self.kwargs)
   
                               |
                               |
   
       def call_func(self, req, *args, **kwargs):
           """Call the wrapped function; override this in a subclass to
           change how the function is called."""
           return self.func(req, *args, **kwargs)
   
                       |
                       |
   
   # 中间件函数（不是应用，单纯地执行函数）
   def restrict_ip(req, app, ips):
       if req.remote_addr not in ips:
           raise webob.exc.HTTPForbidden('Bad IP: %s' % req.remote_addr)
       return app
   
               |
               |
   
   # app 应用（wsgify 对象，注意跟中间件 wsgify 对象区分开来）
   @wsgify
   def app(req):
       return 'hi'
   
   # 接下来的执行就比较简单了，调用 wsgify 对象的 __call__ 函数，最终返回 app 处理结果。注意，此时的 wsgify 对象的 self.middleware_wraps 为 None，因为 app 已经是最后一个应用。