We will walk through the creation of a tiny Pyramid
application in this chapter. After we're finished creating it, we'll explain in more detail how the application works.
Note
If you're a "theory-first" kind of person, you might choose to read contextfinding_chapter
and views_chapter
to augment your understanding before diving into the code that follows, but it's not necessary if -- like many programmers -- you're willing to "go with the flow".
Here's one of the very simplest Pyramid
applications, configured imperatively:
from pyramid.configuration import Configurator
from pyramid.response import Response
from paste.httpserver import serve
def hello_world(request):
return Response('Hello world!')
def goodbye_world(request):
return Response('Goodbye world!')
if __name__ == '__main__':
config = Configurator()
config.begin()
config.add_view(hello_world)
config.add_view(goodbye_world, name='goodbye')
config.end()
app = config.make_wsgi_app()
serve(app, host='0.0.0.0')
When this code is inserted into a Python script named helloworld.py
and executed by a Python interpreter which has the Pyramid
software installed, an HTTP server is started on TCP port 8080:
$ python helloworld.py
serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
When port 8080 is visited by a browser on the root URL (/
), the server will simply serve up the text "Hello world!" When visited by a browser on the URL /goodbye
, the server will serve up the text "Goodbye world!"
Now that we have a rudimentary understanding of what the application does, let's examine it piece-by-piece.
The above script defines the following set of imports:
from pyramid.configuration import Configurator
from pyramid.response import Response
from paste.httpserver import serve
The script imports the Configurator
class from the pyramid.configuration
module. This class is used to configure Pyramid
for a particular application. An instance of this class provides methods which help configure various parts of Pyramid
for a given application deployment.
The script uses the pyramid.response.Response
class later in the script to create a response
object.
Like many other Python web frameworks, Pyramid
uses the WSGI
protocol to connect an application and a web server together. The paste.httpserver
server is used in this example as a WSGI server for convenience, as the paste
package is a dependency of Pyramid
itself.
The above script, beneath its set of imports, defines two functions: one named hello_world
and one named goodbye_world
.
def hello_world(request):
return Response('Hello world!')
def goodbye_world(request):
return Response('Goodbye world!')
These functions don't do anything very taxing. Both functions accept a single argument (request
). The hello_world
function does nothing but return a response instance with the body Hello world!
. The goodbye_world
function returns a response instance with the body Goodbye world!
.
Each of these functions is known as a view callable
. View callables in a Pyramid
application accept a single argument, request
and are 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 upstream WSGI
server and sent back to the requesting browser. To return a response, each view callable creates an instance of the pyramid.response.Response
class. In the hello_world
function, the string 'Hello world!'
is passed to the Response
constructor as the body of the response. In the goodbye_world
function, the string 'Goodbye world!'
is passed.
single: imperative configuration single: Configurator single: helloworld (imperative)
In the above script, the following code, representing the configuration of an application which uses the previously defined imports and function definitions is placed within the confines of an if
statement:
if __name__ == '__main__':
config = Configurator()
config.begin()
config.add_view(hello_world)
config.add_view(goodbye_world, name='goodbye')
config.end()
app = config.make_wsgi_app()
serve(app, host='0.0.0.0')
Let's break this down this piece-by-piece.
if __name__ == '__main__':
config = Configurator()
The 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 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 python helloworld.py
is executed from the operating system command line.
helloworld.py
in this case is a Python module. Using the if
clause is necessary -- or at least best practice -- because code in any Python module may be imported by another Python module. By using this idiom, the script is indicating that it does not want the code within the if
statement to execute if this module is imported; the code within the if
block should only be run during a direct script execution.
The config = Configurator()
line above creates an instance of the pyramid.configuration.Configurator
class. The resulting config
object 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 a application registry
associated with the application.
config.begin()
The pyramid.configuration.Configurator.begin
method tells the system that application configuration has begun. In particular, this causes the application registry
associated with this configurator to become the "current" application registry, meaning that code which attempts to use the application registry thread
local
will obtain the registry associated with the configurator. This is an explicit step because it's sometimes convenient to use a configurator without causing the registry associated with the configurator to become "current".
Note
See threadlocals_chapter
for a discussion about what it means for an application registry to be "current".
config.add_view(hello_world)
config.add_view(goodbye_world, name='goodbye')
Each of these lines calls the pyramid.configuration.Configurator.add_view
method. The add_view
method of a configurator registers a view
configuration
within the application registry
. A view
configuration
represents a set of circumstances related to the request
that will cause a specific view callable
to be invoked. This "set of circumstances" is provided as one or more keyword arguments to the add_view
method. Each of these keyword arguments is known as a view configuration predicate
.
The line config.add_view(hello_world)
registers the hello_world
function as a view callable. The add_view
method of a Configurator must be called with a view callable object or a dotted Python name
as its first argument, so the first argument passed is the hello_world
function. This line calls add_view
with a default value for the predicate
argument, named name
. The name
predicate defaults to a value equalling the empty string (''
). This means that we're instructing Pyramid
to invoke the hello_world
view callable when the view name
is the empty string. We'll learn in later chapters what a view name
is, and under which circumstances a request will have a view name that is the empty string; in this particular application, it means that the hello_world
view callable will be invoked when the root URL /
is visited by a browser.
The line config.add_view(goodbye_world, name='goodbye')
registers the goodbye_world
function as a view callable. The line calls add_view
with the view callable as the first required positional argument, and a predicate
keyword argument name
with the value 'goodbye'
. The name
argument supplied in this view configuration
implies that only a request that has a view name
of goodbye
should cause the goodbye_world
view callable to be invoked. In this particular application, this means that the goodbye_world
view callable will be invoked when the URL /goodbye
is visited by a browser.
Each invocation of the add_view
method implies a view
configuration
registration. Each predicate
provided as a keyword argument to the add_view
method narrows the set of circumstances which would cause the view configuration's callable to be invoked. In general, a greater number of predicates supplied along with a view configuration will more strictly limit the applicability of its associated view callable. When Pyramid
processes a request, however, the view callable with the most specific view configuration (the view configuration that matches the most specific set of predicates) is always invoked.
In this application, Pyramid
chooses the most specific view callable based only on view predicate
applicability. The ordering of calls to pyramid.configuration.Configurator.add_view
is never very important. We can register goodbye_world
first and hello_world
second; Pyramid
will still give us the most specific callable when a request is dispatched to it.
config.end()
The pyramid.configuration.Configurator.end
method tells the system that application configuration has ended. It is the inverse of pyramid.configuration.Configurator.begin
. In particular, this causes the application registry
associated with this configurator to no longer be the "current" application registry, meaning that code which attempts to use the application registry thread local
will no longer obtain the registry associated with the configurator.
Note
See threadlocals_chapter
for a discussion about what it means for an application registry to be "current".
single: make_wsgi_app single: WSGI application
app = config.make_wsgi_app()
After configuring views and ending configuration, the script creates a WSGI application via the pyramid.configuration.Configurator.make_wsgi_app
method. A call to make_wsgi_app
implies that all configuration is finished (meaning all method calls to the configurator which set up views, and various other configuration settings have been performed). The make_wsgi_app
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, however, you can learn more about it by visiting wsgi.org.
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 two calls to its add_view
method.
serve(app, host='0.0.0.0')
Finally, we actually serve the application to requestors by starting up a WSGI server. We happen to use the paste.httpserver.serve
WSGI server runner, passing it the app
object (a router
) as the application we wish to serve. We also pass in an argument host=='0.0.0.0'
, meaning "listen on all TCP interfaces." By default, the Paste HTTP server listens only on the 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 don't specify a TCP port number to listen on; this means we want to use the default TCP port, which is 8080.
When this line is invoked, it causes the server to start listening on TCP port 8080. It will serve requests forever, or at least until we stop it by killing the process which runs 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.
Note
An example of using declarative configuration (ZCML
) instead of imperative configuration to create a similar "hello world" is available within declarative_configuration
.
For more information about the API of a Configurator
object, see pyramid.configuration.Configurator
.
For more information about view configuration
, see views_chapter
.