single: hello world program
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_chapter
section.
Here's one of the very simplest Pyramid
applications:
helloworld.py
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.
On UNIX:
$ /path/to/your/virtualenv/bin/python helloworld.py
On Windows:
C:\> \path\to\your\virtualenv\Scripts\python.exe helloworld.py
This command will not return and nothing will be printed to the console. When port 8080 is visited by a browser on the URL /hello/world
, the server will simply serve up the text "Hello world!". If your application is running on your local system, using http://localhost:8080/hello/world
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.
Press Ctrl-C
(or 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.
The above helloworld.py
script uses the following set of import statements:
helloworld.py
The script imports the ~pyramid.config.Configurator
class from the pyramid.config
module. An instance of the ~pyramid.config.Configurator
class is later used to configure your Pyramid
application.
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 also imports the pyramid.response.Response
class for later use. An instance of this class will be used to create a web response.
The above script, beneath its set of imports, defines a function named hello_world
.
helloworld.py
The function accepts a single argument (request
) and it returns an instance of the 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 single argument, 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 ~pyramid.response.Response
class. In the hello_world
function, a string is passed as the body to the response.
single: imperative configuration single: Configurator single: helloworld (imperative)
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 if
statement:
helloworld.py
Let's break this down piece-by-piece.
helloworld.py
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 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 python helloworld.py
is executed from the command line.
Using the if
clause is necessary -- or at least best practice -- because code in a Python .py
file may be eventually imported via the Python import
statement by another .py
file. .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 script execution.
The config = Configurator()
line above creates an instance of the ~pyramid.config.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 an application registry
associated with the application.
helloworld.py
First line above calls the pyramid.config.Configurator.add_route
method, which registers a route
to match any URL path that begins with /hello/
followed by a string.
The second line, config.add_view(hello_world, route_name='hello')
, registers the hello_world
function as a view callable
and makes sure that it will be called when the hello
route is matched.
single: make_wsgi_app single: WSGI application
helloworld.py
After configuring views and ending configuration, the script creates a WSGI application via the pyramid.config.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 calls to its add_view
and add_route
methods.
helloworld.py
Finally, we actually serve the application to requestors by starting up a WSGI server. We happen to use the wsgiref
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 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 also specify a TCP port number to listen on, which is 8080, passing it as the second argument. The final argument is the app
object (a router
), which is the the application we wish to serve. Finally, we call the server's 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 8080. The server will serve requests forever, or at least until we stop it by killing the process which runs it (usually by pressing Ctrl-C
or 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 ~pyramid.config.Configurator
.
For more information about view configuration
, see view_config_chapter
.