当前位置: 首页 > 工具软件 > CherryPy > 使用案例 >

cherrypy简介

戚成礼
2023-12-01

本文将介绍 CherryPy,一种用于 Python 的、简单而又非常有用的 Web 框架。它所做的全部工作就是以尽可能少的忙乱将 Web 服务器与您的 Python 代码连接。它并不决定使用哪些其他工具,所以您可以从自己的角度自由地选择模板系统、数据库映射程序或者其他工具。我将说明如何使用 CherryPy 编写应用程序。本文假定您已经拥有了一些关于 Python 以及 HTTP 请求和响应如何工作的知识。

CherryPy 请求

CherryPy 不是依靠 Apache 或者另外的 Web 服务器,而是运行它自己的小型的基于 Python 的 Web 服务器。传统的 Web 服务器在目录树磁盘之外创建一个 Web 空间,而 CherryPy 服务器则在 Python 对象树之外创建它的 Web 空间。

考虑一下对于 URL http://localhost:8080/hello/ 的请求。在传统的 Web 服务器中,这种 URL 相应于 Web 空间根部下面的 hello/ 目录。当您使用 Web 浏览器访问它时,Web 服务器读取 hello/ 目录中的 index.html 文件或者调用该目录中的 index.cgi 脚本作为一个 CGI,并且向您发送输出。

CherryPy Web 服务器不提供根植于磁盘目录中的 Web 空间,而提供根植于特定的 Python 对象 cpg.root 中的 Web 空间。若要访问那个对象的每个方法和成员,只需将它的名称附加到根 URL 上即可。所以,hello/ URL 在 CherryPy 中相应于 cpg.root 的成员 hello

通过定义一个方法为请求提供服务

如果 cpg.root.hello 是一个方法,则 CherryPy 调用该方法,方法的输出被发送到 Web 浏览器。下面的代码定义一个暴露 hello 方法的对象:

清单 1. 定义一个暴露 hello 方法的对象
#!/usr/bin/env python
from cherrypy import cpg
class Application:
    @cpg.expose
    def hello(self):
        return "Hello, world!"
    
cpg.root = Application()
cpg.server.start()

通过 Python 运行这段脚本,CherryPy Web 服务器将会启动。只要该脚本一直在运行,您就可以访问 http://localhost:8080/hello/,并且可以看到字符串 Hello, world!。(当然,这还得假定您没有在端口 8080 上运行一台服务器。)如果您访问其他 URL,包括 Web 服务器根,将会得到一个 CherryPy 错误,因为 /hello/ 是该应用程序知道如何提供服务的惟一 URL。

通过定义对象树为请求提供服务

如果 cpg.root.hello 是一个对象,而不是方法,那么当用户访问 /hello/ 时,CherryPy 会调用 hello 对象的 index() 方法。这些代码以与先前示例相同的方式提供 /hello/ URL 服务:

清单 2. CherryPy 调用 hello 对象的 index() 方法
#!/usr/bin/env python
from cherrypy import cpg
class HelloWorld:
    @cpg.expose
    def index(self):
        return "Hello, world!"
class Application:
    hello = HelloWorld()
    
cpg.root = Application()
cpg.server.start()

当您访问 /hello/ URL 时,您的请求被映射到对象 cpg.root.hello,并且其默认的方法(index())被调用来处理该请求。

暴露对象和方法

方法 hello 和 index 上的 装饰符 @cpg.expose 有什么用呢?它告诉 CherryPy,调用该方法来响应 Web 请求没有问题。

在提供静态文件的 Web 网站,假定 Web 空间中的每个文件和目录都计划用于公共消耗。但是也有几处例外,例如,Apache 就不会提供隐藏的文件,如 UNIX® 系统上的 .htaccess。

当您将一个对象树暴露为一个 CherryPy URL 空间时,假设是另一种情形:除非您显性地将方法标记为暴露,否则它不会为外面的用户提供服务。考虑一下许多编程语言中公有和私有类成员之间的区别,(并且通过 Python 中的 _method() 约定非正式地实施)。一个设计良好的 CherryPy 类可能只有少数几个公有的方法暴露给 Web 客户机,但是它很可能有许多不允许客户机直接访问的内部方法。

我认为装饰符是将方法暴露给 CherryPy 的最佳方式,但是也可以通过将其成员 exposed 设置为 True 来暴露一个方法:

清单 3. 通过将其成员 exposed 设置为 True 来暴露一个方法
class HelloWorld:
    def index(self):
        return "Hello, world!"
    index.exposed = True

装饰符不存在于版本 2.4 之前的 Python 中,因而 exposed 这个技巧可能是您将方法暴露给 CherryPy 的惟一方式。

收集用户输入

当用户向 CGI 脚本提交表单或者提供信息时,Web 浏览器会收集那些信息,并且通过环境变量将其传递给该脚本。脚本的责任是解析和理解这些信息,尽管有一套约定控制着这些信息的格式和用途。CherryPy 使用这些非正式的约定消除这个过程的几个步骤,以参数的形式将用户输入提供给它决定调用的 Python 方法。

将查询字符串转变为关键字参数

考虑一个具有查询参数的 URL,比如 http://localhost:8080/hello/?what=hello&who=world。用户可能已经点击这个 URL,或者已将它提交为填充 HTML 表单的结果。传统的基于 CGI 的 Web 服务器将把 what=hello&who=world 传递到环境变量 QUERY_STRING 中的 CGI 脚本。CGI 脚本负责取出该变量,解析那个字符串。Python 的 cgi 模块为您进行解析。但是,使用 CherryPy,您不必做任何事情。CherryPy Web 服务器自动将 URL 的查询字符串转变为一组关键字参数。

清单 4. CherryPy Web 服务器自动将 URL 的查询字符串转变为一组关键字参数
class Application:
    @cpg.expose
    def hello(self, what='Hello', who='world'):
        return '%s, %s!' % (what, who)

当用户点击 /hello/ URL 时,CherryPy 将查询字符串中的 what 和 who 转换为 hello() 方法的参数。从 URL 到 Python 方法调用的转换对您来说完全是透明的。它甚至不在乎原始的 HTTP 请求是通过方法 GET 进来的,还是通过方法 POST 进来的。

将额外的路径部分转换为位置参数

CGI 脚本用户输入的其他来源是环境变量 PATH_INFO。它通常用于使 Web 应用程序的 URL 看起来更像真实的 Web 页。例如,考虑 URL http://localhost:8080/hello/world/。如果 /hello/ 指定了一个 CGI 脚本,那么访问 /hello/world/ 会将 PATH_INFO 环境变量设置为 /world/ 而调用那个脚本。

在 CGI 环境中,是由 CGI 脚本负责解析额外路径信息。但是利用查询字符串参数,CherryPy 基于典型的使用约定为您进行解析。查询字符串键值对成为 CherryPy 应用程序中的关键字参数,而额外路径信息参数则成为对象的 default() 方法的位置参数:

清单 5. 额外路径信息参数成为对象的 default() 方法的位置参数
class Hello:
    @cpg.expose
    def default(self, who):
        return 'Hello, %s!' % who
class Application:
    hello = Hello()
cpg.root = Application()
cpg.server.start()

/hello/world/ URL 的 hello/ 部分被映射为 cpg.root.hello,这是 Hello 的一个实例。对象 Hello 没有叫做 world 的方法或者成员对象,所以这个 URL 的 world 部分作为那个对象的 default() 方法的位置参数被传递进来。

读取自请求对象的标题

CherryPy 解析用户请求的 URL,并使用适当的参数传送到 Python 方法,但是一个 HTTP 请求不只是一个 URL。那进来的 HTTP 标题又如何呢?

CherryPy 方法都具有对叫做 cgp.request 的对象的访问权,该对象包含有许多关于用户的 HTTP 请求的信息。这个对象最有意思的成员是requestMap,它包含与 Web 请求相关的所有进入的 HTTP 标题:

清单 6. requestMap 包含与 Web 请求相关的进入的 HTTP 标题
class Application:
    @cpg.expose
    def index(self):
        items = [x + ': ' + y for x,y in cpg.request.headerMap.items()]
        return "<br />".join(items)

运行该应用程序并访问 http://localhost:8080/,您将会看到您的浏览器与其请求一起发送的所有 HTTP 标题的列表清单。

写到响应对象

对 HTTP 请求怎样,对响应也就怎样。CherryPy 应用程序方法通常情况下会以字符串的形式返回响应的正文,但是有时需要您设置附加的 HTTP 标题,进行一个重定向,或者改变 HTTP 响应代码。您可以借助对每个方法都可用的对象 cpg.response 来完成所有这些事情。

cpg.response.headerMap 是外出 HTTP 标题的映射,就像 cpg.request.requestMap 是进入标题的映射一样:

清单 7. cpg.response.headerMap 是外出 HTTP 标题的映射
#!/usr/bin/env python
from cherrypy import cpg
class Application:
    @cpg.expose
    def setHeader(self, header, value):
        """Hit the '/setHeader?header=Value&foo=bar' URL to get a
	response in which the HTTP header "foo" has a value of
	"bar"."""
        cpg.response.headerMap[header] = value
        return 'Set HTTP response header "%s" to "%s"' % (header, value)

HTTP 状态代码只不过是一个叫做 Status 的 HTTP 标题,所以您可以将它设置为 404、503,或者您需要的其他状态:

清单 8. 设置 HTTP 标题状态
@cpg.expose
    def forbidden(self):
        "Hit the '/forbidden' URL to be denied access."
        cpg.response.headerMap['Status'] = '503 Forbidden'
        return "You don't have permission to access this resource."

若要将某个 HTTP 重定向,您可以手工设置 Status 和 Location 标题,或者可以使用 CherryPy 的 httputils 助手库的 redirect 方法,它完成相同的工作:

清单 9. 使用 CherryPy 的 httputils 助手库的 redirect 方法
@cpg.expose
    def redirect(self):
        "Hit the '/redirect' URL to be redirected."
        from cherrypy.lib import httptools
        httptools.redirect('./destination')
    @cpg.expose
    def destination(self):
        "This is where you end up if you hit the '/redirect' URL."
        from cherrypy.lib import httptools
        cpg.response.headerMap['Content-Type'] = 'text/plain'
        return 'Here is some plain text.'
cpg.root = Application()
cpg.server.start()

在一个会话中保持持续信息

考虑一个这样的应用程序,在其中我可以点击 URL /name/set?name=leonardr 来设置一些数据,然后我可以点击 URL /name/show,并被告知Your previously set name is leonardr。由于第二个请求使用来自第一个请求的信息,所以这两个请求都必须是单个会话的组成部分。我第一次请求中发送的字符串 leonardr 存储在服务器的某个位置。当我进行第二次请求时,不知何故我被认为是发送第一个请求的同一人,并检索到我与第一个请求一起发送的信息。

CherryPy 隐藏了这种复杂性的大部分,使得易于建立和使用基于 cookie 的会话 —— 这是一个重要的功能,但是并不是 CGI 本身就支持的功能。您可以将任何 Python 对象存储在 cpg.request.sessionMap 映射中,下次相同的用户点击您的页面时它就在那儿。下面的示例与刚才描述的应用程序的工作原理相似:

清单 10. 将任何 Python 对象存储在 cpg.request.sessionMap 映射中
#!/usr/bin/env python
from cherrypy import cpg
class Application:
    @cpg.expose
    def set(self, name):
        cpg.request.sessionMap['name'] = name
        return 'Set name to %s' % name
    @cpg.expose
    def show(self):
        return 'Your previously set name is %s.' % \
               cpg.request.sessionMap.get('name', '[none]')

到目前为止都相当简单。可是,为了这些代码起作用,需要设置 CherryPy 服务器将会话 cookie 与每个 HTTP 响应相关联。否则,CherryPy 就永不可能将两个请求与相同的会话关联起来。您可以在 CherryPy 服务器配置文件中进行这些配置(参见 参考资料),但是比较易于证明它是启动 CherryPy Web 服务器的 Python 代码的一部分:

清单 11. 启动 CherryPy Web 服务器的 Python 代码的一部分
cpg.root = Application()
cpg.server.start(configMap={'sessionStorageType' : 'ram',
                            'sessionCookieName' : 'CherryPySessionCookie',
                            'sessionTimeout' : 60}) #Session expires in an hour

结束语

CherryPy 使用与 CGI 相同的概念将 Web 服务器与 Web 应用程序绑定起来,但是通过在单个进程内处理它的所有请求,改善了性能,并且获得了请求间的持续性。因为它只是绑定到 Python 代码,所以它并不需要经常隐藏 CGI 的信息传递技术,这样导致更易理解的更少代码行。CherryPy 是 CGI 的优秀替代品,并且是创建 Python Web 应用程序的良好基础。

 类似资料: