Quick Tour of Pyramid¶

Pyramid lets you start small and finish big. This Quick Tour of Pyramid is for those who want to evaluate Pyramid, whether you are new to Python web frameworks, or a pro in a hurry. For more detailed treatment of each topic, give the Quick Tutorial for Pyramid a try.

If you would prefer to cut and paste the example code in this tour you may browse the source code located in the Pyramid repository in the directory "docs/quick_tour" <https://github.com/Pylons/pyramid/>. If you have downloaded the source code, you will find the tour in the same location.

Installation¶

Once you have a standard Python environment setup, getting started with Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. For this Quick Tour, it means Python, venv, pip, and Setuptools.

To save a little bit of typing and to be certain that we use the modules, scripts, and packages installed in our virtual environment, we'll set an environment variable, too.

As an example, for Python 3 on Linux:

# set an environment variable to where you want your virtual environment
$ export VENV=~/env
# create the virtual environment
$ python3 -m venv $VENV
# install pyramid
$ $VENV/bin/pip install pyramid
# or for a specific released version
$ $VENV/bin/pip install "pyramid==2.0.1"

For Windows:

# set an environment variable to where you want your virtual environment
c:\> set VENV=c:\env
# create the virtual environment
c:\> python -m venv %VENV%
# install pyramid
c:\> %VENV%\Scripts\pip install pyramid
# or for a specific released version
c:\> %VENV%\Scripts\pip install "pyramid==2.0.1"

As of version 2.0, Pyramid runs on Python 3 only. For simplicity, the remaining examples will show only Unix commands.

Hello World¶

Microframeworks have shown that learning starts best from a very small first step. Here's a tiny application in Pyramid:

from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response


def hello_world(request):
    return Response('Hello World!')


if __name__ == '__main__':
    with Configurator() as config:
        config.add_route('hello', '/')
        config.add_view(hello_world, route_name='hello')
        app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 6543, app)
    server.serve_forever()

This simple example is easy to run. Save this as app.py and run it:

$ $VENV/bin/python ./app.py

Next open http://localhost:6543/ in a browser, and you will see the Hello World! message.

New to Python web programming? If so, some lines in the module merit explanation:

Lines 6-7. Implement the view code that generates the response.
Line 10. if __name__ == '__main__': is Python's way of saying "Start here when running from the command line".
Lines 11-13. Use Pyramid's configurator in a context manager to connect view code to a particular URL route.
Lines 14-16. Publish a WSGI app using an HTTP server.

As shown in this example, the configurator plays a central role in Pyramid development. Building an application from loosely-coupled parts via Application Configuration is a central idea in Pyramid, one that we will revisit regularly in this Quick Tour.

See also

See also: Quick Tutorial Hello World, Creating Your First Pyramid Application, and Todo List Application in One File.

Handling web requests and responses¶

Developing for the web means processing web requests. As this is a critical part of a web application, web developers need a robust, mature set of software for web requests.

Pyramid has always fit nicely into the existing world of Python web development (virtual environments, packaging, cookiecutters, one of the first to embrace Python 3, etc.). Pyramid turned to the well-regarded WebOb Python library for request and response handling. In our example above, Pyramid hands hello_world a request that is based on WebOb.

Let's see some features of requests and responses in action:

def hello_world(request):
    # Some parameters from a request such as /?name=lisa
    url = request.url
    name = request.params.get('name', 'No Name Provided')

    body = 'URL %s with name: %s' % (url, name)
    return Response(
        content_type="text/plain",
        body=body
    )

In this Pyramid view, we get the URL being visited from request.url. Also if you visited http://localhost:6543/?name=alice in a browser, the name is included in the body of the response:

URL http://localhost:6543/?name=alice with name: alice

Finally we set the response's content type, and return the Response.

Views¶

For the examples above, the hello_world function is a "view". In Pyramid views are the primary way to accept web requests and return responses.

So far our examples place everything in one file:

the view function
its registration with the configurator
the route to map it to an URL
the WSGI application launcher

Let's move the views out to their own views.py module and change the app.py to scan that module, looking for decorators that set up the views.

First our revised app.py:

from wsgiref.simple_server import make_server
from pyramid.config import Configurator

if __name__ == '__main__':
    with Configurator() as config:
        config.add_route('home', '/')
        config.add_route('hello', '/howdy')
        config.add_route('redirect', '/goto')
        config.add_route('exception', '/problem')
        config.scan('views')
        app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 6543, app)
    server.serve_forever()

We added some more routes, but we also removed the view code. Our views and their registrations (via decorators) are now in a module views.py, which is scanned via config.scan('views').

We now have a views.py module that is focused on handling requests and responses:

from html import escape

from pyramid.httpexceptions import HTTPFound
from pyramid.response import Response
from pyramid.view import view_config


# First view, available at http://localhost:6543/
@view_config(route_name='home')
def home_view(request):
    return Response('<p>Visit <a href="/howdy?name=lisa">hello</a></p>')


# /howdy?name=alice which links to the next view
@view_config(route_name='hello')
def hello_view(request):
    name = request.params.get('name', 'No Name')
    body = '<p>Hi %s, this <a href="/goto">redirects</a></p>'
    # Python html.escape to prevent Cross-Site Scripting (XSS) [CWE 79]
    return Response(body % escape(name))


# /goto which issues HTTP redirect to the last view
@view_config(route_name='redirect')
def redirect_view(request):
    return HTTPFound(location="/problem")


# /problem which causes a site error
@view_config(route_name='exception')
def exception_view(request):
    raise Exception()

We have four views, each leading to the other. If you start at http://localhost:6543/, you get a response with a link to the next view. The hello_view (available at the URL /howdy) has a link to the redirect_view, which issues a redirect to the final view.

Earlier we saw config.add_view as one way to configure a view. This section introduces @view_config. Pyramid's configuration supports imperative configuration, such as the config.add_view in the previous example. You can also use declarative configuration in which a Python decorator is placed on the line above the view. Both approaches result in the same final configuration, thus usually it is simply a matter of taste.

Routing¶

Writing web applications usually means sophisticated URL design. We just saw some Pyramid machinery for requests and views. Let's look at features that help with routing.

Above we saw the basics of routing URLs to views in Pyramid:

Your project's "setup" code registers a route name to be used when matching part of the URL.
Elsewhere a view is configured to be called for that route name.

Note

Why do this twice? Other Python web frameworks let you create a route and associate it with a view in one step. As illustrated in Routes need relative ordering, multiple routes might match the same URL pattern. Rather than provide ways to help guess, Pyramid lets you be explicit in ordering. Pyramid also gives facilities to avoid the problem.

What if we want part of the URL to be available as data in my view? We can use this route declaration, for example:

        config.add_route('hello', '/howdy/{first}/{last}')

With this, URLs such as /howdy/amy/smith will assign amy to first and smith to last. We can then use this data in our view:

@view_config(route_name='hello')
def hello_world(request):
    body = '<h1>Hi %(first)s %(last)s!</h1>' % request.matchdict
    return Response(body)

request.matchdict contains values from the URL that match the "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view.

Templating¶

Ouch. We have been making our own Response and filling the response body with HTML. You usually won't embed an HTML string directly in Python, but instead you will use a templating language.

Pyramid doesn't mandate a particular database system, form library, and so on. It encourages replaceability. This applies equally to templating, which is fortunate: developers have strong views about template languages. That said, the Pylons Project officially supports bindings for Chameleon, Jinja2, and Mako. In this step let's use Chameleon.

Let's add pyramid_chameleon, a Pyramid add-on which enables Chameleon as a renderer in our Pyramid application:

$VENV/bin/pip install pyramid_chameleon

With the package installed, we can include the template bindings into our configuration in app.py:

        config.add_route('hello', '/howdy/{name}')
        config.include('pyramid_chameleon')
        config.scan('views')

Now lets change our views.py file:

from pyramid.view import view_config


@view_config(route_name='hello', renderer='hello_world.pt')
def hello_world(request):
    return dict(name=request.matchdict['name'])

Ahh, that looks better. We have a view that is focused on Python code. Our @view_config decorator specifies a renderer that points to our template file. Our view then simply returns data which is then supplied to our template hello_world.pt:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Quick Glance</title>
</head>
<body>
<h1>Hello ${name}</h1>
</body>
</html>

Since our view returned dict(name=request.matchdict['name']), we can use name as a variable in our template via ${name}.

Templating with Jinja2¶

We just said Pyramid doesn't prefer one templating language over another. Time to prove it. Jinja2 is a popular templating system, modeled after Django's templates. Let's add pyramid_jinja2, a Pyramid add-on which enables Jinja2 as a renderer in our Pyramid applications:

$VENV/bin/pip install pyramid_jinja2

With the package installed, we can include the template bindings into our configuration:

        config.add_route('hello', '/howdy/{name}')
        config.include('pyramid_jinja2')
        config.scan('views')

The only change in our view is to point the renderer at the .jinja2 file:

@view_config(route_name='hello', renderer='hello_world.jinja2')
def hello_world(request):
    return dict(name=request.matchdict['name'])

Our Jinja2 template is very similar to our previous template:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Hello World</title>
</head>
<body>
<h1>Hello {{ name }}!</h1>
</body>
</html>

Pyramid's templating add-ons register a new kind of renderer into your application. The renderer registration maps to different kinds of filename extensions. In this case, changing the extension from .pt to .jinja2 passed the view response through the pyramid_jinja2 renderer.

See also

See also: Quick Tutorial Jinja2, Jinja2 homepage, and pyramid_jinja2 Overview.

Static assets¶

Of course the Web is more than just markup. You need static assets: CSS, JS, and images. Let's point our web app at a directory from which Pyramid will serve some static assets. First let's make another call to the configurator in app.py:

        config.add_route('hello', '/howdy/{name}')
        config.add_static_view(name='static', path='static')
        config.include('pyramid_jinja2')

This tells our WSGI application to map requests under http://localhost:6543/static/ to files and directories inside a static directory alongside our Python module.

Next make a directory named static, and place app.css inside:

body {
    margin: 2em;
    font-family: sans-serif;
}

All we need to do now is point to it in the <head> of our Jinja2 template, hello_world.jinja2:

    <title>Hello World</title>
    <link rel="stylesheet" href="/static/app.css"/>
</head>

This link presumes that our CSS is at a URL starting with /static/. What if the site is later moved under /somesite/static/? Or perhaps a web developer changes the arrangement on disk? Pyramid provides a helper to allow flexibility on URL generation:

    <title>Hello World</title>
    <link rel="stylesheet" href="{{ request.static_url('__main__:static/app.css') }}"/>
</head>

By using request.static_url to generate the full URL to the static assets, you ensure that you stay in sync with the configuration and gain refactoring flexibility later.

Returning JSON¶

Modern web apps are more than rendered HTML. Dynamic pages now use JavaScript to update the UI in the browser by requesting server data as JSON. Pyramid supports this with a JSON renderer:

@view_config(route_name='hello_json', renderer='json')
def hello_json(request):
    return [1, 2, 3]

This wires up a view that returns some data through the JSON renderer, which calls Python's JSON support to serialize the data into JSON, and sets the appropriate HTTP headers.

We also need to add a route to app.py so that our app will know how to respond to a request for hello.json.

        config.add_route('hello', '/howdy/{name}')
        config.add_route('hello_json', 'hello.json')
        config.add_static_view(name='static', path='static')

View classes¶

So far our views have been simple, free-standing functions. Many times your views are related. They may have different ways to look at or work on the same data, or they may be a REST API that handles multiple operations. Grouping these together as a view class makes sense and achieves the following goals.

Group views
Centralize some repetitive defaults
Share some state and helpers

The following shows a "Hello World" example with three operations: view a form, save a change, or press the delete button in our views.py:

# One route, at /howdy/amy, so don't repeat on each @view_config
@view_defaults(route_name='hello')
class HelloWorldViews:
    def __init__(self, request):
        self.request = request
        # Our templates can now say {{ view.name }}
        self.name = request.matchdict['name']

    # Retrieving /howdy/amy the first time
    @view_config(renderer='hello.jinja2')
    def hello_view(self):
        return dict()

    # Posting to /howdy/amy via the "Edit" submit button
    @view_config(request_param='form.edit', renderer='edit.jinja2')
    def edit_view(self):
        print('Edited')
        return dict()

    # Posting to /howdy/amy via the "Delete" submit button
    @view_config(request_param='form.delete', renderer='delete.jinja2')
    def delete_view(self):
        print('Deleted')
        return dict()

As you can see, the three views are logically grouped together. Specifically:

The first view is returned when you go to /howdy/amy. This URL is mapped to the hello route that we centrally set using the optional @view_defaults.
The second view is returned when the form data contains a field with form.edit, such as clicking on <input type="submit" name="form.edit" value="Save">. This rule is specified in the @view_config for that view.
The third view is returned when clicking on a button such as <input type="submit" name="form.delete" value="Delete">.

Only one route is needed, stated in one place atop the view class. Also, the assignment of name is done in the __init__ function. Our templates can then use {{ view.name }}.

Pyramid view classes, combined with built-in and custom predicates, have much more to offer:

All the same view configuration parameters as function views
One route leading to multiple views, based on information in the request or data such as request_param, request_method, accept, header, xhr, containment, and custom predicates.

See also

See also: View Classes and More View Classes in the Quick Tutorial, Defining a View Callable as a Class, and View and Route Predicates.

Quick project startup with cookiecutters¶

So far we have done all of our Quick Tour as a single Python file. No Python packages, no structure. Most Pyramid projects, though, aren't developed this way.

To ease the process of getting started, the Pylons Project provides a cookiecutter that generates a sample Pyramid project from project templates. This cookiecutter will install Pyramid and its dependencies as well.

First you'll need to install cookiecutter.

$VENV/bin/pip install cookiecutter

Let's use the cookiecutter pyramid-cookiecutter-starter to create a starter Pyramid project in the current directory, entering values at the prompts as shown below for the following command.

$VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 2.0-branch

If prompted for the first item, accept the default yes by hitting return.

You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before.
Is it okay to delete and re-clone it? [yes]: yes
project_name [Pyramid Scaffold]: hello_world
repo_name [hello_world]: hello_world
Select template_language:
1 - jinja2
2 - chameleon
3 - mako
Choose from 1, 2, 3 [1]: 1
Select backend:
1 - none
2 - sqlalchemy
3 - zodb
Choose from 1, 2, 3 [1]: 1

We then run through the following commands.

# Change directory into your newly created project.
cd hello_world
# Create a new virtual environment...
python3 -m venv env
# ...where we upgrade packaging tools...
env/bin/pip install --upgrade pip setuptools
# ...and into which we install our project and its testing requirements.
env/bin/pip install -e ".[testing]"
# Reset our environment variable for a new virtual environment.
export VENV=~/hello_world/env

We are moving in the direction of a full-featured Pyramid project, with a proper setup for Python standards (packaging) and Pyramid configuration. This includes a new way of running your application:

$VENV/bin/pserve development.ini

Let's look at pserve and configuration in more depth.

Application running with `pserve`¶

Prior to the cookiecutter, our project mixed a number of operational details into our code. Why should my main code care which HTTP server I want and what port number to run on?

pserve is Pyramid's application runner, separating operational details from your code. When you install Pyramid, a small command program called pserve is written to your bin directory. This program is an executable Python module. It's very small, getting most of its brains via import.

You can run pserve with --help to see some of its options. Doing so reveals that you can ask pserve to watch your development files and reload the server when they change:

$VENV/bin/pserve development.ini --reload

The pserve command has a number of other options and operations. Most of the work, though, comes from your project's wiring, as expressed in the configuration file you supply to pserve. Let's take a look at this configuration file.

See also

Configuration with `.ini` files¶

Earlier in Quick Tour we first met Pyramid's configuration system. At that point we did all configuration in Python code. For example, the port number chosen for our HTTP server was right there in Python code. Our cookiecutter has moved this decision and more into the development.ini file:

###
# app configuration
# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
###

[app:main]
use = egg:hello_world

pyramid.reload_templates = true
pyramid.debug_authorization = false
pyramid.debug_notfound = false
pyramid.debug_routematch = false
pyramid.default_locale_name = en
pyramid.includes =
    pyramid_debugtoolbar

# By default, the toolbar only appears for clients from IP addresses
# '127.0.0.1' and '::1'.
# debugtoolbar.hosts = 127.0.0.1 ::1

###
# wsgi server configuration
###

[server:main]
use = egg:waitress#main
listen = localhost:6543

###
# logging configuration
# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
###

[loggers]
keys = root, hello_world

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = INFO
handlers = console

[logger_hello_world]
level = DEBUG
handlers =
qualname = hello_world

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s

Let's take a quick high-level look. First the .ini file is divided into sections:

[app:main] configures our WSGI app
[server:main] holds our WSGI server settings
Various sections afterwards configure our Python logging system

We have a few decisions made for us in this configuration:

WSGI app: What package has our WSGI application in it? use = egg:hello_world in the app section tells the configuration what application to load.
Easier development by automatic template reloading: In development mode, you shouldn't have to restart the server when editing a Jinja2 template. pyramid.reload_templates = true sets this policy, which might be different in production.
Choice of web server: use = egg:waitress#main tells pserve to use the waitress server.
Interfaces: listen = localhost:6543 tells waitress to listen on all interfaces on port 6543 for both IPv4 and IPv6.

Additionally the development.ini generated by this cookiecutter wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well as traceback information.

Easier development with `debugtoolbar`¶

As we introduce the basics, we also want to show how to be productive in development and debugging. For example, we just discussed template reloading and earlier we showed --reload for application reloading.

pyramid_debugtoolbar is a popular Pyramid add-on which makes several tools available in your browser. Adding it to your project illustrates several points about configuration.

Our cookiecutter pyramid-cookiecutter-starter already configured our package to include the add-on pyramid_debugtoolbar in its setup.py:

requires = [
    'plaster_pastedeploy',
    'pyramid',
    'pyramid_jinja2',
    'pyramid_debugtoolbar',
    'waitress',
]

It was installed when you previously ran:

$VENV/bin/pip install -e ".[testing]"

The pyramid_debugtoolbar package is a Pyramid add-on, which means we need to include its configuration into our web application. The cookiecutter already took care of this for us in its development.ini using the pyramid.includes facility:

pyramid.includes =
    pyramid_debugtoolbar

You'll now see a Pyramid logo on the right side of your browser window, which when clicked opens a new window that provides introspective access to debugging information. Even better, if your web application generates an error, you will see a nice traceback on the screen. When you want to disable this toolbar, there's no need to change code: you can remove it from pyramid.includes in the relevant .ini configuration file.

See also

See also: Quick Tutorial pyramid_debugtoolbar and pyramid_debugtoolbar

Unit and functional tests and `pytest`¶

Yikes! We got this far and we haven't yet discussed tests. This is particularly egregious, as Pyramid has had a deep commitment to full test coverage since before its release.

Our pyramid-cookiecutter-starter cookiecutter generated conftest.py, test_functional.py, and test_views.py modules inside the tests package with two unit tests and two functional tests in it. It also configured setup.py with test requirements: pytest as the test runner, WebTest for running view tests, and the pytest-cov tool which yells at us for code that isn't tested:

tests_require = [
    'WebTest',
    'pytest',
    'pytest-cov',
]

    extras_require={
        'testing': tests_require,
    },

We already installed the test requirements when we ran the command $VENV/bin/pip install -e ".[testing]". We can now run all our tests:

$VENV/bin/pytest --cov --cov-report=term-missing

This yields the following output.

=========================== test session starts ===========================
platform darwin -- Python 3.9.0, pytest-6.2.1, py-1.10.0, pluggy-0.13.1
rootdir: /<somepath>/hello_world, configfile: pytest.ini, testpaths: hello_world, tests
plugins: cov-2.10.1
collected 4 items

tests/test_functional.py ..                                          [ 50%]
tests/test_views.py ..                                               [100%]

---------- coverage: platform darwin, python 3.9.0-final-0 -----------
Name                            Stmts   Miss  Cover   Missing
-------------------------------------------------------------
hello_world/__init__.py             7      0   100%
hello_world/routes.py               3      0   100%
hello_world/views/__init__.py       0      0   100%
hello_world/views/default.py        4      0   100%
hello_world/views/notfound.py       5      0   100%
-------------------------------------------------------------
TOTAL                              19      0   100%

======================== 4 passed in 0.65 seconds =========================

Our tests passed, and its coverage is complete. What did our tests look like?

def test_root(testapp):
    res = testapp.get('/', status=200)
    assert b'Pyramid' in res.body

def test_notfound(testapp):
    res = testapp.get('/badurl', status=404)
    assert res.status_code == 404

from hello_world.views.default import my_view
from hello_world.views.notfound import notfound_view


def test_my_view(app_request):
    info = my_view(app_request)
    assert app_request.response.status_int == 200
    assert info['project'] == 'hello_world'

def test_notfound_view(app_request):
    info = notfound_view(app_request)
    assert app_request.response.status_int == 404
    assert info == {}

Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our view tests import the view, make a dummy request, and sees if the view returns what we expected. Our functional tests verify that the response body from a request to the web root contains what we expected and that the expected response code for making a request to /badurl results in 404.

Logging¶

It's important to know what is going on inside our web application. In development we might need to collect some output. In production we might need to detect situations when other people use the site. We need logging.

Fortunately Pyramid uses the normal Python approach to logging. The development.ini file for your project has a number of lines that configure the logging for you to some reasonable defaults. You then see messages sent by Pyramid (for example, when a new request comes in).

Maybe you would like to log messages in your code? In your Python module, import and set up the logging in your views/default.py:

import logging
log = logging.getLogger(__name__)

You can now, in your code, log messages:

def my_view(request):
    log.debug('Some Message')

This will log Some Message at a DEBUG log level to the application-configured logger in your development.ini. What controls that? These emphasized sections in the configuration file:

[loggers]
keys = root, hello_world

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = INFO
handlers = console

[logger_hello_world]
level = DEBUG
handlers =
qualname = hello_world

Our application, a package named hello_world, is set up as a logger and configured to log messages at a DEBUG or higher level. When you visit http://localhost:6543, your console will now show:

2016-12-25 03:03:57,059 DEBUG [hello_world.views:8][waitress] Some Message

See also

See also: Quick Tutorial Logging and Logging.

Sessions¶

When people use your web application, they frequently perform a task that requires semi-permanent data to be saved. For example, a shopping cart. This is called a session.

Pyramid has basic built-in support for sessions. Third party packages such as pyramid_redis_sessions provide richer session support. Or you can create your own custom sessioning engine. Let's take a look at the built-in sessioning support. In our __init__.py we first import the kind of sessioning we want:

from pyramid.config import Configurator
from pyramid.session import SignedCookieSessionFactory

Warning

As noted in the session docs, this example implementation is not intended for use in settings with security implications.

Now make a "factory" and pass it to the configurator's session_factory argument:

        config.include('.routes')
        my_session_factory = SignedCookieSessionFactory('itsaseekreet')
        config.set_session_factory(my_session_factory)
        config.scan()

Pyramid's request object now has a session attribute that we can use in our view code in views/default.py:

def my_view(request):
    log.debug('Some Message')
    session = request.session
    if 'counter' in session:
        session['counter'] += 1
    else:
        session['counter'] = 0
    return {'project': 'hello_world'}

We need to update our Jinja2 template templates/mytemplate.jinja2 to show counter increment in the session:

<div class="content">
  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Starter project</span></h1>
  <p class="lead">Welcome to <span class="font-normal">{{project}}</span>, a&nbsp;Pyramid application generated&nbsp;by<br><span class="font-normal">Cookiecutter</span>.</p>
  <p>Counter: {{ request.session.counter }}</p>
</div>

Databases¶

Web applications mean data. Data means databases. Frequently SQL databases. SQL databases frequently mean an "ORM" (object-relational mapper.) In Python, ORM usually leads to the mega-quality SQLAlchemy, a Python package that greatly eases working with databases.

Pyramid and SQLAlchemy are great friends. That friendship includes a cookiecutter!

cd ~
env/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 2.0-branch

If prompted for the first item, accept the default yes by hitting return.

You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before.
Is it okay to delete and re-clone it? [yes]: yes
project_name [Pyramid Scaffold]: sqla_demo
repo_name [sqla_demo]: sqla_demo
Select template_language:
1 - jinja2
2 - chameleon
3 - mako
Choose from 1, 2, 3 [1]: 1
Select backend:
1 - none
2 - sqlalchemy
3 - zodb
Choose from 1, 2, 3 [1]: 2

We then run through the following commands as before.

# Change directory into your newly created project.
cd sqla_demo
# Create a new virtual environment...
python3 -m venv env
# ...where we upgrade packaging tools...
env/bin/pip install --upgrade pip setuptools
# ...and into which we install our project and its testing requirements.
env/bin/pip install -e ".[testing]"
# Reset our environment variable for a new virtual environment.
export VENV=~/sqla_demo/env

We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a method to generate a database migration from existing models and upgrade the database schema using Alembic. Let's generate the first revision.

$VENV/bin/alembic -c development.ini revision --autogenerate -m "init"

Now let's upgrade the database schema.

$VENV/bin/alembic -c development.ini upgrade head

The sample project also provides a console script to load data into the SQLite database. Let's run it, then start the application:

$VENV/bin/initialize_sqla_demo_db development.ini
$VENV/bin/pserve development.ini

The ORM eases the mapping of database structures into a programming language. SQLAlchemy uses "models" for this mapping. The cookiecutter generated a sample model:

class MyModel(Base):
    __tablename__ = 'models'
    id = Column(Integer, primary_key=True)
    name = Column(Text)
    value = Column(Integer)

View code, which mediates the logic between web requests and the rest of the system, can then easily get at the data thanks to SQLAlchemy:

@view_config(route_name='home', renderer='sqla_demo:templates/mytemplate.jinja2')
def my_view(request):
    try:
        query = request.dbsession.query(models.MyModel)
        one = query.filter(models.MyModel.name == 'one').one()
    except SQLAlchemyError:
        return Response(db_err_msg, content_type='text/plain', status=500)
    return {'one': one, 'project': 'sqla_demo'}

See also

See also: Quick Tutorial Databases, SQLAlchemy, Making Your Script into a Console Script, SQLAlchemy + URL dispatch wiki tutorial, and Application Transactions with pyramid_tm.

Forms¶

Developers have lots of opinions about web forms, thus there are many form libraries for Python. Pyramid doesn't directly bundle a form library, but Deform is a popular choice for forms, along with its related Colander schema system.

As an example, imagine we want a form that edits a wiki page. The form should have two fields on it, one of them a required title and the other a rich text editor for the body. With Deform we can express this as a Colander schema:

class WikiPage(colander.MappingSchema):
    title = colander.SchemaNode(colander.String())
    body = colander.SchemaNode(
        colander.String(),
        widget=deform.widget.RichTextWidget()
    )

With this in place, we can render the HTML for a form, perhaps with form data from an existing page:

form = self.wiki_form.render()

We'd like to handle form submission, validation, and saving:

# Get the form data that was posted
controls = self.request.POST.items()
try:
    # Validate and either raise a validation error
    # or return deserialized data from widgets
    appstruct = wiki_form.validate(controls)
except deform.ValidationFailure as e:
    # Bail out and render form with errors
    return dict(title=title, page=page, form=e.render())

# Change the content and redirect to the view
page['title'] = appstruct['title']
page['body'] = appstruct['body']

Deform and Colander provide a very flexible combination for forms, widgets, schemas, and validation. Recent versions of Deform also include a retail mode for gaining Deform features on custom forms.

Deform uses attractive CSS from Twitter Bootstrap and more powerful select, checkbox, and date and time widgets.

See also

See also: Quick Tutorial Forms, Deform, and Colander.

Conclusion¶

This Quick Tour covered a little about a lot. We introduced a long list of concepts in Pyramid, many of which are expanded on more fully in the Pyramid developer docs.

Quick Tour of Pyramid¶

Installation¶

Hello World¶

Handling web requests and responses¶

Views¶

Routing¶

Templating¶

Templating with Jinja2¶

Static assets¶

Returning JSON¶

View classes¶

Quick project startup with cookiecutters¶

Application running with `pserve`¶

Configuration with `.ini` files¶

Easier development with `debugtoolbar`¶

Unit and functional tests and `pytest`¶

Logging¶

Sessions¶

Databases¶

Forms¶

Conclusion¶

Table of Contents

Previous topic

Next topic

This Page

Quick Tour of Pyramid¶

Installation¶

Hello World¶

Handling web requests and responses¶

Views¶

Routing¶

Templating¶

Templating with Jinja2¶

Static assets¶

Returning JSON¶

View classes¶

Quick project startup with cookiecutters¶

Application running with pserve¶

Configuration with .ini files¶

Easier development with debugtoolbar¶

Unit and functional tests and pytest¶

Logging¶

Sessions¶

Databases¶

Forms¶

Conclusion¶

Application running with `pserve`¶

Configuration with `.ini` files¶

Easier development with `debugtoolbar`¶

Unit and functional tests and `pytest`¶