Creating Your First Pyramid Application¶
In this chapter, we will walk through the creation of a tiny Pyramid application. After we're finished creating the application, we'll explain in more detail how it works. It assumes you already have Pyramid installed. If you do not, head over to the Installing Pyramid section.
Here's one of the very simplest Pyramid applications:
1from wsgiref.simple_server import make_server 2from pyramid.config import Configurator 3from pyramid.response import Response 4 5 6def hello_world(request): 7 return Response('Hello World!') 8 9 10if __name__ == '__main__': 11 with Configurator() as config: 12 config.add_route('hello', '/') 13 config.add_view(hello_world, route_name='hello') 14 app = config.make_wsgi_app() 15 server = make_server('0.0.0.0', 6543, app) 16 server.serve_forever()
When this code is inserted into a Python script named
executed by a Python interpreter which has the Pyramid software
installed, an HTTP server is started on TCP port 6543.
This command will not return and nothing will be printed to the console. When
port 6543 is visited by a browser on the URL
/, the server will
simply serve up the text "Hello world!". If your application is running on
your local system, using http://localhost:6543/ in a browser
will show this result.
Each time you visit a URL served by the application in a browser, a logging line will be emitted to the console displaying the hostname, the date, the request method and path, and some additional information. This output is done by the wsgiref server we've used to serve this application. It logs an "access log" in Apache combined logging format to the console.
Ctrl-Break on Windows) to stop the application.
Now that we have a rudimentary understanding of what the application does, let's examine it piece by piece.
helloworld.py script uses the following set of import statements:
1from wsgiref.simple_server import make_server 2from pyramid.config import Configurator 3from pyramid.response import Response
Like many other Python web frameworks, Pyramid uses the WSGI
protocol to connect an application and a web server together. The
wsgiref server is used in this example as a WSGI server for convenience,
as it is shipped within the Python standard library.
The script imports the
Configurator class from the
pyramid.config module. An instance of the
Configurator class is later used to configure your
The script also imports the
pyramid.response.Response class for later
use. An instance of this class will be used to create a web response.
View Callable Declarations¶
The above script, beneath its set of imports, defines a function named
6def hello_world(request): 7 return Response('Hello World!')
The function accepts a single argument (
request) and it returns an instance
pyramid.response.Response class. The single argument to the
class' constructor is a string computed from parameters matched from the URL.
This value becomes the body of the response.
This function is known as a view callable. A view callable accepts a
request. It is expected to return a response
object. A view callable doesn't need to be a function; it can be represented
via another type of object, like a class or an instance, but for our purposes
here, a function serves us well.
A view callable is always called with a request object. A request object is a representation of an HTTP request sent to Pyramid via the active WSGI server.
A view callable is required to return a response object because a
response object has all the information necessary to formulate an actual HTTP
response; this object is then converted to text by the WSGI server
which called Pyramid and it is sent back to the requesting browser. To return
a response, each view callable creates an instance of the
Response class. In the
hello_world function, a
string is passed as the body to the response.
In the above script, the following code represents the configuration of this
simple application. The application is configured using the previously defined
imports and function definitions, placed within the confines of an
10if __name__ == '__main__': 11 with Configurator() as config: 12 config.add_route('hello', '/') 13 config.add_view(hello_world, route_name='hello') 14 app = config.make_wsgi_app() 15 server = make_server('0.0.0.0', 6543, app) 16 server.serve_forever()
Let's break this down piece by piece.
10if __name__ == '__main__': 11 with Configurator() as config:
if __name__ == '__main__': line in the code sample above represents a
Python idiom: the code inside this if clause is not invoked unless the script
containing this code is run directly from the operating system command line.
For example, if the file named
helloworld.py contains the entire script
body, the code within the
if statement will only be invoked when
helloworld.py is executed from the command line.
if clause is necessary—or at least best practice—because code in
.py file may be eventually imported via the Python
statement by another
.py files that are imported by other
.py files are referred to as modules. By using the
if __name__ ==
'__main__': idiom, the script above is indicating that it does not want the
code within the
if statement to execute if this module is imported from
another; the code within the
if block should only be run during a direct
with Configurator() as config: line above creates an instance of the
Configurator class using a context manager. The resulting
represents an API which the script uses to configure this particular
Pyramid application. Methods called on the Configurator will cause
registrations to be made in an application registry associated with the
12 config.add_route('hello', '/') 13 config.add_view(hello_world, route_name='hello')
The first line above calls the
method, which registers a route to the root (
/) URL path.
The second line registers the
hello_world function as a view
callable and makes sure that it will be called when the
hello route is
WSGI Application Creation¶
14 app = config.make_wsgi_app()
After configuring views and ending configuration, the script creates a WSGI
application via the
A call to
make_wsgi_app implies that all configuration is finished
(meaning all method calls to the configurator, which sets up views and various
other configuration settings, have been performed). The
method returns a WSGI application object that can be used by any WSGI
server to present an application to a requestor. WSGI is a protocol
that allows servers to talk to Python applications. We don't discuss
WSGI in any depth within this book, but you can learn more about it by
reading its documentation.
The Pyramid application object, in particular, is an instance of a class
representing a Pyramid router. It has a reference to the
application registry which resulted from method calls to the
configurator used to configure it. The router consults the registry to
obey the policy choices made by a single application. These policy choices
were informed by method calls to the Configurator made earlier; in our
case, the only policy choices made were implied by calls to its
WSGI Application Serving¶
15 server = make_server('0.0.0.0', 6543, app) 16 server.serve_forever()
Finally, we actually serve the application to requestors by starting up a WSGI
server. We happen to use the
make_server server maker for
this purpose. We pass in as the first argument
'0.0.0.0', which means
"listen on all TCP interfaces". By default, the HTTP server listens only on
127.0.0.1 interface, which is problematic if you're running the server
on a remote system and you wish to access it with a web browser from a local
system. We also specify a TCP port number to listen on, which is 6543, passing
it as the second argument. The final argument is the
app object (a
router), which is the application we wish to serve. Finally, we call
serve_forever method, which starts the main loop in which it
will wait for requests from the outside world.
When this line is invoked, it causes the server to start listening on TCP port
6543. The server will serve requests forever, or at least until we stop it by
killing the process which runs it (usually by pressing
Ctrl-Break in the terminal we used to start it).
Our hello world application is one of the simplest possible Pyramid applications, configured "imperatively". We can see that it's configured imperatively because the full power of Python is available to us as we perform configuration tasks.
For more information about the API of a Configurator object, see
For more information about view configuration, see View Configuration.