1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
*******************************
Your first CherryPy application
*******************************
The standard 'Hello world!' application takes less than 10 lines of code
when written using CherryPy::
import cherrypy
class HelloWorld:
def index(self):
return "Hello world!"
index.exposed = True
cherrypy.quickstart(HelloWorld())
We assume that you already have :doc:`installed </intro/install>` CherryPy.
Copy the file above and save it locally as ``hello.py``, then start the
application at the command prompt::
$ python hello.py
Direct your favorite web browser to http://localhost:8080 and you should
see ``Hello world!`` printed there.
How does it work?
-----------------
Let's take a look at ``hello.py``:
* The ``import cherrypy`` statement imports the main CherryPy module.
This is all that is required to have CherryPy working. Feel free to
"import cherrypy" in an interactive session and see what's available!
``help(cherrypy)`` is also quite useful.
* We declare a class named ``HelloWorld``. An instance of this class is the
object that will be published by CherryPy. It contains a single method,
named ``index``, which will get called when the root URL for the site is
requested (for example, ``http://localhost/``). This method returns the
**contents** of the Web page; in this case, the ``'Hello World!'`` string.
Note that you don't have to subclass any framework-provided classes; in fact,
you don't even have to use classes at all! But let's start with them for now.
* The ``index.exposed = True`` is a necessary step to tell CherryPy that the
``index()`` method will be **exposed**. Only exposed methods can be called
to answer a request. This feature allows the user to select which methods
of an object will be accessible via the Web; non-exposed methods can't be
accessed.
* ``cherrypy.quickstart(HelloWorld())`` mounts an instance of the HelloWorld
class, and starts the embedded webserver. It runs until explicitly
interrupted, either with ``Ctrl-C`` or via a suitable signal (a simple
``kill`` on Unix will do it).
When the application is executed, the CherryPy server is started with the
default configuration. It will listen on ``localhost`` at port ``8080``. These
defaults can be overridden by using a configuration file or dictionary
(more on this later).
Finally, the web server receives the request for the URL
``http://localhost:8080``. It searches for the best method to handle the
request, starting from the ``HelloWorld`` instance. In this particular case,
the root of the site is automatically mapped to the ``index()`` method (similar
to the ``index.html`` that is the standard page for conventional Web servers).
The HelloWorld class defines an ``index()`` method and exposes it. CherryPy
calls ``HelloWorld().index()``, and the result of the call is sent back to
the browser as the contents of the index page for the website. All the
dispatching and HTTP-processing work is
done automatically; the application programmer only needs to provide the
desired content as the return value of the ``index`` method.
CherryPy structure
------------------
Most of the features of CherryPy are available through the :mod:`cherrypy`
module. It contains several members:
* :class:`cherrypy.engine <cherrypy.process.wspbus.Bus>`
controls process startup, shutdown, and other events, including your own
Plugins. See :doc:`/concepts/engine`.
* :class:`cherrypy.server <cherrypy._cpserver.Server>` configures and controls
the HTTP server.
* :class:`cherrypy.request <cherrypy._cprequest.Request>` contains all
the information that comes with the HTTP request, after it is parsed and
analyzed by CherryPy.
* :attr:`cherrypy.request.headers <cherrypy.lib.httputil.HeaderMap>`
contains a mapping with the header options that were sent as part of
the request.
* :class:`cherrypy.session <cherrypy.lib.sessions.Session>` is a special
mapping that is automatically generated and encoded by CherryPy; it can
be used to store session-data in a persistent cookie. For it to work you
have to enable the session functionality by setting 'tools.session.on' to
True in your config.
* :class:`cherrypy.response <cherrypy._cprequest.Response>` contains the
data that is used to build the HTTP response.
* :attr:`cherrypy.response.headers <cherrypy.lib.httputil.HeaderMap>`
contains a mapping with the header options that will be returned by the
server, before the contents get sent.
* :attr:`cherrypy.response.body <cherrypy._cprequest.Response.body>` contains
the actual contents of the webpage that will be sent as a response.
|