1. PYRAMID INTRODUCTION
Documentation Pyramid’s minimalism means that it is easier for us to maintain complete and up-to-date documentation. It is our goal that no aspect of Pyramid is undocumented.
Speed Pyramid is designed to provide noticeably fast execution for common tasks such as templating and simple response generation. Although “hardware is cheap”, the limits of this approach become painfully evident when one finds him or herself responsible for managing a great many machines.
Reliability Pyramid is developed conservatively and tested exhaustively. Where Pyramid source code is concerned, our motto is: “If it ain’t tested, it’s broke”.
Openness As with Python, the Pyramid software is distributed under a permissive open source license.
1.1 What Makes Pyramid Unique
Understandably, people don’t usually want to hear about squishy engineering principles, they want to hear about concrete stuff that solves their problems. With that in mind, what would make someone want to use Pyramid instead of one of the many other web frameworks available today? What makes Pyramid unique?
This is a hard question to answer, because there are lots of excellent choices, and it’s actually quite hard to make a wrong choice, particularly in the Python web framework market. But one reasonable answer is this: you can write very small applications in Pyramid without needing to know a lot. “What?”, you say, “that can’t possibly be a unique feature, lots of other web frameworks let you do that!” Well, you’re right. But unlike many other systems, you can also write very large applications in Pyramid if you learn a little more about it. Pyramid will allow you to become productive quickly, and will grow with you; it won’t hold you back when your application is small and it won’t get in your way when your application becomes large. “Well that’s fine,” you say, “lots of other frameworks let me write large apps too.” Absolutely. But other Python web frameworks don’t seamlessly let you do both. They seem to fall into two nonoverlapping categories: frameworks for “small apps” and frameworks for “big apps”. The “small app” frameworks typically sacrifice “big app” features, and vice versa.
We don’t think it’s a universally reasonable suggestion to write “small apps” in a “small framework” and “big apps” in a “big framework”. You can’t really know to what size every application will eventually grow. We don’t really want to have to rewrite a previously small application in another framework when it gets “too big”. We believe the current binary distinction between frameworks for small and large applications is just false; a well-designed framework should be able to be good at both. Pyramid strives to be that kind of framework.
To this end, Pyramid provides a set of features, that, combined, are unique amongst Python web frameworks. Lots of other frameworks contain some combination of these features; Pyramid of course actually stole many of them from those other frameworks. But Pyramid is the only one that has all of them in one place, documented appropriately, and useful a la carte without necessarily paying for the entire banquet. These are detailed below.
4
1.1. WHAT MAKES PYRAMID UNIQUE
1.1.1 Single-file applications
You can write a Pyramid application that lives entirely in one Python file, not unlike existing Python microframeworks. This is beneficial for one-off prototyping, bug reproduction, and very small applications. These applications are easy to understand because all the information about the application lives in a single place, and you can deploy them without needing to understand much about Python distributions and packaging. Pyramid isn’t really marketed as a microframework, but it allows you to do almost everything that frameworks that are marketed as micro offer in very similar ways.
from wsgiref.simple_server import make_server from pyramid.config import Configurator
from pyramid.response import Response
def hello_world(request):
return Response(’Hello %(name)s!’ % request.matchdict)
if __name__ == ’__main__’: config = Configurator()
config.add_route(’hello’, ’/hello/{name}’) config.add_view(hello_world, route_name=’hello’) app = config.make_wsgi_app()
server = make_server(’0.0.0.0’, 8080, app) server.serve_forever()
See also Creating Your First Pyramid Application.
1.1.2 Decorator-based configuration
If you like the idea of framework configuration statements living next to the code it configures, so you don’t have to constantly switch between files to refer to framework configuration when adding new code, you can use Pyramid decorators to localize the configuration. For example:
from pyramid.view import view_config from pyramid.response import Response
@view_config(route_name=’fred’) def fred_view(request):
return Response(’fred’)
However, unlike some other systems, using decorators for Pyramid configuration does not make your application difficult to extend, test or reuse. The view_config decorator, for example, does not actually
5
1. PYRAMID INTRODUCTION
change the input or output of the function it decorates, so testing it is a “WYSIWYG” operation; you don’t need to understand the framework to test your own code, you just behave as if the decorator is not there. You can also instruct Pyramid to ignore some decorators, or use completely imperative configuration instead of decorators to add views. Pyramid decorators are inert instead of eager: you detect and activate them with a scan.
Example: Adding View Configuration Using the @view_config Decorator.
1.1.3 URL generation
Pyramid is capable of generating URLs for resources, routes, and static assets. Its URL generation APIs are easy to use and flexible. If you use Pyramid’s various APIs for generating URLs, you can change your configuration around arbitrarily without fear of breaking a link on one of your web pages.
Example: Generating Route URLs.
1.1.4 Static file serving
Pyramid is perfectly willing to serve static files itself. It won’t make you use some external web server to do that. You can even serve more than one set of static files in a single Pyramid web application (e.g. /static and /static2). You can also, optionally, place your files on an external web server and ask Pyramid to help you generate URLs to those files, so you can use Pyramid’s internal fileserving while doing development, and a faster static file server in production without changing any code.
Example: Serving Static Assets.
1.1.5 Debug Toolbar
Pyramid’s debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and allows you access to framework data such as the routes configured, the last renderings performed, the current set of packages installed, SQLAlchemy queries run, logging data, and various other facts. When an exception occurs, you can use its interactive debugger to poke around right in your browser to try to determine the cause of the exception. It’s handy.
Example: The Debug Toolbar.
6
1.1. WHAT MAKES PYRAMID UNIQUE
1.1.6 Debugging settings
Pyramid has debugging settings that allow you to print Pyramid runtime information to the console when things aren’t behaving as you’re expecting. For example, you can turn on “debug_notfound”, which prints an informative message to the console every time a URL does not match any view. You can turn on “debug_authorization”, which lets you know why a view execution was allowed or denied by printing a message to the console. These features are useful for those WTF moments.
There are also a number of commands that you can invoke within a Pyramid environment that allow you to introspect the configuration of your system: proutes shows all configured routes for an application in the order they’ll be evaluated for matching; pviews shows all configured views for any given URL. These are also WTF-crushers in some circumstances.
Examples: Debugging View Authorization Failures and Command-Line Pyramid.
1.1.7 Add-ons
Pyramid has an extensive set of add-ons held to the same quality standards as the Pyramid core itself. Addons are packages which provide functionality that the Pyramid core doesn’t. Add-on packages already exist which let you easily send email, let you use the Jinja2 templating system, let you use XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc.
Examples: http://docs.pylonsproject.org/docs/pyramid.html#pyramid-add-on-documentation
1.1.8 Class-based and function-based views
Pyramid has a structured, unified concept of a view callable. View callables can be functions, methods of classes, or even instances. When you add a new view callable, you can choose to make it a function or a method of a class; in either case, Pyramid treats it largely the same way. You can change your mind later, and move code between methods of classes and functions. A collection of similar view callables can be attached to a single class as methods, if that floats your boat, and they can share initialization code as necessary. All kinds of views are easy to understand and use and operate similarly. There is no phony distinction between them; they can be used for the same purposes.
Here’s a view callable defined as a function:
7
1. PYRAMID INTRODUCTION
1
2
3
4
5
6
from pyramid.response import Response from pyramid.view import view_config
@view_config(route_name=’aview’) def aview(request):
return Response(’one’)
Here’s a few views defined as methods of a class instead:
1 |
from pyramid.response import Response |
2 |
from pyramid.view import view_config |
3 |
|
4 |
class AView(object): |
5 |
def __init__(self, request): |
6self.request = request
7
8 @view_config(route_name=’view_one’)
9def view_one(self):
10 return Response(’one’)
11
12@view_config(route_name=’view_two’)
13def view_two(self):
14return Response(’two’)
See also @view_config Placement.
1.1.9 Asset specifications
Asset specifications are strings that contain both a Python package name and a file or directory name, e.g. MyPackage:static/index.html. Use of these specifications is omnipresent in Pyramid. An asset specification can refer to a template, a translation directory, or any other package-bound static resource. This makes a system built on Pyramid extensible, because you don’t have to rely on globals (“the static directory”) or lookup schemes (“the ordered set of template directories”) to address your files. You can move files around as necessary, and include other packages that may not share your system’s templates or static files without encountering conflicts.
Because asset specifications are used heavily in Pyramid, we’ve also provided a way to allow users to override assets. Say you love a system that someone else has created with Pyramid but you just need to change “that one template” to make it all better. No need to fork the application. Just override the asset specification for that template with your own inside a wrapper, and you’re good to go.
Examples: Understanding Asset Specifications and Overriding Assets.
8